diff --git a/AGENTS.md b/AGENTS.md index 31791ce..b7232fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,6 +92,26 @@ - 统计接口(dashboard/analytics/screen 共 20 个路由)**已从匿名可访问变为需登录** 并受范围过滤。注意:大屏挂满 7 天后 refresh token 过期会跳登录页。 +- **MOM 回执的部门校验**(`endpoints/webhooks.py`,2026-09 新增) + MOM 同时对接 IRIS 与 LICA 两个 Track 实例,按载荷里的 `company_name` 分流。 + 本实例(LICA)采取**严格白名单**: + + | `company_name` | 本实例行为 | + |---|---| + | `"LICA"`(strip 后) | 正常处理 | + | 空白 / 缺失 / `"IRIS"` / 未知值 | 忽略,返回 `reason: "ignored_company"` | + + ⚠️ **这与 IRIS 实例的策略刻意相反,不要"统一"**: + IRIS 对空白值要**放行** —— MOM 判定不出公司时会回落到指向 IRIS 的扁平配置, + 不收就彻底丢了;LICA 没有兜底角色,空白值本就该由 IRIS 兜。 + LICA 的原则是**宁可漏、不可误收**:误收会改掉别的部门的设备状态。 + + ⚠️ 拦截时返回 **200 + `matched=False`** 而非 4xx —— 与"未命中"保持同一契约, + 避免 MOM 侧当成故障去重试。`reason: "ignored_company"` 这个取值与 IRIS 实例 + 保持一致(MOM 不解析它,但排查时两边日志要对着看)。 + + 排查口径:**有 `reason` = 被部门校验拦下;无 `reason` = 通过了校验、只是产品没匹配上。** + ## 本地起环境(关键,踩过的坑都在这) 1. **本机没有 Postgres 时需要先装**(容器内 `sudo` 可用): diff --git a/backend/app/api/v1/endpoints/webhooks.py b/backend/app/api/v1/endpoints/webhooks.py index 6d42b1b..f55c674 100644 --- a/backend/app/api/v1/endpoints/webhooks.py +++ b/backend/app/api/v1/endpoints/webhooks.py @@ -176,8 +176,11 @@ async def mom_inbound_webhook( # 旧配置直接打这个接口,也不会把别的部门的设备状态改掉。 # 返回 200 + matched=False 而非 4xx —— 与「未命中」保持同一契约, # 避免 MOM 侧把它当成故障去重试。 + # + # ⚠️ reason 的取值 "ignored_company" 与 IRIS 实例保持一致 —— MOM 侧不解析 + # 它,但排查时两边日志对着看,字段名不一致会白白浪费时间。 if not _belongs_to_this_org(payload.company_name): - return {"ok": True, "matched": False, "reason": "org_mismatch"} + return {"ok": True, "matched": False, "reason": "ignored_company"} explicit_revoke = _is_outbound_revoke(payload) @@ -390,7 +393,7 @@ async def mom_outbound_webhook( # ── 部门校验(纵深防御)—— 同 mom_inbound,理由见该处注释 if not _belongs_to_this_org(payload.company_name): - return {"ok": True, "matched": False, "reason": "org_mismatch"} + return {"ok": True, "matched": False, "reason": "ignored_company"} # ── 按 serial_number(优先)或 sku 匹配"在仓库/已入库"的产品 ── product = None