127 lines
6.5 KiB
Markdown
127 lines
6.5 KiB
Markdown
|
---
|
|||
|
|
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。
|