#WorkBuddy# 24 个端点 204 处偏差：快照 diff 精确率只有 15.35%，契约治理做到 100% 零误报

import re, uuid
from datetime import datetime

def fmt_ok(val, fmt):
    if fmt == "date-time":  # 先正则卡死 RFC3339，再交给解析器
        if not re.fullmatch(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})", val):
            return False
        try:
            datetime.fromisoformat(val.replace("Z", "+00:00")); return True
        except ValueError:
            return False
    if fmt == "uuid":
        try: uuid.UUID(val); return True
        except ValueError: return False
    return True

def type_ok(v, t):
    return {"object": dict, "array": list, "string": str}.get(t) and isinstance(v, dict if t == "object" else list if t == "array" else str) \
        or (t == "integer" and isinstance(v, int) and not isinstance(v, bool)) \
        or (t == "number" and isinstance(v, (int, float)) and not isinstance(v, bool))

def validate(node, sch, path, out, in_item=False):
    if node is None:
        ts = sch.get("type")
        if not ((ts == "null") or (isinstance(ts, list) and "null" in ts)):
            out.append((f"{path}", "NULL_SEMANTICS"))
        return
    ts = sch.get("type")
    types = [t for t in (ts if isinstance(ts, list) else [ts]) if t != "null"]
    if types and not any(type_ok(node, t) for t in types):
        out.append((path, "TYPE_DRIFT")); return
    if "enum" in sch and node not in sch["enum"]:
        out.append((path, "ENUM_OUT"))
    if "format" in sch and isinstance(node, str) and not fmt_ok(node, sch["format"]):
        out.append((path, "DATETIME_FORMAT" if sch["format"] == "date-time" else "TYPE_DRIFT"))
    if isinstance(node, dict):
        for req in sch.get("required", []):
            if req not in node:
                out.append((f"{path}/{req}", "NESTED_ITEM" if in_item else "MISSING_REQUIRED"))
        for k, v in node.items():
            if k in sch.get("properties", {}):
                validate(v, sch["properties"][k], f"{path}/{k}", out, in_item)
            elif sch.get("additionalProperties") is False:
                out.append((f"{path}/{k}", "EXTRA_FIELD"))
    if isinstance(node, list) and "items" in sch:
        for i, v in enumerate(node):  # 只有顶层集合之外的数组元素才算“嵌套”
            validate(v, sch["items"], f"{path}/{i}", out, in_item or not path.endswith("/items"))

def invariants(ep, resp, out):
    body = resp["body"]
    if resp["status"] != ep["status"]:          # 创建接口应 201，返回 200
        out.append(("", "STATUS_CODE"))
    if ep["kind"] == "list":
        items = body["data"]["items"]; page = body["data"]["page"]
        if page["total"] < len(items):          # 分页自相矛盾
            out.append(("/data/page/total", "PAGINATION"))
        objs = [(f"/data/items/{i}", it) for i, it in enumerate(items)]
    else:
        objs = [("/data", body["data"])]
    for pre, o in objs:
        p, q, amt = o.get("price"), o.get("quantity"), o.get("total_amount")
        if all(isinstance(x, (int, float)) and not isinstance(x, bool) for x in (p, q, amt)):
            if abs(p * q - amt) > 0.01:         # 金额勾稽不平
                out.append((f"{pre}/total_amount", "SEMANTIC_AMOUNT"))
        st, arch = o.get("status"), o.get("archived_at")
        if st != "archived" and arch is not None:  # 未归档却有归档时间
            out.append((f"{pre}/archived_at", "CROSS_FIELD"))

请对我的接口契约做一次巡检：
1. 读取 <spec 路径>（OpenAPI/自描述 JSON 均可）与 <当前响应快照目录>；
2. 逐端点做 Schema 校验：required/type/enum/format/items/未声明字段，
   时间格式先按 RFC3339 正则卡死再解析；
3. 追加跨字段不变量：分页 total 与条数、金额勾稽、时间先后、状态与时间戳配对；
4. 先在基线快照上空跑一遍，报告数必须为 0 才算校验器可信；
5. 输出清单：每条按 JSON Pointer 定位、按 10 类偏差归类、按严重度排序，
   妥协为零：不要给"可能有问题"，只给"确定违规"。