diff --git a/.gitmodules b/.gitmodules index f2511fb..966124e 100644 --- a/.gitmodules +++ b/.gitmodules @@ -7,9 +7,9 @@ [submodule "ui/wxapp_escort"] path = ui/wxapp_escort url = http://gitea.huashengtec.com/xJourney/wxapp_escort.git -[submodule "ui/wxapp_escort_admin"] - path = ui/wxapp_escort_admin - url = http://gitea.huashengtec.com/xJourney/wxapp_escort_admin.git +[submodule "ui/wxapp_companion"] + path = ui/wxapp_companion + url = http://gitea.huashengtec.com/xJourney/wxapp_companion.git [submodule "ui/web_tcm"] path = ui/web_tcm url = http://gitea.huashengtec.com/xJourney/web_tcm.git diff --git a/doc/architecture-overview.html b/doc/architecture-overview.html new file mode 100644 index 0000000..4282b37 --- /dev/null +++ b/doc/architecture-overview.html @@ -0,0 +1,1457 @@ + + + + + +ws_health 架构概要设计 + + + +
+ +
+
Architecture Overview
+

ws_health 架构概要设计

+

+ 面向陪诊业务的后端服务、两端小程序、Web 管理后台与微信支付链路的整体设计摘要。 + 本文只保留跨模块的核心方案与不变量,实施细节与未完成事项分别以专项文档和 + plan.md 为准。 +

+
+ 版本 v1.0 + 日期 2026-11-10 + 代码基准 api/health · api/user · ui/wxapp_escort · ui/wxapp_companion · ui/web_escort_admin + 来源 6 份专项设计文档 +
+
+ + + +
+ + +
+

01概览与关键决策

+ +

+ ws_health 是一个按业务域拆分目录、独立部署的轻量微服务系统:api/health + 承载陪诊业务(订单、健康档案、医院、资源、AI 聊天),api/user + 承载平台账号、多应用身份与 token 鉴权;前端包含 C 端小程序、陪诊师小程序与 Vue Web 管理后台。 +

+ +

+ 设计的核心不是“服务数量”,而是几条贯穿全系统的边界:账号与授权分离、 + 订单状态与支付状态分离、业务订单与支付流水分离、 + 小程序端与管理后台的应用身份分离。 +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
关键决策选择理由 / 约束
服务拆分方式按目录拆分 + nginx 路径路由,各自独立部署中等流量下足够;避免过早引入注册中心、服务网格等基础设施
数据库共用 MongoDB 实例,按服务分库边界清晰、索引不冲突;量级上升后可平滑迁移到独立实例
鉴权token 单点在 user 服务,health 实时校验 + 进程内缓存改造成本低;代价是登出/锁定在 health 侧最多延迟 5 分钟
多应用身份user / user_app / user_identity 三表登录身份、应用授权、平台账号生命周期不同,混在一个字段无法建唯一约束
入驻审批一致性条件更新抢占 + 幂等补偿,不使用 Mongo 事务部署形态不保证副本集;唯一索引与条件更新足以覆盖并发
订单归属管理员代客下单采用档案锚定,无归属可留空遵守 user 服务“不接受按 userId 明文查询”的安全约束,不新开查人接口
支付数据流水表是财务事实源,订单 payment 只是汇总快照一单多流水、退款可追溯、对账口径统一
Web 后台身份独立应用 web-escort-admin,不复用小程序 appId两端可分别授权、分别停用;管理员判定只认 user_app 成员关系
小程序角色化页内切换数据源与入口,不做动态 tabBar微信原生 tabBar 不支持按角色动态隐藏,custom tabBar 成本高
+
+ +
+ 阅读口径:文中“已实现”指代码与接口已落地;“明确不做”是已评审的边界,不代表遗漏; + 仍待开发的事项统一收敛到 plan.md。 +
+
+ + +
+

02系统架构

+ +
+
+
客户端
+
+
C 端小程序wxapp_escort下单 / 支付 / 预约记录
+
陪诊师小程序wxapp_companion管理员 + 陪诊员共用
+
Web 管理后台web_escort_adminVue 3 + Vite + TS
+
微信客户端wx.login / 扫码 / 支付
+
+
+ +
↓ HTTPS / WSS
+ +
+
接入层
+
+
nginx/health → 9004 · /user → 9010 · /ws → 9005同域分流、TLS 终止
+
+
+ +
↓ 反向代理
+ +
+
服务层
+
+
health 服务HTTP :9004订单 / 档案 / 医院 / 支付 / 资源
+
health 服务WS :9005AI 聊天,Agent 按 userId 缓存
+
user 服务HTTP :9010注册登录 / token / 多应用授权
+
+
+ +
↓ Mongoose
+ +
+
数据层
+
+
health 业务库escort_record / payment_record / refund_record …
+
eiot_user 库user / user_app / user_identity
+
+
+ +
+ +
+
外部依赖
+
+
微信登录jscode2session
+
微信支付APIv3 JSAPI
+
DeepSeek / TavilyAI Agent
+
百度地图位置能力
+
+
+
+ +

请求与鉴权链路

