docs: add miniprogram phone quick login design.

Capture the approved WeChat getPhoneNumber login flow for shanxia mini program, including WECHAT_MP_* config, sys_user openid columns, and parity with password login JWT.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/superpowers/specs/2026-09-18-miniprogram-phone-quick-login-design.md

@@ -0,0 +1,222 @@
+# 山峡小程序「手机号快捷登录」设计
+
+> 日期：2026-09-18  
+> 适用范围：`miniprogram` 登录页 + `backend` 微信换票 / 绑号  
+> 参考实现：`/Users/zlwu/work/00code/zkxw`（`mobile-h5` + `backend` mini auth）  
+> 视觉：登录页协议/隐私下方新增按钮，样式对齐 zkxw「手机号快捷登录」
+
+---
+
+## 1. 目标与已确认决策
+
+### 1.1 目标
+
+1. 登录页在协议、隐私下方增加「手机号快捷登录」按钮；点击后可完成登录并进入工作台。
+2. 账号密码登录保持现有行为，与快捷登录互不影响。
+3. 快捷登录用微信手机号匹配已有 `sys_user.phone_no`；唯一命中则登录并绑定 `wx_openid`；未找到 / 多账号失败（不自动注册）。
+
+### 1.2 决策摘要
+
+| 项 | 约定 |
+|----|------|
+| 身份策略 | 对齐 zkxw：`phone_no` 匹配 + 绑定 `wx_openid` |
+| 自动注册 | **不做** |
+| 密码登录后静默绑微信 | **不做**（仅快捷登录路径绑号） |
+| 仅 openid 静默换票接口 | **不做**（本期不做 `wechat-bind` / silent login） |
+| 密钥配置 | **新增** `WECHAT_MP_APPID` + `WECHAT_MP_SECRET`；`WXPAY_*` 不动 |
+| 前端交互 | 协议下方按钮；`open-type="getPhoneNumber"` + 同次 `uni.login`；未勾选协议时确认键同次拉授权 |
+| JWT | 与密码登录同一套 access / refresh / userInfo |
+
+### 1.3 非目标
+
+- 密码登录成功后静默绑定 openid
+- 仅 openid 静默登录 / OA 深链换票
+- 自动注册新用户
+- web-admin 微信登录
+- 改微信支付 / 模板消息现有 `WXPAY_*` 配置用途
+- 客户端 / 供应商 / 配送员多端分 App 登录
+
+---
+
+## 2. 端到端流程
+
+```
+登录页「手机号快捷登录」
+  →（未勾选协议）确认弹窗「同意并登录」确认键 open-type=getPhoneNumber
+  →（已勾选）button open-type=getPhoneNumber
+  → e.detail.code → phoneCode
+  → uni.login → loginCode
+  → POST /api/mini/auth/wechat-login { loginCode, phoneCode }
+  → 后端 jscode2session → openid
+  → 后端 getuserphonenumber → 规范化手机号
+  → 按 phone_no 唯一匹配 sys_user（status 正常、del_flag=0）
+  → 首次写 wx_openid；已绑则校验一致
+  → 签发 JWT（同密码登录）
+  → 前端存会话 → 拉 menu-codes → 进工作台
+```
+
+密码登录：现有 `POST /api/web/auth/login`（RSA）不变；**不**调用微信绑号。
+
+---
+
+## 3. 配置
+
+### 3.1 后端环境变量（新增）
+
+| 环境变量 | 用途 | 说明 |
+|----------|------|------|
+| `WECHAT_MP_APPID` | 小程序 AppID | 与门户正式号一致：`wx7db1ddb2a90c9425` |
+| `WECHAT_MP_SECRET` | 小程序 AppSecret | 仅后端；禁止写入前端源码 |
+
+`WXPAY_MINI_APPID` / `WXPAY_SECRET` **保持不动**（支付/模板消息）。
+
+另需：
+
+| 项 | 说明 |
+|----|------|
+| `API_ENCRYPT_EXCLUDE_PATHS` | 加入 `/api/mini/auth/wechat-login` |
+| 前端 `manifest.json` → `mp-weixin.appid` | 已是 `wx7db1ddb2a90c9425`，须与 `WECHAT_MP_APPID` 一致 |
+
+实现完成后由人工将真实 `WECHAT_MP_SECRET` 填入 `backend/.env` / `.env.production`。
+
+### 3.2 微信公众平台前置条件
+
+| 要求 | 说明 |
+|------|------|
+| 主体 | 非个人主体，且已完成微信认证 |
+| 能力 | 开通「手机号快速验证」（可能按次计费） |
+| 合法域名 | request 域名含现有 API 主机（如 `w.shanxiachem.com`） |
+| 基础库 | 使用新版 `e.detail.code`（约 ≥ 2.21.2）；不用旧版 encryptedData 解密 |
+| 验收 | 以真机为准（开发者工具对 getPhoneNumber 不可靠） |
+
+官方参考：
+
+- [手机号快速验证组件](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/getPhoneNumber)
+- [getuserphonenumber](https://developers.weixin.qq.com/miniprogram/dev/server/API/user-info/phone-number/api_getphonenumber)
+
+---
+
+## 4. 数据模型
+
+### 4.1 `sys_user` 增列
+
+| 列名 | 类型 | 说明 |
+|------|------|------|
+| `wx_openid` | `VARCHAR(64) NULL` | 本小程序下 openid；未绑定为 NULL |
+| `wx_unionid` | `VARCHAR(64) NULL` | 有则写入；本期不做多端打通依赖 |
+
+约束：
+
+- 唯一索引建议：`uk_sys_user_wx_openid`（`wx_openid`）；MySQL 5.7 下多 NULL 可共存；应用层保证同一 openid 不绑两人。
+- 匹配手机号：`phone_no` trim / 去 `+86`/`86` 前缀规范化；要求 `status=1`、`del_flag=0`；发 token 前角色校验与密码登录一致。
+- 同一规范化手机号命中多条启用账号：明确错误，不自动选人。
+
+SQL 落在 `docs/sql/` 增量脚本，并同步 ORM `SysUser`。
+
+---
+
+## 5. 后端 API
+
+### 5.1 `POST /api/mini/auth/wechat-login`
+
+- 鉴权：无需 Bearer（登录入口）
+- 请求体：
+
+```json
+{
+  "loginCode": "<uni.login 返回的 code>",
+  "phoneCode": "<getPhoneNumber 返回的 code>"
+}
+```
+
+本期登录页场景 **始终传** `phoneCode`；后端无 `phoneCode` 时返回明确错误（不做 openid-only 静默登录）。
+
+- 成功 `data`（与密码登录对齐）：
+
+```json
+{
+  "token": "<access JWT>",
+  "refreshToken": "<refresh JWT>",
+  "expiresIn": <秒>,
+  "userInfo": { }
+}
+```
+
+### 5.2 业务分支
+
+| 情况 | 行为 |
+|------|------|
+| `openid` 已绑定用户 | 必须与本次授权手机号对应同一用户（`phones_match`）；不一致 → 失败 |
+| 未绑定 | 按规范化手机号查启用用户 |
+| 0 条 | 失败：未找到员工账号 |
+| >1 条 | 失败：手机号对应多个账号 |
+| 唯一命中 | 写入 `wx_openid`（及可选 `wx_unionid`）并 commit → 发 JWT |
+| openid 已被其他用户占用 | 冲突失败 |
+
+### 5.3 微信 HTTP API（自建后端，非云开发）
+
+1. `GET https://api.weixin.qq.com/sns/jscode2session`（`WECHAT_MP_APPID` + `WECHAT_MP_SECRET` + `loginCode`）
+2. `GET https://api.weixin.qq.com/cgi-bin/token` → `access_token`
+3. `POST https://api.weixin.qq.com/wxa/business/getuserphonenumber`（body: `{ "code": phoneCode }`）
+
+### 5.4 失败提示（前端 Toast / 接口 message）
+
+| 场景 | 提示方向 |
+|------|----------|
+| 用户拒绝授权 / 无 code | 需要授权手机号，或请使用账号密码登录 |
+| 未找到匹配员工 | 未找到对应员工账号（请确认手机号已在系统维护） |
+| 同一手机号多账号 | 手机号对应多个账号，请联系管理员 |
+| openid 已绑他人 / 与手机号不一致 | 微信与账号不匹配，请联系管理员 |
+| 账号停用 / 无角色 | 与密码登录相同的拒绝原因 |
+
+---
+
+## 6. 前端改动
+
+| 位置 | 改动 |
+|------|------|
+| `miniprogram/pages/login/login.vue` | 协议/隐私下方：「或」分隔 +「手机号快捷登录」；样式对齐 zkxw；协议门禁 |
+| 协议确认弹窗 | 快捷登录入口打开时，确认键带 `open-type="getPhoneNumber"`，同次点击完成同意+授权 |
+| `miniprogram/config/api.js` | 增加 wechat-login 路径常量 |
+| `miniprogram/stores/user.js`（或等价 auth 工具） | `wechatLogin({ loginCode, phoneCode })`；成功后复用现有存 token、menu-codes、进工作台 |
+
+密码登录按钮与表单逻辑保持不变。
+
+---
+
+## 7. 后端改动清单
+
+| 位置 | 改动 |
+|------|------|
+| `app/api/mini_auth.py`（新） | `wechat-login` 路由 |
+| `app/services/wechat_mini_auth.py`（新） | code2session、get_phone_number、手机号规范化 |
+| `app/services/wechat_login_service.py`（新） | 匹配 / 绑定 / 冲突校验 |
+| 现有发 JWT 能力 | 复用密码登录签发（如 `issue_tokens` / public 登录同路径逻辑） |
+| `app/models/models.py` | `SysUser.wx_openid` / `wx_unionid` |
+| `app/crud/user.py` | `get_by_wx_openid`、`list_active_by_phone_no` 等 |
+| `app/core/config.py` | `WECHAT_MP_*` + 加密排除 |
+| `app/api/__init__.py` + `app/main.py` | 注册路由 |
+| `docs/sql/` | 增量 DDL |
+
+实现时可对照移植 zkxw 对应文件，按山峡现有命名与 JWT 签发方式适配，不引入密码登录后的 `wechat-bind`。
+
+---
+
+## 8. 验收标准
+
+1. 账号密码登录仍可用，行为与现网一致。
+2. 已勾选协议时，点「手机号快捷登录」→ 授权 → 匹配成功 → 进入工作台。
+3. 未勾选协议时，确认「同意并登录」可同次拉起手机号授权并完成登录。
+4. `phone_no` 为空 / 不匹配 / 多账号 → 失败且不创建用户。
+5. 首次成功写入 `wx_openid`；再次快捷登录同号同微信可进。
+6. openid 与手机号对应关系冲突时拒绝登录。
+7. 真机验证通过（开发者工具仅作联调参考）。
+
+---
+
+## 9. 风险与依赖
+
+- **Secret 未配置**：接口应返回可理解错误，避免空串调微信。
+- **AppID 不一致**：`manifest` / `WECHAT_MP_APPID` / 微信后台必须同一正式号。
+- **手机号未维护**：管理员需保证员工 `sys_user.phone_no` 正确且唯一。
+- **计费**：手机号快速验证可能按次收费，需在公众平台关注额度。