"""云成本「成本口径」方法论目录 — 2026-07 成本口径改造 PR5。 单一真源（single source of truth，仿 ``assessment_catalog`` 的模式）： 每朵云一个静态描述符，完整记录研发口径（业务折前成本 / list）是怎么 取数、怎么算的 —— 数据源、白名单规则原文、排除项、禁用列、public/list 语义、调账处理、核验状态与日期、已知边界。财务 / 采购 / 云管理对着 这页自己核对数字，有问题再改规则。 **规则原文是和云管理团队核验定稿的文本，改语义前必须重新核验**（见 各条目 ``verified_at``）。描述符内容是中文运营文档（后端数据，同 ``assessment_catalog`` / ``compliance_catalog`` 先例），不走前端 i18n； 前端只翻译页面骨架标签。 保密红线：本目录只含规则文字与核验记录，**不含任何实付金额、不泄露 折扣率** —— ``can_read_cloud`` 即可读。当月两口径对数区（list/invoice 合计与差值分桶）由 router 层单独拼装，仅对保密圈 （:func:`app.domains.cmdb.cost_view.can_view_invoice_measure`）返回。 Pure data — stdlib-only. """ from __future__ import annotations from typing import Any # 核验状态闭集（前端徽章）: # verified 已核验 —— 白名单规则已用真实账单核验定稿 # semi_verified 半核验 —— 规则已实现，个别口径点待云管理确认 # rules_ready 规则已实现 —— 等数据源开通（PR6 后的 Azure） # pending 待接入 —— 现状为折后实付，研发口径未接 # out_of_scope 不在本次范围 —— 未接账单 VERIFICATION_STATUSES: tuple[str, ...] = ( "verified", "semi_verified", "rules_ready", "pending", "out_of_scope", ) # 每个条目的字段： # key 稳定机器键（前端锚点 / 对数区 join 键） # provider cmdb integrations.provider 值（对数区按此 join； # None = 无账单数据可对） # title 展示标题（中文，运营文档） # verification_status 上面闭集之一 # verified_at 核验日期（YYYY-MM-DD;未核验为 None） # data_source 取数链路描述 # list_rule 研发口径（list）白名单规则原文 —— 云管理团队定稿， # 不要改写语义 # public_rule public（按需牌价）语义 # exclusions 排除项（一律不计入研发口径的行类型/列） # forbidden_columns 禁用列（含合同折扣、绝不能进研发口径的列） # adjustment_handling 调账/冲正处理 # known_boundaries 已知边界（对账须知） # pending_confirmations 待云管理确认的口径点（空 = 无） CLOUD_METHODOLOGIES: list[dict[str, Any]] = [ { "key": "aws_org", "provider": "aws", "title": "AWS 主 Org（BigQuery CUR）", "verification_status": "verified", "verified_at": "2026-07-27", "data_source": ( "BigQuery CUR 导出，dataset gcp-digital-bi.aws_billing_no_payer" "（CUR 2.0 / Data Exports，按月分表，含全部 linked account）。" ), "list_rule": ( "list = line_item_line_item_type ∈ {Usage, SavingsPlanCoveredUsage} " "的 line_item_unblended_cost（SP 覆盖行 unblended 实测==按需等价，" "样本周 $430,590.57 两列一致）；未来有 RI 时 DiscountedUsage 用 " "pricing_public_on_demand_cost 还原。" ), "public_rule": "public = 白名单行的 pricing_public_on_demand_cost。", "exclusions": [ "SavingsPlanNegation", "SavingsPlanRecurringFee", "SavingsPlanUpfrontFee", "RIFee", "Fee", "Credit", "Refund", "Tax", "Discount", "BundledDiscount", "FlatRateSubscription", "（白名单制：以上及一切未知新类型默认出局）", ], "forbidden_columns": [], "adjustment_handling": ( "Credit / Refund / Discount 等只留在发票口径（财务瀑布分桶），" "绝不参与研发口径。" ), "known_boundaries": [ "CUR 导出不含 payer 账号（无权限）；Support 与 AWS 侧 credit " "多记在 payer —— 对账须计入该范围差。", "SP 集中购买账号 380838443567 仅财务页显示。", "目前无 RI（DiscountedUsage 还原分支为预留）。", "行级（cost_facts）合计比日汇总（billing_daily）低约 0.7–1.0%：" "净额为 0 的分组不落行（SP 覆盖行与冲正行配平后），日汇总走" "更宽的重取窗口 —— 属既有口径差，非缺数（2026-07-28 回填后" "逐月复核稳定在该区间）。", ], "pending_confirmations": [], }, { "key": "aws_sg", "provider": "aws", # 注意与主 Org 同 provider；对数区按 integration 区分不了时合并展示 "title": "AWS SG（Cost Explorer）", "verification_status": "verified", "verified_at": "2026-07-27", "data_source": ( "AWS Cost Explorer API（无 CUR 导出的单账号/SG org；" "per-resource + principal-tag + 日汇总三条查询路径）。" ), "list_rule": ( "per-resource 行天然白名单纯净（折扣行无 RESOURCE_ID，已被跳过）" "→ list == unblended；principal-tag 与 billing_daily 走 " "RECORD_TYPE=Usage 白名单遍。" ), "public_rule": ( "CE 无公开牌价度量 → public 恒 NULL（SG 无 spot，无损失）。" ), "exclusions": [ "RECORD_TYPE ∈ {Credit, Tax, Refund, …}（非 Usage 一律不计）", ], "forbidden_columns": [], "adjustment_handling": ( "Credit / Tax 只留在发票口径；纯 credit 单元按符号归桶，" "list=None。" ), "known_boundaries": [ "SG 无 SP/RI（2026-06 实测）；未来若买 RI，CE 无法还原 " "DiscountedUsage 牌价，须切 CUR。", ], "pending_confirmations": [], }, { "key": "gcp", "provider": "gcp", "title": "GCP（BigQuery 账单导出）", "verification_status": "verified", "verified_at": "2026-07-27", "data_source": ( "BigQuery 账单导出，3 张 gcp_billing_export_v1_* 表" "（Default / FCUD 1Y / FCUD 3Y 三种 consumption_model）。" ), "list_rule": ( "list = cost_at_list，白名单 cost_type='regular' AND service ∉ " "{Support, Invoice} AND cost_at_list IS NOT NULL；Marketplace " "计入；三种 consumption_model（Default/FCUD 1Y/3Y）都保留；" "Spot/抢占式已按官方 Spot SKU 牌价；负数冲正保留；credits " "完全不参与。已验证 2026-05 全月 list = $910,010.34。" ), "public_rule": ( "GCP 牌价即 cost_at_list（public == list；spot 已按 Spot SKU " "牌价，无独立按需还原列）。" ), "exclusions": [ "cost_type ≠ 'regular'（tax / adjustment / rounding_error）", "service ∈ {Support, Invoice}（单独统计，财务页）", "credits[]（全部类型，完全不参与研发口径）", ], "forbidden_columns": [ "cost（已折入合同价，2026-05 实测 −21%）", "cost_at_effective_price_default", "cost_at_list_consumption_model", "price.effective_price", "price.list_price_consumption_model", ], "adjustment_handling": ( "usage 行存税前毛额；credits 按 (day×project×type) 合成独立" "负数行进财务瀑布分桶（PROMOTION→credit 桶、" "FEE_UTILIZATION_OFFSET→commitment_discount 等，见 " "gcp_cloud.py 的 _GCP_CREDIT_TYPE_BUCKETS）；负数冲正保留。" ), "known_boundaries": [ "Support / Invoice 单独统计（财务页），不在研发口径。", "无项目归属行（project.id IS NULL，多为账单级调整/税费载体）" "无法落到某个子账号，因此不进 facts/billing_daily —— " "2026-05 实测：BQ 白名单总额 $910,010.34 中此类 $4,190.44" "（0.46%），平台侧可归属额 $905,819.91（2026-07-28 回填对齐）。", ], "pending_confirmations": [], }, { "key": "aliyun_intl", "provider": "aliyun", "title": "阿里云国际站（BSS DescribeInstanceBill）", "verification_status": "semi_verified", "verified_at": "2026-07-27", "data_source": ( "阿里云 BSS OpenAPI DescribeInstanceBill（按实例账单，" "intl 站点按行币种换算）。" ), "list_rule": ( "list = PretaxGrossAmount（牌价）；Item 字段分类：" "SubscriptionOrder / PayAsYouGoBill → usage；" "Refund / Adjustment → adjustment。" ), "public_rule": "阿里牌价即 PretaxGrossAmount（public == list）。", "exclusions": [ "Item ∈ {Refund, Adjustment}（→ adjustment 桶，只在财务瀑布）", "未知 Item 类型 → other 桶，绝不误入 usage", ], "forbidden_columns": [ "PretaxAmount（折后实付 —— 缺牌价绝不用实付兜底，计数告警）", ], "adjustment_handling": ( "Refund/Adjustment 归 adjustment 桶 —— 2026 YTD 调账 −$21.5 万" "集中在 5/25、7/21 处理日；缺牌价行聚合计数 → WARN 告警核查。" ), "known_boundaries": [], "pending_confirmations": [ "抢占式实例在 PretaxGrossAmount 里按 spot 实价还是标准价记账", "PretaxGrossAmount 是否纯牌价（有无价内折扣已折入）", ], }, { "key": "azure", "provider": "azure", "title": "Azure（Cost Management → Cost Exports）", # PR6 已落白名单规则/分类器/数据面适配层（azure_cloud.py # billing_source='exports'），只差真实拉取器等 Exports 开通。 "verification_status": "rules_ready", "verified_at": None, "data_source": ( "现状：Cost Management Query API ActualCost（EA/MCA 折后价）。" "目标：Cost Exports（storage account CSV/parquet），研发口径 = " "payg_cost_in_billing_currency 白名单 —— 规则已实现" "（azure_cloud.py billing_source='exports'），等云管理开通" "导出后接真实拉取器。" ), "list_rule": ( "规则已实现，等 Exports 开通 —— 开通前研发面显示为折后实付" "（ActualCost），list 恒 NULL。规则：list = " "payg_cost_in_billing_currency，白名单 charge_type='Usage'" "（OnDemand/Spot/RI/SP 覆盖行都保留，RI/SP 覆盖行以 PAYG 价" "还原）+ 非承诺类 Purchase（Power BI、Marketplace 等，" "pricing_model ∉ {Reservation, SavingsPlan} 且 reservation_id " "/ benefit_id 为空）。" ), "public_rule": "Exports 接入后 public 待评估（PAYG 价即近似牌价）。", "exclusions": [ "RI/SP 购买行", "UnusedReservation / UnusedSavingsPlan", "Refund / Credit / RoundingAdjustment / 税费", "Microsoft Support（单独统计）", "（白名单制：未知新 charge_type 默认出局）", ], "forbidden_columns": [ "cost_in_billing_currency（含合同价）", "effective_price（含合同价）", "unit_price（含合同价）", ], "adjustment_handling": ( "PAYG 缺失行不得用实际成本兜底，单独告警核查。" ), "known_boundaries": [ "Exports 尚未开通；开通前研发面 Azure 数字 = 折后实付" "（COALESCE 回落），非业务折前口径。", "Exports 落 storage account（CSV/parquet），读取方式待云管理" "开通后确定 —— 配置面（exports_storage_account 等）已预留。", ], "pending_confirmations": [], }, { "key": "other_clouds", "provider": None, "title": "腾讯云 / 金山云 / UCloud", "verification_status": "out_of_scope", "verified_at": None, "data_source": "未接账单。", "list_rule": "不在本次范围 —— 未接账单，无研发口径。", "public_rule": "无。", "exclusions": [], "forbidden_columns": [], "adjustment_handling": "无。", "known_boundaries": [], "pending_confirmations": [], }, ] # 跨云共享边界（不属于单朵云，前端在页头统一展示）。 SHARED_BOUNDARIES: list[str] = [ "已关停（status=closed）的子账号/项目：摄取链路只取 active 子账号，" "所以它们的历史花费保持「实付有值、研发口径为空」。2026-07-28 全量" "回填后实测仅 2 个（AWS 757842878326 约 $330、GCP gcp-web3bench 约 " "$26），合计约占月度云花费的 0.01%。", "行级（cost_facts）与日汇总（billing_daily）之间存在约 1% 的口径差 " "——净额为 0 的分组不落行、日汇总重取窗口更宽。对账请在同一粒度内比。", ] def get_methodology_catalog() -> list[dict[str, Any]]: """返回条目列表（浅拷贝，防调用方原地改静态数据）。""" return [dict(entry) for entry in CLOUD_METHODOLOGIES]