docs(02-01): 完成 PERM+FIN+POLL 9项修复计划 PERM-01/02 FIN-01/02/03 POLL-01/02/03/04
This commit is contained in:
182
.planning/codebase/TESTING.md
Normal file
182
.planning/codebase/TESTING.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# Testing Patterns
|
||||
|
||||
**Analysis Date:** 2026-03-27
|
||||
|
||||
## Test Framework
|
||||
|
||||
**Runner:**
|
||||
- 当前仓库未检测到有效的 Go 自动化测试文件：`glob("**/*_test.go")` 返回空，`glob("tests/**")` 返回空。
|
||||
- 因此，仓库当前状态下不存在可执行的项目内单元测试、集成测试或 E2E 测试代码。
|
||||
|
||||
**Assertion Library:**
|
||||
- 未检测到；因为当前仓库没有 `*_test.go` 文件。
|
||||
|
||||
**Configured / Documented commands:**
|
||||
```bash
|
||||
go test ./... # `README.md` 文档命令；当前仓库没有测试文件
|
||||
go test -cover ./... # `README.md` 文档命令；覆盖率描述与仓库现状不符
|
||||
go test -v ./... # `Makefile` 的 `test` 目标与 `README.md` 一致
|
||||
go test ./pkg/... # `README.md` 文档命令；当前没有对应测试文件
|
||||
go test ./tests/integration/... # `README.md` 文档命令；当前仓库不存在 `tests/` 目录内容
|
||||
go test -v ./internal/middleware -run TestKeyAuth # `README.md` 文档命令；当前未检测到对应测试
|
||||
```
|
||||
|
||||
## Policy Reality
|
||||
|
||||
**Current project rule (authoritative):**
|
||||
- `AGENTS.md` 明确规定：本项目不使用任何形式的自动化测试代码。
|
||||
- `AGENTS.md` 明确禁止单元测试、集成测试、验收测试、流程测试、E2E 测试，以及创建 `*_test.go` 文件；唯一例外是用户明确要求“请写测试”。
|
||||
|
||||
**Repository reality:**
|
||||
- 当前仓库与该规则一致：未发现任何 `*_test.go` 文件，也未发现 `tests/` 目录内容。
|
||||
|
||||
**Stale documentation conflicts:**
|
||||
- `README.md` 仍包含完整“测试”章节，列出 `go test ./...`、覆盖率、集成测试、`tests/integration/`、以及 `docs/testing/test-connection-guide.md` 的说明。
|
||||
- `README.md` 的项目结构段仍展示 `tests/integration/auth_test.go`、`tests/integration/ratelimit_test.go`。
|
||||
- `README.md` 的 “Speckit / 宪章” 段仍写有 “70%+ 测试覆盖率，核心业务 90%+”。
|
||||
- 这些内容与 `AGENTS.md` 的现行禁令、以及仓库中真实文件状态冲突。后续执行应以 `AGENTS.md` + 实际文件现状为准。
|
||||
|
||||
## Verification Approach Actually Used
|
||||
|
||||
**Primary approach:**
|
||||
- 人工验证 + 脚本检查 + 文档生成检查 + 生产日志/监控。
|
||||
|
||||
**Evidence from policy:**
|
||||
- `AGENTS.md` 将替代方案明确写为：
|
||||
- 使用 PostgreSQL MCP 工具手动验证数据
|
||||
- 使用 Postman/curl 手动测试 API
|
||||
- 依赖生产环境日志和监控发现问题
|
||||
|
||||
**Repository scripts that support this model:**
|
||||
- `scripts/check-service-errors.sh`：静态扫描 Service 层错误处理规则。
|
||||
- `scripts/check-comment-paths.sh`：静态扫描 Handler 注释中的 API 路径是否过时。
|
||||
- `scripts/check-all.sh`：聚合上述脚本。
|
||||
- `scripts/verify_migration/main.go`：直接连接数据库查询表和字段，验证迁移结果；这是一种手工校验辅助程序，不是自动测试框架。
|
||||
- `cmd/gendocs/main.go` / `make docs`：通过重新生成 OpenAPI 文档来验证路由注册和文档接线是否完整。
|
||||
|
||||
## Test File Organization
|
||||
|
||||
**Location:**
|
||||
- 当前无自动化测试文件。
|
||||
|
||||
**Naming:**
|
||||
- 按 Go 常规应为 `*_test.go`，但本项目现行规则禁止新增，除非用户明确要求。
|
||||
|
||||
**Structure:**
|
||||
```text
|
||||
自动化测试目录：未检测到
|
||||
README 中声明的 `tests/integration/`：当前不存在实际文件
|
||||
```
|
||||
|
||||
## Manual Validation Patterns
|
||||
|
||||
**API / behavior validation:**
|
||||
- 使用 Postman、curl 或 Swagger/OpenAPI 文档进行接口人工验证，依据见 `AGENTS.md` 与 `docs/api-documentation-guide.md`。
|
||||
- 生成 OpenAPI 文档后检查路径是否出现：`go run cmd/gendocs/main.go`，再检查 `docs/admin-openapi.yaml`，依据见 `docs/api-documentation-guide.md`。
|
||||
|
||||
**Database validation:**
|
||||
- 涉及数据正确性时，使用 PostgreSQL MCP 工具做手动查询验证，依据见 `AGENTS.md` 的 `db-validation` 说明。
|
||||
- 涉及迁移结果时，可运行 `go run scripts/verify_migration/main.go` 检查表与字段；该脚本读取真实数据库 schema，不产出测试报告。
|
||||
|
||||
**Convention validation:**
|
||||
- 改动 Service 层错误处理后运行 `bash scripts/check-service-errors.sh`。
|
||||
- 改动 Handler 注释或路由后运行 `bash scripts/check-comment-paths.sh`。
|
||||
- 需要一次性检查时运行 `bash scripts/check-all.sh`。
|
||||
|
||||
**Documentation / OpenAPI validation:**
|
||||
- 新增 Handler 后必须同步更新 `cmd/api/docs.go` 与 `cmd/gendocs/main.go`，然后重新生成文档并检查目标路径，依据见 `docs/api-documentation-guide.md`。
|
||||
|
||||
## Mocking
|
||||
|
||||
**Framework:**
|
||||
- Not applicable；当前没有自动化测试代码。
|
||||
|
||||
**Patterns:**
|
||||
```text
|
||||
未检测到 mock 框架、测试替身、fixture helper 或 testutil 包的实际使用。
|
||||
```
|
||||
|
||||
**What to Mock:**
|
||||
- 当前仓库没有现行自动化测试实践可供复用。
|
||||
|
||||
**What NOT to Mock:**
|
||||
- 当前仓库没有现行自动化测试实践可供复用。
|
||||
|
||||
## Fixtures and Factories
|
||||
|
||||
**Test Data:**
|
||||
```text
|
||||
未检测到 fixture/factory 测试数据目录或 `_test.go` 中的构造模式。
|
||||
```
|
||||
|
||||
**Reality check:**
|
||||
- `README.md` 仍引用 `docs/testing/test-connection-guide.md` 和 `testutils.NewTestTransaction(...)` 示例，但当前仓库没有对应测试文件作为实际落点。
|
||||
|
||||
## Coverage
|
||||
|
||||
**Requirements:**
|
||||
- 当前现行项目规则不要求覆盖率，且原则上禁止自动化测试，依据见 `AGENTS.md`。
|
||||
|
||||
**Conflict to document clearly:**
|
||||
- `README.md` 和其中引用的 Speckit 宪章仍声称需要覆盖率目标；这与 `AGENTS.md` 的测试禁令冲突，且与当前“零测试文件”现状不符。
|
||||
|
||||
**View Coverage:**
|
||||
```bash
|
||||
go test -cover ./... # 仅为 README 中遗留命令，不代表现行流程
|
||||
```
|
||||
|
||||
## Test Types
|
||||
|
||||
**Unit Tests:**
|
||||
- 当前未使用。
|
||||
|
||||
**Integration Tests:**
|
||||
- 当前未使用。
|
||||
- `README.md` 里提到的 `tests/integration/` 是过期描述，不是当前仓库事实。
|
||||
|
||||
**E2E Tests:**
|
||||
- 当前未使用。
|
||||
|
||||
## CI Reality
|
||||
|
||||
**Actual workflow present:**
|
||||
- `.gitea/workflows/deploy.yaml` 只有检出、Docker 构建、推送镜像、部署到测试环境的步骤。
|
||||
|
||||
**What is not in CI:**
|
||||
- 未发现 `go test`。
|
||||
- 未发现 `bash scripts/check-all.sh`。
|
||||
- 未发现 `bash scripts/check-service-errors.sh`。
|
||||
- 未发现 `bash scripts/check-comment-paths.sh`。
|
||||
- 未发现独立的质量门或覆盖率上传步骤。
|
||||
|
||||
**Conflict to document clearly:**
|
||||
- `README.md` 写着“这些检查会在 CI/CD 流程中自动执行”，但 `.gitea/workflows/deploy.yaml` 中没有相应步骤。当前 CI 现实是“构建/部署优先，无显式质量校验门”。
|
||||
|
||||
## Common Verification Commands
|
||||
|
||||
```bash
|
||||
bash scripts/check-service-errors.sh # 校验 Service 错误处理规则
|
||||
bash scripts/check-comment-paths.sh # 校验 Handler 注释路径是否过时
|
||||
bash scripts/check-all.sh # 运行当前已存在的全部静态脚本检查
|
||||
go run cmd/gendocs/main.go # 重新生成 OpenAPI 文档，验证路由接线
|
||||
make docs # 等价于生成 OpenAPI 文档
|
||||
go run scripts/verify_migration/main.go # 人工验证数据库迁移结果
|
||||
```
|
||||
|
||||
## Current Gaps and Caveats
|
||||
|
||||
- `Makefile` 仍保留 `test:` 目标并执行 `go test -v ./...`，这属于历史遗留入口，不应被误解为现行团队要求。
|
||||
- `README.md` 的测试章节、目录结构和覆盖率目标明显滞后于当前 `AGENTS.md` 规则。
|
||||
- `scripts/check-service-errors.sh` 虽然存在，但当前仓库 `internal/service/polling/alert_service.go` 仍有 `fmt.Errorf(...)` 违规点，说明现有脚本检查并未通过 CI 强制执行。
|
||||
- `scripts/verify_migration/main.go` 内含直接数据库连接字符串，反映的是临时人工验证脚本，而不是可复用、无环境依赖的测试体系。
|
||||
|
||||
## Prescriptive Summary
|
||||
|
||||
- 讨论“测试”时，先区分三件事：`README.md` 的历史文档、`AGENTS.md` 的现行规则、仓库当前真实文件状态。
|
||||
- 在当前仓库中，默认不要新增 `*_test.go`；只有用户明确要求时才编写测试代码。
|
||||
- 日常验证优先使用：静态检查脚本、OpenAPI 文档再生成、数据库手查、Postman/curl、人肉回归。
|
||||
- 判断 CI 是否有质量门时，以 `.gitea/workflows/deploy.yaml` 为准，而不是 `README.md` 的说明。
|
||||
|
||||
---
|
||||
|
||||
*Testing analysis: 2026-03-27*
|
||||
Reference in New Issue
Block a user