## API 接口目录

- **DDS-Section**: 11. API 接口设计（GIN RESTful）
- **DDS-Lines**: L1350-L1451

### Extract

#### 导入中心 API

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/v1/import/batches` | 上传账单文件，创建批次（multipart/form-data） |
| `GET` | `/api/v1/import/batches` | 获取批次列表 |
| `GET` | `/api/v1/import/batches/:batchId` | 获取批次详情 |
| `POST` | `/api/v1/import/batches/:batchId/process` | 触发解析与清洗流水线 |
| `GET` | `/api/v1/import/batches/:batchId/preview` | 获取清洗预览结果 |
| `DELETE` | `/api/v1/import/batches/:batchId` | 删除批次 |

##### 上传文件接口详情

```
POST /api/v1/import/batches
Content-Type: multipart/form-data

参数:
  - files[]            (必填) 账单文件
  - sourcePlatform     (可选) 指定来源平台: "alipay", "wechat"
  - autoDetect         (可选) 是否自动识别, 默认 true

响应:
{
  "code": 0,
  "message": "ok",
  "data": {
    "batchId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "UPLOADED",
    "filesCount": 2,
    "detectedPlatforms": ["alipay", "wechat"]
  }
}
```

#### 交易记录 API

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/transactions` | 分页查询交易记录 |
| `GET` | `/api/v1/transactions/:id` | 获取交易详情（含规则命中记录） |
| `GET` | `/api/v1/transactions/:id/trace` | 获取交易完整处理链路 |

#### 去重确认 API

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/dedup/reviews` | 获取疑似重复列表 |
| `GET` | `/api/v1/dedup/reviews/:reviewId` | 获取重复详情（含评分因子） |
| `POST` | `/api/v1/dedup/reviews/:reviewId/confirm` | 确认合并 |
| `POST` | `/api/v1/dedup/reviews/:reviewId/reject` | 拒绝合并 |

#### 规则管理 API

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/rules` | 获取规则列表（支持类型/平台过滤） |
| `POST` | `/api/v1/rules` | 创建规则 |
| `PUT` | `/api/v1/rules/:id` | 更新规则 |
| `DELETE` | `/api/v1/rules/:id` | 删除规则 |
| `POST` | `/api/v1/rules/evaluate` | 重新评估规则（修改规则后触发） |
| `POST` | `/api/v1/rules/:id/test` | 测试规则命中预览 |

#### 导入/导出 API

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/v1/import/tasks` | 创建导入任务（确认导入到 Firefly） |
| `GET` | `/api/v1/import/tasks/:taskId` | 获取导入任务详情 |
| `POST` | `/api/v1/import/tasks/:taskId/retry` | 重试失败项 |
| `GET` | `/api/v1/export/csv/:batchId` | 导出批次为 CSV 文件 |

#### 审计与系统 API

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/audit/logs` | 获取操作日志列表 |
| `GET` | `/api/v1/settings` | 获取系统配置 |
| `PUT` | `/api/v1/settings` | 更新系统配置（Firefly 连接等） |
| `POST` | `/api/v1/settings/test-connection` | 测试 Firefly III 连接 |
