# 产品架构 v2 · 账号与多端体系

> 用途：把「小博 AI 课」从**无登录静态站**，升级为**有账号、能云端存学习信息、多端多角色**的产品。定方案（账号策略 / 数据模型 / 前后端边界 / 隐私合规 / 迁移路径），先不写代码。
> 承接：现状 = 零依赖 Node（`server.js`）+ nginx + localStorage + `/api/apo`(mimo)。状态：v1 方案（2026-07）。

---

## 一、总原则
1. **游客先玩、登录再绑定**：不注册也能玩（本地存进度）；愿意保存/跨端/看报告时再登录，一键把本地进度迁上云。**绝不拿登录墙挡住体验**。
2. **数据最小化 + 儿童隐私优先**：只存「为学习服务」的数据；不采精准位置、不做广告画像；低龄需**家长同意**；可导出、可删除。
3. **一套 API，多端多角色**：Web（现）/ 未来小程序 / App 共用同一套后端；学生 / 家长 / 教师三种角色同源。

---

## 二、账号策略

> **早期最简版（✅ 已实现，2026-07）**：账号 = **邮箱 / 手机 / 用户名（任意）+ 密码**，**无验证码、无邮件/短信验证**，注册即用。服务端 `crypto.scrypt` 加盐哈希 + 随机 token，文件存储（`.data/accounts.json`）。接口：`POST /api/auth/register` · `POST /api/auth/login` · `GET /api/me` · `POST /api/progress`（token 鉴权，进度按「更完成」合并）。前端 `assets/auth.js` + `account.html`，登录后本地进度与云端双向合并。**验证码 / 微信 / 家长绑定 / 教师建班 = 后续增量**，不阻塞当前。

| 方式 | 说明 |
|---|---|
| **游客** | 打开即玩，进度存 `localStorage`（现状）。可随时「保存我的进度」触发登录并迁移。 |
| **手机验证码** | 主登录方式，门槛低、合规清晰。 |
| **微信登录** | 移动端便捷（未来小程序内）。 |
| **家长绑定** | 家长手机登录 → 绑定孩子账号 → 看素养报告。低龄账号由家长开通/同意。 |
| **教师** | 教师账号 → 建班 → 学生用班级码加入。 |

> 登录后：本地 `ai4k12_home` 的 `{xp, done[], 素养}` 一次性上传合并到云端 profile。

---

## 三、角色与端
| 角色 | 能做什么 | 端 |
|---|---|---|
| **学生** | 玩课、攒 XP/勋章、看自己的素养三维、问小博 Copilot | Web / 小程序 / App |
| **家长** | 看孩子素养报告与进度、放心（不编程/不刷屏/儿童安全） | Web / 小程序 |
| **教师** | 建班、布置、看班级进度、用一节当课/PPT | Web |
| **平台/众创**（后台） | 上传/审核选题、内容中台、数据看板 | Web 后台 |

---

## 四、数据模型（核心表）
```
users        用户：id, 手机/微信openid, role(student/parent/teacher), created_at
profiles     画像：user_id, nick, avatar, stage(学段), 素养三维{原,判,用}, xp, coins, streak
progress     进度：user_id, lesson_id, status(done), score, ts   （替代 localStorage）
badges       勋章：user_id, badge_key, earned_at
works        作品：user_id, lesson_id, payload(孩子的产出/答案快照)
content      内容中台：lesson_id, act, stage, json(小节JSON), source(借鉴出处), status, version
classes      班级：id, teacher_id, name, code
class_members 关系：class_id, student_id
relations    家庭：parent_id, child_id, consent(家长同意)
```
> `content` 表 = 内容中台：把每节的原子化 JSON 存库，支撑「一压千面」(学生课/教师PPT/家长报告) 与众创回填。

---

## 五、前后端边界
```
[前端 · 静态]  home/learn/lesson…（现零框架）
      │  fetch(JWT)
      ▼
[API · Node]  /api/auth(登录/验证码/JWT) · /api/me(画像) · /api/progress(读写)
              /api/badges · /api/content(取小节JSON) · /api/apo(Copilot·现有)
              /api/tts(小博语音·新，mimo TTS)   ← 交互标准要素①
      │
      ▼
[数据 · DB]   用户/进度/内容表（腾讯云）
```
- **鉴权**：手机验证码 → 签发 **JWT**；前端带 token 调 API。
- **存储**：现 zero-dep Node 之上加 **DB**（起步可 SQLite/文件；上量换 **Postgres** 或腾讯云 KV/云数据库）。进度先可用 KV（读写快、结构简单），画像/内容用关系表。
- **离线优先仍保留**：未登录/断网时本地可玩，联网再同步（乐观合并，以「更完成」为准）。

---

## 六、隐私与合规（儿童向硬约束）
- 最小采集：不要真实姓名/学校/精准位置；昵称+头像即可。
- **家长同意**：低龄账号由家长开通并知情同意；提供数据导出与一键删除。
- 内容安全：Copilot(/api/apo) 输出过滤、不吓唬、不诱导；家长可关。
- 密钥与安全：JWT 秘钥、DB、mimo/COS 密钥仅服务端；**之前聊天暴露过的密钥务必轮换**。

---

## 七、迁移路径（分阶段，不推倒现状）
1. **阶段 1（现状）**：游客 + localStorage，全站可玩。
2. **阶段 2 · 可选登录 + 云同步**：加 `/api/auth`+`/api/me`+`/api/progress` + DB；本地进度可上云、跨端。
3. **阶段 3 · 家长/教师端**：家庭绑定 + 素养报告页；教师建班 + 班级看板。
4. **阶段 4 · 内容中台 + 众创后台**：`content` 表 + 上传审核 + 一压千面渲染。
5. **阶段 5 · 小程序/App**：复用同一套 API。

> 每阶段独立可上线，先做**阶段 2**（登录+云存进度），价值最高、改动可控。

## 关联
| 文件 | 负责 |
|---|---|
| `product-architecture-v2.md`（本文） | 账号 / 数据模型 / 前后端 / 迁移 |
| `lesson-interaction-standard.md` | 一节课交互标准（含积分勋章、TTS） |
| `project-plan.html` | 项目总纲（含产品架构入口） |