wenzi/AGENTS.md

蚊子项目智能体执行规则

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