358 lines
20 KiB
Markdown
358 lines
20 KiB
Markdown
# 产品-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`
|
||
|
||
每完成一个分册，都要回到本文件检查模板覆盖，再进入下一个分册。
|