Files
ws_health/doc/web-escort-admin-plan.md
T

18 KiB
Raw Blame History

陪诊 Web 后台管理(web_escort_admin)实施方案

制定日期:2026-11-06 目标目录:ui/web_escort_admin(当前为空) 分析基准:api/health/routes/index.js、api/user/routes/index.js、ui/wxapp_escort(C 端现状)、doc/escort-admin-sync-plan.md(管理端差距分析) 已确认决策:UI 采用 INSPINIA v5.0 模板;后端接口随前端一起补齐;第一期只做登录 + 工作台 + 四大核心模块。

一、背景与范围

现有管理能力承载在 ui/wxapp_companion(小程序端,管理员/陪诊员混用),缺少桌面端后台。本方案新建 Vue Web 后台,第一期覆盖:

  • 登录 + 工作台
  • 订单管理(写操作接口齐全,列表筛选需补强)
  • 用户管理(列表无筛选、缺锁定/解锁接口)
  • 就诊人管理(CRUD 齐全,缺归属校验与归属回显)
  • 陪诊师管理(管理端接口完全缺失,需新建)

医院管理、培训报名审核闭环、内容页(协议/指南)放第二期。

二、现状能力盘点

2.1 接口现状

模块 现有接口 缺口
用户管理 POST /user/list、/user/userInfo、/user/update(user 服务 :9010) 筛选能力弱;无锁定/解锁、无失败重置(目前解锁需手动改库,见 doc/backend-architecture.md 第三节遗留事项)
就诊人管理 /health/health-profile 管理员 CRUD 全套(api/health/routes/index.js:126-130)。schema 已有 userId 字段,管理端写入白名单 PROFILE_FIELDS 已放行 userId 实际缺两处:后端不校验传入的 userId 是否存在;列表不回显归属用户昵称/手机号,前端无法按用户辨识(详见 4.3)
陪诊师管理 仅公开公示接口 GET /attendant、/attendant/:id(api/health/routes/index.js:153-155)。model 层已有 createEmployee / updateEmployee / findByOrg / findByRole / findByUserId 静态方法 handler 与路由完全没有面向管理端的接口:列表、新增、编辑、启停用均无;培训报名列表 GET /training-application 已有
订单管理 /escort-record 全套:列表(requireAdmin)/详情/状态流转/支付补录/退款核销/软删除 写操作完整;列表筛选能力不足:目前仅支持 status / cancelStatus / userId / appointmentDate(单日)/ healthProfileId / 分页,缺支付状态、支付渠道、时间段、关键词(详见 4.2)

2.2 订单后端关键约束(前端必须遵守)

来自 doc/escort-admin-sync-plan.md 3.2 节:

  • 服务状态迁移仅允许 pending → confirmed → in_progress → completed,completed 为终态
  • 取消迁移仅允许 none → requested/cancelled、requested → cancelled
  • 已收款(paid/partial/refunding/refunded)订单禁止改支付状态、实收金额、总金额
  • 手工标记「线上微信 + 已支付」必须存在支付流水,否则后端 400
  • 存在未支付流水时禁止改价
  • 管理员/陪诊员取消时:未确认且未收款物理删除;否则 cancelStatus=cancelled,已收款自动进入退款
  • 删除订单为管理员专属的软删除

2.3 应用身份与鉴权

Web 后台是独立应用,不复用小程序陪诊师端的应用身份:

