MediLink B 端使用说明书（中文）

适用对象：顾问（CONSULTANT）/ 医生（DOCTOR）/ 运营管理员（ADMIN）。访问入口 https://<域名>/admin/（dev http://127.0.0.1:5173/admin/）。 本手册为图解版：每页 = 入口 → 截图 → 做什么 → 操作步骤 → 规则与注意。截图由 Playwright 真环境生成（web/e2e/admin-snapshots.spec.ts），存 images/。

1 开始之前

1.1 角色与权限速查

菜单按登录时下发的权限快照显隐（authz.ts 纯函数）——权限变更后需重新登录刷新。

1.2 登录（两段式）

• 入口：/admin/login
• 步骤：①输入邮箱+密码 → ②若已绑定 TOTP，输入验证器（Google Authenticator 等）6 位码 → 进入工作台。
• 规则：
  • 密码错/账号禁用/邮箱不存在一律提示相同错误（防试探）。
  • TOTP 码 30s 一换、可用前后各一个窗口；同一码 90 秒内不能重复使用（重试请等下一码）。
  • 未绑定 2FA 的账号直接进入（自助绑定见「设置与 2FA」章节）。

2 顾问日常（CONSULTANT）

2.1 聊天工作台

账号与首次登录

• 初始顾问账号（部署方 seed 发放）：consultant@medilink.local / Consultant#2026。上线后请立即登录改密（见「设置与 2FA」章节）。
• 顾问为强制两段式登录（TOTP，见 1.2）：邮箱密码通过后需输 6 位动态码。
• 开发/测试环境的 TOTP 种子为 JBSWY3DPEHPK3PXP（Base32），添加方式任选：
  • Google Authenticator / 1Password 等：手动添加 → 输入上述种子 → 生成 6 位码（30s 一换）；
  • 或命令行现算（macOS/Linux 自带 python3）：

    python3 -c "import hmac,hashlib,struct,time,base64; \
      k=base64.b32decode('JBSWY3DPEHPK3PXP'); \
      m=struct.pack('>Q',int(time.time())//30); \
      print('%06d'%(struct.unpack('>I',hmac.new(k,m,hashlib.sha1).digest()[-4:])[0]%10**6))"
    

• 管理员（ADMIN）/ 医生（DOCTOR）账号没有发送权限（RBAC 字典仅授顾问 chat:send）：登录聊天页为监控模式——消息可见，输入框/发送/推送卡片为禁用态并显示「监控模式：仅顾问可回复」，属预期设计而非故障。

多顾问值守：响应原理与流程

原理（广播制，当前版本无分配/认领机制）：

• 会话不绑定具体顾问：任意顾问在会话列表可见全部会话与消息（权限 chat:read）；
• 任意顾问可回复任意会话（发送仅校验权限与会话存在，不校验归属）；
• 两位顾问同时回复同一会话时，双方消息都会正常送达患者并上屏，系统不做加锁、不做冲突提示。

建议值守流程：

1. 轮值主应答：同一时段指定一名顾问为主应答人，其余顾问只读观察，避免多头回复；
2. 接手报备：换班接手时先在会话里发一条「此处由我跟进」（或工作台口头交接），再开始回复；
3. 复杂病例转工单：聊天只做咨询与引导，涉及诊疗方案的问题推送注册卡片转正式工单，由医生在预诊断工作台处理，不要在聊天里给医疗建议。

• 入口：左侧菜单「聊天」（/admin/chat）
• 做什么：接待匿名咨询、双语回复（系统自动翻译）、推送注册卡片。
• 步骤：
  1. 左侧会话列表点选会话（广播制，全员可见全部会话）；
  2. 底部输入框中文回复，回车发送——患者侧看到英文译文（气泡先显示原文，译文异步补挂）；
  3. 需引导注册时点「推送注册卡片」——患者聊天页出现卡片，点击直达注册页。
• 规则与注意：
  • 消息 ≤2000 字符；图片走聊天图上传（jpg/png ≤10MB）。
  • 患者注册后会话自动归属其账号，历史消息不丢；绑定后该会话不再接受访客身份发言。
  • 「注册完成」会出现在右上角待办铃铛（INBOX）。
  • 发送失败（网络/权限异常）会弹出错误提示；提示「Forbidden」多为账号无 chat:send 权限（见上文监控模式说明）。

2.2 工单列表与详情

• 入口：左侧菜单「工单」（/admin/tickets）
• 做什么：跟进全部工单的状态与进度、分配顾问/医生、手动流转、下载病历、管理出行与阶段。
• 步骤：
  1. 列表按状态/期望城市筛选，点行进入详情；
  2. 详情页时间线展示全部状态/分配/阶段/文档事件；
  3. 「分配顾问」「分配医生」：选人后生效（可改派）；
  4. 「流转」：按状态机推进（如 IN_TREATMENT→COMPLETED），必须填原因；
  5. 文档区点击下载（浏览器代理下载，≤20MB）；同组资料可查历史版本。
• 规则与注意：
  • 状态机白名单流转（非法跳转会 409）；三条回退边中「支付失败重谈」「医生拒绝重派」由系统自动触发，手动可用的回退边=改方案（PENDING_DEPARTURE→PLAN_CONFIRMING）。
  • 诊疗阶段（出发准备→返程 8 阶段）仅在工单进入「就医中」后可推进。

2.3 诊疗阶段推进与资料上传

