oh-my-muse/design-docs/产品-02A-统一功能规格模板与产品接口约定.md

产品-02A：统一功能规格模板与产品接口约定

• 版本：v1
• 更新日期：2026-05-22
• 目标读者：产品 / 交互 / 前端 / 后端 / 测试
• 阅读时间：15-25 分钟
• 边界说明：本文件承接 产品-01 和 产品-02，定义 产品-02B~02G 的统一写法。它不直接列完所有功能，不写代码级 API、数据库字段或路由细节；它规定每个功能规格必须写到什么粒度，确保后续分册能支撑 UI 原型、接口设计、测试验收和后续旅程文档。

0. 前序继承

阶段 2.1 必须继承以下结论：

1. 产品-01 已锁定 Muse 的产品定位、六个产品空间、用户主权、市场资产边界和长期知识闭环。
2. 产品-02 是功能边界总纲，负责六个产品空间的职责、权限、交互边界和非谈判项。
3. 产品-02B~02G 是详细功能规格，必须回答“有哪些页面、页面有什么内容、用户看到什么数据、可以做什么操作、需要什么产品接口”。
4. 本阶段仍属于产品需求层，不进入 产品-03 的旅程步骤、不进入 流程-* 的系统处理细节、不进入 后端-* 的代码级 API 或 Schema。
5. 后续详细规格必须能作为前端 UI 原型的直接输入，但不能为了画页面而破坏 产品-02 的权限、授权、Shadow/Canonical、stale guard 和市场资产不污染作品事实等边界。

1. 文档目标

产品-02A 解决一个问题：阶段 2 的详细功能规格不能各写各的。

后续每个空间分册必须使用同一套结构描述：

• 功能模块是什么。
• 页面是什么。
• 页面展示什么数据。
• 用户可以执行什么操作。
• 操作后进入什么状态。
• 失败、空态、禁用态如何呈现。
• 当前页面需要哪些产品接口。
• 这些产品接口的输入、输出、权限、状态和副作用是什么。

这里的“产品接口(Product Interface)”不是后端 endpoint，也不是数据库表字段。它是产品层合同：前端、后端、测试和后续架构文档都能基于它继续细化，但不能反向改变产品语义。

2. 产品-02 系列文档组织

文档	文档性质	负责什么	不负责什么
产品-02	总纲	六个产品空间、边界、权限、统一交互规则、非谈判项	不展开所有页面和接口
产品-02A	规格模板	统一详细功能规格和产品接口写法	不替各空间列具体页面
产品-02B	管理员控制台规格	管理员页面、数据、操作、分权、审计、治理接口	不进入普通用户创作旅程
产品-02C	用户工作区与作品工作台规格	我的作品、写作台、规划、知识、导入导出、记录用量	不承载完整智能体/知识库/市场后台
产品-02D	智能体工作台规格	智能体创建、配置、安装、替换槽位、试用、发布	不允许用户接管系统保护节点
产品-02E	知识库工作台规格	全局/用户/账户可用/已安装知识库、处理状态、绑定、发布	不直接修改作品局域知识库事实
产品-02F	市场规格	资产发现、详情、授权、安装、绑定、发布、审核、下架	不承诺完整电商、支付、结算、DRM
产品-02G	个人中心规格	账户、偏好、用量、权益、授权记录、发布记录总览	不替代各业务空间后台

阶段 2 必须先完成 产品-02A，再按 02B -> 02C -> 02D -> 02E -> 02F -> 02G 顺序补齐详细规格。不能跳过前序空间，也不能在后续分册里反向修改已确认总纲。

3. 功能规格统一模板

每个 产品-02B~02G 分册必须按以下结构编写。

3.1 功能模块总览

每个空间先列功能模块总表。

字段	写法要求
模块名称	使用产品语言，必要时附英文锚点
目标用户	管理员、普通用户或两者
模块目标	一句话说明用户为什么需要它
默认入口	从哪个导航、页面、对象或状态进入
核心对象	该模块围绕哪些产品对象工作
主要页面	列出本模块涉及页面
核心操作	列出用户能做的主动作
关键状态	列出影响展示和操作的状态
依赖接口	列出本模块需要的产品接口名称
边界	明确本模块不做什么

模块总览用于快速判断功能是否完整，不能只写概念描述。

3.2 页面清单

每个空间分册必须先给页面清单，再展开单页规格。

页面 ID	页面名称	使用角色	页面目标	默认入口	主要操作	关键状态
示例：work-list	我的作品	普通用户	找到并进入作品	登录后默认入口	新建、导入、打开、筛选	空列表、加载失败、待处理风险

