games-development-ai/docs/agent-specs/_archive/2026-06-11-W4单位经济埋点-评审纪要.md

W4 单位经济埋点 · Review 版 Spec 四镜头评审纪要（逐条处置）

2026-06-11 ｜ 定稿 agent ｜ 对象 spec：docs/agent-specs/2026-06-11-W4单位经济埋点-review.md 处置原则：接受的 finding → 落进 spec 对应节并标明改了哪节；拒绝/重定向 → 说明理由。所有 finding 的载体事实已逐条 grep/读码核实。

---

处置统计

维度	接受（改进 spec）	重定向（合并/已在他节落地）	拒绝	小计
feasibility	6	0	0	6
scope-guardian	3	1（#4 为正面 FYI，无需改）	0	4
data-integrity	8	0	0	8
coherence	6	0	0	6
合计	23 接受	1（FYI 确认无需改）	0	24

无拒绝项：四镜头 finding 的载体事实全部核实属真，且建议方向均与「spec 应替实现者做的裁决在 review 期收口」一致，故全部接受或确认。1 条 scope#4 为「正面示范、无需改动」的 FYI，按其建议在 spec 中显式强化「三空列排除在 DoD 外」即可（实际已落 §6.2）。

---

一、feasibility（6 条，全接受）

#	sev	issue 摘要	处置
1	major	plan A（④落 game_telemetry_game_stat 加列）被标「改动面最小」，实为新建跨模块写 seam（telemetry-api 仅 3 枚举无 Stat 写 API、insertOrAccumulate 冻结 8 列硬编码、trade pom 不依赖 telemetry）	接受。核实属真（telemetry-api 仅 3 文件、trade pom 仅依赖 ad-api+community-api）。改 §0(c)/§3.1 图/§3.4/§4.1：③④落点定向为「收益侧自有表」——③ ad 侧只读聚合、④ trade 加 game_id 列；明确否决 telemetry 加列并点破「实为新建 Feign 写 seam，非加列」。§8.0 S2 固化此裁决。
2	major	④同事务跨模块写风险（telemetry 回写卷入分账事务）被点到未给可执行裁定；「提交后异步」又与本波不引 MQ 冲突，实现者两难	接受。改 §6.1 事务边界 + §3.5 挂点：因③④已否决 telemetry 加列，④落 trade 自有表 = 同事务安全、零跨模块写，两难根除；明确否决「telemetry 写卷入分账事务」；未来若需异步外写照 Wave4 notifyIncomeChanged 事务内 try-catch 范式。
3	minor	④加 gameId 到 DTO 须同步改契约授权源 ad.yaml 的 x-feign-contracts itemFields，spec 未点名该必改文件	接受。核实 ad.yaml:389-394 itemFields 确为 5 字段无 gameId，DTO 注释「严格对齐契约·不多不少」。改 §3.5（三步链→四步链，新增 ad.yaml 为第 1 步）+ §6.2 DTO 红线：契约面=ad.yaml+DTO+V14 列+透传四点，缺一即断。
4	minor	③归因依赖 projectApi.getCreatorUserId，未声明「被删/下架游戏历史收入仍按定格快照可聚合、不在聚合期重新反查」	接受。核实 V6 注释「由 game_id 反查后落库定格」=快照已固化。改 §3.4 + 验收项2：聚合直读已定格 game_id/creator_user_id，与运行时 project 状态解耦、不漏账、不重新反查 projectApi。
5	minor	uk_source/uk_trace 被写为二列，实际 DDL 是三列（含 tenant_id），实现者按二列写去重谓词会埋错	接受。核实 V7:76 uk_source=(source,source_ref,tenant_id)、V6:73 uk_trace=(trace_id,event_type,tenant_id)。改 §3.4/§6.1 幂等节：校正为三列，提示去重谓词按三列写、勿按二列假设。
6	minor	TelemetryEventEnum 是否含 ad/income 事件留作 execution 待核，实测已双处登记，徒增无谓核对	接受。核实 TelemetryEventEnum.java:45-47 + events.schema.json:66-68 均已登记三事件。改 §4.4 EV 段：review 阶段结案——③④不新增事件名则枚举+契约零改动，红线本波不适用；§8.0 S3 固化。

---

二、scope-guardian（4 条：3 接受 + 1 FYI 确认）

