Gotham 模式识别 · LightGotham

1. 页面概览

1.1 是什么

「模式识别」页面（页面内标题为 Gotham 模式识别）是 LightGotham 的情报规则检测工作台，把「什么样的事件值得警惕」固化为可执行规则，自动扫描融合实体与时间轴事件，命中后落库为告警并支持人工研判闭环。页面定位是「规则 + 统计」的确定性检测：规则优先，AI 增强仅 V2（当前未启用），对标 Palantir Gotham 的 pattern detection 能力。

1.2 核心价值

维度	说明
三种规则类型	`frequency`（时间窗口内事件频次≥阈值）、`anomaly`（属性数值超阈值，算子 gt/lt/gte/lte/eq）、`association`（同一实体事件类型组合共现）
规则生命周期	草稿→测试中→启用中→已禁用→已归档，状态机约束非法流转，active 才被调度评估
评估与测试	单条「评估」落库命中、「测试」不落库只返回命中数、「全量评估」对所有启用规则批量执行
命中闭环	命中/告警状态 `open → acknowledged → resolved`，人工确认/处置，操作即时刷新
告警打分	`score = 严重度基础分 × 类型置信度 × 新鲜度衰减`，评分越高越优先研判
预置规则库	bootstrap 幂等预置 6 条反欺诈/企业关联/公共安全规则（默认 active）

1.3 一句话总结

在 Gotham 里创建并启用模式规则，评估命中生成带评分的告警，由人工确认、处置完成研判闭环——把「可疑行为」变成可追溯、可排序、可处置的情报线索。

2. 访问入口

2.1 路由与菜单

路由：/gotham/patterns；路由名称：GothamPatterns
路由 meta：title: Gotham 模式识别，requiresAuth: true，挂在父路由 /gotham（GothamLayout）下
菜单位置：Gotham 左侧边栏「模式识别」
前端源码：action/web/src/views/GothamPatternsPage.vue
API 客户端：action/web/src/api/gothamClient.js

2.2 认证与权限

路由挂 requiresAuth: true，未登录访问被全局守卫重定向到 /login。
请求走 gothamClient：请求拦截器自动附带 Authorization: Bearer <aip_token>；响应拦截器遇 401 时用 gotham_refresh_token 调 POST /auth/refresh 换发新 token 并重放原请求，refresh 失败才清令牌跳登录。

2.3 端口与 API 前缀

Gotham 后端端口：18083（Vite 将 /gotham-api 前缀代理到该端口并重写为 /api/v1）。
API 前缀：/gotham-api/v1（gothamClient 的 baseURL）。

3. 界面布局

页面单栏纵向布局，顶部标签页切换「规则管理 / 告警看板」：

┌──────────────────────────────────────────────────────────────┐
│ Gotham 模式识别 [刷新]                                         │
│ [alert 操作结果提示条（可关闭）]                                │
│ [规则管理] [告警看板（N）]                                      │
│ [全量评估结果小卡片：total / hit / miss / errors（可选）]        │
│ ① 规则列表（N）[全量评估]                                       │
│    ID/名称/pattern_type/target/严重度/状态/启用/创建时间/操作     │
│ ② 创建规则 / 编辑规则 #id（表单：name/描述/类型/目标/严重度/启用/ │
│    config JSON）[创建规则|保存修改][取消编辑]                    │
│ ③ 命中记录（N）[状态过滤][规则过滤]                             │
│    ID/rule_id/target_entity_id/证据/count/状态/严重度/时间/操作  │
└──────────────────────────────────────────────────────────────┘

规则列表：全部模式规则一览，操作列提供编辑/评估/测试/生命周期流转/删除。
创建/编辑表单：定义规则属性与 config JSON，切换规则类型自动填入对应模板。
命中记录：评估产生的告警级命中，支持按状态、按规则过滤并确认/处置。
告警看板：所有命中按时间降序展示，含评分 score 与聚合组，确认/处置沿用命中状态机。

4. 交互元素

4.1 标签页与通用操作

