feat(kpi): 归集侧接作废/撤单标记过滤（voucher_void_marks）
- kpi_value_collector: 所有消费 voucher_details 的归集路径统一排除已作废凭证 (NOT EXISTS voucher_void_marks, entity_id+voucher_no+voucher_date+revoked_at IS NULL), 与 DB 视图 v_voucher_details_active 定义一致；标记表不存在时自动跳过（兼容旧库） - 禁硬编码：凭证号不出现在代码/配置，撤单只需写标记表 - verify_cashflow_direct_caliber: 2026-08 从已知差异放行改为硬断言（8 期逐期一致） - tests/test_void_marker_filter_20260914.py: 标记表在/不在 两分支 3 例
This commit is contained in:
Hermes CI Fix
@@ -31,7 +31,7 @@ if __name__ == "__main__":
|
||||
import os
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
|
||||
from sqlalchemy import and_, func, not_, or_
|
||||
from sqlalchemy import MetaData, Table, and_, exists, func, not_, or_
|
||||
from sqlalchemy.orm import aliased
|
||||
from app.database import get_session_local
|
||||
from app.models import (
|
||||
@@ -67,6 +67,70 @@ def _field_expression(model, field: str, aggregate: str = "sum"):
|
||||
return func.sum(col)
|
||||
|
||||
|
||||
# ── 作废/撤单标记过滤（2026-09-14 接入；单一事实来源 = cma.voucher_void_marks）──────
|
||||
# 口径: 本模块**所有**消费 voucher_details 的归集路径统一排除「已作废/被更正」凭证。
|
||||
# 判定键 = (entity_id, voucher_no, voucher_date) 且 revoked_at IS NULL —— 与 DB 视图
|
||||
# `cma.v_voucher_details_active` 的定义逐字一致（视图供探针/报表等其它消费方使用）。
|
||||
# 纪律: 禁硬编码凭证号；标记表是唯一数据源 —— 今后任何撤单只需写标记表，代码零改动。
|
||||
# 兼容: 标记表不存在（测试库/旧库）→ 跳过过滤，不阻断采集（告警一次）。
|
||||
_VOID_MARK_TABLE = "voucher_void_marks"
|
||||
_void_mark_table_ref = None # 反射缓存: Table（存在）| False（不存在）
|
||||
_void_mark_warned = False
|
||||
|
||||
|
||||
def _void_mark_table(db):
|
||||
"""作废标记表（反射 + 缓存）；表不存在/不可读 → None。"""
|
||||
global _void_mark_table_ref, _void_mark_warned
|
||||
if _void_mark_table_ref is not None:
|
||||
# 注意: Table 对象无真值（__bool__ 未定义），必须显式判 False，不能写 `ref or None`
|
||||
return None if _void_mark_table_ref is False else _void_mark_table_ref
|
||||
try:
|
||||
# 走 Session 自身连接（而非 engine）: 测试库 StaticPool 下两者是同一 DBAPI 连接，
|
||||
# 另开 engine 连接会在归还时回滚掉 Session 未提交的写入；此处保持同一事务。
|
||||
bind = db.connection() if hasattr(db, "connection") else db.get_bind()
|
||||
_void_mark_table_ref = Table(_VOID_MARK_TABLE, MetaData(), autoload_with=bind)
|
||||
logger.info("作废标记过滤已接入: %s（撤销标记后自动重新计入）", _VOID_MARK_TABLE)
|
||||
except Exception as e: # noqa: BLE001 - 兼容无标记表的环境
|
||||
_void_mark_table_ref = False
|
||||
if not _void_mark_warned:
|
||||
logger.warning("作废标记表 %s 不可用 → 本次不做作废过滤: %s", _VOID_MARK_TABLE, e)
|
||||
_void_mark_warned = True
|
||||
return None if _void_mark_table_ref is False else _void_mark_table_ref
|
||||
|
||||
|
||||
def _void_mark_table_exists(db) -> bool:
|
||||
return _void_mark_table(db) is not None
|
||||
|
||||
|
||||
def _has_col(src, name: str) -> bool:
|
||||
cols = getattr(src, "c", None)
|
||||
return (name in cols) if cols is not None else hasattr(src, name)
|
||||
|
||||
|
||||
def _exclude_void(db, query, src):
|
||||
"""给凭证明细查询挂上 NOT EXISTS(voucher_void_marks) 过滤（本模块唯一注入点）。
|
||||
|
||||
src = VoucherDetail（或 aliased(VoucherDetail)）；标记表不存在 → 原样返回。
|
||||
"""
|
||||
marks = _void_mark_table(db)
|
||||
if marks is None:
|
||||
return query
|
||||
clause = ~exists().where(and_(
|
||||
marks.c.entity_id == src.entity_id,
|
||||
marks.c.voucher_no == src.voucher_no,
|
||||
marks.c.voucher_date == src.voucher_date,
|
||||
marks.c.revoked_at.is_(None),
|
||||
))
|
||||
return query.filter(clause)
|
||||
|
||||
|
||||
def _apply_voucher_guard(db, query, src):
|
||||
"""凡指向凭证明细的查询一律过作废过滤（非凭证明细源表原样返回）。"""
|
||||
if _has_col(src, "voucher_no") and _has_col(src, "voucher_date"):
|
||||
return _exclude_void(db, query, src)
|
||||
return query
|
||||
|
||||
|
||||
def collect_for_mapping(db, mapping: KPIValueSource, period: str, write_kpi: bool = True) -> Tuple[Optional[float], str]:
|
||||
"""执行单条取数映射，返回 (采集值, 说明)。write_kpi=False 时为试跑模式（不写库）。"""
|
||||
table = mapping.source_table
|
||||
@@ -111,6 +175,9 @@ def collect_for_mapping(db, mapping: KPIValueSource, period: str, write_kpi: boo
|
||||
return None, f"期间字段 {period_field} 不存在于表 {table}"
|
||||
q = q.filter(pf == period)
|
||||
|
||||
# 作废/撤单标记过滤（消费 voucher_details 的统一守卫）
|
||||
q = _apply_voucher_guard(db, q, model)
|
||||
|
||||
# 过滤规则: subject_code / direction / plan_type / carry_forward
|
||||
subject_code = filter_rule.get("subject_code")
|
||||
if subject_code and hasattr(model, "subject_code"):
|
||||
@@ -125,6 +192,7 @@ def collect_for_mapping(db, mapping: KPIValueSource, period: str, write_kpi: boo
|
||||
q = q.filter(func.date_format(model.voucher_date, "%Y-%m") == period)
|
||||
else:
|
||||
q = q.filter(getattr(model, period_field) == period)
|
||||
q = _apply_voucher_guard(db, q, model)
|
||||
field = "credit_amount"
|
||||
elif direction == "debit" and hasattr(model, "debit_amount"):
|
||||
q = db.query(_field_expression(model, "debit_amount", aggregate))
|
||||
@@ -133,6 +201,7 @@ def collect_for_mapping(db, mapping: KPIValueSource, period: str, write_kpi: boo
|
||||
q = q.filter(func.date_format(model.voucher_date, "%Y-%m") == period)
|
||||
else:
|
||||
q = q.filter(getattr(model, period_field) == period)
|
||||
q = _apply_voucher_guard(db, q, model)
|
||||
field = "debit_amount"
|
||||
plan_type = filter_rule.get("plan_type")
|
||||
if plan_type and hasattr(model, "plan_type"):
|
||||
@@ -239,6 +308,7 @@ def _subject_amount(db, entity_id: int, pattern: str, period: str, measure: str)
|
||||
q = q.filter(VoucherDetail.subject_code == pattern)
|
||||
if period:
|
||||
q = q.filter(VoucherDetail.period == period)
|
||||
q = _exclude_void(db, q, VoucherDetail) # 作废/撤单标记过滤
|
||||
credit, debit, rows = q.first()
|
||||
credit, debit = float(credit or 0), float(debit or 0)
|
||||
if measure == "debit":
|
||||
@@ -319,6 +389,7 @@ def _cashflow_voucher_subquery(db, entity_id: int, period: Optional[str], cash_s
|
||||
if period:
|
||||
q = q.filter(VoucherDetail.period == period)
|
||||
q = q.filter(or_(*[VoucherDetail.subject_code.like(p) for p in cash_subjects]))
|
||||
q = _exclude_void(db, q, VoucherDetail) # 作废/撤单标记过滤（凭证键集合）
|
||||
voucher_cnt = q.distinct().count()
|
||||
return q.distinct().subquery(), voucher_cnt
|
||||
|
||||
|
||||
@@ -5,7 +5,8 @@
|
||||
|
||||
判据（全部只读，write_kpi=False）:
|
||||
1. 生产同一代码路径试算 2026-01..08，与现网 zxt-sync 权威值对账（容差 0.001）
|
||||
—— 2026-08 因上游已撤单凭证仍在库内（智享通快照不含）按已知差异放行（WARN，不算 FAIL）
|
||||
—— 2026-08 差异已随「作废/撤单标记过滤」接入归集器（2026-09-14）消除：
|
||||
归集侧统一按 cma.voucher_void_marks 排除已作废凭证，8 期逐期一致（无放行期）
|
||||
2. 恒等式: 经营净额 + 筹资净额 + 投资净额 = 现金总净额（每期 |Δ| ≤ 0.001）
|
||||
3. 负例对照: 若按「凭证级整单分类」（错误做法），2026-06 应为 453,697.63 元
|
||||
（行级 = 434,997.63 元，差 +18,700 = 凭证 31226 同单内的银行手续费）→ 证明必须行级拆分
|
||||
@@ -25,7 +26,7 @@ from scripts.kpi_value_collector import collect_for_mapping
|
||||
ENTITY = 1
|
||||
PERIODS = ["2026-0%d" % i for i in range(1, 9)]
|
||||
TOL = 0.001
|
||||
KNOWN_DIFF_PERIODS = {"2026-08"} # 上游已撤单凭证未标记 → 已知差异（挂账，非回归）
|
||||
KNOWN_DIFF_PERIODS = set() # 2026-09-14 起为空集：作废标记过滤已接入归集器，8 期逐期硬断言
|
||||
RULE = {
|
||||
"calc": "cashflow_direct", "measure": "net", "version": 1, "bucket": "operating",
|
||||
"cash_subjects": ["1001%", "1002%", "1012%"],
|
||||
|
||||
Reference in New Issue
Block a user