From 762bd0e7da27db3dea2c9e1ac59344b07af758c8 Mon Sep 17 00:00:00 2001 From: lik Date: Fri, 6 Nov 2026 19:54:17 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=B3=A8=E5=86=8C=E9=99=AA=E8=AF=8A?= =?UTF-8?q?=20Web=20=E5=90=8E=E5=8F=B0=E5=AD=90=E6=A8=A1=E5=9D=97=E5=B9=B6?= =?UTF-8?q?=E8=A1=A5=E5=85=85=E7=AE=A1=E7=90=86=E7=AB=AF=E6=96=B9=E6=A1=88?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 ui/web_escort_admin 子模块;补充陪诊后台实施方案与陪诊师端同步改造清单;用户多应用方案登记 web-escort-admin 应用。 --- .gitmodules | 3 + doc/escort-admin-sync-plan.md | 790 ++++++++++++++++++++++++++++++++++ doc/user-multi-app-plan.md | 16 +- doc/web-escort-admin-plan.md | 259 +++++++++++ ui/web_escort_admin | 1 + 5 files changed, 1068 insertions(+), 1 deletion(-) create mode 100644 doc/escort-admin-sync-plan.md create mode 100644 doc/web-escort-admin-plan.md create mode 160000 ui/web_escort_admin diff --git a/.gitmodules b/.gitmodules index fd0e5c4..f2511fb 100644 --- a/.gitmodules +++ b/.gitmodules @@ -16,3 +16,6 @@ [submodule "ui/taroapp_escort"] path = ui/taroapp_escort url = http://gitea.huashengtec.com/xJourney/taroapp_escort.git +[submodule "ui/web_escort_admin"] + path = ui/web_escort_admin + url = http://gitea.huashengtec.com/xJourney/web_escort_admin.git diff --git a/doc/escort-admin-sync-plan.md b/doc/escort-admin-sync-plan.md new file mode 100644 index 0000000..08d1859 --- /dev/null +++ b/doc/escort-admin-sync-plan.md @@ -0,0 +1,790 @@ +# 陪诊师端(wxapp_escort_admin)功能同步改造清单 + +> 分析日期:2026-11-06 +> 分析基准:`api/health/routes/index.js`(接口能力)、`ui/wxapp_escort`(用户端已实现功能)、`ui/wxapp_escort_admin`(陪诊师/管理端现状) +> 本文只做差距分析与改动项整理,不包含代码实现。 +> 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 定为档案锚定且无归属可留空。 + +## 一、结论摘要 + +1. **这个端实际同时承载「管理员」和「陪诊员」两种身份,但代码默认按管理员工作。** 订单列表、首页统计都调用 `GET /health/escort-record`(要求管理员),陪诊员登录后会直接 403;专门给陪诊员用的 `GET /health/escort-record/attendant` 已封装却从未使用。 +2. **「新增预约」目前只能给管理员本人下单。** 后端 `createRecord` 强制 `userId = token 用户`,且就诊人档案必须属于该用户;前端却允许选择任意客户的档案,选到客户档案会提示「就诊人档案不存在」。 +3. **订单支付补录只支持「全额已支付/未支付」,且已收款状态显示误导。** 编辑页 `paymentLocked` 已对 `partial/paid/refunding/refunded` 四种状态锁定且保存时不回传支付字段,不存在误改回未支付的风险;但表单会把它们回填显示为「未支付」,没有部分支付补录能力,手工标记「线上微信已支付」还会被后端拒绝。 +4. **订单列表的分页、筛选、统计都是前端按当前页计算的。** `hasMore` 计算后恒为 `false`,上拉加载永远不会触发;状态筛选只对已加载的当前页生效。 +5. **多个接口能力尚未接入管理端:** 陪诊员本人订单、支付查单、订单软删除、培训报名列表、医院库 CRUD、AI 语音/图片识别、AI 快捷问题、服务协议/服务指南等内容页。 +6. **健康档案缺少「所属用户」概念。** 管理端新建档案不写 `userId`,生成的档案无法用于任何客户订单;客户详情页的路由还指向一个不存在的页面。 +7. **建议顺序:先补后端 3 个能力(角色查询、陪诊员订单列表口径、管理员代客下单),再改前端。** 否则前端只能做「隐藏入口」,无法真正支撑陪诊员日常使用。 + +## 二、优先级定义 + +| 优先级 | 定义 | 典型事项 | +| --- | --- | --- | +| P0 | 不修则陪诊员端无法正常使用,或会产生错误数据、资金/权限风险 | 角色识别、订单列表数据源、代客下单、患者信息兜底 | +| P1 | 影响日常操作效率、信息完整性或数据一致性 | 取消申请闭环、支付信息补全、支付补录与锁定、订单表单规则对齐、档案归属、客户详情、培训/医院管理 | +| P2 | 体验补齐、内容页、非核心管理能力 | AI 语音/图片、帮助页、个人资料编辑、隐私展示、榜单页 | + +## 三、关键现状 + +### 3.1 角色与权限 + +| 身份 | 判定依据 | 可访问的核心接口 | 当前管理端表现 | +| --- | --- | --- | --- | +| 管理员 | `user.app["wxapp-escort-admin"].role` 含 `admin`,或 Employee 在职且 `role=admin`(`api/health/utils/permissions.js:31-45`、`:83-98`) | `GET /escort-record`、档案管理、医院写接口、培训报名列表、退款查单、删除订单 | 当前所有页面默认按该身份工作 | +| 陪诊员 | Employee `status=active` 且 `role=attendant`(`api/health/utils/permissions.js:53-68`、`:83-98`) | `GET /escort-record/attendant`、`GET /escort-record/:id`(仅本人名下)、`PATCH .../status`(仅本人名下)、`GET .../pay/status`(仅本人名下) | 订单列表 403;档案接口 403;没有角色感知 | +| C 端用户 | token 用户本人 | `/escort-record/my`、`/health-profile/mine`、支付/取消等 | 不在本端范围 | + +关键事实: + +- `GET /health/escort-record` 已挂 `requireAdmin`(`api/health/routes/index.js:96`),陪诊员不可用。 +- `GET /health/escort-record/attendant` 只要求登录(`api/health/routes/index.js:94`),但返回结构缺少 `total/counts`,且没有过滤软删除、已取消和支付窗口(`api/health/handler/escort_record.js:319-339`)。 +- 健康档案管理接口全部要求管理员(`api/health/routes/index.js:124-128`),陪诊员在订单详情里按 `profileId` 拉档案会 403。 +- 管理员身份已可从登录响应的 `apps` 判定(`api/health/utils/permissions.js:44-76` 同口径),但陪诊员身份仍需员工档案查询,且管理端尚未接入,页面无法按角色切换数据源与操作按钮。 + +### 3.2 订单状态与支付口径 + +| 维度 | 取值 | 说明 | +| --- | --- | --- | +| 服务状态 `status` | `pending` / `confirmed` / `in_progress` / `completed` | 只描述服务生命周期,不含取消;`completed` 为终态 | +| 取消状态 `cancelStatus` | `none` / `requested` / `cancelled` | 与 `status` 解耦;展示状态优先取 `cancelStatus` | +| 支付状态 `payment.status` | `unpaid` / `partial` / `paid` / `refunding` / `refunded` | 已支付/部分支付/退款中/已退款受后端保护 | +| 支付渠道 `payment.payChannel` | `online_wechat` / `offline` | 用户下单时的选择;历史订单缺失按 `offline` 解释 | +| 实际收款方式 `payment.method` | 空串 / `online_wechat` / `offline_cash` / `offline_transfer` | 线下收款由平台补记;线上微信只能由支付回调写入 | +| 支付窗口 `paymentWindowEnd` | ISO 时间 / `null` | 由后端按创建时间与微信支付配置派生;列表/详情用于判断「支付已超时」 | + +后端关键规则: + +- 状态迁移只允许 `pending → confirmed → in_progress → completed`,`completed` 不可再变(`api/health/utils/record_state.js:12-25`)。 +- 取消迁移只允许 `none → requested/cancelled`、`requested → cancelled`(`api/health/utils/record_state.js:12-25`)。 +- 已收款订单禁止改支付状态、实收金额和总金额(`api/health/handler/escort_record.js:488-504`)。 +- 手工标记「线上微信 + 已支付」必须存在支付流水,否则返回 400(`api/health/handler/escort_record.js:506-516`)。 +- 存在未支付流水时禁止改价(`api/health/handler/escort_record.js:560-575`)。 +- 管理员/陪诊员取消时,未确认且未收款会物理删除;其余进入 `cancelStatus=cancelled`,已收款自动进入退款(`api/health/handler/escort_record.js:745-811`)。 +- 删除订单仅管理员可用,且为软删除(`api/health/handler/escort_record.js:830-834`)。 + +### 3.3 服务目录与排期 + +服务目录 `api/health/resource/services.js` 是预约规则的唯一事实源: + +- `service.id / title / price / areas` +- `service.booking.advanceDays`:至少提前预约天数 +- `service.booking.durationMinutes`:标准时长 +- `service.booking.sessions[]`:可预约时段 +- `service.booking.requiresAddress`:是否需要收货地址(跑腿/买药) + +后端下单/改期会忽略客户端提交的 `schedule.duration` 和 `payment.totalFee`,统一按服务目录重新派生并校验(`api/health/handler/escort_record.js:166-219`、`:367-390`、`:589-603`)。管理端表单需要按同一份目录渲染,否则会出现「前端能填、后端拒绝」。 + +### 3.4 关键字段 + +订单 `escort_record` 主要字段: + +| 分组 | 字段 | +| --- | --- | +| 归属 | `userId`、`healthProfileId`、`deletedAt` | +| 就诊人快照 | `patient.name/mobile/sex/birth` | +| 服务 | `escort.serviceId/serviceName/sexRequirement` | +| 陪诊员 | `attendant.id/name/sex/mobile` | +| 医院 | `hospital.province/name/address/department/doctor/medicalRecordNo` | +| 排期 | `schedule.date/startTime/endTime/duration` | +| 费用 | `payment.totalFee/paidFee/method/payChannel/paymentRecordId/status` | +| 备注 | `notes.patientNote/escortNote/medicalSummary` | +| 问诊 | `inquiry.medicalHistory/demand` | +| 收货 | `shippingAddress.recipientName/mobile/address` | +| 取消 | `cancelStatus/cancelReason/cancelRequestedAt/cancelledAt` | +| 元数据 | `meta.createtime/updatetime`、改期审计 `schedule.scheduleUpdatedAt` | + +健康档案 `health_profile` 主要字段: + +- `userId`(所属用户,可为空) +- `profile.name/mobile/sex/birth/idnumber` +- `location.country/province/city/district/address` +- `health.height/weight/bloodType/remark` + +## 四、接口覆盖矩阵 + +### 4.1 health 服务 + +图例:✅ 已封装且已使用;⚠️ 已封装未使用;❌ 未封装。 + +| 接口 | 管理端 `utils/api.js` | 当前使用情况 | 结论 | +| --- | --- | --- | --- | +| `GET /health/escort-record` | ✅ | 首页、订单列表、档案详情 | 管理员可用,陪诊员 403 | +| `GET /health/escort-record/attendant` | ✅ | 未使用 | 陪诊员主列表应改用它 | +| `GET /health/escort-record/my` | ✅ | 未使用 | 可选:查看本人在 C 端的订单 | +| `GET /health/escort-record/:id` | ✅ | 订单详情、编辑回填 | 需按角色控制可编辑范围 | +| `POST /health/escort-record` | ✅ | 新增预约 | 只能给 token 用户本人下单 | +| `PUT /health/escort-record/:id` | ✅ | 编辑订单 | 管理员全字段;陪诊员仅部分字段 | +| `PATCH /health/escort-record/:id/status` | ✅ | 列表、详情 | 已使用,流程基本正确 | +| `DELETE /health/escort-record/:id` | ✅ | 未使用 | 缺管理员「删除订单」入口 | +| `POST /health/escort-record/:id/pay` | ❌ | — | 仅订单本人可发起,管理端不适用 | +| `GET /health/escort-record/:id/pay/status` | ❌ | — | 建议补:管理员/陪诊员可查支付结果 | +| `POST /health/escort-record/:id/refund/query` | ✅ | 订单详情 | 已使用,仅管理员 | +| `GET /health/health-profile` | ✅ | 档案列表、订单选档案 | 管理员专属 | +| `GET /health/health-profile/:id` | ✅ | `patient-info` 组件 | 管理员专属;陪诊员 403 | +| `POST/PUT/DELETE /health/health-profile` | ✅ | 档案新增/编辑/删除 | 管理员专属 | +| `GET /health/training-application` | ❌ | — | 缺培训报名管理页 | +| `GET /health/hospital`、`GET /health/hospital/:id` | ❌ | — | 缺医院选择/详情 | +| `POST/PUT/DELETE /health/hospital` | ❌ | — | 缺医院维护页 | +| `GET /health/service` | ✅ | 订单编辑服务下拉 | 已使用 | +| `GET /health/agreement` | ✅ | 未使用 | 缺服务协议页 | +| `GET /health/hospital-info` | ✅ | 未使用 | 缺医院信息页 | +| `GET /health/hospital-ranking` | ✅ | 未使用 | 缺医院榜单页 | +| `GET /health/department-rankings` | ✅ | 未使用 | 缺科室榜单页 | +| `GET /health/ai-quick-questions` | ✅ | 未使用,页面写死 | 应改为接口下发 | +| `POST /health/ai/asr` | ❌ | — | AI 页缺语音输入 | +| `POST /health/ai/ocr` | ❌ | — | AI 页缺图片识别 | +| `GET /health/attendant`、`/health/attendant/:id` | ❌ | — | 公开公示接口;不能直接用于派单 | + +### 4.2 user 服务 + +| 接口 | 管理端 `utils/api.js` | 当前使用情况 | 结论 | +| --- | --- | --- | --- | +| `POST /user/wxsignin` | ✅ | `app.js` 静默登录、设置页弹窗 | 弹窗口径与 C 端不一致,见 P1-10 | +| `POST /user/signout` | ✅ | 设置页退出 | 已使用 | +| `POST /user/update` | ✅ | 未使用 | 缺个人资料编辑 | +| `POST /user/userInfo` | ✅ | 未使用 | 可用于刷新当前用户 | +| `POST /user/list` | ✅ | 客户列表 | 后端未支持关键词/用户ID筛选,前端只过滤当前页 | +| `POST /user/wxgetphonenumber` | ✅ | 未使用 | 登录弹窗应改用手机号 code | + +### 4.3 C 端功能对照 + +| C 端功能 | C 端位置 | 管理端现状 | 同步动作 | +| --- | --- | --- | --- | +| 服务列表/详情/下单 | `pages/home/index`、`pages/escort/itemlist|itemdetail|itemorder` | 仅订单编辑里选服务 | 表单按服务目录渲染;补医院选择、性别要求、收货地址、支付渠道 | +| 预约记录 | `pages/escort/recordlist` | `pages/order/index` | 补角色数据源、服务端筛选、分页、支付/取消状态 | +| 预约详情 | `pages/escort/recorddetail` | `pages/order/orderDetail` | 补取消原因、支付窗口、实收金额、收货地址、改期审计 | +| 就诊人 | `pages/health/profilelist|profileedit` | `pages/healthprofile/*` | 补所属用户、搜索、分页、校验、隐私展示 | +| 培训报名 | `pages/train/index|apply` | 无 | 新增管理端报名列表 | +| AI 助手 | `pages/ai/aichat` | `pages/ai/index` | 补语音/图片识别、接口快捷问题 | +| 我的/资料 | `pages/mine/mine|profileedit` | `pages/me/index`、`pages/set/index` | 补资料编辑;设置页占位项落地或移除 | +| 协议/指南/关于/联系 | `pages/escort/agreement|guide`、`pages/mine/about|contact` | 无 | 可选补齐内容页 | +| 医院选择 | `components/hospital-select` + `app.loadHospitals()` | 手填医院名 | 补医院库选择与地址回填 | +| 陪诊师公示 | API 已有,C 端未落页面 | 无 | 管理端可选做预览,不用于派单 | + +## 五、具体改动项 + +### P0-1 角色识别与权限分层 + +**现状** + +- 管理端没有角色状态,`pages/home`、`pages/order/index`、`pages/healthprofile` 都默认当前账号是管理员。 +- 陪诊员登录后调用 `GET /escort-record` 会 403;订单详情里的 `patient-info` 调 `GET /health-profile/:id` 也会 403。 +- `GET /escort-record/attendant` 已在 `utils/api.js` 封装,但没有任何页面调用。 +- 后端没有「当前账号的员工身份」查询接口;`permissions.js` 里的角色判定只在服务端使用。 + +**目标** + +- 管理员身份无需新增接口:登录响应已带 `apps: [{ appId, roles, status }]`(`api/user/handler/users.js:178-227`、`:255-261`),前端按 `apps` 中 `appId ∈ {wxapp-escort-admin, web-escort-admin}` 且 `roles` 含 `admin`、`status !== 'disabled'` 判定,与 `api/health/utils/permissions.js:44-76` 同口径(注意 `web-escort-admin` 也算管理员)。 +- 陪诊员身份仍需服务端查员工档案:新增 `GET /health/employee/me`(登录态,只返回员工档案 `role/employeeNo/profile`,不重复返回 admin 判定),或在 `POST /user/userInfo` 响应中附带。 +- 前端登录后缓存 `role`,提供统一的 `canAdmin` / `canAttendant` 判断。 +- 按角色切换:订单数据源、首页统计、档案/客户/医院/培训入口、订单详情操作按钮、退款查单/删除按钮。 +- 陪诊员只显示本人名下订单;管理员保留全量能力。 + +**涉及** + +- 后端:`api/health/routes/index.js`、`api/health/handler/employee.js` +- 前端:`app.js`、新增 `utils/role.js`、`pages/home/*`、`pages/order/*`、`pages/healthprofile/*`、`pages/customer/*`、`pages/set/*` + +**依赖**:仅陪诊员身份需后端员工档案接口(B1 已收窄为只查员工档案)。 + +### P0-2 陪诊员订单列表数据源 + +**现状** + +- `pages/order/index.js:198-240` 固定调用 `API.escort.getAllRecords`,参数写死 `status: 'pending,confirmed,in_progress,completed'` 和 `includeCancelled: 1`。 +- `getAllRecords` 路由要求管理员(`api/health/routes/index.js:96`),陪诊员无法使用。 +- `getAttendantRecords` 返回结构只有 `records`,没有 `total`、`counts`、`paymentWindowEnd`,也没有过滤软删除和已取消(`api/health/handler/escort_record.js:319-339`、`api/health/models/schema/escort_record.js:360-375`)。 + +**目标** + +- 管理员走 `GET /escort-record`,陪诊员走 `GET /escort-record/attendant`,页面按角色选择。 +- 后端补齐陪诊员列表口径:支持 `status` 多值、`cancelStatus`、`includeCancelled`、`page/pageSize`、返回 `total` 与 `counts`,并补 `paymentWindowEnd`。 +- 列表页角标/统计与管理员口径一致。 + +**涉及** + +- 后端:`api/health/handler/escort_record.js`、`api/health/models/schema/escort_record.js` +- 前端:`utils/api.js`、`pages/order/index.js/wxml`、`pages/home/index.js` + +**依赖**:后端陪诊员列表增强。 + +### P0-3 管理员代客下单 + +**现状** + +- `createRecord` 强制 `userId = ctx.state.user._id`(`api/health/handler/escort_record.js:333`),并要求 `healthProfileId` 属于该用户(`:352-355`)。 +- 管理端新增预约页可以打开全部档案(`pages/order/orderEdit.js:102-126`),但选到客户档案提交会报「就诊人档案不存在」。 +- 即使提交成功,订单也挂在管理员本人名下,客户在 C 端看不到。 +- 表单里填写的 `payment.totalFee`、`schedule.duration` 会被后端忽略:总价取服务目录价格,时长/结束时间按服务目录派生(`:367-390`、`:409-414`)。 + +**目标**(已定案:档案锚定归属,见 9.2-1) + +- 后端改为「档案锚定」:管理员建单不传 `userId`(传了也忽略),订单归属取 `healthProfileId` 对应档案的 `profile.userId`;档案有归属则订单带上,无归属则订单 `userId` 留空(schema 非必填),后期由管理员在订单编辑中补归属(`RECORD_FIELDS` 已含 `userId`,无需改后端白名单)。 +- 前端增加「代客下单」流程:先选客户(或从客户详情进入),再选该客户档案;订单价格只读展示服务目录价格;支付状态初始为未支付,线下收款通过编辑页补记。 +- 无归属档案允许选择,但表单明确提示「该档案未关联客户,订单归属留空,可后期补」;创建成功后按是否有归属分别提示,并跳转订单详情。 +- 新增预约携带 `idempotencyKey`(与 C 端 `pages/escort/itemorder.js` 一致),防止连点重复建单;管理端新增预约当前未传该字段。 + +**涉及** + +- 后端:`api/health/handler/escort_record.js` +- 前端:`pages/order/orderEdit.js/wxml`、`pages/customer/detail`(新增)、`pages/healthprofile/profileInfo.js` + +**依赖**:后端管理员代客下单支持;客户列表/详情接口(见 P1-5)。 + +### P0-4 订单详情就诊人信息兜底 + +**现状** + +- `pages/order/orderDetail.wxml:22-28` 只传 `profile-id` 给 `patient-info` 组件,没有传订单里的 `patient` 快照。 +- `patient-info` 组件在 `profile-id` 存在时只调 `API.healthProfile.getProfileById`(`components/patient-info/index.js:43-60`)。 +- 陪诊员调用该接口会 403;档案被删除时也会静默失败,最终患者姓名/电话为空。 +- 后端 `getRecordById` 本身返回完整的 `record.patient` 快照(`api/health/handler/escort_record.js:308-324`)。 + +**目标** + +- 订单详情始终用 `order.patient` 作为兜底展示(姓名、性别、年龄、电话);档案加载成功后再覆盖。 +- 管理员可查看档案完整信息;陪诊员至少能看订单快照里的联系人信息。 +- 可选:后端允许「该订单的陪诊员」读取订单关联档案的脱敏信息,避免陪诊员只能看快照。 + +**涉及** + +- 前端:`pages/order/orderDetail.js/wxml`、`components/patient-info/index.js` +- 后端(可选):`api/health/routes/index.js`、`api/health/handler/health_profile.js` + +**依赖**:无(前端兜底即可);完整档案信息需后端授权。 + +### P0-5 订单列表筛选、分页与统计修正 + +**现状** + +- `pages/order/index.js:198-240` 一次拉取 4 种状态 + 已取消订单,然后在前端按 `displayStatus` 过滤。 +- 统计 `calculateStats` 只统计当前已加载列表;切换状态页签不重新请求,只在本地过滤。 +- `hasMore` 在过滤后被赋值为 `orderList.length < total`,而 `total` 又被覆盖成 `orderList.length`,结果恒为 `false`,`onReachBottom` 永远不会加载下一页。 +- 状态筛选未使用后端支持的 `status` / `cancelStatus` / `includeCancelled` / `keyword` 参数(`api/health/handler/escort_record.js:249-313`)。 +- 「待取消」页签没有列表级操作入口,只有详情页能处理。 + +**目标** + +- 每个页签使用服务端筛选: + - 全部:`includeCancelled=1` + - 待确认:`status=pending` + `cancelStatus=none` + - 待取消:`cancelStatus=requested` + - 已确认:`status=confirmed` + `cancelStatus=none` + - 进行中:`status=in_progress` + - 已完成:`status=completed` + - 已取消:`cancelStatus=cancelled` +- 使用后端返回的 `total` 判断 `hasMore`;上拉加载下一页;下拉刷新重置页码。 +- 页签计数使用后端聚合;当前 `findRecordPage` 只返回 `counts.all/ongoing`(`api/health/models/schema/escort_record.js:284-300`),需要扩展为各状态计数,或由前端并行请求各页签的总数。 +- 「待取消」卡片增加「同意取消」快捷操作;取消/确认后刷新当前列表与统计。 +- 接入已支持的订单搜索:`keyword` 可匹配就诊人姓名/电话、陪诊员姓名、医院名、订单ID(`api/health/models/schema/escort_record.js:298-311`);另有 `userId/healthProfileId/appointmentDate/startDate/endDate/paymentStatus/payChannel` 可用(`:234-313`),无需后端改造。 + +**涉及** + +- 前端:`pages/order/index.js/wxml` +- 后端:`api/health/models/schema/escort_record.js`(仅各状态计数需扩展) + +**依赖**:各状态计数(B9);订单搜索已就绪。 + +### P1-1 取消申请闭环 + +**现状** + +- 详情页能识别 `cancelStatus=requested` 并显示「同意取消」(`pages/order/orderDetail.js:174-179`),但: + - 不显示 `cancelReason`、`cancelRequestedAt`、`cancelledAt`; + - 列表页「待取消」卡片没有处理入口; + - 管理员直接取消时没有填写取消原因的入口(后端支持 `reason`,会截断 200 字,`api/health/handler/escort_record.js:652`); + - 取消成功后不区分「物理删除」和「进入已取消」,列表不会自动移除已删除订单。 +- 后端对管理员取消已完成订单会拒绝(`:763-766`),前端按钮已隐藏,但缺少提示文案。 + +**目标** + +- 详情页增加「取消信息」区块:申请原因、申请时间、取消时间、当前处理状态。 +- 待取消订单在列表/详情都提供「同意取消」;管理员额外提供「拒绝并保留订单」需要后端新增状态(当前没有 `rejected`,暂不做)。 +- 管理员取消时可选填原因;确认弹窗说明「未确认且未收款将直接删除订单,已收款将进入退款」。 +- 取消成功后按后端 `data.deleted` 决定返回列表或刷新详情;列表页删除对应卡片。 + +**涉及** + +- 前端:`pages/order/index.js/wxml`、`pages/order/orderDetail.js/wxml` +- 后端:无需新增(拒绝取消需要新增状态,暂不在范围) + +**依赖**:无。 + +### P1-2 支付/退款信息补全 + +**现状** + +- 订单详情展示 `payment.status`、`payChannel`、`method`,但缺少 `paidFee`、支付窗口、是否超时、支付流水状态。 +- 管理端 API 未封装 `GET /escort-record/:id/pay/status`,无法主动查单;该接口对管理员/陪诊员均可用(`api/health/handler/payment.js:656-663`)。 +- 退款查单已有按钮,但仅 `payment.status === 'refunding'` 且 `payment.method === 'online_wechat'` 时显示(`pages/order/orderDetail.js:143-186`);退款失败/异常时没有入口查看详情。 + +**目标** + +- 费用区补充:应收、实收、支付渠道、实际收款方式、支付状态、支付窗口截止时间、是否超时。 +- 增加「查询支付状态」按钮(`payChannel=online_wechat` 且未支付/退款中时),调用 `GET .../pay/status`,刷新详情。 +- 明确区分「未支付」「部分支付」「已支付」「退款中」「已退款」,与 C 端文案一致。 +- 退款查单按钮保持管理员可见;陪诊员隐藏。 + +**涉及** + +- 前端:`utils/api.js`、`pages/order/orderDetail.js/wxml` +- 后端:无 + +**依赖**:无。 + +### P1-3 订单编辑与用户端规则对齐 + +**现状** + +- 管理端订单编辑只有:省份、医院名称(手填)、科室、医生、日期、开始时间、服务名称、费用、是否已支付、支付方式、病历、诉求、备注(`pages/order/orderEdit.wxml:38-144`)。 +- 缺少:医院地址、病历号、性别要求、收货地址、支付渠道、服务目录的预约规则。 +- 日期可选今天起任意日期,时间可选任意时刻;后端会按 `advanceDays`、`sessions` 校验并拒绝(`api/health/handler/escort_record.js:176-219`)。 +- `schedule.duration` 固定写 60(`pages/order/orderEdit.js:430-433`),后端会忽略并按服务目录重算。 +- 新建时费用输入框可编辑,但后端固定取服务价格。 +- 编辑时未按角色限制字段;陪诊员提交支付/费用字段会被后端过滤或直接 400。 + +**目标** + +- 服务选择后加载该服务的 `areas`、`booking.advanceDays`、`sessions`,日期最小值为今天 + `advanceDays`,开始时间使用半小时档位(与 C 端 `buildTimeSlots` 一致)。 +- 医院改为从 `GET /health/hospital` 选择(可按省份/关键词),选中后回填 `name/address`;保留「其他医院」手填入口。 +- 增加 `hospital.address`、`hospital.medicalRecordNo`、`escort.sexRequirement`(不限/男/女)、`shippingAddress`(当 `booking.requiresAddress` 为 true 时展示)。 +- 新建时费用改为只读展示服务目录价格;编辑时管理员可改价,但受「已收款/在途流水」锁定。 +- 增加 `payment.payChannel`(线上微信/线下支付)选择;切换规则与后端一致(仅未支付、待确认/已确认、未申请取消)。 +- 按角色控制可编辑字段:陪诊员只保留服务执行相关字段(医院/排期/备注/病历/诉求),隐藏费用、支付、归属、陪诊员分配。 +- 移除或忽略无效的 `duration` 提交;排期以后端返回为准。 + +**涉及** + +- 前端:`pages/order/orderEdit.js/wxml`、`utils/api.js`、`components/hospital-select`(可从 C 端复用/适配) +- 后端:无(现有校验已足够) + +**依赖**:公共医院列表接口。 + +### P1-4 健康档案归属、检索与校验 + +**现状** + +- 管理端新建档案不设置 `userId`(`pages/healthprofile/profileInfo.js:180-201`),生成的档案没有归属用户,无法用于任何客户订单。 +- 列表只取最近 20 条,无分页、无搜索(`pages/healthprofile/index.js:28-54`)。 +- 快捷菜单「全部档案」「患者查询」「就诊记录」均为占位提示(`:56-72`)。 +- 表单只校验姓名/电话非空(`pages/healthprofile/profileInfo.js:170-178`),不校验手机号格式、身份证格式、出生日期范围、身高体重范围;后端管理端创建接口也没有做这些校验(`api/health/handler/health_profile.js:253-261`)。 +- 列表展示 `item.profile.birth` 时未对 `profile` 缺失做兜底(`pages/healthprofile/index.js:37`)。 + +**目标** + +- 档案增加「所属用户」:新建时必选客户(管理员自己的档案可选择本人);编辑时展示归属,不允许随意转移(后端当前允许改 `userId`,建议收紧)。 +- 列表分页、搜索(姓名/手机号)、排序(最近更新):后端已支持(`api/health/handler/health_profile.js:97-115` 的 `userId/name/mobile/sortBy` + 分页),前端接入即可。 +- 展示归属用户姓名/手机号:用 `POST /user/info/batch` 批量取(`api/user/routes/index.js:35`,单次上限 100),不要逐行查询。 +- 实现快捷菜单:全部档案、患者查询(姓名/手机号)、就诊记录(按 `healthProfileId` 查订单)。 +- 表单校验与 C 端对齐:手机号 `1[3-9]\d{9}`、身份证 18 位、出生日期 1900-01-01 至今天、身高 30–250、体重 2–300;提交前给出字段级错误。 +- 详情增加身份证号(可脱敏/展开)、地区、血型、备注;删除时提示「已关联订单仍保留订单快照」。 +- 陪诊员不展示档案管理入口,仅从订单快照查看联系人。 + +**涉及** + +- 前端:`pages/healthprofile/index.js/wxml`、`pages/healthprofile/profileInfo.js/wxml`、`pages/order/orderEdit.js`、`utils/api.js` +- 后端(建议):管理端创建/更新档案时校验 `userId` 存在且属于 C 端用户;更新时禁止转移归属 + +**依赖**:客户选择(P1-5)。 + +### P1-5 客户详情与客户搜索 + +**现状** + +- `pages/customer/index.js:215-220` 点击客户跳转 `/pages/customer/detail?id=...`,但该页面不存在(目录下只有 `index.*`)。 +- `POST /user/list` 后端已升级:以 `user_app` 为分页主体(语义为「`wxapp-escort` 有效成员」),支持 `keyword`(姓名/手机/邮箱/拼音)、`accountStatus`、`startDate/endDate`,并返回 `total/page/pageSize`(`api/user/handler/users.js:637-712`);前端已传 keyword,只需改为服务端搜索并使用 `res.data.total`。 +- `GET /escort-record?userId=` 与 `GET /health-profile?userId=` 均已支持(`api/health/models/schema/escort_record.js:264`、`api/health/handler/health_profile.js:97-115`),客户详情页所需查询无需后端改造。 +- 当前页面仍有:`total` 取 `data.users.length` 导致 `hasMore` 恒 `false`(`pages/customer/index.js:139-167`),属纯前端修复。 + +**目标** + +- 新增客户详情页:用户资料、健康档案列表、订单列表、快捷「代客下单」「新增档案」「拨打电话」。 +- 客户列表分页使用后端 `total`;搜索改为服务端 `keyword`(姓名/手机);按 `userId` 精确取用户用 `POST /user/info/batch`。 +- 客户详情通过 `userId` 拉档案(`GET /health-profile?userId=`)和订单(`GET /escort-record?userId=`)。 +- 仅管理员可见;陪诊员隐藏入口。 + +**涉及** + +- 前端:`pages/customer/index.js/wxml`、新增 `pages/customer/detail.*`、`app.json`、`utils/api.js` +- 后端:无需改造(列表筛选与按 userId 查询均已具备) + +**依赖**:无。 + +### P1-6 培训报名管理 + +**现状** + +- 报名接口已存在:用户端 `POST /health/training-application`、`GET /health/training-application/mine`;管理端 `GET /health/training-application`(管理员,`api/health/routes/index.js:118-121`)。 +- 管理端没有报名列表页面,`utils/api.js` 也没有封装。 +- 后端列表返回 `applicant.name/mobile/education`、`examMonth`、`course`、`status`、`createtime`,不返回照片/身份证图片(`api/health/handler/training_application.js:20-39`)。 +- 没有「查看材料」「修改报名状态」接口。 + +**目标** + +- 新增管理端报名列表:状态页签(待审核/已联系/已入班/已取消)、分页、按姓名/手机号搜索(后端暂不支持搜索,可先前端过滤当前页)。 +- 列表展示报名人、手机号、学历、考试月份、课程、提交时间、状态。 +- 明确只读;如需审核流转,后端补 `GET /training-application/:id`(含材料)和 `PATCH /training-application/:id/status`。 +- 入口放首页/设置页,仅管理员可见。 + +**涉及** + +- 前端:新增 `pages/training/index.*`、`app.json`、`utils/api.js`、`pages/home/index.js`、`pages/set/index.js` +- 后端(可选):报名详情、状态更新 + +**依赖**:后端状态更新/材料查看(若需要审核闭环)。 + +### P1-7 医院库维护与订单选院 + +**现状** + +- 医院接口已完整:公开列表/详情(`GET /health/hospital`、`/:id`),管理员新增/修改/删除(`POST/PUT/DELETE /health/hospital`,`api/health/routes/index.js:130-135`)。 +- 管理端 `utils/api.js` 完全没有医院接口,也没有医院管理页面。 +- 订单编辑只能手填医院名,无法带出地址、科室、等级,也无法复用医院库。 +- 医院字段:`name/entityName/province/city/address/phone/departments/level`,`pinyin/fudanRank` 由服务端生成(`api/health/handler/hospital.js:14`)。 + +**目标** + +- 新增医院库页面:关键词/省份/主体名称搜索、分页、详情、新增、编辑、删除;仅管理员可写。 +- 表单字段按后端白名单:名称、主体名称、省份、城市、地址、电话、科室(数组)、等级;不要编辑拼音/复旦档位。 +- 订单编辑使用医院库选择器;选中后回填 `hospital.name/address`,支持「其他医院」手填。 +- 可选:用 `GET /health/hospital-info`、`/hospital-ranking`、`/department-rankings` 做医院资料/榜单展示页。 + +**涉及** + +- 前端:`utils/api.js`、新增 `pages/hospital/index|detail|edit.*`、`app.json`、`pages/order/orderEdit.*`、`components/hospital-select` +- 后端:无 + +**依赖**:无。 + +### P1-8 陪诊师派单与在线状态 + +**现状** + +- 订单编辑/详情没有「分配/更换陪诊师」入口;后端管理员可以通过 `PUT /escort-record/:id` 写 `attendant` 字段(`api/health/handler/escort_record.js:463-484`、白名单 `:19-23`),但没有可选的陪诊师列表接口。 +- 公开的 `GET /health/attendant` 返回的是脱敏姓名、`Employee._id`,不含手机号和登录用户 ID;而订单的 `attendant.id` 需要是 `user._id`(`api/health/handler/escort_record.js:110-117`),不能直接复用。 +- 首页「在线/离线」开关只改本地 `data.online`(`pages/home/index.js:91-95`),没有写库;Employee 有 `attendantInfo.isOnline`,但没有对应接口。 +- 陪诊员无法写 `notes.escortNote` / `notes.medicalSummary`:`updateRecord` 对非管理员只允许 `OWNER_NOTE_FIELDS`(`api/health/handler/escort_record.js:29-38`),不含服务记录/就诊摘要。 + +**目标** + +- 后端新增管理员可用的陪诊师列表(含 `userId`、姓名、手机号、性别、服务区域、在职状态),例如 `GET /health/employee?role=attendant&status=active`;不要复用公开公示接口。 +- 订单详情/编辑增加「分配陪诊师」:按性别要求、服务区域筛选;选中后写 `attendant.id/name/sex/mobile`;后端校验该 `userId` 是当前在职陪诊员。 +- 首页在线状态改为读写员工在线状态接口;未能实现前,移除或标注「仅本地展示」。 +- 后端允许陪诊员更新本人订单的 `notes.escortNote` 和 `notes.medicalSummary`(或新增服务记录接口);前端增加服务记录编辑区。 + +**涉及** + +- 后端:`api/health/routes/index.js`、`api/health/handler/employee.js`、`api/health/handler/escort_record.js` +- 前端:`pages/order/orderDetail.*`、`pages/order/orderEdit.*`、`pages/home/index.*`、`utils/api.js` + +**依赖**:员工列表、在线状态、陪诊员字段权限(后端)。 + +### P1-9 首页统计与入口权限 + +**现状** + +- 首页今日收益/今日订单/近 7 日订单都调用 `getAllRecords`(`pages/home/index.js:97-152`),陪诊员 403。 +- 今日收益按 `payment.totalFee` 累加,未支付订单也会计入(`:104-120`)。 +- 快捷入口固定展示「注册用户」「健康档案」「个人信息」等,未按角色隐藏。 +- 近 7 日订单一次取 50 条后前端过滤,数据量大时不准。 + +**目标** + +- 按角色选择数据源:管理员全量,陪诊员本人订单。 +- 收益按 `payment.paidFee` 或「已支付/部分支付」口径统计,排除未支付与已退款。 +- 统计与列表使用服务端筛选/分页;首页只取必要字段。 +- 陪诊员隐藏客户/档案/医院/培训等管理员入口;管理员保留。 +- 今日订单数按 `appointmentDate` 查询,避免前端按时间戳猜日期。 + +**涉及** + +- 前端:`pages/home/index.js/wxml` +- 后端:可选补员工统计接口,避免前端二次聚合 + +**依赖**:P0-1、P0-2。 + +### P1-10 请求层、环境配置与登录口径 + +**现状** + +- `utils/config.js` 是空对象(`export default { baseUrl: '' }`),`utils/request.js` 构造函数写死 `https://api.huashengtec.com`;`utils/api.js` 的 user 接口也写死绝对地址(`utils/api.js:5-10`)。本地调试必须改代码。 +- `utils/request.js` 没有 401 静默重登与重试;C 端 `utils/request.js:24-37` 已有 `recoverUnauthorized`。管理端 token 被轮换后页面只会报错。 +- `pages/ai/index.js:216` 发送 `appId: app.globalData.appId || ''`,但 `app.js` 的 `globalData` 没有 `appId`(`app.js:102-106`)。 +- 设置页登录弹窗用 `phoneNumber` 直传(`pages/set/index.js:112-118`);已有手机号的账号会返回 409「该手机号已注册,请先使用手机号登录后再绑定微信」(`api/user/handler/users.js:375-380`)。 + +**目标** + +- 按 C 端模式补齐 `config.js`:`DEBUG`、`APP_ID`、`BASE_URL`、`USER_BASE_URL`、`WS_BASE_URL`、AI 媒体超时;`request.js`/`chatmsg.js`/`api.js` 全部从配置取值。 +- `request.js` 增加 401 恢复回调,由 `app.js` 注入静默重登;避免与 `ensureLogin` 死锁。 +- `app.js` 补 `appId`,或从 AI 发送参数中移除未定义字段。 +- 登录弹窗改用微信手机号授权 `phoneCode`(与 C 端一致),或直接移除弹窗、统一走静默登录 + 管理员后台开通。 +- 统一错误提示:网络错误、401、403、业务 code 分类展示。 + +**涉及** + +- 前端:`utils/config.js`、`utils/request.js`、`utils/api.js`、`utils/chatmsg.js`、`app.js`、`pages/set/index.js` + +**依赖**:无。 + +### P1-11 订单支付补录与编辑锁定(review 后自 P0 降级) + +**现状**(按当前代码修订) + +- 编辑页已实现已收款锁定:`paymentLocked` 在 `pages/order/orderEdit.js:46` 定义、`:187-192` 按 `partial/paid/refunding/refunded` 计算并 `setData`,wxml 中禁用支付开关/方式选择并显示提示;保存时锁定订单不回传任何 payment 字段(`:508-513`),不存在「把已支付/退款中订单改回未支付」的风险。 +- 剩余问题: + - 显示误导:`loadOrder` 只把 `payment.status === 'paid'` 判为已支付(`:223`),`partial/refunding/refunded` 在开关上回填为「未支付」,虽被锁定但展示不准确; + - 无部分支付补录:`paidFee` 只能等于全额或 0(`:511`),线下只支持全额已支付或未支付; + - 「是否已支付」开关与「支付方式」没有联动:选中 `online_wechat` 再打开已支付,后端会返回「线上微信收款只能由支付回调写入」(`api/health/handler/escort_record.js:506-516`); + - 订单详情缺 `payment.paidFee`、支付窗口与超时状态。 +- 后端支持已核实:对 `unpaid` 订单,管理员写 `offline_cash/offline_transfer` + `paidFee` + `payment.status=partial` 不被任何校验拦截(锁定只在当前状态已收款时生效,`api/health/handler/escort_record.js:486-516`),无需新增后端接口。 + +**目标** + +- 统一支付编辑状态机: + - `partial/paid/refunding/refunded` 时保持现有锁定,并把回填显示改为真实支付状态文案(不再显示「未支付」),附「退款请走取消流程」提示; + - `unpaid` 且存在未支付流水时,锁定总金额(保留现有 `amountLocked`),提示先关单/取消; + - `unpaid` 且无在途流水时,允许管理员补录线下收款:选择 `offline_cash` / `offline_transfer`,填写 `paidFee`,由页面推导 `payment.status`(`0 → unpaid`、`0 < paidFee < totalFee → partial`、`paidFee >= totalFee → paid`); + - 选中 `online_wechat` 时禁止手工标记已支付,并提示「线上支付由微信回调自动入账」。 +- 增加实收金额展示与校验:`0 ≤ paidFee ≤ totalFee`。 +- 保存前做本地校验,避免把必然失败的请求发到后端。 +- 订单详情补 `payment.paidFee`、`paymentWindowEnd`、是否超时、支付流水/退款状态。 + +**涉及** + +- 前端:`pages/order/orderEdit.js/wxml`、`pages/order/orderDetail.js/wxml`、新增 `utils/payment.js`(统一支付文案/状态推导) +- 后端:无需新增接口,按现有规则做前端约束即可 + +**依赖**:无。 + +### P2-1 AI 快捷问题、语音与图片 + +**现状** + +- 管理端 AI 页快捷问题是硬编码的 4 条(`pages/ai/index.js:10-15`);后端已有 `GET /health/ai-quick-questions`,`utils/api.js` 也已封装但未使用。 +- 管理端 `utils/api.js` 没有 `ai.asr` / `ai.ocr`;AI 页没有语音输入和图片识别。 +- C 端已实现实时语音(WS `asr_start/asr_chunk/asr_stop`,失败回退 `POST /health/ai/asr`)和图片 OCR(`POST /health/ai/ocr`)。 + +**目标** + +- 快捷问题改为接口下发,失败时回退本地默认问题。 +- 增加语音输入:优先走 WS 实时识别,失败回退整段识别;识别结果回填输入框,用户确认后发送。 +- 增加图片识别:选择图片 → `ocr` → 文本回填输入框/作为消息发送;沿用 C 端的 `format` 帧与权限提示。 +- 按角色提示:陪诊员无权限时后端会返回「当前账号未绑定在职陪诊员档案」,前端直接展示。 + +**涉及** + +- 前端:`utils/api.js`、`pages/ai/index.js/wxml`、`utils/chatmsg.js` +- 后端:无(接口已存在) + +**依赖**:无。 + +### P2-2 内容与帮助页 + +**现状** + +- 设置页「消息通知」「帮助中心」没有 URL,点击提示「功能开发中」(`pages/set/index.js:15-19`、`:145-158`)。 +- 管理端没有服务协议、服务指南、关于我们、联系我们页面;C 端已有对应页面,接口 `GET /health/agreement`、`GET /health/service` 已存在。 + +**目标** + +- 增加「服务协议」「服务指南」「关于我们」「联系我们」页面;协议/服务内容从接口读取,联系信息用静态配置。 +- 设置页菜单接入真实页面;「消息通知」若无后端能力,先移除或标注「暂无消息」。 +- 仅保留对陪诊师有用的内容,避免把 C 端「合作与入驻」直接搬过来。 + +**涉及** + +- 前端:新增内容页、`app.json`、`pages/set/index.js/wxml`、`utils/api.js` + +**依赖**:无。 + +### P2-3 个人资料编辑 + +**现状** + +- `pages/me/index.js` 只读展示用户资料;设置页「个人资料」跳到该页,不能编辑。 +- `utils/api.js` 已封装 `POST /user/update`,但未使用。 + +**目标** + +- 增加资料编辑:姓名、性别、出生日期、手机号、邮箱、身份证号(按 user 服务允许字段)。 +- 陪诊员可补充员工档案信息?当前没有员工自助更新接口,暂不做;只编辑用户资料。 +- 保存后刷新 `globalData.user` 与页面。 + +**涉及** + +- 前端:`pages/me/index.js/wxml`、新增 `pages/me/profileedit.*`、`utils/api.js`、`app.json` + +**依赖**:无(用户资料接口已存在)。 + +### P2-4 隐私与展示细节 + +**现状** + +- 管理端档案详情展示完整身份证号;列表不展示证件号。 +- 订单详情展示完整订单号;C 端做了脱敏。 +- 陪诊员与管理员看到的信息没有差异。 + +**目标** + +- 列表默认脱敏(手机号中间四位、身份证号中间位);详情可展开查看完整值。 +- 订单号在管理端可保留完整(对账需要),但分享/截图场景建议脱敏。 +- 陪诊员只展示服务必需信息(联系人电话、医院、地址、注意事项),隐藏身份证号、费用明细、退款信息。 +- 统一空态/加载态/错误态。 + +**涉及** + +- 前端:`utils/privacy.js`(可从 C 端复用)、订单/档案页面 + +**依赖**:无。 + +### P2-5 医院信息与榜单页 + +**现状** + +- `GET /health/hospital-info`、`/hospital-ranking`、`/department-rankings` 已封装,但管理端未使用。 + +**目标** + +- 可选做「医院资料/榜单」只读页,供陪诊师了解医院等级、科室排名。 +- 若不做,移除 `utils/api.js` 中未使用的封装,减少误导。 + +**涉及** + +- 前端:`utils/api.js`、新增页面或删除未用 API + +**依赖**:无。 + +### P2-6 陪诊师公示预览 + +**现状** + +- 公开接口 `GET /health/attendant`、`/:id` 已存在,返回脱敏姓名、服务年限、健康证明有效期、培训记录、评价聚合,不含手机号/身份证/证书编号(`api/health/handler/employee.js:75-103`)。 +- 管理端未展示。 + +**目标** + +- 可选做「陪诊师公示预览」,让管理员核对对外展示内容。 +- 不用于派单选择(`id` 是 Employee._id,不是登录用户 ID)。 + +**涉及** + +- 前端:`utils/api.js`、可选页面 + +**依赖**:无。 + +### P2-7 设置页占位与消息通知 + +**现状** + +- 「消息通知」「帮助中心」占位;「清除缓存」会清空 `admin_user_info` 等本地缓存并重置登录态(`pages/set/index.js:198-216`)。 + +**目标** + +- 明确每个菜单的去向;无能力的功能移除,避免「开发中」长期存在。 +- 清除缓存后重新登录并刷新首页,避免停留在无用户状态。 + +**涉及** + +- 前端:`pages/set/index.js/wxml` + +**依赖**:无。 + +### P2-8 健壮性与空态 + +- `pages/healthprofile/index.js:37` 读取 `item.profile.birth` 未兜底 `profile` 缺失。 +- `pages/order/orderDetail.wxml` 直接访问 `order.hospital.name` 等嵌套字段,订单数据不完整时可能渲染异常;建议 JS 侧归一化。 +- `pages/order/index.js` 统计/筛选切换后未重置加载态;失败时 `isLoading` 可能残留。 +- 统一 loading / empty / error / retry 三态,避免空白页。 + +## 六、后端接口缺口(需先补) + +| 编号 | 缺口 | 现状 | 建议 | 影响 | 优先级 | +| --- | --- | --- | --- | --- | --- | +| B1 | 员工档案查询(原「角色查询」已收窄) | 管理员身份已可从登录响应的 `apps` 判定;陪诊员身份需按 userId 查 Employee,无接口 | `GET /health/employee/me` 只返回员工档案 `role/employeeNo/profile` | 陪诊员页面角色判定 | P0 | +| B2 | 陪诊员订单列表口径 | `GET /escort-record/attendant` 无 total/counts、单状态、未过滤软删除/取消、无支付窗口 | 复用管理员列表的过滤/分页/派生逻辑,按 `attendant.id` 限定 | 陪诊员订单列表/首页 | P0 | +| B3 | 管理员代客下单 | `createRecord` 强制 `userId=token 用户`,档案必须属于该用户 | 档案锚定:订单归属取 `profile.userId`,不传/忽略管理员传入的 userId;无归属档案允许下单,`userId` 留空后期补(见 9.2-1) | 新增预约/客户详情 | P0 | +| B4 | 陪诊员读取订单档案 | `GET /health-profile/:id` 要求管理员 | 允许该订单的陪诊员读取关联档案(可脱敏),或提供订单专属档案接口 | 订单详情患者信息 | P0(可选) | +| B5 | 陪诊师列表(派单) | 只有公开脱敏列表,无 userId/手机号 | `GET /health/employee?role=attendant&status=active`(管理员) | 派单/更换陪诊师 | P1 | +| B6 | 陪诊员写服务记录 | `updateRecord` 对非管理员只允许患者备注/病历/诉求 | 允许本人订单写 `notes.escortNote`、`notes.medicalSummary` | 服务记录/就诊摘要 | P1 | +| B7 | 培训报名详情/状态 | 只有列表,无详情/状态更新 | `GET /training-application/:id`(含材料)、`PATCH .../status` | 培训报名管理 | P1 | +| B8 | ~~订单搜索~~(已实现) | `buildRecordFilter` 已支持 keyword(就诊人姓名/电话、陪诊员、医院、订单ID)及 userId/healthProfileId/日期/支付状态筛选(`schema/escort_record.js:234-313`) | 无需改造,前端接入 | 订单列表 | — | +| B9 | 各状态计数 | `counts` 只有 `all/ongoing` | 扩展为各状态 + `cancelRequested` | 订单页签角标 | P1 | +| B10 | 员工在线状态 | 首页开关只改本地 | `PATCH /health/employee/me/online` 或员工更新接口 | 首页在线状态 | P2 | +| B11 | 订单详情软删除过滤 | `getRecordById` 使用 `findById`,未过滤 `deletedAt` | 改用 `findRecordById` 或加 `deletedAt: null` | 删除后的详情/权限一致性 | P1 | +| B12 | ~~用户列表筛选~~(已实现) | `userList` 已按 `user_app` 有效成员分页,支持 keyword/accountStatus/日期并返回 total(`api/user/handler/users.js:637-712`) | 无需改造;按 userId 取用户用 `POST /user/info/batch` | 客户搜索/详情 | — | +| B13 | 管理端档案归属校验 | 管理员创建/更新档案不校验 `userId` 是否存在 | 校验目标用户存在且属于 C 端;更新时禁止转移归属 | 档案归属 | P1 | + +## 七、前端文件级改动清单 + +| 文件/目录 | 改动 | 优先级 | +| --- | --- | --- | +| `app.json` | 增加客户详情、培训、医院、内容页、资料编辑等页面路由 | P0/P1 | +| `app.js` | 增加 `appId`、401 恢复回调、角色加载与全局缓存 | P0 | +| `utils/config.js` | 补 DEBUG/APP_ID/BASE_URL/USER_BASE_URL/WS_BASE_URL/AI 超时 | P1 | +| `utils/request.js` | 从配置取 baseURL;增加 401 重登重试;统一错误 | P1 | +| `utils/api.js` | 补 `getAttendantRecords` 参数/支付查单/删除/培训/医院/AI 媒体/公示接口;user 接口从配置派生 | P0/P1 | +| 新增 `utils/role.js` | 角色读取、`canAdmin/canAttendant`、页面级守卫 | P0 | +| 新增 `utils/order.js` | 统一状态/支付映射、展示状态派生、支付窗口判断 | P1 | +| `pages/home/index.js/wxml` | 角色化数据源、收益口径、入口权限、在线状态 | P0/P1 | +| `pages/order/index.js/wxml` | 角色化列表、服务端筛选、分页修复、待取消操作、支付/取消标识 | P0 | +| `pages/order/orderDetail.js/wxml` | 患者快照兜底、取消信息、支付/退款信息、查支付、删除、分配陪诊师、服务记录 | P0/P1 | +| `pages/order/orderEdit.js/wxml` | 服务目录规则、医院选择、地址/病历号、性别要求、收货地址、支付渠道、支付锁定、角色字段限制 | P0/P1 | +| `pages/healthprofile/index.js/wxml` | 分页/搜索/归属用户、快捷菜单落地 | P1 | +| `pages/healthprofile/profileInfo.js/wxml` | 所属用户、校验、证件号/地区/血型、删除提示 | P1 | +| `pages/customer/index.js/wxml` | 分页修复、服务端搜索、详情跳转 | P1 | +| 新增 `pages/customer/detail.*` | 客户资料 + 档案 + 订单 + 代客下单 | P1 | +| 新增 `pages/training/index.*` | 培训报名列表/状态筛选 | P1 | +| 新增 `pages/hospital/*` | 医院库列表/详情/编辑 | P1 | +| `components/hospital-select` | 从 C 端复用/适配 | P1 | +| `pages/ai/index.js/wxml` | 接口快捷问题、语音/图片识别 | P2 | +| `pages/set/index.js/wxml` | 菜单落地、登录口径、清除缓存后刷新 | P1/P2 | +| `pages/me/index.js/wxml` | 个人资料编辑入口 | P2 | +| 新增内容页 | 协议/指南/关于/联系 | P2 | + +## 八、验收清单(P0) + +- [ ] 管理员登录后能看到全部订单;陪诊员登录后只能看到 `attendant.id = 本人 userId` 的订单,不再出现 403。 +- [ ] 陪诊员订单列表支持状态筛选、分页、上拉加载;所有页签计数正确。 +- [ ] 管理员选择有归属客户的档案创建订单,订单 `userId` 为该客户,客户在 C 端能看到;选择无归属档案可下单,订单 `userId` 留空并提示,后续可通过订单编辑补归属;不再报「档案不存在」。 +- [ ] 订单详情在档案 403/已删除时仍能显示订单快照中的患者姓名、电话、性别、年龄。 +- [ ] 已支付/部分支付/退款中/已退款订单的支付字段在编辑页锁定只读,且显示真实支付状态文案(不再显示「未支付」);线下补录与部分支付的详细验收见 P1-11。 +- [ ] 订单列表不再出现「没有更多了」但实际还有数据的分页问题。 +- [ ] 所有管理员专属接口(全量订单、档案、客户、医院、培训、退款查单、删除)在陪诊员身份下不会出现在界面中。 + +## 九、实施评审结论(2026-11-06,代码级核实) + +**总体结论:P0 计划可实施,且工作量比正文预估更小。** 后端三个缺口(B1/B2/B3)在模型层与 handler 层均有现成基础;实施前需确认 1 个跨服务依赖,注意 2 个实现约束。 + +### 9.1 实施利好(比正文预估更小的改造面) + +- **B3 改造面很小**:`createRecord` 已有完整管理员分支——payChannel 按 method 推导(`escort_record.js:400-407`)、method 白名单(`:416-419`)、attendant 对管理员放行(`:377`);档案归属校验(`:352-355`)与未完成单上限(`:421-423`)都基于 `userId` 变量,放开 userId 后自动正确。幂等键后端已实现(`:337-344`),P0-3 的幂等键要求后端零改动,管理端前端传字段即可。 +- **B1/B5 模型层现成**:`Employee.userId`(`schema/employee.js:31`)、`findByUserId`(`:194`)、`findByRole(role, {page,pageSize,status})`(`:180-183`)、`attendantInfo.isOnline`(`:99`)均已存在,handler 只需薄封装。 +- **B2 复用点明确**:`withPaymentWindow` 是 handler 静态方法(`escort_record.js:125`),attendant 列表增强可直接复用;分页/计数参照 `findRecordPage`(`schema/escort_record.js:283-299`)。 + +### 9.2 实施前需确认 / 注意 + +1. **【已定方案】B3 归属校验采用「档案锚定」,不查用户;无归属档案可下单,userId 留空后期补**(产品已确认):health 服务获取用户的唯一途径是经 user 服务的 `getUserByToken`(`utils/user_service.js`),且其注释明确「user 服务已不再接受按 userId 明文查询,避免凭 userId 冒充他人身份」——为代客下单新开按 userId 查询接口会撞上这条安全设计。故 B3 实施为: + - 管理员建单**不传 userId**(传了也忽略),订单归属取 `healthProfileId` 对应档案的 `profile.userId`;档案有归属则订单带该 userId; + - 档案无归属时**允许下单**,订单 `userId` 留空(schema 非必填,`schema/escort_record.js:28-33`),后期由管理员通过 `PUT /escort-record/:id` 补归属(`RECORD_FIELDS` 已含 `userId`,`handler/escort_record.js:19-23`,后端无需新增能力); + - 实现注意:`createRecord` 的 `userId` 来源从 token 用户改为 `profile.userId || null`; + - 幂等键(`:342`、`:469`)按 `userId: null` 查询可用:`{ userId: null }` 同时匹配字段缺失,唯一索引仍生效,键随机无实际碰撞风险; + - **未完成单上限(`:455-461`)对空 userId 必须跳过校验**:`countUnfinishedRecords(null)` 会统计全部无主订单,第 4 张无主订单起会被「每个用户最多 3 个」全局拦截; + - 留空订单不出现在 C 端「我的预约」(按 userId 查询天然不命中),补归属后客户才可见; + - 档案归属必填(B13/P1-4)不再是代客下单的前置条件,两者解耦。 +2. **tabBar 不能按角色动态切换**:管理端 `app.json` 为静态 3 tab(首页/AI/设置),微信原生 tabBar 无法按角色隐藏;角色化只能在页内做(数据源切换 + 入口隐藏 + 页面守卫),不引入 custom tabBar。P0-1 实施时按此理解。 +3. **路由注册顺序**:新增 `/employee/me` 必须注册在 `/employee/:id` 之前(本文件已有同类注释先例:`:88`、`:154`)。 + +### 9.3 建议实施顺序(两批次) + +- **批次 1(后端,可一次合入)**:B1(`GET /employee/me`)→ B2(attendant 列表增强)→ B3(代客下单,档案锚定方案已定,见 9.2-1)。三项相互独立,均为小改动。 +- **批次 2(前端 P0)**:P0-1 角色层 → P0-2 + P0-5 订单列表 → P0-3 新增预约表单。P0-4(患者快照兜底)无后端依赖,可与批次 1 并行先行。 +- P1 项按 B5/B6/B8/B9/B12 后端缺口到位的节奏排入。 + +## 十、需要产品确认 + +1. 本端定位是「管理员 + 陪诊员」共用,还是只面向陪诊员?这决定管理类入口是否保留。 +2. 管理员「代客下单」已定案为档案锚定、无归属可留空(见 9.2-1);剩余待确认:补归属的入口与核对方式(是否需要防误挂校验)。 +3. 陪诊员是否需要查看患者身份证号、完整费用与退款信息?建议只给服务必需字段。 +4. 培训报名是否需要审核流转(联系/入班/取消),还是只读列表即可? +5. 医院库维护是否放在本端,还是由独立后台维护? +6. 部分支付/线下收款补录是否为必须能力?当前后端支持,但管理端没有界面。 diff --git a/doc/user-multi-app-plan.md b/doc/user-multi-app-plan.md index 9233b62..aa1a12c 100644 --- a/doc/user-multi-app-plan.md +++ b/doc/user-multi-app-plan.md @@ -2,7 +2,7 @@ | 项 | 内容 | |---|---| -| 状态 | 已评审,待确认实施 | +| 状态 | 已实施(P1-P3 完成;P4 未做、P5 部分完成),2026-11-06 按代码回填 | | 日期 | 2026-11-05 | | 范围 | `api/user` 的用户模型、微信登录、鉴权、用户列表;MongoDB 库 `eiot_user` | | 目标 | 一个平台账号可在多个 app / 网站 / 小程序中拥有独立的身份、角色和授权状态 | @@ -210,6 +210,7 @@ import config from "../conf.json" with { type: "json" }; export const APP_REGISTRY = { "wxapp-escort": { platform: "weixin", provider: "weixin-mini" }, "wxapp-escort-admin": { platform: "weixin", provider: "weixin-mini" }, + "web-escort-admin": { platform: "web", provider: "password" }, "ttapp-escort": { platform: "douyin", provider: "douyin-mini" }, "tcm": { platform: "web", provider: "password" }, }; @@ -999,6 +1000,7 @@ for (const user of cursor) { | `doc/wechatpay-plan.md` | 过渡期仍引用 `app`,需在 P5 一并更新 | | `api/health/utils/permissions.js` | 过渡期不改;P5 改读 `user_app` | | `ui/web_tcm/src/stores/tcm_organization.js` | P5 改读 `apps[].config` 或 `apps[].orgId` | +| `api/user/scripts/create_web_admin.js` | Web 后台管理员初始化脚本:P2 前写旧 `app`,P4 后改写入 `user_app`(`appId=web-escort-admin`) | --- @@ -1040,4 +1042,16 @@ for (const user of cursor) { --- +## 13. 与陪诊业务(管理员代客下单)的联动决策 + +`doc/escort-admin-sync-plan.md` 的 B3(管理员代客下单)已定案采用「档案锚定」归属,与本方案的安全约束互洽,记录如下,避免实施时重新讨论: + +1. **health 侧不新增按 userId 查询用户的接口。** 管理员建单时订单归属取所选健康档案的 `profile.userId`,不传、也不信任管理员传入的 userId。这与 `api/health/utils/user_service.js` 中「user 服务不接受按 userId 明文查询」的既有约束一致。 +2. **档案无归属时订单 `userId` 留空,后期补。** `escort_record.userId` 非必填;补归属由管理员在 health 侧订单编辑完成(`RECORD_FIELDS` 已含 `userId`),不依赖 user 服务。留空订单对 C 端不可见(按 userId 查询不命中),补齐后客户才可见。 +3. **补归属不依赖账号合并,也不新增接口。** 管理端通过 `POST /user/list`(已实现为「`wxapp-escort` 有效成员」口径,支持 keyword 且返回 `total`)人工核对客户,确认后把 `userId` 写入档案或订单;unionid / 手机号合并只影响账号归并,与补归属无关。 +4. **`web-escort-admin`(Web 后台)如后续支持代客下单,沿用同一规则**:档案锚定、不传 userId、无归属留空。 +5. 本节为业务层约定,不改动 R1-R8 任何契约。 + +--- + 附:本方案只改 `api/user` 的模型与接口,不包含会话表、权限管理后台、细粒度 RBAC。`user_session` 作为独立事项另行评估。 diff --git a/doc/web-escort-admin-plan.md b/doc/web-escort-admin-plan.md new file mode 100644 index 0000000..0e71099 --- /dev/null +++ b/doc/web-escort-admin-plan.md @@ -0,0 +1,259 @@ +# 陪诊 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_escort_admin`(小程序端,管理员/陪诊员混用),缺少桌面端后台。本方案新建 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 直连本地服务。 diff --git a/ui/web_escort_admin b/ui/web_escort_admin new file mode 160000 index 0000000..bfe4511 --- /dev/null +++ b/ui/web_escort_admin @@ -0,0 +1 @@ +Subproject commit bfe451104d61904ed606608fbb7d2ce212b9055c