docs(plan): gameDefinition 迁移重构为 spike 先行 + Tier-1 广度拆独立计划
双对抗评审(codex+opus)揪出初版根本前提问题(gameDefinition 包JS非替代/ 赌注未验证/空验收门/基座与广度命运耦合),创始人裁定「前置 spike 先行」。重构: - 2026-06-18-001 重写:gameDefinition 迁移=前置 spike(路A 模型产结构化 vs 路B 模型产JS+后端抽取,端到端过门率 vs 现60%基线)+ 工程条件于 spike 通过 + 引擎线 E1/E2;修正前提框架(源组织JS非替代);engineBundle 全保留冻结 - 2026-06-18-002 新建:Tier-1 七域广度拆出(独立 JIT,不受迁移卡)+ 补强验收级测试矩阵 - 评审7项风险(命门spike/引擎承重/dual-path双cutover/空门/worker split-brain/ 存储归属/历史游戏)全纳 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
zizi
parent
d51a6b5943
commit
750fdce993
@ -0,0 +1,173 @@
|
||||
---
|
||||
title: "feat: gameDefinition 生命周期迁移 — 前置 spike 先行 + 条件工程"
|
||||
status: active
|
||||
date: 2026-06-18
|
||||
type: feat
|
||||
origin: docs/brainstorms/2026-06-17-6c6g-后端-P1-工作清单-requirements.md
|
||||
supersedes: 本档 2026-06-18 初版(基座+Tier1 合一)经双对抗评审重构;Tier-1 广度已拆出至 2026-06-18-002
|
||||
---
|
||||
|
||||
# feat: gameDefinition 生命周期迁移 — 前置 spike 先行 + 条件工程
|
||||
|
||||
> **重构说明(2026-06-18,双对抗评审后)**:本档初版把"gameDefinition 基座迁移"与"Tier-1 七域广度"合一(10 单元),被 codex + opus 双对抗评审揪出**根本前提问题**:① gameDefinition **不替代** JS、是**组织/包裹** LLM 产的 JS(behaviors 真逻辑仍是 LLM 写的 JS,见 execution §224 + schema `behavior` 仅需 `{id,trigger}`)→ 迁移是让便宜模型在现 JS 之上**多产一层结构**,现路才 60% → **更难不更易**;② 核心赌注**未验证**就排 3 单元工程;③ U1 验收门(过 schema 校验)是**空门**;④ 基座(高风险两线协调)与广度(独立 CRUD)绑一个 plan = 命运耦合。**创始人裁定:前置 spike 先行;Tier-1 广度拆独立计划([2026-06-18-002](2026-06-18-002-feat-tier1-breadth-backend-plan.md))。** 本档现只管 gameDefinition 迁移,且工程**条件于 spike 通过**。
|
||||
|
||||
## 摘要
|
||||
|
||||
落地 06-17 生命周期裁定(游戏=长生命周期项目:gameDefinition 源 → build → engineBundle 包)前,**先做一个前置 spike 证伪核心赌注**——便宜模型能否产出**结构化 gameDefinition**(组织 LLM 的 JS 为模块化 behaviors + 声明式 entities/scenes/rules 信封)、且 build 出的游戏**端到端过九门、过门率不低于现 factorySrc 60% 基线**。spike 并列对比两条路(模型直产结构化 vs 模型产 JS + 后端确定性抽取派生),出结果再决定**要不要/怎么迁移**。工程单元(U1–U3)**全部条件于 spike 通过 + 引擎线 E1/E2 就绪**,不在 spike 出结论前启动。
|
||||
|
||||
---
|
||||
|
||||
## 问题背景
|
||||
|
||||
**两阶段生命周期(06-17 裁定 · 不变)**:gameDefinition = 权威开发态源;engineBundle = 发行态构建产物(全保留冻结,见 KTD 5)。
|
||||
|
||||
**前提纠正(评审揪出,我已核实)**:gameDefinition **不消除 JS 生成**。读 `2026-06-17-固定游戏架构与SAA-agentic-studio-execution.md:224`「gameDefinition.behaviors 是声明式模块描述,真逻辑代码仍由核心代码 agent 产出经构建编译进 __GameBundle」+ 冻结 `source-project.schema.json`(`behavior` 仅 required `{id,trigger}`、`code` 非必填)。即:gameDefinition = **在 LLM 产的 JS 逻辑(模块化进 behaviors)之外,再加一层声明式 entities/scenes/rules/config/assets 信封**。迁移要便宜模型**多产一层结构 + 保持一致**——SAA 现路才 60%,这一层只会**更难**;可维护性收益也**部分**(换美术/调参/改关卡 → 确定性改数据;改玩法逻辑 → 仍走 LLM regenerate 重出 behavior 的 JS)。**故核心赌注必须先验证,不能假定。**
|
||||
|
||||
**机会成本(评审提出 · spike 输入)**:SAA 现路 60%、worker 转产线 cutover 已 defer(见 [2026-06-17-001](2026-06-17-001-feat-backend-tier0-gen-mainline-plan.md))。此刻投激进形态迁移 vs **先把现路推到 80% 上线**(最接近 MVP 可玩闭环)——spike 结果 + 成本是这个决策的输入。
|
||||
|
||||
---
|
||||
|
||||
## 关键技术决策（KTD）
|
||||
|
||||
1. **gameDefinition = 结构化源(组织/包裹 JS,非替代)**:模块化 behaviors(各含 LLM 产的逻辑 JS)+ 声明式 entities/scenes/rules/config/assets 信封。**纠正初版"取代 factorySrc 直出 JS"的错误框架。**
|
||||
|
||||
2. **spike 先行(前置门)**:核心赌注(便宜模型能否稳产 build-able 的结构化 gameDefinition)未验证 → 工程前先 spike,**端到端过门率为判据**(非 schema-valid 空门)。spike 不通过则不进工程。
|
||||
|
||||
3. **spike 并列两路**:**路 A**(模型直产结构化 gameDefinition + 最小 build-from-source)vs **路 B**(模型仍产 JS〔现 60% 路不动〕+ 后端**确定性抽取**派生 gameDefinition)。路 B 把"结构化"风险从"模型能否稳产"(高方差瓶颈)移到"抽取器能否覆盖"(可工程化可测)——初版完全没考虑此路。
|
||||
|
||||
4. **工程条件化 + 诚实依赖账**:U1–U3 工程**条件于 spike 通过**;且 U2(build-from-source)/U3(modify)**承重依赖引擎线 E1/E2**(gameDefinition→render 适配器 + build 命令),E1/E2 未冻接口前不启动 U2。后端**真能独立交付的只有 U1**(产源 + 落库),其端到端真值仍依赖 E1/E2 → 阶段一拆"U1 源生成 / E1/E2 就绪后联调 / modify"三段独立验收。
|
||||
|
||||
5. **engineBundle/__GameBundle 全保留冻结**:`__GameBundle` 全局名(契约冻结 `game-studio/src/host/inject.ts:202`)、GamePackage(仍存 engineBundle)、Runner v2 装载链(engineBundle→feed 真玩)、feed 宿主——迁移**只改 engineBundle 的来源**(从 LLM 直出 JS → 从结构化源 build),**不改包本身与下游**。源新增(独立 `game_source_project` 表,源不进 GamePackage)、包保留。**绝非"用 gameDefinition 取代 engineBundle"。**
|
||||
|
||||
6. **additive 非破坏 + cutover 量化门**:迁移期保现 factorySrc→engineBundle 60% working 路;cutover 判据 = 新路过门率 ≥ 现基线 × 阈值(非"过一款"),有 owner、有 dual-path 上限期。两套生成 prompt **物理隔离零共享**(保"flag off 零回归"为强保证)。
|
||||
|
||||
---
|
||||
|
||||
## 高层技术设计（HTD）
|
||||
|
||||
### 两阶段生命周期(前提纠正版:源组织 JS,非替代)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
LLM["便宜模型"]
|
||||
subgraph S1["开发态(权威源)"]
|
||||
GDEF["gameDefinition<br/>声明式 entities/scenes/rules/config<br/>+ behaviors(各含 LLM 产的逻辑 JS,模块化)"]
|
||||
end
|
||||
subgraph S2["发行态(构建产物·全保留)"]
|
||||
BUNDLE["engineBundle (__GameBundle)"]
|
||||
end
|
||||
LLM -->|"路A:直产结构化源"| GDEF
|
||||
LLM -.->|"路B:产 JS"| JS["JS 工厂(现 60% 路)"]
|
||||
JS -.->|"后端确定性抽取派生"| GDEF
|
||||
GDEF -->|"build-from-source(引擎 E1/E2)"| BUNDLE
|
||||
BUNDLE --> PKG["GamePackage 发行(不变)"]
|
||||
```
|
||||
|
||||
### spike → 决策 → 条件工程
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
SPIKE["前置 spike(S1 路A / S2 路B / S3 对比决策)"]
|
||||
SPIKE -->|"路A 过门率 ≥ 现60%基线 ∧ 成本达标"| PA["工程走路A:U1 产结构化源"]
|
||||
SPIKE -->|"路A 劣化 ∧ 路B 抽取覆盖够"| PB["工程走路B:模型产JS+后端抽取"]
|
||||
SPIKE -->|"两路均未达标"| DEFER["推迟迁移 · 先稳现路到80%上线(U7/W-G1)"]
|
||||
PA --> ENG["条件:引擎线 E1/E2 就绪"]
|
||||
PB --> ENG
|
||||
ENG --> U23["U2 build-from-source 联调 → U3 modify 真生效"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 实现单元
|
||||
|
||||
### 前置门 · gameDefinition spike（先行 · 出结论才进工程）
|
||||
|
||||
> spike 是**实验**(改码看结果),由 ce-work 执行;本节定义实验设计、判据、决策。隔离分支跑、不进发布链、单独记 cost/trace。样本 = 5–8 款一句话,覆盖现路已知难易档(复用 U7 e2e 的贪吃蛇/接金币/躲障碍〔过〕+ 打砖块/点击消除〔败〕+ 2–3 款新档)。
|
||||
|
||||
### S1. spike 路 A — 模型直产结构化 gameDefinition + 最小 build
|
||||
|
||||
- **Goal**:改 generate prompt 产结构化 gameDefinition(声明式 entities/scenes/rules/config + 模块化 behaviors〔各含逻辑 JS〕)+ 写一个 **spike 级最小 build-from-source**(把结构化源编译成能装载的 bundle)→ 真九门。测过门率/成本/失败类型。
|
||||
- **Files**(spike 分支,不进主干):`game-cloud/.../saa/SaaPrompts.java`(实验性 gameDefinition SYSTEM)、`.../saa/`spike build 适配、spike 脚本。
|
||||
- **判据**:过门率 vs 现 factorySrc 60% 基线;单款成本 vs ¥0.15 闸;失败类型归因(结构产不出 / 一致性失败 / build 失败 / 玩法不过门)。
|
||||
- **Verification**:N 款端到端(gameDefinition→build→九门 真玩),出过门率表 + 失败类型分布 + 成本。
|
||||
|
||||
### S2. spike 路 B — 模型产 JS（现路不动）+ 后端确定性抽取派生 gameDefinition
|
||||
|
||||
- **Goal**:generate 仍产现 JS 工厂(60% 路零改)+ 写后端**确定性抽取器**(JS/产物 → 派生 gameDefinition:抽 entities/config/assets 引用/behavior 模块边界)→ 现 build → 九门。测抽取**覆盖度**(多少结构能确定性抽出)+ 过门率(应 ≈ 现 60%,因生成路不动)。
|
||||
- **Files**(spike 分支):后端抽取器原型、spike 脚本。
|
||||
- **判据**:抽取覆盖度(entities/config/assets/behaviors 各能抽出多少);过门率(预期 ≈ 现基线);可维护性真收益(抽出的结构哪些可确定性编辑)。
|
||||
- **Verification**:同 N 款,产派生 gameDefinition + 抽取覆盖度报告 + 过门率(对照路 A)。
|
||||
|
||||
### S3. spike 对比 + 决策
|
||||
|
||||
- **Goal**:对比路 A / 路 B 的**过门率 vs 现 60% 基线 / 单款成本 / 可维护性真兑现面**,出三选一决策。
|
||||
- **决策门**:
|
||||
- 路 A 过门率 ≥ 现基线 ∧ 成本达标 → 工程走路 A(进 U1,条件引擎线)。
|
||||
- 路 A 劣化 ∧ 路 B 抽取覆盖够用 → 工程走路 B(模型产 JS + 后端抽取,风险更低)。
|
||||
- 两路均未达标 → **推迟迁移,先稳现路到 80% 上线**(资源回 U7/W-G1),迁移待现路达标后重评。
|
||||
- **Verification**:决策文档(过门率/成本/覆盖度三表 + 选路理由),回填本计划 + 总账。
|
||||
|
||||
---
|
||||
|
||||
### 条件工程 · gameDefinition 落地（spike 通过 + 引擎线 E1/E2 就绪才启动）
|
||||
|
||||
> 以下 U1–U3 **不在 spike 出结论前启动**;措辞按路 A 写,若 spike 选路 B 则 U1 改为"后端抽取器产线化"。
|
||||
|
||||
### U1. generate 产结构化源（后端可独立 · spike 后）
|
||||
|
||||
- **Goal**:按 spike 选定路,generate 产结构化 gameDefinition 落 `sourceProject.gameDefinition`(收敛 behaviors 到契约 `gameDefinition.behaviors`)。
|
||||
- **Dependencies**:S3 决策;**worker prompt 同步方案**(否则 SAA 产结构化、W-G1 worker 仍产 blob = split-brain → U1 验收须含 worker 同步或显式声明只覆盖 SAA 实验线)。
|
||||
- **Files**:`SaaPrompts.java`(gameDefinition SYSTEM,与现 factory SYSTEM **物理隔离**)、`SaaStudioNodes.java`(generateNode 产源)、`SaaStudioNodesTest.java`;worker `wg1/gen-worker/worker/prompt.py`(同步,W-G1 协调)。
|
||||
- **Approach**:dual-path 用 flag 二选一(shadow 模式才第二次 LLM 产结构化,单独记 cost/trace、不进发布);现路字节零变。
|
||||
- **Test scenarios**:gameDefinition 过 schema **且引用完整性**(scene.entityRefs/entity.components 指向存在的 id);behaviors 模块化;现 factorySrc 路 prompt/产物字节零回归(flag off);worker 口径一致。
|
||||
- **Verification**(硬门,非 schema-valid 空门):产的 gameDefinition 经 build(U2/spike build)→ 九门过门率 ≥ 现基线;现路零回归。
|
||||
|
||||
### U2. build-from-source 接缝（条件引擎线 E1/E2 · 前置冻接口）
|
||||
|
||||
- **Goal**:build 节点从 `gameDefinition` 构建 engineBundle(经引擎线 E1/E2 适配器),取代 factorySrc→esbuild。
|
||||
- **Dependencies**:U1;**引擎线 E1/E2 — 前置门 = 冻结 E1 的 gameDefinition→render 字段级消费契约**(schema 已冻 ≠ 渲染语义已定);存储归属(`game_source_project` 归 studio vs project,execution §12 仍 Open)收口。
|
||||
- **Approach**:接引擎 build 命令;E1/E2 未落前 guard/fallback 现路(不静默);cutover 量化门(过门率 ≥ 现基线 × 阈值 + dual-path 上限期)。复现性:同 buildInputHash → 字节等价 bundle(buildInputHash = gameDefinition canonical JSON + engine ver + build tool ver + templateId + asset refs)。
|
||||
- **Test scenarios**:gameDefinition→build→含 `__GameBundle` 的 bundle;同源 hash 字节等价;E1/E2 未落 guard fail-loud。
|
||||
- **Verification**:门控 e2e(E1/E2 就位):gameDefinition→build→play 过九门;现路 fallback 零回归。
|
||||
|
||||
### U3. modify 真生效（依赖 U2）
|
||||
|
||||
- **Goal**:deterministic RFC6901 改 gameDefinition + regenerate-module 重一 behavior,经 build-from-source 重建;移除 U6 现 fail-loud guard。
|
||||
- **Dependencies**:U2(build-from-source)。
|
||||
- **Approach**:deterministic 改声明式部件(数据)→ 重建;regenerate-module 重目标 behavior 的 JS、不动其余;**诚实边界**:改玩法逻辑仍走 LLM regenerate(非纯确定性),可维护性收益限定在数据态部件。
|
||||
- **Test scenarios**:deterministic 改 gameDefinition 一字段 → 重建反映;regenerate 重一 behavior 不动其余;改源不改包(重新构建)。
|
||||
- **Verification**:modify 产新预览版,走发布审核、不动 currentVersion。
|
||||
|
||||
---
|
||||
|
||||
## 范围边界
|
||||
|
||||
- **Tier-1 七域广度** → 拆至 [2026-06-18-002](2026-06-18-002-feat-tier1-breadth-backend-plan.md)(独立 · JIT · 不受本迁移卡)。
|
||||
- **引擎线 E1(gameDefinition→render 适配器)+ E2(build 命令)**:Mac/引擎线 owns;本计划 U2 只接缝、且前置冻 E1 字段契约。
|
||||
- **W-G1 worker 转产线 + 生成质量 ≥80%**:W-G1 域;U1 的 worker prompt 同步 = W-G1 协调。
|
||||
- **真广告/真支付/真采购** = 日历闸门,mock(provider 工厂注入)。
|
||||
|
||||
---
|
||||
|
||||
## 风险与依赖
|
||||
|
||||
- **R1(命门)便宜模型能否稳产 build-able 结构化源**:gameDefinition 在 JS 之上加结构 = 更难;**由前置 spike(S1/S2)证伪,非假定**。spike 失败 → 推迟迁移、先稳现路。
|
||||
- **R2 引擎线 E1/E2 承重依赖**:U2/U3 全悬于 E1/E2;**前置门 = 冻 E1 字段级消费契约**;后端独立可交付仅 U1。
|
||||
- **R3 dual-path 过渡态复杂度 + 两 cutover 叠加**(U7 worker@60% + 本迁移 cutover):两套 prompt 物理隔离;cutover 量化门 + owner + dual-path 上限期;逻辑上**宜先 U7 把现路达 80% 转正,再换地基**。
|
||||
- **R4 验收门空门陷阱**:schema-valid ≠ 可玩;判据一律端到端过门率 + 引用完整性。
|
||||
- **R5 worker split-brain**:U1 须含 worker 同步,否则只声称 SAA 实验线。
|
||||
- **R6 存储归属(studio vs project)仍 Open**:U2 前置确认(非并行风险)。
|
||||
- **R7 历史 engineBundle 游戏**:迁移期旧游戏只可 play/release、不可 deterministic modify(或 best-effort 反向 scaffold,不混入主验收)。
|
||||
|
||||
---
|
||||
|
||||
## 需求追溯
|
||||
|
||||
| 需求(origin) | 单元 | 性质 |
|
||||
|---|---|---|
|
||||
| 06-17 生命周期裁定核心赌注验证 | S1/S2/S3 spike | 前置门 |
|
||||
| R-B7 源真化 / 产结构化源 | U1(条件) | 工程 |
|
||||
| R-B7 build-from-source | U2(条件·引擎 E1/E2) | 工程 |
|
||||
| R-B7 modify 完整应用 | U3(条件) | 工程 |
|
||||
|
||||
> **执行姿势**:spike 先行(S1/S2/S3 隔离分支,ce-work 执行,出决策)→ 决策门 → 条件工程(U1 后端独立 / U2 前置冻 E1 契约 / U3 依赖 U2)。**spike 不通过则推迟迁移、资源回稳现路。** 每工程单元 codex 一轮评审。测试机 mini-desktop。
|
||||
147
docs/plans/2026-06-18-002-feat-tier1-breadth-backend-plan.md
Normal file
147
docs/plans/2026-06-18-002-feat-tier1-breadth-backend-plan.md
Normal file
@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "feat: 6c6g 后端线 Tier-1 广度域(闭环骨架 + 广度后端)"
|
||||
status: active
|
||||
date: 2026-06-18
|
||||
type: feat
|
||||
origin: docs/brainstorms/2026-06-17-6c6g-后端-P1-工作清单-requirements.md
|
||||
---
|
||||
|
||||
# feat: 6c6g 后端线 Tier-1 广度域
|
||||
|
||||
> **拆分说明**:本档由 [2026-06-18-001](2026-06-18-001-feat-gen-lifecycle-and-tier1-breadth-plan.md) 初版的"阶段二·Tier-1 广度"拆出(双对抗评审建议:基座迁移与广度域性质迥异,绑一个 plan = 命运耦合)。**本档七域对 mock 独立、不受 gameDefinition 迁移卡**,按联调里程碑 M2/M3 各自 JIT 推进(需求档原口径)。
|
||||
|
||||
## 摘要
|
||||
|
||||
Tier-1 = 闭环骨架 + 广度后端域,**对 mock 独立、可并行**,与生成主线迁移解耦。七域:feed 游标真化 / 经济(admin 赋余额+订阅)/ 社区(评论/关注/排行/弹幕)/ 账号(政策/申诉)/ admin 运营(限曝光/导出/看板)/ 素材(实体/浏览/上传)/ 玩法模板注册(低优先级·最后)。**复用现成模式**(provider 工厂 / 通知底座 / trade 幂等 / feed interact 幂等 / WebSocket starter),薄 CRUD 铺量为主,真复杂度点(feed 复合游标 / 社区 ZSET+弹幕)单独标注。
|
||||
|
||||
---
|
||||
|
||||
## 问题背景
|
||||
|
||||
七域现状(逐域读码实证):**素材整域未建**;**社区仅通知底座成**(评论/关注/排行/弹幕全无);**账号政策正文/申诉缺**(适龄分级已 real);**feed 游标分页是桩**(`FeedServiceImpl.java:131` nextCursor 恒空串 = 永远第一页);**经济(trade)最成熟**(钱包/收益/提现已 real,缺 admin 赋余额 + 订阅);**admin 无独立模块**(端点散在各模块 `controller/admin`);**玩法模板**低优先级(创始人 06-17 排 Tier-0 后)。
|
||||
|
||||
---
|
||||
|
||||
## 关键技术决策（KTD）
|
||||
|
||||
1. **复用现成模式(reuse over rebuild)**:`PayoutClientFactory`(fail-fast)/`AdProviderFactory`(降级)→ 经济真支付、素材 provider;通知底座(归属隔离 + @Primary)→ 评论/关注通知;trade 幂等(bizNo + 余额 CAS)→ admin 赋余额;feed interact 幂等 → 点赞;infra WebSocket starter → 弹幕地基。
|
||||
2. **admin 赋余额/订阅入口落 trade `controller/admin`**(经济 ↔ admin 强共享,game-admin 前端调),不另起 admin 后端模块。
|
||||
3. **JIT 推进**:七域独立,按联调里程碑各自 just-in-time;低风险 CRUD(账号/素材浏览)留最后全量 pass;玩法模板排最后(与生成主线耦合)。
|
||||
4. **验收级测试矩阵**(评审补强):每域测试覆盖**契约字段 / 权限 RBAC / 租户·用户归属隔离 / 幂等键 / 并发 / 空数据 / mock provider 降级 / 审计日志**,非只 happy-path 200。
|
||||
|
||||
---
|
||||
|
||||
## 实现单元
|
||||
|
||||
### U1. R-FEED feed 游标分页真化
|
||||
|
||||
- **Goal**:feed 流真游标分页(`(sort_score, id)` 复合游标防丢/重 + 二次过滤续取),替现"永远第一页"桩。
|
||||
- **Requirements**:R-FEED P-FED-13;契约 `feed.yaml` T-FED-06。
|
||||
- **Dependencies**:无(纯独立)。
|
||||
- **Files**:`game-cloud/game-module-feed/.../mapper/feed/FeedRankMapper.java`、`.../service/feed/FeedServiceImpl.java`(buildStream)、`.../controller/app/feed/vo/{FeedStreamReqVO,ZoneStreamReqVO}.java`(加 cursor)、测试。
|
||||
- **Approach**:Mapper 加 `(sort_score,id) < cursor` 复合游标(sort_score DECIMAL 可重复 → 必须复合防丢/重 = **真复杂度**);buildStream 以末条 `(sortScore,id)` 编码 nextCursor;处理**二次过滤(filterByProjectPublished)后不足 size 但仍 hasMore 的续取**(隐藏坑);索引 `idx_zone_status_sort` 已支持。
|
||||
- **Patterns**:现 buildStream(`FeedServiceImpl.java:119`)、FeedRankMapper(`:29`)。
|
||||
- **Test scenarios**:happy 多页翻到底无重无漏;edge sort_score 重复值续接、二次过滤后续取补足、空 cursor=首页、hasMore 正确;**Covers T-FED-06** cursor 编解码往返一致;并发翻页不串。
|
||||
- **Verification**:多页翻到底全集无重无漏;demo feed 真规模。
|
||||
|
||||
### U2. R-ECON 经济（admin 赋余额 + 订阅）
|
||||
|
||||
- **Goal**:admin 赋余额(real,credit 方法 + 端点 + 流水)+ 订阅域(实体表 + admin 赋订阅 + C 端查订阅态)。
|
||||
- **Requirements**:R-ECON;契约 `trade.yaml`。
|
||||
- **Dependencies**:无(trade 成熟);↔U5(admin 入口共享)。
|
||||
- **Files**:`game-module-trade/.../service/.../AccountService(Impl).java`(credit/grant)、`controller/admin/TradeAdminController.java`(赋余额端点)、新订阅 DO/Mapper/Service/Controller、`huijing-server/.../db/migration/V21+__create_game_trade_subscription.sql`、测试。
|
||||
- **Approach**:admin 赋余额 = 复用 income 流水范式记一笔 `source=admin_grant` + 余额原子增(CAS);订阅 = 新表(plan/expire/status)+ admin 赋订阅 + C 端查;mock 支付 provider 工厂(`PayoutClientFactory`)现成。
|
||||
- **Patterns**:AccountService 余额原子增减 + withdraw bizNo 幂等、PayoutClientFactory。
|
||||
- **Test scenarios**:happy 赋余额→流水+余额增、赋订阅→C 端查态;**幂等**(同 bizNo 不重复入账);**并发** CAS 正确;**权限** admin RBAC;订阅过期态查询;审计日志(赋值操作可溯)。
|
||||
- **Verification**:admin 赋余额/订阅端点 200;流水可对账。
|
||||
|
||||
### U3. R-SOC 社区社交（评论/关注/排行 ZSET/弹幕 WS）
|
||||
|
||||
- **Goal**:评论 CRUD + 关注关系 + 排行 Redis ZSET + 弹幕 WS 底座(minimal-real / mock)。
|
||||
- **Requirements**:R-SOC;契约 `community.yaml`。
|
||||
- **Dependencies**:无(community 自有);复用通知底座 + WebSocket starter。
|
||||
- **Files**:`game-module-community/.../`新评论/关注 DO/Mapper/Service/Controller + Flyway、排行 Service(`opsForZSet`)、弹幕 WS handler、测试。
|
||||
- **Approach**:评论 = 克隆通知底座归属隔离 + CRUD + 转 compliance 举报;关注 = 克隆 feed interact 幂等(唯一键,取关改 active 不删);排行 = Redis ZSET(**回填一致性 = 真复杂度,须定 ZSET↔DB 双写一致窗口 + 触发源**);弹幕 = 复用 WebSocket starter。
|
||||
- **Patterns**:通知底座(`NotifyServiceImpl`)、feed interact 幂等、WebSocket starter。
|
||||
- **Test scenarios**:评论 CRUD + 举报转 compliance;关注/取关**幂等**;ZSET 排行更新↔DB 一致性(回填窗口);弹幕广播频道隔离;**权限/归属**(评论作者校验);空数据(无评论/无关注)。
|
||||
- **Verification**:评论/关注/排行端点 + 弹幕 WS 连通。
|
||||
- **Open(评审 P-8)**:① 弹幕——确认 WebSocket starter 在**当前单体无 MQ** 部署下的广播能力边界(MQ=future-state 未部署);若依赖 MQ 则 MVP 弹幕限"单实例 minimal-real"、标 scale 边界。② 排行——ZSET↔DB 回填一致性方案须写进 approach(幂等 ≠ 一致性)。
|
||||
- **Note**:域较大,执行可拆评论+关注 / 排行 ZSET / 弹幕 WS 三子单元。
|
||||
|
||||
### U4. R-ACC 账号（政策正文页 / 申诉）
|
||||
|
||||
- **Goal**:政策正文页(富文本 + 版本)+ 申诉回路(提交/查询 + admin 处理);适龄分级已 real(compliance)。
|
||||
- **Requirements**:R-ACC;`passport.yaml` 已冻 + 新政策/申诉契约。
|
||||
- **Dependencies**:无(最薄 CRUD);归属 compliance(已有 rating/ban/gate 语义)。
|
||||
- **Files**:`game-module-compliance/.../`新政策 DO/端点 + 申诉 DO/端点 + Flyway、测试。
|
||||
- **Approach**:政策正文 = 薄 CRUD(富文本 + 版本);申诉 = 薄 CRUD + 状态机(提交→admin 处理→结果),可选关联 ban 台账。
|
||||
- **Patterns**:compliance rating/ban(`ComplianceRatingController`/`ComplianceBanController`)。
|
||||
- **Test scenarios**:政策正文存取 + 多版本取最新;申诉提交→admin 处理状态机;**重复提交守卫**;**权限**(申诉本人 + admin 处理 RBAC);空数据。
|
||||
- **Verification**:政策页/申诉端点 200。
|
||||
|
||||
### U5. R-ADMIN admin 运营（限曝光 / 导出 / 经营看板）
|
||||
|
||||
- **Goal**:限曝光(扩 feed rank)+ 导出(CSV/Excel)+ 经营看板聚合(telemetry+trade+aigc+project);赋余额/订阅入口见 U2。
|
||||
- **Requirements**:R-ADMIN。
|
||||
- **Dependencies**:↔U2(赋余额/订阅共享);看板跨模块只读(telemetry/trade/aigc/project)。
|
||||
- **Files**:`controller/admin/feed/AdminFeedController.java`(限曝光扩)、新导出端点(yudao Excel)、新看板聚合 Controller/Service、测试。
|
||||
- **Approach**:限曝光 = 基于 feed rank 扩(曝光上限/降权,复用 `offlineRank`/boost);导出 = yudao Excel 底座;看板 = 跨模块只读聚合(GMV/DAU/生成量/营收,组合 telemetry GameStat + trade `/report/revenue` + aigc 计数 + project 发布量)。
|
||||
- **Patterns**:AdminFeedController、AdminTelemetryController、trade 营收报表。
|
||||
- **Test scenarios**:限曝光降权生效;导出 CSV/Excel 字段正确;看板聚合数正确;**跨模块只读不写**、缺模块数据兜底;**权限** admin RBAC;空数据。
|
||||
- **Verification**:限曝光/导出/看板端点 200。
|
||||
|
||||
### U6. R-MAT 素材（实体 / 浏览 / 选用 / 上传端点）
|
||||
|
||||
- **Goal**:素材实体表(六类)+ 浏览分页 + 选用加入草稿 assetContext + 上传拿 ref 端点(`/asset/upload`,OSS/MinIO)。
|
||||
- **Requirements**:R-MAT;契约 `studio.yaml`(assetContext 已冻)+ `source-project.schema.json`(assetSpec.category)。
|
||||
- **Dependencies**:**上传端点归属待裁(studio vs 共享 media)= 前置确认**(评审:未裁前只做契约 + assetContext 消费链验证,避免返工)。
|
||||
- **Files**:`game-module-studio/.../`新素材 DO/Mapper/Service/Controller + Flyway(game_material 六类)、浏览端点、选用→草稿 assetContext、`/asset/upload` 端点、测试。
|
||||
- **Approach**:素材实体 = 六类(对齐 `StudioAssetContextItem.category`);浏览 = 分页 CRUD;选用 → 写草稿 assetContext(打通 `StudioDraftCreateReqVO` 落库链、替旧 `attachments`);上传 = OSS/MinIO 拿 ref;provider mmx-cli;采购/分成 = mock。
|
||||
- **Patterns**:StudioAssetDO 槽位、provider 工厂、OSS/MinIO 基建。
|
||||
- **Test scenarios**:素材浏览分页;选用→草稿 assetContext 落库;上传→拿 ref;ref 被 create/modify 消费;**六类 category 校验**;上传大小/类型守卫;**归属隔离**(创作者素材)。
|
||||
- **Verification**:素材浏览/选用/上传端点 200;`assetContext.ref` 有生产端。
|
||||
- **Open**:上传端点归属(studio vs media)**先裁后规划具体端点**(需求档待确认 #2)。
|
||||
|
||||
### U7. R-TPL 玩法模板后端注册（低优先级 · 最后）
|
||||
|
||||
- **Goal**:品类玩法模板注册化(经营模拟/剧情互动/解谜闯关/TRPG/非遗科普品类引导生成),现仅 generic 单模板。
|
||||
- **Requirements**:R-TPL P-TPL-01/03(低优先级,创始人 06-17 排 Tier-0 后)。
|
||||
- **Dependencies**:生成主线耦合(扩模板同步 aigc schema/prompt/validator);排最后。
|
||||
- **Files**:`aigc/.../AigcTemplateConstants.java`、studio `getTemplateList`、`PromptResourceLoader`/`GameConfigSchemaValidator` 资源 Map、`contracts/templates/<id>.schema.json`、测试。(或 DB 表化 = 设计决策。)
|
||||
- **Approach**:按扩展纪律扩**品类玩法模板**(非旧"游戏模板"整局填参;品类引导 AI 生成);是否 DB 表化 = 设计决策。
|
||||
- **Patterns**:AigcTemplateConstants 扩展纪律。
|
||||
- **Test scenarios**:新品类注册→`template/list` 可见→品类引导生成;多处同源(schema/prompt/validator)口径一致。
|
||||
- **Verification**:品类模板注册 + 品类引导生成。
|
||||
|
||||
---
|
||||
|
||||
## 范围边界
|
||||
|
||||
- **真广告联盟 / 真支付收单 / 真实素材采购分成** = 日历闸门,mock gated(provider 工厂注入)。
|
||||
- **gameDefinition 生命周期迁移** → [2026-06-18-001](2026-06-18-001-feat-gen-lifecycle-and-tier1-breadth-plan.md)(独立,本档不依赖其结果)。
|
||||
- **前端接线**(game-admin/game-studio 接这些端点)= 前端线。
|
||||
|
||||
---
|
||||
|
||||
## 风险与依赖
|
||||
|
||||
- **R1 域间共享**:经济 ↔ admin 赋余额/订阅入口归属(落 trade `controller/admin`,KTD 2);admin 看板跨 4 模块只读(耦合最多,非算法复杂)。
|
||||
- **R2 真复杂度点**:feed 复合游标(U1,二次过滤续取)、社区 ZSET 回填一致性 + 弹幕 WS 无 MQ 广播边界(U3)——非纯 CRUD,单独留意。
|
||||
- **R3 素材上传归属未裁**(U6):前置确认,未裁前只做契约 + 消费链。
|
||||
- **R4 复用模式成熟度**(评审 P-8):WebSocket starter 无 MQ 广播、ZSET↔DB 一致性——动工前确认,非假定。
|
||||
|
||||
---
|
||||
|
||||
## 需求追溯
|
||||
|
||||
| 需求 | 单元 | 复杂度 |
|
||||
|---|---|---|
|
||||
| R-FEED 游标真化 | U1 | 真复杂度(复合游标) |
|
||||
| R-ECON 经济 | U2 | 薄(钱包已 real,补 admin+订阅) |
|
||||
| R-SOC 社区 | U3 | 真复杂度(ZSET+弹幕) |
|
||||
| R-ACC 账号 | U4 | 最薄 CRUD |
|
||||
| R-ADMIN 运营 | U5 | 薄聚合(跨模块读) |
|
||||
| R-MAT 素材 | U6 | 中(上传 OSS + 归属待裁) |
|
||||
| R-TPL 玩法模板 | U7 | 中(多处同源,低优先级最后) |
|
||||
|
||||
> **执行姿势**:七域 JIT、对 mock 独立可并行;U2↔U5 共享赋余额入口需协调;U6 上传归属先裁;U7 排最后。低风险 CRUD 留最后全量 pass。每域验收级测试矩阵(KTD 4)。每单元 codex 一轮评审。测试机 mini-desktop。
|
||||
Loading…
x
Reference in New Issue
Block a user