# IT 运营 - 数据模型文档

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

---

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

### Schema 摘要

| 字段 | 内容 |
|------|------|
| Schema 名称 | `ops_finance` |
| 业务域 | IT 运营域；首期覆盖多云账单聚合、成本分析、预算治理、AI 月报 |
| 核心实体 | `cloud_accounts`、`billing_sync_jobs`、`cloud_bill_items`、`monthly_cost_snapshots`、`cost_anomalies`、`cost_budgets`、`ai_cost_reports` |

### 实体字段清单（最小）

| 实体 | 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| cloud_accounts | id | UUID | ✅ | 云账号主键 |
| cloud_accounts | provider | Enum | ✅ | `aws` / `aliyun` / `tencent` / `gcp` |
| cloud_accounts | accountId | String | ✅ | 厂商账号 ID |
| cloud_accounts | accountName | String | ✅ | 账号显示名称 |
| cloud_accounts | credentialRef | String | ✅ | 凭证引用，不存明文密钥 |
| cloud_accounts | status | Enum | ✅ | `active` / `disabled` / `error` |
| billing_sync_jobs | id | UUID | ✅ | 同步任务主键 |
| billing_sync_jobs | provider | Enum | ✅ | 云厂商 |
| billing_sync_jobs | periodMonth | String | ✅ | 账期，格式 `YYYY-MM` |
| billing_sync_jobs | status | Enum | ✅ | `pending` / `running` / `success` / `failed` |
| billing_sync_jobs | startedAt | DateTime | ❌ | 开始时间 |
| billing_sync_jobs | finishedAt | DateTime | ❌ | 完成时间 |
| billing_sync_jobs | summary | Json | ❌ | 同步摘要 |
| cloud_bill_items | id | UUID | ✅ | 标准化账单明细主键 |
| cloud_bill_items | provider | Enum | ✅ | 云厂商 |
| cloud_bill_items | billingAccountId | UUID | ✅ | 关联云账号 |
| cloud_bill_items | periodMonth | String | ✅ | 账期 |
| cloud_bill_items | billingDate | Date | ✅ | 账单日期 |
| cloud_bill_items | originalServiceName | String | ✅ | 厂商原始服务名 |
| cloud_bill_items | normalizedService | String | ✅ | 统一服务类目 |
| cloud_bill_items | projectCode | String | ❌ | 项目/成本中心编码 |
| cloud_bill_items | region | String | ❌ | 区域 |
| cloud_bill_items | resourceId | String | ❌ | 资源 ID |
| cloud_bill_items | currency | String | ✅ | 原币种 |
| cloud_bill_items | originalAmount | Decimal | ✅ | 原始金额 |
| cloud_bill_items | exchangeRate | Decimal | ✅ | 汇率 |
| cloud_bill_items | normalizedAmount | Decimal | ✅ | 折算后金额 |
| cloud_bill_items | tags | Json | ❌ | 原始与标准化标签 |
| cloud_bill_items | rawPayload | Json | ✅ | 原始账单片段 |
| monthly_cost_snapshots | id | UUID | ✅ | 月度快照主键 |
| monthly_cost_snapshots | periodMonth | String | ✅ | 账期 |
| monthly_cost_snapshots | provider | Enum | ✅ | 云厂商，支持 `all` |
| monthly_cost_snapshots | dimensionType | Enum | ✅ | `provider` / `account` / `project` / `service` / `region` |
| monthly_cost_snapshots | dimensionKey | String | ✅ | 维度值 |
| monthly_cost_snapshots | totalAmount | Decimal | ✅ | 本月金额 |
| monthly_cost_snapshots | previousAmount | Decimal | ❌ | 上月金额 |
| monthly_cost_snapshots | changeAmount | Decimal | ❌ | 差额 |
| monthly_cost_snapshots | changeRate | Decimal | ❌ | 环比百分比 |
| cost_anomalies | id | UUID | ✅ | 异常主键 |
| cost_anomalies | periodMonth | String | ✅ | 账期 |
| cost_anomalies | provider | Enum | ✅ | 云厂商 |
| cost_anomalies | anomalyType | Enum | ✅ | `spike` / `budget_overrun` / `untagged_cost` |
| cost_anomalies | severity | Enum | ✅ | `low` / `medium` / `high` |
| cost_anomalies | title | String | ✅ | 异常标题 |
| cost_anomalies | evidence | Json | ✅ | 结构化证据数据 |
| cost_budgets | id | UUID | ✅ | 预算主键 |
| cost_budgets | scopeType | Enum | ✅ | `all` / `provider` / `project` / `department` |
| cost_budgets | scopeKey | String | ✅ | 范围值 |
| cost_budgets | currency | String | ✅ | 币种 |
| cost_budgets | budgetAmount | Decimal | ✅ | 月预算 |
| cost_budgets | alertThresholds | Json | ✅ | 告警阈值配置 |
| ai_cost_reports | id | UUID | ✅ | 报告主键 |
| ai_cost_reports | periodMonth | String | ✅ | 账期 |
| ai_cost_reports | status | Enum | ✅ | `pending` / `generated` / `failed` |
| ai_cost_reports | summary | Json | ✅ | AI 结构化输出摘要 |
| ai_cost_reports | markdownContent | Text | ✅ | AI 报告正文 |
| ai_cost_reports | sourceSnapshotVersion | String | ✅ | 分析所用快照版本 |
| ai_cost_reports | generatedAt | DateTime | ❌ | 生成时间 |

### 关系与约束

| 关系/约束 | 说明 |
|-----------|------|
| `cloud_accounts.accountId + provider` 唯一 | 同一厂商账号不能重复接入 |
| `cloud_bill_items` 关联 `cloud_accounts.id` | 明细必须归属到一个云账号 |
| `monthly_cost_snapshots(periodMonth, provider, dimensionType, dimensionKey)` 唯一 | 避免重复聚合快照 |
| `cost_budgets(scopeType, scopeKey, currency)` 唯一 | 同一范围同一币种只允许一条生效预算 |
| `ai_cost_reports(periodMonth, sourceSnapshotVersion)` 唯一 | 同一快照版本只保留一版正式报告 |

---

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

### 建模原则

- `it-operations` 是一级域，首期所有表围绕云费用子能力建设，后续新增能力继续复用同一 schema 或按子域拆分。
- `cloud_bill_items` 是事实表，保留来源和原始口径。
- `monthly_cost_snapshots` 是服务总览和 AI 的主要输入表。
- `cost_anomalies` 保存规则检测结果，供页面和 AI 共同消费。
- `ai_cost_reports` 只保存可追溯的报告产物，不保存模型私有中间状态。

### 后续可扩展实体

- `cost_allocation_rules`：定义项目/部门分摊规则
- `cost_exports`：导出任务记录
- `cost_recommendations`：节省建议库