#	sev	issue 摘要	处置
1	major	③④是否纳入本波在 plan 内部未拍：§0 取舍说「做」、§8.1 又把「推迟 M4 vs 独立小波」列待裁，范围未闭合就展开实现细节	接受。改 §0 范围边界 + §8.0 S1：范围裁决落槌=「本波 = ③④后端埋点独立小波」，不推迟 M4；§8.1 不再作为开放裁决。范围在进 execution 前完全收敛。
2	minor	④跨模块契约改动的唯一当前消费者是单个验收项，需确认是真实需求而非为看板/分账预留	接受（确认为本波验收必需）。④的 game_id 贯通服务于验收项3「按游戏读出创作者应得」=本波 DoD 核心，非预留。改 §8.0 S2 + 验收项3：明确④落点为本波交付项；A1 看板 UI 渲染仍外推看板波（§3.6）。
3	minor	plan 有 ≥6 项设计裁决标「未拍」，范围边界多处是软的；建议把已给倾向的解耦类裁决固化进非目标	接受。新增 §8.0「已收敛裁决」表（S1-S9）：把成本键/分母/三空列/MQ/V14 收口/落点/范围按 plan 倾向固化，§8.1 收缩为仅 3 条真需创始人/排期拍的口径。execution 拿到闭合范围。
4	minor(FYI)	§6.2 三空列「顺带补写」plan 已正确判定解耦，提示 execution 勿因「反正要 ALTER」顺手塞进本波	确认（按建议强化，无需新增裁决）。改 §6.2：三空列与本波完全无关、明确排除在 DoD 外（本波③④不碰 telemetry 表，更不会顺手补）；§8.0 S7 登记。

---

三、data-integrity（8 条，全接受）

#	sev	issue 摘要	处置
1	major	③累加未约束「必须挂 firstBilling=true 分支」，命中 uk_trace 回查分支重复累加会虚高 sum(gross)	接受。核实 AdRevenueServiceImpl:124-128 firstBilling=false 回查分支属真。改 §3.5/§4.3/§6.1 firstRecord 守门 + 验收项6：③④写/透传一律只在首次真实入账分支；验收项6 补「staging 重放后按游戏 sum 不变」实测（非仅单测 mock）。注：本波③走只读聚合无累加，约束主要针对④透传与未来③改累加。
2	major	逐笔双重 floor（MockAdProvider/1000 + setScale DOWN）致 Σnet≠Σgross×0.80，验收项3 缺容差会误判对账失败	接受。核实 MockAdProvider:29-35 整除 + SettlementServiceImpl:94-97 setScale(0,DOWN) 双 floor 属真。新增 §6.3 第2条 + 改验收项3：对账以逐笔为权威（单笔 net==floor(gross×rate)、单笔 gross==floor(ecpm/1000)），禁用「总额×0.80」反推。
3	major	若走 telemetry 加列，跨平面幂等语义断裂未点破：telemetry 恰一次来自 uk_event_id，③④源是 ad/trade 的 uk_trace/uk_source，uk_game_date 不防重复累加	接受。核实 GameStatMapper:72 注释「恰一次由 uk_event_id」属真。改 §4.1（否决 telemetry 加列的幂等理由）+ §6.1 幂等节：明确 telemetry uk_event_id 与 ad/trade uk_trace/uk_source 是两条不相干轨道，③④恰一次只能靠上游 firstBilling/firstRecord + ad/trade 自身键——既然③④已不落 telemetry，此雷从根上消除。
4	minor	单位非「分」统一：成本侧用元（编排器浮点）、收益侧用分（DB 整数），§0「单位(分)口径统一」表述与实际不符	接受。核实 report.py/newapi_cost.py 用元、ad/trade DB 用分（BIGINT）属真。改 §0 单位说明段 + §6.3 第1条：明确收益侧分、成本侧元，两平面两精度域，禁同列求差。
5	minor	「mock 阶段渠道扣率=0 自洽」缺前提失效条件（自洽前提=revenue_amount 语义=未扣渠道的 N，真实接联盟若存 G 则少扣一层、违反 R3）	接受。核实 SettlementServiceImpl:83,94 net=gross×0.80 无 ×0.6、与模型 R3（N=0.6G）分叉属真。新增 §6.3 第4条 mock 不变式 + 改 §8.1 第2条：登记硬不变式「mock 下 revenue_amount≡N」；真实化波前置=先定存 G 还是 N，存 G 则须先 ×(1-渠道扣率)。
6	minor	TelemetryEventEnum 是否含事件「须 execution 核对」过度保守，已可 review 期确证	接受（与 feasibility#6 同根）。改 §4.4 EV 段：review 期结案已双处就位、③④零改动；§8.0 S3。
7	minor	V14 两副本铁律正确但缺存量反例防撞：V7 残留第三副本（trade 单模块 src），实现者易因循把 V14 也丢进 trade 单模块	接受。核实 V7 确有 trade 单模块 src 副本（含 target/classes 共多副本，md5 全等 dd5bb43…）。改 §4.4 ★防呆条：V14 禁放 game-module-trade-server/.../db/migration/，V7 残留三副本是反面模板不可仿照。
8	minor	④game_id 贯通后「按哪个日期键」未明确，③(stat_date)与④(settle_date)在 T+1/补结算下若不严格相等会错位	接受。核实 V7:67 settle_date 注释「= 上游 stat_date」、SettlementServiceImpl:84 透传属真。新增 §6.3 第3条 + 改验收项3：日期键统一上游 stat_date（=trade settle_date），补「③Σgross[game,statDate] 与 ④Σgross[game,settleDate] 同游戏同日相等」断言。

