# 账号同步接入方案

当前状态：应用仍然本地保存，未创建云端项目、未连接真实账号，也没有向云端上传学习记录。`cloud/schema.sql` 是待部署的数据库方案；不是已完成的云同步功能。

## 架构

采用 Supabase Auth 管理邮箱登录，PostgreSQL 保存学习数据，Row Level Security 将不同用户的数据隔离。词库继续作为公开静态文件随应用发布，不需要为每个用户重复上传。依据：[Supabase Auth](https://supabase.com/docs/guides/auth)、[用户数据管理](https://supabase.com/docs/guides/auth/managing-user-data)、[客户端初始化](https://supabase.com/docs/reference/javascript/initializing)。

```text
电脑／手机
    ├─ 本地缓存 + 待同步修改队列
    ├─ 邮箱登录 → Supabase Auth → 用户身份
    └─ 同步服务 → 自己的收藏／复习记录／设置／练习事件
                     ↑ RLS 用户隔离 + 版本检查
```

## 同步哪些数据

| 范围 | 记录键 | 数据 |
| --- | --- | --- |
| 收藏 saved | 词条稳定 ID | 收藏状态；取消收藏保留删除标记 |
| 复习 progress | 方向:词条ID | 阶段、到期时间、上次评分 |
| 设置 settings | 每个设置的名称 | 每日目标、方向、语速 |
| 练习 review_event | 每次练习的 UUID | 词条、方向、评分、时间、设备时区 |

练习次数由事件去重聚合，不能把两台设备各自的“今日总次数”直接相加。浏览器中的旧数据保留为游客档案；首次登录时明确选择导入本机游客数据，不能悄悄把另一账号的数据上传到新账号。

## 冲突和断网

1. 每次操作先写入按用户 ID 分区的本地缓存与 outbox，保证离线可用。
2. 登录、网络恢复、页面重新可见时拉取云端增量；分页拉取，不能假定一次返回全部记录。
3. 逐条上传修改，并附最后读取的 revision；数据库锁定该行并比较版本。
4. 版本一致才写入，否则返回云端当前记录。无冲突字段可合并；同一词同一方向同时评分时结合练习事件重新计算，不能仅按设备时钟覆盖。
5. 取消收藏写 tombstone，避免旧设备重新上传后让收藏“复活”。重试沿用同一个事件 UUID。
6. 退出登录后清除会话并切换到游客数据；账号 A 与 B 的缓存和待上传队列始终隔离。同步失败显示“本机已保存，待同步”，不显示成功。

数据库示例见 `cloud/schema.sql`。它提供用户隔离和带 revision 检查的单条写入 RPC；客户端登录、outbox、冲突处理和多设备集成测试仍需在选定项目后实现。需要特别验证两账号互不可读、离线修改重连、同时编辑、删除标记、会话过期、退出后换号以及超过 1,000 条记录的分页同步。

## 正式启用需要

- 一个由你持有的 Supabase 项目。
- Project URL 与 **publishable key（公开客户端密钥）**。不要提供数据库密码、secret key 或 service_role key。
- 应用正式 HTTPS 域名，用于登录回调；开发时可以先配置 localhost。
- 邮箱登录方式：验证码或密码。正式邮件发送需要配置对应邮件服务。

后续接入顺序：部署表结构 → 配置邮箱认证和回调 → 实现客户端账号隔离与队列 → 接入同步 → 两个设备、两个账号做验证 → 上线。云服务地区及邮箱送达情况应按实际使用地点验证。

## QQ、微信登录：从零开始

可以接入。第三方登录确认“你是谁”，收藏与进度还需本应用自己的数据库存储。目前没有域名或开放平台应用，因此本版只提供说明，未启用 QQ／微信登录。

1. 准备正式 HTTPS 网站地址和后端／数据库，让手机和平板能通过同一个网址访问。
2. QQ：在 QQ 互联注册开发者，按要求审核资质，创建网站应用，填写网站名称、域名与回调地址，申请 AppID 和 AppKey，完成平台要求的上线审核。官方准备工作：https://wiki.connect.qq.com/准备工作_oauth2-0 。
3. 微信：在微信开放平台申请适合网站的登录能力。先在控制台确认当前主体资质、认证及网站应用审核要求；网站扫码登录与微信内网页授权是不同场景，需要分别确认可用能力。官方入口：https://open.weixin.qq.com/ ，网站登录文档：https://developers.weixin.qq.com/doc/oplatform/Website_App/WeChat_Login/Wechat_Login.html 。本次工具未能读取微信官方文档，故不承诺个人主体资格、费用或审核时长，以控制台当前规则为准。
4. 获得应用资格后，在服务端配置密钥及回调，完成授权、校验和用户会话。密钥不放入 HTML、前端代码或离线包，也无需发到聊天中。
5. 将第三方身份绑定到本应用账号，再同步收藏、复习和设置。在手机与电脑上测试同一账号恢复、断网重连与退出换号。

### 与现有方案的关系

之前的 Supabase SQL 仍是邮箱账号方案的数据库草案，不表示已支持 QQ／微信。若使用第三方认证网关或自建 OAuth 后端，需要先设计可信的身份映射和数据库授权，不能把 QQ OpenID 直接当成 Supabase 会话。身份唯一键应包含平台、应用和 OpenID；多个登录方式需通过已登录的绑定流程关联，不能按昵称或头像自动合并。

授权回调需校验一次性 state、固定回调地址并在后端换取凭据；会话使用安全 Cookie，日志避免记录密钥或完整令牌。云端学习记录始终按本应用用户 ID 隔离。

建议顺序：先上线网站和一种账号同步方式，再增加第二种第三方登录。平台注册、认证或托管若产生费用，待选定方案后单独确认，本次没有购买或开通服务。单文件离线版继续支持备份导入导出，但无法独自完成云端认证与同步。