From b38e1d4bda51292625368877f8cb5e5765740de5 Mon Sep 17 00:00:00 2001 From: que01 Date: Sun, 20 Sep 2026 23:16:39 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E5=8A=9F=E8=83=BD?= =?UTF-8?q?=E4=BA=A4=E4=BB=98=E4=B8=8E=E8=AF=84=E5=AE=A1=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 1 + docs/engineering-delivery-checklist.md | 43 ++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 docs/engineering-delivery-checklist.md diff --git a/AGENTS.md b/AGENTS.md index 8452c30..8e58aeb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,6 +34,7 @@ - Before delivery, run relevant type checks, API integration tests, and frontend production builds. Do not claim an endpoint is delivered without a passing automated test. - Prefer cohesive commits that complete a reviewable unit of work; do not submit speculative fragments while the feature is broken. - When a code review identifies a recurring design issue, update this file or a focused architecture document before implementing the next related feature. +- Before delivery, follow `docs/engineering-delivery-checklist.md`; a feature is incomplete when its API path, failure path, data migration, client contract, UI states, or user-visible operation semantics are unverified. ## Production engineering standards diff --git a/docs/engineering-delivery-checklist.md b/docs/engineering-delivery-checklist.md new file mode 100644 index 0000000..9362094 --- /dev/null +++ b/docs/engineering-delivery-checklist.md @@ -0,0 +1,43 @@ +# Engineering Delivery Checklist + +这份清单用于功能提交前自检,尤其适用于 API、模板、后台工作台和数据库变更。完成一项功能不只意味着代码能够编译,还意味着契约、行为和失败路径已经验证。 + +## API 与授权 + +- 明确接口的认证要求、角色、品牌隔离和状态转换; +- 测试缺少凭证、凭证无效或角色错误,以及成功授权路径; +- 测试成功响应、业务校验失败和资源不存在; +- API Client 方法、请求类型、响应类型和调用页面同步更新; +- 状态码、错误 code、错误 message 和 `requestId` 符合统一响应约定。 + +## 数据与迁移 + +- Prisma schema、migration、seed、运行时代码和集成测试一起变更; +- migration 在真实本地数据库执行一次; +- 新增字段考虑默认值、旧数据兼容和回滚策略; +- 升级、回滚或删除行为明确说明是否会影响用户已经修改的数据; +- 快照、历史记录和版本字段需要有容量和一致性考虑。 + +## 模板与配置包 + +- 模板声明必须真正驱动安装和升级,不能只增加类型而保留 Controller 硬编码; +- 安装必须保存版本和配置快照; +- 升级必须有预览、显式确认和“不覆盖用户内容”的规则; +- 回滚必须明确是恢复配置基线还是删除新增数据,并在接口文案和测试中保持一致; +- 模板新增能力不得侵入个人品牌核心模型。 + +## 后台 UI + +- 覆盖 loading、empty、error、retry、success 和 mutation failure 状态; +- 失败时保留用户输入,成功后才关闭或重置表单; +- API 错误必须对用户可见,不能只出现在浏览器 Console; +- 关键操作的产品文案必须准确描述实际行为,尤其是升级、回滚、删除和发布; +- 接口路径、方法名和 API Client 在页面接入前先完成类型检查。 + +## 交付门槛 + +- 运行相关 API integration tests; +- 运行 API Client、API 和 Admin typecheck; +- 运行 Admin production build; +- 运行 `pnpm format:check` 和 `git diff --check`; +- 做一次变更范围 Code Review,确认没有“已实现但未测试”的 endpoint 或 UI 操作。