# 产品文档管理步骤

- 日期：2026-05-22
- 适用范围：本轮 Muse 产品形态阶段化重设计，以及后续 `产品-02D~02G`、`产品-03`、`流程-*`、`架构-*`、`前端-*`、`后端-*` 的文档更新。
- 文档性质：项目内 memorys 留痕，用于下次继续设计时快速恢复流程约束和产品文档质量要求。

## 1. 阶段化文档管理步骤

本轮产品文档不能一次性全量缝合，必须按阶段、按顺序推进。

1. 先确认当前阶段。
2. 只修改当前阶段 owner 文档。
3. 已修改并确认过的前序文档作为当前阶段事实来源。
4. 后续阶段文档只能作为参考，用来发现冲突和待承接事项，不能反向覆盖前序结论。
5. 发现冲突时，先记录冲突和决策问题，不擅自混合新旧口径。
6. 每个阶段完成后，需要用户确认，再进入下一阶段。
7. 不跨阶段顺手修改后续文档。
8. 原型、review、修复都必须回到当前阶段文档闭环。

当前阶段顺序以 `design-docs/临时-产品形态阶段化重设计计划.md` 为准。

## 2. 产品文档内容要求

产品详细规格必须能支撑前端 UI 原型、后端产品接口拆解、测试验收和后续旅程文档。

每个 `产品-02B~02G` 分册至少要回答：

1. 有哪些功能模块。
2. 有哪些页面，页面 ID 是什么。
3. 每个页面的目标、角色、入口、返回规则是什么。
4. 页面有哪些区域。
5. 每个区域展示什么信息。
6. 列表、表单、详情、弹窗、抽屉分别展示哪些字段。
7. 查询条件是什么字段，用什么查询方式。
8. 用户可以做什么主操作、次操作和危险操作。
9. 操作前置条件、确认方式、成功结果、失败反馈和后续处理是什么。
10. 页面有哪些正常态、空态、错误态、无权限态、只读态、禁用态。
11. 需要哪些产品接口。
12. 产品接口的输入上下文、返回内容、权限、状态变化、副作用、失败类型、用户反馈、审计要求和后续承接是什么。
13. 哪些能力明确不做，哪些能力移交后续阶段。

不能只写“支持管理”“展示列表”“提供配置”“查看详情”这类概念描述。

## 3. 产品接口要求

产品接口不是后端 endpoint，也不是数据库字段，而是产品层合同。

接口表必须使用 `产品-02A` 的统一结构：

| 字段 | 要求 |
|---|---|
| 接口名称 | 产品层稳定名称 |
| 类型 | 查询 / 命令 / 决策 / 任务 / 授权 / 来源 / 质量 / 用量 / 审计 / 选项 |
| 使用页面 | 哪些页面或区域调用 |
| 用户意图 | 用户为什么需要它 |
| 输入上下文 | 账户、角色、对象、筛选、分页、授权快照、来源版本、幂等键等 |
| 返回内容 | 页面需要展示的数据，不写数据库字段 |
| 权限规则 | 谁能调用，哪些内容脱敏，哪些状态禁用 |
| 状态变化 / 副作用 | 是否改变状态，是否产生任务、审计、用量、授权快照或来源状态 |
| 失败类型 / 用户反馈 | 失败原因和页面如何提示 |
| 审计要求 | 是否记录操作者、理由、范围、时间、前后状态 |
| 后续承接 | 由哪个产品、流程、架构或后端文档继续细化 |

新增页面或操作时，必须同步补产品接口；新增接口时，必须能在页面、操作和覆盖表中找到使用位置。

## 4. 原型约束

HTML 原型必须严格来自当前阶段文档。

1. 文档没有描述的功能、字段、状态、按钮、模块，不允许出现在原型中。
2. 原型不是文档摘要，而是可参考的真实产品 UI 稿。
3. 列表必须有贴近业务的假数据。
4. 表单必须展示紧凑字段、输入控件、默认值或示例值。
5. 多组件页面必须按字段密度、组件大小和真实工作流布局。
6. 该有按钮、筛选、状态、禁用原因、错误反馈的地方要在原型中体现。
7. UI 风格要符合产品文档中的后台/工作台风格，不做营销页式设计。

如果原型暴露文档缺失，优先修文档，再按修复后的文档改原型。

## 5. Review 和修复闭环

对关键产品分册执行 review 时，默认按大厂 PRD 标准检查：

1. 文档边界是否正确。
2. 内容是否完整。
3. 页面、字段、操作、状态、接口是否闭合。
4. 是否存在没有业务发起人的孤儿功能。
5. 权限、审计、安全、数据边界是否可信。
6. 是否违反前序阶段已确认设计。
7. 是否引入后续阶段职责。
8. 是否有隐含架构边界或领域边界冲突。
9. 是否能直接支撑 UI 原型和后续后端接口拆解。

修复时按严重性处理：

1. P0：边界错误、越权、职责错位、无法实现、与前序结论冲突。
2. P1：字段、接口、状态、异常、审批、幂等、补偿、审计不完整。
3. P2：表达、索引、后续承接、原型便利性和长期治理项。

修复后必须做至少三类检查：

1. 当前文档 diff 检查。
2. 关键词扫描旧口径残留。
3. 接口表、页面表、覆盖表闭合检查。

## 6. 已确认的关键产品文档口径

以下口径已经在当前轮次反复确认，后续阶段必须承接。

1. 管理员控制台是治理面，不是用户创作工作台。
2. 普通用户默认从我的作品进入，作品工作台默认落在写作台。
3. 智能体工作台、知识库工作台、市场、个人中心是独立产品空间。
4. 用户也有自己的知识库管理模块，知识库也能上架市场。
5. 管理员元结构管理必须保留。
6. 大量 AI 能力是系统预编排功能链路，用户配置的是开放槽位中的子智能体替换。
7. 输入输出合规、拆分切块、入 RAG、语义安全围栏、静态检查、权限、审计、Shadow -> Canonical 等系统保护节点不可替换。
8. AI 候选、知识草稿、规划候选必须先进入待审层，用户确认后才能进入正式事实。
9. 市场购买、安装或绑定资产不等于自动写入用户作品事实。
10. New-API 是外部 LLM Gateway，Muse 直接调用其接口管理网关用户、订阅额度、余额查询和调用日志归属，不同步其路由、成本和调用日志权威数据。
11. 接口调用日志和业务审计日志要区分；所有系统接口调用要有轻量日志，高危业务动作进入 append-only 审计。
12. 权限设计要类似 yudao 的角色、权限组、菜单、页面、操作、数据范围模型，但不能形成单一超级权限。
13. 通用私有正文查看入口不进入当前管理员控制台设计。
14. 来源失效不做独立管理模块，只在引用来源处展示来源已失效、已下架、授权已撤销或需重验。

## 7. 下次继续时的执行提示

继续做下一个产品分册时，先读取：

1. `design-docs/临时-产品形态阶段化重设计计划.md`
2. `design-docs/产品-01-产品定位与核心价值.md`
3. `design-docs/产品-02-核心功能与交互边界.md`
4. `design-docs/产品-02A-统一功能规格模板与产品接口约定.md`
5. 已确认的前序分册，例如 `产品-02B`、`产品-02C`
6. 本文件

然后只修改当前阶段目标文档。若用户要求 review，则先 review 当前阶段文档；若用户要求修复，则按 review 结论修当前阶段文档；若用户要求原型，则严格按当前阶段文档生成 HTML 原型。