• 入口：工单详情（就医中状态）
• 步骤：①点「推进阶段」选择下一阶段并填原因；②「上传阶段资料」选阶段+文件+说明；③如需替换，选同一版本组上传新版本（旧版自动归档，可查）。
• 规则：资料 pdf/jpg/png ≤20MB；版本组内现行版唯一；替换后患者端立即可见最新版。

2.4 出行协助

• 入口：工单详情出行区
• 步骤：「新增记录」选类型（酒店/交通）、标题、时间、明细与备注 → 创建后按进展流转（PLANNED→BOOKED→COMPLETED/CANCELLED）。
• 规则：明细为结构化记录（服务端不校验内容）；患者端「进度页」可只读查看。

2.5 运营看板

• 入口：左侧菜单「看板」（/admin/board）
• 做什么：总览工单状态/阶段分布、发现超时工单、支付残留单对账、FAILED 邮件对账。
• 规则：超时阈值由系统配置（待分配/预诊断中/待支付三档）；「对账」tab 的关单与重发仅 ADMIN 可操作。

3 医生日常（DOCTOR）

3.1 预诊断工作台

• 入口：左侧菜单「预诊断」（/admin/diagnosis）
• 做什么：处理待预诊工单——看病历、填意见、推荐科室与专家、预估时间费用；或拒绝重派。
• 步骤：
  1. 待诊列表点工单，Modal 内在线预览病历（图片/PDF）；
  2. 填写预诊意见与治疗方案；
  3. 推荐科室后按科室拉取专家列表选人（或手填）——选定专家即确认院区；
  4. 填预估停留天数与费用（费用留空则定金按系统固定额）；
  5. 提交：工单进入「方案确认中」，患者收到邮件并可在进度页查看方案。
• 规则与注意：
  • 「拒绝」必须填原因：工单退回「待分配」，顾问收到站内提醒后重新分配（可换医生）。
  • 专家快照写入方案后不再随专家改名/下架变化（医疗记录语义）。
  • 只有「预诊断中」状态的工单出现在列表；提交/拒绝后自动移出。

4 运营管理（ADMIN）

聊天页对管理员为只读监控（可看会话与消息，无发送框——RBAC 口径：chat:send 仅授顾问，见 2.1）。

4.1 医院管理

• 入口：左侧菜单「医院」（/admin/hospitals）
• 做什么：医院建档、编辑（含富文本三列）、上架/下架、科室与专家维护、封面图上传。
• 步骤：
  1. 「新建」填中英文名/等级/城市/地址/科室标签/国际部简介/服务特色/就诊流程 → 保存（草稿态；建院时填的富文本随表单直接落库）；
  2. 「编辑」九字段全量回填，改后保存（version 并发保护：他人先改则保存失败，刷新后重改）；
  3. 「封面」选图 → 本地预览 → 「上传」（M14 新增入口；jpg/png ≤5MB，presign 直传不占后端带宽）；打开 Modal 即显示「当前封面」回显（M15 读侧，草稿态也可看）；
  4. 「上架」发布（列表仅上架医院对患者可见；下架随时可再上架）；
  5. 科室：院内「新增科室」（草稿起步，随院区独立上下架）；
  6. 专家：科室下「新增专家」（姓名/职称/专长/简介/排序），上架后医生预诊可选。
• 规则与注意：
  • 编辑表单中的国际部简介/服务特色/就诊流程随表单全量提交（M13 修复后不再清空已有内容，见 FSD 99-附录 DIF-F2-1）；封面图不在编辑表单内——走操作列「封面」按钮（见步骤 3），编辑不影响已有封面。
  • 封面上传成功后列表会刷新（封面 confirm 会使版本号+1，独立入口避免与编辑并发冲突）；已上传封面在「封面」Modal 顶部回显（M15 读侧端点），患者端医院详情页头图同步展示（仅上架医院）。
  • 无删除操作——只有下架（历史数据保全）。

4.2 用户管理

• 入口：左侧菜单「用户」（/admin/users）
• 做什么：建 B 端账号、禁用/启用、改角色、重置密码、重置 2FA。
• 步骤：列表→操作列对应按钮；全部敏感操作必须填原因（进审计日志）。
• 规则：
  • 角色变更后对方重新登录才生效（权限快照随登录刷新）。
  • 禁用立即生效（下次登录被拒）；重置 2FA 后对方需重新扫码绑定。

4.3 设置与 2FA

• 入口：左侧菜单「设置」（/admin/settings）
• 做什么：绑定/解绑自己的 TOTP 验证器。
• 步骤：①「绑定 2FA」得二维码（另有密钥文本可手动输入）→ ②验证器 App 扫码（或手输密钥）→ 输入当前 6 位码确认 → 生效；解绑需输入当前有效码。
• 规则：绑定后登录必须两段式；绑定中途（未验证首码）不生效，不会把自己锁在外面。
• 忘记验证码/换手机：本人无法登录时由管理员在「用户管理」重置 2FA。完整说明（原理/验证器 App 选型/排障）见 docs/TOTP双重验证说明.md。

4.4 审计与 GDPR

• 入口：审计页（操作日志倒序）；GDPR 抹除在用户/患者维度操作。
• 规则：抹除=墓碑化（账号保留脱敏锚保审计链、聊天正文清空、OSS 文档删除）；操作全部留痕（gdpr.erase）。