Loop Polish

启动项目 → 完整验证 → 评分 → 自动修复 → 循环直至完美 → 生成报告。未达完美，绝不发布。

1. 核心流程

步骤 1 启动 → 步骤 2 验证 → 步骤 3 评分 → 步骤 4 修复 → 步骤 5 回归测试 → 步骤 6 生成报告
                ↑                                                     │
                └──────────── 若未达标则循环 ───────────────────────────┘

预检模式：步骤 1 → 步骤 2 → 步骤 3 → 输出问题 → 停止（不修复，不循环）

2. 配置文件 .loop-polish.json（可选，缺失时使用默认值）

{
  "mode": "full",
  "max_rounds": 10,
  "target_score": 100,
  "scope": "all",
  "auto_fix": { "enabled": true, "strategy": "conservative", "max_per_round": 3 },
  "browser": { "headless": true },
  "report": { "format": "markdown", "output_dir": "./polish-reports/" },
  "timeout_minutes": 120
}

3. 执行步骤

步骤 1：启动项目

0. 检测项目结构：
   - 后端：搜索 pom.xml/build.gradle/package.json/go.mod/requirements.txt
   - 前端：搜索 package.json + vite.config/vue.config/next.config
   - 纯前端/纯后端：跳过不存在的部分，仅启动存在的部分

1. Git 安全检查（仅在 full 模式下）：
   - 检查工作区状态：git status --porcelain，若有未提交更改则暂存
   - 创建修复分支：git checkout -b loop-polish/round-{timestamp}
   - 记录原始分支名称，用于步骤 6 切换回

2. 清理旧进程（跨平台）：
   - 检查端口：后端 8080/3000/5000，前端 5173/3000
   - Windows：netstat -ano | findstr :port → taskkill /PID {pid} /F
   - Linux/Mac：lsof -ti :port | xargs kill -9 2>/dev/null

