From e4e66f382689f3909aa4d27d77c4b4e60673c4f6 Mon Sep 17 00:00:00 2001 From: bizwings Date: Sun, 30 Aug 2026 15:19:33 +0800 Subject: [PATCH] =?UTF-8?q?BIZ-102=20v1.1:=20=E8=AE=B0=E5=BD=95-=E6=AF=94?= =?UTF-8?q?=E5=AF=B9=20=E4=B8=AD=E5=A5=96=E9=87=91=E9=A2=9D=E5=B1=95?= =?UTF-8?q?=E7=A4=BA=20PRD=20=E4=B8=8E=20UI=20=E5=8E=9F=E5=9E=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit v1.0: 3 字段增量扩展（prize_amount/total_prize/prize_summary）+ 前端 3 处扩展 v1.1: 落实架构评审 3 点意见 - 金额字段统一'(单位:元)'与量级安全说明 - prize_summary key 改英文枚举（first_prize..sixth_prize），新增 prize_level 中文名 - floating 标记落 results[i] 与 prize_summary[key] 两粒度 - 兼容性条款：每次实时计算，不依赖持久化 Co-authored-by: multica-agent --- docs/PRD-BIZ102-记录比对中奖金额展示.md | 187 +++++++++++++++++ docs/prototype-BIZ102-compare-prize.html | 252 +++++++++++++++++++++++ 2 files changed, 439 insertions(+) create mode 100644 docs/PRD-BIZ102-记录比对中奖金额展示.md create mode 100644 docs/prototype-BIZ102-compare-prize.html diff --git a/docs/PRD-BIZ102-记录比对中奖金额展示.md b/docs/PRD-BIZ102-记录比对中奖金额展示.md new file mode 100644 index 0000000..30143e3 --- /dev/null +++ b/docs/PRD-BIZ102-记录比对中奖金额展示.md @@ -0,0 +1,187 @@ +# 产品需求文档（PRD）：记录-比对 中奖金额展示 + +> **编号**：BIZ-102（BIZ-101 子任务1） +> **负责人**：沈路明（productmanager） +> **版本**：v1.1 +> **状态**：架构评审通过（条件式已落实），待设计与开发评审 +> **父任务**：BIZ-101「webui 记录-比对 中奖金额展示」（CO 已批准） +> **关联系统**：双色球 WebUI（后端 Flask `app.py` + 前端 `index.html`） + +--- + +## 1. 背景与目标 + +### 1.1 业务背景 +当前 `POST/GET /api/records//compare` 已完成「是否中奖 + 几等奖」的比对，前端弹窗展示每注的奖项徽标与红球/蓝球命中情况，但**不展示中奖金额**。运营人员与刘总在查看比对结果时，只能看到「x 注中奖」，无法直观获知本次生成号码的**总中奖金额**与**各奖级分布金额**，不利于快速评估生成策略的价值与复盘。 + +### 1.2 解决的问题 +- 运营/管理层查看比对结果时，缺少「中奖金额」这一核心经营指标。 +- 现有比对只给出奖项枚举，无法按奖级聚合金额，复盘成本结构困难。 + +### 1.3 成功指标（可量化） +- [ ] 比对弹窗统计区新增「总中奖金额」与「各奖级金额分布」两项，覆盖率 100%。 +- [ ] 每条中奖注在奖项徽标旁展示该注中奖金额，覆盖率 100%。 +- [ ] 后端响应新增字段后，旧版前端（不消费新字段）功能不受影响，回归通过率 100%。 +- [ ] 中奖金额计算口径在 UI 中对浮动奖显式标注「以官方公布为准」，避免误导。 + +--- + +## 2. 用户故事 + +- **作为运营人员**，我希望在比对弹窗中一眼看到「本次生成共中奖多少元、各奖级各多少元」，以便快速汇报生成效果，无需人工逐注累加。 +- **作为刘总**，我希望查看每注的中奖金额与总额，以便评估号码生成策略的投入产出，并在浮动奖场景下明确知晓金额口径来源。 +- **作为开发（徐聪）**，我希望后端以结构化字段（`prize_amount` / `total_prize` / `prize_summary`）一次性返回金额，前端直接消费，避免前端重复实现中奖金额计算逻辑。 + +--- + +## 3. 功能需求 + +### 3.1 后端 API 扩展（`app.py` `/api/records//compare`） + +现有响应 `data` 已包含：`status, gen_time, compare_type, compare_rule, draw{...}, results[], total, win_count, win_tickets[]`。 +每条 `results[i]` 已包含：`index, reds, blue, red_matches, blue_match, prize_level, prize_desc, is_win`。 + +本需求在**不改动既有字段**前提下做增量扩展： + +| 功能点 | 位置 | 字段 | 类型 | 描述 | 优先级 | 验收标准 | +|--------|------|------|------|------|--------|----------| +| F-1 每注中奖金额 | `results[i]` | `prize_amount` | int（单位:元） | 该注中奖金额（元），未中奖为 `0` | P0 | 中奖注 `prize_amount` = 该奖级单注金额；未中奖注恒为 `0` | +| F-2 总中奖金额 | `data` 顶层 | `total_prize` | int（单位:元） | 所有中奖注金额合计（元） | P0 | `total_prize` = Σ `results[i].prize_amount`，与前端展示一致 | +| F-3 按奖级汇总 | `data` 顶层 | `prize_summary` | dict | 按奖项分组汇总，仅含实际出现的奖项 | P0 | key 为英文枚举（见 3.3），每项含 `{count, amount, prize_level, floating}`；未出现奖级不出现 | +| F-3.1 单注浮动标记 | `results[i]` | `floating` | bool | 该注是否属浮动奖（一/二/三等奖）；固定奖或未中奖为 `false` | P1 | 浮动奖注 `floating = true`，固定奖注 `floating = false` | + +**字段类型与单位**（v1.1 落实架构评审 #1）： +- 所有金额字段（`prize_amount` / `total_prize` / `prize_summary[].amount`）均为 **整数**，**单位:元（非分）**。 +- 量级说明：双色球一等奖历史最高单注超 1500 万元，Python int 无溢出（任意精度）；前端 JS `Number` 在 `2^53 ≈ 9007 万亿` 以下安全，本场景安全。 + +**边界**： +- `status === 'waiting'`（等待开奖）的响应**不新增**上述字段（无开奖数据，无法计算）。 +- 浮动奖（一/二/三等奖）单注金额来源见第 4 节；若取不到动态金额，使用占位值并通过 F-3.1 的 `floating: true` 提示前端「金额以官方公布为准」。 + +### 3.2 前端展示扩展（`index.html` `compareRecord()` 比对弹窗） + +现有弹窗结构（`.compare-summary` 含 4 项：生成时间 / 比对开奖期 / 总注数 / 中奖注数）保持不变，做增量插入： + +| 功能点 | 位置 | 描述 | 优先级 | 验收标准 | +|--------|------|------|--------|----------| +| F-4 统计区-总额 | `.compare-summary` 内 | 新增「总中奖金额 `` 元」 | P0 | 使用 `data.total_prize`；`0` 时显示「0 元」 | +| F-5 统计区-分布 | `.compare-summary` 下方 | 遍历 `prize_summary`，逐行展示「`` 注 `<奖级>` 共 `` 元」 | P0 | 仅展示 `count > 0` 的奖级；每行一条 | +| F-6 每注金额 | 每注 `.compare-ticket` | 在 `prize-badge`（几等奖）旁额外显示该注金额，如「`五等奖 10元`」 | P0 | 使用 `r.prize_amount`；未中奖注不显示金额 | + +**展示文案规范**： +- 统计区总额：`总中奖金额 25 元` +- 分布行：`1 注 五等奖 共 10 元` / `3 注 六等奖 共 15 元` +- 每注：`五等奖 10元`（浮动奖额外追加 `· 浮动以官方为准` 角标，角标数据源为 `r.floating === true`，见第 4 节） + +**前端字段消费映射**： +- 统计区总额 ← `data.total_prize` +- 分布行每条 ← `Object.entries(data.prize_summary)` 遍历，每项含 `count` / `amount` / `prize_level`（中文显示名）/ `floating` +- 每注金额 ← `r.prize_amount`，浮动角标 ← `r.floating` + +--- + +## 3.3 `prize_summary` 字段结构与 key 命名规范（v1.1 落实架构评审 #2） + +采用**方案 A（推荐）**：`prize_summary` 的 key 使用**英文枚举**，每项内显式带中文 `prize_level` 字段供前端展示。 + +**理由**： +- **[常识]** JSON key 使用中文在日志检索、grep、跨语言消费、后期 i18n 时易踩坑；英文枚举是更稳定的契约。 +- 前端用映射表把英文 key 翻译成中文显示名，仅多写一处常量映射，零成本。 + +`prize_summary` 结构示例： +```json +{ + "fifth_prize": {"count": 1, "amount": 10, "prize_level": "五等奖", "floating": false}, + "sixth_prize": {"count": 3, "amount": 15, "prize_level": "六等奖", "floating": false} +} +``` + +| key | prize_level | 类型 | 中奖条件 | +|------|------|------|----------| +| `first_prize` | 一等奖 | 浮动 | 6红+1蓝 | +| `second_prize` | 二等奖 | 浮动 | 6红+0蓝 | +| `third_prize` | 三等奖 | 浮动 | 5红+1蓝 | +| `fourth_prize` | 四等奖 | 固定 | 5红+0蓝 或 4红+1蓝 | +| `fifth_prize` | 五等奖 | 固定 | 4红+0蓝 或 3红+1蓝 | +| `sixth_prize` | 六等奖 | 固定 | 2红+1蓝 或 1红+1蓝 或 0红+1蓝 | + +字段含义： +- `prize_summary[key].count` = 该奖级中奖注数 +- `prize_summary[key].amount` = `count × 该奖级单注金额`（元，整数） +- `prize_summary[key].prize_level` = 中文显示名（前端直接展示） +- `prize_summary[key].floating` = 是否浮动奖（前端决定是否展示「以官方公布为准」角标） +- 仅当 `count > 0` 的奖级出现在 `prize_summary` 中（未中奖注不计入） + +## 4. 中奖金额口径与浮动奖说明 + +### 4.1 单注奖级金额表 + +| 奖项 | 单注金额（元） | 类型 | 中奖条件 | 声明 | +|------|---------------|------|----------|------| +| 一等奖 | 浮动（官方公布） | 浮动 | 6红+1蓝 | [已知] 双色球一等奖为浮动奖池 | +| 二等奖 | 浮动（官方公布） | 浮动 | 6红+0蓝 | [已知] 二等奖为浮动奖池 | +| 三等奖 | 浮动（官方公布） | 浮动 | 5红+1蓝 | [已知] 三等奖为浮动奖池 | +| 四等奖 | 200 | 固定 | 5红+0蓝 或 4红+1蓝 | [已知] 中彩中心固定奖级 | +| 五等奖 | 10 | 固定 | 4红+0蓝 或 3红+1蓝 | [已知] 中彩中心固定奖级 | +| 六等奖 | 5 | 固定 | 2红+1蓝 或 1红+1蓝 或 0红+1蓝 | [已知] 中彩中心固定奖级 | + +> 固定奖级（四/五/六等奖）金额由中彩中心规则固定，可直接硬编码；浮动奖（一/二/三等奖）实际金额随奖池浮动。 + +### 4.2 浮动奖处理规则（关键决策点） +[推论] 本迭代先采用**单注固定/占位金额**驱动展示，浮动奖金额本期以「占位值 + UI 显式标注」呈现，待数据源（开奖数据接口）能提供每期实际奖金后再切换为动态读取。 + +- **数据源可读取实际奖金时**：`prize_amount` 取接口返回的实际单注金额；`prize_summary` 的 `amount` 按实际金额计算。 +- **数据源不可读取时（本期默认）**：浮动奖使用占位值（建议一等奖 5,000,000 / 二等奖 200,000 / 三等奖 3,000 作占位，**[猜测]** 具体占位值待刘总确认），并在 UI 该奖级旁追加角标「`浮动·以官方公布为准`」。 +- **Fallback 策略**：优先实际金额 → 缺失时占位值 + 标注。 + +### 4.3 计算边界 +- `prize_amount` 一律为非负整数（元），未中奖 = `0`。 +- `total_prize` = Σ `results[i].prize_amount`，由后端聚合，前端不做二次计算。 +- `prize_summary[key].amount` = `count × 该奖级单注金额`，由后端聚合。 +- 每次比对请求都**重新计算**上述字段，**不持久化到数据库**（v1.1 落实架构评审兼容性补充：避免老记录因历史缺字段导致新版本回放异常）。 + +--- + +## 5. 兼容性（不影响现有比对流程） + +- [ ] 新增字段为**纯增量**，旧版前端未消费新字段时比对弹窗功能不变。 +- [ ] 旧版后端（无新字段）对新版前端：前端需做字段存在性判断（`data.total_prize ?? 0`），避免 `undefined` 渲染异常。 +- [ ] `status === 'waiting'` 响应结构不变，不新增字段。 +- [ ] 比对核心逻辑（奖项判定、命中统计）零改动，仅追加金额计算分支。 + +--- + +## 6. 验收标准 + +### 后端 +1. 中奖记录比对响应中，`results[i]` 含 `prize_amount`（int，单位:元），且中奖注 = 对应奖级单注金额、未中奖注 = `0`。 +2. `data.total_prize`（int，单位:元）= 所有中奖注 `prize_amount` 之和。 +3. `data.prize_summary` 仅含 `count > 0` 的奖级；key 为英文枚举（`first_prize` ... `sixth_prize`）；每项含 `{count, amount, prize_level, floating}`，且 `amount = count × 单注金额`。 +4. `results[i].floating` 在浮动奖（一/二/三等奖）注上为 `true`，固定奖与未中奖注为 `false`。 +5. `waiting` 状态下不返回上述字段。 +6. 字段每次实时计算，不依赖持久化（老记录重新比对也能正确返回新字段）。 + +### 前端 +7. 比对弹窗统计区显示「总中奖金额 元」。 +8. 弹窗展示各奖级分布行「x 注 y 等奖 共 z 元」，仅 `count > 0` 奖级；显示名取 `prize_summary[key].prize_level`。 +9. 每条中奖注在奖项徽标旁显示该注金额；未中奖注不显示金额。 +10. `floating: true` 的注/奖级在 UI 显式标注「以官方公布为准」。 + +### 回归 +9. 不消费新字段的旧逻辑（命中统计、奖项徽标）行为不变。 +10. 字段缺失时前端不报错（存在性兜底）。 + +--- + +## 7. 范围与边界（与 BIZ-101 的关系） +- **本卡（BIZ-102）**：仅产出 PRD + UI 原型，不写后端/前端代码，不做部署。 +- **后续链路**：本卡 `in_review` → 产研交叉评审（@梁思筑 @徐聪 @苏锦绘）→ 通过后进入 BIZ-101 子任务2（开发落地）。 +- 中奖金额的**具体数值**（尤其浮动奖占位值）由本 PRD 决策，落地细节在子任务2 实现。 + +--- + +## 版本历史 +| 版本 | 日期 | 作者 | 说明 | +|------|------|------|------| +| v1.0 | 2026-08-30 11:57 | 沈路明 | 首版 PRD，基于现有 `app.py` compare 与 `index.html` compareRecord 结构增量设计 | +| v1.1 | 2026-08-30 14:35 | 沈路明 | 落实架构评审（梁思筑）3 点意见：① 金额字段追加 `(单位:元)` 标注与量级安全说明；② `prize_summary` key 改用英文枚举（方案 A），新增 `prize_level` 中文显示名字段；③ 浮动标记 `floating` 落到 `results[i]` 与 `prize_summary[key]` 两处粒度；④ 验收标准补充兼容性「每次实时计算」条款 | diff --git a/docs/prototype-BIZ102-compare-prize.html b/docs/prototype-BIZ102-compare-prize.html new file mode 100644 index 0000000..9595953 --- /dev/null +++ b/docs/prototype-BIZ102-compare-prize.html @@ -0,0 +1,252 @@ + + + + + +BIZ-102 比对弹窗原型 · 中奖金额展示 + + + + + +
+
🎯 中奖比对
+
+ + +
+
生成时间
2026-08-30 11:00:00
+
比对开奖期
2026098 · 2026-08-25
+
总注数
5
+
中奖注数
4
+ + +
总中奖金额 25 元
+ + +
+ +
1 注 五等奖共 10 元
+ +
3 注 六等奖共 15 元
+ +
1 注 一等奖 · 浮动共 5,000,000 元*
+
* 浮动奖金额为占位/官方公布值，以官方公布为准（数据源：prize_summary[key].floating）
+
+
+ + +
+ 开奖号码： + 030814192227 + 11 +
+ + +
+ 001 + 030814192227 + 11 + 一等奖 + 5,000,000元 + 红6 蓝✓ +
+
+ 002 + 03081419 + 11 + 五等奖 + 10元 + 红4 蓝✓ +
+
+ 003 + 0308 + 11 + 六等奖 + 5元 + 红2 蓝✓ +
+
+ 004 + 08 + 11 + 六等奖 + 5元 + 红1 蓝✓ +
+
+ 005 + 010203 + 09 + 未中奖 + 红0 蓝✗ +
+ +
🎉 共 4 注中奖！
+
+
+ +
+ 原型说明（BIZ-102 / PRD v1.1）：
+ · 绿色总额条 = 新增 F-4（data.total_prize）；虚线框 = 新增 F-5（遍历 data.prize_summary，key 为英文枚举 first_prize...sixth_prize，展示名取 prize_level）；
+ · 每注徽标后的绿色金额 = 新增 F-6（results[i].prize_amount）；
+ · 浮动奖（一/二/三等奖）金额旁红色「浮动以官方为准」角标，数据源 results[i].floating === true 与 prize_summary[key].floating === true（PRD 第 3.1 / 3.3 节）；
+ · 未中奖注不显示金额。原型数据为演示用占位值。
+ · mock JSON 示例： + 
+{
+  "total_prize": 25,
+  "prize_summary": {
+    "fifth_prize": {"count": 1, "amount": 10,  "prize_level": "五等奖", "floating": false},
+    "sixth_prize": {"count": 3, "amount": 15,  "prize_level": "六等奖", "floating": false}
+  },
+  "results": [
+    {"index": 1, "prize_level": "五等奖", "prize_amount": 10, "floating": false, "is_win": true},
+    {"index": 2, "prize_level": "六等奖", "prize_amount": 5,  "floating": false, "is_win": true}
+  ]
+}
+
+
+ + +