61 lines
3.1 KiB
Markdown
61 lines
3.1 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. **前端门禁** — 任何触及 `deploy/tksea-portal/`、`deploy/*portal*`、`/portal-admin-api/` 文案或前端验收文档的改动，必须至少执行：
|
||
- `bash ./scripts/test/test_tksea_portal_assets.sh`
|
||
- `bash ./scripts/test/verify_frontend_smoke.sh`
|
||
- 若改动 `providers.html` 页面内显式动作，还必须执行 `bash ./scripts/acceptance/verify_provider_admin_actions.sh` 或给出不可执行原因。
|
||
3. **代码 review** — 加载 `go-reviewer` skill，对新写/修改的全部 Go 文件做系统审查。
|
||
4. **测试覆盖** — `go test -cover ./internal/...` 核心包（provision、access、pack）覆盖率 >= 70%。未达标则补用例。
|
||
5. **静态分析** — `go vet ./...` 零警告。`gofmt -l .` 显示无未格式化文件。
|
||
6. **集成验证** — `go test ./tests/integration/... -count=1` 必须通过。
|
||
7. **板同步** — 更新 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 中的任何一步
|