# 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 中的任何一步
