179 lines
7.1 KiB
Markdown
179 lines
7.1 KiB
Markdown
# 孕育无忧 H5 应用修改记录
|
||
|
||
> 项目: app_03 (孕育无忧 — H5 小程序嵌入式)
|
||
> 时间跨度: 2026-05-21 ~ 2026-05-27
|
||
> 技术栈: FastAPI + MongoDB + React 18 + Vite 6
|
||
|
||
---
|
||
|
||
## 一、认证流程演进（4 次重构）
|
||
|
||
### Phase 1: JWT 直传（80904e6 ~ 1eef3ae）
|
||
|
||
**方案：** 小程序 `?token=JWT` → H5 decodeToken → 后端 verify_signature=False 按 openid 查/创建用户
|
||
|
||
**关键改动：**
|
||
- 后端 `get_current_user` 取消签名验证
|
||
- JWT payload 字段调整为 `{uid, openid, phone}`
|
||
- 前端 `decodeToken()` 解析 token
|
||
- 无需小程序手动传递 uid，仅 token 即可
|
||
|
||
**问题：** 小程序端 web-view URL 中 `openid=` 为空值 → 走 dev-login 分支 → 数据库记录 name='开发测试用户'
|
||
|
||
### Phase 2: 参数直传（1eef3ae）
|
||
|
||
**方案：** `?uid=&openid=&phone=` → 前端 `createDummyToken()` 构建本地 JWT → 直接登录
|
||
|
||
**关键改动：**
|
||
- 新增 `createDummyToken()` 函数，前端构造 base64 编码的 JWT
|
||
- JWT base64url 解码需 `replace(/-/g,'+').replace(/_/g,'/')`
|
||
- 新增 `/auth/params-login` 后端接口（可选，暂不需要）
|
||
- 移除 paramsLogin API 调用，纯前端完成
|
||
|
||
**问题：** URL 传 3 个参数太繁琐，小程序端需要额外处理手机号敏感信息
|
||
|
||
### Phase 3: 统一调试（150dafc ~ bceb4f4）
|
||
|
||
**新增功能：**
|
||
- `services/debug.ts` — 统一调试模块：`isDebug()`, `debugLog()`, `getDebugLogs()`
|
||
- 通过 `.env` 中 `VITE_DEBUG=true` 控制，开发默认开启，生产关闭
|
||
- LoginPage 自动记录登录流程；ProfilePage 按条件显示调试面板
|
||
- 头像支持：后端 `UserProfileUpdate` 新增 `avatar_url` 字段
|
||
- ProfilePage 头像卡片显示真实头像（有 avatar_url 时）
|
||
- ProfilePage 增加用户姓名编辑字段
|
||
|
||
### Phase 4: CRMEB 代理（bceb4f4 ~ 96a938e，当前版本）
|
||
|
||
**方案：** `?openid=xxx`（单参数）→ 后端 `openid-login` → 调 CRMEB 内部接口获取信息 → 自动补齐
|
||
|
||
**关键改动（96a938e）：**
|
||
|
||
后端：
|
||
- 新增 `POST /auth/openid-login` — 接收 openid，调 CRMEB 获取 nickname/phone/avatar
|
||
- `config.py` 新增 `crmeb_base_url`、`crmeb_api_key`
|
||
- 查找/创建用户时自动同步：name、phone、avatar_url
|
||
|
||
前端：
|
||
- LoginPage 简化：检测 openid → 调 openid-login → 跳转
|
||
- UserContext 修复 avatar_url 未映射导致头像不显示
|
||
|
||
CRMEB 端（外部）：
|
||
- 新增 `InternalController`，`GET /api/internal/user-info?openid=xxx`
|
||
- `X-Internal-Key` Header 认证，硬编码密钥（后续改为 config 读取）
|
||
|
||
---
|
||
|
||
## 二、完整 Commit 清单
|
||
|
||
| SHA | 时间 | 类型 | 摘要 |
|
||
|-----|------|------|------|
|
||
| `96a938e` | 05/27 22:24 | feat | **openid-login + avatar_url 修复** — CRMEB 代理登录方案最终版 |
|
||
| `bceb4f4` | 05/27 20:24 | feat | 支持从小程序获取微信头像和昵称同步到 H5 |
|
||
| `150dafc` | 05/27 20:19 | feat | 统一调试模块 debug.ts，VITE_DEBUG 环境变量控制 |
|
||
| `27b5856` | 05/27 18:52 | cleanup | 移除所有调试代码，登录页精简 |
|
||
| `1eef3ae` | 05/27 18:48 | refactor | 小程序参数直传 uid/openid/phone，前端构建本地 token |
|
||
| `8c50afc` | 05/27 03:44 | feat | 小程序 web-view Token 传递问题分析与修复方案 |
|
||
| `6dc6258` | 05/27 03:07 | feat | H5 登录调试面板，URL 信息显示 |
|
||
| `5a0f1f4` | 05/27 02:27 | feat | API 前缀配置调整，Vite 代理更新 |
|
||
| `fe116b9` | 05/27 02:19 | feat | 调试面板 |
|
||
| `80904e6` | 05/27 01:49 | feat | 按 openid 查找/创建用户，调整 JWT 负载字段 |
|
||
| `3506731` | 05/23 02:15 | fix | 修复 DEV_MODE 解析 |
|
||
| `08df182` | 05/23 01:59 | refactor | 简化 H5 应用用户授权 |
|
||
| `53128a6` | 05/22 00:51 | feat | 添加 serv.sh 服务管理脚本 |
|
||
| `ded7ea1` | 05/21 20:56 | feat | 新增可配置路径前缀支持子路径部署 |
|
||
| `fd1aea1` | 05/21 17:10 | build | 配置部署子路径 /app_03/ |
|
||
| `409daba` | 05/21 00:46 | feat | 初始化项目基础代码结构 |
|
||
|
||
---
|
||
|
||
## 三、新增/修改文件清单
|
||
|
||
### 新增文件
|
||
|
||
| 文件 | 目的 |
|
||
|------|------|
|
||
| `frontend/src/app/services/debug.ts` | 统一调试模块：日志记录/读取/清除 |
|
||
| `backend/serv.sh` | 服务管理脚本（start/stop/restart/logs） |
|
||
| `docs/crmeb-internal-api-plan.md` | CRMEB 内部接口方案文档 |
|
||
| `.env.example` | 环境变量模板 |
|
||
|
||
### 关键修改文件
|
||
|
||
| 文件 | 变化 |
|
||
|------|------|
|
||
| `frontend/src/app/pages/LoginPage.tsx` | 3 次重写：token 解码 → 参数直传 → openid-login |
|
||
| `frontend/src/app/pages/ProfilePage.tsx` | 添加头像显示、姓名编辑、调试面板 |
|
||
| `frontend/src/app/services/api.ts` | 添加 fetchApi export、createDummyToken |
|
||
| `frontend/src/app/context/UserContext.tsx` | 修复 avatar_url 映射 |
|
||
| `frontend/.env` | 添加 VITE_API_PREFIX、VITE_DEBUG、VITE_UPLOADS_PREFIX |
|
||
| `backend/app/config.py` | 添加 crmeb_base_url、crmeb_api_key |
|
||
| `backend/app/routers/auth.py` | 添加 openid-login 接口、dev-login 调整 |
|
||
| `backend/app/schemas/user.py` | UserProfileUpdate 添加 avatar_url |
|
||
| `backend/app/middleware/auth.py` | verify_signature=False |
|
||
| `backend/app/models/user.py` | 添加 avatar_url 字段 |
|
||
|
||
---
|
||
|
||
## 四、部署与运维记录
|
||
|
||
### 服务器信息
|
||
|
||
| 项目 | 地址 |
|
||
|------|------|
|
||
| app_03 服务 | 8.145.39.61:8030（uvicorn） |
|
||
| CRMEB 服务 | 8.130.191.152:20199（Swoole） |
|
||
| H5 入口 | https://mp.yizhezhe.com/app_03/ |
|
||
| Git 远程 | gitea@git@git@gitea.nexjs.com:jone/app_03_pregnancy.git |
|
||
|
||
### 部署关键点
|
||
|
||
1. **Nginx 尾随斜杠问题**：`location = /app_03 { return 301 /app_03/; }` 必须带，否则丢 query 参数
|
||
2. **API 代理**：前后端统一使用 `/app_03/api/*` 路径，Nginx rewrite 剥离前缀
|
||
3. **后端重启命令**：
|
||
```bash
|
||
fuser -k 8030/tcp && sleep 2 && \
|
||
nohup env DEV_MODE=1 .venv/bin/uvicorn app.main:app \
|
||
--host 127.0.0.1 --port 8030 --workers 1 > app.log 2>&1 &
|
||
```
|
||
4. **前端构建**：
|
||
```bash
|
||
cd frontend && npm run build
|
||
scp -r dist/* root@8.145.39.61:/opt/app/app_03_pregnancy/frontend/dist/
|
||
```
|
||
|
||
### 服务器 Git 管理
|
||
|
||
- 服务器仓库 reset 到 1eef3ae（合并前状态），remote 指向 gitea
|
||
- 回滚后 HEAD 在 96a938e，状态 clean
|
||
- 本地实现新功能后再 push 到 gitea，服务器 pull 部署
|
||
|
||
---
|
||
|
||
## 五、测试账号
|
||
|
||
| 角色 | openid | 手机号 | 昵称 |
|
||
|------|--------|--------|------|
|
||
| 真实用户 | `oauWC1zc7hVn3j60QwkuHyjGn03Y` | 13693687880 | 枫逸 |
|
||
| 开发测试 | `dev_test_account_001` | 13800000000 | 开发测试用户 |
|
||
|
||
---
|
||
|
||
## 六、废弃方案记录
|
||
|
||
| 方案 | 原因 | commit |
|
||
|------|------|--------|
|
||
| JWT 签名验证 | 小程序 token 无法共享签名密钥，改为不验签 | — |
|
||
| jwt-yun `exchange-code` | 外部服务不可用 | — |
|
||
| URL 传 3 参数 (`?uid=&openid=&phone=`) | 参数繁琐，敏感信息暴露 | 1eef3ae |
|
||
| paramsLogin 后端接口 | 纯前端可完成，不需要额外 API | 1eef3ae |
|
||
| 前端 createDummyToken() | 替代为后端 openid-login 返回 token | bceb4f4 |
|
||
|
||
---
|
||
|
||
## 七、待办项
|
||
|
||
- [ ] CRMEB InternalController 密钥从 config 读取（当前硬编码）
|
||
- [ ] 小程序端 web-view URL 改为 `?openid=` 单参格式
|
||
- [ ] 前后端代码 commit + push 到 gitea
|
||
- [ ] 服务器 deploy 最新代码
|