# 前端/后端代码自动扫描功能

## 功能说明

在生成 `03-待确认问题清单.md` 之前，`sdd-flow-kit` 现在会**自动扫描**项目的前端基础设施和后端代码（如果有 skill 配置），为 AI 提供明确的代码基线证据。

## 自动扫描内容

### 1. 前端基础设施扫描

自动扫描并生成 `source/frontend-infrastructure-baseline.md`，包含：

- **全局组件清单**：所有 `src/components/` 下的组件（代码行数、是否有文档）
- **布局配置**：`layout.config.ts` 的位置
- **API 模块结构**：`config/api/modules/` 下的所有模块
- **项目约定**：API 调用规范、目录结构、路由配置规则

**示例输出**：
```markdown
## 1. 全局组件清单

| 组件目录 | 代码行数 | 说明文档 | 相对路径 |
|----------|---------|---------|----------|
| `table` | 2250 | ✅ | `src/components/table` |
| `layout` | - | - | `src/components/layout` |
...

**关键组件说明**：
- **表格**：`src/components/table/index.vue`（2250 行）
  - 功能：列配置、筛选、搜索、分页、批量操作
  - **03 问题清单禁止问**：「用原生 table 还是 n-data-table」（已有封装）
```

### 2. 后端代码扫描（可选）

如果检测到后端路径 skill（如 `adi-operation-api-fe-integration`），自动扫描并生成 `source/backend-code-summary.md`：

- **后端接口清单**：所有 Controller 的 HTTP 方法、路径、文件位置
- **对比指引**：如何在 03 问题清单中引用后端代码

**检测条件**：
- 项目中存在 `.cursor/skills/**/SKILL.md` 或 `.claude/skills/**/SKILL.md`
- skill 文件包含「后端路径」或「后端只读入口」字段
- 后端路径为绝对路径且目录存在

**示例输出**：
```markdown
## 已实现的后端接口

| HTTP 方法 | 完整路径 | Controller | 文件位置 |
|-----------|----------|------------|----------|
| POST | `/api/finance/report/page` | FinanceReportController | `src/main/java/.../FinanceReportController.java` |
...

## 生成 03 待确认清单时的强制要求

✅ **正确示例**：
### 1.1 账期依据枚举不一致
**问题**：后端 `AccountPeriodBasisEnum` 已定义 4 项（NEXT_MONTH_FIRST_DAY_AFTER_DELIVERY_END / PROJECT_END_PLUS_ONE_DAY / SETTLEMENT_DATE / INVOICE_DATE），
但 PRD §账期规则配置 仅描述 2 项。
**代码位置**：`adi-operation-api/src/main/java/cloud/adinsight/finance/enums/AccountPeriodBasisEnum.java`
**需要确认**：以哪个为准？
```

## 使用方法

### 自动使用（无需手动操作）

当你运行 `npx sdd-flow-kit start` 时，扫描会自动执行：

```bash
npx sdd-flow-kit start --product ADI --version 2.3.4 --project-root /path/to/frontend

# 输出示例：
# ✓ 扫描到 25 个组件
# ✓ 找到布局配置: layout.config.ts
# ✓ 找到 14 个 API 模块
# ✓ 检测到后端 skill: adi-operation-api-fe-integration
#   后端路径: /Users/xxx/adi-operation-api
#   扫描到 87 个后端接口
```

### AI 自动注入

在执行 `02-需求分析提示词.md` 时，AI 会自动读取：
1. `source/PRD.md`（必填）
2. `source/frontend-infrastructure-baseline.md`（自动生成）
3. `source/backend-code-summary.md`（如检测到后端 skill）

## 效果对比

### 之前（没有代码扫描）

**03 问题清单会问这些无意义的问题**：
```markdown
### 3.2 列表表格组件基线
**假设**：基于系统技术栈（Vue 3 + Naive UI），推测使用 Naive UI 的 `n-data-table` 组件实现列表。
**推测风险**：PRD 要求"列表字段宽度支持自定义拖拽设置"，但 `n-data-table` 默认不支持列宽拖拽...
**需要确认**：
1. `n-data-table` 是否支持列宽拖拽？还是需要使用第三方库（如 `@antv/s2`）？
```

