山海同文开发计划 v1.0Shanhai Tongwen · Engineering Delivery Plan · v1.0

版本 1.0 · 2026 年 9 月 · 依据《山海同文落地方案 v3.0》（docs.gacee.org/shanhai-plan）与 JurisEdu 平台现状（jurisedu/jurisedu 0.14.0）。本计划只覆盖工程交付；商务、教研、合规工作流以落地方案为准。

1. 目标与范围

• 交付目标：10 月底冻结 MVP，11 月起支撑三国各一校、每校 20–40 名学员的六周试点；复盘前产出方案 §00 六条成功标准所需的全部系统数据。
• MVP 范围（方案 §05 表）：录播 + 会议工具直播 + PWA 离线练习 + 伴学与复习两个智能体 + 客观题与拍照作业 + 老师复核队列与 AI 提议收件箱 + 学校端名册与周报 + 运营端复用超管台 + 四种界面语言（中 / 英 / 斯瓦希里 / 法）+ 图书馆网页阅读器。
• 明确不做（阶段 2）：发音评测、情景对话、评测与班主任智能体、可验真结业证明、原生安卓 App、企业委托班、法语与斯瓦希里语讲解脚手架。

2. 系统边界与复用

后端新增模块以本仓库 contracts/hanqiao-api.yaml 为契约，在 jurisedu 仓库以分支 feat/hanqiao-* 提交；迁移编号自 360 起（当前最新 359）。

3. 里程碑（与落地方案对齐）

4. 迭代计划（两周一个 Sprint，MVP 共三个 Sprint）

Sprint 0 · 脚手架（本周，已完成大部分）

