| 项目 | +说明 | +
|---|---|
| 文档版本 | +v1.0 | +
| 编写日期 | +2026-09-18 | +
| 适用环境 | +dev / test / main 三环境通用（截图取自 dev 环境） | +
| 适用读者 | +系统管理员、研发总监、技术主管、方案工程师、外部审计/访客 | +
| 配套格式 | +Markdown（本文）/ HTML / PDF / Word | +
水木东方 · 医疗器械 AI 协同工作台 +是一个面向企业与团队的多用户工作流与对话智能体平台，定位于医疗器械受控研发场景（NMPA +/ ISO 13485 语境）。它将「AI +对话助手」与「受控文档治理」结合：项目成员通过对话推进项目，AI +助手协助沉淀研发文档，文档经过编制 → 审核 → +批准三责分离的审批链后归档生效，阶段全部必需文档批准后项目方可推进到下一阶段。
+| 模块 | +功能 | +
|---|---|
| 登录与准入 | +账号密码登录、用户自主注册、注册审批、首次登录强制改密 | +
| 工作台 | +三栏布局：项目会话列表 / 对话区 / 交付物文档区 | +
| 项目管理 | +立项会话、成员与职责分配、工作流切换、阶段门禁推进 | +
| 对话 | +流式对话、附件上传（每轮最多 5 +个）、意图计划卡片、历史搜索与导出 | +
| 文档 | +块编辑、编辑租约锁、版本历史与对比、评论、可见性覆盖、导出 | +
| 审批 | +文档三责审批（编制/审核/批准）、阶段门禁、注册审批、修改建议审批 | +
| 系统管理台 | +运行总览、知识库连接、特性开关、设置白名单、工作流定义、RBAC +角色权限、用户与准入治理、文档模板库 | +
| 知识库 | +跨环境共享的向量知识库（RAG），检索结果在对话中以推荐卡片呈现 | +
| 术语 | +含义 | +
|---|---|
| 项目实例（ProjectInstance） | +一个业务项目激活工作流后生成的运行实例，包含阶段序列与当前活动阶段 | +
| 工作流（Workflow） | +预定义的「阶段 → 任务 → +产出文档」模板。系统内置三套正式工作流：main（V0.1 +需求摸底 → V0.5 方案与可行性 → V1.0 +商务报价）、product_manager（系统需求基线）、test_manager（系统验证策划） | +
| 阶段门禁（Stage Gate） | +进入下一阶段前，本阶段所有「必需且受审批管理」的文档必须到达「已批准」终态，由项目创建人显式推进 | +
| 文档审批（docgov） | +受控文档 编制中 → 审核中 → 批准中 → 已批准 +的生命周期，三责分离，含编辑租约锁 | +
| 职责三角色 | +编制人（author，唯一可改正文）、审核人（reviewer）、批准人（approver） | +
| RAG 知识库 | +跨环境共享的向量检索库，为对话提供引用与案例推荐 | +
| SSE 流式对话 | +服务端推送（Server-Sent Events）实时输出 AI 回复，逐字呈现 | +
| 任务持久化 | +AI 任务运行落库，支持断点恢复、取消与事件回放 | +
| PI Agent Runner | +产品容器内的真实 AI 执行器，驱动项目助手对话与文档生成 | +
| 环境 | +访问地址 | +用途 | +
|---|---|---|
| 开发 dev | +http://127.0.0.1:8080 | +日常开发验证 | +
| 测试 test | +http://127.0.0.1:8081 | +发布前验收 | +
| 生产 main | +http://127.0.0.1:8000 | +正式使用 | +
推荐使用 Chrome / Edge 最新版本，窗口宽度建议 1440px +以上（三栏布局）。
+系统不提供匿名访问，账号有三条来源：
+InitPass123，首次登录强制改密（见 2.5）。打开访问地址，进入登录页。左侧为品牌与能力介绍，右侧为登录表单；左上角胶囊显示当前环境（DEV/MAIN）。
+
操作步骤：
+++注意：连续登录失败请确认账号状态。新注册未审核的账号登录会提示「账号正在等待管理员审核中」；被停用的账号无法登录，需联系管理员。
+
管理员开通的账号使用初始密码首次登录时，系统强制要求修改密码：
+
登录成功后进入工作台。工作台为三栏布局：
+
| 区域 | +内容 | +
|---|---|
| 左栏 | +项目会话列表（一项目一会话）、「+ +新建立项会话」按钮、项目成员入口 | +
| 中栏 | +对话区：消息流、阶段事件条、分类 Dock、输入区（附件/引用/发送） | +
| 右栏 | +交付物文档区：分类 +Tab（受控/共享/私密）、文档渲染与块编辑、治理操作条 | +
顶栏显示：当前项目名与当前阶段、工作流名称与运行状态、项目助手在线状态（绿点）、系统设置与个人信息入口。
+
点击左下角个人区域打开个人设置弹窗，可修改个人资料（姓名、部门、工号等）：
+
「我的项目权限」弹窗展示当前账号在各项目中的职责：待我编制 / 待我审核 +/ 待我批准的文档清单，以及法定职责说明：
+
++本章仅适用于**系统管理员（ADMIN）**角色。管理员登录后，可通过顶栏入口切换到「系统管理台」全屏视图；非管理员访问会被二次鉴权拦截（403 +退回工作台）。
+
系统管理台左侧为 8 个分组导航：
+
| 分组 | +用途 | +
|---|---|
| 系统运行总览 | +服务健康、版本、数据库与知识库就绪状态 | +
| 知识库连接 | +知识库在线状态、服务地址、数据库、连接账号 | +
| 特性功能开关 | +环境变量级 / 数据库级 feature flag 管理 | +
| 系统设置白名单 | +允许前端读取的系统设置项 | +
| 工作流定义 | +内置工作流定义列表（阶段/任务/产出文档结构） | +
| RBAC 角色权限 | +角色-权限矩阵，支持自定义角色 | +
| 用户与准入治理 | +账号开通、注册审批、准入策略 | +
| 文档与模板库 | +文档模板名称、版本、资产标识 | +
在「用户与准入治理 → 账号列表」中：
+
InitPass123），将其线下告知员工；账号列表还支持：变更职位与角色、启用/停用账号、重置初始密码（重置后该账号下次登录再次强制改密）。
+当准入策略开启「自主注册」且「注册需审核」时，新注册用户进入待审核队列：
+
两个开关：
+| 开关 | +说明 | +
|---|---|
| 开放自主注册 | +关闭后登录页不再显示「用户自主注册」Tab | +
| 注册需要审核 | +开启后新注册账号处于待审核状态，须管理员核准 | +
「RBAC 角色权限」分组展示角色 × 权限点矩阵：
+
系统内置 5 个角色（ADMIN 为系统角色，不可删除/改名）：
+| 角色 | +Code | +定位 | +
|---|---|---|
| 系统管理员 | +ADMIN | +全量权限，含系统管理台 | +
| 研发总监 | +DIRECTOR | +立项、指派负责人、可见性配置与覆盖、导出、查看全部工作流 | +
| 研发技术主管 | +TECH_LEAD | +立项、指派负责人、导出、查看全部工作流 | +
| 方案工程师 | +ENGINEER | +导出、查看全部工作流 | +
| 外部审计/访客 | +GUEST | +仅导出（只读审计场景） | +
权限点目录：project:create（立项）、project:assign_lead（变更责任人）、system:manage（系统管理）、workflow:config_visibility（可见性配置）、doc:override_visibility（可见性覆盖）、doc:export（导出）、workflow:view_all（查阅全部）、workflow_defs.publish（发布工作流定义）、templates.publish（发布模板）。
管理员还可新建自定义角色并勾选权限点组合，或修改/删除非系统角色。
+| 截图 | +说明 | +
|---|---|
 |