控件	位置	含义与作用
标签页「规则管理」「告警看板」	页头下方	切换两个视图；告警看板标签带当前告警数「（N）」
「刷新」按钮	页头右上	并行重载规则、命中、告警三份数据
「关闭」链接按钮	alert 提示条右侧	关闭当前操作结果提示

4.2 规则列表与表单

控件	含义与作用
「全量评估」按钮	对全部启用规则批量评估；执行中显示「评估中…」，结果以 total/hit/miss/errors 统计卡展示并提示「全量评估完成：共 N 条，命中 N，未命中 N，失败 N」
行内「评估」	单条规则评估（命中落库），弹窗展示 EvaluationResult
行内「测试」	手动测试不落库，仅提示「测试完成：命中（count=N）/未命中（count=N）」
行内生命周期按钮	按状态机显示「测试中/激活/禁用/归档/回草稿」，点击经 `window.confirm` 确认后流转
行内「编辑」「删除」	回填表单进入编辑态 / 确认后删除规则（删除前有确认弹窗）
表单字段	名称 name （全局唯一）、描述 description、规则类型 pattern_type、目标 target、严重度 severity（低/中/高）、启用 enabled、config JSON
「创建规则」「保存修改」「取消编辑」	提交创建/更新；config JSON 非法时提示「config JSON 不合法」；编辑态点「取消编辑」重置表单

4.3 命中与告警操作

控件	含义与作用
状态过滤 / 规则过滤	命中列表下拉过滤：全部/open/acknowledged/resolved 与「全部规则」/指定规则
「确认」	命中/告警 `open → acknowledged`，确认弹窗「确认命中 #id（rule_id=..）吗？」
「处置」	命中/告警 `open\|acknowledged → resolved`，处置后操作列显示「-」

5. 后端关联

5.1 API 客户端

文件：action/web/src/api/gothamClient.js；baseURL /gotham-api/v1，超时 30000ms。
导出：connectWebSocket / disconnectWebSocket / wsSubscribeProject / wsUnsubscribeProject（本页未直接使用）。

5.2 端点表

方法	路径	说明
GET	`/patterns/rules`	规则列表
POST	`/patterns/rules`	创建规则（CreateRuleRequest）
GET	`/patterns/rules/:id`	规则详情
PUT	`/patterns/rules/:id`	更新规则（指针字段 nil 保留原值）
DELETE	`/patterns/rules/:id`	删除规则
POST	`/patterns/rules/:id/evaluate`	单条规则评估（命中写 PatternHit）
POST	`/patterns/rules/:id/test`	手动测试（不落库）
POST	`/patterns/rules/:id/transition`	生命周期流转，body `{to}`
POST	`/patterns/rules/:id/toggle`	active/disabled 启停切换
POST	`/patterns/evaluate-all`	批量评估全部启用规则，返回 BatchResult
GET	`/patterns/hits`	命中列表（status/rule_id + limit/offset）
POST	`/patterns/hits/:id/acknowledge`	确认命中（open → acknowledged）
POST	`/patterns/hits/:id/resolve`	处置命中（open\|acknowledged → resolved）
GET	`/patterns/alerts`	告警列表（时间降序，默认 limit 200）
POST	`/patterns/alerts/:id/acknowledge`	确认告警
POST	`/patterns/alerts/:id/resolve`	处置告警

5.3 响应结构

统一响应体 {code: 0, data: ...}。全量评估结果（BatchResult）与单条评估结果（EvaluationResult）：

{ "code": 0, "data": { "total": 6, "hit": 2, "miss": 3, "errors": 1 } }
{ "code": 0, "data": { "rule_id": 3, "rule_name": "反欺诈-大额异常转账", "pattern_type": "anomaly",
  "target": "entity", "matched": true, "count": 1, "hit_id": 7,
  "target_entity_id": "graph:person:zhangyuan", "evidence": {"field": "amount", "value": 520000} } }

5.4 关键机制

