# IT 运营 - API 文档

> **版本**: v0.1
> **最后更新**: 2026-03-10
> **维护者**: FFOA 开发团队

---

## ✅ 机器读取区（必填）

### 统一约定

- Base URL: `/api/v1/it-operations`
- 认证: Bearer Token (JWT)
- 错误码: [08-error-codes.md](./08-error-codes.md)
- 统一拦截器: 成功响应由 `TransformInterceptor` 统一包装；错误响应由 `AllExceptionsFilter` 统一格式化
- 响应封装:
  - 成功: `{ "success": true, "data": {...}, "message": "success", "timestamp": "...", "path": "/api/v1/..." }`
  - 分页: `{ "success": true, "data": { items, pagination: { page, pageSize, total, totalPages } }, "timestamp": "...", "path": "/api/v1/..." }`
  - 失败: `{ "success": false, "error": { "code": "<ERROR_CODE>", "message": "<i18n.key>", "...": "..." }, "timestamp": "...", "path": "/api/v1/...", "method": "GET", "statusCode": 400 }`
- 示例说明: 示例响应默认仅展示 `data` 字段，实际接口返回统一封装

### 通用状态码

| 状态码 | 说明 |
|-------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 参数错误/业务校验失败 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 409 | 业务冲突 |
| 422 | 数据校验失败 |

### API 说明

- 覆盖 IT 运营模块首期“云费用”子能力的 MVP 与 Phase 2 核心接口。
- 所有金额字段统一返回字符串格式的十进制值，避免前端浮点误差。
- 所有汇总接口默认返回 `displayCurrency` 和 `dataFreshness`。

### 接口数量汇总

- 总计: 10 个接口
- 统计口径: 下方“接口清单（按域）”中的全部路径

---

## 接口清单（按域）

### 1) 总览与分析（5）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 001 | GET | /capabilities | `it-operations:view` |
| 002 | GET | /cloud-costs/overview | `cloud-cost:view` |
| 003 | GET | /cloud-costs/trends | `cloud-cost:view` |
| 004 | GET | /cloud-costs/breakdowns | `cloud-cost:view` |
| 005 | GET | /cloud-costs/bills | `cloud-cost:view` |
| 006 | GET | /cloud-costs/anomalies | `cloud-cost:view` |

### 2) 同步与预算（2）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 007 | POST | /cloud-costs/sync | `cloud-cost:manage` |
| 008 | PUT | /cloud-costs/budgets/:id | `cloud-cost:manage` |

### 3) AI 月报（2）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 009 | GET | /cloud-costs/ai-reports | `cloud-cost:view` |
| 010 | POST | /cloud-costs/ai-reports/generate | `cloud-cost:manage` |

---

## 数据结构定义（字段级）

### 通用查询参数

#### CostPeriodQuery

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| periodMonth | String | ❌ | 账期，格式 `YYYY-MM`，默认当前月 |
| provider | String | ❌ | `aws` / `aliyun` / `tencent` / `gcp` / `all` |
| displayCurrency | String | ❌ | 展示币种，默认 `CNY` |

#### BreakdownQuery

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| periodMonth | String | ❌ | 账期 |
| dimension | String | ✅ | `provider` / `account` / `project` / `service` / `region` |
| provider | String | ❌ | 云厂商 |
| topN | Int | ❌ | 返回前 N 条，默认 10 |
| compareWithPrevious | Boolean | ❌ | 是否包含上月对比，默认 `true` |

#### BillsQuery

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| periodMonth | String | ❌ | 账期 |
| provider | String | ❌ | 云厂商 |
| accountId | String | ❌ | 云账号 ID |
| projectCode | String | ❌ | 项目编码 |
| normalizedService | String | ❌ | 统一服务类目 |
| page | Int | ❌ | 页码，默认 1 |
| pageSize | Int | ❌ | 每页数量，默认 20 |

### 业务实体与 DTO

#### CapabilityItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| key | String | ✅ | 子能力标识 |
| name | String | ✅ | 名称 |
| status | String | ✅ | `active` / `planned` |
| path | String | ✅ | 前端路由 |
| description | String | ✅ | 子能力说明 |

#### OverviewResponse

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| periodMonth | String | ✅ | 当前账期 |
| totalAmount | String | ✅ | 本月总费用 |
| previousAmount | String | ✅ | 上月总费用 |
| changeAmount | String | ✅ | 差额 |
| changeRate | String | ✅ | 环比百分比 |
| displayCurrency | String | ✅ | 展示币种 |
| dataFreshness | String | ✅ | 数据更新时间 |
| providers | ProviderCostCard[] | ✅ | 厂商卡片列表 |

#### ProviderCostCard

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| provider | String | ✅ | 云厂商 |
| amount | String | ✅ | 本月费用 |
| previousAmount | String | ✅ | 上月费用 |
| changeRate | String | ✅ | 环比 |
| percentage | String | ✅ | 厂商占比 |

#### BreakdownItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dimensionKey | String | ✅ | 维度值 |
| amount | String | ✅ | 本月费用 |
| previousAmount | String | ❌ | 上月费用 |
| changeRate | String | ❌ | 环比 |
| provider | String | ❌ | 云厂商 |
| meta | Json | ❌ | 附加说明 |

#### BillItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | ✅ | 明细 ID |
| provider | String | ✅ | 云厂商 |
| accountName | String | ✅ | 云账号名称 |
| billingDate | String | ✅ | 账单日期 |
| originalServiceName | String | ✅ | 原始服务名 |
| normalizedService | String | ✅ | 统一服务类目 |
| projectCode | String | ❌ | 项目编码 |
| region | String | ❌ | 区域 |
| resourceId | String | ❌ | 资源 ID |
| currency | String | ✅ | 原币种 |
| originalAmount | String | ✅ | 原始金额 |
| normalizedAmount | String | ✅ | 折算金额 |

#### AnomalyItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | ✅ | 异常 ID |
| anomalyType | String | ✅ | 异常类型 |
| severity | String | ✅ | 严重级别 |
| title | String | ✅ | 异常标题 |
| provider | String | ✅ | 云厂商 |
| changeRate | String | ❌ | 涨幅 |
| evidence | Json | ✅ | 证据 |

#### AiCostReport

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | String | ✅ | 报告 ID |
| periodMonth | String | ✅ | 账期 |
| status | String | ✅ | 报告状态 |
| summary | Json | ✅ | 结构化摘要 |
| markdownContent | String | ✅ | Markdown 正文 |
| generatedAt | String | ❌ | 生成时间 |

---

## 统一格式 + 简短示例

### 1) 总览与分析（6）

**[001] GET /capabilities**
- 说明: 获取 IT 运营子能力列表
- 请求 Query: 无
- 响应 Data: `{ items: CapabilityItem[] }`
- 示例请求: `GET /api/v1/it-operations/capabilities`
- 状态码: 200, 401, 403

**[002] GET /cloud-costs/overview**
- 说明: 获取账期总览与厂商卡片
- 请求 Query: `CostPeriodQuery`
- 响应 Data: `OverviewResponse`
- 示例请求: `GET /api/v1/it-operations/cloud-costs/overview?periodMonth=2026-03`
- 状态码: 200, 401, 403

**[003] GET /cloud-costs/trends**
- 说明: 获取多月趋势图数据
- 请求 Query: `periodMonth`, `months`, `provider`
- 响应 Data: `{ items: [{ periodMonth, provider, amount }] }`
- 示例请求: `GET /api/v1/it-operations/cloud-costs/trends?months=6`
- 状态码: 200, 401, 403

**[004] GET /cloud-costs/breakdowns**
- 说明: 按维度获取成本拆分
- 请求 Query: `BreakdownQuery`
- 响应 Data: `{ dimension, items: BreakdownItem[] }`
- 示例请求: `GET /api/v1/it-operations/cloud-costs/breakdowns?dimension=service&periodMonth=2026-03`
- 状态码: 200, 401, 403

**[005] GET /cloud-costs/bills**
- 说明: 获取标准化账单明细
- 请求 Query: `BillsQuery`
- 响应 Data: `PageResult<BillItem>`
- 示例请求: `GET /api/v1/it-operations/cloud-costs/bills?provider=aws&page=1&pageSize=20`
- 状态码: 200, 401, 403

**[006] GET /cloud-costs/anomalies**
- 说明: 获取异常费用列表
- 请求 Query: `CostPeriodQuery`
- 响应 Data: `{ items: AnomalyItem[] }`
- 示例请求: `GET /api/v1/it-operations/cloud-costs/anomalies?periodMonth=2026-03`
- 状态码: 200, 401, 403

### 2) 同步与预算（2）

**[007] POST /cloud-costs/sync**
- 说明: 手动触发账单同步
- 请求 Body: `{ providers?: string[], periodMonth?: string }`
- 响应 Data: `{ jobIds: string[] }`
- 示例请求: `POST /api/v1/it-operations/cloud-costs/sync`
- 状态码: 201, 401, 403, 409

**[008] PUT /cloud-costs/budgets/:id**
- 说明: 更新预算配置
- 请求 Body: `{ budgetAmount: string, currency: string, alertThresholds: object }`
- 响应 Data: `{ id, updatedAt }`
- 示例请求: `PUT /api/v1/it-operations/cloud-costs/budgets/budget_001`
- 状态码: 200, 400, 401, 403, 404

### 3) AI 月报（2）

**[009] GET /cloud-costs/ai-reports**
- 说明: 获取 AI 月报列表
- 请求 Query: `periodMonth?`, `status?`
- 响应 Data: `{ items: AiCostReport[] }`
- 示例请求: `GET /api/v1/it-operations/cloud-costs/ai-reports?periodMonth=2026-03`
- 状态码: 200, 401, 403

**[010] POST /cloud-costs/ai-reports/generate**
- 说明: 基于当前账期快照生成 AI 月报
- 请求 Body: `{ periodMonth: string, regenerate?: boolean }`
- 响应 Data: `{ reportId: string, status: "pending" | "generated" }`
- 示例请求: `POST /api/v1/it-operations/cloud-costs/ai-reports/generate`
- 状态码: 201, 400, 401, 403, 409