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

260 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 陪诊 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`,幂等,可重复执行用于重置密码。
```bash
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"]`:
```json
"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` 重新派生,前端相应字段只读展示
## 六、实施前确认
- [x] 初始管理员账号已创建:手机号 `13800000000`、密码 `Escort@2026`,授权 `web-escort-admin`(见 2.4)
- [x] 本地服务可连: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 直连本地服务。