+ +
+
  • + 客户端携带 token + 请求头 token: xxx 或 Authorization: Bearer xxx,health 服务两者兼容。 +
  • +
  • + health 侧 requireAuth + 先查进程内 token→user 缓存(TTL 5 分钟,LRU 上限 2000,无效 token 负缓存 60 秒);未命中再调 user 服务 /user/userInfo。 +
  • +
  • + 身份与角色判定 + 管理员看 apps 中的成员关系与 roles;陪诊员看 Employee 档案(role=attendant 且 status=active);订单级权限再由 canAccess 逐单拦截。 +
  • +
  • + 业务处理 + 响应 HTTP 状态码恒为 200,业务码在 body.code,提示文案在 body.msg;前端按 body.code 判断会话失效与错误。 +
  • +
    + +
    + 边界:health 服务不直接建模 user 数据,唯一关联字段是 employee.userId(跨服务软引用); + 跨服务不做分布式事务,弱一致场景用幂等 + 补偿。 +
    +
    + + +
    +

    03身份与权限

    + +

    + 用户模型把过去塞在 user.app 一个 Mixed 字段里的三件事拆开: + 平台账号、应用成员与授权、外部登录身份。 +

    + +
    +
    +
    核心账号
    +
    +
    user平台账号profile / security / status,不保存应用清单
    +
    +
    +
    ↓ 1 : N
    +
    +
    派生关系
    +
    +
    user_app成员 + 授权roles / status / source / grant / config
    +
    user_identity登录身份appId + provider + openid / unionid
    +
    +
    +
    + +
    + + + + + + + + + + + + + + + + + + + + + +
    集合回答的问题关键唯一约束
    user“这个人是谁”profile.mobile unique + sparse
    user_app“他能进哪个应用、是什么角色、是否被停用”{ userId, appId } unique;status 取 active / disabled
    user_identity“他用什么方式登录”{ appId, provider, openid } unique partial;{ provider, unionid } unique partial
    +
    + +

    授权规则

    +
      +
    • 登录只授予 user:管理员角色只能通过 POST /user/grant 或运维脚本显式授予,登录接口不会产生管理员。
    • +
    • 角色校验必须带应用维度:auth({ appId, roles });声明了 appId 就必须存在 status=active 的成员关系,否则 403。只写 roles 不写 appId 视为路由配置错误。
    • +
    • 撤销不删成员:撤销角色只 $pull roles,保留成员记录便于审计;撤销前校验“至少保留一个启用管理员”。
    • +
    • 应用注册表集中维护:APP_REGISTRY 记录 appId → platform / provider,启动时校验 conf.json 覆盖情况,配置缺失在部署阶段暴露。
    • +
    + +

    health 侧如何判定管理员与陪诊员

    +
    + + + + + + + + + + + + + + + + + + + + + +
    身份判定依据可访问范围
    管理员userInfo 返回的 apps 中存在 wxapp-escort-admin 或 web-escort-admin,roles 含 admin 且未停用;过渡期兼容旧 app 字段全量订单、档案、医院写接口、培训报名、陪诊师管理、退款查单、删除订单
    陪诊员Employee 档案 role=attendant + status=active本人名下订单、本人订单状态流转、支付查单、服务记录
    C 端用户token 用户本人/escort-record/my、/health-profile/mine、支付 / 取消
    +
    + +

    user ↔ employee 关联加固

    +
      +
    • employee.userId 建 partial unique 索引(仅约束 ObjectId 类型),一人最多一条员工档案;换微信号走人工改绑,不自动合并。
    • +
    • employee.userIdSource 记录绑定来源:manual / application,可追溯。
    • +
    • employeeNo 为 unique + sparse,不能设默认空串;建档路径显式生成 ATT{yyyyMMdd}{4位随机},撞号换号重试。
    • +
    • 三层身份各司其职:user.apps 中有 wxapp-escort-admin 只代表“进过陪诊师端”;attendant_application 代表“申请过程”;employee(attendant + active)才代表权限。
    • +
    + + +
    +

    3.1 陪诊师入驻

    + +

    + 新增一条完整链路:微信登录 → 无身份仅见申请页 → 提交资料 → Web 后台审核 → 通过后自动建档 → 全功能开放。 + 申请数据独立成表,员工表只保存审核通过的真实员工。 +

    + +
    + 无申请 + 提交 + pending + 通过 + approved + (已是员工) +
    +
    + pending + 驳回 + rejected + 重新提交 + 新的 pending +
    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    设计点方案
    数据模型attendant_application:申请人信息、服务城市、资质 / 健康证 data URL、状态、审核记录、approvedEmployeeId(补偿用)
    并发防重{ userId: 1 } partial unique(仅 status=pending);提交先查后插,撞 11000 回落原单
    审批一致性先条件更新抢占 pending → approved;再幂等建档;失败可重按“通过”续跑,不用事务
    建档规则无档案则新建并显式生成工号;已有 attendant 档案则激活并同步字段;其他岗位抛冲突、申请单回滚为 pending
    材料处理证件照留在申请表做审计,不复制进 employee;仅回填健康证到期日等结构化字段
    结果感知不做主动推送;用户下次进入小程序时申请页 / 全局守卫强刷角色即可感知
    +
    + +

    审批幂等逻辑

    +
    // 第一步:只有 pending 能被抢占,两个管理员并发只有一个成功
    +doc = findOneAndUpdate({ _id, status: "pending" }, { $set: { status: "approved", review } })
    +
    +// 已处理过:approved 但未回填员工 → 续跑;已回填 → 幂等成功;其余 → 409
    +// 第二步:ensureEmployee(doc) 幂等建档,成功后回填 approvedEmployeeId
    + +

    小程序全局守卫

    +
      +
    1. 包装全局 Page() 构造器,在每个页面 onShow 后统一执行守卫,避免逐页遗漏。
    2. +
    3. 当前路由在白名单(申请页)→ 直接放行。
    4. +
    5. ensureRoleSafe() 解析失败(5xx / 断网)→ 停留当前页,不跳转,避免误踢在职陪诊师。
    6. +
    7. role === "none" → reLaunch 到申请页;admin / attendant 正常放行。
    8. +
    + +
    + 明确不做:撤回申请、审核结果订阅消息、给 /escort-record 增加身份中间件(C 端共用这些接口)、把材料照片复制到 employee。 +
    +
    + + +
    +

    04订单域

    + +

    + escort_record 是业务聚合根,同时保存归属引用、就诊人快照、 + 服务与排期、陪诊员、医院、费用快照、取消信息等。 + 快照字段保证档案被修改或删除后,历史订单仍可完整还原。 +

    + +

    三个正交状态维度

    +
    + + + + + + + + + + + + + + + + + + + + + +
    维度取值迁移规则
    服务状态 statuspending → confirmed → in_progress → completed单向;completed 为终态,不可回退
    取消状态 cancelStatusnone / requested / cancelled只允许 none → requested / cancelled、requested → cancelled
    支付状态 payment.statusunpaid / partial / paid / refunding / refunded已收款后禁止改支付状态、实收金额、总金额;退款由支付链路推进
    +
    + +

    + 取消与支付是独立维度:服务状态只描述履约生命周期,取消用 cancelStatus 表达, + 展示优先级取 cancelStatus。用户端只保留“取消订单”,不提供删除入口。 +

    + +

    服务目录是预约规则的唯一事实源

    +

    + api/health/resource/services.js 定义服务价格、可服务区域、 + advanceDays、durationMinutes、sessions、 + requiresAddress。后端下单 / 改期会忽略客户端提交的 + schedule.duration 与 payment.totalFee,按目录重新派生并校验; + 前端只能只读展示,不能自行填写。 +

    + +

    订单归属:档案锚定

    +
      +
    • 管理员代客下单不传 userId(传了也忽略),订单归属取所选健康档案的 profile.userId。
    • +
    • 档案无归属时允许下单,订单 userId 留空;后期由管理员在订单编辑中补归属,补齐后 C 端才可见。
    • +
    • 不新开“按 userId 查用户”的接口,遵守 user 服务的安全约束。
    • +
    • 无主订单必须跳过“每人最多 3 张未完成单”的校验,否则会按空 userId 统计全部无主订单并全局拦截。
    • +
    • 新建订单携带 idempotencyKey,防止连点重复建单。
    • +
    + +

    权限与查询口径

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    场景接口 / 规则
    管理员全量列表GET /escort-record,requireAuth + requireAdmin
    陪诊员本人列表GET /escort-record/attendant,按 attendant.id = 当前 userId 限定,复用管理员的过滤 / 分页 / 支付窗口派生逻辑
    单条访问HandlerEscortRecord.canAccess 逐单判定:管理员放行,陪诊员仅本人名下
    列表筛选服务状态(多值)、取消状态、支付状态、支付渠道、预约日期 / 时间段、关键词(就诊人 / 陪诊员 / 医院 / 订单号)、userId、healthProfileId
    计数一致性筛选条件统一收敛到 buildRecordFilter,列表与 counts 必须同源,避免页签角标与列表不一致
    +
    + +
    + 为什么 C 端与管理端共用写接口:下单、改单、取消同属一套状态机与资金规则; + 追加身份中间件会直接打断 C 端。越权风险由逐单 canAccess 与字段白名单控制。 +
    +
    + + +
    +

    05支付与退款

    + +

    选型

    +
    + + + + + + + + + + + +
    要素结论
    支付产品小程序支付(JSAPI 下单 + wx.requestPayment)
    商户 / API普通商户直连,APIv3,JSON 报文 + RSA-SHA256 签名
    验签微信支付公钥(PUB_KEY_ID_),长期有效免轮换
    SDKNode 内置 crypto 自实现,无新增依赖
    支付窗口下单显式传 time_expire,默认 24 小时且不晚于服务开始当天;窗口以下单时间为起点固定计算
    +
    + +

    数据模型:订单快照 + 流水事实源

    +
    +
    +
    业务
    +
    +
    escort_record业务订单status + payment 汇总快照(展示用)
    +
    +
    +
    ↓ 1 : N,每次支付尝试一条
    +
    +
    资金
    +
    +
    payment_record支付流水outTradeNo / transactionId / 状态机 / 事件时间戳
    +
    refund_record退款流水outRefundNo / refundId / 状态 / 入账账户
    +
    +
    +
    + +
      +
    • 金额全链路用“分”(int):由 service.price 字符串按小数点拆位得到整数分,不做元 × 100 浮点运算,只在展示层转元。
    • +
    • 一单可多流水,单号不重用:outTradeNo = 订单_id + "-" + 尝试序号,唯一索引;订单的 payment.paymentRecordId 指向当前有效流水。
    • +
    • 支付方式双字段:payChannel 是用户选择的渠道(online_wechat / offline),method 是实际收款方式(空 / online_wechat / offline_cash / offline_transfer);避免把未收到的钱记成已按某方式收款。
    • +
    + +

    支付主链路

    +
    +
  • + 创建支付 + 校验订单本人 / 待支付 / 金额大于 0 / 未超支付窗口;同一订单按 recordId 进程内串行,防止并发产生两条在途流水。 +
  • +
  • + JSAPI 下单 + prepay_id 有效期内(2 小时)重复点击直接复用;已过期但仍在支付窗口内,沿用原 outTradeNo 与原参数重下;旧流水已关闭或窗口到期才换新号。 +
  • +
  • + 前端调起收银台 + 前端回调不可信;支付后必须调后端查单确认,以后端结果为准。 +
  • +
  • + 支付回调(权威) + 验签 → AES-256-GCM 解密 → 校验 out_trade_no / 金额 / mchid / appid / currency → 写流水 → 刷订单快照 → 5 秒内应答 200,重复推送幂等。 +
  • +
  • + 取消 / 切换支付方式 + 若存在在途流水,必须先关单;关单失败当场查单一次:已支付则中止切换并转退款,未确认则标记 closed_unconfirmed 交给巡检。 +
  • +
  • + 退款 + 先写 refund_record(processing) 再调退款接口;超时/系统异常先查退款,未受理则同一 outRefundNo 原参数重试一次;回调或管理端查单补写终态。 +
  • +
    + +

    关键一致性规则

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    场景处理
    已取消订单收到支付回调流水仍落 pay_success(钱确实到账,是财务事实),订单快照保持 cancelled;应答 200 之后异步发起原路全额退款
    存在未决流水时改价禁止修改 payment.totalFee;要调价必须先关单,否则微信侧金额与本地流水错位
    手工标记“线上微信 + 已支付”必须存在支付流水,否则 400;线上收款只能由支付回调写入
    线下收款平台补记 offline_cash / offline_transfer + paidFee,按金额推导 unpaid / partial / paid;不改动履约链路
    回调验签 / 解密 / 字段校验失败只记日志并应答 4XX/5XX,不落业务库(报文不可信)
    外部调用异常统一记 lastError { stage, code, message, requestId, httpStatus, at }、errorCount、lastAttemptAt;接口只返回通用提示,不暴露内部细节
    +
    + +

    后台巡检(回调丢失的唯一兜底)

    +
      +
    • 服务启动时注册单一定时器,默认运行,每 10 分钟扫一次最近 7 天内的 created / closed_unconfirmed 流水。
    • +
    • created:查单为 SUCCESS 则按回调同一套逻辑收敛;NOTPAY 且已过 timeExpireAt 则关单置 closed。
    • +
    • closed_unconfirmed:查单确认,未支付补记 closed,已支付转退款。
    • +
    • 对账以 transactionId / outTradeNo 为键,与微信交易账单逐笔核对;本期不做自动账单下载,保留人工对账与巡检兜底。
    • +
    +
    + + +
    +

    06管理端设计

    + +

    6.1 陪诊师小程序(wxapp_companion)

    +
      +
    • 角色化:登录后解析 admin / attendant / none;管理员看全量数据,陪诊员只看本人订单;tabBar 静态不变,入口与数据源在页内切换。
    • +
    • 全局守卫:包装 Page() 统一注入;无身份跳申请页;角色解析失败停留当前页。
    • +
    • 入驻申请页:未申请 / 已驳回展示表单并可预填;待审核展示静态说明;已是员工直接回首页。页脚展示当前微信账号,不提供无效的“退出登录”。
    • +
    • 订单操作:管理员可补录线下收款、取消、退款查单、删除;陪诊员只能做状态流转与服务记录;已收款订单的支付字段锁定只读。
    • +
    + +

    6.2 Web 管理后台(web_escort_admin)

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    项设计
    技术栈Vue 3 + Vite + TypeScript + Pinia(persistedstate)+ Vue Router + Bootstrap 5 / INSPINIA
    登录手机号 + 密码(POST /user/signin)或微信扫码(/user/wechat/qr/*,一次性 ticket 换 token)
    身份判定路由守卫拉 /user/userInfo,要求 apps 中存在 web-escort-admin 且 roles 含 admin
    请求封装HTTP 状态码恒 200;body.code === 401 清会话跳登录;body.code !== 0 用 body.msg 提示
    一期模块工作台、订单管理(列表 / 详情 / 状态流转 / 支付补录 / 取消审核 / 退款核销 / 软删除)、用户管理(锁定 / 解锁)、就诊人管理、陪诊师管理(含入驻审核页签与材料弹窗)
    二期模块医院管理、培训报名审核闭环、内容配置(协议 / 指南);管理员授权管理可复用 /user/grant
    +
    + +
    + 安全边界:扫码只解决“你是谁”,不解决“能不能进后台”——不自动建号、不自动授予 admin; + 未授权的微信号一律拒绝。token 不放进 URL,只带一次性 ticket。 +
    +
    + + +
    +

    07数据模型一览

    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    库集合职责关键索引 / 约束
    eiot_useruser平台账号、资料、安全凭证、账号状态profile.mobile unique sparse
    user_app应用成员、角色、启停用、授权来源、个人配置{ userId, appId } unique;{ appId, status }、{ appId, roles }
    user_identity微信 / 密码等外部登录身份、unionid{ appId, provider, openid } unique partial;{ provider, unionid } unique partial
    health 业务库employee员工档案:岗位、状态、工号、服务区域、健康证、公示信息{ userId } unique partial(ObjectId);employeeNo unique sparse
    attendant_application陪诊师入驻申请、材料、审核记录{ userId } unique partial(pending);{ status, meta.createtime }
    escort_record订单聚合:患者快照、服务、陪诊员、医院、排期、费用快照、取消按 userId / attendant.id / status / appointmentDate / payment.status 查询
    payment_record支付流水(财务事实源)outTradeNo unique;transactionId unique sparse;{ recordId }
    refund_record退款流水outRefundNo unique;refundId unique sparse
    health_profile就诊人档案,可归属某个 C 端用户{ userId }、{ name, mobile }
    hospital医院库:名称、主体、省市、地址、科室、等级拼音 / 复旦排名由服务端派生
    training_application培训报名按状态与提交时间查询
    +
    +
    + + +
    +

    08安全与一致性

    + +
    +
    +
    SECURITY
    +

    敏感数据边界

    +

    + 身份证号与证件照片只允许 requireAdmin 获取;审核列表不返回大图与身份证号, + 详情单独按 id 查询。图片入参校验 data URL 前缀、base64 合法性与 JPEG/PNG 文件头, + 不只信 MIME。 +

    +
    +
    +
    AUDIT
    +

    可追溯

    +

    + 审批人、审批时间、驳回原因全部落库;支付与退款保留完整事件时间戳、 + bankType、successTime、Request-ID 与错误快照。 +

    +
    +
    +
    CONSISTENCY
    +

    幂等优先,不上分布式事务

    +

    + 全系统以唯一索引 + 条件更新 + upsert 为基础:申请靠 pending 唯一索引, + 审批靠条件抢占,支付靠流水号唯一索引与状态条件更新,用户绑定靠 openid 唯一索引。 +

    +
    +
    +
    MIGRATION
    +

    索引变更走显式脚本

    +

    + 同键不同选项的索引不能共存,迁移脚本按“查重 → 删旧索引 → 建新索引”执行; + 所有 model 挂 error 监听,避免索引创建失败导致进程启动即崩。 +

    +
    +
    + +

    已知取舍

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    取舍影响触发条件 / 后续
    health 侧 token 缓存 5 分钟登出 / 锁定最多延迟 5 分钟生效可接受;后续引入 JWT 短 access + refresh 可改善
    单 token管理端登录会把 C 端踢下线user_session 作为独立事项另行评估
    限流、微信 access_token、WS Agent 缓存均为进程内存态nginx 挂多实例后失效水平扩容前外移 Redis
    两服务各一份 conf.jsonMongo 连接信息重复、凭证轮换需改多处中期统一到服务器级 .env
    旧 user.app 字段仍在身份数据存在双写与兼容读取所有客户端改读 apps 后的下个发布周期移除
    +
    +
    + + +
    +

    09现状与后续

    + +

    已落地的主干

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    域状态说明
    用户多应用模型已实施三表、APP_REGISTRY、appId 维度的 auth、grant / app-config 接口已落地;旧 app 字段处于兼容期
    陪诊师入驻已实施申请 / 审核 / 自动建档 / 全局守卫 / Web 审核页签全链路完成
    订单域已实施状态机、筛选与计数、代客下单档案锚定、陪诊员列表、服务目录派生均已落地
    微信支付已实施JSAPI 下单 / 查单 / 关单 / 退款 / 回调 / 巡检 / 错误落库已接入;商户配置与合规为上线前运维项
    Web 后台一期已实施登录、工作台、订单、用户、就诊人、陪诊师(含入驻审核)已可用
    陪诊师小程序同步改造部分完成角色层与订单主链路已完成;客户详情、档案归属、培训、医院库、请求层配置等仍待补齐
    用户模型收尾部分完成P4(删旧 app、strict: true)与 P5(下游完全改读 apps)未完成
    +
    + +
    + 后续工作不在本文展开。所有未完成事项、上线前运维清单、明确延后项与待产品确认问题, + 统一维护在 plan.md。 +
    + +

    相关专项文档

    + +
    + +
    + + +
    + + + + diff --git a/doc/attendant-onboarding-plan.md b/doc/attendant-onboarding-plan.md index a23fa76..c6ef97a 100644 --- a/doc/attendant-onboarding-plan.md +++ b/doc/attendant-onboarding-plan.md @@ -1,7 +1,7 @@ # 陪诊师入驻申请与审核方案 > 制定日期:2026-11-07 -> 代码基准:`api/health/routes/index.js`、`handler/employee.js`、`utils/permissions.js`、`ui/wxapp_escort_admin/utils/role.js`、`ui/web_escort_admin/src/views/attendants` +> 代码基准:`api/health/routes/index.js`、`handler/employee.js`、`utils/permissions.js`、`ui/wxapp_companion/utils/role.js`、`ui/web_escort_admin/src/views/attendants` > 状态:已实施(2026-11-08 完成编码与文档同步,实施记录见 §12) ## 0. 修订记录(2026-11-07 review) @@ -148,7 +148,7 @@ await AttendantApplication.updateOne({ _id: doc._id }, { $set: { approvedEmploye 驳回:`{ status: "rejected", review: { reviewerId, reviewedAt, rejectReason } }`,原因必填、≤200 字,仅允许从 `pending` 迁移。 -## 5. 小程序端(`ui/wxapp_escort_admin`) +## 5. 小程序端(`ui/wxapp_companion`) ### 5.1 新增页面 diff --git a/doc/backend-architecture.md b/doc/backend-architecture.md index b6009ce..7be5e30 100644 --- a/doc/backend-architecture.md +++ b/doc/backend-architecture.md @@ -14,7 +14,7 @@ d:\work\ws_health │ └── HTTP :9010 ├── ui/ # 小程序端 │ ├── wxapp_escort/ # C 端 -│ └── wxapp_escort_admin/ # 管理端 +│ └── wxapp_companion/ # 管理端 └── doc/ ``` diff --git a/doc/escort-admin-sync-plan.md b/doc/escort-admin-sync-plan.md index 08d1859..9f40590 100644 --- a/doc/escort-admin-sync-plan.md +++ b/doc/escort-admin-sync-plan.md @@ -1,7 +1,7 @@ -# 陪诊师端(wxapp_escort_admin)功能同步改造清单 +# 陪诊师端(wxapp_companion)功能同步改造清单 > 分析日期:2026-11-06 -> 分析基准:`api/health/routes/index.js`(接口能力)、`ui/wxapp_escort`(用户端已实现功能)、`ui/wxapp_escort_admin`(陪诊师/管理端现状) +> 分析基准:`api/health/routes/index.js`(接口能力)、`ui/wxapp_escort`(用户端已实现功能)、`ui/wxapp_companion`(陪诊师/管理端现状) > 本文只做差距分析与改动项整理,不包含代码实现。 > 2026-11-06 review 修订:原 P0-5(支付补录与编辑锁定)经核实 `paymentLocked` 锁定已生效,降级为 P1-11 并重写现状;原 P0-6 顺延为 P0-5;新增预约补充幂等键要求;修正部分行号与退款查单按钮显示条件。 > 2026-11-06 二次修订(按后端最新代码回填):B8 订单搜索、B12 用户列表筛选已实现;P1-4/P1-5 的检索与 userId 查询后端已就绪;B1 收窄为仅查员工档案(管理员身份改由登录响应的 `apps` 判定);B3 定为档案锚定且无归属可留空。 diff --git a/doc/plan.md b/doc/plan.md new file mode 100644 index 0000000..454f92f --- /dev/null +++ b/doc/plan.md @@ -0,0 +1,154 @@ +# ws_health 未完成事项与后续计划 + +> 整理日期:2026-11-10 +> 依据:`backend-architecture.md`、`user-multi-app-plan.md`、`attendant-onboarding-plan.md`、`escort-admin-sync-plan.md`、`web-escort-admin-plan.md`、`wechatpay-plan.md`,并结合当前代码核对 +> 配套架构文档:[architecture-overview.html](./architecture-overview.html) +> 状态口径:**已完成** / **部分完成** / **未开始** / **上线前运维项** / **明确延后** + +## 0. 总览 + +| 模块 | 完成度 | 剩余重点 | 最高优先级 | +| --- | --- | --- | --- | +| 用户多应用模型 | 部分完成 | P4 删旧 `app`、P5 下游切读 `apps` | P2 | +| 陪诊师入驻 | 已完成 | 索引迁移与真机联调属上线动作 | P0(运维) | +| 订单域后端 | 已完成 | 无 | — | +| 微信支付 | 已完成 | 商户配置、合规、上线核验 | P0(运维) | +| Web 管理后台一期 | 已完成 | 二期医院 / 培训 / 内容、扫码配置、默认密码 | P0(配置)/ P2(功能) | +| 陪诊师小程序 | 部分完成 | 客户详情、档案归属、订单信息与编辑、培训、医院库、请求层 | P1 | +| 后端架构优化 | 部分完成 | 凭证轮换、Redis 外移、配置统一 | P0 / P2 | + +--- + +## 1. 陪诊师小程序(`ui/wxapp_companion`) + +### 1.1 已完成基线 + +- 角色层:`utils/role.js` 的 `ensureRole / ensureRoleSafe / guardAdminPage / queryOrders`,管理员 / 陪诊员 / 无身份三态。 +- 全局守卫:`app.js` 包装 `Page()`,无身份跳申请页,解析失败停留当前页。 +- 入驻申请页:`pages/apply/*` 三视图(表单 / 待审核 / 已是员工)。 +- 订单主链路:角色化数据源、服务端筛选、分页与 `hasMore` 修复、支付锁定、退款查单、线下补录入口(全额)。 +- 后端支撑已就绪:`GET /employee/me`、陪诊员订单列表、代客下单(档案锚定)、员工列表、订单搜索与各状态计数。 + +### 1.2 待完成 + +| 编号 | 事项 | 现状 / 缺口 | 优先级 | 来源 | +| --- | --- | --- | --- | --- | +| M1 | 客户详情页 | `pages/customer/index.js` 跳转 `/pages/customer/detail`,但该页面未注册、不存在;列表 `total` 仍取当前页长度,`hasMore` 不准 | P1 | sync-plan P1-5 | +| M2 | 健康档案归属 | 新建档案没有“所属用户”选择;列表无归属回显;`profileInfo` 不传 `userId` | P1 | sync-plan P1-4 / B13 | +| M3 | 订单详情补全 | 缺 `cancelReason / cancelRequestedAt / cancelledAt`、`paidFee`、支付窗口与超时标识、主动查支付状态、删除订单、分配陪诊师、服务记录编辑 | P1 | sync-plan P1-1 / P1-2 / P1-8 | +| M4 | 订单编辑规则对齐 | 医院仍是手填,缺地址 / 病历号 / 性别要求 / 收货地址 / 支付渠道;日期时段未按服务目录渲染;未按角色限制可编辑字段 | P1 | sync-plan P1-3 | +| M5 | 部分支付与补录 | 仅支持“全额已支付 / 未支付”;无 `paidFee` 区间校验;`payChannel` 编辑缺失;支付状态文案回填不准确 | P1 | sync-plan P1-11 | +| M6 | 培训报名列表 | 无页面、无 API 封装;后端只有列表,无详情与状态更新接口 | P1 | sync-plan P1-6 / B7 | +| M7 | 医院库维护 | `utils/api.js` 未封装医院库 CRUD(仅医院信息 / 榜单),无医院列表与编辑页;订单不能选院回填地址 | P1 | sync-plan P1-7 | +| M8 | 请求层与环境配置 | 无 `utils/config.js`;`utils/request.js:3` 写死 `https://api.huashengtec.com`;无 401 静默重登;AI 页 `appId` 未定义 | P1 | sync-plan P1-10 | +| M9 | 派单与在线状态 | 员工列表接口已有,但订单无“分配陪诊师”入口;首页在线开关只改本地 `data.online`,无写接口 | P1 / P2 | sync-plan P1-8 / B10 | +| M10 | AI 快捷问题 / 语音 / 图片 | 快捷问题仍硬编码;`ai.asr` / `ai.ocr` 未封装 | P2 | sync-plan P2-1 | +| M11 | 内容页与个人资料 | 协议 / 指南 / 关于 / 联系、个人资料编辑均未落地;设置页仍有“开发中”占位 | P2 | sync-plan P2-2 / P2-3 / P2-7 | +| M12 | 隐私与展示细节 | 列表未脱敏;陪诊员与管理员看到的信息无差异;医院榜单 / 公示预览未做;部分页面缺空态兜底 | P2 | sync-plan P2-4 / P2-5 / P2-6 / P2-8 | + +### 1.3 关键验收口径 + +- 客户详情能从列表进入,展示用户资料、名下档案、名下订单,并支持代客下单 / 新增档案;分页以服务端 `total` 为准。 +- 新建档案必须选择归属客户(或本人),编辑页回显归属;无归属档案有明确提示。 +- 订单详情在档案 403 或已删除时仍能展示订单里的患者快照;已取消订单能看到完整取消信息。 +- 已支付订单的支付字段只读且显示真实状态文案;补录线下收款时 `0 ≤ paidFee ≤ totalFee`,状态由页面按金额推导。 +- 请求层支持本地 / 生产环境切换,token 失效可静默重登并重试一次。 + +--- + +## 2. Web 管理后台(`ui/web_escort_admin`) + +### 2.1 已完成基线 + +- 登录:手机号密码 + 微信扫码回调页;路由守卫校验 `apps` 中的 `web-escort-admin` 管理员成员关系。 +- 工作台、订单(列表 / 详情 / 状态流转 / 支付补录 / 取消审核 / 退款查询、重试、人工核销 / 软删除)。 +- 用户管理(筛选 / 锁定解锁)、就诊人管理、陪诊师管理(在职列表 + 入驻审核页签 + 材料弹窗)。 + +### 2.2 待完成 + +| 编号 | 事项 | 现状 / 缺口 | 优先级 | +| --- | --- | --- | --- | +| W1 | 二期模块 | 医院管理、培训报名审核闭环、内容配置(协议 / 指南)均未建页面与路由 | P2 | +| W2 | 管理员授权管理 | 后端 `/user/grant` 已可用,后台暂无授权页面 | P2 | +| W3 | 模板 demo 清理 | 仍保留 `views/admin/*`、`views/auth/*` 等大量未使用模板页 | P3 | +| W4 | 微信扫码登录配置 | `conf.json` 的 `app["web-escort-admin"]` 需填 appid / secret,回调域名需配到微信后台;未配置时扫码接口返回 503 | 上线前运维 | +| W5 | 初始管理员安全 | 默认密码 `Escort@2026` 必须在上线前更换;重跑 `api/user/scripts/create_web_admin.js` 即可 | 上线前运维 | +| W6 | 服务重启 / 构建 | 后端改动需重启,前端需构建部署;当前无热重载 | 上线前运维 | + +--- + +## 3. 用户多应用模型(`api/user`) + +| 编号 | 事项 | 现状 / 缺口 | 优先级 | 来源 | +| --- | --- | --- | --- | --- | +| U1 | P4:停止写旧 `app`、删除字段、`strict: true` | `api/user/models/schema/user.js:74` 仍有 `app`,`:87` 仍为 `strict: false`;写入仍在双写 | P2 | multi-app P4 | +| U2 | P5:下游完全切读 `apps` | health 侧 `permissions.js` 已优先读 `apps`,但仍保留旧 `app` 兜底;`web_tcm` 仍读 `app.tcm`(外部仓库) | P2 | multi-app P5 | +| U3 | 多端登录互踢 | 仍为单 token,管理端登录会把 C 端踢下线;`user_session` 未建 | 明确延后 | multi-app §6.2 / §12.3 | +| U4 | `unionid` 跨应用合并 | 依赖微信开放平台绑定后才有值;未绑定时退化为手机号 | 运营配置 | multi-app §10 | +| U5 | 新应用 config 白名单 | `ttapp-escort` 等未配置 `APP_CONFIG_SCHEMAS`,写入会返回 400;接入前需补 | 接入前 | multi-app §6.7 | + +**U1 前置条件**:所有客户端已改读 `apps`,且兼容视图稳定运行至少一个发布周期;执行前备份 `user` 集合。 + +--- + +## 4. 后端能力缺口(`api/health`) + +| 编号 | 事项 | 现状 / 缺口 | 优先级 | +| --- | --- | --- | --- | +| B1 | 培训报名详情与状态流转 | 只有 `GET /training-application`;缺 `GET /:id`(含材料)与 `PATCH /:id/status` | P1(若做审核闭环) | +| B2 | 员工在线状态 | `attendantInfo.isOnline` 已有,但无写接口;需 `PATCH /employee/me/online` | P2 | +| B3 | 档案归属校验增强 | `handler/health_profile.js:56-62` 只校验 ObjectId 格式,未校验用户在 user 服务存在,也未禁止管理端转移归属 | P1 | +| B4 | 派单校验 | 分配陪诊师需校验目标 `userId` 是当前在职陪诊员;目前只有员工列表接口,无订单侧校验封装 | P1 | + +> 已补齐、无需再排期:`GET /employee/me`、陪诊员订单列表口径、代客下单档案锚定、订单搜索 / 支付状态筛选 / 各状态计数、订单详情软删除过滤、陪诊员服务记录字段、`/user/lock` 解锁接口、`/user/info/batch` 批量取用户。 + +--- + +## 5. 安全与上线运维项 + +| 编号 | 事项 | 说明 | 优先级 | +| --- | --- | --- | --- | +| O1 | 凭证轮换 | MongoDB 密码、微信 AppSecret、`.env` 内 3 个 API key 均已入 git 历史;需更换凭证,并确认 `conf.json` / `.env` 已从索引移除 | P0(安全) | +| O2 | 员工 userId 索引迁移 | 依次执行 `node scripts/check_employee_binding.js` → `node scripts/migrate_employee_userid_unique_index.js --apply` → `node scripts/check_db_schema_sync.js` | P0(部署) | +| O3 | 微信支付商户配置 | JSAPI 权限、商户号与小程序 APPID 绑定、API 证书、APIv3 密钥、微信支付公钥、账户余额;服务器 `conf.json`、环境变量、出网、回调 IP / WAF | P0(上线前) | +| O4 | 支付合规 | 交易类小程序需接入“订单发货管理”,否则可能被限制支付权限 | P0(上线前) | +| O5 | Web 后台配置 | 扫码 appid / secret / 回调域名;默认管理员密码更换;服务重启与前端构建 | P0(上线前) | +| O6 | Redis 外移 | 限流、微信 access_token 缓存、WS Agent 缓存均为进程内存态,多实例部署前需外移 | P2(扩容前) | +| O7 | 配置统一 | 两服务各一份 `conf.json`,Mongo 连接信息重复;统一到服务器级 `.env` | P2(中期) | +| O8 | JWT / refresh token | 当前为不透明 token + 5 分钟缓存;中期可换短 access + refresh,降低登出延迟 | P3(中期) | + +--- + +## 6. 微信支付:明确延后项 + +以下均为 `wechatpay-plan.md` 第十节已确认“本期不做”,不属于遗漏: + +- 交易账单 / 资金账单自动下载与自动对账(现由巡检 + 人工下载账单兜底)。 +- 巡检多频率退避与告警(现固定 10 分钟一轮)。 +- 退款 `ABNORMAL`(银行卡作废 / 冻结)自动异常退款(现转人工)。 +- 支付主备域名自动切换(现只连主域名)。 +- 部分退款 / 多次退款(现一单一退,`outRefundNo` 固定 `-R1`)。 +- 培训报名复用 `payment_record` 接入支付。 + +--- + +## 7. 待产品确认 + +1. 管理端小程序定位:长期是“管理员 + 陪诊员”共用,还是只面向陪诊员?决定管理类入口是否保留。 +2. 代客下单补归属的入口与核对方式:是否需要防误挂校验(如二次确认、操作日志)。 +3. 陪诊员可见字段范围:是否需要查看身份证号、完整费用与退款信息?建议只给服务必需字段。 +4. 培训报名是否需要审核流转(联系 / 入班 / 取消),还是只读列表即可?决定 B1 是否排期。 +5. 医院库维护放在陪诊师小程序、Web 后台,还是独立后台? +6. 部分支付 / 线下收款补录是否为必须能力?当前后端支持,管理端仅做了全额补录。 +7. 多应用同时登录(不互踢)是否需要在下一阶段解决? + +--- + +## 8. 建议执行顺序 + +1. **上线硬项**:O1 凭证轮换 → O2 索引迁移 → O3 / O4 支付配置与合规 → O5 Web 后台配置与密码。 +2. **管理端 P1 闭环**:M8 请求层(前置)→ M1 客户详情 → M2 + B3 档案归属 → M3 / M5 订单详情与支付 → M4 订单编辑。 +3. **管理能力补齐**:M6 + B1 培训、M7 医院库、M9 + B2 / B4 派单与在线状态。 +4. **模型收尾**:U1 P4 → U2 P5(需一个发布周期与全量回归)。 +5. **扩容前优化**:O6 Redis 外移、O7 配置统一。 +6. **按需排期**:M10 / M11 / M12、W1 / W2 / W3、第 6 节延后项。 diff --git a/doc/web-escort-admin-plan.md b/doc/web-escort-admin-plan.md index 0e71099..0035524 100644 --- a/doc/web-escort-admin-plan.md +++ b/doc/web-escort-admin-plan.md @@ -7,7 +7,7 @@ ## 一、背景与范围 -现有管理能力承载在 `ui/wxapp_escort_admin`(小程序端,管理员/陪诊员混用),缺少桌面端后台。本方案新建 Vue Web 后台,第一期覆盖: +现有管理能力承载在 `ui/wxapp_companion`(小程序端,管理员/陪诊员混用),缺少桌面端后台。本方案新建 Vue Web 后台,第一期覆盖: - 登录 + 工作台 - 订单管理(写操作接口齐全,列表筛选需补强) diff --git a/doc/wechatpay-plan.md b/doc/wechatpay-plan.md index 97d1d94..0580bb6 100644 --- a/doc/wechatpay-plan.md +++ b/doc/wechatpay-plan.md @@ -363,7 +363,7 @@ escort_record (业务订单) payment_record (支付流水) refu | 2 | `pages/escort/itemorder.js` | 新增支付方式选择(微信支付 / 线下支付,默认微信支付);提交订单时带 `payment.payChannel`。选微信支付:下单成功 → 立即 `payOrder` → `wx.requestPayment` → 查单确认 → 按结果跳转;选线下支付:下单成功后直接跳订单列表并提示线下支付 | | 3 | `pages/escort/recordlist` / `recorddetail` | `unpaid` 订单按 `payChannel` 展示:`online_wechat` 显示「待支付」+「去支付」(超过支付窗口则显示「支付已超时」并隐藏去支付,只保留改线下 / 取消),`offline` 显示「线下支付」。详情页保留「取消订单」(无删除按钮):待确认且未收款取消即删除;已确认/已收款提示「取消申请已提交」。详情页增加「切换支付方式」入口(仅待支付可改);支付按钮防抖 | -管理端(`ui/wxapp_escort_admin`):`pages/order/orderDetail` 需展示 `refunding` / `refunded` 与 `payChannel`,并新增「查询退款结果」按钮(调 `POST /escort-record/:id/refund/query`),用于退款回调丢失时的人工兜底;`orderEdit` 在存在未决流水时禁用金额输入。 +管理端(`ui/wxapp_companion`):`pages/order/orderDetail` 需展示 `refunding` / `refunded` 与 `payChannel`,并新增「查询退款结果」按钮(调 `POST /escort-record/:id/refund/query`),用于退款回调丢失时的人工兜底;`orderEdit` 在存在未决流水时禁用金额输入。 ## 七、关键技术点与易错点 diff --git a/ui/wxapp_companion b/ui/wxapp_companion new file mode 160000 index 0000000..a8b8968 --- /dev/null +++ b/ui/wxapp_companion @@ -0,0 +1 @@ +Subproject commit a8b896846b69fb9ed67265b69901f48c72e40034 diff --git a/ui/wxapp_escort_admin b/ui/wxapp_escort_admin deleted file mode 160000 index 5915396..0000000 --- a/ui/wxapp_escort_admin +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 5915396192325d7a1e933671f401a31719a133d8