---

四、coherence（6 条，全接受）

#	sev	issue 摘要	处置
1	blocker	V14 占号纪律建立在「V12/V13 尚未落盘、并行期撞号」前提上，但 V12/V13 已双副本落盘、Wave4 已收口，V14 是无争议下一空位，撞号风险不存在；§8.1#11 抛伪问题	接受（blocker 消除）。核实 contracts/db-schemas/ + huijing-server/.../db/migration/ 下 V12/V13 各两副本已落、V14 未占用属真。改 §4.1/§4.4/§6.2/§8.0 S4：V12/V13 表述改为「已落盘、Wave4 已收口」，V14=无并行撞号的下一空位、仅需常规单序列收口；§8.1#11 降级为 §8.0 S4 登记项，不再开放裁决。
2	major	③落库倾向在 §3.4(倾向 B 不加列)与 §4.1/§8.1(③列为 telemetry 加列候选)之间自相矛盾	接受。改 §3.4/§4.1/§3.1 图/§8.0 S2：统一为「③=ad 侧只读聚合查询、不加 telemetry 列；④=trade 加 game_id 列」，§4.1 不再把③列为加列候选，矛盾消除。
3	major	实测单款成本三文档口径分叉（0.009/0.031/0.02-0.04），spec 把 0.009 与 0.031 连成连续区间，实为不同批次/不同评审结论	接受。核实 newapi review §0:13=¥0.009（单次 602 quota 推算）、模型 §5:48=¥0.031（merge-prod-20 批实测）、newapi review §7#5:140 残留 ¥0.02-0.04（其 §0 评审 F 已否定）属真。改 §1.2 表 + §2#5：注明两数来源差异、非连续区间，execution 引数以模型 §5 实测 ¥0.031/款为准，并标注 newapi review §7#5 残留口径已被其自身否定。
4	minor	行号引用漂移：V5「later 补列非遗漏」自认在 :48-49，spec 多处写 V5:44（表头注首行）	接受。核实 V5:48-49 才是原句、:44 为表注释首行。改 §0/§3.1 图注/§4.1：移除单行 V5:44 锚点（§0/§4.1 不再引该行号；因③④已不落 telemetry，相关「头注官方加列口子」论证整体删除，锚点漂移问题随之消解）。
5	minor	同步事务链路描述与契约/建表注释的 MQ 目标态有表述张力，spec 未点破契约层仍写 MQ	接受。核实 events.schema.json:5 + V5:6 写 MQ 异步、实现为同步属真。改 §1.1 链路澄清段：契约/建表头注的 MQ 异步是目标态（M5 余项），本波不改契约描述、execution 以代码现状（同步写）为准。
6	minor	newapi review §0.5「下一版本=V12」陈旧信息被本 spec 间接继承，交叉阅读得 V12/V14 两个矛盾「下一空位」	接受（与 blocker 同根）。改 §4.1/§4.4（V12/V13 已落、V14 为下一空位）：blocker 修复时一并交代；本 spec 主张 V14 为下一空位、与磁盘事实一致，对引用件 newapi review §0.5 的陈旧 Flyway 段不再继承。

---

五、定稿后仍待创始人/排期拍的口径清单（仅 3 条，已收窄）

全部为「口径/真实化路线」裁决，非本波实现裁决；本波 execution 不阻塞于此（埋点 measurement 可先落，真实化前置留待拍板）。

1. 【假设值红线】token 单价/换算三假设值（PRICE_PER_MTOKEN_YUAN=2.0 / QUOTA_PER_UNIT=500000 / USD_CNY=7.2）替换路径绑 A1 LLM 实名充值闸门：拿到 new-api 真实账单/QUOTA_PER_UNIT 实配前，对外/对内数字是否一律保留【假设·待测】标注、不得作预测口径、不得对外锁价（建议写成硬边界）。

2. 【真实化路线·gross 语义 + 分成深度（合并）】：本波裁定仅埋点观测（mock 下 revenue_amount≡N、扣率=0 暂自洽）；待拍=真实接联盟后 game_ad_revenue.revenue_amount 存 G（总消耗）还是 N（渠道净额）——决定 trade 的 ×0.8 是否需先 ×0.6（存 G 则违反 R3 且历史快照不可回算）。字段命名/口径须在真实化波开工前定义防漂移。

3. 【对账归属·排期】③④与渠道结算单 T+1/月结对账（外部账单 ↔ 平台台账）属支付真实化波：待排期定何时做、谁做。本波③④到「平台内按游戏可 curl/DB 取到」即止。

已在 §8.0 收敛、不再上抛的原待裁项：S1 范围归属 / S2 落点形态 / S3 事件契约 / S4 V14 收口 / S5 ①成本键 / S6 quality_score 分母 / S7 三空列 / S8 MQ / S9 IP 分账。