SHA-4 Growth Loop MVP 集成：合并 codex/growth-loop-mvp 到最新 main (SHA-5)

[WardLu]

概览

将本地分支 codex/growth-loop-mvp（2 个 commit：aad1ed8 + c762626，约 6000 行，基于旧 main dc9794c）集成到最新 origin/main（a7bd8ca），并补入共享 Supabase 测试路由约定。本 PR 只做集成与验证，不实现新功能。

关联：SHA-4（实施计划父任务）/ SHA-5（本集成任务）。

变更内容

• Growth Loop MVP 核心：src/learning-*.js 状态封装/账本/奖励/兑换/同步/导出、src/app.js 与 src/cloud.js 接入、src/app.css 样式、8 个 supabase/migrations/ 数据库提案迁移、5 个 pgTAP 测试、tests/e2e/growth-loop.spec.js 与 14 个新单测文件。
• 共享 Supabase 测试路由（来自 feat/email-template-design 的 a8da8d6、028bea7 两个基础设施 commit，按任务要求保留共享路由约定）：scripts/test-shared-db.mjs、start-shared-supabase.mjs、serve-shared-functions.mjs，package.json 的 test:db 改走共享路由并新增 test:fast/test:ui/test:full，CI 增加 SHADOW_MATE_TEST_DB_URL 导出与分层测试约定文档。
• 冲突处理（以 origin/main 为准）：
  • .github/workflows/shared-supabase-policy.yml：add/add 冲突，保留 origin/main 版本（允许新增迁移、禁止修改历史，符合本 PR 新增 8 个迁移的需求）。
  • README.md：自动合并，共享路由文档与 origin/main 的 TTS CDN 说明共存。
  • package.json：growth-loop 分支未改脚本，直接采用含共享路由的主线版本。
  • 文档（README/CHANGELOG/RELEASE_NOTES）、src/piper-tts.js 与 TTS 测试：全部保留 origin/main 版本。

验证证据

命令	结果	说明
npm run check	PASS	静态检查
npm run test:unit	PASS	19 文件 / 109 项（含 14 个 growth-loop 新单测 + shared-db 脚本测试）
npm run test:db	PASS	共享 Supabase 路由 learning_rls_test.sql 58 项
growth-loop pgTAP（隔离本地）	PASS	6 文件 / 159 项（5 个 growth-loop + learning_rls）
npm run test:functions	PASS	delete-account 隔离守卫（隔离实例）
npm run test:e2e	PASS	60/60，含 growth-loop 2/2 与 cloud-real 真实 Supabase
npm run verify	PASS	public/security/static/build/check-build/coverage 全过（exit 0）
npm run release:check	PASS	未设 RELEASE_URL，生产 URL 检查按约定跳过

未决问题 / 环境阻塞

1. growth-loop pgTAP 无法经共享路由运行：共享本地库（merchant-admin 54322）尚未加载 growth_loop_* schema。8 个新迁移未进入 Shadow Portal 控制面台账，apply-shadow-mate-local-schema.mjs 会拒绝未登记源迁移。按 proposal-only 边界本仓库不执行共享库迁移；需控制面登记并生成 SHA-256 校验快照后，test:db 共享路由才能覆盖 growth-loop pgTAP。当前以隔离本地实例验证通过（159 项）。
2. test:functions 依赖隔离实例：共享 merchant-admin 函数 overlay 清单未包含 shadow-mate 的 delete-account，因此该测试在 shadow-mate 自身隔离实例（54311）上验证。
3. E2E 采用隔离实例：按 CI 约定以 E2E_REAL_SUPABASE=1 + 隔离实例运行，避免触碰生产 Supabase。

约束遵守

• 未执行任何生产迁移；未 push codex/growth-loop-mvp；未引入 src/analytics.js（Vercel Custom Events 属另一条工作线）。

---

跟进更新（SHA-5 review 建议处理）