+特性功能开关：控制实验性能力的启用/关闭（数据库级开关即时生效；环境变量级需重启服务）。注意：未理解的开关不要随意改动，部分开关影响数据处理链路 | +
 |
+知识库连接：查看共享知识库（RAG）在线状态、服务地址、数据库与连接账号；离线时对话中的案例推荐不可用 | +
 |
+工作流定义：查看内置工作流的阶段、任务与产出文档模板结构 | +
 |
+文档与模板库：模板名称、版本列表与资产标识（asset_key），受控文档基于模板生成 | +
拥有 project:create
+权限的角色（研发总监、技术主管）可立项。点击左栏「+ 新建立项会话」：
立项后，打开「项目成员」弹窗，把成员加入项目并分配职责：
+
职责与文档审批链直接挂钩（见第 8 章）：
+++职责模式：项目工作流计划可配置 +
+full（编制/审核/批准三人齐备）、partial（部分职责）、none（免审批链）以及试点环境的「编制人兼任」（同人三签）模式。
一个项目可挂接多套工作流（如同时推进商务线 main 与产品线 +product_manager）。工作流在项目设置的「选择工作流」步骤中选择（列出全部已发布工作流，单选）：
+
| 工作流 | +阶段序列 | +
|---|---|
| main | +V0.1 需求摸底 → V0.5 方案与可行性 → V1.0 商务报价 | +
| product_manager | +系统需求基线 | +
| test_manager | +系统验证策划 | +
项目设置的「配置职责」步骤中，可将阶段产出文档（如 intake +用户初始需求收集表）纳入人工审批，并通过下拉框指派编制/审核/批准三权责任人：
+
中栏底部为输入区：输入消息，Enter 发送，Shift+Enter 换行。项目助手以 +SSE 流式逐字输出回复。
+下图为与项目助手的真实对话（dev 环境真实 PI Agent 执行）：
+
项目助手可以帮你：查询项目进展与风险、沉淀客户需求与技术指标、起草沟通话术与方案要点、推进方案论证与报价核算、编制或修订交付物文档。
+每轮对话最多可上传 5 +个附件（图片、文档等），点击输入区附件图标选择文件：
+
当助手识别到需要多步骤执行的任务时，会在对话中给出执行计划（步骤清单与选项），你可以直接回复确认（如"好"或"1"）让助手按计划执行，或补充说明调整方向。多意图计划的确认/驳回卡片由特性开关控制（当前 +dev 环境默认关闭，计划以消息内选项形式呈现，见 6.1 +的真实对话截图）。
+对话支持历史搜索、日历定位、导出与 Digest 时间线回顾：
+
右栏为交付物文档区，顶部分类 Tab 将文档分为三层：
+| 分类 | +说明 | +
|---|---|
| 工作流受控 | +工作流要求的正式交付物，走三责审批链，全生命周期留痕 | +
| 项目共享 | +项目成员共享的非受控资料 | +
| 个人私密 | +仅自己可见的草稿与笔记 | +
受控文档由「块」组成。双击任意段落进入就地编辑；鼠标右键可唤出快捷菜单（编辑、批注、复制、插块）：
+
++编辑租约锁：同一文档同一时间仅一人持有编辑租约，避免冲突；他人打开时显示锁定状态。审核中/批准中的文档正文锁定，不可编辑。
+
文档工具栏可打开版本历史抽屉，查看每次修订版本，支持两版本对比（人工修改以琥珀底+下划线标出，相对最新基线）：
+
交付物支持导出 DOCX / XLSX / Markdown（需要 doc:export
+权限）：
默认可见性由工作流配置；有 doc:override_visibility
+权限的角色（如研发总监）可对单个文档做可见性覆盖：
系统中有四套审批机制，本章逐一说明。
+受控文档生命周期：
+编制中(drafting) → 审核中(reviewing) → 批准中(approving) → 已批准(approved)
+ ↑ ↓ 驳回
+ └──── 退回编制 ────┘第 1 步：编制人认领文档。 +编制人打开受控文档并首次保存正文后，系统自动完成认领（治理操作条显示「编制中 +· 已被编制人认领」），获得该文档的编制权：
+
第 2 步：编制并提交送审。 +编制完成后点击「提交送审（流转至审核人）」，文档进入「审核中」，正文锁定：
+
第 3 步：审核人审核。 +审核人在自己的队列中看到待审核文档，可「审核通过（送呈批准人）」或「驳回退回编制」（驳回需说明理由）：
+
第 4 步：批准人终审。
+批准人执行「终审批准生效」；批准后文档到达 approved
+终态并自动入标杆库。批准人驳回时必须填写理由，可指定回退到编制或审核环节：
++三责分离守卫：只有编制人可改正文；审核人/批准人不可编辑；送审只能由编制人发起。试点环境支持「编制人兼任」同人三签模式（同一人员依次完成三签）。
+
当前阶段所有「必需且受审批管理」的文档到达已批准后，阶段门禁就绪，顶部出现推进 +Banner：
+
只有项目创建人可以点击「确认推进」进入下一阶段；门禁未就绪时按钮不可用并列出阻塞项（哪些必需文档未批准）：
+
非编制人员对受控文档可发起「修改建议」（propose），由责任人确认（decide）后合入，全程留痕，不破坏三责分离。
+面向管理员，见 +4.2。普通用户视角：注册后等待审核，审核通过前登录会收到「等待管理员审核」提示。
+| 权限点 | +ADMIN | +DIRECTOR | +TECH_LEAD | +ENGINEER | +GUEST | +
|---|---|---|---|---|---|
| 立项 project:create | +✓ | +✓ | +✓ | +— | +— | +
| 变更责任人 project:assign_lead | +✓ | +✓ | +✓ | +— | +— | +
| 系统管理 system:manage | +✓ | +— | +— | +— | +— | +
| 可见性配置 workflow:config_visibility | +✓ | +✓ | +— | +— | +— | +
| 可见性覆盖 doc:override_visibility | +✓ | +✓ | +✓ | +— | +— | +
| 导出 doc:export | +✓ | +✓ | +✓ | +✓ | +✓ | +
| 查阅全部 workflow:view_all | +✓ | +✓ | +✓ | +✓ | +— | +
++以管理台「RBAC +角色权限」矩阵实时数据为准；自定义角色权限由管理员配置。
+
系统管理员：登录 → 管理台总览看运行状态 → +注册审批中心处理新注册 → 为新员工开通账号并指派角色 → +按需调整特性开关。
+研发总监 / 技术主管（项目创建人）：立项 → +配置成员职责 → 与项目助手对话推进需求 → 关注待批准队列 → 终审批准文档 → +阶段门禁就绪后确认推进。
+编制人：在「我的项目权限」看待我编制清单 → 认领文档 +→ 块编辑编制内容 → 提交送审 → 如被驳回按意见修改再送审。
+审核人：看待我审核队列 → +审阅送审文档（可批注/提修改建议）→ 通过送呈批准人，或驳回退回编制。
+外部审计/访客：只读查阅被授权的交付物 → +导出留存。
+Q1：登录提示「账号正在等待管理员审核中」？ +自主注册的账号需要管理员在「注册审批中心」核准。请联系系统管理员。
+Q2：忘记密码怎么办？ +联系管理员在「账号列表」中「重置初始密码」，之后用初始密码登录并按提示强制改密。
+Q3：登录后看不到管理台入口？ +管理台仅系统管理员可见。其他角色访问会被拦截并退回工作台。
+Q4：为什么不能编辑某份受控文档？ +可能原因：你不是该文档编制人；文档处于审核中/批准中（正文锁定）；他人持有编辑租约；文档已批准归档（终态只读）。
+Q5：「确认推进」按钮不可用？ +阶段门禁未就绪：本阶段还有必需文档未批准。Banner +上会列出阻塞文档清单，先完成其审批链。另外只有项目创建人能推进阶段。
+Q6：对话中助手没有推荐案例？ +知识库可能离线。请管理员到「知识库连接」分组检查共享知识库状态。
+Q7：附件传不上去？ 每轮对话最多 5 +个附件，超出需分轮发送；另请确认文件类型受支持。
+Q8：注册 Tab 不见了？ +管理员在「准入策略」中关闭了自主注册。请联系管理员直接开通账号。
+本说明书基于 dev 环境（schema +v52）真实操作截图编写。界面与流程以实际环境为准。
+ + diff --git a/docs/user-manual/dist/系统使用说明书.pdf b/docs/user-manual/dist/系统使用说明书.pdf new file mode 100644 index 00000000..51262463 Binary files /dev/null and b/docs/user-manual/dist/系统使用说明书.pdf differ