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 处文档滞后已修复，无功能性问题。可以进入部署/上线阶段。
4.7 KiB
4.7 KiB
📱 二期 · 微信小程序 — 功能大纲（页面生命周期）
上游：
docs/30.小程序概要设计.md
编号体系：P01-P06（小程序页面），与一期 H5 功能大纲（001-014）互补
编号体系
| 编号 | 页面 | 功能 | 登录 |
|---|---|---|---|
| P01 | 首页 | 看板（倒计时/预测/当前价/国际油价折线/爱车入口） | 🔓 |
| P02 | 省份选择 | 最近 5 省 + 31 省网格 | 🔓 |
| P03 | 登录 | 微信一键登录 | 🔓 |
| P04 | 爱车管理 | 车辆 CRUD + 调价影响 | 🔒 |
| P05 | 设置 | 个人偏好 + admin 全局（含微信配置）+ 自动定位开关 | 🔒/👑 |
| P06 | 历史 | 年度调价 + 92# 阶梯折线 | 🔓 |
通用约定：
wx.request经utils/api.js统一注入Authorization: Bearer <token>；401+1008 自动跳 P03 登录页。
P01 首页（定位 + 看板）
触发：进入小程序首页
生命周期：
P01.1 首页 onLoad
├─ 读取 storage 最近省 → province（无则"北京"）
├─ 读 app.globalData.isLogin → 爱车卡片双态
├─ GET /api/dashboard?province=X → 渲染：
│ 倒计时/预测/当前价/国际油价折线(canvas)/最近调价
└─ wx.getLocation 定位模块（异步，不阻塞渲染）
├─ 成功 → GET /api/location/regeo → 得省 ≠ 当前 → 刷新看板
└─ 失败/拒绝 → 静默保持当前省
P01.2 点击左上角省份 → 跳 P02
P01.3 点击爱车卡片
├─ 已登录 → 跳 P04
└─ 未登录 → 跳 P03（redirect=vehicles）→ 登录后回跳 P04
P01.4 onShow（从 P02/P03 返回）
├─ 最近省变化 → 重新加载看板
└─ 同步登录态（爱车卡片双态刷新）
P02 省份选择页
触发：点击首页左上角省份 / 直接进入
生命周期：
P02.1 onLoad
├─ 读 storage.recent_provinces → 渲染最近 5 省（无则隐藏）
├─ GET /api/provinces → 渲染 31 省网格（按大区分组 + 92# 角标）
└─ 当前省高亮
P02.2 点击历史省份芯片 → select(p)
├─ pushRecent(p)（LRU，仅手动记录）
└─ navigateBack 返回首页 → 首页刷新
P02.3 点击网格省份 → 同上
P02.4 直接返回（未选）→ 首页不变
P03 登录页（微信一键登录）
触发：未登录用户点击私有功能 / 主动进入
生命周期：
P03.1 onLoad
├─ 读 redirect 参数（回跳页，如 vehicles）
└─ 渲染"微信一键登录"按钮
P03.2 用户点击 → wx.login()
├─ 得 code → POST /api/auth/wechat { code }
├─ 成功 → 存 token + app.setLogin(user) → 回跳 redirect（默认首页）
├─ 失败（后端未配 AppID/Secret）→ 提示"请部署方配置微信登录"
└─ wx.login 失败 → 提示重试
P03.3 返回首页看行情 → reLaunch 到首页
首用户规则：后端 users 表为空时，第一个微信登录用户自动成为 admin。
P04 爱车管理页
触发：首页爱车卡片 / 导航进入（需登录）
生命周期：
P04.0 未登录 → 跳 P03（redirect=vehicles）
P04.1 onLoad
├─ GET /api/vehicles → 车辆列表
├─ GET /api/vehicles/impact → 调价影响区（window + 每车建议）
└─ GET /api/provinces → 表单省份下拉
P04.2 点击"添加" → 弹表单（昵称/省份/油号/油箱/油耗/月里程）→ POST /api/vehicles → 刷新
P04.3 点击"编辑" → 表单预填 → PUT /api/vehicles/:id → 刷新
P04.4 点击"删除" → confirm → DELETE /api/vehicles/:id → 刷新
P04.5 （三期）点击某辆车"加油记录" → 跳 pages/refuels（见 40 系列文档）
P05 设置页
触发：导航进入（个人偏好需登录；全局仅 admin）
生命周期：
P05.0 读取 storage 自动定位开关 → 渲染 switch
P05.1 已登录：
├─ GET /api/settings/user → 个人偏好（webhook×3/邮箱/阈值/默认省）
├─ 保存 → POST /api/settings/user
└─ 测试发送 → POST /api/settings/test（逐渠道）
P05.2 已登录且 admin：
├─ GET /api/settings/server → 全局（高德 Key/微信 AppID/AppSecret/SMTP）
└─ 保存 → POST /api/settings/server
P05.3 自动定位开关 → storage auto_location（on/off）
P05.4 退出登录 → app.setLogout() → 清理 token/user
P06 历史调价页
触发：首页导航"历史"
生命周期：
P06.1 onLoad
├─ 默认当年 + 当前省
├─ GET /api/history?year=&province= → 汇总卡 + 调价列表 + 92# 阶梯折线(canvas)
P06.2 切换年份（picker）→ 重新加载
P06.3 切换当前省（返回首页改省后回来）→ onShow 重新加载