后端变量命名专家

首选方案：

• login_location - 登录地，语义直观；适合在日志与DB中统一命名（如列名 login_location）
• device_fingerprint - 设备指纹，避免缩写，跨端含义稳定
• transaction_count_30d - 近30日交易次数，时间窗口后缀 30d 清晰、便于扩展其他窗口
• transaction_amount_30d - 近30日交易总额，金额语义明确，避免 sum/total 歧义
• account_level - 账户等级，适用于等级枚举或数值型
• anomaly_flag - 异常标记，适合日志/DB布尔字段统一（布尔或0/1）
• extended_features - 预留特征扩展字典，便于新增特征不改函数签名
• gray_release_enabled - 灰度开关主控布尔值，命名直观
• gray_bucket - 灰度分组/桶编号（可选），便于按桶灰度

推荐理由：命名完整、无歧义、与日志/表结构可直接一致；数值窗口统一用后缀 30d，布尔在跨层使用 flag，便于ORM与分析查询；同时提供扩展与灰度控制位于参数层，避免频繁变更签名。

备选方案1：

• login_geo - 更偏数据地理属性的表达，适合已标准化行政区编码或Geo字符串
• last_30d_transaction_count - 显式“last_30d”，更贴近时序语义
• last_30d_transaction_amount - 与上保持一致
• account_tier - 若业务更偏“等级档位/层级”概念
• is_anomalous - Python 风格更强的布尔命名，适合仅在代码层使用（DB/日志建议仍用 anomaly_flag）
• extra_features - 若倾向更短的扩展特征命名
• enable_gray_mode - 更口语化的灰度启用开关
• gray_group - 用于分桶/分组的命名等价

适用场景说明：强调Python语义或已有Geo/层级术语沉淀的团队；日志/DB层仍建议保持与首选方案一致以避免混乱。

备选方案2（域前缀风格，适合多域字段避免冲突）：

• risk_login_location
• risk_device_fingerprint
• risk_transaction_count_30d
• risk_transaction_amount_30d
• risk_account_level
• risk_anomaly_flag
• risk_extended_features
• risk_gray_release_enabled
• risk_gray_bucket

适用场景说明：在网关聚合或多域事件日志中避免字段冲突；DB/日志同名直接落库，便于下游数据仓库建模。

• Python snake_case；名词或名词短语为主，布尔在代码层可用 is_*，在日志/DB层建议 *_flag 以统一。
• 时间窗口采用后缀 _30d，避免以数字开头；可平行扩展 _7d、_90d。

• 实体_度量_窗口：transaction_count_30d、transaction_amount_30d
• 实体/属性名：login_location、device_fingerprint、account_level
• 布尔/标记：anomaly_flag、gray_release_enabled
• 扩展容器：extended_features（字典，键为具体特征名）

• login_location → 登录地（国家/省市/区编码或标准化名称）
• device_fingerprint → 设备唯一指纹
• transaction_count_30d → 近30天交易次数
• transaction_amount_30d → 近30天交易总金额
• account_level → 账户等级（数值或枚举）
• anomaly_flag → 上游或历史异常标记
• extended_features → 新增风险特征集合（如近7日退款率、黑名单命中次数等）
• gray_release_enabled / gray_bucket → 灰度控制与分桶

• 变量名可无缝对齐日志字段与DB列名，避免转换层（推荐直接同名落库）。
• 金额字段建议在DB使用 decimal/numeric 类型；在Python使用 Decimal，命名仍为 transaction_amount_30d。

• 统一将时间窗口作为后缀，形成字段族谱，便于指标横向扩展与报表透视。
• 代码层可同时保留 is_anomalous（内部）与 anomaly_flag（外部IO）映射，但外部接口、日志、表结构统一采用 anomaly_flag。
• 扩展特征一律放入 extended_features（dict），新增特征命名沿用相同规范（如 refund_rate_7d、chargeback_count_90d）。

• 一旦对外/落库字段确定，避免改名；新增采用可并行的同族命名（例如新增 transaction_count_7d）。
• 灰度参数灰度桶 gray_bucket 为可选，未参与灰度时置空；灰度策略变更不影响主参数命名。
• 为防止歧义，避免使用 txn、amt、geo 等缩写作为对外/落库命名；若内部使用缩写，务必保持对外映射清晰。

首选方案：TenantBillingConfig

• 推荐理由：直观表达“多租户的计费配置”，后缀 Config 表达配置用途，导出标识符采用 PascalCase，字段语义明确，易于在多服务间复用；配套提供统一的 JSON 键与环境变量命名规则，便于热更新与版本化管理。
• 建议全局变量名：ActiveTenantBillingConfig（表达当前生效配置，契合热更新场景）
• 字段命名（Go 标识符 → JSON 键 → 环境变量）
  • ConfigVersion → configVersion → TENANT_BILLING_CONFIG_VERSION
  • BillingCycle → billingCycle → TENANT_BILLING_BILLING_CYCLE
  • FreeQuota → freeQuota → TENANT_BILLING_FREE_QUOTA
  • UnitPrice → unitPrice → TENANT_BILLING_UNIT_PRICE
  • CurrencyCode → currencyCode → TENANT_BILLING_CURRENCY_CODE
  • StatementCutoffDay → statementCutoffDay → TENANT_BILLING_STATEMENT_CUTOFF_DAY
  • InvoiceTitle → invoiceTitle → TENANT_BILLING_INVOICE_TITLE
  • UpdatedAt（可选，热更新元信息）→ updatedAt → TENANT_BILLING_UPDATED_AT

