events 插件骨架与契约包（v1.3 · 2026-07-26）

多团队并行开发的”地基”：骨架代码 + 契约包 + 红线检查脚本。现有工程代码（main.py / kernel）零改动，全部新代码在 plugins/events/ 内。

v1.2 进展（P0 五组全部交付，前后端齐套）

组1 事件核心：events CRUD/筛选/全文、标签树/打标/去标、关联查询（实体/文件/子事件）——events_router.py / events_service.py / manage.html
组2 实体归一：复核队列/决策详情/确认/拒绝/归一检索 + 匹配流水线（字典→来源映射→名称规则→LLM 兜底）+ canonical 引擎——canonical_router.py / canonical_service.py / workers/engines/canonical.py / canonical.html（复核台页面）
组3 任务清单：草稿五态状态机（TimeParser + 实体锚定 + nl_task_parsers 日志）、预览、确认生成任务；监视清单 CRUD + 四类清单项命中——task_router.py / task_service.py / taskdraft.html（五步引导）/ watchlist.html
组4 告警：规则 CRUD（numeric 白名单校验）+ 处置（确认/忽略/误报反馈反哺统计）+ 订阅；alerting 周期引擎（45s 评估、冷却、max 封顶、动作链 ws_push/create_task/webhook、超时升级查 duty_roster）——alert_router.py / alert_service.py / workers/engines/alerting.py / alerting.html
组5 文件媒体：年/月日 SHA256 去重秒传（2026/0726/hash16.ext）、上传事务链（attachments+elefile+event_file_links）、标注存 metadata、三引擎抽取（mysql_fulltext/preset_rule/llm）+ 审核导入走组1 service——file_router.py / storage_service.py / file_service.py / workers/engines/extract.py / media.html
装配验证通过：48 条路由注册无误、3 引擎（alerting/canonical/extract）全部可实例化、common 8 模块/services 6/routers 5 导入正常、红线检查 PASS、全量语法通过

P0 已完整。fusion/assoc/inference/pipeline/ontology 五个工作台仍属 P1。

v1.2.1 补丁：frontend/index.html 顶栏新增”返回门户”链接（默认指向 /，门户若挂在其他路径改 back-home 的 href 即可）。

v1.3 进展（P1 启动包：geo/cache 落地 + 五引擎骨架）

kernel/geo.py 评审：纯函数零依赖，完全复用 → common/geox.py 封装（注意坐标序 lat,lon，与 MySQL 相反；SQL 粗筛 + geox 精筛分层）
kernel/cache.py 评审：Redis+LRU 自动降级，可复用 → common/cachex.py 封装（统一前缀 events；workers/__main__.py 已接入 ensure_init()——worker 独立进程没有 main.py 的启动钩子；无 Redis 时锁降级恒 True，多实例周期引擎须配 Redis 或单实例）
P1 五引擎骨架（全部可实例化、已注册，填 TODO 即实现）：
- inference.py：队列型，消费 relation_transitive_queue（derive/invalidate 两路框架）
- normalizer.py：周期 60s，ais/radar/routine unpivot → time_series_data，水位线在 cachex
- correlate.py：周期 120s，空间关联粗筛+精筛算法已可跑（红线：只查不写，关联结论落地待仲裁）
- detect.py：周期 60s，已实现（v1.3.1）——file_content 增量 → 800 字切块（100 重叠）→ LLM 抽事件（detect_event_extract 模板，种子 v1.1）→ 块级指纹查重 → events_service.create_event；系统用户 {“id”:0} → handler_id=NULL（handler_id 可空，DDL 已确认，create_event 已支持）；无坐标事件跳过
- fusion.py：周期 180s + 分布式锁，时空粗筛并查集算法已可跑，簇幂等落库待填
契约更新：01 §10 评审结论落地；02 新增 P1 任务卡（组6 引擎组 + 组7 前端五台）；04 新增 §5~§8 轮询契约
装配验证通过：common 10 模块 / services 6 / routers 5 / engines 8 导入正常，8 引擎注册并可实例化；geox 实算（北京-上海 1067km）、cachex 真实 kernel/cache.py 读写删/锁/幂等冒烟通过；红线 PASS、全量语法 PASS

P1 开工清单见《02》第三章：各引擎”开工前必备”列（DDL 切片、仲裁结论、业务规则输入）凑齐即可填实现体。

