docs(user-manual): 新增系统使用说明书（33 张 dev 真实截图 + md/html/pdf/docx 四格式）

2026-09-18 04:08:49 +00:00
parent 423f7e7413
commit 688d9d30eb
44 changed files with 1898 additions and 0 deletions
@@ -13,6 +13,7 @@

 | owner | task | branch | worktree | mutex | status |
 |-------|------|--------|----------|-------|--------|
+| Kimi | 2026-09-18-user-manual | feature/user-manual | .worktrees/feature-user-manual | docs | done |
 | Cursor-Auto | 2026-09-18-wave2-config-flag-align | fix/wave2-config-flag-align | - | infra | done |
 | Cursor | 2026-09-18-wave1-main-env-fix | fix/wave1-main-env-fix | - | infra | done |
 | Cursor | 2026-09-18-wave0-p0-bug-fixes | fix/wave0-p0-sse-chat-cache-bugs | - | chat + web | done |
@@ -0,0 +1,58 @@
+---
+title: "系统使用说明书（含真实截图，md/word/pdf/html 四格式）"
+status: done
+created: 2026-09-18
+updated: 2026-09-18
+owner: Kimi
+branch: feature/user-manual
+worktree: .worktrees/feature-user-manual
+mutex: docs
+---
+
+# 系统使用说明书（含真实截图，md/word/pdf/html 四格式）
+
+## 目标
+
+产出覆盖「从 0 进入系统 → 登录/注册 → 管理员角色权限配置 → 日常使用 → 审批全流程」的终端用户说明书，配 dev 环境真实操作截图（含真实 PI 对话），交付 Markdown / HTML / PDF / Word 四种格式于 `docs/user-manual/`。
+
+## 范围
+
+- dev 环境（127.0.0.1:8080）Playwright 实操截图约 30 张（登录、工作台、立项、对话、文档、审批链、管理台 8 分组）
+- `docs/user-manual/manual.md` 十章中文说明书（内容以代码为准）
+- `docs/user-manual/scripts/`（截图与格式生成脚本，可重跑）
+- `docs/user-manual/dist/`（html/pdf/docx 产物）
+
+## 非目标
+
+- 不合入 dev、不 push（用户未要求）
+- 不改动任何产品代码
+- 不覆盖 control-center/web（空壳）与 engineering-dashboard（工程内部）
+
+## 步骤
+
+1. [x] 分支 + 登记
+2. [x] 环境预检（健康、登录凭证、中文字体、chromium）
+3. [x] 截图脚本 `capture-screenshots.mjs` 并采集
+4. [x] 真实 PI 对话截图
+5. [x] 三责审批链 + 阶段门禁截图（zhanggong/lizhuguan/wangzong）
+6. [x] 撰写 manual.md
+7. [x] build-formats.mjs 生成 html/pdf/docx（pandoc 缺失时 .doc 兜底）
+8. [x] 校验（图片引用、PDF 渲染抽查、docx 媒体嵌入）
+9. [x] 提交 + 更新 CURRENT
+
+## 验收标准
+
+- [x] 四种格式文件齐备且可打开
+- [x] manual.md 图片引用全部存在，无孤图
+- [x] PDF 中文无乱码、图片正常嵌入
+- [x] 说明书章节覆盖：进入系统/登录/注册/管理员配置角色权限/项目使用/对话/文档/审批/FAQ
+
+## 相关链接
+
+- Checklist: -
+- Handoff: -
+- Test report: -
+
+## 证据 / 备注
+
+- 演示账号（dev 种子，密码 123456）：zhanggong / lizhuguan / wangzong / guest；管理员 admin（密码取 configs/.env.dev）
@@ -0,0 +1,27 @@
+# 系统使用说明书（水木东方 · 医疗器械 AI 协同工作台）
+
+面向终端用户与系统管理员的完整使用说明书，覆盖：从 0 进入系统、登录/注册、管理员配置角色与权限、项目使用、AI 对话、文档工作台、审批全流程、FAQ。全部截图为 dev 环境真实操作采集（含真实 PI Agent 对话）。
+
+## 文件说明
+
+| 路径 | 说明 |
+|------|------|
+| [manual.md](./manual.md) | 说明书主文档（Markdown 源，SSOT） |
+| [images/](./images/) | 全部 UI 截图（PNG，编号对应章节） |
+| [dist/系统使用说明书.html](./dist/系统使用说明书.html) | HTML 版（单文件，图片已嵌入，浏览器直接打开） |
+| [dist/系统使用说明书.pdf](./dist/系统使用说明书.pdf) | PDF 版（A4） |
+| [dist/系统使用说明书.docx](./dist/系统使用说明书.docx) | Word 版 |
+| [scripts/capture-screenshots.mjs](./scripts/capture-screenshots.mjs) | 截图采集脚本（Playwright，需 dev 环境运行在 8080） |
+| [scripts/build-formats.mjs](./scripts/build-formats.mjs) | 格式生成脚本（pandoc + playwright） |
+
+## 重新生成
+
+```bash
+# 重新采集截图（dev 环境需在运行，会创建「说明书演示」前缀的演示数据）
+node docs/user-manual/scripts/capture-screenshots.mjs
+
+# 重新生成 HTML / PDF / DOCX
+node docs/user-manual/scripts/build-formats.mjs
+```
+
+依赖：pandoc（`brew install pandoc`）、playwright（复用仓库 `web/node_modules`，chromium 已安装）。
@@ -0,0 +1,75 @@
+{
+  "capturedAt": "2026-09-18T04:02:39.919Z",
+  "results": [
+    {
+      "file": "10-workbench-overview.png",
+      "ok": true,
+      "note": "三栏工作台总览（张工）"
+    },
+    {
+      "file": "11-topbar.png",
+      "ok": true,
+      "note": "顶栏特写（当前项目 + 项目助手在线）"
+    },
+    {
+      "file": "12-left-rail.png",
+      "ok": true,
+      "note": "左栏项目会话列表特写"
+    },
+    {
+      "file": "13-user-settings.png",
+      "ok": true,
+      "note": "个人设置弹窗"
+    },
+    {
+      "file": "14-my-rights.png",
+      "ok": true,
+      "note": "我的项目权限弹窗"
+    },
+    {
+      "file": "60-admin-overview.png",
+      "ok": true,
+      "note": "系统运行总览"
+    },
+    {
+      "file": "61-admin-users.png",
+      "ok": true,
+      "note": "账号列表 + 开通受控员工账号弹窗（示例已填，未提交）"
+    },
+    {
+      "file": "62-admin-approvals.png",
+      "ok": true,
+      "note": "注册审批中心（含 demo02 待审核记录）"
+    },
+    {
+      "file": "63-admin-access-policy.png",
+      "ok": true,
+      "note": "准入策略开关"
+    },
+    {
+      "file": "64-admin-roles.png",
+      "ok": true,
+      "note": "RBAC 角色权限矩阵"
+    },
+    {
+      "file": "65-admin-features.png",
+      "ok": true,
+      "note": "特性功能开关"
+    },
+    {
+      "file": "66-admin-kb.png",
+      "ok": true,
+      "note": "知识库连接"
+    },
+    {
+      "file": "67-admin-workflows.png",
+      "ok": true,
+      "note": "工作流定义"
+    },
+    {
+      "file": "68-admin-templates.png",
+      "ok": true,
+      "note": "文档与模板库"
+    }
+  ]
+}
@@ -0,0 +1,472 @@
+# 水木东方 · 医疗器械 AI 协同工作台 — 系统使用说明书
+
+| 项目 | 说明 |
+|------|------|
+| 文档版本 | v1.0 |
+| 编写日期 | 2026-09-18 |
+| 适用环境 | dev / test / main 三环境通用（截图取自 dev 环境） |
+| 适用读者 | 系统管理员、研发总监、技术主管、方案工程师、外部审计/访客 |
+| 配套格式 | Markdown（本文）/ HTML / PDF / Word |
+
+---
+
+## 目录
+
+1. [系统简介](#1-系统简介)
+2. [快速开始：从 0 进入系统](#2-快速开始从-0-进入系统)
+3. [界面导览：三栏工作台](#3-界面导览三栏工作台)
+4. [管理员指南：用户、角色与权限](#4-管理员指南用户角色与权限)
+5. [项目使用：立项与成员配置](#5-项目使用立项与成员配置)
+6. [对话与 AI 项目助手](#6-对话与-ai-项目助手)
+7. [文档工作台](#7-文档工作台)
+8. [审批全流程](#8-审批全流程)
+9. [角色权限速查与典型动线](#9-角色权限速查与典型动线)
+10. [常见问题 FAQ](#10-常见问题-faq)
+
+---
+
+## 1. 系统简介
+
+### 1.1 系统定位
+
+**水木东方 · 医疗器械 AI 协同工作台** 是一个面向企业与团队的多用户工作流与对话智能体平台，定位于医疗器械受控研发场景（NMPA / ISO 13485 语境）。它将「AI 对话助手」与「受控文档治理」结合：项目成员通过对话推进项目，AI 助手协助沉淀研发文档，文档经过**编制 → 审核 → 批准**三责分离的审批链后归档生效，阶段全部必需文档批准后项目方可推进到下一阶段。
+
+### 1.2 三大核心能力
+
+1. **受控 RBAC 权限体系**：系统级角色权限（RBAC）+ 文档级职责角色（编制/审核/批准）+ 项目级成员职责，三层隔离。
+2. **项目助手（AI Agent）**：每个项目会话配备项目助手，支持 SSE 流式对话、意图识别、计划确认卡片、知识库检索推荐。
+3. **三层文档隔离**：交付物分为「工作流受控」「项目共享」「个人私密」三类，受控文档全生命周期留痕，支持版本历史、修订、导出 DOCX/XLSX。
+
+### 1.3 主要功能一览
+
+| 模块 | 功能 |
+|------|------|
+| 登录与准入 | 账号密码登录、用户自主注册、注册审批、首次登录强制改密 |
+| 工作台 | 三栏布局：项目会话列表 / 对话区 / 交付物文档区 |
+| 项目管理 | 立项会话、成员与职责分配、工作流切换、阶段门禁推进 |
+| 对话 | 流式对话、附件上传（每轮最多 5 个）、意图计划卡片、历史搜索与导出 |
+| 文档 | 块编辑、编辑租约锁、版本历史与对比、评论、可见性覆盖、导出 |
+| 审批 | 文档三责审批（编制/审核/批准）、阶段门禁、注册审批、修改建议审批 |
+| 系统管理台 | 运行总览、知识库连接、特性开关、设置白名单、工作流定义、RBAC 角色权限、用户与准入治理、文档模板库 |
+| 知识库 | 跨环境共享的向量知识库（RAG），检索结果在对话中以推荐卡片呈现 |
+
+### 1.4 术语表
+
+| 术语 | 含义 |
+|------|------|
+| 项目实例（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 执行器，驱动项目助手对话与文档生成 |
+
+---
+
+## 2. 快速开始：从 0 进入系统
+
+### 2.1 访问地址与浏览器要求
+
+| 环境 | 访问地址 | 用途 |
+|------|----------|------|
+| 开发 dev | http://127.0.0.1:8080 | 日常开发验证 |
+| 测试 test | http://127.0.0.1:8081 | 发布前验收 |
+| 生产 main | http://127.0.0.1:8000 | 正式使用 |
+
+推荐使用 Chrome / Edge 最新版本，窗口宽度建议 1440px 以上（三栏布局）。
+
+### 2.2 账号从哪里来
+
+系统不提供匿名访问，账号有三条来源：
+
+1. **管理员直接开通**（最常见）：管理员在管理台「用户与准入治理」中创建受控员工账号，初始密码默认为 `InitPass123`，首次登录强制改密（见 2.5）。
+2. **用户自主注册**：在登录页「用户自主注册」Tab 自行注册。注册后职位为「访客/待指派」，**必须经管理员在注册审批中心核准后才能登录**。是否开放注册、注册是否需要审核，由管理员在「准入策略」中控制。
+3. **环境引导管理员**：系统首次部署时自动创建管理员账号（用户名密码由部署配置决定）。
+
+### 2.3 登录
+
+打开访问地址，进入登录页。左侧为品牌与能力介绍，右侧为登录表单；左上角胶囊显示当前环境（DEV/MAIN）。
+
+![登录页 - 账号密码](images/01-login.png)
+
+操作步骤：
+
+1. 在「账号密码登录」Tab 输入用户名与密码；
+2. 点击登录；
+3. 登录成功后进入三栏工作台。
+
+> **注意**：连续登录失败请确认账号状态。新注册未审核的账号登录会提示「账号正在等待管理员审核中」；被停用的账号无法登录，需联系管理员。
+
+### 2.4 自主注册
+
+![登录页 - 用户自主注册](images/02-login-register.png)
+
+1. 切换到「用户自主注册」Tab；
+2. 填写必填项：用户名、真实姓名、密码（两次输入一致）；选填：部门、工号；
+3. 提交后等待管理员审核；审核通过后使用注册的用户名密码登录；
+4. 审核通过后，管理员还会为你指派职位与角色（见第 4 章）。
+
+### 2.5 首次登录强制改密
+
+管理员开通的账号使用初始密码首次登录时，系统强制要求修改密码：
+
+![首次登录强制改密](images/03-first-login-password.png)
+
+1. 输入新密码并确认；
+2. 点击「重置并加密」；
+3. 确认后自动进入系统，之后使用新密码登录。
+
+---
+
+## 3. 界面导览：三栏工作台
+
+登录成功后进入工作台。工作台为三栏布局：
+
+![三栏工作台总览](images/10-workbench-overview.png)
+
+| 区域 | 内容 |
+|------|------|
+| 左栏 | 项目会话列表（一项目一会话）、「+ 新建立项会话」按钮、项目成员入口 |
+| 中栏 | 对话区：消息流、阶段事件条、分类 Dock、输入区（附件/引用/发送） |
+| 右栏 | 交付物文档区：分类 Tab（受控/共享/私密）、文档渲染与块编辑、治理操作条 |
+
+### 3.1 顶栏
+
+![顶栏](images/11-topbar.png)
+
+顶栏显示：当前项目名与当前阶段、工作流名称与运行状态、项目助手在线状态（绿点）、系统设置与个人信息入口。
+
+### 3.2 左栏：项目会话列表
+
+![左栏项目会话列表](images/12-left-rail.png)
+
+- 每个项目对应一个会话卡片，显示项目名、当前阶段徽标、消息数；
+- 点击卡片切换当前项目；
+- 「+ 新建立项会话」发起立项（见 5.1）；
+- 「项目成员」打开成员与职责弹窗（见 5.2）。
+
+### 3.3 个人设置
+
+点击左下角个人区域打开个人设置弹窗，可修改个人资料（姓名、部门、工号等）：
+
+![个人设置](images/13-user-settings.png)
+
+### 3.4 我的项目权限
+
+「我的项目权限」弹窗展示当前账号在各项目中的职责：待我编制 / 待我审核 / 待我批准的文档清单，以及法定职责说明：
+
+![我的项目权限](images/14-my-rights.png)
+
+---
+
+## 4. 管理员指南：用户、角色与权限
+
+> 本章仅适用于**系统管理员（ADMIN）**角色。管理员登录后，可通过顶栏入口切换到「系统管理台」全屏视图；非管理员访问会被二次鉴权拦截（403 退回工作台）。
+
+系统管理台左侧为 8 个分组导航：
+
+![管理台 - 系统运行总览](images/60-admin-overview.png)
+
+| 分组 | 用途 |
+|------|------|
+| 系统运行总览 | 服务健康、版本、数据库与知识库就绪状态 |
+| 知识库连接 | 知识库在线状态、服务地址、数据库、连接账号 |
+| 特性功能开关 | 环境变量级 / 数据库级 feature flag 管理 |
+| 系统设置白名单 | 允许前端读取的系统设置项 |
+| 工作流定义 | 内置工作流定义列表（阶段/任务/产出文档结构） |
+| RBAC 角色权限 | 角色-权限矩阵，支持自定义角色 |
+| 用户与准入治理 | 账号开通、注册审批、准入策略 |
+| 文档与模板库 | 文档模板名称、版本、资产标识 |
+
+### 4.1 开通受控员工账号
+
+在「用户与准入治理 → 账号列表」中：
+
+![账号列表与开通账号](images/61-admin-users.png)
+
+1. 点击「开通受控员工账号」；
+2. 填写用户名、姓名、角色、部门等信息；
+3. 系统生成初始密码（默认 `InitPass123`），将其线下告知员工；
+4. 员工首次登录会被强制改密（见 2.5）。
+
+账号列表还支持：**变更职位与角色**、**启用/停用账号**、**重置初始密码**（重置后该账号下次登录再次强制改密）。
+
+### 4.2 注册审批中心
+
+当准入策略开启「自主注册」且「注册需审核」时，新注册用户进入待审核队列：
+
+![注册审批中心](images/62-admin-approvals.png)
+
+- **通过并指派**：先在下拉框选择授予的业务职位（如「方案工程师」），再点击通过；账号激活，用户可登录并立即拥有该职位对应角色权限；
+- **驳回**：注册被拒绝，账号不可用。
+
+### 4.3 准入策略
+
+![准入策略](images/63-admin-access-policy.png)
+
+两个开关：
+
+| 开关 | 说明 |
+|------|------|
+| 开放自主注册 | 关闭后登录页不再显示「用户自主注册」Tab |
+| 注册需要审核 | 开启后新注册账号处于待审核状态，须管理员核准 |
+
+### 4.4 RBAC 角色权限矩阵
+
+「RBAC 角色权限」分组展示角色 × 权限点矩阵：
+
+![RBAC 角色权限矩阵](images/64-admin-roles.png)
+
+系统内置 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`（发布模板）。
+
+管理员还可**新建自定义角色**并勾选权限点组合，或修改/删除非系统角色。
+
+### 4.5 其余管理分组
+
+| 截图 | 说明 |
+|------|------|
+| ![特性功能开关](images/65-admin-features.png) | 特性功能开关：控制实验性能力的启用/关闭（数据库级开关即时生效；环境变量级需重启服务）。**注意**：未理解的开关不要随意改动，部分开关影响数据处理链路 |
+| ![知识库连接](images/66-admin-kb.png) | 知识库连接：查看共享知识库（RAG）在线状态、服务地址、数据库与连接账号；离线时对话中的案例推荐不可用 |
+| ![工作流定义](images/67-admin-workflows.png) | 工作流定义：查看内置工作流的阶段、任务与产出文档模板结构 |
+| ![文档与模板库](images/68-admin-templates.png) | 文档与模板库：模板名称、版本列表与资产标识（asset_key），受控文档基于模板生成 |
+
+---
+
+## 5. 项目使用：立项与成员配置
+
+### 5.1 新建立项会话
+
+拥有 `project:create` 权限的角色（研发总监、技术主管）可立项。点击左栏「+ 新建立项会话」：
+
+![新建立项会话](images/20-create-project.png)
+
+1. 填写项目名称、项目类型、背景说明等；
+2. 选择工作流（见 5.3）；
+3. 确认后系统创建项目实例，自动进入第一阶段（如 main 工作流的「V0.1 需求摸底」），并生成本阶段要求的受控文档骨架。
+
+### 5.2 项目成员与职责分配
+
+立项后，打开「项目成员」弹窗，把成员加入项目并分配职责：
+
+![项目成员与职责](images/21-project-members.png)
+
+职责与文档审批链直接挂钩（见第 8 章）：
+
+- **编制人**：可编辑受控文档正文、提交送审；
+- **审核人**：对送审文档做审核决议（通过/驳回）；
+- **批准人**：终审批准，批准后文档归档生效。
+
+> **职责模式**：项目工作流计划可配置 `full`（编制/审核/批准三人齐备）、`partial`（部分职责）、`none`（免审批链）以及试点环境的「编制人兼任」（同人三签）模式。
+
+### 5.3 工作流切换
+
+一个项目可挂接多套工作流（如同时推进商务线 main 与产品线 product_manager）。工作流在项目设置的「选择工作流」步骤中选择（列出全部已发布工作流，单选）：
+
+![选择工作流](images/22-workflow-switcher.png)
+
+| 工作流 | 阶段序列 |
+|--------|----------|
+| main | V0.1 需求摸底 → V0.5 方案与可行性 → V1.0 商务报价 |
+| product_manager | 系统需求基线 |
+| test_manager | 系统验证策划 |
+
+### 5.4 项目设置与职责配置
+
+项目设置的「配置职责」步骤中，可将阶段产出文档（如 intake 用户初始需求收集表）纳入人工审批，并通过下拉框指派编制/审核/批准三权责任人：
+
+![配置职责](images/23-project-settings.png)
+
+---
+
+## 6. 对话与 AI 项目助手
+
+### 6.1 发起对话
+
+中栏底部为输入区：输入消息，Enter 发送，Shift+Enter 换行。项目助手以 SSE 流式逐字输出回复。
+
+下图为与项目助手的真实对话（dev 环境真实 PI Agent 执行）：
+
+![真实对话](images/30-chat-real.png)
+
+项目助手可以帮你：查询项目进展与风险、沉淀客户需求与技术指标、起草沟通话术与方案要点、推进方案论证与报价核算、编制或修订交付物文档。
+
+### 6.2 附件上传
+
+每轮对话最多可上传 **5 个附件**（图片、文档等），点击输入区附件图标选择文件：
+
+![附件上传](images/31-chat-attachment.png)
+
+### 6.3 意图计划确认卡片
+
+当助手识别到需要多步骤执行的任务时，会在对话中给出**执行计划**（步骤清单与选项），你可以直接回复确认（如"好"或"1"）让助手按计划执行，或补充说明调整方向。多意图计划的确认/驳回卡片由特性开关控制（当前 dev 环境默认关闭，计划以消息内选项形式呈现，见 6.1 的真实对话截图）。
+
+### 6.4 历史记录
+
+对话支持历史搜索、日历定位、导出与 Digest 时间线回顾：
+
+![历史记录](images/33-history.png)
+
+---
+
+## 7. 文档工作台
+
+右栏为交付物文档区，顶部分类 Tab 将文档分为三层：
+
+| 分类 | 说明 |
+|------|------|
+| 工作流受控 | 工作流要求的正式交付物，走三责审批链，全生命周期留痕 |
+| 项目共享 | 项目成员共享的非受控资料 |
+| 个人私密 | 仅自己可见的草稿与笔记 |
+
+### 7.1 块编辑
+
+受控文档由「块」组成。双击任意段落进入就地编辑；鼠标右键可唤出快捷菜单（编辑、批注、复制、插块）：
+
+![文档块编辑](images/40-doc-editor.png)
+
+> **编辑租约锁**：同一文档同一时间仅一人持有编辑租约，避免冲突；他人打开时显示锁定状态。审核中/批准中的文档正文锁定，不可编辑。
+
+### 7.2 版本历史与对比
+
+文档工具栏可打开版本历史抽屉，查看每次修订版本，支持两版本对比（人工修改以琥珀底+下划线标出，相对最新基线）：
+
+![版本历史](images/41-version-history.png)
+
+### 7.3 导出
+
+交付物支持导出 DOCX / XLSX / Markdown（需要 `doc:export` 权限）：
+
+![导出](images/42-export.png)
+
+### 7.4 文档可见性
+
+默认可见性由工作流配置；有 `doc:override_visibility` 权限的角色（如研发总监）可对单个文档做可见性覆盖：
+
+![文档可见性](images/43-doc-visibility.png)
+
+---
+
+## 8. 审批全流程
+
+系统中有四套审批机制，本章逐一说明。
+
+### 8.1 文档三责审批（核心）
+
+受控文档生命周期：
+
+```text
+编制中(drafting) → 审核中(reviewing) → 批准中(approving) → 已批准(approved)
+        ↑                ↓ 驳回
+        └──── 退回编制 ────┘
+```
+
+**第 1 步：编制人认领文档。** 编制人打开受控文档并首次保存正文后，系统自动完成认领（治理操作条显示「编制中 · 已被编制人认领」），获得该文档的编制权：
+
+![编制中 · 已被编制人认领](images/50-doc-claim.png)
+
+**第 2 步：编制并提交送审。** 编制完成后点击「提交送审（流转至审核人）」，文档进入「审核中」，正文锁定：
+
+![提交送审](images/51-doc-submit-review.png)
+
+**第 3 步：审核人审核。** 审核人在自己的队列中看到待审核文档，可「审核通过（送呈批准人）」或「驳回退回编制」（驳回需说明理由）：
+
+![审核决议](images/52-doc-review.png)
+
+**第 4 步：批准人终审。** 批准人执行「终审批准生效」；批准后文档到达 `approved` 终态并自动入标杆库。批准人驳回时必须填写理由，可指定回退到编制或审核环节：
+
+![终审批准](images/53-doc-approve.png)
+
+> **三责分离守卫**：只有编制人可改正文；审核人/批准人不可编辑；送审只能由编制人发起。试点环境支持「编制人兼任」同人三签模式（同一人员依次完成三签）。
+
+### 8.2 阶段门禁推进
+
+当前阶段所有「必需且受审批管理」的文档到达已批准后，阶段门禁就绪，顶部出现推进 Banner：
+
+![阶段门禁就绪](images/54-stage-gate-ready.png)
+
+**只有项目创建人**可以点击「确认推进」进入下一阶段；门禁未就绪时按钮不可用并列出阻塞项（哪些必需文档未批准）：
+
+![确认推进阶段](images/55-stage-advance.png)
+
+### 8.3 修改建议审批
+
+非编制人员对受控文档可发起「修改建议」（propose），由责任人确认（decide）后合入，全程留痕，不破坏三责分离。
+
+### 8.4 注册审批
+
+面向管理员，见 4.2。普通用户视角：注册后等待审核，审核通过前登录会收到「等待管理员审核」提示。
+
+---
+
+## 9. 角色权限速查与典型动线
+
+### 9.1 权限速查表
+
+| 权限点 | 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 角色权限」矩阵实时数据为准；自定义角色权限由管理员配置。
+
+### 9.2 典型角色的一天
+
+**系统管理员**：登录 → 管理台总览看运行状态 → 注册审批中心处理新注册 → 为新员工开通账号并指派角色 → 按需调整特性开关。
+
+**研发总监 / 技术主管（项目创建人）**：立项 → 配置成员职责 → 与项目助手对话推进需求 → 关注待批准队列 → 终审批准文档 → 阶段门禁就绪后确认推进。
+
+**编制人**：在「我的项目权限」看待我编制清单 → 认领文档 → 块编辑编制内容 → 提交送审 → 如被驳回按意见修改再送审。
+
+**审核人**：看待我审核队列 → 审阅送审文档（可批注/提修改建议）→ 通过送呈批准人，或驳回退回编制。
+
+**外部审计/访客**：只读查阅被授权的交付物 → 导出留存。
+
+---
+
+## 10. 常见问题 FAQ
+
+**Q1：登录提示「账号正在等待管理员审核中」？**
+自主注册的账号需要管理员在「注册审批中心」核准。请联系系统管理员。
+
+**Q2：忘记密码怎么办？**
+联系管理员在「账号列表」中「重置初始密码」，之后用初始密码登录并按提示强制改密。
+
+**Q3：登录后看不到管理台入口？**
+管理台仅系统管理员可见。其他角色访问会被拦截并退回工作台。
+
+**Q4：为什么不能编辑某份受控文档？**
+可能原因：你不是该文档编制人；文档处于审核中/批准中（正文锁定）；他人持有编辑租约；文档已批准归档（终态只读）。
+
+**Q5：「确认推进」按钮不可用？**
+阶段门禁未就绪：本阶段还有必需文档未批准。Banner 上会列出阻塞文档清单，先完成其审批链。另外只有项目创建人能推进阶段。
+
+**Q6：对话中助手没有推荐案例？**
+知识库可能离线。请管理员到「知识库连接」分组检查共享知识库状态。
+
+**Q7：附件传不上去？**
+每轮对话最多 5 个附件，超出需分轮发送；另请确认文件类型受支持。
+
+**Q8：注册 Tab 不见了？**
+管理员在「准入策略」中关闭了自主注册。请联系管理员直接开通账号。
+
+---
+
+*本说明书基于 dev 环境（schema v52）真实操作截图编写。界面与流程以实际环境为准。*
@@ -0,0 +1,8 @@
+{
+  "demoProjectId": 6502,
+  "uidZhang": 10,
+  "uidLi": 11,
+  "uidWang": 12,
+  "workflowActivated": true,
+  "intakeDocId": "doc_proj6491_intake"
+}
@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// 由 manual.md 生成 HTML / PDF / DOCX 三种格式到 dist/
+// 依赖：pandoc（brew install pandoc）、playwright（复用 web/node_modules）
+// 运行：node docs/user-manual/scripts/build-formats.mjs
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MANUAL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DIST = path.join(MANUAL_DIR, 'dist');
+const MD = path.join(MANUAL_DIR, 'manual.md');
+const CSS = path.join(MANUAL_DIR, 'scripts', 'manual.css');
+
+fs.mkdirSync(DIST, { recursive: true });
+
+function pandoc(args) {
+  execFileSync('pandoc', args, { cwd: MANUAL_DIR, stdio: 'inherit' });
+}
+
+// 1) HTML（嵌入图片与样式，单文件可分发）
+const htmlPath = path.join(DIST, '系统使用说明书.html');
+pandoc([
+  'manual.md', '-f', 'gfm', '-t', 'html5', '--standalone',
+  '--embed-resources', `--css=${CSS}`,
+  '--metadata', 'title=水木东方 · 医疗器械 AI 协同工作台 — 系统使用说明书',
+  '--toc', '--toc-depth=2', '--shift-heading-level-by=0',
+  '-o', htmlPath,
+]);
+console.log('[ok] HTML:', htmlPath);
+
+// 2) DOCX（pandoc 自动嵌入 images/ 下的图片）
+const docxPath = path.join(DIST, '系统使用说明书.docx');
+pandoc(['manual.md', '-f', 'gfm', '--resource-path=.', '-o', docxPath]);
+console.log('[ok] DOCX:', docxPath);
+
+// 3) PDF（主机缺 chromium 系统依赖，改在 playwright docker 镜像内打印）
+const pdfPath = path.join(DIST, '系统使用说明书.pdf');
+const REPO = '/home/weichen/projects/Agent-System';
+execFileSync('docker', [
+  'run', '--rm', '-v', `${REPO}:${REPO}`, '-w', `${REPO}/web`,
+  'mcr.microsoft.com/playwright:v1.63.0-noble',
+  'node', path.join(MANUAL_DIR, 'scripts', 'pdf-print.mjs'), htmlPath, pdfPath,
+], { stdio: 'inherit' });
@@ -0,0 +1,36 @@
+/* 系统使用说明书 HTML/PDF 样式 */
+:root { color-scheme: light; }
+html { font-size: 15px; }
+body {
+  font-family: "Noto Sans CJK SC", "Source Han Sans SC", "Microsoft YaHei", "PingFang SC", "WenQuanYi Micro Hei", sans-serif;
+  line-height: 1.75;
+  color: #1f2329;
+  max-width: 880px;
+  margin: 0 auto;
+  padding: 2rem 2.5rem;
+}
+h1, h2, h3, h4 { color: #0f2a43; line-height: 1.35; }
+h1 { font-size: 1.7rem; border-bottom: 3px solid #1f6feb; padding-bottom: .4rem; }
+h2 { font-size: 1.35rem; border-bottom: 1px solid #d0d7de; padding-bottom: .3rem; margin-top: 2.2rem; }
+h3 { font-size: 1.1rem; margin-top: 1.6rem; }
+h1#toc, nav#TOC { page-break-after: always; }
+img {
+  display: block;
+  max-width: 100%;
+  margin: 1rem auto;
+  border: 1px solid #d0d7de;
+  border-radius: 6px;
+  box-shadow: 0 2px 8px rgba(0,0,0,.08);
+}
+table { border-collapse: collapse; width: 100%; margin: 1rem 0; font-size: .92rem; }
+th, td { border: 1px solid #d0d7de; padding: .4rem .6rem; text-align: left; }
+th { background: #f0f4f8; }
+code { background: #f6f8fa; padding: .1em .35em; border-radius: 4px; font-size: .88em; }
+pre { background: #f6f8fa; padding: .8rem 1rem; border-radius: 6px; overflow-x: auto; }
+pre code { background: none; padding: 0; }
+blockquote {
+  margin: 1rem 0; padding: .6rem 1rem;
+  border-left: 4px solid #1f6feb; background: #f0f6ff; color: #344054;
+}
+hr { border: none; border-top: 1px solid #d0d7de; margin: 2rem 0; }
+a { color: #1f6feb; text-decoration: none; }
@@ -0,0 +1,18 @@
+// 在 playwright docker 镜像内运行：chromium 打印 HTML → PDF
+// 用法：node pdf-print.mjs <html绝对路径> <pdf输出绝对路径>
+import { createRequire } from 'node:module';
+const require = createRequire('/home/weichen/projects/Agent-System/web/package.json');
+const { chromium } = require('playwright');
+
+const [htmlPath, pdfPath] = process.argv.slice(2);
+const browser = await chromium.launch();
+const page = await browser.newPage();
+await page.goto('file://' + htmlPath, { waitUntil: 'networkidle' });
+await page.pdf({
+  path: pdfPath,
+  format: 'A4',
+  printBackground: true,
+  margin: { top: '18mm', bottom: '18mm', left: '15mm', right: '15mm' },
+});
+await browser.close();
+console.log('[ok] PDF:', pdfPath);