时序分析 · LightGotham · frontend-intro-v5

1. 页面概览

时序分析页（TemporalPage.vue）是 LightGotham V5 Stage 4 图谱域（B4-3）的时间维图分析工具：它利用图边上的时间信息（occurrence_time 属性，由图谱映射页的 time_col 写入），在用户设定的时间窗内回答三类问题——「时窗内子图长什么样」（时窗子图）、「每天/每周/每月图在增长多少」（时间桶趋势）、「时窗内两点之间是否可达、最短路多长」（时窗内最短路径）。页面顶部设置 From/To 时窗与桶粒度，下方依次展示趋势图、ECharts 力导子图与路径查询结果。

一句话总结：时序分析页把图从"静态结构"变成"可随时间切片查询、趋势观察、路径追踪"的动态视角。

2. 访问入口

路由 path /gotham/temporal、name GothamTemporal、meta.title「时序分析」、requiresAuth 为真，挂在 GothamLayout 子路由；侧边栏入口见 GothamLayout.vue 菜单「时序分析」。前端源码 action/web/src/views/gotham/TemporalPage.vue（293 行），API 客户端 action/web/src/api/temporalApi.js。
认证：aip_token + gotham_refresh_token；本页接口挂 /analysis/graph/* admin 组，非 admin 返回 403 AUTHZ_ERROR。
端口 18083，API 前缀 /gotham-api/v1。

3. 界面布局

+---------------------------------------------------------------+
| Gotham 时序图分析   [刷新]                                    |
+---------------------------------------------------------------+
| [alert 操作结果提示条（可关闭）]                               |
+---------------------------------------------------------------+
| [时窗与桶参数]  From | To | Bucket(按天/按周/按月)             |
|  [运行分析]  时窗子图：N 节点 / M 边                          |
+---------------------------------------------------------------+
| [时序趋势（新增节点 / 新增边）]  ECharts 柱状+折线            |
+---------------------------------------------------------------+
| [时窗子图]  ECharts graph 力导布局                            |
+---------------------------------------------------------------+
| [时窗内最短路径]  From 节点 | To 节点  [查询路径]             |
|  距离 N（K 个节点）  a → b → c                                |
+---------------------------------------------------------------+

页头：标题 +「刷新」（重新运行时窗子图与趋势分析）。
时窗与桶参数卡片：From/To 时间输入 + 桶粒度下拉 +「运行分析」。
时序趋势卡片：各桶新增节点（柱状）/新增边（折线）的 ECharts 图。
时窗子图卡片：ECharts 力导布局展示时窗内节点与边。
路径查询卡片：起点/终点节点 ID + 最短路径结果。

4. 交互元素

控件	位置	含义与作用
From / To	时窗与桶参数	时间边界，支持 RFC3339 或 `2026-08-01` 等常见格式；留空表示不设下界/上界（闭区间含端点）
Bucket 下拉	时窗与桶参数	趋势图桶粒度：按天 day / 按周 week / 按月 month
「运行分析」	时窗与桶参数	并行调子图 + 趋势接口，成功后渲染两张 ECharts 图并显示「时窗子图：N 节点 / M 边」
「查询路径」	路径查询卡片	需填起点/终点节点 ID，调时窗内最短路径，显示距离与节点序列
「刷新」	页头	重新运行时窗子图与趋势分析

5. 后端关联

方法	路径	用途
POST	`/analysis/graph/temporal/subgraph`	时窗子图，body `{from, to}` → `{nodes, edges}`
POST	`/analysis/graph/temporal/trend`	时间桶统计，body `{from, to, bucket}` → `[{time, nodes, edges}]` 按时间升序
POST	`/analysis/graph/temporal/path`	时窗内最短路径，body `{from, to, window:{from, to}}` → `{path, nodes, edges, distance, hint}`

关键机制

时间语义：时窗为闭区间 [from, to]；边属性 occurrence_time（图谱映射页 time_col 写入）落入时窗的边 + 两端节点构成子图；无该属性或解析失败的边视为无时间信息，不落入任何时窗。

时间解析：RFC3339 优先，兼容 2006-01-02 15:04:05、2006-01-02T15:04:05、2006-01-02；from 晚于 to 返回 400「时窗 from 不能晚于 to」。

趋势桶：按 day/week/month 对齐桶起点（UTC），桶内 Edges = occurrence_time 落桶的边数，Nodes = 首次出现在桶内的节点数；无效 bucket 返回错误。

路径：先取时窗子图快照（只读 temporalSubStore）再复用加权最短路径算法；起点或终点不在时窗子图内时不视为错误，返回 distance=-1 + hint「起点或终点不在时窗子图内（无命中边或节点不存在）」。

节点属性掩码：子图响应经 maskNodeProperties 过滤敏感属性后返回。

6. 权限与安全

认证：JWT Bearer + refresh token 轮换；/analysis/graph/* 仅 admin 角色可执行（非 admin 403）。
数据级安全：子图节点属性经 maskNodeProperties 掩码，避免敏感属性透出。
只读能力：三个端点只读图数据，不产生写操作。

7. 常见问题与排错

7.1 趋势图显示「暂无趋势数据」

现象：趋势卡片显示提示文字而非图表。
原因：时窗内没有带 occurrence_time 属性的边（如未在图谱映射页配置 time_col 并执行图谱化）。
处理：回到图谱映射页配置 time_col 并重新执行图谱化，再运行分析。

7.2 「查询路径」返回距离 -1

现象：提示「距离 -1」且显示 hint 文案。
原因：起点或终点节点不在时窗子图内（无命中边或节点不存在）。
处理：扩大时窗范围或确认节点 ID 正确；也可先用时窗子图确认节点是否在图中。

7.3 时间格式报错

现象：提示「时序分析失败：... from 时间格式非法」。
原因：From/To 填了不支持的时间格式。
处理：使用 RFC3339（如 2026-08-01T00:00:00Z）或 2026-08-01 格式。

7.4 非 admin 用户操作报 403

现象：所有接口返回 AUTHZ_ERROR。
原因：/analysis/graph/temporal/* 为管理能力。
处理：用 admin 角色账号操作。

8. 已知缺陷与边界

缺陷/边界	说明
仅 admin 可执行	三个端点均挂 admin 中间件
依赖 time_col	无 `occurrence_time` 属性的边不参与时窗过滤，趋势/子图可能为空
桶对齐 UTC	桶边界按 UTC 计算，跨时区展示可能与本地日期错位
路径在子图内寻路	时窗内最短路径只在时窗子图上计算，忽略时窗外更短路径
节点属性掩码	子图响应属性被 mask，部分原始属性前端不可见