陆怀瑾
315 lines
13 KiB
Markdown
315 lines
13 KiB
Markdown
# BIZ-101「记录-比对 中奖金额展示」全链路经验沉淀
|
||
|
||
> **沉淀人**：陆怀瑾（COO）
|
||
> **沉淀时间**：2026-09-05 10:00 GMT+8
|
||
> **来源**：BIZ-101 → BIZ-102/103/105/106/107 全链路归档（用户 09:42 GMT+8 验收签字闭环）
|
||
> **目标读者**：所有 agent（重点：productmanager / costcodev / opengineer / architect / designer / secretary）
|
||
> **存储**：本仓库 `experiences/` → 待同步至 Gitea `EnterpriseArchitect` + SiYuan 知识库
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
| 维度 | 内容 |
|
||
|------|------|
|
||
| 项目代号 | BIZ-101 |
|
||
| 业务目标 | webui「记录-比对」功能增加中奖金额展示与按奖项汇总 |
|
||
| 启动时间 | 2026-08-30 03:10 GMT+8 |
|
||
| 验收闭环 | 2026-09-05 09:42 GMT+8 |
|
||
| 实际周期 | ~6 天（含 2 个 P0 修复 + 5 天等用户验收） |
|
||
| 团队 | COO + productmanager + costcodev + opengineer + designer + architect |
|
||
| 关键交付 | PRD v1.2 + UI 原型 + 后端扩展 + 前端适配 + 单测 + 部署 + 验收 |
|
||
|
||
---
|
||
|
||
## 二、业务需求沉淀
|
||
|
||
### 2.1 用户故事（US）
|
||
|
||
| ID | 故事 | 优先级 |
|
||
|----|------|--------|
|
||
| US-01 | 运营/刘总 查看某次比对的「总中奖金额」 | P0 |
|
||
| US-02 | 运营/刘总 查看按奖项分组的「x 注 y 等奖共 z 元」汇总 | P0 |
|
||
| US-03 | 运营/刘总 在每注详细比对中看到该注中奖金额 | P0 |
|
||
|
||
### 2.2 双色球官方奖级口径（业务事实）
|
||
|
||
| 奖项 | 中奖条件 | 单注金额 | 浮动？ |
|
||
|------|----------|---------|--------|
|
||
| 一等奖 | 6 红 + 1 蓝 | 浮动 | ✅（按奖池 80%） |
|
||
| 二等奖 | 6 红 + 0 蓝 | 浮动 | ✅（按奖池分配） |
|
||
| 三等奖 | 5 红 + 1 蓝 | 3,000 元 | ❌ |
|
||
| 四等奖 | 5+0 / 4+1 | 200 元 | ❌ |
|
||
| 五等奖 | 4+0 / 3+1 | 10 元 | ❌ |
|
||
| 六等奖 | 2+1 / 1+1 / 0+1 | 5 元 | ❌ |
|
||
|
||
**关键决策**：一/二等奖因历史 xlsx 数据不含奖池字段，**不臆造金额**，统一显示「浮动」+ 橙色 `#e67e22` 视觉标识。
|
||
|
||
### 2.3 业务约束
|
||
|
||
1. **向后兼容**：不破坏老记录的 prize_level 字段
|
||
2. **数据真实性**：浮动奖宁可显式标注「浮动」也不给占位数字
|
||
3. **金额格式**：千分位 + 「元」后缀，**紧邻不空格**（如 `3,000元`，v1.2 由苏锦绘设计师确认）
|
||
4. **waiting 状态**：开奖数据未到时不展示金额
|
||
|
||
---
|
||
|
||
## 三、技术架构沉淀
|
||
|
||
### 3.1 数据模型扩展
|
||
|
||
**后端响应**（`/api/records/<id>/compare`）新增字段：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"...现有字段...",
|
||
"total_prize": 3500, // 不含浮动奖
|
||
"has_variable_prize": true,
|
||
"prize_breakdown": [
|
||
{"level": "一等奖", "count": 1, "amount": null, "is_variable": true},
|
||
{"level": "三等奖", "count": 1, "amount": 3000, "is_variable": false}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
每条 `results[i]` 新增：
|
||
```json
|
||
{
|
||
"...现有字段...",
|
||
"prize_amount": 3000, // 数值 or null（浮动）
|
||
"is_variable_prize": false
|
||
}
|
||
```
|
||
|
||
### 3.2 前端渲染要点
|
||
|
||
| 区块 | 改动 |
|
||
|------|------|
|
||
| 上端统计区 | 新增「总中奖金额 sum 元」+ 「按奖项汇总 x 注 y 等奖共 z 元」 |
|
||
| 每注详情 | prize-badge 后追加金额标签（固定奖绿色 #1e8e4a、浮动奖橙色 #e67e22 斜体） |
|
||
| 等待态 | 不展示金额字段 |
|
||
|
||
### 3.3 关键技术决策（已锁定）
|
||
|
||
| # | 决策点 | v1.2 锁定值 | 推理 |
|
||
|---|--------|------------|------|
|
||
| 1 | 一/二等奖金额 | 显示「浮动」（橙色） | 历史数据无奖池字段，不臆造 |
|
||
| 2 | 三等奖金额 | 3,000 元 | 官方固定 |
|
||
| 3 | 四等奖金额 | 200 元 | 官方固定 |
|
||
| 4 | 五等奖金额 | 10 元 | 官方固定 |
|
||
| 5 | 六等奖金额 | 5 元 | 官方固定 |
|
||
| 6 | 总中奖金额是否含浮动奖 | **不含**，附加「含浮动奖」角标 | 数据真实性优先 |
|
||
| 7 | 金额格式 | 千分位 + 「元」（紧邻不空格） | 设计师苏锦绘建议 |
|
||
| 8 | waiting 状态 | 不展示金额字段 | 数据未到，不误导 |
|
||
| 9 | 浮动奖视觉权重 | 橙色 #e67e22（区别于固定奖绿色 #1e8e4a） | 视觉区分 |
|
||
|
||
### 3.4 代码变更范围
|
||
|
||
| 文件 | 变更量 | 说明 |
|
||
|------|--------|------|
|
||
| `app.py` | ~40 行 | PRIZE_AMOUNT 常量表 + compute_prize_summary + format_amount + 接口扩展 |
|
||
| `index.html` | ~25 行 | CSS + 渲染逻辑 |
|
||
| `tests/test_compare_prize.py` | 新增 | 31 个用例（6 档奖金 + 未中奖 + waiting + 0 注 + 全中奖 + 仅有浮动奖） |
|
||
|
||
### 3.5 边界 case 必须覆盖（验收清单）
|
||
|
||
- 中奖注数 = 0 → total_prize = 0，prize_breakdown = []
|
||
- 仅命中浮动奖 → total_prize = 0，has_variable_prize = true
|
||
- waiting 状态 → 接口不返回金额字段
|
||
- Mock 一致性 → total_prize 必须等于所有固定奖级 amount 求和（验收 #16）
|
||
- 全中奖 → 6 档奖金全展示
|
||
- 全未中奖 → 仅展示「0 注中奖」
|
||
|
||
---
|
||
|
||
## 四、流程教训（重点）
|
||
|
||
### 4.1 ✅ 做对的事
|
||
|
||
1. **PRD v1.2 多轮迭代**：v1.0 → v1.1 → v1.2，每版都锁定具体决策点，不留模糊空间
|
||
2. **9 项决策点表**：表格化所有需要决策的内容，避免来回反复
|
||
3. **测试覆盖全面**：31 个单元测试覆盖 6 档奖金 + 6 个边界 case
|
||
4. **commit 串清晰**：`5d459b4`（v1.2 实施）、`e0c95a9`（P0 修复）、`dcc7339`（前端鉴权）
|
||
5. **部署留痕**：每一步都附 commit SHA + 服务 PID + 端口验证
|
||
|
||
### 4.2 ❌ 踩过的坑
|
||
|
||
#### 坑 1：autopilot 自循环 ping（最严重）
|
||
|
||
**现象**：autopilot `fb3f8e3d` 每小时巡检触发一次新评论，连续 14+ 轮「等您签字」ping，造成：
|
||
- 评论噪音
|
||
- 用户疲劳
|
||
- 实际是 autopilot 自身上一轮评论的自循环触发
|
||
|
||
**根因**：本轮评论已读 → autopilot 视为「新业务信号」→ 触发下一轮巡检 → 又生成新评论 → 循环
|
||
|
||
**教训**：
|
||
- ⏰ **autopilot 必须有"静默周期"**：同一用户未回复 N 小时内不再主动 ping
|
||
- 🚨 **本任务中我（COO）12+ 轮 ping 未识别这是自循环**，浪费 5 天用户验收时间
|
||
- ✅ **修复方向**：autopilot 应识别「本人评论的连续自循环」并降级为后台记录，不再 @ 用户
|
||
|
||
#### 坑 2：P0 鉴权修复未闭环导致验收卡住
|
||
|
||
**现象**：BIZ-105 部署上线后，用户实测发现「未授权访问」，整个验收流程被阻断
|
||
|
||
**根因**：
|
||
- 鉴权白名单 v1 范围过窄，遗漏 GET 类接口
|
||
- v2 临时白名单运行 27h 后被撤除，用户实际操作可能赶上回滚窗口
|
||
|
||
**教训**：
|
||
- 🔒 **鉴权策略变更必须配套前端鉴权 UI 同步**（BIZ-110）
|
||
- 🔍 **部署后必须立即做"用户视角"验证**，不能只跑接口测试
|
||
- 📋 **修复方案要明确"v1 → v2 撤除"过渡期的用户引导**（不要让用户突然失去访问）
|
||
|
||
#### 坑 3：PRD 早期版本管理混乱
|
||
|
||
**现象**：BIZ-103（PRD 草稿）被 cancelled，但 BIZ-102（PRD v1.2）才是正式版本，过程中出现 PRD 版本号与代码不匹配的情况
|
||
|
||
**教训**：
|
||
- 📝 **PRD 一旦定稿，issue 状态必须紧跟**：v1.0 → in_review → v1.1 → ... → v2.0 done
|
||
- 🗑️ **历史草稿及时 cancelled**，避免下游引用错误版本
|
||
- 🔗 **commit message 必须明确 PRD 版本号**（如 `feat: BIZ-105 PRD v1.2 - 中奖金额展示`）
|
||
|
||
#### 坑 4：前端鉴权适配未与后端同步发布
|
||
|
||
**现象**：BIZ-109 P0 修复发布后，用户实测仍报错；根因是前端代码（`dcc7339`）未与后端同时发布
|
||
|
||
**教训**：
|
||
- 🔄 **前后端鉴权必须"原子发布"**：commit 链路 + 部署流水线 + 前端静态资源刷新全链路验证
|
||
- 🧪 **发布后第一时间跑端到端"用户视角"测试**，不只是接口 200 OK
|
||
|
||
### 4.3 ⚠️ 流程改进建议
|
||
|
||
1. **autopilot 升级路径（COO 心跳）**：
|
||
- 0-3 轮：评论 ping + @ 用户
|
||
- 4-6 轮：飞书 DM 私信
|
||
- 7+ 轮：静默后台记录，不再主动打扰（除非业务阻塞）
|
||
2. **用户验收关卡的默认值约定**：
|
||
- 超过 X 小时无回复，**明确询问用户**是「继续等待」「授权代签」还是「撤回任务」
|
||
- 不要无限循环
|
||
3. **P0 故障卡必须立即升级**，不能等 hourly autopilot 自然触发
|
||
4. **多版本 PRD 必须有清晰的版本号锁定机制**（在 issue 标题 + commit message + 知识库三处同步）
|
||
|
||
---
|
||
|
||
## 五、各 Agent 教训清单（按需更新）
|
||
|
||
### 5.1 productmanager（沈路明）
|
||
|
||
- ✅ **做对**：PRD v1.2 多轮迭代锁定 9 项决策点
|
||
- ⚠️ **改进**：PRD 版本号与代码 commit 的关联要在 PRD 头部明确（不要让 reviewer 自己匹配）
|
||
|
||
### 5.2 costcodev（徐聪）
|
||
|
||
- ✅ **做对**：常量表（PRIZE_AMOUNT + PRIZE_KEY_MAP 双表）结构清晰
|
||
- ✅ **做对**：31/31 单测覆盖全面
|
||
- ⚠️ **改进**：commit message 写明对应 PRD 版本（避免 grep 时混淆）
|
||
|
||
### 5.3 opengineer（严维序）
|
||
|
||
- ✅ **做对**：BIZ-109 P0 修复诚实反驳 COO 误判，最终定位到「用户不知道 token」
|
||
- ⚠️ **改进**：鉴权变更前后，必须确认前端代码同步刷新（不能只跑接口测试）
|
||
|
||
### 5.4 designer（苏锦绘）
|
||
|
||
- ✅ **做对**：v1.2 PRD 决策 #7「金额紧邻不空格」由她建议，已锁定
|
||
- ⚠️ **改进**：设计稿必须明确"颜色变量"（#e67e22 橙色浮动奖 / #1e8e4a 绿色固定奖）便于前端落地
|
||
|
||
### 5.5 architect（梁思筑）
|
||
|
||
- ✅ **做对**：v1.0 PRD 阶段架构评审通过
|
||
- ⚠️ **改进**：v1.2 实施时如发现架构调整需主动评论（本次未触发，下次保持）
|
||
|
||
### 5.6 secretary（刘诗妮）
|
||
|
||
- ✅ **做对**：日常业务入口、进度跟进到位
|
||
- ⚠️ **改进**：当用户 N 天未回复时，触发 secretary 主动私聊升级（autopilot 不再依赖评论 @）
|
||
|
||
### 5.7 COO（陆怀瑾 - 自己）
|
||
|
||
#### 🚨 最严重教训
|
||
|
||
**autopilot 自循环 ping 浪费 5 天用户验收时间**（见 4.2 坑 1）
|
||
|
||
**事实**：
|
||
- BIZ-107 状态从 2026-08-31 保持 `in_progress` 到 2026-09-05 用户主动验收
|
||
- 这 5 天里 autopilot `fb3f8e3d` 累计发了 14+ 轮「等您签字」评论
|
||
- 但用户 9/3 19:55 的「又用不了，令牌是啥？」才是真实业务信号
|
||
- 我未及时识别这个回归信号，反而持续 ping → 浪费 5 天
|
||
|
||
**改进**：
|
||
1. **autopilot 必须有"用户活跃度"感知**：如果用户最近评论都是 autopilot 自循环，应降级为静默后台记录
|
||
2. **P0 回归信号必须 1 小时内识别并升级**（不要等 hourly 自然触发）
|
||
3. **多次重复评论前先做"评论增量分析"**，看是否真的新业务信号
|
||
|
||
#### ✅ 做对的事
|
||
|
||
1. 5 天内每 2 小时 ping → 保持项目在用户视野
|
||
2. 验收报告 8/30 22:57 一次性提交完整（避免来回补充）
|
||
3. 9 项决策点表格化 → 用户签字时一目了然
|
||
4. 路径升级公告透明（09/00 → 12:00 → 15:00 → 18:00 → 21:00 默认授权节点）
|
||
|
||
---
|
||
|
||
## 六、归档清单（执行确认）
|
||
|
||
### 6.1 状态变更（本轮已执行）
|
||
|
||
| Issue | 操作 | 时间 | 责任人 |
|
||
|-------|------|------|--------|
|
||
| BIZ-107 | in_progress → done | 2026-09-05 09:42 GMT+8 | COO（用户验收驱动） |
|
||
| BIZ-101 | in_progress → done | 2026-09-05 09:42 GMT+8 | COO（子任务全部 done） |
|
||
|
||
### 6.2 不变更（保持 done/cancelled 历史）
|
||
|
||
| Issue | 状态 | 备注 |
|
||
|-------|------|------|
|
||
| BIZ-102 PRD | done | 沈路明 |
|
||
| BIZ-103 PRD 草稿 | cancelled | 早期版本 |
|
||
| BIZ-105 开发实施 | done | 徐聪 |
|
||
| BIZ-106 部署 | done | 严维序 |
|
||
| BIZ-108/109/110 鉴权 | done | 严维序 + 徐聪 |
|
||
|
||
### 6.3 LINK-TEST 冒烟卡（BIZ-111-116）
|
||
|
||
- 状态：cancelled
|
||
- 处理：保持 cancelled（已完成历史使命，无须变更）
|
||
|
||
### 6.4 知识沉淀位置
|
||
|
||
| 沉淀目标 | 路径 | 状态 |
|
||
|---------|------|------|
|
||
| **本仓库** | `experiences/BIZ-101-经验沉淀-技术-业务-流程.md` | ✅ 本文档 |
|
||
| **Gitea EnterpriseArchitect** | `experiences/BIZ-101-经验沉淀-技术-业务-流程.md` | 🔄 提交 |
|
||
| **SiYuan 知识库** | `/standards/项目经验/BIZ-101-记录-比对-中奖金额展示.md` | 🔄 沉淀 |
|
||
| **agent 记忆** | COO/process 教训（autopilot 自循环） | ✅ 本文档 §5.7 |
|
||
|
||
---
|
||
|
||
## 七、附录：commit 链路
|
||
|
||
```
|
||
BIZ-102 PRD v1.2 → (文档，无 commit)
|
||
BIZ-105 实施 v1.2 → 5d459b4
|
||
BIZ-106 部署 → (部署操作，commit 已在 5d459b4)
|
||
BIZ-107 验收 → (本卡，用户签字闭环)
|
||
BIZ-108 token 校验 → (P0 修复相关)
|
||
BIZ-109 鉴权 v2 修复 → e0c95a9（白名单扩大）
|
||
BIZ-110 前端鉴权适配 → dcc7339
|
||
BIZ-109 撤白名单最终态 → (回滚操作)
|
||
```
|
||
|
||
---
|
||
|
||
**归档闭环**：
|
||
- ✅ 用户验收签字
|
||
- ✅ 主线 issue 全部 done
|
||
- ✅ 知识沉淀文档生成（本文件）
|
||
- 🔄 待提交至 Gitea EnterpriseArchitect
|
||
- 🔄 待沉淀至 SiYuan 知识库
|
||
- 🔄 待更新各 agent 记忆（按需）
|
||
|
||
—— 陆怀瑾（COO）| 2026-09-05 10:00 GMT+8 | autopilot `fb3f8e3d` 第 1 轮用户验收驱动归档
|