一个小型业务系统如何做版本、测试和交付

功能完成只是交付的开始

栖光是一个小型业务系统，但它的交付问题一点也不小。它同时包含微信小程序、Node.js 后端、React 后台、MySQL 数据结构、OpenAPI 类型生成、支付退款、数据看板、优惠券、积分、存酒和后台权限。

在这种项目里，功能写完并不等于交付完成。一个接口改动可能影响 Admin 页面和小程序页面；一个订单字段调整可能影响支付、退款、积分和看板；一个数据库变更可能需要发布前 SQL、回滚说明和人工检查。

所以我更愿意把交付理解成一条链路：需求进入任务板，代码实现，接口和类型同步，自动化验证，人工验收，发布记录，剩余风险说明。缺了任何一环，项目都可能只是“能跑”，但还不能说“能交付”。

版本、测试和发布文档之间的关系图，展示交付如何从变更来源进入任务看板，再经过验证、验收、发布记录和剩余风险回流到下一版本。

任务看板让版本有边界

栖光的 docs/task-board.md 不是简单待办列表，而是按版本和任务类型组织的看板。它记录任务状态、工作流分类、变更性质、优先级、风险、并行性、写入范围、输出和完成定义。

这个结构解决了一个很实际的问题：项目越做越久，需求会不断插入。如果没有版本边界，所有事情都会堆在一起。栖光通过 V1.1、V1.2、V1.3.、V1.4 等阶段把任务收进不同版本，也明确哪些是当前版本范围，哪些是后续候选。

比如 V1.2 的目标是私域入口、优惠券、用户标签、地址簿和 Admin 官网首页；V1.4 版本则记录了积分、客户存酒、商品图片裁切、后台员工账号、后台菜单和数据看板等改动。这样回看项目时，不需要从代码里猜每一项功能是哪次迭代来的。

测试策略不是为了好看

栖光的 docs/test-strategy.md 把验证分成自动化验证、人工验收、回归检查、测试缺口和发布门槛。它有一个我很认可的原则：不把未执行的测试写成已通过，无法验证的内容必须记录为缺口或风险。

这条原则很重要。很多项目最容易在交付时说“应该没问题”，但业务系统不能只靠感觉。尤其是支付、退款、优惠券金额、数据看板口径、小程序兼容性和权限控制，只看页面不报错是不够的。

栖光里常见的自动化验证包括后端 Service 测试、后端构建、tsoa 生成、Admin generate-api、小程序 generate-api、Admin 页面契约测试、TypeScript 类型检查和生产构建。人工验收则保留给真实交互、微信开发者工具、小额真实支付或后台真实数据抽查这类自动化难以完全覆盖的部分。

数据看板重构是一条完整验证样本

2026-07-02 的后台数据看板收款口径重构，是很适合拿来说明交付链路的一次改动。

这次改动把 Dashboard 从单一营业额拆成经营指标和资金指标，同时拆出经营趋势、资金趋势、最近营业订单、最近充值和最近退款。它影响后端聚合、OpenAPI 返回结构、Admin 生成类型、Dashboard 页面展示和人工验收口径。

任务看板里记录的验证命令包括：

cd backend && npx --yes tsx --test --test-force-exit src/services/config.service.test.ts
cd backend && npm run build
cd admin && npm run generate-api
cd admin && node --test src/routes/dashboard-page.test.mjs src/routes/dashboard-filter-navigation.test.mjs
cd admin && npx tsc --noEmit --pretty false
cd admin && npm run build

这组命令覆盖了后端聚合、后端构建、接口类型同步、页面契约、类型检查和前端构建。测试策略里还补了人工验收：确认微信实收净额公式，抽查混合支付订单和部分退款订单，确认最近充值不会混入营业订单。

这就是我理解的交付闭环：自动化负责结构、构建和部分规则，人工验收负责真实业务口径。

发布记录负责把风险说清楚

除了任务和测试，栖光还有 docs/releases/。其中 1.4.0.md 记录了版本目标、新增功能、功能调整、Bug 修复、接口/数据库/配置变更、待确认事项、已知问题和发布前重点回归。

这种记录很有价值，因为它把“功能完成”翻译成“版本交付”。比如积分和客户存酒不是只写页面，它还涉及 point_records、products.is_storable、存酒批次/申请/流水表、积分补发 SQL、历史积分流水类型迁移等数据库与迁移事项。员工账号也不是只加一个页面，还涉及超级管理员判定、员工权限限制、个人信息页和改密接口。

发布记录不会让项目自动变得完美，但它能让风险可见。比如 1.4.0 里明确保留了生产微信支付真实链路联调、微信开发者工具最终人工验收、存酒商品不记录规格等待确认项。把风险写出来，比假装已经全部验证更可靠。

小型项目也应该有交付门槛

栖光不是大型团队项目，但这不代表它可以没有交付门槛。恰恰相反，个人项目更容易因为没有流程而把风险藏起来。

我现在更倾向于给小型业务系统保留几个固定门槛：接口变更必须重新生成 OpenAPI 和对应客户端；后端或 Admin 变更必须构建通过；小程序变更必须考虑微信兼容性；金额、支付、退款和看板口径必须保留人工验收；数据库变更必须有发布清单和回滚思路。

这些流程不会让项目显得笨重，反而能让我更放心地继续迭代。因为每次改动之后，我知道自己至少检查了哪些关键点，也知道还有哪些东西没有验证。