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.1 KiB
4.1 KiB
📱 二期 · 微信小程序 — 附录
上游：
docs/30.小程序概要设计.md
目录 / 配置 / 开发者工具 / 上线清单 / 错误码
一、项目目录结构
miniprogram/
├─ app.js 全局：baseUrl + 登录态（setLogin/setLogout）
├─ app.json 页面注册（6 页）+ 窗口 + getLocation 权限声明
├─ app.wxss 全局样式（卡片/按钮/标签）
├─ project.config.json 开发者工具配置（appid、urlCheck=false）
├─ sitemap.json 搜索索引配置
├─ utils/
│ ├─ api.js wx.request 封装：Bearer token 注入 + 401 跳登录
│ ├─ auth.js 最近省 LRU / 登录态 / 格式化（fmtNum/dirText/confText）
│ └─ chart.js 轻量 canvas 折线图（drawChart）
└─ pages/
├─ index/ 首页看板（index.js/wxml/wxss/json）
├─ province/ 省份选择
├─ login/ 微信一键登录
├─ vehicles/ 爱车管理（CRUD + 影响 + 加油记录入口）
├─ settings/ 设置（个人 + admin 全局）
├─ history/ 历史调价
├─ calc/ 独立油耗计算器（三期，无需登录，见 docs/44）
└─ refuels/ 加油记录三 tab（三期，见 docs/43、44）
二、关键配置项
| 文件 | 项 | 说明 |
|---|---|---|
app.js |
globalData.baseUrl |
后端地址；开发 http://localhost:8080，生产 HTTPS |
app.json |
pages |
6 页注册（首项为首页） |
app.json |
requiredPrivateInfos |
["getLocation"]（微信隐私接口声明） |
app.json |
permission.scope.userLocation.desc |
定位用途文案（审核必填） |
project.config.json |
appid |
真实 AppID（体验/发布）；开发可 touristappid |
project.config.json |
setting.urlCheck |
false（开发免域名校验；生产走微信后台配置） |
| 微信后台 | request 合法域名 | 生产须配置后端 HTTPS 域名 |
三、开发者工具使用
| 步骤 | 动作 |
|---|---|
| 1 | 后端启动：go run ./cmd/server（本机 8080） |
| 2 | 开发者工具导入 miniprogram/ 目录 |
| 3 | 详情 → 本地设置 → 勾选"不校验合法域名、web-view、TLS 版本" |
| 4 | 若用微信一键登录：后端设置页配置 wechat_appid / wechat_secret |
| 5 | 编译预览；真机调试需将 baseUrl 改为电脑局域网 IP 或已上线 HTTPS |
四、上线 / 审核清单
| # | 项 | 说明 |
|---|---|---|
| 1 | 后端部署 | Docker 部署到服务器（HTTPS，docker-compose.yml） |
| 2 | 域名配置 | 微信后台配置 request 合法域名（后端 HTTPS） |
| 3 | 小程序 AppID | 注册小程序，AppID 填入 project.config.json |
| 4 | 微信登录配置 | admin 在后端设置页配置 AppID/AppSecret |
| 5 | 类目 | 选择合适类目（如"工具>信息查询"） |
| 6 | 隐私协议 | 微信后台填写用户隐私保护指引（定位用途） |
| 7 | 体验版 | 上传代码 → 设为体验版 → 内部测试 |
| 8 | 提交审核 | 附测试账号说明 → 发布 |
五、错误码（复用后端）
| code | HTTP | 含义 | 小程序处理 |
|---|---|---|---|
| 0 | 200 | 成功 | — |
| 1005 | 400 | 通知渠道/微信登录未配置 | 提示"请部署方配置" |
| 1008 | 401 | 未登录 | 清 token → 跳登录页 |
| 1009 | 403 | 非 admin | 提示无权限 |
| 1010 | 400 | 用户名已存在 | — |
| 1011 | 401 | 用户名或密码错误 / 微信登录失败 | 提示重试 |
| 5000 | 500 | 服务器内部错误 | toast |
完整错误码见
docs/24.附录.md。
六、相关文档索引
| 文档 | 内容 |
|---|---|
docs/30.小程序概要设计.md |
定位/登录/页面地图/部署 |
docs/31.小程序详细设计.md |
引导页 |
docs/32.小程序功能大纲.md |
页面生命周期 P01-P06 |
docs/33.小程序与后端接口对接.md |
认证/API 清单/差异 |
docs/40.记账概要设计.md 等 |
三期记账功能（小程序将新增 refuels 页） |