• 仓库、工作区、CI、Dockerfile、环境变量
• BFF 代理 + httpOnly 会话 + 邮箱验证码登录（夹具 / 真实两种模式）
• 离线层：Dexie 模型、出站队列与同步引擎（含单测）、PIN 保险库、内容包下载与校验、FSRS 排程
• Serwist 服务工作线程与 /offline 回退
• 学员端：今日、复习卡、直播入口、课程与离线包；老师端工作台；学校 / 运营 / 企业占位
• 契约 v0.1（/api/coach/hq/*）、ADR-H01–H10
• 后端：internal/hanqiao 包骨架 + 迁移 360（hq_packs、hq_pack_items、hq_live_sessions、hq_live_joins、hq_sync_events、hq_sync_cursors、hq_devices）PR 提交

Sprint 1 · 学员闭环（9 月第 3–4 周）

• 后端：today（基于 me/kg + 课表 + 停电档案）、cards、sync（幂等、序号、变更推送）、packs 清单与签名 URL；HSK 一级图谱子树种子（体系 → 学段 → 主题 → 知识点，词汇 / 语法 / 汉字 / 场景）
• 前端：今日与复习卡切换到真实接口；录播播放器（HLS，纯音频档）；随堂练与客观题判分（端侧）；拍照作业上传（离线先存）→ /coach/recognize
• 质量：Playwright 离线场景（限速 256 kbps、丢包 5%）；2 GB 安卓真机基线；PoC-3/4 记录表
• 验收：一名学员在飞行模式完成三组练习并在 24 小时后同步零丢失

Sprint 2 · 老师与学校闭环（10 月第 1–2 周）

• 后端：老师端 sessions（Zoom / 腾讯会议适配层，创建会议、回收录制）、recording → 转码任务 → pack 版本；review-queue 与 proposals 的山海同文字段；名册导入沿用 /coach/kb + kb/setup 提议 → 批准；学校周报聚合（出勤含回放）
• 前端：老师复核队列（只看分歧与主观项）、AI 提议审批、直播控制台、录课上传；学校端名册导入、同意书覆盖率看板、设备与缓存点状态、周报
• 质量：双 Agent 一致率与转人工率进入周报；租户隔离自动化测试纳入 CI（后端）
• 验收：一位老师用一小时完成一周的发布、直播、复核、审批

Sprint 3 · 冻结与试点准备（10 月第 3–4 周）

• 后端：租户预算护栏（ADR-7）、成本报表、评估集 200 题门禁、渗透测试整改；学校缓存点镜像脚本
• 前端：共享设备多账号（PIN 保险库）全流程；图书馆阅读器（整本缓存、划线、生词进复习卡）；界面语言四语审校；性能预算（冷启动 ≤ 5 秒、首屏 ≤ 1.5 MB gzip、存储 ≤ 150 MB）
• 运维：learn.gacee.org 切换到产品应用（原型迁至 demo.gacee.org）；staging 环境；发布与回滚演练
• 验收：M2 门禁全部通过

试点期（11–12 月）与阶段 2（次年 1–3 月）

• 试点期每周一个小版本：只修缺陷与指标采集，不加功能；周五 30 分钟弱网演示
• 阶段 2 Sprint 4–9：发音管线（ASR + GOP + 声调）、情景对话、评测与班主任智能体、可验真证书、原生安卓 App（Expo，复用 mobile-edu 客户端模式与本仓库同步协议）、企业委托班、法语 / 斯瓦希里语脚手架

5. 团队与分工（工程）

6. 环境与流程

• 本地：npm run dev（夹具模式无需后端）；接真实后端时启动 jurisedu 的 docker compose（Postgres / Neo4j / Redis / RabbitMQ）与 go run ./cmd/api，设置 JE_API_MODE=live。
• 分支与评审：main 受保护；功能分支 → PR → CI 绿 + 一人评审；后端契约变更须同时更新 contracts/ 并在 PR 描述引用。
• 环境：development（本地）→ staging（NEXT_PUBLIC_ENV=staging，样例数据标记）→ production（learn.gacee.org）。生产仅通过标签发布。
• 版本：package.json 为唯一真源，SemVer；每个 Sprint 结束打标签 v0.x.0；试点期热修 v0.x.y。
• 配置：所有密钥只在服务端环境变量；NEXT_PUBLIC_* 不含敏感信息；功能开关见 ADR-H09。

7. 测试策略

8. 风险与依赖（工程）

9. 发布与运维

• 镜像：apps/web/Dockerfile（standalone），部署到 JE 新加坡 ACK（与 mobile-edu 同一发布范式）或 Vercel（staging）。
• 回滚：镜像 sha 不可变；回滚即切换上一 sha；服务工作线程随版本化缓存自动失效。
• 监控：BFF 5xx 率、刷新失败率、同步成功率、降级触发次数、离线练习占比、首屏耗时（真机）。
• 试点周报字段来自 sync 事件与 JurisEdu 观测层，按校自动生成。

10. 立即执行清单

1. 在 jurisedu 仓库建分支 feat/hanqiao-foundation：internal/hanqiao 骨架、迁移 360、路由挂载 /api/coach/hq/*（先返回契约示例）。
2. 由 JE 运维创建 GACEE 一级租户与三所试点校子租户（ADR-1），发放老师与学校管理员账号。
3. 教研提供 HSK 一级前六周的知识点清单与 300 题，用于图谱种子与复习卡。
4. 申请 Zoom Server-to-Server OAuth 与腾讯会议企业 API 凭据。
5. 采购两台 2 GB 内存安卓测试机；在 CI 增加真机结果上传。

山海同文架构决策记录（ADR-H 系列）

编号与落地方案 §05 的 ADR-1 至 7 互补：方案级决策（租户、直播来源、离线策略、模型路由、记忆、数据驻留、成本护栏）以方案为准；本目录记录工程实现层的决策。状态：已采纳（Accepted）除非另注。

ADR-H01 · 仓库边界：产品仓库 + 平台单体

• 决策：山海同文产品代码（学员 PWA、老师 / 学校 / 企业 / 运营界面、BFF、离线层、接口契约）放在独立仓库 jurisedu/hanqiao；所有服务端能力（租户、课程图谱、评测、智能体、证书、直播会话、内容包、同步）实现于 JurisEdu 单体 jurisedu/jurisedu（services/backend/internal/hanqiao），以 /api/coach/hq/* 暴露。
• 理由：落地方案约定平台底座归平台、内容与品牌归协会；产品仓库按协会域名（learn.gacee.org）独立发布，平台仓库沿用其 CI、迁移、RLS 与发布门禁。避免在协会产品仓库中出现第二个数据存储。
• 后果：前后端以 contracts/hanqiao-api.yaml 为契约并行开发；前端在契约就绪前以夹具模式运行；后端变更走 jurisedu 的 PR 流程。

ADR-H02 · 前端栈：Next.js 15 App Router + React 19 + TypeScript

• 决策：沿用交互原型（hanqiao-mock）的技术栈与设计系统（CSS 变量、七语词典、Shell / ui 组件），保证从原型到产品的视觉连续性；生产构建为 standalone 输出，可容器化部署到 JE 新加坡集群，也可部署 Vercel。
• 替代方案：Vite + React（与 JE apps 一致）。放弃原因：PWA 与 BFF 需要服务端路由与流式渲染，App Router 一体化更省。

ADR-H03 · BFF 代理与 httpOnly Cookie 会话

• 决策：浏览器只与同源 /api/je/* 通信；Next 路由处理器持有访问令牌与刷新令牌（httpOnly、SameSite=Lax、生产 Secure），转发到 JurisEdu 并在 401 时刷新一次后重放。登录用 JurisEdu 邮箱验证码端点。
• 理由：令牌不落浏览器存储，降低 XSS 泄露风险；服务工作线程可对同源 GET 做缓存；X-JE-Tenant 由 BFF 统一注入。
• 后果：离线时 BFF 不可达，屏幕依赖本地快照（ADR-H05）；原生 App 阶段改用与 mobile-edu 相同的直连 + 安全存储模式。

ADR-H04 · 离线外壳：Serwist 服务工作线程

• 决策：应用外壳与静态资源预缓存；/api/je/* GET 走 network-first（8 秒超时后回退缓存）；内容包条目由 lib/offline/packs.ts 写入 Cache Storage（hq-packs-v1）并 cache-first；导航失败回退 /offline。开发模式禁用服务工作线程。
• 理由：PWA 先行是方案 ADR-3 的要求；Serwist 是 Next App Router 的 Workbox 继任者。

ADR-H05 · 本地存储与同步：Dexie + 事件溯源出站队列

• 决策：IndexedDB（Dexie）保存账号、内容包状态、复习卡、快照与出站队列；每条学习事件带幂等键；服务器单调序号为权威，客户端游标只在成功应用变更后推进；冲突规则「进度 = 服务器权威 + 事件合并，笔记 = 最后写入」；复习排程（FSRS 近似）在端侧运行。
• 理由：满足 PoC-4「零丢失、≤ 60 秒同步、崩溃安全」；引擎为纯函数，可在 Node 中单测。

ADR-H06 · 共享设备多账号：PIN 派生密钥的本地保险库

• 决策：同一设备多个学员账号并存；每账号以 PBKDF2-SHA256（600k 次）从 PIN 派生 AES-GCM 密钥，仅驻内存；出站队列载荷与快照可加密；内容包按引用计数共享；忘记 PIN 仅丢失本地未同步数据。原生 App 改用 Argon2id。
• 理由：PoC-6；WebCrypto 无原生 Argon2。

ADR-H07 · 内容包格式

• 决策：清单（id、version、unit、items[{id,type,url,bytes,sha256,lang}]）+ 条目文件；HLS 阶梯 240p/360p/480p/720p + 纯音频；6 秒切片；每包 AES-128 密钥由后端签发短期 URL；客户端逐条校验 SHA-256，全部通过才标记 ready；版本升级标记 stale。
• 理由：方案 §06 第六节；断点续传按条目粒度。

ADR-H08 · 直播适配：会议工具深链 + 平台侧点名与回放

• 决策：MVP 不集成 RTC SDK；老师端在平台创建会话，后端通过 Zoom / 腾讯会议 API 创建会议并回收录制；学员端按地区推荐入口并在 join 时记录进入；回放 15 分钟内可看并计入出勤。适配层接口固定，阶段 2 可替换商用 RTC。
• 理由：方案 ADR-2 与 PoC-1。

ADR-H09 · 功能开关与阶段门禁

• 决策：NEXT_PUBLIC_FLAGS 控制 offline_packs / shared_device / live_deeplink / agent_companion / photo_homework / pronunciation / certificates；每个开关对应一张 PoC 卡或阶段门禁，未通过门禁的能力在生产关闭。

ADR-H10 · 观测与质量门禁

• 决策：CI 门禁 = typecheck、lint、单测、构建、契约检查、学员首屏 gzip ≤ 1.5 MB；Playwright 覆盖登录、离线复习、同步；2 GB 安卓真机作为验收基线；遥测事件（同步成功率、降级触发、离线练习占比）通过 sync 事件回流后端观测层。