页面 ID 是产品规格内的稳定标识，不等于前端路由名。后续前端可以基于它设计路由、组件和原型。

3.3 单页规格

每个页面必须使用以下模板。

项目	必填内容
页面目标	用户来到这个页面要完成什么
使用角色	哪些角色可见，是否需要管理员分权
入口来源	从哪些页面、对象、通知、跳转进入
返回规则	完成、取消、失败后回到哪里
页面区域	页面有哪些固定区域、列表、面板、抽屉、弹窗
可见数据	用户默认能看到哪些字段和摘要
主操作	页面上最重要的 1-3 个动作
次操作	搜索、筛选、排序、查看详情、复制、重试等
危险操作	删除、撤权、下架、封禁、召回、覆盖、批量确认
状态	正常、加载、空态、失败、无权限、部分可用、只读、过期
权限	谁能看、谁能操作、哪些字段脱敏或隐藏
产品接口	查询、命令、任务、授权、审计等接口
埋点与审计	哪些操作必须记录，普通用量和管理员审计如何区分
验收要点	用什么结果判断页面规格实现正确

单页规格必须能让前端据此画原型。不能只写“展示列表”“支持管理”这类不可执行描述。

3.4 页面区域规格

复杂页面必须拆页面区域。

区域	显示内容	用户操作	数据来源	状态与异常
顶部摘要	当前对象名称、状态、风险、最近更新时间	返回、刷新、进入设置	对象详情查询	无权限、对象不存在
主列表	卡片或表格数据	搜索、筛选、排序、分页、打开详情	列表查询	空态、加载失败
右侧决策区	候选、风险、来源、建议	接受、修改、丢弃、查看来源	候选详情查询	过期、撤权、阻断

区域规格用于避免页面只剩抽象功能名。凡是影响用户判断的区域，都必须说明显示什么和可以做什么。

3.5 操作规格

每个重要操作必须写成可验收的产品动作。

字段	写法要求
操作名称	使用用户可见动作词，如“确认”“丢弃”“绑定”“下架”
操作入口	按钮、菜单、批量操作、详情页、弹窗、快捷动作
前置条件	角色、状态、授权、来源、版本、对象是否可用
操作确认	是否需要确认弹窗、风险说明、二次输入
操作结果	成功后改变什么状态或产生什么对象
副作用	是否触发任务、审计、通知、用量、授权快照、来源状态更新
失败反馈	用户看到什么原因，可以怎么处理
回滚或补偿	是否允许撤销、回退、重试、申诉

涉及正文、知识、授权、市场资产和管理员处置的操作，必须写清楚副作用，不能只写“保存成功”。

4. 产品接口约定

4.1 产品接口分类

后续分册中的接口按产品语义分类，不按技术形态分类。

接口类型	作用	示例
查询接口(Query)	获取页面展示数据，不改变业务状态	查询作品列表、查询智能体详情、查询市场资产详情
命令接口(Command)	用户发起一次状态改变	新建作品、保存规划项、安装智能体、下架资产
决策接口(Decision)	用户对 Shadow、候选、知识草稿或风险项做取舍	原样接受、修改后合并、确认知识、忽略草稿
任务接口(Task)	发起、查询、取消或重试异步处理	发起全书解析、查询资料处理状态、取消生成
授权接口(Authorization)	获取、安装、绑定、解绑、撤权、检查许可	获取市场资产、绑定知识库、检查智能体可用性
来源接口(Source)	展示来源、版本、授权快照和外发范围	查询候选来源摘要、查询授权快照
质量接口(Quality)	展示质量评分、风险、创作健康度和建议	查询候选质量结果、查询一致性检查结果
用量接口(Usage)	展示 Token、配额、待结算和已结算口径	查询作品用量、查询账户用量
审计接口(Audit)	管理员或系统追踪治理操作	查询审计摘要、记录下架原因
选项接口(Option)	获取下拉、筛选、可用动作、可替换槽位	查询可用智能体、查询可绑定知识库

产品接口命名建议使用“动词 + 对象 + 目的”的中文名，例如“查询作品列表”“绑定知识库到作品”“发起全书解析”。后端 API 命名可在后续 后端-* 中另行收敛。

4.2 产品接口规格模板

每个产品接口必须写清以下内容。

