1. 页面概览
时间轴是 LightGotham 的事件时间序列分析页，路由 /gotham/timeline，对应源码 action/web/src/views/GothamTimelinePage.vue。页面围绕事件（Event）提供四块能力：时间范围查询（start/end/type → /timeline/events/range，事件列表）、时间桶聚合（day/week/month/year → /timeline/aggregate，柱状图）、新增/编辑事件（POST/PUT /timeline/events）、时序分析增强（预测/周期/对比三个 Tab，ECharts 渲染）。
事件类型枚举 incident / movement / meeting / transaction / registration，严重度枚举 low / medium / high / critical（另有 none 兜底徽标）。时间范围默认取相对窗口（近 30 天，按本地日期计算）并提供「近 7/30/90 天」快捷档位，不再写死固定日期。事件列表支持双数据源：按时间范围（/timeline/events/range，仅 limit、无翻页）与「全部事件」（/timeline/events，limit+offset 真分页）。一句话总结：时间轴是"事件查询 + 时间桶统计 + 时序算法"的事件情报分析台。
2. 访问入口
- 路由与菜单：
/gotham布局子路由path: 'timeline'，nameGothamTimeline，标题「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）：[近7天][近30天][近90天] 自定义 起 至 类型▾ [查询]|
| 时间桶聚合：按日|按周|按月|按年 |
| 柱状图（桶高按最大计数归一化）+ 桶计数 + 桶标签(旋转-30°) |
+-------------------------------------------------------------+
| 新增/编辑事件（card）：标题* 时间* 类型 严重度 位置 关联实体 描述 |
| 属性JSON [新增事件|保存修改] |
+-------------------------------------------------------------+
| 事件列表（card）：数据源[按时间范围|全部事件(真分页)] |
| 范围模式：取回条数▾(100/200/500/1000) |
| 全部模式：每页条数▾(20/50/100) [上一页] 第 n 页 [下一页] |
| 表格：时间|标题|类型|严重度|位置|关联实体|操作(编辑/删除) |
+-------------------------------------------------------------+
| 时序分析（card）Tab：[预测][周期][对比] |
| 预测→实际/MA/SES 折线；周期→自相关柱状图+周期表；对比→多实体折线|
+-------------------------------------------------------------+各板块职责：
- 时间范围查询：默认相对窗口（近 30 天，按本地日期）；「近 7/30/90 天」快捷档位一键切换，手动改日期即切到「自定义」档位；类型过滤可选。
- 时间桶聚合：day/week/month/year 四态切换重拉聚合；桶标签截断年份前缀（如
08-01）。 - 新增/编辑事件：栅格表单，标题与时间必填；时间
datetime-local转 ISO 提交；行内「编辑」进入编辑态复用同一表单，标题变为「编辑事件 #id」。 - 事件列表：双数据源——「按时间范围」走
/timeline/events/range（取回条数100/200/500/1000，仅 limit 无翻页）；「全部事件（真分页）」走/timeline/events（limit+offset真分页，每页 20/50/100 + 上一页/下一页）。两种模式都保留行内编辑/删除。 - 时序分析：预测输出实际/MA（移动平均）/SES（指数平滑）三线；周期输出自相关柱状图 + 周期表（7 天「典型周周期」、30 天「典型月周期」）；对比按实体输出多序列折线。
4. 交互元素
| 控件 | 位置 | 含义与作用 |
|---|---|---|
| 快捷档位「近 7 / 30 / 90 天」 | 时间范围查询 | 按本地日期算出窗口并回填起止，同时把数据源切回「按时间范围」；当前档位高亮 |
| 自定义起止日期 | 时间范围查询 | 手填 date 输入，改动即把档位切为「自定义」（不再高亮任何快捷档） |
| 刷新查询 / 查询按钮 | 时间范围查询 | GET /timeline/events/range 拉事件列表并连带刷新聚合 |
| 类型下拉 | 时间范围查询 | 「全部类型」或 eventTypes 枚举，作为 range/aggregate 的 type |
| 时间桶切换 | 时间桶聚合 | 「按日 / 按周 / 按月 / 按年」（默认 week），切换即 doAggregate |
| 新增/编辑事件表单 | 新增/编辑事件 | 标题*（如 玄武集团高管会晤）、时间*、类型、严重度（low/medium/high/critical）、位置、关联实体（entity_id）、描述、属性 JSON；编辑态复用 |
| 数据源切换 | 事件列表 | 「按时间范围」/「全部事件（真分页）」两按钮，切换即重拉列表 |
| 取回条数下拉 | 事件列表（范围模式） | 100/200/500/1000 作为 /timeline/events/range 的 limit（后端限 1~1000） |
| 每页条数 + 上一页/下一页 | 事件列表（全部模式） | 每页 20/50/100；limit+offset 真分页，无 total 时下一页按「本页满页」启发式启用 |
| 行内「编辑」「删除」 | 事件列表 | 编辑进入编辑态；删除经确认后 DELETE /timeline/events/:id |
| 预测 Tab | 时序分析 | 类型 + 桶（含年）+ MA 窗口（默认 3）+ 预测期（默认 5），GET /timeline/forecast 画三线图 |
| 周期 Tab | 时序分析 | 类型 + 「检测周期」，GET /timeline/periods（bucket 固定 day，界面已标注）画自相关图与周期表 |
| 对比 Tab | 时序分析 | 实体 ID 逗号分隔（默认 graph:org:xuanwu,graph:org:tianhe）+ 桶（含年），「对比」画多实体折线 |
5. 后端关联
API 客户端：gothamClient.js，axios.create({ baseURL: '/gotham-api/v1', timeout: 30000 })；请求拦截器注入 Bearer token，响应 401 自动 refresh 重放。
端点表：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /timeline/events | 事件列表（真分页），params limit（默认 100）/ offset（默认 0）/ event_type；不接受 start/end |
| POST | /timeline/events | 新增事件 {title, description, event_time, event_type, severity, location, entity_id, properties} |
| GET | /timeline/events/:id | 事件详情 |
| PUT | /timeline/events/:id | 更新事件 |
| DELETE | /timeline/events/:id | 删除事件 |
| GET | /timeline/events/range | 时间范围查询，params start/end/type/limit（limit 1~1000，无 offset） |
| GET | /timeline/aggregate | 时间桶聚合，params start/end/bucket/type |
| GET | /timeline/forecast | 趋势预测，params event_type/bucket/window/horizon，返回 {time, actual, ma, ses} |
| GET | /timeline/periods | 周期检测，params event_type/bucket=day（固定 day），返回 {period_days, correlation} |
| GET | /timeline/compare | 多实体对比，params entity_ids/bucket，返回 {entity_id, points: [{time, count}]} |
端点与参数依据：server/server.go:571-580、handlers_timeline.go:19-34（list 默认 limit=100/offset=0）、:156-167（periods 默认 bucket=day）、timeline/service.go:63-68（bucket 常量）、:74（MaxQueryLimit=1000）、period.go:43-45（periods 非 day 返回 400）。
关键机制：
- 查询与聚合联动：
doRange成功后自动doAggregate；切桶、刷新查询复用当前rangeForm的 start/end/type。写操作（新增/编辑/删除）后走refreshAfterWrite，保持当前数据源与页码并刷新聚合。 - 相对默认时间范围：
recentRange(days)用本地日期算[今天-days+1, 今天]，默认 30 天；快捷档位 7/30/90；手动改date输入把档位切为自定义。 - 事件列表双数据源：范围模式（
/timeline/events/range，仅 limit，无 offset）；全部模式（/timeline/events，limit+offset 真分页）。两者互斥切换，切换后重拉列表。 - ECharts 实例管理：
showChart重复渲染前dispose()旧实例；Tab 切换后 60msresize()；卸载时统一 dispose。 - 预测算法语义：MA 为移动平均线、SES 为指数平滑线（虚线），无历史数据时提示「暂无预测数据（该类型无历史事件）」。
- 周期表语义：
period_days命中 7/30 标注典型周/月周期，否则标「周期性波动」；柱状图 y 轴上限固定 1。
6. 权限与安全
- 认证：全部请求走
aip_tokenBearer，401 自动 refresh 换发重放；刷新失效清 token 跳/login。 - 角色限制：
/timeline/*全部在 protected 组，无 admin 细分。 - 写操作防护：新增事件校验标题与时间必填、属性 JSON 合法性；时间由
datetime-local转 ISO。
7. 常见问题与排错
问题 1：点「查询」提示「请填写起止时间」
现象：未出列表即被前端拦截。
原因：rangeForm.start 或 end 为空（一般发生在清空了自定义日期后）。
处理：点「近 30 天」等快捷档位回填，或手动补齐起止日期；默认已按本地日期预填近 30 天。
问题 2：预测/对比图表空白提示「暂无预测数据」
现象：接口 200 但 data 为空。
原因：该事件类型无历史事件，或对比实体无数据。
处理：先做时间范围查询确认有事件，再换有数据的事件类型/实体 ID。
问题 3：时间桶柱状图不刷新或报「聚合查询失败」
现象：切桶后柱子不变或红色 alert。
原因：doAggregate 复用 rangeForm 起止为空时报错；或接口异常。
处理：先成功执行一次「查询」再切桶；查看 Network 中 /gotham-api/v1/timeline/aggregate 响应。
问题 4：新增事件后列表没立刻出现
现象：提示「事件创建成功（id=N）」但当前页列表仍旧。
原因：写操作后按当前数据源与页码刷新；范围模式下事件时间若超出 start/end 则不显示；全部模式下按 event_time ASC, id ASC 排序，新事件排在末页，当前页看不到。
处理：确认 event_time 在范围模式查询范围内；全部模式下翻到末页查找；或点「刷新查询」。
问题 5：「下一页」翻到底后显示空列表
现象：末页恰好满页时点「下一页」得到空表。
原因：响应无 total，下一页可用性按「本页满页」启发式估计（本页满 = 认为可能还有下一页）。
处理：点「上一页」返回；如需精确总数需后端补 total（当前不支持）。
8. 已知缺陷与边界
| 项 | 说明 |
|---|---|
| 范围端点无 offset | /timeline/events/range 只有 limit（1~1000），范围模式无翻页；真分页须切「全部事件」走 /timeline/events |
| 全部模式无 total | /timeline/events 不分页元数据（无 total），下一页按「本页满页」启发式，末页恰满会多一次空翻 |
| 两种模式不叠加 | 「全部事件」端点不接受 start/end，故该模式列表不套用上方时间范围过滤 |
| 周期检测固定按日 | /timeline/periods 后端固定 bucket=day（其他粒度返回 400），界面不提供桶选择（已标注） |
| 时区偏移风险 | datetime-local 本地时间转 ISO，跨时区查看有偏移 |
| 聚合柱状图无缩放 | 桶多时横向滚动，无数据缩放交互 |
注：事件编辑/删除 UI 已于 2026-09-06 修复（行内编辑/删除，调用后端 PUT/DELETE）。
注：2026-09-13 三处修订——(1) 默认时间范围由写死的 2026-07-01 ~ 2026-08-31 改为相对窗口（近 30 天，本地日期）并加「近 7/30/90 天」快捷档位；(2) 时间桶聚合与预测/对比桶选择补 year（后端 bucket 常量含 day/week/month/year，timeline/service.go:63-68）；/timeline/periods 仍固定 day 并在界面标注；(3) 事件列表新增「全部事件（真分页）」数据源，走 GET /timeline/events（handlers_timeline.go:19-34 默认 limit=100/offset=0）实现 limit+offset 真分页，范围模式保留并标注「仅 limit、无翻页」。