3. 启动后端（若项目包含后端，按类型）：
   Java：mvn clean package -DskipTests -q ; java -jar target/*.jar
   Node：npm install ; node server.js
   Python：pip install -r requirements.txt ; python app.py
   Go：go build ; ./app
   启动后轮询 /health 或 /actuator/health 或根路径 GET 请求，最长 60 秒
   若均不可达，通过 netstat/lsof 确认端口是否监听

4. 启动前端（若项目包含前端）：
   npm install（若无 node_modules）；npm run dev
   轮询开发服务器状态，最长 60 秒

5. 失败处理：
   → 捕获错误日志，尝试修复（缺失依赖/端口冲突），重试 2 次 → 仍失败则中止

步骤 2：完整验证

作用域控制（根据 scope 配置）：
  scope=all：执行 2.1 + 2.2 + 2.3
  scope=backend：执行 2.1 + 2.3
  scope=frontend：执行 2.2
  scope=api：执行 2.1
  纯前端项目（无后端代码）：自动跳过 2.1 和 2.3
  纯后端项目（无前端代码）：自动跳过 2.2

2.1 后端 API 验证

1. 扫描 API 接口：
   Java：grep @RestController 定位 Controller 文件 → grep @(Get|Post|Put|Delete)Mapping
   Node：grep router\.(get|post|put|delete)|app\.(get|post|put|delete)
   Python：grep @(app|router)\.(route|get|post|put|delete)
   提取：HTTP 方法、路径、参数名及类型

2. 解析请求体参数（POST/PUT）：
   @RequestBody 或 body 参数指向 DTO 类 → 读取 DTO 源码 → 提取字段名和类型
   无 DTO → 从 @RequestParam / @PathVariable 方法签名中提取

3. 路径参数处理（如 GET /users/{id}）：
   调用模块的 POST 接口创建记录 → 获取返回的 id → 用于 GET/PUT/DELETE 的路径参数
   若 POST 不可用，尝试调用 GET 列表接口 → 取第一个条目的 id
   若 POST 请求体依赖其他资源（如创建订单需用户 ID），先尝试创建依赖项，失败则跳过该接口

4. 认证处理：
   扫描含 login/auth/signin 关键字的接口 → 自动调用获取 Token
   后续请求自动携带 Authorization: Bearer {token}
   若未找到登录接口，则跳过认证

5. 验证每个接口（每接口最多重试 2 次）：
   正常情况：有效参数，验证返回 200/201，响应为合法 JSON，关键字段非空
   边界情况：空字符串、0、负数、极长字符串
   缺失必填项：移除必填字段，验证返回 400
   权限测试：无 Token → 401，普通用户 Token 访问管理员接口 → 403

6. 验证失败时收集诊断信息：
   - 后端日志最后 50 行（tail -50 或 Get-Content -Tail 50）
   - 完整响应体 + 请求参数 + 请求头

2.2 前端浏览器验证

### 1. 前端路由扫描
- Vue：使用 `grep "path:"` 定位路由文件 → 提取所有 `path` 值
- React：使用 `grep "path:"` 或 `path:` 定位路由定义 → 提取所有路径
- 生成路由列表

### 2. 表单扫描（从源码中提取，避免盲目操作）
- 使用 `grep "<el-form|<a-form|<t-form|<v-form|<form|<Form"` 查找各页面中的表单组件
- 记录每个表单所在的页面，作为浏览器验证的交互目标

### 3. 调用 Skill: playwright-master，按路由列表逐页验证
- 页面加载：无白屏、无 `console.error`
- 表单交互（仅对第2步中扫描到的表单）：填写 → 验证 → 提交
- 列表操作（如存在）：分页、搜索、删除
- 模态框/抽屉（如存在）：打开 → 操作 → 关闭
- 导航操作：菜单点击、标签切换
- 若页面无表单，跳过表单验证

### 4. 验证失败时处理
- 截图保存
- 收集 `console.error` 日志
- 记录失败的网络请求日志

---

#### 2.3 数据库状态验证

对于每次写操作（POST/PUT/DELETE）：

1. 获取数据库连接信息（按优先级搜索）：
   - `application.yml` / `application.properties`：`spring.datasource.url`
   - `.env` 文件：`DATABASE_URL`，或 `DB_HOST` + `DB_PORT` + `DB_NAME` + `DB_USER` + `DB_PASSWORD`
   - `config.json` / `config.js`：搜索 `db`、`database`、`mysql`、`postgres` 等关键词
   - 若均未找到，跳过数据库验证并输出提示

2. 检测数据库类型（根据连接字符串或驱动）：
   - MySQL：`jdbc:mysql://` 或 `mysql://`
   - PostgreSQL：`jdbc:postgresql://` 或 `postgresql://`
   - SQLite：`jdbc:sqlite:` 或 `sqlite:`
   - 根据类型选择对应命令行工具：`mysql -e` / `psql -c` / `sqlite3`

3. 数据验证方式：
   - POST 创建：直接查询，确认记录已写入且字段值正确
   - PUT 更新：直接查询，确认字段已更新
   - DELETE：直接查询，确认记录已删除或软删除标志设置正确

---

### 第三步：评分

**统计规则**：
- 总功能得分 = API 接口数量 + 前端页面数量
- 每个 API 接口覆盖两个维度：功能完整性（能否正常调用）、错误处理（边界/权限拒绝是否正确）
- 每个前端页面覆盖两个维度：用户体验（能否正常操作）、数据正确性（显示数据与后端一致）
- 性能要求：API 响应时间 > 2 秒，或页面加载时间 > 3 秒，扣分

**评分公式**：
- 单维度得分 = 100 × （该维度通过项数 / 该维度总项数）
- 最终得分 = 完整性×0.40 + 正确性×0.25 + UX×0.15 + 错误处理×0.10 + 性能×0.10

**扣分规则**：
- 单点失败扣 100 / 总分
- 重试仍失败额外扣 5 分（最多扣 15 分）

**输出格式**：

📊 Round 1: 76.8/100 [Not passed]

Completeness:80% Correctness:72% UX:80% Error:60% Performance:90% | Passed:85/120 Failed:35

---

### 第四步：自动修复

若 `auto_fix.enabled=false` 或 `mode=preflight`：跳过本步骤，直接进入第6步生成报告

1. 修复优先级（P1→P3）：
   - P1：编译/语法错误（缺少导入、类型不匹配、空指针等）
   - P2：逻辑/数据错误（查询逻辑错误、条件错误、前后端不一致）
   - P3：用户体验/性能问题（缺少加载状态、提示信息不友好，仅在激进策略下启用）

2. 策略范围：
   - 保守：P1~P2 | 单文件 | 每轮 ≤ 3 处
   - 中等：P1~P2 | ≤ 2 个文件 | 每轮 ≤ 5 处
   - 激进：P1~P3 | 跨模块 | 每轮 ≤ 10 处

3. 修复流程：
   a. 读取失败案例诊断日志 + 截图 → 定位根因 → 查看源码
   b. 生成修复方案（优先最小改动）
   c. 对高风险修改（如 Schema 变更、认证逻辑、删除 >10 行代码）前询问用户
   d. 修复前保存原始代码片段（用于失败时精准回滚）
   e. 使用 Edit 工具应用修复 → 记录差异
   f. 本地回归测试（仅测试该功能点，不执行全量运行）
   g. 通过 → 标记为已修复；失败 → 使用 Edit 恢复原代码，标记为“无法修复”

4. 退出策略：
   - 同一问题连续两次失败 → 跳过
   - 连续三轮无分数提升 → 输出“auto-fix limit reached”，停止循环
   - 已处于保守模式且连续三轮无改进 → 立即停止

**输出格式**：

🔧 Round 1 fix (conservative):

✅ [P1] UserController.java:45 - missing @Valid

✅ [P1] order.ts:23 - path typo

⚠️ Skipped 2 need human confirmation | Fixed:2 Remaining:31

---

### 第五步：回归验证

1. 仅重测上一轮中失败的用例
2. 使用 `git diff --name-only` 检测变更文件 → 仅重测受影响模块
3. 跳过已通过和未变更的模块
4. 重新执行第2~3步 → 对比当前轮次与上一轮得分

**输出格式**：

🔄 Round 2 regression: Retested 35 → Passed 31 Failed 4 | Score: 92.50 (+15.70 ↑)

---

### 第六步：终止、报告生成与清理

**终止条件（满足任一即终止）**：
1. 得分 ≥ 目标得分 → ✅ 通过
2. 轮次 ≥ 最大轮次 → ⏰ 达到最大轮次
3. 连续三轮得分变化 < 1 → 📉 得分停滞
4. 总耗时 > 超时时间 → ⏱️ 超时
5. 用户中断

**报告生成（输出至 `report.output_dir`）**：

Loop Polish 报告

摘要

最终得分 | 轮次 | 总耗时 | 通过 | 修复 | 剩余

得分趋势

修复详情

每轮修复列表 + 差异 + 结果

剩余问题与建议

未修复项 + 原因 + 建议（如：添加单元测试、增加校验、增加日志等）

**清理操作**：
- 停止前后端服务（终止启动的进程）
- `git checkout` 回退至原始分支
- `git stash pop`（若第1步中已暂存）
- 输出报告路径

---

## 4. 中断恢复

自动保存 `.loop-polish-state.json` 文件于中断时：

{

"round": 2,

"step": "verify",

"passed": ["api:GET:/users", "ui:login"],

"failed": ["api:PUT:/orders"],

"fixed": ["UserController.java:45"],

"unfixable": [],

"scores": [

{"round": 1, "score": 76.8, "fixes": 2}

]

}

恢复时读取状态文件 → 跳过已完成步骤 → 从断点处继续。删除该文件可重置状态。

## 5. 使用示例

Run loop polish # 完整修复

Loop polish preflight: API only # 快速扫描

Loop polish: 5 rounds, 95 score, aggressive, HTML report # 自定义配置

Run loop polish on user module and order module, target 100 # 指定模块修复

---

## 6. 前置条件

- 项目可构建且可运行
- `npx playwright install chromium`（首次运行时若缺失会自动安装）
- 数据库可连接并已初始化数据

---

## 7. 注意事项

- 所有修复操作均在独立的 Git 分支中进行，主分支保持安全
- 首次使用建议设置 `strategy=conservative`，熟悉后可逐步提高
- 预检模式无风险，适合在 CI 环境中使用
- 报告文件保存至 `polish-reports/` 目录
- 完成后自动切换回原分支并清理临时文件