项目	必填内容
接口名称	产品层稳定名称
接口类型	查询 / 命令 / 决策 / 任务 / 授权 / 来源 / 质量 / 用量 / 审计 / 选项
使用页面	哪些页面或区域调用它
用户意图	用户为什么触发或需要它
输入上下文	账户、角色、作品、对象、筛选、分页、授权快照、来源版本等
返回内容	页面需要展示的数据，不写数据库字段
权限规则	谁能调用，哪些内容脱敏，哪些状态禁用
状态变化	如果会改变状态，说明从什么状态到什么状态
副作用	是否写 Shadow、Canonical、Archive、任务、审计、用量或授权快照
失败类型	无权限、对象不存在、版本过期、授权失效、任务失败、合规阻断等
用户反馈	失败或部分成功时页面怎么提示
审计要求	是否记录操作者、理由、范围、时间、前后状态
后续承接	需要由 产品-03、流程-*、架构-*、后端-* 承接的内容

4.3 产品接口示例

以下示例只定义产品层合同，不代表最终后端 API。

示例 1：查询我的作品列表

项目	内容
接口名称	查询我的作品列表
接口类型	查询接口(Query)
使用页面	我的作品
用户意图	用户登录后找到要继续写作的作品
输入上下文	当前账户、筛选条件、排序、分页
返回内容	作品卡片、最近编辑时间、字数、章节数、状态、待确认知识数量、最近失败任务摘要
权限规则	只返回当前用户拥有或有权访问的作品
状态变化	无
副作用	无；不能因查询触发知识入库或生成
失败类型	登录失效、加载失败、无权限
用户反馈	提示重试、重新登录或显示空态引导
审计要求	普通查询不进入管理员审计；异常访问需进入安全日志

示例 2：原样接受 AI 候选

项目	内容
接口名称	原样接受 AI 候选
接口类型	决策接口(Decision)
使用页面	写作台候选决策区
用户意图	用户确认候选文本可以进入正文
输入上下文	当前账户、作品、章节、文本块、候选、来源快照、授权快照
返回内容	合并后的正文状态、版本记录、候选归档状态、知识变更状态
权限规则	用户必须有当前作品编辑权限；候选未过期且未撤权
状态变化	AI 候选从 Shadow 进入 Archive 的已接受记录；正文进入 Canonical 和版本历史
副作用	可异步产生知识草稿；知识草稿仍需用户确认，不能自动进入局域知识库
失败类型	候选过期、授权失效、文本块冲突、合规阻断
用户反馈	提示重新生成、刷新正文、查看来源或手动复制
审计要求	记录用户决策、候选版本、来源摘要、正文版本

示例 3：绑定知识库到作品

项目	内容
接口名称	绑定知识库到作品
接口类型	授权接口(Authorization)
使用页面	作品工作台的知识来源、知识库工作台的绑定入口、市场资产详情
用户意图	用户希望某个知识库成为当前作品的检索或生成来源
输入上下文	当前账户、作品、知识库、授权快照、用途范围、是否允许进入模型上下文
返回内容	绑定状态、可用范围、版本、冲突策略、是否可关闭或降权
权限规则	用户必须拥有作品权限和知识库使用许可
状态变化	知识库从账户可用或已安装状态进入作品绑定状态
副作用	后续生成可引用该来源；不能写入局域知识库，不能覆盖作品事实
失败类型	授权失效、知识库下架、处理状态不可用、用途不允许生成
用户反馈	显示不可绑定原因、替代来源或稍后重试
审计要求	记录绑定操作者、作品、知识库版本、授权快照和用途

5. UI 原型生成要求

产品-02B~02G 必须写到可以生成低保真 UI 原型的程度。每个页面至少要能回答：

1. 页面标题是什么。
2. 用户从哪里进入。
3. 页面默认第一屏显示什么。
4. 有哪些主要区域。
5. 每个区域展示哪些数据。
6. 主按钮和危险按钮是什么。
7. 哪些操作是折叠、弹窗、抽屉或详情页。
8. 空态、失败态、无权限态、只读态、过期态怎么表现。
9. 哪些状态下按钮不可用。
10. 点击主操作后页面如何反馈。

页面规格不要求定义视觉风格、组件库、颜色、间距和具体路由。这些由后续前端文档或 UI 原型阶段承接。

如果当前阶段同步产出 HTML 原型，HTML 原型不能只是规格摘要或页面清单浏览器，必须至少满足以下验收合同：