规则生命周期状态机：draft→testing→active→disabled→archived、active→testing、disabled→active；进入 active 置 Enabled=true、进入 disabled 置 Enabled=false，archived 为终态。非法流转后端返回 409（GOTHAM_PATTERN_RULE_INVALID_TRANSITION）。
config 模板：frequency {"window_days":30,"min_count":3,"event_type":"incident","entity_id":""}；anomaly {"field":"amount","operator":"gt","threshold":100000,...}；association {"items":["a","b"],"min_support":1}；提交前前端校验 JSON 合法性。
命中幂等与告警聚合：24h 内同 (rule, target_entity_id) 未解决命中去重不重复写；30min 窗口内同规则限频聚合到同一 alert_group_id 并累加 count。
告警打分：score = 严重度基础分（低30/中50/高70）× 类型置信度（frequency 0.8，anomaly/association 0.9）× exp(-0.05·age小时)，保留两位小数。
预置规则库：bootstrap 时幂等插入 6 条预置规则（覆盖反欺诈/企业关联/公共安全，直接置 active 并跳过生命周期校验）；规则名全局唯一，重复同名人工创建会被跳过。

6. 权限与安全

认证：全部 /patterns/* 端点位于 protected 组，JWT 无效一律 401，前端自动刷新/跳登录。
写操作防护：删除规则、生命周期流转、确认/处置命中与告警均经 window.confirm 二次确认，防止误操作。
配置校验：规则 name 全局唯一、pattern_type 白名单（frequency/anomaly/association）、target 白名单（entity/timeline/geo/graph）、severity 白名单（低/中/高），非法值由后端校验拦截。

7. 常见问题与排错

问题一：提交规则时报「config JSON 不合法」

现象：保存表单被拦截并提示 JSON 不合法。原因：config 输入框内容不是合法 JSON（如缺引号、花括号不匹配）。处理：切换规则类型自动填入模板后按模板修改，保存前可用 JSON 校验工具核对。

问题二：规则一直未命中，命中列表为空

现象：评估多次但 hits 列表始终为空。原因：规则处于 draft/testing/disabled 状态不被评估，或 target 为预留的 geo/graph，或阈值设置过高。处理：先「测试」看命中数，再「流转」到启用中（active）后「评估」；确认 target 为 entity/timeline。

问题三：全量评估统计有 errors

现象：全量评估结果卡 errors 大于 0。原因：部分启用规则评估时异常（如 anomaly 配置的属性不存在、目标数据源无数据）。处理：把失败规则单条「评估」复现并查看弹窗 message 字段；修正 config 后重试。

问题四：生命周期流转按钮没出现在操作列

现象：部分规则没有流转按钮。原因：当前状态无合法去向（如 archived 终态）。处理：刷新列表确认最新状态；archived 规则不可再流转，只能删除。

问题五：反复确认/处置同一命中仍能点击

现象：已确认的命中还能再操作。原因：多人同时操作或页面未刷新。处理：操作后列表自动刷新，已终态（resolved）行操作列显示「-」；再次点击会由后端状态机拒绝。

8. 已知缺陷与边界

边界	说明
AI 增强	当前为确定性规则检测，AI 增强标注「仅 V2」，matched_by 无 llm 值
调度评估	规则 `schedule` cron 为空时仅手动/事件驱动评估，不会定时触发
分页默认	命中列表默认 limit 100、offset 0，量大时需后端分页参数配合
打分衰减	新鲜度按小时指数衰减（24h 后约 0.30），历史告警评分自然降低
去重口径	24h 去重冷却按任意状态（含 resolved）命中计算，resolved 后窗内同规则不再触发、超窗才允许重建；30min 限频仍按未解决（open/acknowledged）命中计算
表单字段	新建规则表单不暴露 `schedule`（cron）与 `category`（业务分类）；后端请求模型亦无对应字段，当前无法支持，新建默认 schedule 为空、category=general

注：geo/graph 目标下拉「预留」标注已于 2026-09-06 修复（去掉「预留」提示，按 target 填充合法 config 模板）。