Lampio 知识库

主题

Supabase 统一维护到 RB — 迁移计划 ​

创建 2026-06-15。跨端重构，分会话执行（CLAUDE.md §9）。本文件是跨会话进度真相。 决策范围：Schema 真相源 + 全部 13 个 Edge Function 统一归 RB（用户 2026-06-15 选定）。

⚠️ 本文件物理存放在 RB 仓库（~/reading-browser/docs/plans/archive/supabase-consolidation-plan.md， ~/reading-browser 软链 → /Users/larry/reading-browser）。 RVH 会话请用绝对路径读取：Read ~/reading-browser/docs/plans/archive/supabase-consolidation-plan.md ——在 RVH 仓库内 grep / 找 docs/plans/... 是找不到的（不同 repo，相对路径各自为根）。 同理本文件中所有 RB/... 指 ~/reading-browser/...，RVH/... 指 ~/reading_vocab_helper/...。

目标 ​

把共享 Supabase 后端的维护收敛到 RB 仓库一处，消灭 RB/RVH/Supabase 三端 drift（/cross-end-check 存在的根因）。

背景：两端现状（勘查于 2026-06-15） ​

  • Edge Functions 不重叠（无重复，各有其家）：
    • RB（10）：analyze-articles · discover-sites · disambiguate-sense · explain-phrase · breakdown-sentence · resolve-context · generate-example · reading-report · issue-speech-token · tts-synthesize
    • RVH（3 + _shared/cors.ts）：google-books-proxy · gutenberg-proxy · lookup-or-fetch-word
    • 13 个都部署到同一 Supabase 项目（jdtbyteiwnciqnfppztz）。
  • 关键洞察：所有 function 共用一个项目、URL 稳定，RVH Dart 端只按 URL invoke → function 源码挪仓库，RVH 运行时零影响。
  • 真正的双份维护痛点 = Schema：RVH 用 supabase/migrations/*.sql（停在 v51 + drop_user_word_fkeys），RB 用拍平 supabase/sql/sync-tables.sql。同一套共享表两种表征 → cross-end-check.sh:260 已报 RVH migrations 滞后。
    • 已核实：RB sync-tables.sql 含 last_opened_at（Sprint C-1），真相源本就完整领先，RVH 才是滞后方。

终态 ​

RB/supabase/
├── functions/   # 13 个（RB 10 + 迁自 RVH 的 3）
└── sql/         # 共享表 DDL + RLS = 唯一真相源

RVH/supabase/
├── functions/   # 删除 google-books-proxy / gutenberg-proxy / lookup-or-fetch-word / _shared
└── migrations/  # 不再为共享表加 migration；仅保留词库 pipeline 相关

两条不碰的红线：

  • 预装词库 pipeline（reading_vocab.db）留在 RVH（红线 #10），那是数据 pipeline 不是 Supabase 后端。
  • RVH 侧任何删除/改动必须新开 RVH 会话（§9）。

执行顺序（卡死，避免过渡期 drift） ​

阶段 1 — RB 会话（本会话，2026-06-15）✅ 进行中 ​

  • [x] 复制 RVH 3 个 function 源码进 RB/supabase/functions/
  • [x] 删除随带的 _shared/（3 个 function 内联 corsHeaders，未 import，死代码）
  • [x] 核实 secret 依赖在共享项目已具备：GOOGLE_BOOKS_API_KEY（google-books）、平台自动注入 SUPABASE_*（lookup-or-fetch-word）、gutenberg 无
  • [x] 确认 RB sync-tables.sql 为完整真相源（含 last_opened_at）
  • [x] 更新 supabase/README.md（13 functions，标注迁自 RVH/RVH 侧待删）
  • [x] 验证 RB 能作为 deploy origin（2026-06-15）：从 RB 部署 3 个全部成功（Deployed Functions on project jdtbyteiwnciqnfppztz）+ CORS preflight 冒烟 3 个全 HTTP 200 → RB 确认可作唯一 deploy 源
  • [ ] commit

阶段 2 — RVH 会话（新开，§9）✅ 完成（2026-06-15） ​

触发：阶段 1 commit 且 RB deploy 验证通过后启动。

  • [x] 删除 RVH/supabase/functions/{google-books-proxy,gutenberg-proxy,lookup-or-fetch-word,_shared}（删前 diff -rq 确认与 RB 字节一致；_shared 经 grep 确认 3 个 function 均未 import = 死代码）
  • [x] 约定：RVH 不再为共享表写 migration（supabase/migrations/ 仅保留词库 pipeline 相关）；共享表结构以 RB supabase/sql/sync-tables.sql 为准 → 落 RVH/supabase/migrations/README.md
  • [x] 更新 RVH 侧文档（指向 RB 为 Supabase 后端真相源）：docs/deployment/edge-function-deployment-guide.md（顶部 banner）/ docs/deployment/README.md / docs/database/cross-end-schema-compatibility.md（步骤 2）+ 新增 RVH/supabase/functions/README.md 指针
  • [x] 验证 RVH app 运行时正常：Dart 端按稳定 URL/函数名 invoke（app_config.dart + supabase_vocabulary_service.dart），lib/ 无任何 supabase/functions 源码引用；flutter analyze lib/ = 0 error（删除的仅 Deno TS，不入 Flutter 编译）

风险与处置 ​

风险处置
过渡期两边都有这 3 个 function 源码阶段顺序卡死：RB 接收+验证 → 才由 RVH 删除；期间线上仍是同一份部署，无功能差异
后端归属变模糊（RVH book proxy 在 RB 仓改）单维护者场景下"一处维护"收益 > 归属洁癖；README/本 plan 记录归属变更
RVH 误以为还能在本地改这 3 个RVH 侧文档明确指向 RB；删除原件后自然杜绝
共享表 schema 变更协议维持 §9 协议：RB 先改 sync-tables.sql + Supabase Dashboard 执行 → RVH 跟进 Dart schema（不再写共享表 migration）

回滚 ​

  • 阶段 1 仅新增文件 + 一次 deploy（identical bytes），回滚 = git revert + 无需重部署（线上未变）。
  • 阶段 2 删除前 RVH 仓有 git 历史，可恢复。

RVH → RB 回执（2026-06-15，RVH 会话） ​

阶段 2 全部完成并提交，RVH 仓 commit 0264373（chore(supabase): 阶段2 收敛 Edge Function 维护到 RB，10 files，+64/−892）。

  • 3 个 function + _shared 已从 RVH 删除；删前 diff -rq 逐目录确认与 RB 字节一致，_shared/cors.ts 经 grep 确认无 import（死代码）。
  • RVH 侧新增 supabase/functions/README.md + supabase/migrations/README.md + 3 处部署/跨端文档 banner，全部指向 RB 为后端真相源。
  • 运行时零影响已验证：RVH Dart 按稳定 URL/函数名 invoke，flutter analyze lib/ = 0 error。
  • 未碰红线 #10（预装词库 pipeline reading_vocab.db 仍归 RVH）。

留给 RB 会话的两项收尾（非 RVH 职责）：

  1. 阶段 1 的 - [ ] commit（functions 迁入 + README + 本 plan）尚未打勾 —— RB 仓那批改动需在 RB 会话提交。
  2. 本回执随 RB 仓提交即闭环；此后共享后端（13 functions + 共享表 DDL）唯一真相源 = RB，按 §9 协议演进。