# 微信登录与教师身份实施方案

本文记录已经实现的“微信身份换取后端会话”体系，以及部署和旧数据迁移步骤。完成生产配置与双账号验收前不应公开发布小程序。

## 当前状态

代码已实现数据库迁移、微信换码接口、随机会话令牌、统一 Bearer 鉴权、小程序自动登录与单次重试，以及旧用户归属迁移命令。部署时仍需完成：

1. 在 5700U 的 `server/.env` 填写 `WECHAT_APP_ID` 和 `WECHAT_APP_SECRET`。
2. 重建镜像并运行数据库迁移。
3. 使用目标微信账号首次登录，记录“我的”页面显示的新内部 UUID。
4. 备份数据库后运行 `migrate-user-owner`，把旧开发 UUID 数据交给该账号。
5. 使用两个微信账号验证数据隔离，确认生产 `ALLOW_DEVELOPMENT_USER_HEADER=false`。

## 目标流程

```text
小程序调用 wx.login()
  -> 将一次性 code 发送到 Rust POST /api/v1/auth/wechat/login
  -> Rust 使用服务端 AppID、AppSecret 调用微信 code2Session
  -> 微信返回 openid（unionid 可选）
  -> Rust 查找或创建内部教师 UUID
  -> Rust 签发项目自己的随机会话令牌
  -> 小程序以 Authorization: Bearer <token> 调用普通接口和上传录音
```

微信官方入口：

- [`wx.login`](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html)
- [`code2Session`](https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/user-login/code2Session.html)
- [小程序登录流程](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/login.html)

`WECHAT_APP_SECRET` 只能保存在 Rust 服务环境变量中。小程序不得包含 AppSecret，也不得接收或保存微信 `session_key`。当前阶段只需要 `openid` 识别当前小程序中的教师。

## 数据模型

新增三张表：

```text
users
  id uuid primary key
  status text not null
  created_at timestamptz not null
  updated_at timestamptz not null

wechat_identities
  app_id text not null
  openid text not null
  unionid text null
  user_id uuid not null references users(id)
  created_at timestamptz not null
  last_login_at timestamptz not null
  primary key (app_id, openid)

auth_sessions
  id uuid primary key
  user_id uuid not null references users(id)
  token_hash bytea not null unique
  expires_at timestamptz not null
  last_used_at timestamptz not null
  revoked_at timestamptz null
  created_at timestamptz not null
```

业务表继续使用现有 `owner_id` UUID，不直接使用 `openid`。这样微信身份变化、未来增加手机号或管理员账号时，不需要重写业务数据。

## 后端接口

### `POST /api/v1/auth/wechat/login`

请求：

```json
{ "code": "wx.login 返回的一次性 code" }
```

处理要求：

1. 校验 code 非空并限制长度；进程内最多同时执行 8 个微信换码请求，反向代理仍应按来源限制登录频率。
2. Rust 使用 `WECHAT_APP_ID`、`WECHAT_APP_SECRET` 调用 `code2Session`。
3. 微信返回错误码、缺少 `openid` 或网络失败时返回明确的 `401`/`502`，日志不得记录 AppSecret、session_key 或完整 code。
4. 按 `(app_id, openid)` 原子地查找或创建本地用户。
5. 生成至少 32 字节的加密安全随机令牌，只把 SHA-256 哈希写入数据库。
6. 原始令牌只在本次响应中返回，建议有效期 30 天。

响应：

```json
{
  "access_token": "后端随机会话令牌",
  "expires_at": "2026-08-20T00:00:00Z",
  "user_id": "内部教师 UUID"
}
```

同时增加：

- `GET /api/v1/auth/me`：返回当前内部用户 ID 和会话到期时间。
- `POST /api/v1/auth/logout`：撤销当前令牌。

## 业务接口鉴权

实现统一的 Axum 身份 extractor：

1. 读取 `Authorization: Bearer <token>`。
2. 对 token 做 SHA-256 后查询 `auth_sessions`。
3. 拒绝不存在、已撤销、已过期或用户已停用的会话。
4. 将数据库中的 `user_id` 作为业务 `owner_id`，客户端不能提交或覆盖它。

普通 JSON 请求和 `wx.uploadFile` 必须使用相同的 Bearer token。不得把 `openid`、`user_id` 或固定 UUID 当成可信请求头。

本地开发可暂时保留 `X-User-Id`，但必须由显式环境变量控制：

```env
ALLOW_DEVELOPMENT_USER_HEADER=false
```

生产默认和 `compose.deploy.yml` 必须为 `false`。只有本地测试环境可设置为 `true`，并在日志中显示开发鉴权已开启。

## 小程序登录状态

新增独立 `utils/auth.ts`：

1. 从微信 Storage 读取后端 access token 和到期时间。
2. 没有有效 token 时调用 `wx.login()`，再调用后端登录接口。
3. 使用共享的 `loginPromise` 合并并发登录，避免多个页面同时换取 code。
4. 所有 `wx.request` 和 `wx.uploadFile` 自动附加 Bearer token。
5. 收到一次 `401` 时清理本地 token、重新登录并重试原请求一次，禁止无限重试。
6. 退出登录时先调用后端撤销接口，再清理 Storage。

“我的”页面移除固定开发 UUID，改为显示登录状态和内部教师 ID；不显示 `openid`、session_key 或完整 access token。

## 现有开发数据归属

当前数据属于固定开发用户：

```text
5a4da7f0-d70c-465f-bcab-124c504aa9f0
```

不能把这些数据自动交给“部署后第一个登录的人”，否则存在抢占风险。采用一次性管理命令迁移：

1. 先发布微信登录功能，由目标微信账号完成一次登录并取得新的内部用户 UUID。
2. 在服务端运行受控 CLI：

```text
docker compose -f compose.deploy.yml run --rm --no-deps api \
  migrate-user-owner \
  --from 5a4da7f0-d70c-465f-bcab-124c504aa9f0 \
  --to <新用户UUID>
```

3. CLI 在单个数据库事务中更新学生档案、预设、反馈记录和反馈会话的 `owner_id`。
4. 遇到目标账号已有同类数据或唯一约束冲突时中止并报告，不做部分迁移。
5. 迁移前备份数据库，迁移后比较每张表的记录数并进行页面验收。

CLI 不接收 `openid` 或 AppSecret；它只合并两个经过后端确认的内部 UUID，便于审计和回滚。

## 分阶段交付

1. 数据库迁移、微信 API 客户端、登录接口和会话存储。
2. 后端统一 Bearer extractor，同时在本地保留受控的开发头兼容模式。
3. 小程序登录管理、普通请求和录音上传的自动鉴权与一次重试。
4. 自动化测试：code2Session 模拟、令牌过期/撤销、跨用户隔离、上传鉴权和并发登录。
5. 部署环境变量并验证目标微信账号登录。
6. 运行一次性旧数据迁移，关闭生产 `X-User-Id`，最后再提交体验版测试。

## 发布验收

- 两个不同微信账号看到的数据互相隔离。
- 客户端伪造 `X-User-Id`、`openid` 或 `user_id` 无法越权。
- access token 过期或撤销后必须重新登录。
- 普通接口和录音上传均能在 token 刷新后重试一次。
- AppSecret、session_key 和令牌未出现在代码、Git、日志或错误响应中。
- 原开发用户数据仅归属指定的目标微信账号。