vincent/EnterpriseArchitect
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8b04f8b85652fcdea662d2f5871ad764b8c46044
EnterpriseArchitect/experiences/BIZ-101_记录比对_中奖金额展示_经验沉淀.md
T

13 KiB
Raw Blame History

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）新增字段：

{
  "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] 新增：

{
  "...现有字段...",
  "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 轮用户验收驱动归档

Reference in New Issue View Git Blame Copy Permalink