137 lines
7.3 KiB
Markdown
137 lines
7.3 KiB
Markdown
# 产品文档管理步骤
|
||
|
||
- 日期：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 原型。
|