30 秒速读
- 问题
- 同一个问题三个人能报出三个数：“款”有时按款号算、有时按 SKC 算，货季又常被财年代替。
- 我做了什么
- 先写领域文档，定义术语和不变量；再用 FastAPI 与 MySQL 实现统计和按品牌、货季划分的权限，并搭起四层自动化测试。
- 结果
- 看板成了口径的唯一出处，在生产环境常驻运行；再有口径争议，直接翻文档里那一条。
| 款色 | 素材 | 生成 | 审核 | 交付 |
|---|---|---|---|---|
| 款号 A色号 01 | ✓ | ✓ | ✓ | ✓ |
| 款号 B色号 02 | ✓ | ✓ | — | — |
| 款号 C色号 01 | ✓ | — | — | — |
基于案例逻辑重绘的交互示意，非真实系统截图示例素材与状态
01 · 背景与目标
同一个问题，三个人能报出三个数
上游有多条自动化链路在往库里写生产记录，业务同事想知道「这个货季做了多少款」，却拿不到一致的答案 —— 因为「款」有时按 9 位款号算，有时按 12 位 SKC 算；而「货季」又常被人用财年代替，可同一个财年里其实装着两个货季。
目标不只是做一个能看的页面，而是让这个页面成为口径的唯一出处：同一个指标只有一种算法，边界情况有明确归属，任何人看到的都是同一个数。
02 · 我的工作
我的工作：把业务规则从代码里提出来
领域建模
写一份领域上下文文档，定义术语、列出不变量、划清系统边界，让规则先于实现存在。
后端实现
基于 FastAPI 与 MySQL 实现统计、筛选、备注、图片与计划量管理。
权限体系
设计按品牌与货季划分的数据范围，并让所有读写路径统一服从同一套判定。
质量与运维
搭四层自动化测试与持续集成，编写部署与运维手册，让它能长期无人值守地跑。
03 · 建设路径
从术语表到常驻服务
先定义，再写代码
把款号与 SKC、货季与财年这些天天混用的词逐个钉死定义，写成一份领域上下文文档，再开始做功能。
不变量清单
把「不能发生什么」写成七条显式不变量，例如同一个 SKC 全局只归属一个货季，一旦登记不许在别的货季复用。
脏数据不静默兜底
无效编码一律不许截断、补齐或去空格后入库。历史脏数据先完整隔离，再从在线表移除，而不是就地改对。
数据范围权限
按品牌与货季给账号设可见范围，列表、统计、导出、图片和写操作一律服从。自动注册只能产生只读账号。
四层测试与部署
静态检查、单元测试、连真实数据库的集成测试、浏览器冒烟测试四层并行，注册为系统服务常驻运行。
口径先于代码：款号与 SKC 不是一回事，货季与财年也不是。
04 · 四层测试
一次改动，四层测试并行把关
- 静态检查
- 单元测试
- 集成测试连真实数据库
- 冒烟测试在浏览器里
四层并行跑，任何一层不过，这次改动就不上线
依据：该子项目的持续集成配置。
05 · 复盘与演进
写下来的规则，比记在脑子里的规则便宜
最有价值的决定
先写领域文档再写功能。后来每次口径争议，都能直接翻到那一条，而不是重新讨论一遍。
刻意选的笨办法
宁可让计算失败也不猜：跨年度统计缺少官方日历时直接报错要求补齐，而不是自行推断节假日。
下一步
把仍跟着代码发版的货季规则抽成独立的规则注册表，让口径调整不必重新发布整个服务。