79 lines
6.3 KiB
Markdown
79 lines
6.3 KiB
Markdown
# 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 驱动最终生成页面,验证日程、配送、流程和咨询字段;
|
||
- 数据迁移必须备份、限定品牌、保留历史提交和旧发布快照,并验证重复执行不产生重复内容。
|