appId 载体 登录方式 角色
wxapp-escort C 端小程序 微信登录 user
wxapp-escort-admin 陪诊师/管理小程序 微信登录 admin / user
web-escort-admin 本 Web 后台 账号密码 / 微信扫码 admin
  • 不能用 app["wxapp-escort-admin"] 判定 Web 后台身份:该键属于小程序端,混用会导致两个端无法分别授权、分别停用
  • user 服务已完成多应用重构:授权主体是 user_app 成员关系,管理端路由统一用 auth({ appIds: ADMIN_APP_IDS, roles: ["admin"] }),isAdmin(membership) 只认成员记录
  • health 服务通过 userInfo 返回的 apps 数组判定管理员(含过渡期 app 兜底),并同时接受两个管理端 appId;应用维度完全隔离要等 health 侧改读 user_app 后收紧
  • Web 端判定管理员不能按 Employee 记录放行:requireAdmin 只调 isAdmin()
  • 登录复用 user 服务:POST /user/signin(密码)或 /user/wechat/qr/*(扫码),token 请求头 token: xxx 或 Authorization: Bearer xxx(health 服务两者兼容)
  • health 服务对 token→user 有 5 分钟进程内缓存,登出/锁定在 health 侧最多延迟 5 分钟生效(已知代价,可接受)
  • 陪诊员日常操作继续用小程序端;Web 后台只面向管理员

2.4 初始管理员账号(已创建)

现网此前没有任何 Web 后台管理员,已用脚本创建默认账号:

项 值
用户ID 6aeda4ff6e71ec7180206e95
手机号 13800000000
密码 Escort@2026
姓名 系统管理员
应用授权 user_app(web-escort-admin, roles=["admin"], status="active"),并同步旧 app["web-escort-admin"].role 供 health 过渡期读取

创建脚本:api/user/scripts/create_web_admin.js,幂等,可重复执行用于重置密码。

cd api/user
node scripts/create_web_admin.js [手机号] [密码] [姓名]
  • 不传参数时使用上表默认值
  • 手机号已存在 → 重置密码、解锁、补授权,不会新建重复账号
  • 同时写 user_app(重构后的授权主体)与旧 app 字段(供 api/health 等未迁移下游读取);app 字段移除后只保留 user_app 写入即可
  • 上线前必须改掉默认密码:目前没有改密接口,重跑脚本并传入新密码即可

2.5 登录方式

后台支持两种登录,签发的是同一套平台 token:

方式 入口 说明
手机号 + 密码 POST /user/signin 账号需有 security.passwd
微信扫码 /user/wechat/qr/* 开放平台「网站应用」qrconnect

扫码链路:

  1. 前端 GET /user/wechat/qr/url → 返回二维码地址与一次性 state(5 分钟有效)
  2. 微信回调 GET /user/wechat/qr/callback?code=&state=:校验 state(用后即删)→ 用 code 换取 openid / unionid
  3. 账号匹配顺序:本应用 user_identity(web-escort-admin, weixin-web, openid) → 按 unionid 跨应用 → 旧字段 app["web-escort-admin"].wxopenid 兜底
  4. 必须存在 user_app(appId=web-escort-admin、status=active、roles 含 admin),否则直接 302 回前端并带 error=forbidden
  5. 成功则生成 60 秒有效的一次性 ticket,302 到 ${webOrigin}/auth/wechat-callback?ticket=...
  6. 前端 POST /user/wechat/qr/exchange { ticket } 换取 token

安全约束:

  • 扫码只解决「你是谁」,不解决「能不能进后台」:不自动创建账号、不自动授予 admin,未授权微信号一律拒绝
  • token 不放进 URL(会进浏览器历史与 nginx 日志),URL 只带一次性 ticket
  • state / ticket 存在 user 服务进程内 Map 中,多实例部署需换 Redis
  • 未配置 appid/secret 时扫码接口返回 503,不影响密码登录

配置在 api/user/conf.json 的 app["web-escort-admin"]:

"web-escort-admin": {
  "appid": "<开放平台网站应用 appid>",
  "secret": "<对应 secret>",
  "callbackUri": "http://localhost:9010/user/wechat/qr/callback",
  "webOrigin": "http://localhost:5173"
}

首次使用扫码登录前,必须先用密码登录并在后台点「绑定微信」(GET /user/wechat/qr/url?mode=bind,需登录态),否则该微信没有 user_identity 记录,扫码会落到 not_bound。

三、UI 选型(已确认:INSPINIA 模板)

模板位置:D:\download\INSPINIA_v5.0\INSPINIA_v5.0\Bootstrap\Vue\StarterKit

技术栈:Vue 3.5 + Vite 7 + TypeScript + Pinia 3(带 persistedstate 插件)+ Vue Router 4 + Bootstrap 5.3 + bootstrap-vue-next + @iconify/vue + ECharts 6。

选用理由:后台管理是典型表单+表格+图表场景,模板自带 vertical/horizontal 布局、登录页、错误页、router 骨架,开箱即用;技术栈与项目现有风格(Vite + TS)兼容。

落地动作:

  1. 复制 StarterKit 到 ui/web_escort_admin
  2. 清理 demo 页面(admin/dashboard、admin/icons、多余的 auth 变体),保留 vertical 布局、sign-in、403/404/500 错误页
  3. vite.config.ts 加 dev proxy:/user → http://localhost:9010、/health → http://localhost:9004;生产由 nginx 同路径转发(与现有网关一致,见 api/health/nginx_site.txt)

四、后端接口补齐

4.1 user 服务(:9010)

接口 说明
POST /user/list 增强 现有实现只按 app.wxapp-escort 存在与否过滤,无任何条件筛选(api/user/handler/users.js:300)。补关键词(昵称/手机号)、账号状态、注册时间范围;沿用现有 pageSize 上限 200 的约束
POST /user/info/batch 管理端按 userIds 批量取用户(上限 100),供就诊人/订单列表展示归属用户;避免前端逐行查造成 N+1
POST /user/lock 锁定/解锁统一入口,写 status.account,取值只有 "normal" / "lock"(api/user/models/schema/user.js:70,不是 locked);解锁时同时清零失败次数,锁定同时作废 token
GET /user/wechat/qr/url 生成扫码登录地址,?mode=bind 时为绑定微信(需登录态)
GET /user/wechat/qr/callback 微信开放平台回调,302 回前端并附带一次性 ticket 或 error
POST /user/wechat/qr/exchange 用 ticket 换 token,响应结构与 /user/signin 一致
管理员校验 重构后已在路由层声明:auth({ appIds: ADMIN_APP_IDS, roles: ["admin"] })(api/user/routes/index.js),handler 内不再重复判定

4.2 health 服务(:9004)

4.2.1 陪诊师(Employee)CRUD

枚举以 schema 为准(api/health/models/schema/employee.js):role 有 6 个取值(attendant / nurse / doctor / admin / operator / other,:47-52),status 有 4 个取值(active / inactive / resigned / suspended,:110-115)。model 层静态方法已可用,工作量集中在 handler 与路由:

接口 说明
GET /employee 管理员分页列表,支持 role、status、关键词(姓名/工号/手机号)筛选。公示接口的姓名脱敏(maskName)只用于 C 端,管理端必须返回真实姓名
POST /employee 新增员工档案,复用 createEmployee(内部会生成姓名拼音索引)
PUT /employee/:id 编辑基础信息与公示字段,复用 updateEmployee
PATCH /employee/:id/status 启停用,取值上述 4 个枚举值;非 active 即不在 C 端 GET /attendant 出现(公示列表硬编码 status: "active")

4.2.2 订单列表筛选补强(GET /escort-record)

现状见 api/health/models/schema/escort_record.js:234-269 的 buildRecordFilter:

筛选维度 现状 需补
服务状态 / 取消状态 / userId / healthProfileId 已支持(status 支持逗号多值) —
预约日期 仅单日 appointmentDate(按 schedule.date 的 UTC 日界) 时间段 startDate / endDate
支付状态 payment.status 不支持 补,取值 unpaid / partial / paid / refunding / refunded
支付渠道 payment.payChannel 不支持 补,取值 online_wechat / offline
关键词(就诊人姓名、手机号、订单号) 不支持 补

新增筛选必须同时进入 buildRecordFilter,否则 findRecordPage 里的 counts.all / counts.ongoing 会与列表口径不一致。

全部挂 requireAuth + requireAdmin(api/health/routes/index.js 已有中间件,直接复用)。

4.3 health-profile 归属修正

schema 与写入白名单本身已支持 userId(api/health/models/schema/health_profile.js:13、api/health/handler/health_profile.js:9),管理端 createProfile 只要传了就会落库。sync-plan 里「新建档案不写 userId」指的是小程序前端没传,不是后端不支持。真实缺口有两条:

  • 校验归属用户存在性:createProfile / updateProfile 目前直接透传 userId,既不校验格式,也不确认该用户在 user 服务是否存在
  • 列表回显归属信息:GET /health-profile 只返回档案本身,前端拿不到归属用户昵称/手机号,需要补关联查询

C 端的 /health-profile/mine 系列保持不变:其 userId 仍强制取自 token,updateMyProfile 里还显式 delete update.userId 禁止转移归属(api/health/handler/health_profile.js:190-191)。

4.4 与用户多应用重构的衔接

doc/user-multi-app-plan.md 的方案已在 api/user 落地:user / user_app / user_identity 三张表、auth({ appId, appIds, roles })、/user/grant、/user/app-config 均已可用。Web 后台直接按新模型接入,不再依赖旧 app 字段:

本方案接口 实现口径
登录 /user/signin 平台账号登录,token 仍为平台级单凭证
登录 /user/wechat/qr/* 身份写 user_identity(web-escort-admin, weixin-web, openid);权限仍查 user_app
管理员判定 路由层 auth({ appIds: ADMIN_APP_IDS, roles: ["admin"] });isAdmin(membership) 只认 user_app,无「role 缺失即放行」
POST /user/list 已改为以 user_app 为分页主体(appId=wxapp-escort、status=active),total 语义为「该应用有效成员数」
POST /user/info/batch 复用 buildUserViews 组装 apps,字段不变
POST /user/lock 平台级账号锁定(status.account);与 user_app.status = disabled(应用级停用)是两个维度,不可混用
POST /user/grant Web 后台后续做「管理员授权管理」直接复用,角色白名单 ["user","admin"]

需要遵守的边界:

  • web-escort-admin 已在 APP_REGISTRY 登记为 platform: "weixin"、provider: "weixin-web";appid/secret 配在 conf.json 的 app 块,与小程序账号同处管理
  • 旧 app 字段仅作下游过渡期兼容(health 服务仍在读),前端不能依赖它,登录后只看 apps
  • user_app.status = "disabled" 会立即让该账号失去 Web 后台权限(路由层 403),比锁定账号更精细

五、前端页面设计

5.1 基座

项 设计
request 封装 统一 token 请求头。后端约定 HTTP 状态码恒为 200,业务码在 body.code(api/health/utils/responseUtil.js:7-8)。因此:body.code === 401 时清会话跳登录(不能按 HTTP 401 判断,否则永远不触发);body.code !== 0 时用 body.msg 弹提示(字段名是 msg,不是 message)
会话 Pinia + persistedstate 存 token 与用户信息;刷新不丢。用户身份只读 apps 数组,过渡期才回落 app
路由守卫 全局 beforeEach:无 token → 登录页;登录后拉 /user/userInfo,要求 apps 中存在 appId=web-escort-admin 且 roles 含 admin(过渡期兼容 app["web-escort-admin"]),否则跳 403 并阻止进入
菜单 工作台、订单管理、用户管理、就诊人管理、陪诊师管理(二期:医院管理、培训报名、内容配置)

5.2 页面明细

页面 功能 数据来源
登录页 账号密码 + 微信扫码双入口;扫码支持「绑定微信」模式;登录后校验管理员角色 /user/signin、/user/wechat/qr/url、/user/userInfo
扫码回调页 接收 ?ticket= 或 ?error=;ticket 换 token 后跳工作台,error 按码提示 /user/wechat/qr/exchange
工作台 统计卡片:今日订单、待处理取消申请(cancelStatus=requested)、支付超时未付、近期订单列表 前两项可用现有接口聚合;「支付超时未付」依赖 payment.status 筛选(见 4.2.2),需后端补齐后才能实现
订单列表 筛选:服务状态/取消状态/支付状态/支付渠道/时间段/关键词;分页;状态标签色区分 GET /escort-record(依赖 4.2.2 的筛选补强;未补齐前先只开放已有维度)
订单详情 基础信息、就诊人、陪诊师、支付信息(渠道/实收/流水)、时间线 GET /escort-record/:id、GET .../pay/status
订单操作 状态流转按钮按状态机动态显示;线下支付补录(offline_cash/offline_transfer);取消申请审核;退款核销(POST .../refund/manual);软删除(带二次确认) 现有接口
用户列表 搜索/筛选、状态展示、锁定/解锁 POST /user/list、/user/lock
用户详情 基础信息、名下就诊人、名下订单 /user/userInfo + GET /health-profile?userId= + GET /escort-record?userId=
就诊人列表 按归属用户筛选;显示归属用户昵称/手机号 GET /health-profile
就诊人编辑 新建/编辑(新建时选择归属用户)、删除(二次确认) POST/PUT/DELETE /health-profile
陪诊师列表 分页/筛选、新增/编辑表单、启用/停用 新增 /employee 系列
培训报名 报名列表(只读展示,审核闭环二期) GET /training-application

5.3 交互约束

  • 所有资金相关操作(支付补录、退款核销)必须二次确认,并展示订单当前支付状态
  • 状态流转按钮严格按后端状态机渲染,前端不做后端会拒绝的操作入口
  • 表单校验与服务目录对齐:schedule.duration、payment.totalFee 由后端按 api/health/resource/services.js 重新派生,前端相应字段只读展示

六、实施前确认

  • 初始管理员账号已创建:手机号 13800000000、密码 Escort@2026,授权 web-escort-admin(见 2.4)
  • 本地服务可连:user :9010、health :9004 均在监听
  • 两端服务需重启才能加载本次后端改动(当前由 node index.js 直接启动,无热重载)
  • 微信扫码需填写 conf.json 中 app["web-escort-admin"] 的 appid/secret(开放平台网站应用),并把回调域名配到微信后台

七、交付顺序

  1. 后端(已完成):Employee CRUD + 订单列表筛选补强 + 用户列表筛选/批量/锁定 + 微信扫码登录
  2. 前端基座:模板落地、request/会话/路由守卫、登录页(密码 + 扫码 + 回调页)
  3. 订单管理(列表 → 详情 → 操作)
  4. 就诊人管理、用户管理
  5. 陪诊师管理
  6. 工作台

每步完成后浏览器验证,接口联调基于 dev proxy 直连本地服务。