1. 默认视图必须符合目标用户主路径，不能把默认隐藏、折叠或后续阶段能力做成第一屏主入口。
2. 每个核心页面至少展示正常态、空态、失败态、无权限态、只读态、提交中、过期/撤权/来源失效态中的相关状态。
3. 高危操作必须展示确认、影响预览、成功反馈和失败恢复；不能只放一个危险按钮。
4. 被 PRD 禁止的动作在原型中必须禁用或隐藏，并显示可行动原因。
5. 普通用户界面不得直接暴露 handoff session、precheckId、publishCheckId、Tool Grant、TestRunOutput 等技术合同名；这些只能进入调试详情、管理员审计或 PRD 接口说明，用户界面需转成产品语言。
6. 原型不得恢复已删除、暂缓或后续阶段承接的功能入口。
7. 响应式、键盘焦点、按钮尺寸、文本溢出和禁用态必须足以让前端判断布局约束。

6. 状态、权限和异常写法

6.1 状态必须贴近用户决策

状态不能只写系统状态码。普通用户页面必须用用户能理解的状态，例如：

• 资料处理中。
• 可以用于生成。
• 来源已变化。
• 授权已失效。
• 待确认知识。
• 候选已过期。
• 需要重新生成。
• 已下架，不能继续用于生成。

管理员页面可以显示更精确的任务、审计和治理状态，但也必须给出可行动解释。

6.2 权限必须区分可见、可操作和可导出

每个页面和接口都要区分：

• 能否看到入口。
• 能否看到列表项。
• 能否看到详情。
• 能否看到正文级或内容级字段。
• 能否执行操作。
• 能否导出。
• 能否发布到市场。
• 能否进入模型上下文。

不能只写“有权限 / 无权限”。

6.3 异常必须给用户下一步

异常反馈必须包含：

• 发生了什么。
• 当前事实是否已经改变。
• 用户可以怎么处理。
• 是否需要联系管理员或等待系统处理。

例如生成失败时必须说明“当前正文未改变”；撤权失败时必须说明“该来源不能继续用于生成”；知识草稿过期时必须说明“需要重新提取或手动处理”。

7. 跨空间跳转写法

跨空间动作必须写清楚跳转合同：

字段	说明
来源空间	从哪个空间、页面、对象出发
目标空间	去哪个空间完成什么
携带上下文	账户、作品、资产、授权、返回点
完成后返回	成功后回到哪里，页面如何刷新
失败后回退	权限不足、取消、对象不可用时回到哪里
不能做什么	不能在当前空间展开完整后台，不能自动作用到作品

示例：从写作台选择市场知识库，只能跳到市场或知识库工作台完成获取、安装或绑定；完成后回到当前作品的知识来源区域。没有完成绑定前，市场知识库不能进入当前作品生成上下文。

8. 后续分册的最低交付标准

每个 产品-02B~02G 分册完成时，必须满足：

1. 有模块总览。
2. 有页面清单。
3. 每个核心页面有单页规格。
4. 每个核心操作有操作规格。
5. 每个页面列出需要的产品接口。
6. 产品接口按本文件模板写清输入上下文、返回内容、权限、状态变化、副作用和失败反馈。
7. 明确空态、失败态、无权限态、只读态、过期态。
8. 明确跨空间跳转和返回规则。
9. 不引入 产品-02 已禁止的越权能力。
10. 能被前端用于低保真 UI 原型生成；如同步产出 HTML 原型，必须满足第 5 节的 HTML 原型验收合同。

如果某个空间分册只列概念、不列页面和接口，则不能视为阶段 2 完成。

9. 非谈判项

• 详细功能规格不能反向修改 产品-01 和 产品-02 已确认边界。
• 页面规格不能只写“管理、配置、查看、处理”，必须写清楚用户看到什么和能做什么。
• 产品接口不能直接退化成后端 endpoint 列表，也不能只写“调用后端接口”。
• 查询接口不能产生业务副作用。
• 命令、决策、授权和任务接口必须写清状态变化、副作用、失败反馈和审计要求。
• 涉及正文、作品知识、规划正式项、市场资产、管理员处置的操作，必须说明是否影响 Shadow、Canonical、Archive。
• 涉及市场资产、全局知识、用户知识库、用户智能体的功能，必须说明授权快照、来源版本和撤权/下架后的影响。
• 涉及模型调用或外部上下文的功能，必须说明最小必要、来源可解释、是否可关闭和是否保存全文快照。
• 用户工作区必须保留 no-config 主路径，详细页面不能把智能体、知识库或市场配置变成写作前置条件。

10. 后续写作顺序

下一步按以下顺序完善：

1. 产品-02B-管理员控制台功能规格.md
2. 产品-02C-用户工作区与作品工作台功能规格.md
3. 产品-02D-智能体工作台功能规格.md
4. 产品-02E-知识库工作台功能规格.md
5. 产品-02F-市场功能规格.md
6. 产品-02G-个人中心功能规格.md

每完成一个分册，都要回到本文件检查模板覆盖，再进入下一个分册。