|
|
@@ -0,0 +1,324 @@
|
|
|
+# 医梦患者智能服务门户 P0 开发与联调接手指引
|
|
|
+
|
|
|
+> 对外名称：医梦患者智能服务门户
|
|
|
+>
|
|
|
+> 内部代号：Adjutant（副官）
|
|
|
+>
|
|
|
+> 适用版本：P0 / 单医院移动端 Web Demo
|
|
|
+>
|
|
|
+> 更新日期：2026-07-27
|
|
|
+
|
|
|
+## 1. 接手者先读什么
|
|
|
+
|
|
|
+建议按以下顺序阅读：
|
|
|
+
|
|
|
+1. 项目根目录 [README](../README.md)：启动方式和工程入口。
|
|
|
+2. 本文：当前实现、代码边界和联调顺序。
|
|
|
+3. [P0 产品与交互文档集](./p0-mobile/README.md)：产品定位、入口、流程和验收原则。
|
|
|
+4. [产品定义](./p0-mobile/01-product-definition.md)、[信息架构](./p0-mobile/02-information-architecture-and-agent-entry.md) 和 [核心交互流程](./p0-mobile/03-core-interaction-flows.md)。
|
|
|
+5. [实施边界与验收](./p0-mobile/06-implementation-handoff-and-acceptance.md) 和 [客户端总交互流程](./p0-mobile/07-client-total-interaction-flow.md)。
|
|
|
+6. 最后阅读 `src/portal/`，再决定联调代码落点。
|
|
|
+
|
|
|
+## 2. 产品定位与 P0 边界
|
|
|
+
|
|
|
+本项目不是智能体聊天窗口集合，也不是完整互联网医院。它是部署给单家医院、面向患者的智能服务门户。
|
|
|
+
|
|
|
+P0 只验证三项能力：
|
|
|
+
|
|
|
+| 能力 | 患者主流程 | P0 执行方式 |
|
|
|
+|---|---|---|
|
|
|
+| 智能分诊挂号 | 表达需求 → 连续补槽 → 风险筛查 → 查询号源 → 确认挂号 | Mock HIS / Mock MCP |
|
|
|
+| 检验检查报告解读 | 上传报告 → 识别分析 → 结构化解读 → 风险提醒 | Mock Report MCP |
|
|
|
+| 中医舌诊 | 体质问答 → 上传舌象 → 分析 → 综合结果 | 后续接现有舌诊 MCP |
|
|
|
+
|
|
|
+P0 的明确限制：
|
|
|
+
|
|
|
+- 单医院，不做跨院数据。
|
|
|
+- 不做登录、实名认证和家庭代办，默认固定 Mock 患者本人。
|
|
|
+- 不接真实 HIS、LIS、EMR，不执行真实挂号或支付。
|
|
|
+- 服务目录可展示更多智能体，但只有三项 P0 能力可点击。
|
|
|
+- 结果和医疗提示均为演示内容，不能用于真实诊断或处置。
|
|
|
+- 交付形态是适配移动端的 Web 系统，不按原生 iOS/Android 应用实现。
|
|
|
+
|
|
|
+虽然 P0 只有本人，后续接口仍应预留 `operatorId` 和 `subjectPatientId`，避免 P1 支持家庭代办时重构数据归属。
|
|
|
+
|
|
|
+## 3. 这几天已经完成的工作
|
|
|
+
|
|
|
+### 3.1 产品与交互
|
|
|
+
|
|
|
+- 对外名称统一为“医梦患者智能服务门户”，内部代号为 Adjutant。
|
|
|
+- 固定“首页、服务、健康记录、我的”四个一级入口。
|
|
|
+- 首页吸收“患者状态与待办”，服务中心采用“一级目录 + 二级阶段”的双层目录。
|
|
|
+- 统一助手和三个服务入口最终进入独立任务，不建立微信式智能体会话列表。
|
|
|
+- 核心交互确定为“语音优先、文字可编辑、图片可上传、智能体连续补槽”。
|
|
|
+- 每次智能体回复后，在输入区上方给出一条可点击的推荐回答。
|
|
|
+- 结果以业务记录回看，不只保存在聊天上下文中。
|
|
|
+
|
|
|
+### 3.2 原型
|
|
|
+
|
|
|
+`prototype/adjutant-mobile/` 保存已通过视觉走查的 React 原型，是当前正式前端的设计参考，不是联调运行入口。
|
|
|
+
|
|
|
+原型已经覆盖：
|
|
|
+
|
|
|
+- 首页状态与待办。
|
|
|
+- 智能体目录和禁用状态。
|
|
|
+- 三智能体对话式任务流程。
|
|
|
+- 移动 Web 语音、文字、拍照/上传输入区。
|
|
|
+- 推荐回答、结构化结果、风险分流和 Mock 标识。
|
|
|
+
|
|
|
+### 3.3 正式 Vue 前端
|
|
|
+
|
|
|
+根工程已从旧桌面三栏终端切换为移动端门户：
|
|
|
+
|
|
|
+- `src/App.vue` 挂载 `src/portal/PortalApp.vue`。
|
|
|
+- `src/portal/pages/` 实现首页、服务、健康记录、我的。
|
|
|
+- `src/portal/components/AgentConversation.vue` 实现三个 P0 演示流程。
|
|
|
+- `src/portal/catalog.ts` 保存智能体目录；仅配置 `mode` 的三项能力可进入。
|
|
|
+- `src/portal/state/portalStore.ts` 管理一级页面和当前智能体。
|
|
|
+- `src/portal/portal.css` 实现最大宽度 430px 的移动 Web 页面。
|
|
|
+- 单元测试和 Playwright 测试覆盖入口、流程和移动/桌面预览布局。
|
|
|
+
|
|
|
+## 4. 工程结构与职责
|
|
|
+
|
|
|
+```text
|
|
|
+src/
|
|
|
+├── portal/ # 当前 P0 正式门户
|
|
|
+│ ├── components/ # 导航、消息、输入区和智能体会话
|
|
|
+│ ├── pages/ # 四个一级页面
|
|
|
+│ ├── state/ # 当前门户的轻量状态
|
|
|
+│ ├── catalog.ts # 医院智能体目录
|
|
|
+│ ├── types.ts
|
|
|
+│ └── portal.css
|
|
|
+├── api/ # 既有 API、HMAC、SSE、卡片 Mock
|
|
|
+├── cards/ # 既有挂号卡片
|
|
|
+├── chat/ # 既有桌面对话组件
|
|
|
+├── layouts/ # 既有桌面终端布局
|
|
|
+├── state/terminalStore.ts # 既有终端任务状态
|
|
|
+└── theme/tokens.css # 全局视觉令牌
|
|
|
+
|
|
|
+prototype/adjutant-mobile/ # 设计原型与视觉基准
|
|
|
+docs/p0-mobile/ # 产品、交互、契约和验收文档
|
|
|
+web-demos/ # 早期业务流程参考
|
|
|
+artifacts/ # 产品审计和视觉 QA 证据
|
|
|
+tests/ # 单元与 E2E 测试
|
|
|
+```
|
|
|
+
|
|
|
+需要特别注意：
|
|
|
+
|
|
|
+- 当前运行入口是根 Vue 工程，不是 `prototype/adjutant-mobile/`。
|
|
|
+- `src/api/`、`src/cards/` 和 `src/state/terminalStore.ts` 是旧终端时期留下的可复用基础，尚未与 `src/portal/` 完整整合。
|
|
|
+- 不要为了复用旧代码，重新引入桌面三栏、右侧活动卡片或 1280px 最小宽度。
|
|
|
+
|
|
|
+## 5. 本地启动与验证
|
|
|
+
|
|
|
+环境要求：
|
|
|
+
|
|
|
+- Node.js 20 或更高版本。
|
|
|
+- pnpm 9 或更高版本。
|
|
|
+- Playwright Chromium（运行 E2E 时需要）。
|
|
|
+
|
|
|
+```bash
|
|
|
+pnpm install
|
|
|
+pnpm dev
|
|
|
+```
|
|
|
+
|
|
|
+默认访问：
|
|
|
+
|
|
|
+```text
|
|
|
+http://127.0.0.1:5173/
|
|
|
+```
|
|
|
+
|
|
|
+完整验证：
|
|
|
+
|
|
|
+```bash
|
|
|
+pnpm test
|
|
|
+pnpm build
|
|
|
+```
|
|
|
+
|
|
|
+当前提交前基线：
|
|
|
+
|
|
|
+- 单元测试：27 项通过。
|
|
|
+- E2E：6 项通过。
|
|
|
+- E2E 视口：390 × 844 移动 Web、1280 × 720 桌面预览。
|
|
|
+- TypeScript 类型检查和生产构建通过。
|
|
|
+
|
|
|
+## 6. 三项能力的稳定编码
|
|
|
+
|
|
|
+前端应只认识稳定的 `capabilityCode`，不要认识 FastGPT 应用 ID。
|
|
|
+
|
|
|
+| 能力 | capabilityCode | 当前前端 mode |
|
|
|
+|---|---|---|
|
|
|
+| 智能分诊挂号 | `SMART_REGISTRATION` | `registration` |
|
|
|
+| 报告智能解读 | `REPORT_INTERPRETATION` | `report` |
|
|
|
+| 中医舌诊 | `TCM_TONGUE_ASSESSMENT` | `tongue` |
|
|
|
+
|
|
|
+下一步可在 `src/portal/types.ts` 中把 `mode` 与 `capabilityCode` 建立显式映射，再由 Gateway 解析真实执行实现。
|
|
|
+
|
|
|
+## 7. 推荐的联调边界
|
|
|
+
|
|
|
+客户端不要直接调用 FastGPT，也不要把具体 Workflow ID 写进组件。推荐调用关系：
|
|
|
+
|
|
|
+```text
|
|
|
+移动 Web
|
|
|
+→ Agent Gateway
|
|
|
+→ 能力校验与患者上下文
|
|
|
+→ FastGPT / Agent Runtime
|
|
|
+→ Mock MCP 或真实 MCP
|
|
|
+→ 标准事件和 UI 数据
|
|
|
+→ 移动 Web
|
|
|
+```
|
|
|
+
|
|
|
+建议统一请求至少包含：
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "hospitalId": "HOSPITAL_DEMO",
|
|
|
+ "operatorId": "USER_DEMO",
|
|
|
+ "subjectPatientId": "PATIENT_DEMO",
|
|
|
+ "relationType": "SELF",
|
|
|
+ "capabilityCode": "SMART_REGISTRATION",
|
|
|
+ "sessionId": "SESSION_DEMO",
|
|
|
+ "taskId": "TASK_DEMO",
|
|
|
+ "input": {
|
|
|
+ "type": "TEXT",
|
|
|
+ "content": "我头疼，帮我挂神经内科明天早上九点的专家号"
|
|
|
+ },
|
|
|
+ "context": {
|
|
|
+ "channel": "MOBILE_WEB",
|
|
|
+ "mock": true
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+建议统一返回或事件包含：
|
|
|
+
|
|
|
+- `traceId`、`taskId`、`sessionId`。
|
|
|
+- 当前任务状态和等待原因。
|
|
|
+- 智能体文本消息。
|
|
|
+- 已收集字段、缺失字段和下一条推荐回答。
|
|
|
+- 标准 UI 数据，例如号源、报告指标、风险提示和结果摘要。
|
|
|
+- MCP 调用状态和可公开的错误信息。
|
|
|
+- 是否需要人工处理或终止普通流程。
|
|
|
+
|
|
|
+不要在浏览器日志、测试截图或公共仓库中保存真实报告原图、完整身份证号、手机号、Token 或医院生产地址。
|
|
|
+
|
|
|
+## 8. 推荐联调顺序
|
|
|
+
|
|
|
+### 第一步：建立 Agent Gateway 适配层
|
|
|
+
|
|
|
+- 新建门户专用 API/适配层，隐藏 FastGPT 和 MCP 的具体协议。
|
|
|
+- 配置开发、Mock 和医院环境地址。
|
|
|
+- 统一错误、超时、取消和 `traceId`。
|
|
|
+- 保留当前前端演示状态作为无后端降级路径。
|
|
|
+
|
|
|
+### 第二步：联调智能分诊挂号
|
|
|
+
|
|
|
+- 将语音转文字结果作为普通文本输入送入同一任务。
|
|
|
+- 服务端返回已收集字段、缺失字段和推荐回答。
|
|
|
+- 急诊红旗优先于普通挂号意图。
|
|
|
+- 号源查询、选择和最终确认使用结构化数据。
|
|
|
+- 任何有副作用的操作都必须再次确认，并携带幂等键。
|
|
|
+
|
|
|
+P0 只连接 Mock HIS / Mock MCP，不得误调真实挂号接口。
|
|
|
+
|
|
|
+### 第三步：联调报告解读
|
|
|
+
|
|
|
+- 对话内上传图片或 PDF。
|
|
|
+- 展示上传、识别、分析和结果状态。
|
|
|
+- 返回结构化 Markdown 或标准结果字段。
|
|
|
+- 风险提醒必须独立突出，不埋在长文本中。
|
|
|
+- OCR 失败、图片模糊和接口失败均支持重试。
|
|
|
+
|
|
|
+### 第四步：联调中医舌诊
|
|
|
+
|
|
|
+- 先完成体质和症候问答，再进入舌象采集。
|
|
|
+- 上传图片后调用已有舌诊 MCP。
|
|
|
+- 将问答证据和 MCP 结果合并为综合结果。
|
|
|
+- 明确“健康参考，不能替代中医师完整辨证”。
|
|
|
+
|
|
|
+### 第五步：统一任务与记录
|
|
|
+
|
|
|
+- 将 `AgentConversation.vue` 中的本地阶段状态迁移到统一任务 Store。
|
|
|
+- 支持任务中断、恢复、完成和失败。
|
|
|
+- 将完成结果写入“健康记录”，而不是建立智能体聊天会话列表。
|
|
|
+
|
|
|
+## 9. 交互实现不可破坏的规则
|
|
|
+
|
|
|
+1. 产品始终是移动端 Web，主体最大宽度为 430px；桌面只用于预览。
|
|
|
+2. 语音是主要交付方式，但转写内容必须可见，关键操作必须屏幕确认。
|
|
|
+3. 文字、语音和推荐回答最终进入同一任务输入协议。
|
|
|
+4. 每次智能体回复后生成一条情境相关的推荐回答。
|
|
|
+5. 智能体负责理解、追问和解释；列表、选择、上传和确认使用标准组件。
|
|
|
+6. 只有三个 P0 智能体可进入，其他目录项保持不可点击。
|
|
|
+7. 急诊风险识别是挂号前置安全门禁，不作为患者可点击的独立智能体。
|
|
|
+8. 报告和舌诊输出必须结构化展示，不返回一整屏无层次长文本。
|
|
|
+9. 医疗风险、Mock 状态和服务边界必须持续可见。
|
|
|
+10. 患者回看的是挂号、报告和评估记录，不是智能体会话列表。
|
|
|
+
|
|
|
+## 10. 当前未完成事项
|
|
|
+
|
|
|
+以下内容是接手后的实际工作，不应误认为当前已经实现：
|
|
|
+
|
|
|
+- 真实语音识别和录音权限。
|
|
|
+- Agent Gateway 和 FastGPT 会话联调。
|
|
|
+- Mock MCP 的网络调用。
|
|
|
+- 报告文件真实上传、OCR 和结构化解析。
|
|
|
+- 现有舌诊 MCP 的真实调用。
|
|
|
+- 服务端任务状态、等待恢复和审计。
|
|
|
+- 健康记录持久化。
|
|
|
+- 医院品牌、能力清单和接口地址的配置化。
|
|
|
+- P1 登录、实名认证、家庭成员和真实院内接口。
|
|
|
+
|
|
|
+## 11. 联调验收清单
|
|
|
+
|
|
|
+### 挂号
|
|
|
+
|
|
|
+- 一句话包含部分或大部分挂号字段时可正确提取。
|
|
|
+- 缺失医生时连续追问，不能提前查询或提交挂号。
|
|
|
+- MCP 返回医生后生成“我想挂列表第一位医生”的推荐回答。
|
|
|
+- 所有字段完整后查询 Mock 号源。
|
|
|
+- 患者确认前不执行 Mock 挂号。
|
|
|
+- 胸痛、呼吸困难等演示红旗可停止普通流程。
|
|
|
+
|
|
|
+### 报告
|
|
|
+
|
|
|
+- 可在对话内选择图片或 PDF。
|
|
|
+- 上传和分析过程有明确状态。
|
|
|
+- 结果包含概览、风险、异常指标、联合解读和建议。
|
|
|
+- 图片不清晰、格式不支持和服务失败可恢复。
|
|
|
+
|
|
|
+### 舌诊
|
|
|
+
|
|
|
+- 体质问答按步骤完成并可继续。
|
|
|
+- 图片上传前有拍摄提示。
|
|
|
+- MCP 处理中有可理解的状态反馈。
|
|
|
+- 结果同时呈现问答、舌象特征和综合建议。
|
|
|
+
|
|
|
+### 通用
|
|
|
+
|
|
|
+- 390px 宽度下无横向滚动、遮挡或原生设备框。
|
|
|
+- 只有三项 P0 服务可点击。
|
|
|
+- 返回后一级导航和目录状态合理。
|
|
|
+- 失败信息不泄露内部接口、Prompt、Token 或患者敏感数据。
|
|
|
+- `pnpm test` 和 `pnpm build` 通过。
|
|
|
+
|
|
|
+## 12. 提交与协作建议
|
|
|
+
|
|
|
+- 一次提交只解决一类问题，例如“Gateway 适配”“挂号联调”“报告上传”。
|
|
|
+- 不要同时修改原型和正式前端；只有交互决策变化时才同步原型。
|
|
|
+- 新增能力前先更新 `capabilityCode`、输入输出契约和验收用例。
|
|
|
+- 任何医院差异应进入配置或 Adapter，不要散落在 Prompt 和页面条件分支中。
|
|
|
+- 保留 Mock 演示路径，确保后端暂不可用时仍能完成 P0 展示。
|
|
|
+- 提交前至少执行 `pnpm test` 和 `pnpm build`。
|
|
|
+
|
|
|
+## 13. 接手后的首个建议任务
|
|
|
+
|
|
|
+先完成一个最小的 `AgentGatewayClient`，用同一接口支持 Mock 与远程模式，然后只替换挂号流程的本地阶段推进。
|
|
|
+
|
|
|
+完成标准：
|
|
|
+
|
|
|
+1. 页面不感知 FastGPT App ID。
|
|
|
+2. 一条挂号会话能够接收服务端追问、缺失字段和推荐回答。
|
|
|
+3. Mock 号源以结构化数据返回并可确认。
|
|
|
+4. 网络失败可回退到明确错误状态，不破坏当前页面。
|
|
|
+5. 现有测试继续通过，并新增至少一条 Gateway Mock 集成测试。
|
wangkangyjy