历史 · 需求、设计、原型与 API 实施流程

历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。

本流程适用于所有活跃仓库，由本人统一决策和验收。当前优先完成需求、设计与原型；已有实现先审查复用，只补差距。本页定义统一格式，各平台具体用户、页面和能力维护在自己的实施页。

七项工作与完成条件

工作	要回答的问题	交付物	完成条件
需求确定	谁在什么情况下完成什么，首期做到哪里	用户、场景、功能清单、首期/后续/不做、验收场景、待决策项	本人确认首期范围；现有能力与新需求分开；未知不伪装成定案
产品 / 服务设计	用户怎样走完任务，系统怎样承载	信息架构、旅程、页面/服务、数据与状态、权限、跨平台交接	每个动作有负责仓库和来源；共享设计一致，特例有理由
原型设计	交互与状态是否支持任务	可点击流程或时序/状态机/fixture，预览与场景清单	关键流程可走查；正常、空态、异常、无权限、未接入有解释
后台 API 设计与开发	查询/命令/事件如何支持原型、持久化和恢复	能力清单、契约、数据/Repository、鉴权、错误与测试	实现符合契约；正常与拒绝真实；幂等和恢复按能力验证
API 文档	消费方如何正确且可验证地使用接口	OpenAPI/Schema、鉴权、参数/响应、错误、示例、版本与限制	示例可复现；未实现标设计中；公开内容不泄漏内部信息
前端实现与联调	页面是否忠实反映真实数据	组件、BFF/适配、浏览器/集成报告、原型差异	任务与接口一致；替身/真实调用分开；跨平台入口不中断
验收与发布	完成到哪层，能否上线和回滚	本地报告、决定、版本/制品、环境与回滚说明	需求/原型/代码/联调/生产分别接收，生产动作按授权执行

后台 API 包括产品 BFF、Core 私有服务、公共 API Edge 和 Gateway 执行接口，不能全部塞进 Admin。Admin 是员工后台界面与 BFF；服务仍由相应仓库负责。

需求文档最小内容

每个活跃仓在现有 PRD 或 docs/planning/requirements.md 维护以下内容。已有文档直接引用并补差距，不强制另建同名文件：

目标用户 / 首要任务 / 要解决的问题
现有能力与来源版本 / 当前不足
首期范围 / 后续范围 / 本期不做
用户故事及可观察的验收条件
功能：已有可复用 / 需要修改 / 需要新增 / 待确认
角色权限 / 数据归属 / 跨平台交接
异常恢复 / 非功能要求（按场景填写，不编造性能指标）
待决策项 / 本人决定 / 版本与更新时间

功能使用稳定需求 ID，关联设计、原型场景和 API 能力。数字指标、计费策略、域名、身份服务选型和商业承诺没有依据时标记待确认，不由原型替本人定案。

产品设计与原型标准

设计稿至少包含入口、导航、页面职责、操作、状态与反馈。品牌、字体/token、共享组件从 Design 获取，业务页面留在产品仓。

关键任务覆盖首次进入、已有数据、加载/空态、提交/处理/成功、失败后的下一步、未登录/无权限/资源不存在/未接入，以及刷新返回后的恢复。检查桌面与窄屏、键盘焦点和基础可访问性。

可复用已有页面补状态，无需重新画所有静态图。本地假数据可用于原型，但说明和报告必须标明；正式页面不能用假成功或虚构余额代替真实 API。

原型交付通过 prototype-manifest 或等价说明登记：源文件、启动命令/预览地址、页面/场景、数据模式、缺口、本人意见和版本。临时 localhost 地址会失效，必须同时保留可重启文件与命令。

无 UI 服务用拓扑、时序、状态机、请求/响应草稿和可执行 fixture 作为原型，不必新建管理界面。Design 原型是组件/流程样板，Docs 原型是文档导航、检索与接口参考页。

API 能力清单

在现有文档或 docs/planning/api-inventory.md 维护下列字段。未确认路径时写能力名称与“路径待定”，不编造已存在的 endpoint。

字段	要求
需求 / 原型场景	稳定 ID 与文件引用
能力与类型	查询、命令、事件、流式/异步，是否有副作用
服务 Owner / 消费方	具体仓库和模块，不能只写后端
生命周期	需求中、设计草稿、已发布规范、已实现、已联调、已部署
资源与身份	数据归属、Customer/Workforce/Workload、权限和范围
请求响应	字段、单位、校验、可空/缺失、分页/排序、稳定 ID
失败恢复	错误码、拒绝副作用、幂等、重试、超时/取消、未知状态
规范来源	Contracts 固定版本或明确草稿，产品内部接口由产品维护
实现文档	源码、参考页、例子、测试
接入前置	身份、Owner、环境、Schema/版本与缺口

页面可提前审查 view model 和协议草稿；正式消费者仍用固定契约。展示模型不是跨仓 DTO，不通过本机路径导入其他仓业务源码。

API 文档与规范分工

类别	规范 / 实现	文档承载与必备内容
公共机器 API	Contracts / API Edge / Core	Console 公开开发者入口组织，Docs 提供帮助；认证、准入/执行区别、幂等、错误、示例、限制与版本
产品 BFF	产品仓，跨仓 DTO 引用 Contracts	产品开发文档；Session/Origin、字段、分页、错误、Owner 和未接入限制
内部服务 / 事件	Contracts / 运行仓	仓内工程文档及适合公开的架构说明；audience/scope、状态机、事务、重放、完整性与兼容
组件 / 工具 / 配置	Design / Infrastructure / Docs	对应仓文档；props/token、CLI/配置、用例、版本与边界，不伪装业务 REST API

需求时建立文档目录；设计时写规范草稿和例子；开发时校验文档与类型；联调时运行例子并保存结果；发布时固定版本与弃用说明。一个接口明确一个规范源，说明页引用它，不复制维护第二份 Schema。内部接口资料不因进入文档计划而自动公开发布。

从原型拆开发包

按一个可验收用户任务纵向切片：需求/原型 → 最小 API → 数据/权限 → 页面 → 文档例子 → 验收。先复用代码和测试，再补差异。

例如 Console 可以先接真实目录，再接身份和 Key，最后按已实现能力接用量与执行。原型可先走查完整流程；真实 Key 创建与模型执行分别等待自己的接口条件。

不按仓库平均分开发量，不要求全部后台一起开工。已有在途工作保留版本和状态，新开发顺序在原型确认后安排。

首轮统一决定清单

主题	需确认的内容
跨平台入口	Site、Console、Studio 入口/返回路径与现有差异
身份与开发区	登录方案、Key/用量现有 Owner、目标接口与旧入口保留条件
首期范围	各平台一个核心任务及不做范围，不能从架构模块数倒推必做功能
Drama V2	独立仓视频段下载交付与旧架构合成/Shot 术语差异；Studio 短剧继续保留
Commerce	工具 MVP 与商品/活动流程如何分期，不把 mock 当真实后端
统一设计	采用规范版本、共享壳/组件和产品特例
API 文档	四类接口目录、规范源、版本与可执行示例

决定存于本机工作台，绑定文件版本。此清单列出待确认内容，不代替具体产品需求的确认。