Files
persionalBrand/docs/engineering-delivery-checklist.md

79 lines
6.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Engineering Delivery Checklist
这份清单用于功能提交前自检,尤其适用于 API、模板、后台工作台和数据库变更。完成一项功能不只意味着代码能够编译,还意味着契约、行为和失败路径已经验证。
## API 与授权
- 明确接口的认证要求、角色、品牌隔离和状态转换;
- 测试缺少凭证、凭证无效或角色错误,以及成功授权路径;
- 测试成功响应、业务校验失败和资源不存在;
- 新增、删除或调整任意 Controller route 时,同步更新 `apps/api/test/route-coverage.matrix.ts`,并运行 `pnpm test:api-routes`;矩阵必须由 NestJS metadata 动态发现结果校验,禁止依赖手工维护的路由清单自证;
- 发布与撤回类端点还需覆盖并发版本分配、发布快照与客户提交的一致性;
- API Client 方法、请求类型、响应类型和调用页面同步更新;
- 状态码、错误 code、错误 message 和 `requestId` 符合统一响应约定。
## 数据与迁移
- Prisma schema、migration、seed、运行时代码和集成测试一起变更;
- migration 在真实本地数据库执行一次;
- 新增字段考虑默认值、旧数据兼容和回滚策略;
- 升级、回滚或删除行为明确说明是否会影响用户已经修改的数据;
- 快照、历史记录和版本字段需要有容量和一致性考虑。
## 模板与配置包
- 执行 pnpm template:doctor 并遵循 [模板完成度规则](template-completion-rules.md),诊断未解决项和未验证项不能视为完成;
- 模板声明必须真正驱动安装和升级,不能只增加类型而保留 Controller 硬编码;
- 每个页面上的品牌事实、信任资料、业务详情和可编辑文案都必须来自 Runtime 数据,并在同一页面声明对应 Admin editor binding;`pnpm validate:templates` 的逐页 renderer / editor 契约测试通过后才能判定模板完成;
- 每种模板信任内容必须声明实际展示页面,逐页测试要同时验证“声明的类型有 renderer 消费”和“renderer 使用的类型已声明”;
- 新模板必须由 package-discovered 测试自动纳入,不得只给现有模板写专用断言;
- 信任内容类型必须在 manifest 声明 `title`、`summary`、`content` 对应的 Admin 字段标签;API 按当前品牌 manifest 校验类型,不能在 DTO 中固定模板类型枚举;
- 模板数据存储与发布映射遵循 `docs/template-data-flow.md`,信任内容和咨询表单分别使用 `TrustContent` 与 `InquiryForm`;
- 安装必须保存版本和配置快照;
- 升级必须有预览、显式确认和“不覆盖用户内容”的规则;
- 回滚必须明确是恢复配置基线还是删除新增数据,并在接口文案和测试中保持一致;
- 模板新增能力不得侵入个人品牌核心模型。
## Taro 模板双端验收
- 构建任意 Taro 模板小程序时使用真实发布参数,并保留命令证据:
`TEMPLATE_KEY=<template-key> API_BASE_URL=<production-api> WEAPP_APP_ID=<appid> pnpm --filter @personal-brand/taro build:weapp`;
- 小程序和 H5 必须分别构建并归档到 `apps/taro/dist/<templateKey>/weapp` 与 `apps/taro/dist/<templateKey>/h5`;产物契约测试通过;
- 产物检查必须覆盖:`project.config.json` 的 AppID、请求内嵌的 `API_BASE_URL`、`/media/` 相对地址补全结果、`common.wxss` 中的按钮规则;
- 产物不得出现 Taro 指纹:`build:weapp`、`build:h5`、`build:preview`、后台静态产物必须走包内脚本(`pnpm build:admin:preview` 或 `pnpm deploy:package`,构建后处理与打包门禁失败都会中断),必要时用 `node config/mask-taro.cjs <weapp|h5|admin> --check` 复核;改名规则只改 `apps/taro/config/mask.config.json`;
- 涉及 `Button`、`Input`、`Textarea`、`Picker` 等原生控件时,源码和产物都要核对;禁止只依据 H5 预览判定小程序样式;
- 按页面角色检查视觉点,不按模板名称写专用清单,并记录截图或说明未改动原因:
- 首页:媒体加载、横向间距、标签换行、整卡点击;
- 列表页:卡片宽度、媒体高度、空态和点击目标;
- 详情页:主行动按钮全宽、默认高度 88rpx、文字垂直居中,安全区不被遮挡,底部说明不被遮盖;
- 个人页:紧凑行动按钮高度由模板令牌定义、文字垂直居中、拨号/复制可点;
- 表单页:提交按钮全宽、88rpx 高、文字垂直居中,错误和重试可见;
- 微信真机:request/media 域名、登录、拨号、复制、滚动和底部安全区;
- 模板自定义尺寸必须通过共享 CSS 变量声明,不把 `46rpx`、`88rpx` 这类值散落在多个模板里;
- 产物级断言只能证明配置和规则存在,不能替代真实数据驱动的页面截图;最终视觉证据必须来自微信开发者工具或真机。
## 后台 UI
- 覆盖 loading、empty、error、retry、success 和 mutation failure 状态;
- 失败时保留用户输入,成功后才关闭或重置表单;
- API 错误必须对用户可见,不能只出现在浏览器 Console;
- 关键操作的产品文案必须准确描述实际行为,尤其是升级、回滚、删除和发布;
- 接口路径、方法名和 API Client 在页面接入前先完成类型检查。
## 交付门槛
- 运行相关 API integration tests;
- 集成测试须使用独立 schema 或数据库;不得在默认测试命令中重建开发品牌数据;
- 运行 API Client、API 和 Admin typecheck;
- 运行 Admin production build;
- 运行 `pnpm format:check` 和 `git diff --check`;
- 做一次变更范围 Code Review,确认没有“已实现但未测试”的 endpoint 或 UI 操作。
## 固定视觉区域与旧数据验收
- 必填视觉区域不由任意记录数量决定布局;缺少实际展示字段或重复公开记录必须阻止发布;
- 结构化内容完整性由 manifest 声明判定,后台和发布端共用规则;隐藏字段不能仍被要求必填;
- 对照原型检查子卡数量、内容层次和文字换行,源码匹配不视为视觉验收;
- 使用当前数据库通过发布 API 驱动最终生成页面,验证日程、配送、流程和咨询字段;
- 数据迁移必须备份、限定品牌、保留历史提交和旧发布快照,并验证重复执行不产生重复内容。