时间轴

1. 页面概览

时间轴是 LightGotham 的事件时间序列分析页，路由 /gotham/timeline，对应源码 action/web/src/views/GothamTimelinePage.vue。页面围绕事件（Event）提供四块能力：时间范围查询（start/end/type → /timeline/events/range，事件列表）、时间桶聚合（day/week/month → /timeline/aggregate，柱状图）、新增事件（POST /timeline/events）、时序分析增强（预测/周期/对比三个 Tab，ECharts 渲染）。

事件类型枚举 incident / movement / meeting / transaction / registration，严重度枚举 low / medium / high / critical（另有 none 兜底徽标）。一句话总结：时间轴是"事件查询 + 时间桶统计 + 时序算法"的事件情报分析台。

2. 访问入口

• 路由与菜单：/gotham 布局子路由 path: 'timeline'，name GothamTimeline，标题「Gotham 时间轴」，requiresAuth: true；侧边栏第三项「时间轴」（{ path: '/gotham/timeline', label: '时间轴' }）。
• 认证与权限：请求经 gothamClient.js（baseURL /gotham-api/v1）附 aip_token，401 自动 refresh 重放；/timeline/* 在 protected 组，无 admin 角色限制。
• 端口与 API 前缀：Gotham 后端 18083，前端前缀 /gotham-api。

3. 界面布局

+-------------------------------------------------------------+
| 页头：Gotham 时间轴  [刷新查询]   alert                       |
+-------------------------------------------------------------+
| 时间范围查询（card）：开始日期 至 结束日期 类型▾ [查询]         |
|   时间桶聚合：按日|按周|按月                                   |
|   柱状图（桶高按最大计数归一化）+ 桶计数 + 桶标签(旋转-30°)     |
+-------------------------------------------------------------+
| 新增事件（card）：标题* 时间* 类型 严重度 位置 关联实体 描述     |
|                 属性JSON [新增事件]                           |
+-------------------------------------------------------------+
| 事件列表（card）：时间|标题|类型|严重度|位置|关联实体           |
+-------------------------------------------------------------+
| 时序分析（card）Tab：[预测][周期][对比]                        |
|   预测→实际/MA/SES 折线；周期→自相关柱状图+周期表；对比→多实体折线|
+-------------------------------------------------------------+

各板块职责：

• 时间范围查询：起止日期 + 类型过滤（可选），默认 2026-07-01 ~ 2026-08-31，limit 200。
• 时间桶聚合：day/week/month 三态切换重拉聚合；桶标签截断年份前缀（如 08-01）。
• 新增事件：栅格表单，标题与时间必填；时间 datetime-local 转 ISO 提交。
• 时序分析：预测输出实际/MA（移动平均）/SES（指数平滑）三线；周期输出自相关柱状图 + 周期表（7 天「典型周周期」、30 天「典型月周期」）；对比按实体输出多序列折线。

4. 交互元素

5. 后端关联

API 客户端：gothamClient.js，axios.create({ baseURL: '/gotham-api/v1', timeout: 30000 })；请求拦截器注入 Bearer token，响应 401 自动 refresh 重放。

端点表：

关键机制：

• 查询与聚合联动：doRange 成功后自动 doAggregate；切桶、刷新查询复用当前 rangeForm 的 start/end/type。
• ECharts 实例管理：showChart 重复渲染前 dispose() 旧实例；Tab 切换后 60ms resize()；卸载时统一 dispose。
• 预测算法语义：MA 为移动平均线、SES 为指数平滑线（虚线），无历史数据时提示「暂无预测数据（该类型无历史事件）」。
• 周期表语义：period_days 命中 7/30 标注典型周/月周期，否则标「周期性波动」；柱状图 y 轴上限固定 1。

6. 权限与安全

• 认证：全部请求走 aip_token Bearer，401 自动 refresh 换发重放；刷新失效清 token 跳 /login。
• 角色限制：/timeline/* 全部在 protected 组，无 admin 细分。
• 写操作防护：新增事件校验标题与时间必填、属性 JSON 合法性；时间由 datetime-local 转 ISO。

7. 常见问题与排错

问题 1：点「查询」提示「请填写起止时间」

现象：未出列表即被前端拦截。

原因：rangeForm.start 或 end 为空。

处理：补齐起止日期重试；默认已预填 2026-07-01 与 2026-08-31。

问题 2：预测/对比图表空白提示「暂无预测数据」

现象：接口 200 但 data 为空。

原因：该事件类型无历史事件，或对比实体无数据。

处理：先做时间范围查询确认有事件，再换有数据的事件类型/实体 ID。

问题 3：时间桶柱状图不刷新或报「聚合查询失败」

现象：切桶后柱子不变或红色 alert。

原因：doAggregate 复用 rangeForm 起止为空时报错；或接口异常。

处理：先成功执行一次「查询」再切桶；查看 Network 中 /gotham-api/v1/timeline/aggregate 响应。

问题 4：新增事件后列表没立刻出现

现象：提示「事件创建成功（id=N）」但列表仍旧。

原因：创建成功后 doRange() 重查，若重查失败或事件时间超出查询范围则不显示。

处理：确认 event_time 在 start/end 范围内；或点「刷新查询」。

8. 已知缺陷与边界

注：事件编辑/删除 UI 已于 2026-09-06 修复（行内编辑/删除，调用后端 PUT/DELETE）。