1. test:db 覆盖 growth-loop pgTAP（建议 1，已实现） — commit 918b99a：scripts/test-shared-db.mjs 从硬编码 learning_rls_test.sql 改为扫描 supabase/tests/*.sql。在已应用全部迁移的实例上实测 Files=6, Tests=159, Result: PASS（含 5 个 growth-loop + learning_rls），CI 中 supabase start 会应用仓库全部迁移，因此 growth-loop pgTAP 不再游离在 CI 之外。本地共享实例在控制面登记迁移前会如实报 schema 缺失（learning_profile_rewards 不存在），属预期中间态。

2. 合入顺序协调（建议 2，需用户/合入方决定） — PR #40（feat/email-template-design）当前 mergeable=CONFLICTING：它基于旧 main（merge-base 6dc0593），与最新 main 在约 20 个文件上分叉，且其 a8da8d6 新增的 shared-supabase-policy.yml 文案与 main 的 a78f3bf 规范版本不同。本 PR #43 基于最新 main、已 MERGEABLE，且保留了 main 的规范 policy 文件。建议顺序：先合本 PR #43，再让 #40 rebase 到新 main（共享路由脚本内容与本 PR 完全相同，可干净去重；policy 文件冲突以 main 版本为准）。无论哪种顺序，#40 都必须先 rebase 到最新 main 才能合入。

3. 迁移 01420 冗余（建议 3，已核实，交控制面决定） — 已 diff 核实：01420 的 drop + create 与 01037 的 create or replace 函数体逐字节相同，最终 schema 与仅应用 01037 无差异，确实冗余。未在本仓库擅自删改迁移（proposal-only 边界 + 迁移历史属控制面）。建议控制面批准时直接跳过 01420，或保留并在台账注明为防御性幂等 no-op。

4. 验证边界（建议 4，已记录） — 本次补充验证：npm run test:db（共享实例 learning_rls 58 项 PASS + 隔离实例 6 文件 159 项 PASS）、npm run check PASS、npm run test:unit 19 文件 / 109 项 PASS、tests/unit/shared-db-test-script.test.js 2/2 PASS。test:functions/test:e2e 依赖运行中实例，按建议留待 W4/W5/W6 合入前在 CI 跑完整 test:full。

---

合入门槛（merge gate，用户已确认 2026-08-16）

本 PR 保持 Draft，不合并，直到以下条件满足：

1. 8 个 Growth Loop 迁移先经 Shadow Portal 控制面登记并在生产共享库执行（本仓库对共享库 proposal-only，不从本仓库执行生产迁移；迁移清单与执行顺序见 SHA-5 评论）。
2. 迁移落地后，再合入本 PR → main → Vercel 自动部署 → 前端与 DB 同时启用。

禁止前端先上线：合入 main 会触发 Vercel 生产部署，且 version-guard 会强制客户端尽快切到新构建；若 DB 未就绪，用户会直接看到 schema 错误/功能降级。因此前端代码不得先于 DB 迁移上线。

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
shadow-mate	Ready	Preview	Aug 17, 2026 3:48pm

[WardLu]

Review 通过（SHA-4 协调任务 · merge gate 已满足）

（注：当前账号为 PR 作者，GitHub 不允许自批准；本 review 以 comment 形式记录审查结论。）

Review 范围：PR #43 全部 38 个文件、6043 行新增（8 个迁移 + growth-loop 客户端模块 + 集成 + 测试）。合并门槛（8 个迁移经 Shadow Portal 控制面登记并执行到生产，SHA 8/8 一致）此前已在 SHA-4 核实闭合。

迁移层（8 个，已上生产，逐条审查）

• RLS 全部启用，anon 全部 revoke；authenticated 按最小权限授权；新表按 household membership 隔离。
• 受控写入函数（learning_record_points / learning_redeem_reward / learning_fulfill_redemption / learning_cancel_redemption / learning_record_activity_event）均 security definer + search_path=''，先校验 auth + owner/guardian 归属，再以 request_id 幂等。
• 账本只追加不覆盖：兑换借记 + 取消退款成对写入，触发器强制 redemption/refund 与 ledger 链接一致。
• 活动事件表在 private schema、revoke 公共角色、payload 键白名单 + 4KB 上限 + hash 去重，无 Data API 直读。
• 唯一改动现有表的是 learning_point_ledger 加 occurred_on date not null default current_date（PG12+ metadata-only），6 参 RPC 保留、7 参为新增重载，旧客户端不受影响。

客户端层

• Local-first：IndexedDB snapshot + outbox 事件模型，事件先落库再出投影；outbox 带租约、指数退避 + jitter、terminal 状态（conflict/rejected）。
• 云端 transport 以 request_id 幂等、错误分类（conflict/rejected/retryable）正确；拉取快照对未迁移环境返回空快照有保护，不会用空数据覆盖本地。
• 导出做字段白名单 + 敏感键清洗（auth/email/token/device/analytics 等均不导出）。
• 分析事件类型与 payload 键全部白名单，事件 ID 确定性生成以幂等，不含儿童个人标识。

CI / 验证

• PR checks：verify、analyze (javascript-typescript)、CodeQL、Shared Supabase Policy 均 SUCCESS。
• PR 描述记录的本地验证：unit 114/114、pgTAP 159/160、e2e 60/60、verify、release:check 全过（其中 1 项 e2e flaky 已按 CI 约定单独重跑通过）。

非阻塞观察（已记录，不构成合并阻塞）

1. 迁移 01420（drop+recreate 7 参函数）与 01037 函数体逐字节相同，为防御性幂等 no-op；控制面已按生产实际回填 remote_statement_count，保留即可。
2. private schema 依赖共享生产已存在（生产执行已验证，无实际风险）。
3. W4/W5/W6 的完整 test:full 留待其各自合入前在 CI 跑（见 #45/#46/#50）。

结论：审查通过，合入门槛满足、CI 全绿，可合并。