**代码位置字段模糊**：
```markdown
**代码位置**：需在列表和详情页实现状态修改功能
**代码位置**：未确定
```

### 现在（有代码扫描）

**03 问题清单直接引用已有组件**：
```markdown
### 1.1 列配置抽屉的"与现有样式不同"
**问题**：PRD 提到"列配置按钮点击后打开抽屉；交互与现有样式不同"，但不清楚"不同"指什么。
**影响范围**：可能需要重新设计列配置组件，或复用现有组件并调整样式。
**代码位置**：
- 现有列配置：`src/components/table/index.vue`（wTable，2250 行，已支持列配置）
- 列配置组件：`src/components/table/components/`
**需要确认**：
1. 现有 wTable 的列配置是弹窗还是抽屉？
2. 新版本要求的差异具体是什么？
```

**代码位置具体到文件**：
```markdown
**代码位置**：
- 列表：`src/views/finance/projectReport/use/index.ts`（待新建）
- 组件：复用 `src/components/table/index.vue`（wTable，已封装列配置、筛选）
- API：`src/config/api/modules/finance/index.ts`（待新建模块）
- 后端：`adi-operation-api/src/main/java/cloud/adinsight/finance/controller/FinanceReportController.java`
```

## 配置后端 Skill（可选）

如果你的项目有独立的后端代码库，可以创建后端路径 skill 来启用自动扫描：

**文件位置**：`.cursor/skills/backend-integration/SKILL.md`

**最小配置示例**：
```markdown
---
name: backend-integration
description: 后端代码路径配置
---

## 后端只读入口（默认起点）

除非用户明确要求替换，否则一切「读后端、对齐接口、联调」均从以下目录开始：

`/Users/xxx/Desktop/your-backend-api`

Java 源码根包：`src/main/java/com/example/`
```

只要包含「后端路径」相关的绝对路径，扫描器就会自动检测并扫描。

## 技术实现

### 核心模块

- `src/core/frontendInfrastructureScan.ts`：前端基础设施扫描
- `src/core/backendSkillDetector.ts`：后端 skill 检测
- `src/core/backendApiScan.ts`：后端 Controller 扫描（已有）
- `src/steps/startFlow.ts`：集成扫描到脚手架流程

### 测试验证

```bash
# 运行集成测试
node dist/tests/frontendInfraScan.test.js

# 预期输出：
# ✅ 扫描到 25 个组件
# ✅ wTable: 2250 行
# ✅ 找到: layout.config.ts
# ✅ 找到 14 个 API 模块
# ✅ 检测到: adi-operation-api-fe-integration
# ✅ 所有测试通过
```

## 常见问题

### Q1：如果项目结构不同怎么办？

扫描器会自动尝试多个常见路径：
- `src/components/` 或 `frontend/src/components/`
- `src/config/api/modules/` 或 `frontend/src/config/api/modules/`
- `.cursor/skills/` 或 `.claude/skills/` 或 `frontend/.cursor/skills/`

### Q2：扫描失败会怎样？

扫描是增强功能，失败不会阻断流程：
- 前端扫描失败：生成空的基础设施摘要
- 后端 skill 未检测到：跳过后端扫描
- AI 仍可生成 03，但可能会问更多基础问题

### Q3：如何禁用自动扫描？

目前自动扫描是默认启用的。如果需要禁用，可以手动删除生成的 `source/*-baseline.md` 和 `source/*-summary.md` 文件。

## 更新日志

- **v1.7.17**（2026-07-21）：新增前端基础设施扫描 + 后端 skill 自动检测
  - 解决 AI 在生成 03 时过度推测已有组件（如问"用原生 table 还是 n-data-table"）
  - 代码位置从"未确定"变为具体文件路径
  - 支持自动扫描后端 Controller（如果有 skill 配置）