 KennethCheng
|
a2fc215ef9
|
docs: README 补全 Docker 部署章节(拓扑图 / 镜像要点 / 持久化 / 反代)
上条 commit (846b1a7) 把 deploy/ 目录实际文件都铺好了,但 README 的
"🐳 部署"还停留在"待完成"占位,新成员(以及未来的自己)看到 README
会以为 Docker 还没做。这条 commit 把 README 与实际状态对齐。
新增 / 改动 README.md:
- 仓库结构树:deploy/ 从"(待) docker-compose + nginx"改成
"Docker 部署文件",列出 4 个子文件
- 替换 "🐳 部署(待完成)" 占位为完整章节:
* 快速部署:一条 docker compose up -d
* 部署拓扑:ASCII 图展示 web 容器 (nginx) 反代 /api 到 api 容器
(GORM + SQLite),数据卷持久化
* 镜像要点:表格列出 api / web 两个镜像的 base image + 关键配置
(CGO=0 / tini / 非 root / corepack pnpm / gzip + 30 天 immutable cache)
* 数据持久化:DB_PATH 路径 / volume 名 / 备份命令(docker run --rm 模板)
* 反代建议:不要直接 8080 暴露公网,前面挡 NPM / Traefik,符合
plan §17 "容器内 API 默认只监听内网"
* 健康检查:API + web 都用 wget,compose 用 condition: service_healthy
* 开发模式:不想装 Go 也能跑,流程:pnpm build -> docker compose up
* 链回 deploy/README.md
- 路线图:Phase 5 标 done,Phase 6/7/8 标 pending(对应 Import/Export /
Auth / 扩展)
未做(留待后续):
- README 截图(Docker 跑起来后再补)
- Traefik / NPM 自动 HTTPS 的具体配置(留给 plan §17 后续)
- 数据备份 cron / 灾备演练
风格保持与之前一致:中文为主,技术名词留英文,emoji 章节标题。
|
2026-09-13 17:20:50 +08:00 |
|
|
KennethCheng
|
f24e6639e3
|
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 上线后再翻
|
2026-09-13 17:06:39 +08:00 |
|