yexuejc/oil-price-monitoring
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
oil-price-monitoring/docs/44.记账前端详细设计.md
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

6.1 KiB
Raw Permalink Blame History

⛽ 三期 · 记账功能 — 前端详细设计

上游：docs/40.记账概要设计.md（v1.1）、docs/43.记账API详细设计.md 覆盖 H5 与微信小程序双端：独立油耗计算器 / 记一笔 / 记录列表 / 油耗统计（折线图）

一、H5 前端

1.1 页面路由

页面 路由 访问 说明
独立油耗计算器 /fuel-calc 🔓 无需登录 算真实油耗；登录+有车可"保存到车辆"
记录列表 /refuels?vehicle=1 🔒 列表（倒序）+ 油耗字段 + 编辑/删除/补录
记一笔 /refuels/new?vehicle=1 🔒 表单：回填 + 录入 + 完成
油耗统计 /refuels/stats?vehicle=1 🔒 ECharts 折线图 + 汇总
入口 爱车页每辆车卡片 🔒 "加油记录"按钮 + "最近一次油耗"卡片

1.2 记一笔页（登录 + 有车，完整流程）

进入页面
  ├─ GET /api/refuels/prefill?vehicle_id=X ⟶ [A22]
  ├─ 回填（可改）：
  │    ├─ 当前油价   ← current_price（该车省份该油号最新价）
  │    ├─ 上次码表里程 ← last_odometer（最近一条）
  │    └─ 加油日期   ← 默认当前日期，可改（补录场景）
  │    （展示该车平均油耗 avg_l_per_100km 作参考）
  ├─ 输入（必填）：支付金额 / 当前码表里程
  ├─ 可选：优惠金额（默认0）/ 加油日期 / 本次是否加满（复选框，**仅标签**）/ 备注
  └─ 点击"完成"
       ├─ POST /api/refuels ⟶ [A19]
       ├─ possible_missing=true → 弹"耗油量异常，是否有漏记？" → 是：跳列表补录 / 否：保留
       └─ anomaly=odometer → 记录标黄"里程异常"

1.3 独立油耗计算器（核心新功能，无需登录/车辆）

访问矩阵：
  未登录      → 全手输，仅本地计算，不保存（显示"登录后可保存到车辆"）
  登录+有车    → 回填该车信息（A22），计算后可选"保存到车辆"（A19）
  登录+无车    → 提示"请先添加车辆"，引导爱车页
  登录+有车+首条 → 提示"首次加油，无上次基准"

流程：
  进入 /fuel-calc
    ├─ 已登录 + 有车 → 页面顶部【当前车辆】选择器（A4 车辆列表，可切换）
    │    ├─ 切换车辆 → GET A22 prefill → 回填：当前油价 / 上次里程 / 上次日期（可改）
    │    └─ 该车无记录 → 展示"暂无历史"（无上次基准）
    ├─ 未登录 → 顶部登录入口"登录后可实时追踪真实油耗"
    │    └─ 空表单（油价 / 上次里程 / 上次日期 用户手输，可空）
    ├─ 输入：本次里程 / 支付金额 / 优惠金额(0) / 是否加满(标签) / 加油日期(默认当前)
    └─ 点"计算油耗" → 前端本地公式 → 展示结果卡片：
         L/100km = (amount-discount)/price / (odo_now - odo_last) × 100
         元/km   = (amount-discount) / (odo_now - odo_last)
         ├─ 有上次基准且 distance>0 → 展示油耗；distance<=0 → 提示"里程异常"
         ├─ 无上次基准 → 仅展示本次加油量/金额（提示需两次记录才能算油耗）
         ├─ 已登录+有车 → 按钮"保存到车辆" → POST A19 → 保存 + 异常检测
         └─ 未登录 → 结果卡片下方展示"登录后可实时追踪真实油耗"（点击登录）

1.4 记录列表

  • 每条显示：日期 / 里程 / 油量 / 单价 / 实付 / 区间油耗（L/100km、元/km）
  • 加满标签：full_tank=true 显示"加满"徽标
  • 异常记录：anomaly=odometer 标黄"里程异常"
  • 操作：编辑（弹层）→ PUT；删除 → confirm → DELETE；补录 → 弹表单（漏记那次的日期/里程/金额/油价）→ 按日期排序落位 → 级联重算

1.5 统计页 + 爱车首页"最近油耗"卡片

  • 统计页：汇总卡（总次数/累计金额/累计油量/平均 L/100km/平均元/km）+ ECharts 折线图
  • 爱车首页卡片：每辆车显示"最近一次油耗 L/100km"→ 点击跳该车统计页

二、ECharts 折线图设计（H5）

图 数据源 说明
油耗趋势 trends.l_per_100km 主图，markLine 显示平均油耗
成本趋势 trends.yuan_per_km 可切换查看
油价趋势 trends.price 每升价格变化
累计费用 trends.cumulative_amount 面积图（阶梯累计）
  • 日期横轴；图例可切换指标；异常点（anomaly=odometer）空心标记，hover 提示
  • 数据源：GET /api/refuels/stats?vehicle_id=X ⟶ [A23]

三、小程序前端

3.1 页面

页面 功能
pages/refuels/refuels 某辆车加油记录（三 tab：记录 / 记一笔 / 统计）
pages/calc/calc 独立油耗计算器（首页导航入口，无需登录）

入口：

  • 爱车页（P04）每辆车 → "加油记录" → navigateTo pages/refuels/refuels?vehicle_id=X
  • 首页导航 → "算油耗" → navigateTo pages/calc/calc

3.2 记一笔（与 H5 一致）

  • 回填 current_price / last_odometer / 加油日期（默认当前）
  • 输入支付金额 / 优惠金额 / 当前里程 + 加满复选框（标签）
  • 完成 → POST → possible_missing 用 wx.showModal 确认 → 是：跳补录 / 否：保留
  • anomaly=odometer 标黄提示

3.3 独立计算器（calc 页）

  • 未登录：纯本地计算（输入油价/上次里程/本次里程/金额/优惠）→ 展示 L/100km、元/km
  • 已登录：车辆选择 → 回填（A22）→ 计算 → "保存到车辆"按钮（A19）
  • 折线图：复用 utils/chart.js drawChart（油耗 + 累计费用两个 series）

四、表单字段校验（双端一致）

字段 规则
vehicle_id 保存时必填，须属于当前用户（计算器本地算可缺省）
odometer 必填，数值 (0, 1000000] km
amount 必填，数值 > 0 元
price_per_liter 必填，数值 > 0 元/升
discount 可选，[0, amount) 元
full_tank 可选，默认 true（仅标签，不参与计算）
refuel_at 可选，默认当前时间（补录可改）
Reference in new issue View Git Blame Copy Permalink