docs(.agents,mvp): plan002 Tier-1 收口——外部IO不入事务红线泛化(U3/U6实证) + 进度总账回填(U3社区/U5admin/U6素材/U7模板)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.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/**

.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 分层语义（不可混用）
 

.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）
 
 钱财动作（提现打款 / 奖励发放 / 分账入账）的不可逾越规则——任一违反即驳回：

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 原生模块，当前未接入单体 | — |