mirror of
https://github.com/fastapiadmin/FastapiAdmin.git
synced 2026-10-07 02:01:37 +00:00
zhangtao
ffbe2453f2
- 清理冗余代码与配置： - 删除废弃的 mock 适配器、通用 mock 模块与示例API - 移除冗余的 ts 类型文件与 patch 目录 - 简化 tsconfig 组件路径配置 - 新增功能与优化： - 新增全局水印组件与水印配置 - 接入微信小程序登录/手机号登录 - 新增系统参数配置 store 与国际化支持 - 新增 markdown 渲染插件与样式配置 - 优化 pinia 持久化逻辑修复 - 新增微信小程序 access_token 缓存配置 - 修复登录趋势数据结构定义 - 优化全局请求防抖重定向逻辑 - 页面与路由优化： - 补全引导页首次启动逻辑 - 统一页面底部安全区适配 - 更新页面路由类型声明 - 代码质量优化： - 移除无用 console.log 调试代码 - 修复全局弹窗重复重登录问题 - 优化 mp-html 组件配置
74 lines
4.1 KiB
Markdown
74 lines
4.1 KiB
Markdown
# 微信小程序后端接口实现 — 交付说明
|
||
|
||
**日期**: 2026-08-05
|
||
**范围**: 打通小程序完整登录闭环（微信一键登录 / 手机号登录 / 小程序码生成）
|
||
|
||
---
|
||
|
||
## 一、新增后端接口（3个）
|
||
|
||
| 接口 | 方法 | 功�� | 依赖 |
|
||
|------|------|------|------|
|
||
| `/system/auth/wx-login` | POST | uni.login code → code2Session → openid → 查建用户 → JWT | WX_MINI_APP_ID/SECRET |
|
||
| `/system/auth/wx-phone-login` | POST | getPhoneNumber code → getuserphonenumber → 手机号 → 查建用户 → JWT | 同上 |
|
||
| `/system/auth/wx-qrcode/generate` | POST | scene/page/width → getwxacodeunlimit → base64 PNG | 同上 |
|
||
|
||
## 二、文件变更清单
|
||
|
||
### 后端（5个）
|
||
| 文件 | 变更 |
|
||
|------|------|
|
||
| `backend/app/config/setting.py` | +`WX_MINI_APP_ID` / `WX_MINI_APP_SECRET` / `WX_MINI_ACCESS_TOKEN_CACHE_TTL=7000` |
|
||
| `backend/app/common/enums.py` | +`WX_MINI_ACCESS_TOKEN` Redis key |
|
||
| `backend/app/api/v1/module_system/auth/schema.py` | +`WxLoginSchema` / `WxPhoneLoginSchema` / `WxQrCodeSchema` / `WxQrCodeOutSchema` |
|
||
| `backend/app/api/v1/module_system/auth/wx_mini_service.py` | **新增**，核心服务层 |
|
||
| `backend/app/api/v1/module_system/auth/controller.py` | +3 个端点及所需 import |
|
||
|
||
### 前端（5个）
|
||
| 文件 | 变更 |
|
||
|------|------|
|
||
| `frontend/app/src/api/module_system/auth.ts` | `wxPhoneLogin` 改为仅传 code；+`generateWxQrCode` 及类型 |
|
||
| `frontend/app/src/composables/useWxLogin.ts` | `wxPhoneLogin` 接收 `e.detail.code` |
|
||
| `frontend/app/src/pages/login/index.vue` | 手机号登录传 code；移除废弃 `getUserProfile` |
|
||
| `frontend/app/src/store/userStore.ts` | `wxPhoneLogin` 类型改为 `{ code: string }` |
|
||
| `frontend/app/src/composables/useSharePoster.ts` | 改用 `AuthAPI.generateWxQrCode`（修复错误路径） |
|
||
|
||
### 顺带修复（2个既有 TS 错误）
|
||
| 文件 | 修复 |
|
||
|------|------|
|
||
| `frontend/app/src/composables/useShare.ts` | 移除不存在的 `ShareAppMessageOptions` / `ShareTimelineOptions` 类型导入 |
|
||
| `frontend/app/src/composables/useSubscribeMessage.ts` | `requestSubscribeMessage` 返回值先转 `unknown` 再断言 |
|
||
|
||
## 三、关键技术决策
|
||
|
||
1. **手机号登录用 2023+ 新方案**：前端 `getPhoneNumber` 回调的 `e.detail.code` 直传后端，后端调 `wxa/business/getuserphonenumber` 换手机号。**无需 AES 解密**，避免引入 pycryptodome 依赖（旧方案 encryptedData+iv 已废弃）。
|
||
2. **access_token 用 stable_token 接口**：`POST cgi-bin/stable_token`，比传统 `cgi-bin/token` 更稳定（并发不互相覆盖）；Redis 缓存 7000s（微信上限 7200 留 200s 余量），多实例共享。
|
||
3. **小程序码返回 base64 data URI**：`data:image/png;base64,...`，前端可直接作为 `<image>` src 或 Canvas 图片来源，无需中转存储。
|
||
4. **用户名规则**：微信登录自动注册 `wxmini_{openid前20位}`；手机号登录 `wxphone_{尾号4位}_{随机8hex}`，风格与 OAuth 模块 `oauth_{provider}_{id}` 一致。
|
||
5. **登录类型标记**：`login_type` 分别记录 `wx_mini` / `wx_mini_phone`，便于会话审计。
|
||
|
||
## 四、验证结果
|
||
|
||
- ✅ 后端全模块导入无错误，3 个新路由断言通过
|
||
- ✅ Schema 字段校验通过（默认值、边界）
|
||
- ✅ 前端 `vue-tsc --noEmit` 通过（0 错误）
|
||
|
||
## 五、上线前置条件（待用户配置）
|
||
|
||
| 事项 | 说明 |
|
||
|------|------|
|
||
| 申请小程序 AppID/AppSecret | 微信公众平台 → 开发管理，填入环境变量 `WX_MINI_APP_ID` / `WX_MINI_APP_SECRET` |
|
||
| 配置订阅消息模板 | 公众平台 → 订阅消息，将模板 ID 填入 `useSubscribeMessage.ts` 的 `TEMPLATE_IDS` |
|
||
| 域名白名单 | 微信公众平台配置 request 合法域名指向后端 API 地址 |
|
||
| 小程序码配额 | 有数量限制（getwxacodeunlimit 每日上限），生产需注意缓存 |
|
||
|
||
## 六、测试建议
|
||
|
||
配置好密钥后，可用以下命令快速自测（需 Redis 与数据库就绪）：
|
||
```bash
|
||
# 微信登录（code 需真实小程序 code，可用微信开发者工具获取）
|
||
curl -X POST http://localhost:8000/api/v1/system/auth/wx-login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"code": "REAL_CODE"}'
|
||
```
|