在内容生成工作流应用中，通过 OpenAPI 让后端和前端保持一致

## 每次修改后端 API 后，重新生成 OpenAPI 类型和客户端 每次修改后端API后，都要运行仓库的OpenAPI更新命令。生成的schema和前端类型属于同一次变更，不能作为以后再处理的清理工作。 前端代码必须通过生成的OpenAPI客户端调用后端端点。不得新增手写service封装，重复定义生成的请求契约和响应契约。 严格划分后端职责： - API层负责解析输入、执行身份认证和授权以及组织响应； - service层负责业务规则、状态流转和数据编排。 跨层的生成契约，包括输入DTO、输出DTO和供应商配置，应放在共享contracts模块中。task模块只应包含任务封装、分派和执行编排，不得定义共享DTO。 integration模块可以依赖共享contracts，但不得依赖task内部的类型模块。 API、类型或状态模型发生变化时，要同时更新后端实现、OpenAPI文档、生成的前端类型、客户端调用和直接相关的文档。 ## 为每个函数写注释，并把当前事实和未来计划分开写进文档 前端样式重复超过一次时，应优先抽取可复用组件或共享样式结构，而不是再次复制。 每个函数、类或同类代码块都需要注释，说明它做什么以及为什么存在。复杂逻辑还应记录相关参数、返回行为和关键内部决策。注释必须与实现保持同步。 编写前先对文档分类： - `guide`说明如何执行任务或接入功能； - `architecture`记录当前已经实现的系统； - `plans`记录未来工作、分阶段任务和拟议变更； - `reference`保存用于查阅的稳定事实； - `blog`保存发布说明。 当前边界、已实现的状态流转和实际行为应写入architecture文档。仍在设计或执行的工作应写入plans。操作步骤和开发工作流应写入guide。 不要在一篇how-to文档中混写当前事实和未来意图。即使涉及同一主题，也要分别写入architecture和plans。 除非任务明确要求，否则不得修改已经定稿的历史发布说明。 ## 让任务中心保持轻量，并让每个工作流界面各司其职 将主要用户工作流拆分为职责明确的界面： - 准备页面提取领域数据、确认候选项、修正基础信息，并将对象推进到`ready`； - 生成工作区检查产出准备度、管理关键素材和参数、启动生成并展示结果； - 任务中心只显示轻量、通用的任务信息，例如状态、进度、成功、失败、取消和返回入口。 不得把领域专用摘要、提示词调试上下文、素材映射或其他大量细节放入通用任务中心。应将这些内容保留在相应的准备、生成、执行或诊断面板中。 如果生成工作区仍保留提取工具，只能将其作为快捷入口或诊断手段。它们不得取代准备页面成为主要确认界面。 职责边界发生变化时，要同时更新相关UI和architecture文档。重新设计任务中心时，不得将其变成新的业务详情页面。 ## 对象状态只用于信息确认，不用于表示生成进度 领域对象的主状态只能用于表示信息确认状态： - `pending`表示仍有提取或确认工作未完成； - `ready`表示必需信息已经确认，可以开始后续准备。 不得使用该状态表示运行时生成状态。`generating`等值属于任务系统和runtime summary。 产出准备度应作为独立维度表示。对象对后续准备处于`ready`状态，并不保证已经满足所有生成条件。 每个用户界面都必须区分： 1. 信息确认状态； 2. 运行时任务状态； 3. 产出生成准备度。 状态语义发生变化时，要同步后端行为、OpenAPI、生成的前端类型、状态标签、导航条件和开发文档。 ## 在准备页面确认后，把用户引导到生成工作区 标准流程如下： 1. 从源内容中提取工作对象； 2. 在准备页面确认并修正提取的素材、对白或其他必需信息； 3. 进入生成工作区，检查关键素材、参考资料、产出参数和准备度； 4. 从生成工作区启动生成； 5. 在领域工作区查看结果，任务中心只用于查看通用任务进度。 准备页面负责提取、确认和修正。生成工作区负责生成准备、执行和结果查看。 准备成功后，要清楚地引导用户进入生成工作区。如果工作区发现对象尚未`ready`，应说明原因，并引导用户返回准备页面。 调整交互时要优先保证该流程。便利性快捷入口不得遮蔽规范的下一步，也不得将准备和生成合并到一个职责模糊的界面中。 ## 每次变更都更新 architecture 文档，并在发布说明中写出可直接使用的迁移步骤 architecture文档只记录当前真实生效的行为。plans记录正在推进的工作、分阶段任务、优先级和未来执行路径。 代码行为、状态语义或页面职责发生变化时，要在同一项工作中更新architecture文档。计划范围、优先级或顺序发生变化时，要更新plans。已经落地的计划应转入architecture或形成发布说明。 存在过时architecture或plans文档时，应将该项工作视为未完成。 发布说明必须包含`title`、`date`、`description`、`tags`和`authors`的frontmatter。只省略不适用的章节，并使用以下稳定顺序： 1. 重点内容； 2. 新增、变更和修复； 3. 破坏性变更和弃用项； 4. 安全事项和已知问题； 5. 迁移指南和回滚说明； 6. 兼容性矩阵、验证命令和升级检查清单； 7. 参考资料、贡献者说明和致谢。 发布说明应采用维护者发布口吻：先给出结论和可执行信息，使用短段落和列表，并保持术语稳定。要明确区分新增能力、行为变化、兼容性风险和已知问题。 迁移步骤、回滚步骤和验证命令必须能够直接使用，不能含糊。 ## 只有生成的类型和文档都与代码一致时才算完成 只有满足所有适用条件时，工作才算完成： 1. 实现已经落地，没有明显占位内容或过时兼容代码残留； 2. 新增和修改的函数及类具有准确、有用的注释； 3. API变更已经同步OpenAPI、生成的前端类型和生成客户端的调用； 4. 当前行为已反映在architecture文档中，未来工作已反映在plans中； 5. 准备、生成和任务中心的职责仍然彼此分离； 6. 前端变更通过仓库的TypeScript no-output检查； 7. 后端变更通过相关测试，或至少通过文档规定的语法和import检查； 8. 完成报告说明了变更内容和已经通过的验证； 9. 剩余工作或后续建议单独列出。 只要代码、契约、生成的类型、文档、状态语义或工作流界面之间存在不一致，就不得宣称完成。