feat(backend): establish gin sqlite service skeleton
This commit is contained in:
QiuSW
@@ -53,7 +53,7 @@
|
||||
|
||||
当前已完成 Phase 0 和 Phase 1：Android 可运行、设备就绪、workflow、私有样本导入、
|
||||
动态词搜索、最多 5 个候选截图采集、结构化需求提取、候选评估和人工确认停止点均已
|
||||
验证。下一步是 T-201，生成并收敛 Go-Gin、SQLite 和迁移骨架。
|
||||
验证。T-201 后端骨架也已完成，下一步是 T-202，生成并确认 P0 Web/App 低保真原型。
|
||||
|
||||
严格按以下顺序推进：
|
||||
|
||||
@@ -103,5 +103,12 @@ $env:RUN_START_COMMAND = "1"
|
||||
.\init.ps1
|
||||
```
|
||||
|
||||
脚本执行 `test assembleDebug`；上游当前没有单元测试源，因此 `test` 的测试任务为
|
||||
`NO-SOURCE`，但编译与 APK 打包必须成功。后端建立后再追加后端测试和启动命令。
|
||||
脚本先执行 Android `test assembleDebug`，再以 `GOTOOLCHAIN=local` 执行后端
|
||||
`go test ./...`、`go vet ./...` 并构建 API 与 migration 两个入口。后端单独运行：
|
||||
|
||||
```powershell
|
||||
Set-Location backend-api
|
||||
$env:GOTOOLCHAIN = "local"
|
||||
go run ./cmd/migrate up
|
||||
go run ./cmd/api
|
||||
```
|
||||
|
||||
+20
-24
@@ -16,10 +16,10 @@
|
||||
| 第一层任务源 | UTF-8 无 BOM 四行蝦皮订单文本 + 同订单号 JPEG | 已实现 | `task-contract` 共享 `ProbeTask/TaskSource`；CLI 输出到 `.local/`，只有显式 Debug 属性才注入 APK，默认构建会清除私有资产。 |
|
||||
| Android 长任务 | 前台服务 + 持续通知 | 计划采用 | 降低执行中被系统挂起的风险，仍需处理进程死亡恢复。 |
|
||||
| 后端语言 | Go 1.23.0 | MVP 已定 | 与现有本机工具链一致；构建测试必须设置 `GOTOOLCHAIN=local` 防止静默升级。 |
|
||||
| 后端骨架 | Go Blueprint v0.10.11 生成的最小 Gin + SQLite 工程 | MVP 已定 | 只作为一次性脚手架输入；生成后立即重写版本约束。 |
|
||||
| 后端骨架 | Go Blueprint v0.10.11 生成的最小 Gin + SQLite 工程 | 已接入并收敛 | 只作为一次性脚手架输入；演示路由、默认 CORS、`.env` 自动加载、单例和 fatal 行为均已删除。 |
|
||||
| 后端框架 | Gin v1.11.0 | MVP 已定 | 这是 `go.mod` 明确支持 Go 1.23.0 的最高已核实 Gin 版本。 |
|
||||
| 数据访问 | 标准库 `database/sql` | MVP 已定 | 领域层通过仓储接口访问，避免先引入 ORM 和代码生成复杂度。 |
|
||||
| 数据迁移 | Goose v3，使用 SQL migration | MVP 已定 | 迁移可审核、可排序并支持 SQLite；版本在 T-201 建立 `go.mod` 时锁定。 |
|
||||
| 数据迁移 | Goose v3.26.0，使用嵌入式 SQL migration | 已验证 | v3.26.0 是已核实仍声明 Go 1.23.0 的最高版本；v3.27.x 要求 Go 1.25。 |
|
||||
| 管理 Web | Gin + `html/template` + `embed` + 少量原生 JS/CSS | MVP 已定 | 不单独引入 SPA 工程，模板和静态资源随服务构建。 |
|
||||
| 数据库 | SQLite | MVP 已定 | 单服务、单设备验证足够；多实例或并发提升前迁移 PostgreSQL。 |
|
||||
| 图片/截图 | 后端受控本地文件目录，数据库存元数据 | MVP 已定 | 禁止把二进制直接塞入日志；生产再评估对象存储。 |
|
||||
@@ -27,7 +27,7 @@
|
||||
| App 鉴权 | 采购员登录态 + 设备绑定令牌 | 目标已定，细节待实现 | 人员身份与设备身份分离；令牌只保存哈希。 |
|
||||
| VLM 接入 | 应用内统一适配器，优先兼容 OpenAI 风格多模态接口 | 需求提取与候选评估已实现，供应商待定 | T-103/T-104 使用严格 JSON Schema、单候选单次调用和 2048 px 图片上限；GUI-Owl/MAI-UI 动作模型不具备需求提取能力。 |
|
||||
| 通知 | MVP 不使用推送 | 已定 | 点击“获取任务”调用原子 claim API；V2 再评估厂商推送/WebSocket。 |
|
||||
| 后端测试 | 标准库 `testing` + `httptest` | MVP 已定 | 覆盖状态机、权限、幂等、SQLite 事务和输入校验。 |
|
||||
| 后端测试 | 标准库 `testing` + `httptest` | 骨架已验证 | 当前 25 个测试覆盖配置、SQLite pragma/外键、迁移、健康检查、安全 recovery、错误合约、路由和有界关闭；后续任务再增加状态机、权限与幂等。 |
|
||||
| Android 测试 | Gradle `test` + `kotlinx-coroutines-test` 1.7.3 + 真实设备 smoke | Phase 1 探针已验证 | 166 次测试覆盖 runner、动态页面分类、受控证据、VLM schema、人工确认策略与隐私；OnePlus PKG110 上完成私有 fixture + 本机 mock 的需求提取和 5 候选评估 smoke。 |
|
||||
| 部署 | 单机局域网 Go 服务；容器化后置 | MVP 已定 | Android 测试机必须能通过 HTTPS 或受控测试网络访问。 |
|
||||
|
||||
@@ -87,15 +87,13 @@ go-blueprint create --name backend-api --framework gin --driver sqlite --git ski
|
||||
```
|
||||
|
||||
Go Blueprint v0.10.11 当前生成的是 `Go 1.25.0 + Gin 1.12.0`，不能直接作为本项目
|
||||
的 `go.mod`。2026-07-25 已在临时目录将生成结果调整为以下版本，并在
|
||||
`GOTOOLCHAIN=local` 下完成 `go mod tidy` 和 `go test ./...`：
|
||||
的 `go.mod`。2026-07-25 已在仓库外临时目录核实生成树，并把正式 `go.mod` 固定为：
|
||||
|
||||
```text
|
||||
go 1.23.0
|
||||
github.com/gin-gonic/gin v1.11.0
|
||||
github.com/gin-contrib/cors v1.7.6
|
||||
github.com/joho/godotenv v1.5.1
|
||||
github.com/mattn/go-sqlite3 v1.14.48
|
||||
github.com/pressly/goose/v3 v3.26.0
|
||||
```
|
||||
|
||||
Gin v1.12.0 的 `go.mod` 要求 Go 1.25.0，因此本项目禁止升级到 Gin 1.12.x，除非先
|
||||
@@ -116,20 +114,18 @@ RabbitMQ、NATS 和 gRPC 为主，不符合最小 Gin + SQLite 边界。
|
||||
```text
|
||||
android-buyer/ # 已接入的 Roubao Kotlin Android App
|
||||
backend-api/
|
||||
cmd/api/ # 进程入口，只负责装配和生命周期
|
||||
internal/domain/ # 实体、状态机和确定性规则
|
||||
internal/usecase/ # 创建、领取、执行和结果归档
|
||||
internal/transport/http/ # Gin handler、中间件和页面
|
||||
internal/repository/sqlite/ # database/sql 仓储
|
||||
internal/platform/ # 配置、日志、文件和 VLM 适配器
|
||||
migrations/ # Goose SQL migration
|
||||
web/templates/ # html/template
|
||||
web/static/ # 少量 CSS/JS
|
||||
var/ # 本地运行数据，必须忽略
|
||||
cmd/api/ # API 进程装配、信号和优雅关闭
|
||||
cmd/migrate/ # 显式 migration up/down/status
|
||||
internal/config/ # 环境变量和安全默认
|
||||
internal/platform/database/ # SQLite 打开、pragma 和生命周期
|
||||
internal/platform/migration/ # Goose provider 封装
|
||||
internal/transport/httpapi/ # Gin 路由、健康检查和 HTTP Server
|
||||
migrations/ # 嵌入式 Goose SQL migration
|
||||
var/ # 本地运行数据，必须忽略
|
||||
docs/
|
||||
```
|
||||
|
||||
目录在真实骨架建立后以代码为准并同步本文。
|
||||
`domain/usecase/repository/sqlite/web` 将在对应业务任务出现真实代码时创建，不提交空包。
|
||||
|
||||
## 构建与运行命令
|
||||
|
||||
@@ -137,13 +133,13 @@ docs/
|
||||
| --- | --- | --- |
|
||||
| Android 标准验证 | `.\init.ps1` | 已验证 |
|
||||
| Android 构建 | `android-buyer\gradlew.bat assembleDebug --no-daemon` | 已验证 |
|
||||
| Android 测试任务 | `android-buyer\gradlew.bat test --no-daemon` | 已验证；当前全工程 78 次测试通过 |
|
||||
| Android 测试任务 | `android-buyer\gradlew.bat test --no-daemon` | 已验证；当前全工程 166 次测试通过 |
|
||||
| Android 安装/启动 | `$env:RUN_START_COMMAND="1"; .\init.ps1` | 已在 Android 16 真机验证 |
|
||||
| 后端依赖 | `go mod download`（在 `backend-api/`） | 待 `T-201` |
|
||||
| 后端测试 | `go test ./...`（在 `backend-api/`） | 待 `T-201` |
|
||||
| 后端构建 | `go build -o bin/cmroubao-api.exe ./cmd/api` | 待 `T-201` |
|
||||
| 后端启动 | `go run ./cmd/api` | 待 `T-201` |
|
||||
| 数据迁移 | `goose -dir migrations sqlite3 ./var/cmroubao.db up` | 待 `T-201` |
|
||||
| 后端依赖 | `$env:GOTOOLCHAIN="local"; go mod download`（在 `backend-api/`） | 已验证 |
|
||||
| 后端测试 | `$env:GOTOOLCHAIN="local"; go test ./...; go vet ./...` | 已验证；25 个测试 |
|
||||
| 后端构建 | `go build -o bin/cmroubao-api.exe ./cmd/api` 与 `./cmd/migrate` | 已验证 |
|
||||
| 后端启动 | `go run ./cmd/api` | 已完成本机 HTTP smoke |
|
||||
| 数据迁移 | `go run ./cmd/migrate up` | 已完成 `status/up/up/down/up` smoke |
|
||||
|
||||
`gradlew installDebug` 在当前 Android 16 设备上由旧版 AGP/ddmlib 返回 `-99`，
|
||||
但 SDK Platform Tools 37.0.0 的 `adb install -r -t` 成功。标准脚本因此使用 SDK
|
||||
|
||||
@@ -60,6 +60,18 @@ internal/platform/ # 配置、日志、文件存储和 VLM 适配器
|
||||
- 在 Gin handler 中写任务状态机、SQL 或仓储业务逻辑。
|
||||
- 保存拼多多密码、支付凭证或支付验证码。
|
||||
|
||||
T-201 已建立的基础包只有 `config`、`platform/database`、`platform/migration` 和
|
||||
`transport/httpapi`。HTTP 进程使用非零 read-header/read/write/idle timeout、
|
||||
1 MiB header 上限和 10 秒有界关闭；默认监听 `127.0.0.1:8080`，扩大监听范围必须
|
||||
显式配置。Gin 不启用默认 Logger/CORS/Recovery，异常恢复返回稳定 JSON 且不记录
|
||||
Authorization、Cookie 或 panic 内容。
|
||||
|
||||
SQLite 默认文件为被忽略的 `backend-api/var/cmroubao.db`，连接启用 foreign keys、
|
||||
5 秒 busy timeout、WAL 和 immediate transaction，并限制单连接以匹配单进程 MVP。
|
||||
数据库由 `cmd` 显式打开和关闭，不存在包级单例。Goose SQL 通过 `embed.FS` 加载，
|
||||
`cmd/migrate` 显式执行 `up/down/status`；T-201 只验证迁移链路，业务表由后续任务
|
||||
按 API 和领域模型建立。
|
||||
|
||||
### 2.2 Android App
|
||||
|
||||
建议模块：
|
||||
|
||||
+12
-3
@@ -83,6 +83,14 @@
|
||||
- 不向客户端返回 `password_hash`、`token_hash`、存储绝对路径或供应商密钥。
|
||||
- 通用错误使用稳定 code 和可读 message；内部堆栈只进受控日志。
|
||||
- 文件访问通过鉴权接口，防止路径遍历和猜测 URL。
|
||||
- Go 命令固定 `GOTOOLCHAIN=local`；`go.mod` 不得出现更高 Go 版本或未固定的
|
||||
`@latest` 依赖。
|
||||
- 后端不得自动加载 `.env`、默认开启 CORS、使用包级数据库单例，或在库、handler、
|
||||
健康检查中调用 `log.Fatal`/`os.Exit`。
|
||||
- `http.Server` 必须配置 read-header/read/write/idle/header 上限和有界关闭；
|
||||
recovery 不得把 Authorization、Cookie、panic 或请求正文写普通日志。
|
||||
- SQLite 数据文件必须位于被忽略目录，启用 foreign keys、有限 busy timeout 和
|
||||
WAL；连接由进程入口显式关闭，migration 使用固定版本和受控 SQL 文件。
|
||||
|
||||
## 7. 安全与隐私
|
||||
|
||||
@@ -125,6 +133,7 @@
|
||||
- [ ] 当前任务文件记录命令、结果、环境和未验证项。
|
||||
- [ ] `current-state.md` 与真实目录、命令和 blocker 一致。
|
||||
|
||||
当前 Android 标准验证命令是根目录 `.\init.ps1`；它执行 Gradle `test` 和
|
||||
`assembleDebug`。设置 `RUN_START_COMMAND=1` 时使用 SDK 内新版 ADB 安装并启动。
|
||||
后端建立后再在这里列出后端命令。
|
||||
项目标准验证命令是根目录 `.\init.ps1`；它执行 Android Gradle `test` 和
|
||||
`assembleDebug`，再以 `GOTOOLCHAIN=local` 执行后端 `go test ./...`、
|
||||
`go vet ./...`、`gofmt` 检查和两个入口构建。设置 `RUN_START_COMMAND=1` 时使用
|
||||
SDK 内新版 ADB 安装并启动 Android App。
|
||||
|
||||
+21
@@ -40,6 +40,27 @@ HTTP 语义：
|
||||
- `429` 频率限制
|
||||
- `503` 依赖暂不可用
|
||||
|
||||
## 服务健康
|
||||
|
||||
### `GET /healthz`
|
||||
|
||||
不需要业务身份，只检查进程和 SQLite 连接，不返回版本、路径、DSN、连接池统计或内部
|
||||
错误。响应带 `Cache-Control: no-store`，默认不返回 CORS header。
|
||||
|
||||
数据库可用：
|
||||
|
||||
```json
|
||||
{"status":"ok"}
|
||||
```
|
||||
|
||||
返回 `200`。数据库不可用时返回 `503`：
|
||||
|
||||
```json
|
||||
{"status":"unavailable"}
|
||||
```
|
||||
|
||||
健康检查失败不能终止进程；未知路由和不允许的方法分别使用稳定 `404`/`405` JSON。
|
||||
|
||||
## 认证
|
||||
|
||||
### 管理 Web 会话
|
||||
|
||||
+22
-7
@@ -5,16 +5,19 @@
|
||||
## 当前快照
|
||||
|
||||
- 日期：2026-07-25
|
||||
- 阶段：Phase 1 已完成，准备开始 T-201 后端骨架
|
||||
- Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104 均已纳入 Git 历史
|
||||
- 阶段：T-201 已完成，准备开始 T-202 P0 低保真原型
|
||||
- Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 均已纳入 Git 历史
|
||||
- 生产代码：`android-buyer/` 已接入 Roubao Android 源码
|
||||
- Android：固定 `main@c8a6d7f03422eb01744b01f3ee77bf7757741f7e`；MIT 许可证已保留
|
||||
- 后端：已决定使用 Go 1.23.0 + Gin 1.11.0；Go Blueprint v0.10.11 骨架尚未接入
|
||||
- 后端：Go 1.23.0 + Gin 1.11.0 + SQLite + Goose 3.26.0 骨架已建立；Go Blueprint
|
||||
v0.10.11 只作为一次性输入，危险默认与演示逻辑已移除
|
||||
- 本机 Android 工具：JDK 17.0.13、Command-line Tools 22.0、SDK 34、
|
||||
Build Tools 34.0.0、Platform Tools/ADB 37.0.0；用户级 SDK 环境变量已设置
|
||||
- Android Studio：未安装；`winget` 静默安装卡住后已终止，不阻塞命令行构建
|
||||
- 测试：`lintDebug test assembleDebug` 成功；App 两个变体、task contract 和导入器
|
||||
共 26 份报告、166 次测试，0 failure、0 error、0 skipped
|
||||
- 后端测试：`GOTOOLCHAIN=local go test -count=1 ./...` 共 25 个测试通过；
|
||||
`go vet ./...`、API/migration Windows 构建和根 `init.ps1` 均通过
|
||||
- Workflow：纯 Kotlin runner 已支持步骤 timeout、最多 3 次 retry、安全阻塞、
|
||||
用户停止和单 runner 并发拒绝；T-102 已接入搜索加有界候选采集五步
|
||||
- TaskSource：严格 CLI 已生成并验证真实私有 ProbeTask；默认 APK 不含私有 fixture
|
||||
@@ -47,18 +50,19 @@
|
||||
| `docs/tasks/T-102.md` | DONE | 最多 5 个候选详情截图、证据 manifest 和结果页返回 |
|
||||
| `docs/tasks/T-103.md` | DONE | 私有任务需求 schema、硬约束、隐私边界和 VLM 适配器 |
|
||||
| `docs/tasks/T-104.md` | DONE | 动态搜索、候选严格评估、本地建议和人工确认点 |
|
||||
| `docs/tasks/T-201.md` | DONE | Go-Gin、SQLite、Goose migration 和健康检查骨架 |
|
||||
| `deepseek总结.txt` | 已有 | 历史讨论摘要，不是正式需求权威 |
|
||||
| `android-buyer/` | 已有 | Roubao `main` 固定 commit 的 Android 基线 |
|
||||
| `android-buyer/task-contract/` | 已有 | Android/CLI 共享 ProbeTask 与 TaskSource |
|
||||
| `android-buyer/tools/shopee-importer/` | 已有 | 开发机私有 fixture 导入 CLI |
|
||||
| `backend-api/` | 待建 | Go-Gin、管理 Web 和数据目标目录 |
|
||||
| `init.ps1` / `init.sh` | 已验证 | Android 构建入口；可选真机安装启动 |
|
||||
| `backend-api/` | 已有 | Go-Gin API、SQLite、migration、健康检查和测试骨架 |
|
||||
| `init.ps1` / `init.sh` | 已验证/待跨平台 | Windows 同时验证 Android/Go；Unix 入口待 Linux/WSL 复核 |
|
||||
|
||||
## 任务摘要
|
||||
|
||||
- 已完成：T-001 至 T-004，以及 T-101 至 T-104。
|
||||
- 已完成：T-001 至 T-004、T-101 至 T-104，以及 T-201。
|
||||
- 正在进行：无。
|
||||
- 下一个可领取任务：T-201 生成并收敛 Go-Gin、SQLite 和迁移骨架。
|
||||
- 下一个可领取任务：T-202 生成并确认 P0 Web/App 低保真原型。
|
||||
|
||||
## 当前可运行内容
|
||||
|
||||
@@ -67,6 +71,11 @@
|
||||
|
||||
$env:RUN_START_COMMAND = "1"
|
||||
.\init.ps1
|
||||
|
||||
Set-Location backend-api
|
||||
$env:GOTOOLCHAIN = "local"
|
||||
go run ./cmd/migrate up
|
||||
go run ./cmd/api
|
||||
```
|
||||
|
||||
2026-07-25 已在 PKG110、Android 16/API 36、拼多多 8.17.0 上完成 Debug APK
|
||||
@@ -85,6 +94,12 @@ $env:RUN_START_COMMAND = "1"
|
||||
`order_submitted` 始终为 false；日志敏感词、Base64、原始响应和 schema/prompt
|
||||
命中均为 0。该结果不代表真实模型的商品匹配质量。
|
||||
|
||||
同日完成 T-201 后端 smoke：本机迁移执行 `status -> up -> up -> down -> up`，
|
||||
第二次 `up` 应用数为 0；API 真实进程的 `GET /healthz` 返回 `200` 和稳定 JSON，
|
||||
未知路由返回 `404`，错误方法返回 `405`，无默认 CORS，stdout/stderr 均为空。
|
||||
`http.Server.Shutdown` 由集成测试验证在 1 秒预算内结束。当前 Windows 没有可用 WSL
|
||||
发行版，因此 `init.sh` 未实际运行；Windows 标准入口已验证。
|
||||
|
||||
## 维护规则
|
||||
|
||||
发生以下变化时覆盖更新本文：
|
||||
|
||||
@@ -0,0 +1,126 @@
|
||||
---
|
||||
id: T-201
|
||||
title: 生成并收敛 Go-Gin、SQLite 和迁移骨架
|
||||
phase: 2
|
||||
deps:
|
||||
- T-104
|
||||
status: DONE
|
||||
created: 2026-07-25
|
||||
context_ref: 84f2da3cf74a17c9a1909faf668f16f5fc4e5afa
|
||||
work_branch: main
|
||||
write_paths:
|
||||
- backend-api/**
|
||||
- init.ps1
|
||||
- init.sh
|
||||
- README.md
|
||||
- docs/00-ai-start-here.md
|
||||
- docs/03-tech-stack.md
|
||||
- docs/04-architecture.md
|
||||
- docs/05-coding-rules.md
|
||||
- docs/api.md
|
||||
- docs/current-state.md
|
||||
- docs/tasks/T-201.md
|
||||
- progress.md
|
||||
---
|
||||
|
||||
## 问题 / 背景
|
||||
|
||||
Phase 1 已证明 Android 能从私有任务完成结构化需求提取、拼多多有界搜索、最多 5 个
|
||||
候选评估并停在人工确认点。Phase 2 需要统一后端承载后续的管理 Web、手动领取、租约
|
||||
和结果回传，但仓库当前没有 Go module、HTTP 服务、SQLite 生命周期或迁移入口。
|
||||
|
||||
## 关联需求与交互
|
||||
|
||||
- 功能：F-001、F-002、F-003、F-007 的共享后端基础，不在本任务实现业务接口。
|
||||
- 用户故事：US-001、US-002、US-003、US-007 的前置基础设施。
|
||||
- 交互：不适用；T-202 才生成并确认 P0 Web/App 原型。
|
||||
- 架构/API：`docs/03-tech-stack.md` 后端版本与骨架选择、`docs/04-architecture.md`
|
||||
Backend API 分层、`docs/api.md` 通用 HTTP 约定。
|
||||
|
||||
## 方案
|
||||
|
||||
1. 固定 Go Blueprint v0.10.11，在仓库外临时目录生成最小 Gin + SQLite 项目作为
|
||||
一次性参考，不直接保留演示业务和生成器默认配置。
|
||||
2. 建立 `cmd/api` 和 `cmd/migrate` 两个入口；应用入口只负责装配、信号处理和优雅
|
||||
关闭，迁移入口显式执行版本化 SQL。
|
||||
3. 使用 Go 1.23.0、Gin 1.11.0、`database/sql`、`mattn/go-sqlite3` 和
|
||||
Goose v3.26.0；所有验证设置 `GOTOOLCHAIN=local`。
|
||||
4. 配置、SQLite、迁移和 Gin transport 分包；关闭默认 CORS，不读取或提交 `.env`，
|
||||
默认只监听本机回环地址，健康检查失败不得终止进程或泄露内部错误。
|
||||
5. SQLite 创建父目录、启用 foreign keys、busy timeout 和 WAL，限制单进程写连接，
|
||||
并由调用方显式关闭数据库。
|
||||
6. 单元/集成测试覆盖配置边界、健康检查成功/失败、SQLite pragma、迁移 up/down 和
|
||||
HTTP 路由；根初始化脚本纳入后端测试与构建。
|
||||
|
||||
## 验收要点
|
||||
|
||||
- [x] `go.mod` 精确声明 Go 1.23.0、Gin 1.11.0 和固定依赖版本。
|
||||
- [x] `GOTOOLCHAIN=local go test ./...` 和 Windows 后端构建通过。
|
||||
- [x] migration 在临时 SQLite 上可 up/down，运行数据目录被 Git 忽略。
|
||||
- [x] `/healthz` 正常返回稳定 JSON；数据库不可用时返回 503 且进程不退出。
|
||||
- [x] HTTP Server 具有读头、读、写、空闲和优雅关闭 timeout。
|
||||
- [x] 没有包级数据库单例、隐式 `.env`、默认 CORS、演示业务或明文凭证。
|
||||
- [x] 根 `init.ps1`/`init.sh` 同时验证 Android 和后端。
|
||||
- [x] 启动 smoke、迁移、测试、构建和敏感信息检查均有可复现证据。
|
||||
|
||||
## 边界
|
||||
|
||||
- 不实现任务创建、列表、鉴权、claim、租约、事件或资产 API。
|
||||
- 不实现管理 Web 页面或 Android HTTP TaskSource。
|
||||
- 不引入 ORM、SPA、Redis、消息队列、WebSocket、Docker 或自动下单逻辑。
|
||||
- 不提交 SQLite 数据文件、`.env`、密钥、私有任务或生成器临时目录。
|
||||
|
||||
## 执行记录
|
||||
|
||||
### 2026-07-25：任务开始
|
||||
|
||||
- 基于 T-104 提交 `84f2da3` 开始。
|
||||
- 本机已核实 Go 1.23.0、CGO 开启、GCC 可用，且 Go Blueprint 可执行文件存在。
|
||||
- 先完成骨架生成审计和依赖版本固定，再写入正式代码。
|
||||
|
||||
### 2026-07-25：骨架审计与实现
|
||||
|
||||
- 本机 Go Blueprint 精确版本为 v0.10.11；在仓库外临时目录执行文档生成命令，
|
||||
文件已完整生成，但 CLI 在非交互 PowerShell 恢复终端时返回错误码。
|
||||
- 生成树当前解析为 Go 1.25.0、Gin 1.12.0，并含默认 CORS、`.env` autoload、
|
||||
包级数据库单例、`log.Fatal` 健康检查和 Hello World；正式实现未复制这些行为。
|
||||
- 正式 `go.mod` 固定 Go 1.23.0、Gin 1.11.0、go-sqlite3 1.14.48 和 Goose 3.26.0；
|
||||
v3.27.x 因要求 Go 1.25 未采用。
|
||||
- 建立 `cmd/api`、`cmd/migrate`、`internal/config`、SQLite、migration 和
|
||||
`transport/httpapi`；没有提前创建空的 domain/usecase/repository/web 包。
|
||||
- SQLite 强制 foreign keys、5 秒 busy timeout、WAL、immediate transaction 和
|
||||
单连接；Gin 默认只监听回环地址，无 CORS/默认 logger，请求异常只记录通用事件。
|
||||
- 公共错误固定 `request_id`、`retryable=false` 和空 `details`；优雅关闭超时后强制
|
||||
关闭 listener 并有界等待，避免数据库关闭后继续接受请求。
|
||||
|
||||
### 2026-07-25：自动化验证
|
||||
|
||||
- 执行 `$env:GOTOOLCHAIN="local"; go test -count=1 ./...`：25 个测试通过，0 失败；
|
||||
配置、SQLite、迁移、健康 200/503、安全 recovery、错误合约、404/405、正常关闭和
|
||||
超时强制关闭均有覆盖。
|
||||
- 执行 `go test -race -count=1 ./...`、`go vet ./...`、`gofmt -l`、API/migration
|
||||
Windows 构建，全部通过；二进制使用本地 Go 1.23.0 工具链。
|
||||
- 根目录 `$env:RUN_START_COMMAND="0"; .\init.ps1` 成功完成 Android
|
||||
`test assembleDebug`、后端 test/vet/gofmt 和双入口构建。
|
||||
- 默认 Debug APK 的 `assets/probe-fixtures/` 条目为 0；`bin/`、`var/`、数据库、
|
||||
WAL/SHM、日志和 `.env` 均被 Git 忽略。
|
||||
|
||||
### 2026-07-25：迁移与 HTTP smoke
|
||||
|
||||
- 独立临时 SQLite 执行 `status -> up -> up -> down -> up -> status`：
|
||||
状态按 pending/applied 切换，第二次 `up` 返回 `applied=0`。
|
||||
- API Windows 进程使用动态回环端口启动；`GET /healthz` 返回
|
||||
`{"status":"ok"}`，Cache-Control 为 no-store，未知路由为 404，POST health 为
|
||||
405，公共错误合约完整，未返回 CORS header，stdout/stderr 字节数均为 0。
|
||||
- smoke 结束后精确检查 API 测试进程数量为 0。健康 503 和不终止行为由 Fake DB
|
||||
集成测试验证；不需要破坏真实运行时数据库来制造故障。
|
||||
|
||||
### 未验证项
|
||||
|
||||
- 当前 Windows 的 `bash.exe` 指向未配置发行版的 WSL，`init.sh` 未实际运行；脚本
|
||||
已与 Windows 入口同步 Go/CGO/test/vet/gofmt/build 逻辑，需在 Linux/WSL 复核。
|
||||
- `/healthz` 当前只表示进程与数据库连接可用，不检查 migration 是否最新；增加
|
||||
readiness/migration 门禁应在首个业务表落地前完成。
|
||||
- 默认数据库路径相对启动工作目录；本地命令必须从 `backend-api/` 运行，部署时应
|
||||
显式配置绝对 `CMROUBAO_DATABASE_PATH`。
|
||||
- 本任务没有业务表、鉴权、管理页面或任务 API；分别属于 T-202 至 T-205。
|
||||
Reference in New Issue
Block a user