events插件骨架与契约包/
├── README.md                        ← 本文件
├── plugins/events/                  ← 插件骨架（整体拷入工程 plugins/ 目录即用）
│   ├── manifest.json                插件清单（前缀 /api/events，挂载 /app/events）
│   ├── run_worker.py                worker 独立进程启动器
│   ├── backend/
│   │   ├── __init__.py              register()：挂路由 + 挂文件预览 /files/events
│   │   ├── app.py                   路由组装 · 滚动集成登记处（TEAM_ROUTERS）
│   │   ├── common/                  kernel 唯一进口（反腐层，平台组维护）
│   │   │   ├── deps.py              鉴权两档 + require_perm 工厂
│   │   │   ├── resp.py              ok / page_resp（列表四键结构）
│   │   │   ├── dbutil.py            utcnow / 分页 / JSON 列 / IN 展开 / get_db / transaction
│   │   │   ├── errors.py            内核异常统一出口
│   │   │   ├── notifyx.py           notify / notify_role / WS 推送
│   │   │   ├── llmx.py              LLM 调用（强制 prompt_id + 日志落库）
│   │   │   ├── nlpx.py              TimeParser / TokenBudget 封装
│   │   │   ├── cfgx.py              配置封装（存储根目录/大小上限/扩展名白名单）
│   │   │   ├── geox.py              【P1】地理计算（distance_m/多边形/bbox，坐标序 lat,lon）
│   │   │   └── cachex.py            【P1】缓存与分布式锁（前缀 events，ensure_init 幂等）
│   │   ├── routers/                 各组交付区（5 组全部已交付）
│   │   ├── services/                业务服务层（API 与 worker 共用，6 个）
│   │   └── workers/                 引擎框架：QueueWorker + PeriodicWorker / registry / __main__
│   │       └── engines/             P0：canonical/extract（队列型）alerting（周期型）
│   │                                P1：inference（队列型）normalizer/correlate/detect/fusion（周期型）
│   └── frontend/
│       ├── index.html               十工作台导航壳（六个 ready，P1 五个置灰）
│       └── tabs/                    manage / canonical / taskdraft / watchlist / alerting / media
├── 契约包/
│   ├── 01_kernel接口速查表.md        替代 kernel 源码（每组必读）
│   ├── 02_表归属矩阵与团队任务卡.md  108 表归属 + 6 张任务卡（分工依据）
│   ├── 03_API契约规范.md             端点/响应/权限点/各组出场接口清单
│   ├── 04_队列载荷契约.md            跨组异步接口（队列行即契约）
│   └── 05_前端契约一页纸.md          session.js/apiFetch/铃铛/时间/文件预览
├── 种子SQL/
│   └── events种子数据_v1.sql          幂等种子（权限点/字典/实体关系类型/标签树/prompt/规则/动作）
└── tools/
    └── redline_check.py             CI 红线检查（python tools/redline_check.py plugins/events）

对现有工程的影响

对象	改动
main.py / kernel/*	零改动
plugins/	新增 events/ 目录（本包拷入）
Python 依赖	新增 `python-multipart`（组5 上传端点所需）
.env	增加 `FILE_STORAGE_LOCAL_PATH` 指向真实存储目录；RAG 相关配置
数据库	执行 `种子SQL/events种子数据_v1.sql`（幂等，可重复执行）：5 角色权限点、状态/优先级/类目字典、实体/关系类型、系统标签树、术语字典、3 个 LLM prompt 模板、2 条归一规则、3 个告警内置动作

启动方式

# API 进程（插件由 main.py 自动扫描注册）
python main.py

# 引擎 worker（独立进程，可多起）
python plugins/events/run_worker.py --engine all --concurrency 4
python plugins/events/run_worker.py --engine canonical

# 红线检查（CI 门禁）
python tools/redline_check.py plugins/events

各组开工三步

读《02》找到自己组的任务卡 +《01》速查表 + 本组 DDL 切片（从 huishievents.sql 抽取）；
参照 routers/events_router.py（后端）、workers/engines/canonical.py（引擎）、frontend/index.html（前端）三个示例写自己模块；
交付前跑 redline_check.py，全绿后提平台组集成（app.py 登记一行）。

部署与待补清单

部署侧（业务方/运维执行）：

pip install python-multipart（文件上传端点依赖）；
.env 配置 FILE_STORAGE_LOCAL_PATH（文件落盘根目录，预览经 /files/events 挂载）；
执行种子 SQL 后，绑定 personnel_role_links（人员-角色）与 duty_roster（当日值班）——告警升级的前提；
告警引擎超时升级依赖 duty_roster 当日 is_primary=1 记录，无排班时降级为 notify_role(escalate_to_role)。

P1 待补（不阻塞 P0 运行）：

~~kernel/geo.py、kernel/cache.py 源码~~（v1.3 已到手并完成封装，见《01》§10）；
session.js 自定义频道钩子：P1 频道推送需平台组扩展（P0/P1 轮询即可）；
kernel/file_storage.py 评审结论：不可复用（旧式 cursor API 与现行 db.py 不兼容、路径规则不符），组5 已按契约自建 storage_service；
角色-权限种子对照表（哪些 role_code 绑哪些 events:* 权限点，需业务方确认）；
密级方案：events 表无密级列，P0 仅文件级密级过滤（file_metadata.classification），事件级待决策；
composite/llm 类型告警规则：P0 引擎跳过并记日志，P1 实现。