57 lines
2.7 KiB
Markdown
57 lines
2.7 KiB
Markdown
|
# sub2api-cn-relay-manager — Agent Guidelines
|
|||
|
|
|
|||
|
|
## 项目关键信息
|
|||
|
|
- Go 1.22.2, 纯 Go (modernc.org/sqlite, 无 CGO)
|
|||
|
|
- 零侵入宿主：不修改 sub2api 源码，不写宿主数据库
|
|||
|
|
- 所有 schema 变更通过 `internal/store/sqlite/` 下的 repo + integration test 验证
|
|||
|
|
- docs/ 下有 PRD.md、TDD_PLAN.md、EXECUTION_BOARD.md、solution 文档
|
|||
|
|
|
|||
|
|
## 质量门禁（每个模块完成前必须执行）
|
|||
|
|
|
|||
|
|
1. **设计对齐** — 重新读取 PRD.md、TDD_PLAN.md、EXECUTION_BOARD.md、docs/plans/ 下的规划设计文档，逐条确认实现已覆盖设计目标。发现漂移先修正，不维持虚假 COMPLETED。
|
|||
|
|
2. **代码 review** — 加载 `go-reviewer` skill，对新写/修改的全部 Go 文件做系统审查。
|
|||
|
|
3. **测试覆盖** — `go test -cover ./internal/...` 核心包（provision、access、pack）覆盖率 >= 70%。未达标则补用例。
|
|||
|
|
4. **静态分析** — `go vet ./...` 零警告。`gofmt -l .` 显示无未格式化文件。
|
|||
|
|
5. **集成验证** — `go test ./tests/integration/... -count=1` 必须通过。
|
|||
|
|
6. **板同步** — 更新 EXECUTION_BOARD.md，反映真实完成状态。
|
|||
|
|
|
|||
|
|
## Go 编码规范
|
|||
|
|
|
|||
|
|
### 包结构
|
|||
|
|
```
|
|||
|
|
internal/
|
|||
|
|
access/ — 访问闭环（订阅分配、探测、自服务检查）
|
|||
|
|
app/ — HTTP 控制面（bootstrap, server, API handlers）
|
|||
|
|
host/sub2api/ — 宿主适配器
|
|||
|
|
pack/ — pack 装载与校验
|
|||
|
|
provision/ — 导入编排（import, preview, reconcile, rollback）
|
|||
|
|
store/sqlite/ — SQLite 数据访问层（repo 模式）
|
|||
|
|
cmd/
|
|||
|
|
cli/ — CLI 入口
|
|||
|
|
server/ — HTTP server 入口
|
|||
|
|
tests/integration/ — 集成测试套件
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 代码风格
|
|||
|
|
- 标准 Go：4-space tabs, 花括号同行, 单 class/struct 文件
|
|||
|
|
- 包名小写，与目录名一致
|
|||
|
|
- 错误处理用 `fmt.Errorf("context: %w", err)` 包裹
|
|||
|
|
- 常量分组在文件顶部，`const ( Name = "value" )`
|
|||
|
|
- Repository 模式：`type XRepo struct { db execQuerier }` + `newXRepo(db)`
|
|||
|
|
- Context 作为第一个参数传入所有 DB/SQL 操作
|
|||
|
|
- 接口定义在使用方，不在实现方
|
|||
|
|
- 测试用 fake/mock adapter 而非真实 HTTP
|
|||
|
|
|
|||
|
|
### 测试规范
|
|||
|
|
- 文件名 `*_test.go` 与源码同包
|
|||
|
|
- 方法名 `TestXxxFlow` / `TestXxxWhenY` 格式
|
|||
|
|
- 优先使用 FakeHostAdapter（已在 provision 包中定义）而不是 mock 框架
|
|||
|
|
- 集成测试放在 `tests/integration/`，使用真实 SQLite 内存库
|
|||
|
|
- 测试函数必须 `t.Parallel()` 安全（使用独立 SQLite 连接）
|
|||
|
|
|
|||
|
|
## 重要约束
|
|||
|
|
- 不要运行 `go get` / `go mod tidy` — 源码写完后告诉用户手动安装依赖
|
|||
|
|
- 不改动 go.mod 中的依赖版本
|
|||
|
|
- 所有功能必须配套测试，集成测试优先
|
|||
|
|
- 不允许跳过 quality gate 中的任何一步
|