# IT 运营 - 架构设计文档

> **版本**: v0.1  
> **状态**: Draft  
> **创建日期**: 2026-03-10  
> **最后更新**: 2026-03-10  
> **架构师**: AI Assistant

---

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

### 架构摘要

| 字段 | 内容 |
|------|------|
| 模块定位 | 企业内部技术治理的一级业务域，首期承载云费用治理，负责账单采集、标准化、聚合分析和 AI 解读 |
| 关键组件 | IT 运营模块外壳、云费用子域控制器与服务、成本接入适配器、账单同步任务、标准化服务、聚合分析服务、异常检测服务、AI 报告服务 |
| 关键接口 | `/cloud-costs/overview`、`/cloud-costs/trends`、`/cloud-costs/breakdowns`、`/cloud-costs/bills`、`/cloud-costs/anomalies`、`/cloud-costs/ai-reports/*` |
| 数据流 | 云厂商账单源 -> 云费用适配器 -> 标准化账单表 -> 聚合统计表 -> 异常检测/AI 分析 -> IT 运营前端展示 |
| 关键依赖 | AWS Cost Explorer、阿里云 BSS OpenAPI、腾讯云 Billing API、GCP BigQuery Billing Export、汇率服务、LLM 服务 |

---

## 🧭 人类阅读区（可选）

### 分层架构

```
┌─────────────────────────────────────────────┐
│ Presentation                                │
│ ITOperationsController / 前端 IT 运营页面      │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│ Application                                 │
│ CloudCostsService / BudgetService /         │
│ CostAnomalyService / AiCostReportService    │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│ Domain                                      │
│ IT 运营域模型、标准化账单、月度快照、预算、异常、AI 报告 │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│ Infrastructure                              │
│ AWS/阿里云/腾讯云/GCP 适配器、Prisma Repo、  │
│ 定时任务、汇率服务、LLM Provider            │
└─────────────────────────────────────────────┘
```

### 关键设计决策

#### 0. 一级域 + 子能力结构

- 一级模块为 `it-operations`。
- 首期子能力为 `cloud-costs`。
- API、前端路由、权限命名按 `it-operations` 域收口，避免后续新增能力时重新拆模块。

#### 1. 账单事实与 AI 解读分层

- 原始/标准化账单由官方账单源驱动。
- 金额计算、汇率换算、聚合统计由后端确定。
- AI 仅消费结构化指标和异常结果，输出解释和建议。
- 任何 AI 文本都不能反写账单事实表。

#### 2. 多云接入采用 Provider Adapter 模式

- `AwsBillingAdapter`
- `AliyunBillingAdapter`
- `TencentCloudBillingAdapter`
- `GcpBillingAdapter`

统一输出标准账单 DTO，屏蔽各云厂商字段差异。

#### 3. 查询层采用“明细 + 快照”双层模型

- 明细表用于追溯、导出和下钻。
- 月度聚合快照用于总览、趋势、Top N 和 AI 输入。
- 预算、异常、AI 报告基于聚合快照和衍生指标生成。

#### 4. 权限边界

- 平台管理员：查看所有 IT 运营能力和所有云账号。
- IT 运营：查看云费用和预算配置。
- 项目负责人：仅查看被授权的项目/成本中心范围。
- 财务角色：查看汇总、明细、导出和月报。

### 关键组件说明

- **账单同步任务**: 每日定时拉取或刷新账单数据，支持手动触发补拉。
- **标准化服务**: 统一厂商、账号、服务类目、币种、标签格式。
- **汇率服务**: 将原币种金额换算为系统主展示币种。
- **聚合分析服务**: 计算月度汇总、维度拆分、环比、Top N。
- **异常检测服务**: 根据规则识别涨幅、突增、未归类成本。
- **AI 报告服务**: 将结构化指标提交给 LLM，生成摘要和建议。

### 同步策略建议

- AWS：优先接 Cost Explorer 汇总，必要时补资源级明细。
- 阿里云：通过 BSS OpenAPI 获取账单数据。
- 腾讯云：通过账单 API 获取汇总和明细。
- GCP：通过 Billing Export to BigQuery 读取明细。
- 同步频率：每日 2 次，月初账单波动期可增加补拉。

### 风险与应对

- **账单延迟**: 页面展示“数据截止时间”和“完整性状态”。
- **币种不一致**: 同时保留原币种金额和折算金额。
- **标签不规范**: 单独标记未归类成本，推动治理。
- **AI 幻觉**: 仅输入结构化指标，输出保留证据字段和来源范围。