From 4ca5263eb0435cfacbc46f533864b357dfb724af Mon Sep 17 00:00:00 2001 From: lili Date: Thu, 18 Jun 2026 11:51:50 -0700 Subject: [PATCH] =?UTF-8?q?docs(.agents,mvp):=20plan002=20Tier-1=20?= =?UTF-8?q?=E6=94=B6=E5=8F=A3=E2=80=94=E2=80=94=E5=A4=96=E9=83=A8IO?= =?UTF-8?q?=E4=B8=8D=E5=85=A5=E4=BA=8B=E5=8A=A1=E7=BA=A2=E7=BA=BF=E6=B3=9B?= =?UTF-8?q?=E5=8C=96(U3/U6=E5=AE=9E=E8=AF=81)=20+=20=E8=BF=9B=E5=BA=A6?= =?UTF-8?q?=E6=80=BB=E8=B4=A6=E5=9B=9E=E5=A1=AB(U3=E7=A4=BE=E5=8C=BA/U5adm?= =?UTF-8?q?in/U6=E7=B4=A0=E6=9D=90/U7=E6=A8=A1=E6=9D=BF)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/README.md | 2 +- .agents/rules/engineering-conventions.md | 2 +- .agents/rules/security-and-reliability.md | 2 ++ docs/mvp/MVP进度总账.md | 12 ++++++------ 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/.agents/README.md b/.agents/README.md index 68b702d3..c3724937 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -37,7 +37,7 @@ | 文件 | 一句话说明 | |---|---| | `rules/engineering-conventions.md` | 命名/分层/API 路径/错误码/提交/PR 等工程规范 | -| `rules/security-and-reliability.md` | 安全基线、幂等、超时重试、合规与可靠性约束 | +| `rules/security-and-reliability.md` | 安全基线、幂等、超时重试、合规与可靠性约束（§4 含「外部 IO 一律不入 DB 事务」泛化红线 + §4.1 资金打款特例） | | `rules/build-vs-buy.md` | 自研偏误防线(R1-R7):现货尽调前置门/形态终点测试/约束血统/prior-art 强制步/名义采用禁令/抽象墙审计 | **skills/** diff --git a/.agents/rules/engineering-conventions.md b/.agents/rules/engineering-conventions.md index 95454959..48dc4398 100644 --- a/.agents/rules/engineering-conventions.md +++ b/.agents/rules/engineering-conventions.md @@ -15,7 +15,7 @@ | 异常处理 | 业务异常一律 `throw exception(错误码枚举)`（Huijing `ServiceException`），禁止裸抛 `RuntimeException`、禁止吞异常返回 null | | 日志 | 类上 `@Slf4j`；关键链路成功 INFO、失败 ERROR，错误日志必须含 `trace_id` 与关键业务 ID（如 `taskId`/`versionId`） | | 注释 | 类注释 +复杂方法注释 +字段注释，**一律简体中文**；对外接口、错误路径、补偿逻辑必须有注释 | -| 事务 | `@Transactional` **只加在 Service 层**，范围尽量小；事务内禁止远程调用（Feign/HTTP/MQ 发送放事务提交后） | +| 事务 | `@Transactional` **只加在 Service 层**，范围尽量小；**事务内禁止任何外部 IO**（Feign/HTTP/MQ 发送、Redis/ZSET 写、WebSocket 广播、文件/对象存储 `FileApi` 一律放事务提交后或事务外，见 [`security-and-reliability.md`](security-and-reliability.md) §4 外部 IO 不入事务红线） | ### 1.1 DO / VO / DTO 分层语义（不可混用） diff --git a/.agents/rules/security-and-reliability.md b/.agents/rules/security-and-reliability.md index dcf4c777..ffc983ff 100644 --- a/.agents/rules/security-and-reliability.md +++ b/.agents/rules/security-and-reliability.md @@ -78,6 +78,8 @@ > **兜底机制（必做）**：定时任务扫描"中间态"超 **5 分钟**的记录 → 自动重试或告警。任何跨模块写都要能被对账扫描发现。 +> **外部 IO 一律不入 DB 事务（红线·泛化）**：任何外部 IO——Redis（含 ZSET / 缓存写）、WebSocket 推送/广播、文件/对象存储（infra `FileApi`）、Feign/HTTP、MQ 发送——**禁止在 `@Transactional` 方法内执行**；移到事务提交后（`TransactionSynchronization.afterCommit`）或事务外。理由：① 外部调用占用 DB 连接/锁、放大持锁时长；② DB 回滚回滚不了外部副作用（ZSET 多计 / 文件孤儿 / 已广播的幻象事件）。fire-and-forget 广播尤须落库提交后再发，否则回滚后客户端已收到不存在的事件。下面 §4.1「打款外部调用不入事务」是本红线在**资金场景的特例**；plan002 评审在 U3（Redis ZSET `incrementScore` + 弹幕 WS 广播）、U6（infra `FileApi.createFile`）各独立逮一次，证其为通用红线。范本：`afterCommit` 注册见 community `RankServiceImpl`（ZSET 提交后累加）/ `CommentServiceImpl`（举报转 compliance 接缝提交后发）；单 insert 无需事务时直接去掉 `@Transactional`、提交后再做 IO（studio `StudioMaterialServiceImpl`，并就近记录文件孤儿无法回滚的补偿口径）。 + ### 4.1 资金打款/发放红线（M4 变现真实化实证，HJ-M4-REAL-001） 钱财动作（提现打款 / 奖励发放 / 分账入账）的不可逾越规则——任一违反即驳回： diff --git a/docs/mvp/MVP进度总账.md b/docs/mvp/MVP进度总账.md index c84afd90..49a73c18 100644 --- a/docs/mvp/MVP进度总账.md +++ b/docs/mvp/MVP进度总账.md @@ -41,15 +41,15 @@ | 模块 | owner P0 | 结构 | 单测文件 | 契约 | Flyway | 接单体 | 真实度（关键说明） | 执行记录 | |---|---|---|---|---|---|---|---|---| | **project** | 5 | ✅成熟 | 1(15 例) | project.yaml | V1 | ✅ | ✅ 状态机/归属/审核/发布门禁/CRUD **真实**；本模块最成熟 | `c4e2d73`·`096020f`·`6c8844f` | -| **aigc** | 3 | 🟡 | 1 | aigc.yaml | V2 | ✅ | 任务态+seam；**Dify 真实生成=桩** | `c4e2d73` | +| **aigc** | 3 | 🟡 | 1 | aigc.yaml | V2 | ✅ | 任务态+seam；**Dify 真实生成=桩**。**🆕 plan002 Tier-1 品类玩法模板注册后端 minimal-real（`feat/tier1-breadth-backend`，单测绿）**：5 品类（business-sim/narrative/puzzle/trpg/heritage）**constants-only 注册**；**U7 品类引导生成质量需 gen+九门 harness 实证=待验证/open，勿读成"品类可玩"** | `c4e2d73`·plan002`feat/tier1-breadth-backend` | | **runtime** | 3 | 🟡 | 4 | runtime.yaml | V3 | ✅ | build/session/package DO；**真实编译打包=桩** | `c4e2d73`·`2ae0c6f` | -| **feed** | 13 | 🟡 | 1 | feed.yaml | V4 | ✅ | stream/zones 结构(curl 200)；**quality_score 排序=真实(B2 回灌 e2e)**；真实互动/分享=桩；卡片 title/cover 回填=null(待修) | `c4e2d73`·B2 | -| **telemetry** | 1 | 🟡 | 3 | telemetry.yaml | V5 | ✅ | **事件同步写落库+quality_score算分+feed回灌 真实 e2e(B2)**；MQ 异步聚合留 TODO(桩) | `c4e2d73`·B2 | +| **feed** | 13 | 🟡 | 1 | feed.yaml | V4 | ✅ | stream/zones 结构(curl 200)；**quality_score 排序=真实(B2 回灌 e2e)**；真实互动/分享=桩；卡片 title/cover 回填=null(待修)。**🆕 plan002 Tier-1 admin 限曝光后端 minimal-real（`feat/tier1-breadth-backend`，单测绿）**：feed rank 扩 `exposure_limit`（admin 限曝光）；**集成/e2e(mini-desktop) 待验证/open** | `c4e2d73`·B2·plan002`feat/tier1-breadth-backend` | +| **telemetry** | 1 | 🟡 | 3 | telemetry.yaml | V5 | ✅ | **事件同步写落库+quality_score算分+feed回灌 真实 e2e(B2)**；MQ 异步聚合留 TODO(桩)。**🆕 plan002 Tier-1 admin 运营后端 minimal-real（`feat/tier1-breadth-backend`，单测绿）**：CSV-Excel 导出 / 经营看板（DAU+GMV+生成量+发布量 跨模块只读聚合，**degraded 兜底**：依赖模块缺数据时降级不崩）；**集成/e2e(mini-desktop) 待验证/open** | `c4e2d73`·B2·plan002`feat/tier1-breadth-backend` | | **ad** | 2 | 🟢真实 | 24 | ad.yaml | V6 | ✅ | **AdRevenueServiceImpl uk_trace 幂等/广告回调验签/PayoutClientFactory fail-fast 已真实**；创作者收益端点 `/app-api/telemetry/my/{summary,trend}` live；**真实广告联盟=桩受日历闸门** | `43fce85`·`e3be456d`(G1) | -| **trade** | 3 | 🟢真实 | 41 | trade.yaml | V7 | ✅ | **SettlementServiceImpl uk_source 逐笔入账/WithdrawServiceImpl 冻结+CAS 审核状态机/打款异步回调 1→2 已真实**；mock e2e 门 4 对账断言 HOLD；**真实 pay=桩受日历闸门** | `43fce85`·`e3be456d`(G1) | -| **studio** | 7 | 🟡 | 1 | studio.yaml | V8 | ✅ | 创作任务链+aigc seam；**真实生成编排=桩** | `b70e90b` | +| **trade** | 3 | 🟢真实 | 41 | trade.yaml | V7 | ✅ | **SettlementServiceImpl uk_source 逐笔入账/WithdrawServiceImpl 冻结+CAS 审核状态机/打款异步回调 1→2 已真实**；mock e2e 门 4 对账断言 HOLD；**真实 pay=桩受日历闸门**。**🆕 plan002 Tier-1（`feat/tier1-breadth-backend`，单测绿）**：为经营看板提供 GMV 只读聚合源（看板本体在 telemetry/admin 运营）；**真广告/支付/素材采购受日历闸门=mock gated** | `43fce85`·`e3be456d`(G1)·plan002`feat/tier1-breadth-backend` | +| **studio** | 7 | 🟡 | 1 | studio.yaml | V8 | ✅ | 创作任务链+aigc seam；**真实生成编排=桩**。**🆕 plan002 Tier-1 素材库后端 minimal-real（`feat/tier1-breadth-backend`，单测绿）**：`game_material` 六类 / 浏览 / 选用入草稿 `assetContext` / 上传 compose infra `FileApi`（单 insert 去 `@Transactional`、`FileApi` 出事务，孤儿文件补偿口径已就近记录）；**真素材采购受日历闸门=mock / 集成/e2e(mini-desktop) 待验证/open** | `b70e90b`·plan002`feat/tier1-breadth-backend` | | **compliance** | 6 | 🟡 | 2 | compliance.yaml | V9 | ✅ | 锁风门 Gate 二态已注入 publish（curl 验证）；**style/ip 原子=桩** | `b70e90b`·`6c8844f` | -| **community** | 5 | 🟢真实 | 22 | community.yaml | V12 | ✅ | ✅ 通知底座 e2e（链路①staging 实证：mock-trigger→`game_community_message`+updater 非空+unread 聚合；站内信/等级引擎 `published_count` 原子自增/3 上游 notify 挂点真接线 aigc·project·trade，事务后+try-catch）；**reward 现金到账（recordIncome TIP）本波做真**（G1 衔接 trade 真实化） | `737e6d5`·`e3be456d`(G1 reward 衔接) | +| **community** | 5 | 🟢真实 | 22 | community.yaml | V12 | ✅ | ✅ 通知底座 e2e（链路①staging 实证：mock-trigger→`game_community_message`+updater 非空+unread 聚合；站内信/等级引擎 `published_count` 原子自增/3 上游 notify 挂点真接线 aigc·project·trade，事务后+try-catch）；**reward 现金到账（recordIncome TIP）本波做真**（G1 衔接 trade 真实化）。**🆕 plan002 Tier-1 后端 minimal-real（`feat/tier1-breadth-backend`，单测绿）**：评论 CRUD + 举报转 compliance（seam，**compliance 举报受理 -api 待交付=open**）/ 关注（软切幂等）/ 排行 Redis ZSET（ZSET↔DB 一致性，`afterCommit` 写 ZSET + `rebuildFromDb` 对账）/ 弹幕 WS（单实例 minimal-real，**多实例待 `sender-type=redis`=open**）；**集成/e2e(mini-desktop) 待验证/open** | `737e6d5`·`e3be456d`(G1 reward 衔接)·plan002`feat/tier1-breadth-backend` | | **biz** | 6 | 🟢真实 | 1(13例) | biz.yaml | V13 | ✅ | ✅ 轻量 lead form e2e（链路②staging 实证：create→quote→advance 状态机 0→1→2+progress 时间线+updater 非空；demo 可预览负路径降级、canTransit 单跳）；**收款/在线签章留 M4（线下 sign-offline 兜底）** | `737e6d5` | | **ip** | 0 | ◻seam | — | — | — | — | D5 决策：不独立建，seam 寄宿 compliance | — | | **pay** | 1 | ◻原生 | huijing | — | — | ❌(注释) | huijing 原生模块，当前未接入单体 | — |