experiences(BIZ-101): 记录-比对 中奖金额展示 全链路经验沉淀（技术+业务+流程）

Co-authored-by: multica-agent <github@multica.ai>

experiences/BIZ-101_记录比对_中奖金额展示_经验沉淀.md

@@ -0,0 +1,314 @@
+# 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 轮用户验收驱动归档