cjyyzx/AI-BRAIN-API.md

AI 大脑 · 对内程序调用接口说明

本文档供 内部 AI 大脑 / 自动化程序 在回答 费用、用量、账单、资源归属 等问题时调用 CloudCost 后端使用。

• 范围：以 只读（GET） 为主。
• 响应 JSON 约定：
  • date → YYYY-MM-DD 字符串
  • datetime → 本地时间 ISO8601（无时区后缀，例：2026-04-18T18:01:19.142386）
  • 金额 / 用量（重要）：
    • 聚合型 / 仪表盘类接口（/api/dashboard/*、/api/service-accounts/{id}/costs、/api/service-accounts/daily-report、/api/dashboard/overview）→ JSON number（float）
    • 原始明细类接口（/api/metering/*、/api/billing/detail）→ JSON string（后端保留 Decimal 精度），需 float(...) / parseFloat(...) 解析
• 完整路由清单：见 API.md。

---

1. 认证体系概述

云管后端已接入 Casdoor 统一认证，所有请求（除匿名白名单外）必须携带合法凭据。

1.1 三种认证方式

方式	Header	适用场景	角色来源
Casdoor OAuth Cookie	浏览器自动携带 cc_access_token	人类用户通过前端登录	Casdoor token 中的 roles
Casdoor Bearer Token	Authorization: Bearer <token>	内部系统间调用（client_credentials）	token roles 非空时用 token；为空时 fallback 到 DB users.roles
API Key	X-API-Key: cck_xxx	三方对接 / 细粒度权限控制	DB users.roles（owner 用户）

AI 大脑 / 内部系统推荐使用方式 2（Casdoor Bearer Token），因为所有内部系统已在 Casdoor 注册了应用，统一走 client_credentials 拿 token 即可。

1.2 四个角色

角色	权限范围
cloud_admin	全部功能 + 全量数据（超级角色，自动满足任何角色要求）
cloud_ops	dashboard + 触发同步
cloud_finance	dashboard + 账单管理
cloud_viewer	dashboard 只读

角色 → 前端页面映射

┌────────────────────────────────────────────┬─────────────┬───────────────┬───────────────┬───────────────┐ │ 前端页面 │ cloud_admin │ cloud_ops │ cloud_finance │ cloud_viewer │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ 仪表盘 / (Dashboard) │ ✅ │ ✅ │ ✅ │ ✅ │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ 统计 /daily-report (日报/账单明细) │ ✅ │ ✅ │ ✅ │ ✅ │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ 计量 /metering │ ✅ │ ✅ │ ✅ │ ✅ │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ 告警 /alerts │ ✅ │ ✅ │ ✅ │ ✅ │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ 货源管理 /accounts (云账号管理) │ ✅ 可增删改 │ ❌ 只能看列表 │ ❌ 只能看列表 │ ❌ 只能看列表 │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ 供应商管理 /suppliers │ ✅ 可增删改 │ ❌ │ ❌ │ ❌ │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ 模型管理 /azure-deploy │ ✅ │ ❌ │ ❌ │ ❌ │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ Azure 接入 /azure-onboard │ ✅ │ ❌ │ ❌ │ ❌ │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ 项目详情 /projects/[id] │ ✅ 可管理 │ ✅ 只读 │ ✅ 只读 │ ✅ 只读 │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ Header 中的 同步按钮 │ ✅ │ ✅ │ ❌ │ ❌ │ ├────────────────────────────────────────────┼─────────────┼───────────────┼───────────────┼───────────────┤ │ Header 中的 账单管理（生成/调整/确认账单） │ ✅ │ ❌ │ ✅ │ ❌ │ └────────────────────────────────────────────┴─────────────┴───────────────┴───────────────┴───────────────┘

---

各角色详细说明

cloud_admin — 超级管理员

能用所有页面的全部功能，额外还有：

• 用户管理、权限分配（/api/admin/users/*）
• 云账号增删改（/api/cloud-accounts/ POST/PUT/DELETE）
• 模块开关（/api/api-permissions/）
• API Key 管理
• Azure 部署和 OAuth 授权
• 数据范围：看到全量数据，不受 cloud_account_grant 限制

cloud_ops — 运维

• 仪表盘：✅ 全部看板数据
• 统计/日报：✅ 账单明细查看和导出
• 同步操作：✅ 触发数据同步、查看同步日志（/api/sync/*）
• 告警：✅ 查看
• 计量：✅ 查看
• ❌ 不能管理云账号/供应商/Azure 部署/账单
• 数据范围：仅限被授权的云账号（通过 UserCloudAccountGrant）

cloud_finance — 财务

• 仪表盘：✅ 全部看板数据
• 统计/日报：✅ 账单明细查看和导出
• 账单管理：✅ 生成、调整、确认、标记已付（/api/bills/*）
• 告警：✅ 查看
• 计量：✅ 查看
• ❌ 不能触发同步、不能管理云账号/供应商/Azure
• 数据范围：仅限被授权的云账号

cloud_viewer — 只读查看者

• 仪表盘：✅ 只读
• 统计/日报：✅ 只读 + 导出
• 告警：✅ 只读
• 计量：✅ 只读
• ❌ 其他所有管理操作都不可用
• 数据范围：仅限被授权的云账号

---

角色管理方式：

• 人类用户：在 Casdoor 后台 → Roles → 给用户分配角色，登录时自动带入
• 机器应用（client_credentials）：Casdoor token 不携带角色，管理员通过 SQL 设置 DB 中的 users.roles

1.3 模块开关

每个业务路由绑定一个模块名（如 dashboard、billing）。管理员可通过 PATCH /api/api-permissions/<module> 全局关停某模块，关停后所有身份调用都会 403。AI 应优雅降级，不要把 403 当故障。

1.4 数据可见范围

同一个 URL，不同身份返回的数值不同：

• cloud_admin（无额外限制）→ 全量数据
• 非 admin → 仅看到 user_cloud_account_grants 表里被授权的云账号数据
• Dashboard 聚合接口在 SUM 之前加 WHERE 过滤，百分比/增长率基于过滤后数据重算
• 如果没有可见数据，返回空数组或零值（不是 403）

AI 回答时应说明"当前视角内"的数据，避免把有限视角误报为全量。

---

2. AI 大脑接入指南

2.1 获取 Token（Casdoor client_credentials）

CASDOOR=https://casdoor.ashyglacier-8207efd2.eastasia.azurecontainerapps.io

TOKEN=$(curl -s -X POST "$CASDOOR/api/login/oauth/access_token" \
  -d "grant_type=client_credentials&client_id=<你的APP_CLIENT_ID>&client_secret=<你的APP_CLIENT_SECRET>" \
  | python -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

• token 默认有效期 24 小时，调用方应缓存并在过期前刷新
• 首次使用该 token 调用云管 API 时，后端会自动在 users 表创建一条记录（casdoor_sub=admin/<app_name>，roles=[]）
• 管理员需提前设置角色（否则所有需要角色的接口返回 403）：

  UPDATE users SET roles='["cloud_admin"]'::jsonb WHERE casdoor_sub='admin/<app_name>';
  

2.2 调用接口

BASE=https://cloudcost-brank.yellowground-bf760827.southeastasia.azurecontainerapps.io

# 确认身份与可见范围
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/auth/me"

# 当月首页 bundle
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/api/dashboard/bundle?month=2026-04"

# 明细分页
curl -s -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/metering/detail?date_start=2026-04-01&date_end=2026-04-30&provider=aws&page=1&page_size=100"

2.3 /api/auth/me 响应说明

{
  "id": 4,
  "username": "sales",
  "email": "",
  "display_name": "Sales App (M2M)",
  "roles": ["cloud_admin"],
  "visible_cloud_account_ids": null
}

visible_cloud_account_ids：

• null → 全量可见（cloud_admin 身份）
• [] → 零可见（未被授权任何云账号）
• [1, 2] → 只能看到这些云账号的数据

2.4 错误码

HTTP 状态码	含义	AI 应对
200	成功	正常解析
401	未带凭据或 token 过期	刷新 token 后重试
403 missing required role	角色不足	该接口对当前身份不可用，跳过
403 Module 'x' is disabled	模块被管理员关停	优雅降级，不报故障
422	参数校验失败	检查 Query 参数格式
503	数据库不可达	稍后重试

---

3. 接口分级

级别	含义
P0 推荐	费用总览、趋势、计量聚合、账单明细分页、数据新鲜度
P1 补充	维度拆分（分类/区域/项目排行）、服务账号上下文、月度账单、告警阈值执行态
P2 可选	资源清单、汇率、分类字典、导出类流式接口（适合落盘，不适合直接塞进模型上下文）
禁止	任何 写操作、凭据解密、同步触发、删除、Azure 部署、以及返回 webhook/邮箱 等敏感配置的接口

---

4. P0 推荐接口（入参 / 出参）

4.1 GET /api/health

用途：连通性探测（匿名可访问）。

出参：

{ "status": "ok" }

字段	类型	说明
status	string	总是 "ok"；仅此一字段。失败时会被 FastAPI 500 覆盖，不返回此对象

---

4.2 GET /api/sync/last

用途：回答「数据同步到什么时候」。模块：sync，角色：cloud_ops（含 admin）。

出参（真实样例）：

{ "last_sync": "2026-04-18T18:01:19.142386" }

字段	类型	说明
last_sync	string | null	最近一次 成功 同步结束时间 ISO8601（本地时间，无时区）。从未同步过时为 null

---

4.3 GET /api/dashboard/bundle

用途：单次请求拿首页级总览。模块：dashboard，角色：cloud_viewer / cloud_ops / cloud_finance（任一即可，cloud_admin 自动通过）。

入参（Query）：

参数	类型	必填	说明
month	string	是	YYYY-MM，统计月
granularity	string	否	daily | weekly | monthly，默认 daily
service_limit	int	否	1–100，默认 10

出参（真实样例，截断）：

{
  "overview": {
    "total_cost": 149785.098288,
    "prev_month_cost": 938396.218412,
    "mom_change_pct": -84.04,
    "active_projects": 7
  },
  "trend": [
    { "date": "2026-04-01", "cost": 7399.860517,
      "cost_by_provider": { "aws": 466.038035, "azure": 962.156064, "gcp": 5971.666418 } }
  ],
  "by_provider": [
    { "provider": "gcp",   "cost": 124735.119318, "percentage": 83.28 },
    { "provider": "azure", "cost": 18058.538325,  "percentage": 12.06 }
  ],
  "by_service": [
    { "product": "Vertex AI",        "cost": 124410.727567, "percentage": 83.06 },
    { "product": "Virtual Machines", "cost": 6202.288351,   "percentage": 4.14 }
  ]
}

字段	类型	说明
overview.total_cost	number	当月总费用（USD，对当前身份可见范围求和）
overview.prev_month_cost	number	上月同口径总费用
overview.mom_change_pct	number	环比变化 %，保留两位小数，可能负值
overview.active_projects	integer	status=active 的服务账号数
trend[].date	string	YYYY-MM-DD
trend[].cost	number	当日全 provider 合计费用
trend[].cost_by_provider	object	形如 { "aws":…, "gcp":…, "azure":… }；只包含当日有数据的 provider
by_provider[]	array	按 provider 当月累计，cost + percentage（占 total_cost 百分比，保留两位小数）
by_service[]	array	Top N 服务（product 原样字符串），N 由 service_limit 控制

---

4.4 GET /api/dashboard/overview

用途：只要月度总览卡片数据。

入参（Query）：month（必填，YYYY-MM）。

出参（真实样例）：

{
  "total_cost": 149785.098288,
  "prev_month_cost": 938396.218412,
  "mom_change_pct": -84.04,
  "active_projects": 7
}

字段同 §4.3 overview。

---

4.5 GET /api/metering/summary

用途：按条件汇总用量/费用。模块：metering，角色：任意登录即可。

入参（Query）：

参数	类型	必填	说明
date_start	string	否	YYYY-MM-DD
date_end	string	否	YYYY-MM-DD
provider	string	否	aws / gcp / azure
product	string	否	产品/服务名
account_id	int	否	服务账号 ID
supply_source_id	int	否	货源 ID
supplier_name	string	否	供应商名称
data_source_id	int	否	数据源 ID

出参（真实样例，注意 total_cost / total_usage 是字符串）：

{
  "total_cost": "149785.098288",
  "total_usage": "55555350118.525461",
  "record_count": 62016,
  "service_count": 43
}

字段	类型	说明
total_cost	string（Decimal）	筛选范围内的费用合计，USD。调用方自行 float(...)
total_usage	string（Decimal）	用量合计。注意不同 product 的 usage_unit 不同，直接求和意义有限
record_count	integer	命中的 billing_data 行数
service_count	integer	不同 product 去重数

---

4.6 GET /api/metering/daily

用途：按日聚合费用与用量。入参同 metering/summary。

出参（真实样例）：

[
  { "date": "2026-04-01", "usage_quantity": "2327753993.353517",
    "cost": "7399.860517", "record_count": 2745 },
  { "date": "2026-04-02", "usage_quantity": "1300687882.204744",
    "cost": "6175.577245", "record_count": 2974 }
]

字段	类型	说明
date	string	YYYY-MM-DD
cost	string（Decimal）	当日费用合计
usage_quantity	string（Decimal）	当日用量合计（跨 product；单位不定）
record_count	integer	当日命中的明细行数

---

4.7 GET /api/metering/by-service

用途：按服务聚合（Top N 分析）。入参同 summary（无 product 过滤）。

出参（真实样例）：

[
  { "product": "Vertex AI", "usage_quantity": "55518458336.183727",
    "usage_unit": "month", "cost": "124410.727567", "record_count": 58924 },
  { "product": "Cloud Text-to-Speech API", "usage_quantity": "18315835.000000",
    "usage_unit": "count", "cost": "315.170942", "record_count": 101 }
]

字段	类型	说明
product	string	原样服务名（含空格大小写；同名但不同 usage_unit 会分别出现，后端按 (product, unit) 分组再在此合并，见 usage_unit）
cost	string（Decimal）	该服务筛选范围内的费用合计
usage_quantity	string（Decimal）	用量合计；仅在该服务使用单一 usage_unit 时可直接阅读
usage_unit	string | null	该服务的用量单位；如果同名 product 有多种单位，后端取任一
record_count	integer	行数

---

4.8 GET /api/metering/detail

用途：原始明细行分页。入参在 summary 基础上增加 page（默认 1）、page_size（默认 50，最大 500）。

出参（真实样例）：

[
  {
    "id": 1819145,
    "date": "2026-04-18",
    "provider": "gcp",
    "data_source_id": 3,
    "project_id": "ysgemini-20260324",
    "product": "Cloud Text-to-Speech API",
    "usage_type": "Cloud TTS API text input token count for Gemini 2.5 Pro",
    "region": "asia-southeast1",
    "cost": "0.031815",
    "usage_quantity": "31815.000000",
    "usage_unit": "count",
    "currency": "USD"
  }
]

字段	类型	说明
id	integer	明细主键（billing_data.id）
date	string	YYYY-MM-DD 账单日期
provider	string	aws / gcp / azure
data_source_id	integer	数据源 FK
project_id	string	云厂商侧项目 ID（GCP project / Azure subscription / AWS account），不是本地 projects.id
product	string | null	服务名
usage_type	string | null	计费类型 / SKU 名
region	string | null	区域
cost	string（Decimal）	该条费用 USD
usage_quantity	string（Decimal）	用量
usage_unit	string | null	用量单位
currency	string	总是 "USD"

---

4.9 GET /api/metering/detail/count

用途：与 detail 同筛选条件下的总条数。

出参：{ "total": 62016 }

字段	类型	说明
total	integer	行数；分页计算用

---

4.10 GET /api/billing/detail

用途：计费明细列表。模块：billing，角色：任意登录。数据按可见数据源过滤。

入参（Query）：

参数	类型	说明
date_start	string	YYYY-MM-DD
date_end	string	YYYY-MM-DD
provider	string	可选
project_id	string	可选
product	string	可选
page	int	默认 1
page_size	int	默认 50，最大 500

出参（真实样例）：

[
  {
    "id": 1759843,
    "date": "2026-04-18",
    "provider": "azure",
    "data_source_id": 2,
    "project_id": "45d7a360-af09-40fc-9afc-56dc475245ec",
    "project_name": "Xmind运营学习专用2026",
    "product": "API Management",
    "usage_type": "Consumption Calls",
    "region": "southeastasia",
    "cost": "0.000000",
    "usage_quantity": "0.083300",
    "usage_unit": "10K",
    "currency": "USD"
  }
]

字段大致同 /metering/detail，额外字段：

字段	类型	说明
project_name	string | null	云厂商侧返回的项目显示名（AWS 未必有；GCP/Azure 多数有）

cost / usage_quantity 仍为 string (Decimal)。

---

4.11 GET /api/billing/detail/count

用途：与 billing/detail 相同筛选下的总行数。

出参：{ "total": 62016 }

---

5. P1 补充接口

5.1 Dashboard 维度拆分

模块：dashboard，角色：cloud_viewer / cloud_ops / cloud_finance（含 admin）。数据按可见数据源过滤。所有 cost 字段均为 JSON number（float）。

GET /api/dashboard/trend

入参：start、end（均 YYYY-MM）；granularity（daily 默认 / weekly / monthly）。

出参：[{ date, cost, cost_by_provider }]，结构同 §4.3 trend[]。

GET /api/dashboard/by-provider

入参：month。出参真实样例：

[
  { "provider": "gcp",   "cost": 124735.119318, "percentage": 83.28 },
  { "provider": "azure", "cost": 18058.538325,  "percentage": 12.06 }
]

字段	说明
provider	aws/gcp/azure
cost	当月累计 USD
percentage	占当月总费用百分比（两位小数）

GET /api/dashboard/by-category

入参：month。出参真实样例：

[{ "category_id": 2, "name": "default", "original_cost": 24846.617897,
   "markup_rate": 1.15, "final_cost": 28573.61058155 }]

字段	说明
category_id、name	费用分类
original_cost	原始成本（未加价）
markup_rate	加价率（1.0 = 不加价）
final_cost	= original_cost × markup_rate

GET /api/dashboard/by-project

入参：month，limit（1–100，默认 10）。出参真实样例：

[
  { "project_id": "xianlong-2", "name": "xianlong-2",
    "provider": "gcp", "cost": 58749.779907 }
]

字段	说明
project_id	云厂商侧项目 ID（字符串），即 GCP project / Azure subscription / AWS account。不是本地 projects.id
name	账单中的项目名（云厂商返回）
provider	aws/gcp/azure
cost	当月累计 USD

GET /api/dashboard/by-service

入参：month，provider（可选），limit（1–100）。出参真实样例：

[
  { "product": "Vertex AI", "cost": 124410.727567, "percentage": 83.06 },
  { "product": "Virtual Machines", "cost": 6202.288351, "percentage": 4.14 }
]

字段同 dashboard/by-provider（percentage 相对当月 total）。

GET /api/dashboard/by-region

入参：month。出参真实样例：

[
  { "region": "asia-east1",      "provider": "gcp", "cost": 38836.928387 },
  { "region": "asia-southeast1", "provider": "gcp", "cost": 9817.383452 }
]

GET /api/dashboard/top-growth

入参：period（默认 7d），limit（1–50）。出参真实样例：

[
  { "project_id": "lyww-01", "name": "lyww-01",
    "current_cost": 3775.070699, "previous_cost": 5e-05,
    "growth_pct": 7550141298.0 }
]

字段	说明
project_id	外部项目 ID 字符串
current_cost / previous_cost	本周期 / 对比周期累计 USD
growth_pct	增幅 %，previous 接近 0 时可能非常大

GET /api/dashboard/unassigned

入参：month。出参真实样例（未与本地 projects 表关联上的外部项目）：

[
  { "project_id": "xianlong-2", "name": "xianlong-2",
    "provider": "gcp", "cost": 58749.779907, "status": null }
]

字段	说明
project_id / name / provider	同 by-project
cost	当月累计 USD
status	总是 null（projects 表里没有对应行），保留字段以便未来扩展

---

5.2 GET /api/service-accounts/

模块：service_accounts，角色：任意登录（列表查看所有角色可用）。路径需带尾部斜杠。

入参（Query）：provider、status、customer_code（按客户编号反查）、page、page_size。

出参（真实样例）：

[
  {
    "id": 7,
    "name": "AWS-Main",
    "supply_source_id": 2,
    "supplier_name": "神州泰岳",
    "provider": "aws",
    "external_project_id": "675139393309",
    "status": "standby",
    "order_method": null,
    "customer_codes": [],
    "created_at": "2026-04-08T10:19:32.565267"
  }
]

字段	类型	说明
id	integer	本地服务账号主键
name	string	账号显示名
supply_source_id / supplier_name	integer / string	所属货源 + 供应商名
provider	string	aws/gcp/azure（来自 supply_source）
external_project_id	string	云厂商侧 ID（AWS account ID / GCP project / Azure subscription）
status	string	active / standby / inactive
order_method	string | null	仅 Azure 账号有意义（MCCL-EA / HK CSP 等下单方式）
customer_codes	string[]	销售系统下发的客户编号，大写归一化；空数组 = 未分配
created_at	string	创建时间 ISO8601

status 派生规则（后端 _recompute_status）：

• inactive（人工停用）→ 不动，最高优先级
• 否则：customer_codes 非空 → active；为空 → standby
• 触发时机：PUT /{id} 带 customer_codes、POST /{id}/activate、POST /customer-assignments/sync 后

---

5.3 GET /api/service-accounts/{account_id}

出参（真实样例，截取）：

{
  "id": 7,
  "name": "AWS-Main",
  "supply_source_id": 2,
  "supplier_id": 3,
  "supplier_name": "神州泰岳",
  "provider": "aws",
  "external_project_id": "675139393309",
  "status": "standby",
  "notes": null,
  "order_method": null,
  "customer_codes": [],
  "secret_fields": ["aws_access_key_id", "aws_secret_access_key", "account_id"],
  "created_at": "2026-04-08T10:19:32.565267",
  "history": [
    { "id": 39, "action": "activated", "from_status": "standby", "to_status": "standby",
      "operator": "xiaohei", "customer_code": null, "notes": null,
      "created_at": "2026-04-18T19:21:38.081899" },
    { "id": 36, "action": "customer_unbound", "from_status": "active", "to_status": "active",
      "operator": "sales", "customer_code": "SYNC_C1", "notes": "sales batch sync",
      "created_at": "2026-04-18T19:10:00.000000" }
  ]
}

列表字段同 §5.2。详情额外字段：

字段	类型	说明
supplier_id	integer	供应商 FK
notes	string | null	账号备注
secret_fields	string[]	账号凭据字段名（不含值）；例如 aws_access_key_id、client_secret
history[]	array	状态变更 + 客户编号变更历史，按 created_at DESC
history[].action	string	见下表
history[].from_status / to_status	string | null	仅状态类事件非空
history[].operator	string | null	触发者用户名；销售系统同步走 "sales-sync"/机器账号名
history[].customer_code	string | null	仅 customer_* 事件非空
history[].notes	string | null	销售批量同步会写 "sales batch sync"

action 枚举：

值	含义
created	创建账号（注：老数据可能记为 assigned）
suspended	人工停用
activated	从停用/备用恢复
customer_bound	绑定一个客户编号
customer_unbound	解除一个客户编号
customer_batch_synced	销售批量同步（此事件单独记录时使用；通常逐个写 bound/unbound）

---

5.4 GET /api/service-accounts/{account_id}/costs

角色：任意登录（已放宽）。

入参（Query）：start_date、end_date（必填，YYYY-MM-DD）。

出参（真实样例，截取）：

{
  "total_cost": 6991.440645000001,
  "total_usage": 5303.442484,
  "services": [
    { "service": "Claude Opus 4.6 (Amazon Bedrock Edition)",
      "cost": 5280.532382, "usage_quantity": 2690.11845, "usage_unit": "Units" },
    { "service": "Claude Sonnet 4.6 (Amazon Bedrock Edition)",
      "cost": 1246.2185079999997, "usage_quantity": 1582.6575039999998, "usage_unit": "Units" }
  ],
  "daily": [
    { "date": "2026-04-01", "cost": 45.23, "usage_quantity": 12.0 }
  ],
  "daily_by_service": [
    { "date": "2026-04-01", "service": "AWS Cost Explorer",
      "cost": 0.01, "usage_quantity": 1.0, "usage_unit": "Requests" }
  ]
}

本接口的 cost/usage 是 JSON number（float）（与 /metering/* 不同）。

字段	说明
total_cost / total_usage	本账号在 date 区间内的汇总
services[].service	产品名（对应 billing_data.product）
services[].usage_unit	该产品的用量单位；该产品有多个单位时，后端取其一
daily[]	按日费用+用量合计
daily_by_service[]	按日 × 服务拆分（用于堆叠图）

---

5.5 GET /api/service-accounts/daily-report

角色：任意登录（前端『统计』页调用，viewer/ops/finance 都可访问）。

入参（Query）：start_date、end_date（必填），provider（可选）。

出参（真实样例）：

[
  {
    "account_id": 88,
    "account_name": "chuhai 自用",
    "provider": "azure",
    "external_project_id": "09e4b3a6-8159-4f14-b108-e4a18ace9212",
    "date": "2026-04-01",
    "product": "Foundry Models",
    "cost": 2.438673
  }
]

每行 = (账号, 日期, 产品) 聚合后的 cost，JSON number（float）。按 date→external_project_id→product 排序。

字段	说明
account_id	本地 projects.id
account_name	账号显示名（本地 projects.name）
provider	aws/gcp/azure
external_project_id	云厂商侧 ID
date / product	账单日期 + 服务
cost	USD

注：此接口的"每条记录按 (账号, 日期, 产品) 聚合"；业务含义是前端『统计』页。物理挂在 service_accounts 路由下，但已做端点级权限区分——只读端点（列表 / 详情 / costs / daily-report）任意登录可用，敏感端点（创建/删除/暂停/恢复/凭据/批量同步）需 cloud_admin。

---

5.6 GET /api/projects/ 与 GET /api/projects/{project_id}

模块：projects，角色：任意登录（读）；写需 cloud_admin。

/api/projects 是老的 Project CRUD，前端不使用。和 /api/service-accounts 指向同一个 projects 表，但返回字段和交互语义略有差异。AI 通常调 service-accounts/ 即可；这组接口仅供历史集成。

列表入参：status、provider、page、page_size。

出参（真实样例，单对象）：

{
  "id": 7,
  "name": "AWS-Main",
  "supply_source_id": 2,
  "provider": "aws",
  "supplier_name": "神州泰岳",
  "external_project_id": "675139393309",
  "data_source_id": 1,
  "category_id": 2,
  "status": "standby",
  "notes": null,
  "created_at": "2026-04-08T10:19:32.565267",
  "updated_at": "2026-04-18T18:53:30.265359"
}

字段	说明
data_source_id	FK → data_sources（对应 /api/data-sources/ 条目）
category_id	FK → categories（费用分类 markup_rate）；可为 null
updated_at	最近一次 update 时间
其它字段	同 §5.2

注意：本接口不返回 customer_codes、order_method、history。需要这些用 /api/service-accounts/{id}。

---

5.7 GET /api/bills/

模块：bills，角色：cloud_finance（含 admin）。

入参（Query）：month（YYYY-MM）、status、page、page_size。

出参：实际调用该账号当月为空 []（尚未生成账单）。字段表（来自后端 schema）：

字段	类型	说明
id	integer	账单 id
month	string	YYYY-MM
category_id	integer	费用分类 FK
provider	string	aws/gcp/azure
original_cost	string/number	原始成本 USD
markup_rate	string/number	加价率（1.0=不加价）
final_cost	string/number	加价后金额
adjustment	string/number	人工调整额（正负皆可）
status	string	draft / confirmed / paid
confirmed_at	string | null	确认时间
notes	string | null	备注
created_at	string	创建时间

---

5.8 GET /api/bills/{bill_id}

单张月度账单详情（同上结构，单对象）。

---

5.9 GET /api/alerts/rule-status

模块：alerts，角色：任意登录。

入参（Query）：month（可选，YYYY-MM，默认当月）。

出参：空数组 []（该环境当前未配置告警规则）。字段表：

字段	类型	说明
rule_id	integer	规则 ID
rule_name	string	规则显示名
threshold_type	string	monthly_budget / daily_budget / growth_rate / monthly_minimum_commitment 等
threshold_value	number	阈值
actual	number	当前实际值
pct	number	actual / threshold_value × 100（增长率类型为差额 %）
triggered	boolean	是否触发
account_name	string	关联的服务账号名（可能为 null，表示全局规则）
provider	string	aws/gcp/azure
external_project_id	string	云厂商侧 ID

---

5.10 GET /api/suppliers/supply-sources/all

模块：suppliers，角色：cloud_admin（整个 suppliers 模块都是 admin）。

入参：supplier_id（可选，过滤某个供应商）。

出参（真实样例）：

[
  { "id": 3, "supplier_id": 1, "supplier_name": "长虹佳华",
    "provider": "azure", "account_count": 3 },
  { "id": 5, "supplier_id": 2, "supplier_name": "内部测试专用",
    "provider": "gcp", "account_count": 1 }
]

字段	说明
id	货源 ID（supply_sources.id）
supplier_id / supplier_name	所属供应商
provider	该货源对应的云
account_count	该货源下的服务账号数

---

5.11 GET /api/metering/products

用途：产品去重列表（下拉/消歧）。

入参：provider、account_id、supply_source_id、supplier_name、data_source_id。

出参（真实样例，截取）：

[
  { "product": "Amazon Simple Notification Service" },
  { "product": "Amazon Simple Queue Service" },
  { "product": "Vertex AI" }
]

单字段 product，排重 + 排序。用于前端 Metering 页的服务过滤下拉。

---

6. P2 可选接口

6.1 GET /api/categories/

角色：cloud_admin（整个 categories 模块 admin-only）。

出参（真实样例）：

[
  { "id": 1, "name": "????", "markup_rate": "1.0000",
    "description": "test",
    "created_at": "2026-04-08T03:43:02.546432",
    "updated_at": "2026-04-08T03:43:02.546432" },
  { "id": 2, "name": "default", "markup_rate": "1.1500",
    "description": "default channel",
    "created_at": "2026-04-08T03:43:28.568331",
    "updated_at": "2026-04-08T10:23:02.934844" }
]

字段	类型	说明
markup_rate	string（Decimal，4 位小数）	加价率
name	string	分类名；历史数据可能含占位符

6.2 GET /api/exchange-rates/

角色：任意登录（读）。入参：date（可选）、from_currency。

出参：数组形如 [{ from_currency, to_currency, rate, date }]；该环境返回 []。

6.3 GET /api/data-sources/

角色：cloud_admin。

出参（真实样例）：

[
  {
    "id": 1,
    "name": "AWS-675139393309",
    "cloud_account_id": 1,
    "category_id": 2,
    "config": { "account_id": "675139393309" },
    "last_sync_at": "2026-04-18T18:00:19.046951",
    "sync_status": "success",
    "is_active": true,
    "created_at": "2026-04-08T03:48:09.812203"
  }
]

字段	说明
config	采集器配置 JSONB；Azure 会有 subscription_id/collect_mode/cost_metric；AWS 仅 account_id
last_sync_at / sync_status	最近一次同步时间与结果

6.4 GET /api/resources/ + GET /api/resources/{id}

角色：任意登录（读）。入参：provider、project_id、resource_type、page、page_size。数据按可见数据源过滤。该环境返回 []。字段表（资源清单 schema）：id、provider、resource_type、resource_id、name、region、project_id、monthly_cost（number，最近一个月估算）、tags。

6.5 GET /api/billing/export / /api/metering/export

CSV 流式下载，大流量，适合工具落盘，不建议作为模型上下文。入参同 detail，响应 Content-Type: text/csv。

---

7. 销售系统专用接口（客户编号下发）

面向"销售系统对接"，AI 大脑不调用。模块：service_accounts；这两条是写操作，需 cloud_admin（service_accounts 只读端点已放宽到任意登录，但写仍然 admin-only）。建议通过 Casdoor client_credentials 拿 token。

7.1 POST /api/service-accounts/customer-assignments/sync

用途：销售系统把"客户编号 ↔ 服务账号"关联批量下发。幂等。

定位键：(supplier_name, provider, external_project_id)。匹配不到的记录进 unmatched 返回，不阻断整批。

入参（Body）：

{
  "mode": "patch",
  "scope_customer_codes": ["C001", "C002"],
  "assignments": [
    {
      "customer_code": "C001",
      "supplier_name": "xxx 供应商",
      "provider": "azure",
      "external_project_id": "5550d5e0-56d3-46b2-8c08-bb9834d8b349"
    }
  ]
}

• mode=patch：只做 upsert，从不删除。推荐作为默认模式。
• mode=full：对 scope_customer_codes 这批做差分（多删少插）。若该字段留空，后端回退为"按 assignments 里出现的客户编号作为 scope"——这种隐式行为建议明确传一份。
• customer_code 自动 upper().strip() 归一化。

出参：

{
  "inserted": 1,
  "deleted": 0,
  "unchanged": 0,
  "unmatched": [
    {
      "customer_code": "C002",
      "supplier_name": "bogus",
      "provider": "azure",
      "external_project_id": "does-not-exist",
      "reason": "service account not found"
    }
  ]
}

7.2 PUT /api/service-accounts/{account_id}（仅 customer_codes 字段）

用途：单个服务账号的客户编号全量覆盖（和 secret_data 同语义：undefined 不动；[] 清空；[...] 替换）。

入参（Body）：

{ "customer_codes": ["C001"] }

出参：整个 ServiceAccountDetail（见 §5.3）。

副作用：

• 新增/删除会写 project_assignment_logs，action=customer_bound / customer_unbound，带 operator。
• 清空或首次绑定都会触发 _recompute_status，自动把 status 从 active → standby 或反向切换。

---

8. 禁止对 AI 开放的接口

以下接口 不应 加入 AI 可调工具列表：

类别	路径	原因
凭据明文	GET /api/service-accounts/{id}/credentials	会解密云账号凭据
写操作	所有 POST / PUT / PATCH / DELETE	含同步触发、账单调整、告警规则变更、服务账号变更等
客户编号分配（销售专用）	POST /api/service-accounts/customer-assignments/sync、PUT /api/service-accounts/{id} 带 customer_codes	仅销售系统走 Casdoor client_credentials 下发；AI 不应写
同步触发	/api/sync/*（除 GET /last）	需 cloud_ops，触发后台任务
Azure 部署	/api/azure-deploy/*	需 cloud_admin，涉及 ARM Token 与资源创建
跨租户授权	/api/azure-consent/*	需 cloud_admin，改订阅授权态
认证管理	/api/admin/users/* · /api/api-keys/* · /api/api-permissions/*	需 cloud_admin，管理员专用

service_accounts 模块混合了只读和凭据接口，如 AI 需要 §5.2–5.5 的数据，工具清单不得包含 /credentials。

---

9. 建议调用顺序

1. GET /api/health → 连通性探测
2. GET /api/auth/me → 确认身份与可见范围
3. GET /api/sync/last → 数据新鲜度
4. GET /api/dashboard/bundle 或 metering/summary → 总览
5. 钻取 → metering/detail + detail/count 分页，或 billing/detail
6. 业务主体 → service-accounts/ 或 projects/
7. 是否超支 → alerts/rule-status

---

10. 各模块权限速查

模块	URL 前缀	所需角色	数据范围过滤
dashboard	/api/dashboard/*	viewer / ops / finance（含 admin）	按可见数据源
billing	/api/billing/*	任意登录	按可见数据源
metering	/api/metering/*	任意登录	支持筛选参数
bills	/api/bills/*	cloud_finance（含 admin）	无
sync	/api/sync/*	cloud_ops（含 admin）	无
cloud_accounts	/api/cloud-accounts/*	读=任意登录；写=cloud_admin	按可见云账号
resources	/api/resources/*	任意登录	按可见数据源
projects	/api/projects/*	读=任意登录；写=cloud_admin	无
alerts	/api/alerts/*	读=任意登录；写告警规则=cloud_ops	无
categories	/api/categories/*	cloud_admin（整个模块）	无
suppliers	/api/suppliers/*	cloud_admin（整个模块）	无
exchange_rates	/api/exchange-rates/*	读=任意登录；写=cloud_admin / cloud_finance	无
data_sources	/api/data-sources/*	cloud_admin（整个模块）	无
service_accounts	/api/service-accounts/*	读=任意登录；写=cloud_admin	无
azure_deploy	/api/azure-deploy/*	cloud_admin	无
azure_consent	/api/azure-consent/*	cloud_admin	无

匿名可访问（不需要任何凭据）：/api/health、/api/auth/*、/docs、/redoc、/openapi.json

---

11. OpenAPI

运行时通过 GET /openapi.json 或 /docs 获取与部署版本一致的 Schema（匿名可访问）。若本文与 OpenAPI 冲突，以 OpenAPI 为准。