# -*- coding: utf-8 -*- """DAMA 数据质量治理规则可配置项（财务七规则）—— 单一事实源 + 三层解析 任务：ASK-20260928-05（任总 2026-09-28 13:38「放行 4 和 5」，本项目 Bot 转呈） 来源清单：wecom-dama《财务七规则可配置化 — 可配置项清单 + 建议默认值 + 权限/留痕建议》 （`wecom-dama/pending-tasks/_reports/project-20260923-quality-rules-config-inventory-dama.md`） 本模块承担三件事（唯一来源，勿在别处复制常量） ---------------------------------------------- 1. **开放面**：37 个规则级参数（`SPEC`）+ 2 个全局项（`GLOBAL_SPEC`）。清单 §3 逐条落成代码； 测试断言项数 = 37 / 2，防后续会话漏项或私自扩面。 2. **锁死面**：清单 §4 的 10 类（判定表达式本体 / 级别归属 / 评分函数 / 实体作用域 / 规则集与数量 / 匹配方式自由化 / kpi_completeness 口径源 / `entity_id IS NULL` 处置 / Bot 通道写配置 / 越界权重）——不在 SPEC 里的键一律 400（写端点）， `LOCKED_PARAM_KEYS` 仅用于把「锁死」讲清楚（可读文案），不是白名单。 3. **三层解析**：账套行（`entity_id`）→ 模板行（`entity_id=0`）→ 代码内置默认； **禁止跨账套回退**（历史事故：`cash.current_balance` 全局键被全账套共用）。 口径（任总 2026-09-28 放行原文：「口径用清单默认值」） ---------------------------------------------------- * 默认值 = 清单 §7「建议默认值」总表，即「现行值，上线零行为差异」， **例外一**：`virtual_pollution.suspect_keywords` 去掉 `sync` （`zxt-sync` 是酣客生产同步来源，现行 134 行 100% 假阳性）——ASK-05 的行为变更； * 演示/测试账套（3/4/5/6）**不开配置**（`CONFIG_ENTITIES = (1, 2)`，清单 §6.4 + ASK-05 口径②）； 读路径仍按三层解析返回生效值（模板/内置默认），只是写端点拒绝。 * **例外二（2026-09-29 尾项，ASK-05 ③-2 拍板「排除」）**：`scope.excluded_entities` 出厂默认 `[3,4,5,6]`，且**已接线** —— 全账套（经营）口径 `entity_id=0` 的评分与明细 不再计入这些账套的行（判据见 `app/api/data_quality.py::_excluded_clause`）。 单账套查询仍可查看（DAMA §6.4「参与检查展示」），只计 `excluded_from_business_caliber=True`。 名单为**参数化**：改本配置值即可调整（零代码回退）。 配置值一律以 JSON 字符串落库（`param_value`），`value_type` 记录类型以便前端/审计呈现。 """ from __future__ import annotations import hashlib import json import logging from typing import Any, Dict, List, Optional, Tuple from sqlalchemy import inspect from sqlalchemy.orm import Session logger = logging.getLogger("cma.dq.rule_config") #: 表名（DDL 走部署链特权迁移步 `backend/scripts/db_migrate.py --apply`，属生产写审批范围） TABLE_NAME = "quality_rule_config" #: 全账套模板行的 entity_id（0 = 模板，不参与具体账套取数） TEMPLATE_ENTITY_ID = 0 #: 开放配置写入的真实账套（口径②：演示/测试账套不开配置） CONFIG_ENTITIES: Tuple[int, ...] = (1, 2) #: 内置默认明细展示条数（清单 §3.9 全局项 `detail_limit` 的出厂值） DEFAULT_DETAIL_LIMIT = 10 #: 写配置必须带变更理由，最短长度（清单 §5.1「反刷分约束」第 1 条） MIN_REASON_LEN = 10 RULE_KEYS: Tuple[str, ...] = ( "unit_check", "dup_alert", "orphan_check", "virtual_pollution", "entity_check", "kpi_completeness", "reconciliation", ) # 全局项（清单 §3.9）：platform 级，仅 it 可写 GLOBAL_RULE_KEY = "global" # 规则级参数统一三件套（每条规则都有；`detail_limit` 为 platform 级） _CAPS = { "deduct_cap": dict(type="int", default=15, open_level="entity", bounds=(0, 50), overflow="clamp", desc="本规则扣分上限（0 = 只报不计分）"), "deduct_factor": dict(type="int", default=3, open_level="entity", bounds=(0, 10), overflow="clamp", desc="本规则每命中一条的扣分系数"), } _WARN_CAPS = { "deduct_cap": dict(type="int", default=10, open_level="entity", bounds=(0, 50), overflow="clamp", desc="本规则扣分上限（0 = 只报不计分）"), "deduct_factor": dict(type="int", default=1, open_level="entity", bounds=(0, 10), overflow="clamp", desc="本规则每命中一条的扣分系数"), } _DETAIL_LIMIT = dict(type="int", default=DEFAULT_DETAIL_LIMIT, open_level="platform", bounds=(1, 100), overflow="clamp", desc="本规则明细展示条数（平台级，仅 it 可写）") _ENABLED = dict(type="bool", default=True, open_level="entity", desc="启用开关（关闭后该规则不参与评分，明细不再展示）") #: 7 条规则的开放参数（37 项；清单 §3.1–§3.7 逐条落成） SPEC: Dict[str, Dict[str, dict]] = { "unit_check": { "enabled": dict(_ENABLED), "amount_threshold": dict(type="int", default=10000, open_level="entity", bounds=(100, 1000000), overflow="reject", desc="金额阈值（万元）：cash_plans.amount > 阈值 即命中（越界拒绝）"), **_CAPS, "detail_limit": dict(_DETAIL_LIMIT), }, "dup_alert": { "enabled": dict(_ENABLED), "min_count": dict(type="int", default=2, open_level="entity", bounds=(2, 20), overflow="reject", desc="同一 plan_id 的 pending 预警条数下限（≥ 该值即重复；越界拒绝）"), **_CAPS, "detail_limit": dict(_DETAIL_LIMIT), }, "orphan_check": { "enabled": dict(_ENABLED), **_CAPS, "detail_limit": dict(_DETAIL_LIMIT), }, "virtual_pollution": { "enabled": dict(_ENABLED), "suspect_keywords": dict( type="json", default=["test", "虚拟", "demo"], open_level="entity", max_items=20, item_max_len=32, forbidden_chars="%_", desc="嫌疑关键词表（大小写不敏感包含式匹配；不含 sync —— 本单唯一行为变更）"), "source_whitelist": dict( type="json", default=["zxt-sync", "bohai_ar", "bohai_ar_20260630", "bohai_prepay_20260630", "bohai_ap_20260630", "receivables_migrate"], open_level="entity", max_items=20, item_max_len=32, forbidden_chars="%_", desc="来源白名单（豁免优先于关键词：命中即不算污染）"), "manual_source_value": dict(type="str", default="manual", open_level="entity", max_len=50, desc="「待人工确认」的来源值（非污染，按 warning 附加扣分）"), **_CAPS, "manual_cap": dict(type="int", default=10, open_level="entity", bounds=(0, 30), overflow="clamp", desc="待人工确认（manual）附加上限"), "manual_factor": dict(type="int", default=1, open_level="entity", bounds=(0, 5), overflow="clamp", desc="待人工确认（manual）附加系数"), "detail_limit": dict(_DETAIL_LIMIT), }, "entity_check": { "enabled": dict(_ENABLED), **_CAPS, "detail_limit": dict(_DETAIL_LIMIT), }, "kpi_completeness": { "enabled": dict(_ENABLED), **_WARN_CAPS, "detail_limit": dict(_DETAIL_LIMIT), }, "reconciliation": { "enabled": dict(_ENABLED), "diff_threshold_pct": dict(type="float", default=20, open_level="entity", bounds=(1, 200), overflow="reject", desc="预算月度合计 vs 年度目标差异阈值（%）；越界拒绝"), "compare_mode": dict(type="enum", default="abs", open_level="entity", enum=("abs", "upper_only", "lower_only"), desc="比较方向：abs=双侧 / upper_only=仅超目标 / lower_only=仅低于目标"), **_WARN_CAPS, "detail_limit": dict(_DETAIL_LIMIT), }, } #: 全局项 key（经营口径排除名单，F6 / ASK-05 ③-2） EXCLUDED_ENTITIES_KEY = "scope.excluded_entities" #: `resolve()["scope"]` / GET 响应里排除名单的**字段名**（短名）。 #: 两者不同名是历史形态：配置项 key 带 `scope.` 前缀（落库/写端点用）， #: 响应 `scope` 段是「已按前缀归组」后的字典 ⇒ 取值为短名。 EXCLUDED_ENTITIES_FIELD = "excluded_entities" #: 全局项（2 项；清单 §3.9） GLOBAL_SPEC: Dict[str, dict] = { "detail_limit": dict(_DETAIL_LIMIT), EXCLUDED_ENTITIES_KEY: dict( type="json", default=[3, 4, 5, 6], open_level="platform", max_items=20, item_max_len=6, desc="排除出「经营口径」评分与播报的账套（3=测试企业 / 4=VerifyCorp / 5=VerifyTest / " "6=演示企业）。已接线：全账套口径（entity_id=0）的评分与明细不再计入这些账套的行；" "单账套查询仍可查看（展示），但标记「不计入经营口径」。写权限仅 it（平台级）；" "改本配置值即可调整名单（零代码回退）"), } # ── 锁死面（清单 §4；仅用于给出可读文案，非白名单）───────────────────────── LOCKED_ITEMS: Tuple[dict, ...] = ( dict(key="expression", item="判定表达式本体（字段/算子/SQL 片段/正则）", reason="表达式可配 = 治理规则可被一次配置改成永久绿灯"), dict(key="level", item="级别归属（error/warning）", reason="级别直接决定扣分上限，降级是最廉价的绕分路径；确有差异请用已开放的扣分权重表达"), dict(key="score_fn", item="评分函数（max(0,100−Σ)、7 条固定、各规则独立封顶后累加、无总封顶）", reason="评分是跨规则/跨期可比的口径基线"), dict(key="entity_scope", item="实体作用域语义（规则 1 用 cash_plans.entity_id；2/3/6/7 用 kpi_definitions.entity_id；5 用 kpi_values.entity_id）", reason="作用域 = 安全边界，开放会引入跨账套借用通路"), dict(key="rule_set", item="规则 key 集合与规则数量（固定 7 条）", reason="规则集是治理骨架，新增规则必须走代码评审"), dict(key="match_mode", item="匹配方式自由化（关键词升级为正则/SQL 片段）", reason="注入面 + 不可验证；匹配方式固定为大小写不敏感包含式"), dict(key="completeness_caliber", item="kpi_completeness 口径源 kpi_definitions.status='active'（含豁免名单 exempt_kpi_codes）", reason="KPI 存废开关已是 status，再加豁免名单 = 双开关口径分裂"), dict(key="null_entity_policy", item="规则5 kpi_values.entity_id IS NULL 行的处置", reason="NULL 语义未裁定前保持 ignore"), dict(key="bot_write", item="Bot 通道（X-BOT-KEY）写配置", reason="Bot 通道无 users 行 → 无操作人可留痕 = 审计断链"), dict(key="weight_range", item="负系数 / 超大上限 / 非整数权重", reason="负系数会变成加分（可刷分）；一律钳制到开放区间"), ) #: 键名 → 锁死文案（写端点遇到这些 param_key 时给「锁死」提示而非笼统的未知参数） LOCKED_PARAM_KEYS = {it["key"]: it for it in LOCKED_ITEMS} # 常见别名（历史/前端习惯叫法）→ 锁死项 key _LOCKED_ALIASES = { "expr": "expression", "predicate": "expression", "sql": "expression", "rule_level": "level", "severity": "level", "score": "score_fn", "score_func": "score_fn", "total_deduct_cap": "score_fn", "exempt_kpi_codes": "completeness_caliber", "status_source": "completeness_caliber", "entity_id_source": "entity_scope", "scope_field": "entity_scope", "rules": "rule_set", "rule_keys": "rule_set", "rule_count": "rule_set", "match_regex": "match_mode", "regex": "match_mode", "pattern": "match_mode", "null_policy": "null_entity_policy", } OPEN_LEVEL_ENTITY = "entity" OPEN_LEVEL_PLATFORM = "platform" # ══════════════════════════════════════════════════════════════════ # 参数查找 / 校验 # ══════════════════════════════════════════════════════════════════ def is_global_param(rule_key: str) -> bool: return rule_key == GLOBAL_RULE_KEY def spec_of(rule_key: str) -> Dict[str, dict]: """返回某 rule_key 的参数规格表（全局项用 rule_key='global'）。""" if is_global_param(rule_key): return GLOBAL_SPEC return SPEC.get(rule_key) or {} def param_spec(rule_key: str, param_key: str) -> Optional[dict]: return spec_of(rule_key).get(param_key) def all_param_pairs() -> List[Tuple[str, str]]: """(rule_key, param_key) 全量清单——37 规则级 + 2 全局项。""" pairs = [(r, p) for r in RULE_KEYS for p in SPEC[r]] pairs += [(GLOBAL_RULE_KEY, p) for p in GLOBAL_SPEC] return pairs def count_rule_params() -> int: """规则级开放参数项数（断言用，清单 §10.2 = 37）。""" return sum(len(SPEC[r]) for r in RULE_KEYS) def open_level_of(rule_key: str, param_key: str) -> str: spec = param_spec(rule_key, param_key) or {} return spec.get("open_level") or OPEN_LEVEL_ENTITY def value_type_of(rule_key: str, param_key: str) -> str: spec = param_spec(rule_key, param_key) or {} return spec.get("type") or "json" def dumps_value(value: Any) -> str: """统一序列化（落库格式；bool/int/float/str/数组一律 JSON）。""" return json.dumps(value, ensure_ascii=False) def loads_value(raw: Any, value_type: str = "") -> Any: """反序列化；非 JSON 的历史/手写行容错（返回 None 表示不可用 → 上层回落）。""" if raw is None: return None if isinstance(raw, (int, float, bool, list, dict)): return raw try: return json.loads(str(raw)) except (ValueError, TypeError): text = str(raw) if value_type == "int": try: return int(float(text)) except (ValueError, TypeError): return None if value_type == "float": try: return float(text) except (ValueError, TypeError): return None if value_type == "bool": if text.strip().lower() in ("1", "true", "yes"): return True if text.strip().lower() in ("0", "false", "no"): return False return None if value_type == "str": return text return None def _coerce_type(value: Any, spec: dict) -> Tuple[bool, Any]: """类型强转（拒绝型：类型不符 → 不可用）。bool 与 int 严格区分（Python 里 bool 是 int 子类）。""" t = spec.get("type") or "json" if t == "bool": if isinstance(value, bool): return True, value if isinstance(value, str) and value.strip().lower() in ("true", "false"): return True, value.strip().lower() == "true" if isinstance(value, int) and value in (0, 1): return True, bool(value) return False, None if t == "int": if isinstance(value, bool): return False, None if isinstance(value, int): return True, value if isinstance(value, float) and float(value).is_integer(): return True, int(value) if isinstance(value, str): s = value.strip() try: return True, int(s) except ValueError: return False, None return False, None if t == "float": if isinstance(value, bool): return False, None if isinstance(value, (int, float)): return True, float(value) if isinstance(value, str): try: return True, float(value.strip()) except ValueError: return False, None return False, None if t == "str": if not isinstance(value, str): return False, None return True, value if t == "enum": if not isinstance(value, str): return False, None return True, value.strip() if t == "json": if not isinstance(value, list): return False, None return True, value return False, None def validate_param(rule_key: str, param_key: str, value: Any) -> dict: """参数级校验（清单 §3 的「取值边界 / 越界处理」逐条落地）。 返回 ``{"ok": bool, "value": <规范化值>, "error": str|None, "warning": str|None}``； 越界处理两类：``reject``（400，附区间文案）/ ``clamp``（钳制到端点 + 响应告警）。 """ spec = param_spec(rule_key, param_key) if spec is None: locked = LOCKED_PARAM_KEYS.get( param_key, LOCKED_PARAM_KEYS.get(_LOCKED_ALIASES.get(param_key, "")) ) if locked: return dict(ok=False, value=None, error=f"参数 {param_key} 属锁死项「{locked['item']}」，不允许配置：{locked['reason']}", warning=None) return dict(ok=False, value=None, error=f"未知参数 rule={rule_key} param={param_key}；" f"可选: {', '.join(spec_of(rule_key).keys()) or '（该规则无开放参数）'}", warning=None) passed, value = _coerce_type(value, spec) if not passed: return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 类型非法：要求 {spec.get('type')}", warning=None) caution = None if spec.get("type") == "enum": if value not in tuple(spec.get("enum") or ()): return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 取值非法：仅支持 {', '.join(spec['enum'])}", warning=None) return dict(ok=True, value=value, error=None, warning=None) if spec.get("type") == "json": max_items = int(spec.get("max_items") or 0) item_max_len = int(spec.get("item_max_len") or 0) forbidden = spec.get("forbidden_chars") or "" if max_items and len(value) > max_items: return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 元素过多：上限 {max_items} 项（当前 {len(value)}）", warning=None) cleaned: List[str] = [] for it in value: if not isinstance(it, str): if spec.get("item_max_len") == 6 and isinstance(it, int) and not isinstance(it, bool): it = str(it) # scope.excluded_entities：账套号允许传 int else: return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 仅允许字符串数组元素", warning=None) s = it.strip() if not s: return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 不允许空串元素", warning=None) if item_max_len and len(s) > item_max_len: return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 元素过长：单元素上限 {item_max_len} 字符（{s}）", warning=None) if any(ch in s for ch in forbidden): return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 元素含非法字符 {forbidden}（不支持通配符/自由模式）", warning=None) cleaned.append(s) # 去重保序（重复项无意义且会让 LIKE 子句膨胀） seen, uniq = set(), [] for s in cleaned: if s not in seen: seen.add(s) uniq.append(s) if len(uniq) != len(cleaned): caution = f"{rule_key}.{param_key} 已去重：{len(cleaned)} → {len(uniq)} 项" return dict(ok=True, value=uniq, error=None, warning=caution) if spec.get("type") == "str": max_len = int(spec.get("max_len") or 0) s = value if not s.strip(): return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 不允许空串", warning=None) if max_len and len(s) > max_len: return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 过长：上限 {max_len} 字符", warning=None) return dict(ok=True, value=s, error=None, warning=None) bounds = spec.get("bounds") if bounds: lo, hi = bounds if value < lo or value > hi: if spec.get("overflow") == "clamp": clamped = min(max(value, lo), hi) logger.warning("DQ_RULE_CONFIG_CLAMPED %s.%s %s → %s（区间 [%s, %s]）", rule_key, param_key, value, clamped, lo, hi) return dict(ok=True, value=clamped, error=None, warning=f"{rule_key}.{param_key} 越界已钳制到区间端点：{value} → {clamped}" f"（允许区间 [{lo}, {hi}]）") return dict(ok=False, value=None, error=f"{rule_key}.{param_key} 越界：允许区间 [{lo}, {hi}]，收到 {value}", warning=None) return dict(ok=True, value=value, error=None, warning=None) # ══════════════════════════════════════════════════════════════════ # 经营口径排除名单（F6 / ASK-05 ③-2「排除演示账套」）—— 单一事实源 # ══════════════════════════════════════════════════════════════════ def normalize_entity_ids(raw: Any) -> List[int]: """把配置里的账套号规范成 int 列表（去重保序；不可解析的元素忽略 = 视为不排除）。""" out: List[int] = [] for v in raw or []: try: n = int(v) except (TypeError, ValueError): continue if n < 0 or n in out: continue out.append(n) return out def excluded_entities_from_resolution(resolution: Optional[dict]) -> List[int]: """从 `resolve()` 结果里取经营口径排除名单（唯一取值口）。 ⚠ 兼容两种字段形态：`scope` 段由 `_assemble()` 按前缀归组 ⇒ 短名 （`EXCLUDED_ENTITIES_FIELD`）；直接取配置项全名的情况也接受。 缺失字段名会让本函数静默返回空集（= 排除名单形同未接线），故两种都查。 """ scope = (resolution or {}).get("scope") or {} raw = scope.get(EXCLUDED_ENTITIES_FIELD) if raw is None: raw = scope.get(EXCLUDED_ENTITIES_KEY) return normalize_entity_ids(raw) def excluded_entity_ids(db: Session, entity_id: int = TEMPLATE_ENTITY_ID) -> List[int]: """按账套三层解析后取排除名单（供引擎/播报侧单一来源引用）。 读路径绝不 500：解析异常 → 返回内置默认（`resolve()` 内部已做容错，此处再兜一层）。 """ try: return excluded_entities_from_resolution(resolve(db, entity_id)) except Exception as exc: # noqa: BLE001 logger.warning("DQ_SCOPE_EXCLUDED_RESOLVE_FAILED entity=%s: %s → 用内置默认", entity_id, exc) return normalize_entity_ids(GLOBAL_SPEC[EXCLUDED_ENTITIES_KEY].get("default")) def is_excluded_from_business_caliber(entity_id: Any, excluded: Any) -> bool: """单个账套是否被排除出经营口径（entity_id 为空/0 → False，不排除默认账套）。""" try: eid = int(entity_id or 0) except (TypeError, ValueError): return False return bool(eid) and eid in set(normalize_entity_ids(excluded)) # ══════════════════════════════════════════════════════════════════ # 读路径：三层解析 # ══════════════════════════════════════════════════════════════════ def table_ready(db: Session) -> bool: """配置表是否就绪（DDL 未落地时**不得**让读路径 500：回落内置默认）。""" try: return bool(inspect(db.get_bind()).has_table(TABLE_NAME)) except Exception as exc: # noqa: BLE001 logger.warning("DQ_RULE_CONFIG_TABLE_PROBE_FAILED %s: %s", TABLE_NAME, exc) return False def _load_rows(db: Session, entity_id: int) -> Dict[Tuple[str, str], dict]: """读模板行 + 本账套行（一次查询）；返回 {(rule_key, param_key): {entity_id, value, raw, row}}。""" from app.models import QualityRuleConfig eids = [TEMPLATE_ENTITY_ID] if entity_id != TEMPLATE_ENTITY_ID: eids.append(entity_id) rows = db.query(QualityRuleConfig).filter(QualityRuleConfig.entity_id.in_(eids)).all() out: Dict[Tuple[str, str], dict] = {} for row in rows: vt = value_type_of(row.rule_key, row.param_key) val = loads_value(row.param_value, vt) if val is None: logger.warning("DQ_RULE_CONFIG_ROW_UNPARSABLE id=%s %s.%s value=%r → 忽略该行（回落下一层）", row.id, row.rule_key, row.param_key, row.param_value) continue out[(row.rule_key, row.param_key)] = { "entity_id": row.entity_id, "value": val, "row": row, } return out def resolve(db: Session, entity_id: int) -> dict: """三层解析当前生效配置（账套行 → 模板行 → 内置默认；**不跨账套回退**）。 返回结构（前端/审计/引擎共用）:: {"entity_id": 1, "config_version": "…", "table_ready": True, "rules": {rule_key: {param_key: {"value":…, "source": "entity|template|builtin", "open_level":…, "desc":…, "updated_by":…, "updated_at":…}}}, "global": {...同 rules 的形状…}, "values": {rule_key: {param_key: <裸值>}}, # 引擎侧取值口 "scope": {"excluded_entities": [...]}} """ eid = int(entity_id or 0) ready = table_ready(db) rows = _load_rows(db, eid) if ready else {} return _assemble(eid, ready, rows) def builtin_resolution(entity_id: int = 0) -> dict: """纯内置默认的解析结果（配置表缺失/读异常时的回落形态，字段与 `resolve()` 逐字一致）。""" return _assemble(int(entity_id or 0), False, {}) def _assemble(eid: int, ready: bool, rows: Dict[Tuple[str, str], dict]) -> dict: """把「行 + 内置默认」组装成对外结构（resolve / builtin_resolution 共用）。""" def _one(rule_key: str, param_key: str, spec: dict) -> dict: val, source, row = spec.get("default"), "builtin", None tmpl = rows.get((rule_key, param_key)) if tmpl and tmpl["entity_id"] == TEMPLATE_ENTITY_ID: val, source, row = tmpl["value"], "template", tmpl["row"] elif eid != TEMPLATE_ENTITY_ID: own = rows.get((rule_key, param_key)) if own and own["entity_id"] == eid: val, source, row = own["value"], "entity", own["row"] entry = { "value": val, "source": source, "open_level": spec.get("open_level"), "desc": spec.get("desc"), "updated_by": None, "updated_at": None, # 类型/取值区间对前端呈现（**仅提示**；越界/类型一律由写端点判定， # 前端不得据本字段自造「校验通过」——清单 §5.1 反刷分约束） "value_type": spec.get("type") or "json", "bounds": list(spec["bounds"]) if spec.get("bounds") else None, "enum": list(spec["enum"]) if spec.get("enum") else None, "overflow": spec.get("overflow"), } if row is not None: entry["updated_by"] = getattr(row, "updated_by", None) ua = getattr(row, "updated_at", None) entry["updated_at"] = ua.isoformat(timespec="seconds") if ua else None entry["row_id"] = row.id return entry rules: Dict[str, Dict[str, dict]] = {} values: Dict[str, Dict[str, Any]] = {} for rule_key in RULE_KEYS: rules[rule_key] = {p: _one(rule_key, p, s) for p, s in SPEC[rule_key].items()} values[rule_key] = {p: e["value"] for p, e in rules[rule_key].items()} glob: Dict[str, dict] = {p: _one(GLOBAL_RULE_KEY, p, s) for p, s in GLOBAL_SPEC.items()} values[GLOBAL_RULE_KEY] = {p: e["value"] for p, e in glob.items()} # 规则级 detail_limit 未配置时，回落全局 detail_limit（清单 §3.9） global_limit = values[GLOBAL_RULE_KEY].get("detail_limit") or DEFAULT_DETAIL_LIMIT for rule_key in RULE_KEYS: entry = rules[rule_key]["detail_limit"] if entry["source"] == "builtin": entry["value"] = global_limit entry["source"] = "builtin(global)" values[rule_key]["detail_limit"] = entry["value"] version = hashlib.sha1( json.dumps(values, sort_keys=True, ensure_ascii=False).encode("utf-8") ).hexdigest()[:12] return { "entity_id": eid, "config_entity_id": eid if eid in CONFIG_ENTITIES else TEMPLATE_ENTITY_ID, "entity_config_enabled": eid in CONFIG_ENTITIES, "table_ready": ready, "config_version": version, "rules": rules, "global": glob, "values": values, "scope": {"excluded_entities": values[GLOBAL_RULE_KEY].get("scope.excluded_entities") or []}, } def engine_values(db: Session, entity_id: int) -> dict: """引擎取值口（data_quality 规则引擎唯一的配置读取入口）。""" return resolve(db, entity_id)["values"] # ══════════════════════════════════════════════════════════════════ # 写路径：单参数 upsert（逐项「一次只改一档」） # ══════════════════════════════════════════════════════════════════ def upsert_param(db: Session, entity_id: int, rule_key: str, param_key: str, value: Any, *, username: Optional[str] = None) -> dict: """写一行配置（调用方负责权限/校验/审计/事务边界）；返回 {id, before, after, source_before}。""" from app.models import QualityRuleConfig before = resolve(db, entity_id) if is_global_param(rule_key): # 全局项：`resolve()["global"]` 直接以 param_key 为键（无 rule_key 一层） before_entry = (before.get("global") or {}).get(param_key, {}) or {} else: before_entry = ((before.get("rules") or {}).get(rule_key, {}) or {}).get(param_key, {}) or {} value_type = value_type_of(rule_key, param_key) payload = dumps_value(value) row = (db.query(QualityRuleConfig) .filter(QualityRuleConfig.entity_id == int(entity_id), QualityRuleConfig.rule_key == rule_key, QualityRuleConfig.param_key == param_key) .first()) if row is None: row = QualityRuleConfig( entity_id=int(entity_id), rule_key=rule_key, param_key=param_key, param_value=payload, value_type=value_type, open_level=open_level_of(rule_key, param_key), is_default=False, description=(param_spec(rule_key, param_key) or {}).get("desc"), updated_by=username, ) db.add(row) else: row.param_value = payload row.value_type = value_type row.is_default = False row.updated_by = username db.flush() # 拿到 id，且撞唯一键时当场暴露 return { "id": row.id, "before": before_entry.get("value"), "before_source": before_entry.get("source"), "after": value, } def history(db: Session, entity_id: int, limit: int = 20) -> List[dict]: """本账套的配置变更历史（读 `operation_logs`；该表无 entity_id 列 → 按 detail JSON 过滤）。""" from app.models import OperationLog rows = (db.query(OperationLog) .filter(OperationLog.action == ACTION_UPDATE) .order_by(OperationLog.id.desc()) .limit(max(limit * 5, 50)) .all()) out: List[dict] = [] for r in rows: detail = r.detail if isinstance(r.detail, dict) else {} if detail.get("entity_id") != int(entity_id): continue out.append({ "id": r.id, "at": r.created_at.isoformat(timespec="seconds") if r.created_at else None, "user_id": r.user_id, "rule_key": detail.get("rule_key"), "param_key": detail.get("param_key"), "before": detail.get("before"), "after": detail.get("after"), "reason": detail.get("reason"), "target_id": r.target_id, }) if len(out) >= limit: break return out #: 审计动作名（清单 §5.2 逐字） ACTION_UPDATE = "update_dq_rule_config" TARGET_TYPE = "dq_rule_config"