260 lines
18 KiB
Markdown
260 lines
18 KiB
Markdown
# 陪诊 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 直连本地服务。
|