maxf
28fcfc6aec
**发现并已修复的文档滞后**（后期代码先于文档，审计时补齐）： | 滞后点 | 修复 | |---|---| | `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 处文档滞后已修复，无功能性问题。可以进入部署/上线阶段。
6.4 KiB
6.4 KiB
📱 二期 · 微信小程序 — 概要设计
上游：
docs/10.概要设计.md（v1.2，API-First 已为小程序铺路）
定位：原生微信小程序端，复用一期 Go 后端全部 API 版本：v1.0 · 2026-09-24
目录
一、小程序定位与形态
| 项 | 说明 |
|---|---|
| 形态 | 原生微信小程序（wxml/wxss/js/json，不引入第三方框架） |
| 后端 | 复用一期 Go 后端（internal/api 全部接口），零后端改动原则下仅增微信认证适配 |
| 与 H5 关系 | 页面与功能对齐 H5（首页/省份/登录/爱车/设置/历史），体验原生 |
| 数据 | 与服务端共用一套账号体系与业务数据（加油记录三期接入） |
一期后端已做的适配（为小程序铺路）：
auth中间件支持Authorization: Bearer <token>（小程序无 Cookie）- 新增
POST /api/auth/wechat（微信一键登录） users表增加wechat_openid（幂等迁移）server_settings增加wechat_appid / wechat_secret
二、登录方案（微信一键登录）
2.1 流程
小程序打开 → 未登录 → 进入"登录页"
├─ 用户点击"微信一键登录"
├─ wx.login() → 获取临时 code
├─ POST /api/auth/wechat { code }
│ ├─ 后端读 server_settings.wechat_appid/wechat_secret
│ ├─ 调微信 jscode2session 换 openid
│ ├─ 按 wechat_openid 查用户：无则自动创建（首微信用户 = admin）
│ └─ 建会话，返回 { token, user }
├─ 前端存 token 到 storage
└─ 回跳登录前页面
2.2 关键点
| 点 | 说明 |
|---|---|
| 无密码 | openid 即身份，用户零注册门槛 |
| 会话 | 返回的 token 存 wx.setStorageSync('token')，后续请求带 Authorization: Bearer <token> |
| 首用户 | 部署者用小程序的第一个微信用户自动成为 admin（可配全局设置） |
| 需配置 | admin 需在"设置"配置小程序 AppID / AppSecret（H5 或小程序设置页均可） |
三、定位方案
wx.getLocation（需授权）
└─ 得 (latitude, longitude)
└─ GET /api/location/regeo?lat=&lng=（复用后端高德逆编码代理）
├─ 成功 → 得省份 → 更新看板
└─ 失败（未授权/高德 Key 未配）→ 静默保持当前省
- 授权失败/拒绝 → 静默降级（保持 localStorage 最近省或默认省），不弹错误
- 用户可关闭"自动定位"（设置页开关，storage）
四、页面地图（6 页）
| 页面 | 路径 | 功能 | 登录 |
|---|---|---|---|
| 首页 | pages/index/index |
看板：倒计时/预测/当前价/国际油价折线/爱车入口 | 🔓 |
| 省份选择 | pages/province/province |
最近 5 省 + 31 省网格 | 🔓 |
| 登录 | pages/login/login |
微信一键登录 | 🔓 |
| 爱车管理 | pages/vehicles/vehicles |
车辆 CRUD + 调价影响 + 加油记录入口（三期） | 🔒 |
| 设置 | pages/settings/settings |
个人偏好 + admin 全局（含微信 AppID/Secret）+ 自动定位开关 | 个人🔒 / 全局👑 |
| 历史 | pages/history/history |
年度调价 + 92# 阶梯折线 | 🔓 |
页面交互与 H5 一致：首页左上角省份入口、历史省份 LRU（仅手动切换记录）、登录门槛 401 自动跳登录页。
五、与后端对接
| 维度 | 说明 |
|---|---|
| 认证 | 请求头 Authorization: Bearer <token>；401+code=1008 时跳登录页（utils/api.js 统一处理） |
| 复用 API | A1 dashboard / A2 provinces / A3 history / A4-A8 vehicles / A9-A11 settings / A12 health / A13 regeo / A14-A17 auth / A19 wechat |
| 差异处理 | 无 Cookie（用 Bearer）；图表用轻量 canvas（不引 echarts 库）；最近省用 storage（非 localStorage） |
| 新增 API | 仅 POST /api/auth/wechat（后端一期已实现） |
六、前端技术选型
| 项 | 选型 | 理由 |
|---|---|---|
| 框架 | 原生小程序 | 零依赖、体积小、无需编译链 |
| 样式 | 原生 wxss | 卡片式，与 H5 视觉对齐 |
| 图表 | utils/chart.js（canvas 2d 手绘折线） |
避免引入 echarts-for-weixin 大依赖 |
| 状态 | storage（token/user/recent_provinces/auto_location） | 简单可持久 |
| 请求 | utils/api.js（Promise 封装） |
统一 token 注入与 401 跳转 |
七、部署与上线
| 阶段 | 动作 |
|---|---|
| 开发 | 微信开发者工具导入 miniprogram/ 目录；勾选"不校验合法域名"；app.js 的 baseUrl 指向本机 http://localhost:8080 |
| 联调 | 后端启动 go run ./cmd/server；后端配置 wechat_appid/wechat_secret |
| 生产 | baseUrl 改为服务器 HTTPS 域名；微信后台配置 request 合法域名 |
| 审核 | 类目选择（工具/生活服务等）、隐私协议（定位说明）、体验版内测 |
| 发布 | 提交审核 → 发布 |
八、文件结构与配置
miniprogram/
├─ app.js / app.json / app.wxss 全局（baseUrl/页面注册/样式）
├─ project.config.json 开发者工具（appid、urlCheck=false）
├─ sitemap.json
├─ utils/
│ ├─ api.js wx.request 封装（Bearer + 401 跳登录）
│ ├─ auth.js 最近省 LRU / 登录态 / 格式化
│ └─ chart.js 轻量 canvas 折线图
└─ pages/
├─ index/ ├─ province/ ├─ login/
├─ vehicles/ ├─ settings/ └─ history/
关键配置：
app.json：注册 6 页；requiredPrivateInfos: ["getLocation"]；permission.scope.userLocation.desc（定位授权文案）app.js：globalData.baseUrl（后端地址，开发/生产切换点）project.config.json：appid（填实际 AppID，体验版需真 AppID 非 tourist）
后续（三期）
记账功能（加油记录 / 真实油耗 / ECharts 折线图）设计见 40 系列文档；小程序端将新增 pages/refuels 页与三期 API 对接。