18 KiB
陪诊 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 |
扫码链路:
- 前端
GET /user/wechat/qr/url→ 返回二维码地址与一次性 state(5 分钟有效) - 微信回调
GET /user/wechat/qr/callback?code=&state=:校验 state(用后即删)→ 用 code 换取 openid / unionid - 账号匹配顺序:本应用
user_identity(web-escort-admin, weixin-web, openid)→ 按unionid跨应用 → 旧字段app["web-escort-admin"].wxopenid兜底 - 必须存在
user_app(appId=web-escort-admin、status=active、roles 含admin),否则直接 302 回前端并带error=forbidden - 成功则生成 60 秒有效的一次性 ticket,302 到
${webOrigin}/auth/wechat-callback?ticket=... - 前端
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)兼容。
落地动作:
- 复制 StarterKit 到
ui/web_escort_admin - 清理 demo 页面(admin/dashboard、admin/icons、多余的 auth 变体),保留 vertical 布局、sign-in、403/404/500 错误页
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(开放平台网站应用),并把回调域名配到微信后台
七、交付顺序
- 后端(已完成):Employee CRUD + 订单列表筛选补强 + 用户列表筛选/批量/锁定 + 微信扫码登录
- 前端基座:模板落地、request/会话/路由守卫、登录页(密码 + 扫码 + 回调页)
- 订单管理(列表 → 详情 → 操作)
- 就诊人管理、用户管理
- 陪诊师管理
- 工作台
每步完成后浏览器验证,接口联调基于 dev proxy 直连本地服务。