GCFS 模块化开发计划（API-First + TDD-First）
目标：以项目核心目的为靶心，从核心模块起步，以 API 接口为桥梁，逐模块做实。
原则：详细可行——锚定已上线的 MRP（https://gcfms.luluta.org）作为核心垂直切片的种子，逐步形式化、再向外扩，而非一次性铺开 44 模块（评审已判定后者超载 5-10 倍、会"永不发布"）。
0. 核心目的与北极星
GCFS 三层价值，按"先做实、再差异化、最后变现"排序：
1. 资金流监控（钱流向哪里）——MRP 已交付雏形，Phase 0-3 做实。
2. 宏观冲击因果链解释（为什么这样流）——核心差异化北极星，Phase 4。
3. 消耗式可信注意力 + 会员/经济（注意力是否在放大）——变现层，需登录+法律，Phase 5-6 冻结。
总纲：价格是结果，资金流是过程，利率是主轴，叙事是传播，反身性是放大器。
1. API-First + TDD-First 开发循环（每个模块都走这 6 步）
①契约先行 → ②夹具(fixtures) → ③RED 测试 → ④最小实现 → ⑤GREEN+重构 → ⑥经接口集成1. 契约先行：先写/扩 OpenAPI（后端接口）或函数/数据契约（管线模块）。契约是唯一真值源（L1-16）。
2. 夹具：每端点造 success / empty / error 三类黄金样例（对齐 GCFS-07）。
3. RED 测试：先写会失败的契约测试（响应须符合 OpenAPI schema / 业务不变量），此时无实现 → 红。
4. 最小实现：写刚好让测试变绿的代码，不过度。
5. GREEN + 重构：测试全绿，清理；CI 门禁（schema-validate / mock-real-parity / no-investment-advice lint）。
6. 经接口集成：消费方（如前端）切到契约对接，而非直读内部数据 → 接口成为真正的桥梁。
铁律：实现不得早于契约 + RED 测试合并；合规 lint（禁买卖/必涨/稳赚）贯穿全程。
2. 全量功能模块清单（24 L1 + 21 L2）→ 状态 × 阶段
状态：✅ MRP 已有雏形 ｜ 🎯 当前核心待建 ｜ ⏸️ MVP-A 扩展 ｜ 🧊 MVP-B/C 冻结
| L1 模块 | 状态 | 阶段 | 说明 |
|---|---|---|---|
| L1-02 数据源与信息采集 | ✅雏形 | P1 做实 | gcfs_sources.py；扩资产级数据 |
| L1-03 数据标准化与指标分析 | ✅雏形 | P1/P2 | gcfs_indicators.py；扩指标+时序 |
| L1-07 信息处理与发布（07.1 Snapshot ✅ / 07.2 API 网关 🎯） | 部分 | P0 | API 网关是当前最缺、最核心的桥梁 |
| L1-09 前端展示与推送 | ✅ | P0 切API/P3 推送 | apps/web 4 页；改读 API |
| L1-11 基础设施与云部署 | ✅ | — | systemd/Caddy/cron 已上线 |
| L1-16 OpenAPI/SDK/Mock 契约治理 | 🎯 | P0 | 契约源，API-First 的根 |
| L1-10 测试/CI/CD/发布 | 🎯 | P0 | TDD harness，CI 门禁 |
| L1-13 资产注册中心与生命周期 | 🎯 | P1 | /assets 的数据模型 |
| L1-22 配置/Feature Flag/参数治理 | 部分✅ | P0→P3 | config.py 已有；Flag 待加 |
| L1-21 内容/方法论/知识库 | 部分✅ | P3 | method/方法论文案已有 |
| L1-14 全球市场日历与时区 | ⏸️ | P3 | 交易窗口/数据时点 |
| L1-15 国际化与地区化 | ⏸️ | P3 | zh-CN + en |
| L1-18 告警/提醒/通知 | ⏸️ | P3 | 邮件订阅（增长闭环起点） |
| L1-20 观测/成本/SLO | ⏸️ | P3 | 健康/新鲜度/错误率 |
| L1-08 隐私/合规/信任/治理 | 部分✅ | P3公共/P5会员 | 免责/红线✅；同意/PII🧊 |
| L1-04 宏观冲击因果链 | 🧊 | P4 | 核心差异化北极星 |
| L1-06 AI 解释与报告 | 部分✅ | P4 | 模板日报✅；真 AI 摘要🧊 |
| L1-01 产品与用户增长 | 部分✅ | P0公共/P5会员 | 公共入口✅；会员飞轮🧊 |
| L1-05 可信注意力与反身性 | 🧊 | P5 | 需登录+反身性指数 |
| L1-17 Admin 控制台 | 🧊 | P5 | 运营后台 |
| L1-23 Credit/Reward 经济 | 🧊 | P5 | 需法律意见（类证券灰区） |
| L1-19 开发者平台/企业数据 | 🧊 | P6 | 商业化 API |
| L1-24 数据产品责任链/发布证据 | 🧊 | P6 | 审计证据包 |
| L1-12 文档/编号/多 Agent 执行 | ⏸️ | P6 | 工程协作 |
L2 子模块（21 个）随其 L1 阶段：P0=L2-07.2；P1=L2-02.1/2、L2-03.1/3、L2-01.1；P2=L2-03.2、L2-07.1；P4=L2-04.1/2/3、L2-02.3；P5=L2-01.2/3、L2-02.4、L2-05.1/2、L2-08.1/2、L2-09.1（前端状态机 P0 已部分实现）。
3. 全量接口清单（IF-001~038）→ 阶段
| 阶段 | 接口 |
|---|---|
| P0 | IF-028 OpenAPI→SDK/Mock/Tests ｜ IF-011 Snapshot→Public API ｜ IF-012 Public API→Frontend ｜ IF-026 API结果→页面状态机 |
| P1 | IF-019 Asset Registry→页面 ｜ IF-001 Source Registry→Collector ｜ IF-002 Collector→Raw ｜ IF-003 Raw→Normalized ｜ IF-008 Quality Gate→Indicator |
| P2 | IF-037 Snapshot Manifest→CDN/Cache ｜ IF-007 Attention Aggregates→Indicator(占位) |
| P3 | IF-020 Market Calendar→窗口 ｜ IF-027 Locale→页面/报告 ｜ IF-032 Runtime→Observability ｜ IF-017 Notification→Alert ｜ IF-033 Content→页面/AI ｜ IF-014 Admin Config→Flag(部分) |
| P4 | IF-004 Event→Causal ｜ IF-009 Indicator→Causal ｜ IF-010 Causal→AI Report ｜ IF-035 Macro Core→Public/Causal ｜ IF-036 AI Report→Publisher |
| P5 | IF-005 Watchlist API ｜ IF-006/023 →反身性分类器 ｜ IF-007 注意力聚合 ｜ IF-013 资产页→会员闸 ｜ IF-021/022 注意力/分享事件 ｜ IF-024 Credit→Economy ｜ IF-025 Consent→Data Gates ｜ IF-034 资产关系图 ｜ IF-015 Challenge→隔离 |
| P6 | IF-018 开发者API→企业 ｜ IF-016 发布证据→审计 ｜ IF-029 Mock场景→QA ｜ IF-030 CI门禁→发布 ｜ IF-031 Infra→运行 ｜ IF-038 Agent交接→编排 |
4. 阶段化路线（核心优先，逐阶段交付可发布增量）
Phase 0 — 把 MRP 升级为 API-First 架构 ★当前
为什么先做：MRP 前端直读 snapshot.json，没有 HTTP API。引入 Public API 层 = 把"以 API 为桥梁"落地，后续一切模块都挂在契约上。
- 模块：L1-16 契约 → L1-07.2 API 网关(FastAPI) → L1-10 TDD harness → L1-09 前端改读 API
- 接口：IF-028 / IF-011 / IF-012 / IF-026
- 端点（GCFS-06 核心子集）：
- GET /v1/public/snapshots/latest
- GET /v1/public/indicators、GET /v1/public/indicators/{indicator_id}
- GET /v1/public/reports/daily
- GET /v1/public/health
- 栈：
apps/apiFastAPI + Pydantic（读 snapshot.json 为数据源）；packages/openapi/openapi.yaml契约；tests/contractspytest 契约测试。 - TDD 门禁：每端点 success/empty/error 夹具；契约测试断言响应符合 OpenAPI schema + 统一 envelope；no-investment-advice lint。
- 交付：前端经 API 渲染（数据不变，架构变实）；契约+测试+CI 就位。
Phase 1 — 资产与指标域做实
- 模块：L1-13 资产注册中心、L1-03 扩指标、L1-02 扩采集
- 接口：IF-019 / IF-001 / IF-002 / IF-003 / IF-008
- 端点：
/v1/public/assets、/assets/{id}、/indicators/{id}/series、/rankings/{id} - 交付：资产目录/详情页（GCFS-08 设计的页面）+ 指标时间序列。
Phase 2 — 标准化/质量/持久化
- 模块：L1-03.2 质量门禁、L2-07.1 发布器做实、数据持久化（Postgres：core.asset / data.indicator_values / snapshots，对齐 GCFS-05 最小集）
- 接口：IF-008 / IF-011 / IF-037
- 交付：从 snapshot-first 静态 → 带历史的真后端（支撑时序/回测）。
Phase 3 — MVP-A 完善（日历/i18n/观测/订阅）
- 模块：L1-14 市场日历、L1-15 i18n(zh+en)、L1-20 观测/SLO、L1-18 邮件订阅、L1-21/22 做实
- 接口：IF-020 / IF-027 / IF-032 / IF-017 / IF-033
- 交付：双语 + 数据状态页 + 邮件订阅（增长闭环起点）。
Phase 4 — 宏观冲击因果链 ★核心差异化
- 模块：L1-04 因果链引擎、L2-04.x（利率重估/高久期/核心节点脆弱性）、L1-06 真 AI 报告
- 接口：IF-004 / IF-009 / IF-010 / IF-035 / IF-036
- 端点：
/v1/public/causal-chains[/{id}]、/events（GCFS-06A 契约已就位，且 asset_id/status 契约对账已修） - 交付：首页"今日主导因果链" + 因果链详情页（GCFS-08 设计）；这是把产品从"看板"升级为"解释型雷达"的关键。
Phase 5 — 可信注意力 + 会员 + Credit（需登录+法律）
- 模块：L1-01 会员、L1-05 可信注意力、L1-08 同意/PII、L1-23 Credit、L1-17 Admin
- 接口：IF-005/006/007/013/021/022/023/024/025/034/015
- 前置：US/EU 法律意见（Credit 类证券灰区）；先只做 Earned Credit、移除可购买。
Phase 6 — 平台化（企业/开发者/治理）
- 模块：L1-19 开发者平台、L1-24 发布证据、L1-12 多 Agent、L1-16 SDK
- 接口：IF-018 / IF-016 / IF-029 / IF-030 / IF-031 / IF-038
5. 立即开始：Phase 0 Step 1
按 API-First：先写契约（packages/openapi/openapi.yaml，4 个核心端点）→ 写 RED 契约测试 → FastAPI 实现到 GREEN → 前端切到 API。
每端点走第 1 节的 6 步循环。下面开始第一个端点 GET /v1/public/snapshots/latest。
本计划是活文档；每 Phase 交付一个可发布增量，先发布后治理，不积压未上线的治理资产。