feat: complete huihui square avatar workflows

overview-huihui-auth-2026-07-21.md

@@ -0,0 +1,31 @@
+# 会会用户体系打通 · 部署与验证概览
+
+## 完成内容
+将 `digital-avatar-app` 的短信验证码登录从「DEV_MOCK 模拟」切换为**真实会会开放平台对接**，并部署到测试环境 `geo-server:/root/avatar-test`。
+
+## 关键改动
+1. **`backend/routers/huihui_auth.py` 重写**
+   - 真实端点：发码 `POST /open/mobile/sms/code`（query 参数）、登录 `POST /open/login/token`（formData，`loginType=code`）。
+   - 签名范式与会会官方 `sign(1).js` 逐字节一致：公共字段 `appId/accessId/timestamp(12h hh)/signType(MD5)/signVersion(1.0)/accessSecret/nonce` → 过滤空值 → 字典序 → `k=v&` → 末尾 `accessSecret=secretKey` → MD5/SHA256 大写。
+   - 登录成功后建/链本地 `users` 表（按会会 userId 唯一），签发本系统 `app_token` 会话。
+2. **真实凭证入环境**
+   - `geo-server:/root/avatar-test/.env`（及本地 `digital-avatar-app/.env`）：`HUIHUI_APP_ID / HUIHUI_ACCESS_ID / HUIHUI_ACCESS_SECRET`，`HUIHUI_DEV_MOCK=false`。
+   - `.env` 已被 `.gitignore` 与 `backend/.dockerignore` 排除，不会入库/入镜像。
+3. **时区 bug 修复（关键）**
+   - 容器默认 UTC，会会网关按**北京时间**校验时间戳 → 签名被拒（"签名验证失败"）。
+   - `_get_timestamp()` 改为显式 `timezone(timedelta(hours=8))`，与容器系统时区解耦（不用 `ZoneInfo`，slim 镜像缺 tzdata）。
+
+## 验证结果（测试环境）
+| 接口 | 结果 |
+|---|---|
+| `POST /api/huihui/sms/send`（13800000001） | 网关 `code=200 success, sent=true` ✅ |
+| `POST /api/huihui/sms/login`（假验证码） | 网关 `code=10000 验证码不正确`（签名已接受）✅ |
+| `GET /api/huihui/me`（无 token） | `401 未登录`（路由/鉴权门正常）✅ |
+| 前端 `:8099` → 后端 `:8000` | nginx `/api` 代理正常 ✅ |
+
+## 待用户操作
+在浏览器打开 `http://192.168.1.188:8099` → 短信登录页 → 输入**本人会会绑定手机号** → 获取真实验证码 → 登录。后端将调会会网关校验并写入 `users` 表，前端拿到 `app_token` + 会会资料后跳转。这是唯一未自动化的步骤（需真实手机号+真实验证码）。
+
+## 排查笔记
+- 测试服务器宿主 `:8000` 另跑 `ai-virtual-news-backend`；容器映射 `8011→8000`，本地冒烟测试必须打 `:8011`。
+- 部署前用独立脚本（managed venv + httpx）直连真实网关验证签名，避免盲部署。