From b3dc9665761806bc78a501f60b6c490bf11b152e Mon Sep 17 00:00:00 2001 From: Milky0217 Date: Fri, 24 Apr 2026 14:52:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E7=99=BB=E5=BD=95?= =?UTF-8?q?=E7=A0=81=E5=92=8C=E6=94=AF=E4=BB=98=E5=AE=9D=E6=8E=A5=E5=85=A5?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- IMPROVEMENTS.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 1 deletion(-) diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md index 5061743..b160f57 100644 --- a/IMPROVEMENTS.md +++ b/IMPROVEMENTS.md @@ -1647,5 +1647,135 @@ fi --- -**最后更新**：2026-04-17 +## 十五、网页端登录码流程（2026-04-24） + +### 功能概述 + +实现**无需微信登录**的网页端登录确认流程。用户在小程序生成登录码，在后端网页完成微信授权登录，再由小程序确认完成整个登录流程。 + +### 业务流程 + +``` +小程序 → 后端 GET /payment/generate-code（生成登录码） + ↓ + 用户在外部浏览器打开支付页 + ↓ + 后端 GET /payment/login-status?code=xxx（网页轮询） + ↓ + 网页端微信扫码授权（openid 写入 DB） + ↓ + 网页端 POST /api/web-login/confirm（确认登录，token 写入 DB） + ↓ + 小程序轮询 GET /payment/login-status?code=xxx + ↓ + confirmed=true, token=xxx → 小程序保存 token 登录完成 +``` + +### 新增接口 + +| 接口 | 方法 | 认证 | 说明 | +|------|------|------|------| +| `GET /payment/generate-code` | GET | 无 | 网页端生成登录码 | +| `GET /payment/login-status` | GET | 无 | 查询登录码状态（网页轮询）| +| `POST /api/web-login/confirm` | POST | JWT | 小程序确认登录 | + +### 数据库 + +`web_login_codes` 表（迁移 `005_add_web_login_codes.sql`）： + +```sql +CREATE TABLE web_login_codes ( + id SERIAL PRIMARY KEY, + code VARCHAR(32) UNIQUE NOT NULL, -- 登录码（如 ASD-XXXXXX） + openid VARCHAR(128), -- 微信 openid（授权后填充） + token TEXT, -- JWT（确认后填充） + expires_at TIMESTAMPTZ NOT NULL, -- 过期时间（10分钟） + user_id INTEGER, -- 关联用户 ID + created_at TIMESTAMPTZ DEFAULT NOW() +); +CREATE INDEX idx_web_login_codes_code ON web_login_codes(code); +CREATE INDEX idx_web_login_codes_expires ON web_login_codes(expires_at); +``` + +状态演变： +1. **初始**：`code` 有值，`openid`=NULL, `token`=NULL +2. **微信授权后**：`openid` 被填充 +3. **确认后**：`token` 被填充，`code` 被删除 + +### 关键 commits + +| Commit | 说明 | +|--------|------| +| `034aa66` | 实现网页端登录码流程（无需微信登录） | +| `c66d130` | 统一登录码参数名为 code（与前端保持一致）| +| `92fb4e3` | web_login_confirm 查询改为精确匹配 code | +| `3bcfd9a` | web_login_confirm 加日志排查 + 精确匹配 code | + +### 已知问题 + +- [ ] `web_login_confirm` (POST /api/web-login/confirm) JSON 反序列化偶发失败，日志已添加诊断（commit `3bcfd9a`） + +--- + +## 十六、支付宝网页支付接入（2026-04-23） + +### 功能概述 + +接入支付宝沙箱环境，用户在外部浏览器完成支付，支付成功回调更新用户会员状态。 + +### 支付流程 + +``` +小程序 → 后端 /payment/page → 支付宝网页支付 → 回调 /payment/notify → 更新用户状态 +``` + +### 关键 commits + +| Commit | 说明 | +|--------|------| +| `8c9552f` | 新增支付页面接口，为接入支付宝做准备 | +| `e828631` | 接入支付宝沙箱环境 (alipay.trade.page.pay) | +| `375f0af` | 更新支付系统和支付宝集成文档 | +| `502ae8b` | payment_page 支持 URL 参数传递 JWT | +| `af4ae27` | 跳转外部支付页不再携带 JWT，由网页端微信扫码登录 | + +### 沙箱测试 + +- 沙箱网关：`https://openapi-sandbox.dl.alipaydev.com/gateway.do` +- 测试账号：https://open.alipay.com/develop/sandbox/app + +--- + +## 十七、常见 Bug 与修复（2026-04） + +### 1. gitignore 阻止 source 文件追踪 + +**问题**：`.gitignore` 配置 `*` 阻止了所有文件，包括源码文件。 + +**现象**：`git add` 后 `git commit` 无响应，`git status` 显示文件但 `git diff --cached` 为空。 + +**修复**：使用 `git add -f ` 强制添加被忽略的文件。 + +### 2. `unwrap_or(None)` 误用导致 SQL 错误被吞掉 + +**问题**：`fetch_optional` 返回 `Result, E>`，`unwrap_or(None)` 只处理 `Err`，不处理 `Ok(None)`。 + +```rust +// 错误：sqlx::Error 被 ok() 吞掉，但 record 仍是 Option +// 导致 record = None，永远走不到查询逻辑 +let record = sqlx::query_as(...).fetch_optional(pool).await.ok(); + +// 正确：用 .ok().flatten() 处理 Result> +let record = sqlx::query_as(...).fetch_optional(pool).await.ok().flatten(); +``` + +### 3. `serde(skip_deserializing)` 导致 SELECT 结果无法填充字段 + +**问题**：`#[serde(skip_deserializing)]` 在 POST 请求体解析时跳过字段，但也阻止了数据库 SELECT 结果填充字段。 + +**修复**：对需要同时支持上传和查询的字段，使用 `#[serde(default)]`。 + +--- + +**最后更新**：2026-04-24 **维护者**：milky