0 Fork 0

Files

T

maxf 28fcfc6aec ## 1️⃣ 文档与代码一致性 ✅（修复 4 处滞后）

**发现并已修复的文档滞后**（后期代码先于文档，审计时补齐）：

| 滞后点 | 修复 |
|---|---|
| `24.附录` users 表缺 `wechat_openid` 列（二期微信登录加的） | ✅ 已补 |
| `24.附录` 缺 `refuel_records` 表（三期记账） | ✅ 已补 |
| `24.附录` 错误码缺 `1012/1013`（三期） | ✅ 已补 |
| `34.附录` 小程序页面目录缺 `calc/refuels`（三期） | ✅ 已补 |

**核对一致项**：
- API 路由 **A1-A23 + `/api/auth/wechat`** 全部注册，与 22/33/43 文档逐项对应
- `schema.sql` 11 表 = 24 附录（10 + refuel）+ 45 附录
- 小程序 8 页文件齐全（js/wxml/wxss/json × 8），`refuels.wxml` 数据绑定与 js 匹配
- H5 8 页面全部可访问

## 2️⃣ 后期变更对前期的影响 ✅ 无破坏

综合回归 **20 项全 PASS**：
- **一期**：账号密码登录 / Cookie 会话 / dashboard / provinces(31省) / history ✅
- **二期**：Bearer token 认证（与 Cookie **双通道共存**，互不冲突）✅
- **三期**：refuel 首条保存 / 区间油耗 8.25 / 统计 / 预填 ✅
- **前端**：9 个资源（8 页 + 静态 JS）全部 200 ✅

关键：二期的 `users` 加列是**幂等增量迁移**（ALTER），未动一期任何表结构；一期 API 与前端全部正常。

## 3️⃣ 整体可行性 ✅ 在可控范围

| 维度 | 状态 |
|---|---|
| 构建/静态检查 | `go build / vet` 全绿 |
| 单元测试 | 6 包 17 单测全过（auth/crawler/cron/db/push/service） |
| 规模 | 11 表 · 23+ 接口 · 8 H5 页面 · 8 小程序页面 · 17 份文档 · ~90 代码文件 |
| 三阶段功能 | 监控预测提醒 → 微信小程序 → 加油记账/真实油耗，全部落地 |

**非阻塞小项**（可后续优化，不影响运行）：
1. `refuels.wxml` 第 11 行 `wx:for` 与 `wx:if` 同节点——功能正常，写法可规范
2. api 包 handler 层无独立单测——由端到端回归覆盖（service 层已有单测）

---

**结论：项目整体健康、文档与代码对齐、三阶段功能完整可用。** 4 处文档滞后已修复，无功能性问题。可以进入部署/上线阶段。

2026-09-25 16:56:07 +08:00

4.0 KiB

Raw Permalink Blame History

📱 二期 · 微信小程序 — 与后端接口对接

上游：docs/30.小程序概要设计.md、docs/22.API详细设计.md（A1-A17） 核心差异：小程序无 Cookie，认证走 Bearer token；仅新增 1 个后端接口 /api/auth/wechat

一、认证机制

1.1 token 生命周期

登录（wx.login）→ POST /api/auth/wechat → 得 { token, user }
  ├─ 存 token 到 wx.setStorageSync('token')
  ├─ 后续请求头：Authorization: Bearer <token>
  └─ 401 + code=1008（token 过期/无效）→ 清 token → 跳 P03 登录页

1.2 后端双通道（一期已实现）

auth 中间件解析登录态顺序：

HTTP-Only Cookie（H5 浏览器）
Authorization: Bearer <token>（小程序）

两者共用 sessions 表同一套 token，后端无需区分客户端。

1.3 登出

小程序 app.setLogout() 仅清本地 token（不调服务端注销）；如需要可调 POST /api/auth/logout（带 token）。

二、新增后端接口（一期已实现）

POST /api/auth/wechat（🔓匿名）

功能：微信一键登录。wx.login 的 code 换取 openid，自动注册/登录。

请求参数

参数	位置	类型	必填	说明
code	body	string	是	`wx.login` 返回的临时 code（5 分钟有效）

响应（HTTP 200）

{
  "code": 0, "message": "ok",
  "data": { "user": { "id": 1, "username": "wx_xxx", "is_admin": true }, "token": "..." }
}

处理逻辑

读 server_settings.wechat_appid / wechat_secret；未配置 → 400+1005。
调微信 jscode2session?appid&secret&js_code&grant_type=authorization_code → openid。
auth.GetUserByOpenid 查用户；无 → auth.CreateWechatUser（username=wx_+openid，首用户 admin）。
建会话（sessions 表）→ 返回 { user, token }（同时 Set-Cookie 兼容 H5）。

失败：微信接口 errcode≠0 或 openid 空 → 401+1011。

三、复用 API 清单

接口	方法	用途	认证
`/api/dashboard`	GET	首页看板（含原油折线/爱车段）	🔓
`/api/provinces`	GET	省份选择网格	🔓
`/api/history`	GET	历史调价 + 阶梯	🔓
`/api/location/regeo`	GET	定位逆编码	🔓
`/api/auth/me`	GET	启动探登录态	🔓
`/api/auth/wechat`	POST	微信一键登录	🔓
`/api/auth/logout`	POST	登出	🔒
`/api/vehicles`	GET/POST	车辆列表/新增	🔒
`/api/vehicles/:id`	PUT/DELETE	车辆编辑/删除	🔒
`/api/vehicles/impact`	GET	调价成本影响	🔒
`/api/settings/user`	GET/POST	个人偏好	🔒
`/api/settings/server`	GET/POST	全局配置（admin）	👑
`/api/settings/test`	POST	渠道测试	🔒

详情字段与响应结构见 docs/22.API详细设计.md；三期记账新增接口见 docs/43.记账API详细设计.md。

四、差异处理（小程序 vs H5）

维度	H5	小程序	处理
认证载体	Cookie	Bearer token	`utils/api.js` 统一注入
最近省份	localStorage	wx storage	`utils/auth.js` 封装，LRU 一致
图表	ECharts	canvas 2d	`utils/chart.js` 手绘折线
定位	navigator.geolocation	wx.getLocation	需 `app.json` 权限声明
登录	账号密码	wx.login 一键	`/api/auth/wechat`
请求	fetch	wx.request	`utils/api.js` Promise 封装
401 处理	跳 /login	navigateTo 登录页	统一拦截

五、环境配置

配置	位置	说明
后端地址	`app.js` → `globalData.baseUrl`	开发 `http://localhost:8080`；生产 HTTPS 域名
AppID	`project.config.json` → `appid`	真机/体验需真实 AppID；开发可用 `touristappid`
合法域名	微信后台	生产需配置 request 合法域名（HTTPS）
定位权限	`app.json`	`requiredPrivateInfos` + `permission`

4.0 KiB Raw Permalink Blame History Unescape Escape