# 蚊子项目智能体执行规则

## 1. 项目事实（必须遵守）
- 后端：Spring Boot 3 + Java 17 + Maven。
- 目标数据库方言：PostgreSQL（统一标准，不再按 MySQL 语义新增迁移）。
- 数据库变更：仅通过 Flyway 脚本（`src/main/resources/db/migration`）。
- Flyway 历史迁移修复策略：仅限“未发布环境”允许直接改历史迁移；已发布环境必须新增补丁迁移。

## 2. 仓库结构与整洁规则
- 根目录只保留入口文件与工程配置，阶段性报告统一放到 `docs/reports/<category>/`。
- 运行日志统一在 `logs/`，历史日志归档到 `logs/archive/<tag>/`。
- 禁止测试报告/截图回流到仓库根目录（通过 `.gitignore` + CI 门禁控制）。
- 构建与测试产物（如 `target/`、`frontend/*/dist`、`frontend/e2e/*results*`）默认视为可清理对象。

## 3. CI 与验证规则
- 在宣称“完成/通过”前，至少执行项目已有验证脚本或等效命令并记录结果。
- 当前核心链路：
  - `./scripts/ci/logs-health-check.sh`（非阻断健康检查）
  - `./scripts/ci/clean-artifacts.sh --include-build-outputs --fail-on-found`（阻断污染回流）
  - `./scripts/ci/backend-verify.sh`
  - `./scripts/ci/assert-migration-not-skipped.sh`
- 归档维护命令：
  - `npm run logs:archive:check`
  - `npm run logs:archive:apply`
  - `npm run logs:archive:index`

## 4. 发布与分支策略（Gitea）
- 优先推送到开发分支（如 `task-1-exception-handling`）并走 PR 合并。
- `main` 若受保护，禁止强推覆盖；需要仓库管理员临时放开保护或通过 PR 合并。
- 用户要求“本地覆盖远端”时，先明确目标分支与保护策略，再执行提交/推送。

## 5. 开发与修改原则
- 先读后改，最小化变更面，避免无关重构。
- 新增行为必须同步补充测试或最小验证步骤。
- 文档与代码必须同步更新，尤其是脚本路径、报告路径、CI 命令。
- 默认优先“归档”而非“删除”；删除动作需用户明确确认。

## 6. 常用命令
- 全量验证：`./scripts/ci/backend-verify.sh`
- 工作区污染检查：`npm run clean:workspace:check`
- 工作区归档清理：`npm run clean:workspace:apply`
- 日志健康检查：`npm run logs:health:check`
- 日志归档索引刷新：`npm run logs:archive:index`