备选方案1：BillingPolicyV1

• 适用场景：需要在类型层面进行严格版本化控制（并行维护多版本结构，避免同名字段在升级时产生歧义）。
• 建议全局变量名：ActiveBillingPolicy
• 字段命名（Go 标识符 → JSON 键 → 环境变量）
  • Version → version → TENANT_BILLING_VERSION
  • Period → period → TENANT_BILLING_PERIOD
  • FreeTier → freeTier → TENANT_BILLING_FREE_TIER
  • RatePerUnit → ratePerUnit → TENANT_BILLING_RATE_PER_UNIT
  • CurrencyCode → currencyCode → TENANT_BILLING_CURRENCY_CODE
  • ReconciliationCutoffAt → reconciliationCutoffAt → TENANT_BILLING_RECONCILIATION_CUTOFF_AT
  • InvoiceTitle → invoiceTitle → TENANT_BILLING_INVOICE_TITLE

备选方案2：BillingPlanConfig

• 适用场景：组织内部以“Plan（计费方案）”为主的领域语言，强调按“方案”管理配置，字段更贴近产品术语。
• 建议全局变量名：CurrentBillingPlan
• 字段命名（Go 标识符 → JSON 键 → 环境变量）
  • PlanVersion → planVersion → TENANT_BILLING_PLAN_VERSION
  • BillingPeriod → billingPeriod → TENANT_BILLING_BILLING_PERIOD
  • FreeQuotaUnits → freeQuotaUnits → TENANT_BILLING_FREE_QUOTA_UNITS
  • PricePerUnit → pricePerUnit → TENANT_BILLING_PRICE_PER_UNIT
  • CurrencyCode → currencyCode → TENANT_BILLING_CURRENCY_CODE
  • CutoffDay → cutoffDay → TENANT_BILLING_CUTOFF_DAY
  • InvoiceHeader → invoiceHeader → TENANT_BILLING_INVOICE_HEADER

• Go 标识符：PascalCase，导出以便跨包复用（如 TenantBillingConfig.BillingCycle）。
• JSON 键：lowerCamelCase，通用 API 约定，前后端一致性更好（如 billingCycle）。
• 环境变量：UPPER_SNAKE_CASE，统一前缀 TENANT_BILLING_，便于检索与分组（如 TENANT_BILLING_BILLING_CYCLE）。

• 类型后缀：Config/Policy/Plan 表达用途与领域含义；V1 明确结构版本。
• 领域清晰度：
  • BillingCycle/BillingPeriod：计费周期（如 monthly、daily）。
  • FreeQuota/FreeTier/FreeQuotaUnits：免费额度（建议使用单位或范围说明）。
  • UnitPrice/RatePerUnit/PricePerUnit：单价/费率；与 CurrencyCode 搭配避免歧义。
  • CurrencyCode：三位 ISO-4217 代码（如 USD、CNY）。
  • StatementCutoffDay/CutoffDay：对账截止日，强调“日”的语义；若需时间戳则使用 ReconciliationCutoffAt。
  • InvoiceTitle/InvoiceHeader：发票抬头。
  • ConfigVersion/Version/PlanVersion：配置版本号，支持灰度与回滚。

• 多租户：类型名以 Billing + Config/Policy/Plan 组织，保持通用可复用。
• 版本化：Version/ConfigVersion/PlanVersion 字段用于配置版本管理。
• 热更新：Active/Current 前缀的全局变量名表达当前生效实例；UpdatedAt 记录最近更新时间。

• Go 导出字段配合 json 标签可直接序列化为 lowerCamelCase；环境变量名称可由配置加载器做映射。
• 货币与价格：建议 UnitPrice/PricePerUnit 使用十进制字符串或整型最小货币单位（如分、厘），避免浮点精度问题；CurrencyCode 使用 ISO-4217。
• 截止日：StatementCutoffDay 使用 1–31 的整数；若业务需要精确到时间，改用 ReconciliationCutoffAt（time.Time）。

• 统一前缀 TENANT_BILLING_，并在配置中心、文档和仪表盘中保持一致。
• 禁用模糊缩写（如 Cfg、Cur、Rt），采用完整语义（Config、CurrencyCode、UnitPrice）。
• 在 PR 中固定字段顺序与注释，避免 JSON 键漂移；新增字段时保持向后兼容。

• 版本演进：需要重大结构变更时引入新类型后缀（如 BillingPolicyV2），保留旧版本供平滑迁移。
• 热更新：全局变量如 ActiveTenantBillingConfig 建议以 atomic.Value 或 RWMutex 保护；UpdatedAt 与 ConfigVersion 联动校验。
• 多语言与合规：InvoiceTitle 允许 Unicode；如需本地化，保持字段名不变，内容交由上层处理。