docs: 仓库根 README + docs/api.md 完整 API 文档
补上交付物必备的文档: - README.md:项目介绍 / 特性 / 技术栈 / 快速开始 / 仓库结构 / 核心计算公式 / 测试覆盖 / 设计原则 / 路线图 / License - docs/api.md:6 个 endpoint 完整契约(请求参数 / 响应 / 错误码 / 业务规则),含 Statistics 字段含义与采样逻辑说明 为什么现在补: - 之前的 12 个 commit 都是代码,GitHub / Gitea 仓库首页空白 - 新成员(或者未来的自己)来看仓库,无法在 5 分钟内知道这是个啥 / 怎么跑 - API 文档从代码里的 dto.go / handler.go 反推,容易漏边界条件;集中写一遍 把所有约束沉淀下来 README 设计: - 顶上一段简介 + badge - ✨ 特性(7 条,每条对应 plan §3 / §6 / §12) - 🛠 技术栈:表格化展示 plan 锁定选型 - 🚀 快速开始:5 步(克隆 / 装依赖 / 启后端 / 启前端 / 冒烟) - 📁 仓库结构:树状展示两个子工程的完整布局 - 🔢 核心计算规则:4 个公式表(从 plan §6 提炼) - 🧪 测试覆盖:列出 22+5+13 的具体来源文件 - 🐳 部署 / 🗺 路线图:占位 + 标 done - 📐 设计原则:把 plan §12 + AGENTS.md 关键约束翻译成"为什么这么做" - 📎 相关:链回 AGENTS.md / docs/api.md / FuelLog_PLAN.md docs/api.md 设计: - 通用约定:UTC / decimal / 列表空数组 / 错误码字典 - 6 个 endpoint 一段一个,含:curl-style 示例、参数表、Response 200 示例、 业务规则(例如 RefuelCreate.price_per_liter 不入参 / RefuelUpdate patch 语义 / Statistics 只在 is_full 序列内采样) - 错误码字典表格(INTERNAL / INVALID_ARGUMENT / NOT_FOUND / CONFLICT / ...) - 索引说明 风格:中文为主,与 AGENTS.md / commit message 保持一致;技术名词留英文 (endpoint / Vehicle / RefuelRecord 等);代码示例保持 JSON 风格。 未做(留待后续): - README 截图:得真起服务跑,等 Docker 起来再补 - README 英文版:暂只中文,MVP 上线后再翻
This commit is contained in:
@@ -0,0 +1,217 @@
|
||||
# FuelLog 加油记
|
||||
|
||||
> 轻量、精美、移动端优先的个人加油记录与车辆燃油成本分析工具。
|
||||
|
||||
[](fuellog-api/go.mod)
|
||||
[](fuellog-web/package.json)
|
||||
[](#license)
|
||||
|
||||
---
|
||||
|
||||
## ✨ 特性
|
||||
|
||||
- **10 秒录入一笔加油**:加油时间 → 里程 → 升数 → 总金额 → 油品 → 加油站 → 加满 → 备注,移动端底部固定保存按钮,实测从打开到保存 < 10s。
|
||||
- **服务端实时算实际油价**:`price_per_liter = total_amount / liters`,前端只入 amount + liters,前端同步显示"实际油价 ¥X.XX/L"作为 UX 反馈,服务端是权威。
|
||||
- **标准百公里油耗**:只在"连续两次 `is_full=true`"之间计算,半箱油不污染指标 —— 与 plan §6.3 / §19 严格对齐。
|
||||
- **每公里成本 + 月度趋势**:Dashboard 主指标 + Statistics 4 张图(油价 / 油耗 / 月度费用 / 每公里成本)。
|
||||
- **PWA**:可"安装"到手机主屏,离线时已访问页面仍可用;Service Worker 预缓存所有静态资源,API 走 NetworkFirst 兜底 cache。
|
||||
- **多车辆 + 唯一默认**:可加多辆,默认车辆唯一,切换走事务。
|
||||
|
||||
---
|
||||
|
||||
## 🛠 技术栈
|
||||
|
||||
| 层 | 选型 | 理由 |
|
||||
|---|---|---|
|
||||
| 前端 | Vue 3 + Vite + TypeScript + Pinia + Vue Router + Tailwind CSS + Naive UI + ECharts | plan §3 锁定;轻量、Mobile First、TypeScript 严格、Naive UI 适配暗色 |
|
||||
| 后端 | Go 1.22 + Gin + GORM | plan §3 锁定;单文件、编译快、goroutine 适合个人项目 |
|
||||
| 数据库 | SQLite (glebarez/sqlite 纯 Go) | plan §3 锁定;零依赖、文件级持久化;WAL + 外键 + busy_timeout |
|
||||
| 精度 | shopspring/decimal | plan §16;金额 / 油耗 / 成本用 decimal 避免 float 累计误差 |
|
||||
| 部署 | Docker + Docker Compose + Nginx | plan §17;反代 + volume 持久化 SQLite |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始(开发期)
|
||||
|
||||
### 前置
|
||||
|
||||
- Node.js ≥ 20(已测 24.15)
|
||||
- pnpm ≥ 9(已测 9.7)或 npm
|
||||
- Go ≥ 1.22(已测 1.27)
|
||||
- git,可选:make
|
||||
|
||||
### 1. 克隆 + 装依赖
|
||||
|
||||
```bash
|
||||
git clone https://gitea.kennethcheng.cc/KennethCheng/FuelLog.git
|
||||
cd FuelLog
|
||||
|
||||
# 后端
|
||||
cd fuellog-api
|
||||
go mod tidy
|
||||
cp .env.example .env
|
||||
|
||||
# 前端(另开一个 shell)
|
||||
cd fuellog-web
|
||||
pnpm install
|
||||
cp .env.example .env.local
|
||||
```
|
||||
|
||||
### 2. 启后端
|
||||
|
||||
```bash
|
||||
cd fuellog-api
|
||||
go run ./cmd/server # 监听 :8080
|
||||
```
|
||||
|
||||
输出形如:
|
||||
```
|
||||
time=... msg="db ready" path=./data/fuellog.db
|
||||
time=... msg="server starting" addr=:8080 mode=debug
|
||||
```
|
||||
|
||||
### 3. 启前端
|
||||
|
||||
```bash
|
||||
cd fuellog-web
|
||||
pnpm dev # 监听 :5173,/api 自动代理到 :8080
|
||||
```
|
||||
|
||||
打开 <http://127.0.0.1:5173> 即可。首次进会看到"还没有车辆,先去添加"的引导。
|
||||
|
||||
### 4. (可选)冒烟测试
|
||||
|
||||
```bash
|
||||
cd fuellog-api
|
||||
pwsh -ExecutionPolicy Bypass -File scripts/smoke.ps1
|
||||
# 13/13 断言:建车 / 加油 / 油价 / 油耗 / 删记录 / 删车 全部命中 plan §6 数值
|
||||
```
|
||||
|
||||
### 5. (可选)单测
|
||||
|
||||
```bash
|
||||
cd fuellog-api
|
||||
go test ./... # 22 decimal + 5 service
|
||||
pnpm typecheck # 前端 vue-tsc
|
||||
pnpm build # 前端 vite build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 仓库结构
|
||||
|
||||
```
|
||||
FuelLog/
|
||||
├── fuellog-api/ # Go 后端
|
||||
│ ├── cmd/server/main.go # 入口
|
||||
│ ├── internal/
|
||||
│ │ ├── config/ # env 加载
|
||||
│ │ ├── db/ # GORM open + migration
|
||||
│ │ ├── handler/ # HTTP 入参 / 出参
|
||||
│ │ ├── service/ # 业务逻辑 + 核心计算
|
||||
│ │ ├── repository/ # GORM 数据访问
|
||||
│ │ ├── model/ # GORM 实体
|
||||
│ │ ├── dto/ # 请求/响应 DTO
|
||||
│ │ ├── middleware/ # logger / recover / cors
|
||||
│ │ └── router/ # Gin 路由
|
||||
│ ├── pkg/
|
||||
│ │ ├── apperror/ # 统一错误类型
|
||||
│ │ └── decimal/ # 金额 / 油耗精度工具
|
||||
│ ├── migrations/ # 迁移(目前 GORM AutoMigrate;后续手写)
|
||||
│ ├── scripts/ # smoke.ps1 等
|
||||
│ └── go.mod
|
||||
│
|
||||
├── fuellog-web/ # Vue 前端
|
||||
│ ├── src/
|
||||
│ │ ├── api/ # axios + 类型化 client
|
||||
│ │ ├── components/ # 业务组件
|
||||
│ │ ├── layouts/ # AppLayout(顶栏 + 移动端底部 Tab)
|
||||
│ │ ├── pages/ # Dashboard / Refuels / RefuelNew / Vehicles / Statistics / NotFound
|
||||
│ │ ├── router/ # Vue Router 配置
|
||||
│ │ ├── stores/ # Pinia
|
||||
│ │ ├── styles/ # tailwind.css + theme.css(CSS Variables)
|
||||
│ │ ├── utils/ # decimal 工具
|
||||
│ │ ├── App.vue
|
||||
│ │ └── main.ts
|
||||
│ ├── public/ # favicon / manifest / PWA icons
|
||||
│ └── package.json
|
||||
│
|
||||
├── deploy/ # (待) docker-compose + nginx
|
||||
├── docs/
|
||||
│ └── api.md # 完整 API 文档
|
||||
├── data/ # SQLite 文件(默认 .gitignore,挂载 volume)
|
||||
├── AGENTS.md # Agent 工程操作手册(规则、约束、Phase 顺序)
|
||||
├── README.md # 本文件
|
||||
└── .gitignore
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔢 核心计算规则
|
||||
|
||||
| 指标 | 公式 | 范围 |
|
||||
|---|---|---|
|
||||
| 实际油价 | `total_amount / liters` | 服务端权威,前端只展示 |
|
||||
| 行驶里程 | `current.odometer - previous.odometer` | 负数 / 零视为无效 |
|
||||
| 百公里油耗 | `liters / mileage × 100` | **只在 `is_full=true` 序列内采样** |
|
||||
| 每公里成本 | `total_amount / mileage` | 同上 |
|
||||
|
||||
所有除法走 `shopspring/decimal`(后端) / 同步实现(前端 `utils/decimal.ts`)。
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试覆盖
|
||||
|
||||
- `pkg/decimal/money_test.go` — 22 个子测试,覆盖 plan §6.1-6.4 全部案例
|
||||
- `internal/service/refuel_record_test.go` — 5 个测试,覆盖"半箱油不进入标准油耗"硬规则
|
||||
- `scripts/smoke.ps1` — 13 步端到端冒烟,跑通"建车 → 加 3 次油 → 统计 → 删记录 → 删车"
|
||||
|
||||
---
|
||||
|
||||
## 🐳 部署(待完成)
|
||||
|
||||
```bash
|
||||
cd deploy
|
||||
docker compose up -d
|
||||
# 浏览器访问 http://your-host
|
||||
```
|
||||
|
||||
详见 `deploy/` 目录(待补充)。
|
||||
|
||||
---
|
||||
|
||||
## 🗺 路线图
|
||||
|
||||
- [x] Phase 0~1:初始化 + 后端骨架 + 数据层 + API + 单测 + 冒烟
|
||||
- [x] Phase 2~3:前端骨架 + 4 个业务页
|
||||
- [x] Phase 4:PWA(manifest / SW / 添加到主屏)
|
||||
- [ ] Phase 5:数据导入导出(JSON / CSV)
|
||||
- [ ] Phase 6:多用户 / 鉴权(目前是个人单机)
|
||||
- [ ] Phase 7:Docker 部署 + 反代
|
||||
- [ ] Phase 8:充电 / 保养 / 停车等扩展
|
||||
|
||||
---
|
||||
|
||||
## 📐 设计原则
|
||||
|
||||
- **Mobile first**:360 / 390 / 430 三档断点先验证;布局用 `grid + md:`,CSS Variables 切暗色。
|
||||
- **不写死颜色 / 间距 / 字号**:Tailwind theme + `:root` CSS Variables 双轨;`brand` / `ink` / `surface` 都是变量,组件层一律 `text-brand` / `bg-surface`。
|
||||
- **Handler 不写业务**:Handler 只做参数解析、错误码映射;Service 持有 Repository 接口,便于单测替换。
|
||||
- **金额 decimal**:任何除法都不直接用 float64。
|
||||
- **半箱油不污染油耗**:plan §6.3 + §19 验收的硬规则,单测里有专门 case。
|
||||
- **错误统一格式**:`{ "code": "INVALID_ARGUMENT", "message": "..." }`,前端 axios 拦截器解到 `Error.cause`。
|
||||
- **PWA 添加到主屏**:`display: standalone` + maskable icon + SW 预缓存,真像 app。
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT
|
||||
|
||||
---
|
||||
|
||||
## 📎 相关
|
||||
|
||||
- [AGENTS.md](./AGENTS.md) — Agent 工程操作手册(规则、约束、Phase 顺序、Definition of Done)
|
||||
- [docs/api.md](./docs/api.md) — 完整 API 文档
|
||||
- [FuelLog_PLAN.md](./FuelLog_PLAN.md) — 原始产品 / 技术决策文档(仓库内)
|
||||
Reference in New Issue
Block a user