ZY Action Platform 分析师使用说明

适用对象：业务分析师 / 情报分析师 · 核心产品：P1 LightAIP、P2 LightFoundry、P4 LightGotham · v5 对齐 wiki/docs 系列文档与 V5 七阶段升级 · 文档日期 2026-08-30

1. 工作流总览

登录（admin 或普通账号，各产品独立 JWT；可开启 TOTP 双因子）
 ├─ AIP（18080）：
 │    ├─ 自然语言查数（NLQ）→ 看 SQL/结果/图表（执行前自动注入 RLS/CLS）
 │    ├─ 决策证据链 /decision（检索→核验→综合，逐条引用）
 │    ├─ 知识库（多格式解析，文档—章节—片段分层树）+ 实体关系抽取 /entity-extract
 │    ├─ 元数据语义标注 /schema-annotation + 会话记忆 /memory-manage
 │    └─ 多智能体编排 /orchestrate + 工作流
 ├─ Foundry（18081）：
 │    ├─ 对象查询（按字段+过滤，OOL）与 对象化 SQL 工作台 /foundry/sql
 │    ├─ 指标查询（GMV/AOV 等聚合，ValueType 13 类标准值类型）
 │    ├─ 数据集 /foundry/datasets + 数据同步 /foundry/sync + 质量画像
 │    ├─ Notebook /foundry/notebook + 块式报表 /foundry/reports + 可视化仪表盘
 │    ├─ 实体消解 Fusion /foundry/fusion + 流事件规则 /foundry/stream
 │    └─ 统一搜索（顶部全局搜索框，跨对象/指标/数据集/仪表盘融合排序）
 └─ Gotham（18083）：
      ├─ 图探索（展开/最短路径/中心度/社群/PageRank 等 10 算法）
      ├─ 图谱域（行级图谱化导入 /gotham/graph-mapping、图分区压缩 /gotham/graph-partition、时序图分析 /gotham/temporal）
      ├─ 地图视图 + 时间轴 + 多视图联动 + 全局搜索
      ├─ 模式识别命中（规则库）
      └─ 生成情报报告（HTML/PDF/Word）+ 协作项目/任务/评论

2. 登录

1. 打开 http://127.0.0.1/ → 跳转 /login（或直连产品端口）；
2. 使用管理员分配账号登录（普通用户注册：POST /api/v1/auth/register）；
3. 若管理员已为账号开启双因子认证（TOTP），登录时还需输入 30 秒轮换的动态口令（totp_code）；账号设置页完成 setup → verify-enable 后生效；
4. 顶部导航提供「智能查询」「数据源管理」「进入 Foundry」「Apollo ▾」「Gotham ▾」。

3. LightAIP：自然语言查数

入口：顶部导航「智能查询」/chat。

3.1 操作步骤

1. 输入自然语言问题（示例：查询所有订单 / 查询订单总金额 / 查询每个客户的订单数量）；
2. 提交后执行链路：意图识别 → 上下文组装（OAG 对象路 → 本体命中优先，否则 RAG 五路召回：metadata/knowledge/history/fewshot/entity 实体通道）→ Text2SQL → SQL 执行（失败自动修复 ≤2 次）→ 图表 DSL + LLM 摘要；
3. NLQ 主链路执行前自动注入 RLS/CLS 行级/列级安全（v5），注入失败直接拒绝执行；查询成功轮次自动回写会话记忆（上下文压缩 + 记忆持久化），跨轮追问不必重复全部条件；
4. 结果面板（图表 / 表格融合面板）展示：意图与置信度、数据源、生成 SQL、结果表格（敏感列自动脱敏，支持列排序 / 前端分页 / 数值右对齐）、图表（18 种图表类型，按列类型自动推荐与字段映射，工具栏支持图表切换 / 字段配置 / 下载 / 全屏，Tab 切换图表与表格）、AI 摘要。

3.2 实测示例

3.3 接口

POST /api/v1/chat   body: {"query":"查询订单总金额"}

3.4 AIP 进阶能力（v5）

边界：意图识别为关键词规则；Text2SQL 依赖外部 LLM（无 key/离线时降级）；一次只查一个数据源；工作流 send_notification 通知支持三渠道——internal（审计留痕）/ feishu（飞书私聊）/ email（SMTP 邮件），feishu / email 需管理员先在管理后台配置好凭证。

4. LightFoundry：对象查询 / 指标查询 / 数据集 / 语义检索

4.1 对象查询

入口：侧边栏「对象查询」/foundry/query，接口 POST /api/v1/objects/:id/query。

{
  "fields": ["order_id", "amount"],
  "filters": [{"field": "amount", "op": "gte", "value": 100}]
}

fields 选择返回列；filters 支持 op：eq/gt/gte/lt/lte/ne + 布尔组合 and/or/not；翻译引擎自动参数白名单防注入、link 自动 JOIN、RLS/CLS 注入（与安全标记隐藏列合并生效）。内置演示对象：customer(1) / order(2) / product(3)。限制：OOL 轻量版（单对象、traverse ≤3 层、禁点号）。

4.2 对象化 SQL 工作台（v5）

入口：侧边栏「SQL 工作台」/foundry/sql，接口 POST /api/v1/ontology/sql/translate|execute。

• 以对象名直查的受限只读 SQL：FROM/JOIN 对象名→物理表、属性→物理列，自动注入 RLS/CLS、强制外层 LIMIT（无则补 500、上限钳 5000）；
• 支持编辑态数据叠加（编辑值优先展示，edited_fields/overlay_note 标注）、CSV 导出与翻译预览（translate 回显物理参数化 SQL 不执行）；
• 安全模型：标识符白名单 + 关键字黑名单 + 字符串参数化；DML/多语句拒绝。

curl -X POST http://127.0.0.1:18081/api/v1/ontology/sql/execute \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"sql":"SELECT order_id, amount FROM order LIMIT 10"}'

4.3 指标查询

POST /api/v1/metrics/query   body: {"name":"total_gmv"}   # 返回 rows=[[6470.5]]

指标查询翻译为 SQL 时注入属性级只读权限（口径由指标定义锁定）。v5 指标字段支持 13 类标准值类型（ValueType），计算属性可引用本体函数（POST /api/v1/ontology/functions/:name/test 在线测试）。

4.4 数据集 / 同步 / 质量画像（v5）

入口：侧边栏「数据集」/foundry/datasets、「数据同步」/foundry/sync、「数据质量」/foundry/quality。

4.5 Notebook 代码工作簿（v5）

入口：侧边栏「Notebook 分析」/foundry/notebook。文本 / SQL / 图表三类单元格混排，可逐块或全量运行（POST /api/v1/notebooks/:id/cells/:cid/run、POST /api/v1/notebooks/:id/run）；SQL 单元复用对象化查询的安全翻译 + RLS/CLS + 编辑态叠加，chart 块直接复用引用 SQL 块结果集（不重算）。

4.6 块式报表（v5）

入口：侧边栏「智能报表」/foundry/reports。按文本 / 图表 / 表格块编排（GET/POST /api/v1/reports），定时生成快照（POST /api/v1/reports/:id/run）+ 邮件 / 站内多渠道分发（POST /api/v1/reports/:id/dispatch）；快照历史 GET /api/v1/reports/:id/runs、预览 GET /api/v1/report-runs/:id/snapshot；报表与指标血缘自动记录。

4.7 实体消解 Fusion（v5）

入口：侧边栏「实体消解」/foundry/fusion。规则分桶 + 相似度匹配发现疑似重复实体（POST /api/v1/fusion/projects/:id/run），阈值外 LLM 复核；人工确认/拒绝闭环（POST /api/v1/fusion/matches/:id/confirm|reject），合并结果可写回原数据或输出新数据集。

4.8 统一搜索（v5）

Foundry 顶栏全局搜索框（防抖），接口 GET /api/v1/nexus/search?q=&scopes=&limit=。融合对象 / 指标 / 数据集 / 仪表盘 / Notebook 多域结果，RRF 融合排序（1/(60+rank)），同 URI 跨 scope 累加去重；URI 直接映射功能页路由跳转，对象级可见性自动注入。

4.9 SemanticSearch（语义检索）

入口：侧边栏「语义检索」/foundry/search，接口 POST /api/v1/ontology/semantic-search。

{"query":"order","scopes":["object","metric"]}

scopes 可选 object/metric/属性等；返回匹配项（含命中原因），对象级可见性注入；输入"销售额""客户""订单"即可命中对应对象与指标。

5. LightGotham：图探索

入口：Gotham ▾ → 情报工作台 /gotham。SVG 自绘图谱（person/org/ship 分色圆形节点 + 有向边），顶部显示节点/边统计。演示图谱（10 节点 + 8 边）：graph:person:zhy（张远，玄武集团）、graph:org:xuanwu（玄武集团，密级 secret）、graph:org:tianhe（天河贸易）、graph:ship:taihe（泰和轮）等。

图分析引擎 10 支算法仅 admin 角色可执行。硬上限：展开 limit≤1000、深度 1-3 度，超限 422 GOTHAM_EXPAND_LIMIT_EXCEEDED；路径节点≤100。实测：展开 zhy depth=2 → nodes≥1、levels≥1；最短路径 zhy→tianhe → distance≥1；中心度 entries≥5；社群 communities≥1。

5.3 图谱域分析（v5，仅 admin）

6. LightGotham：地图 / 时间轴 / 多视图联动 / 全局搜索

6.1 地图视图

入口：/gotham/map。

演示要素 6 个（5 点 1 线：北京/上海/广州/青岛/深圳 + 华北-华东航线）。实测 bbox(115-118/39-41) 命中北京要素（graph:person:zhy）。

6.2 时间轴

入口：/gotham/timeline。事件列表 GET /api/v1/timeline/events；范围查询 GET /api/v1/timeline/events/range?start=2026-07-01&end=2026-08-31；周/日桶聚合 GET /api/v1/timeline/aggregate?start=&end=&bucket=week；预测/周期/对比接口可用。演示事件 9 条（meeting/movement/transaction/registration/incident），严重度 critical/high/medium/low。Time-Wheel 时间轮盘未落地（以 aggregate/forecast/periods 接口实现）。

6.3 多视图联动

入口：/gotham/views。将图谱视图 A 与地图视图 B 建立联动，在 A 上设置过滤器后自动广播到 B。

实测：graph 会话过滤 {"field":"region","op":"eq","value":"北京"} → 广播到 map 会话 target_count≥1。

6.4 全局搜索

GET /api/v1/search?q=张远 — 四域并发（实体/图节点/时间轴/地理），每域 topN、总数上限 40。

7. LightGotham：模式识别与情报报告

7.1 模式识别命中

内置规则：

操作：创建规则 POST /api/v1/patterns/rules → 评估 POST /api/v1/patterns/rules/:id/evaluate → 全量评估 POST /api/v1/patterns/evaluate-all → 命中列表 GET /api/v1/patterns/hits?rule_id=，可 acknowledge/resolve；告警看板 + WebSocket 广播。

7.2 生成情报报告

入口：/gotham/reports。

{
  "title": "张远关联情报简报",
  "report_type": "entity",
  "sections": [{"kind": "entity", "entity_id": "graph:person:zhy"}]
}

报告为块结构（heading/paragraph/table/kv + 嵌入对象快照），覆盖关键实体、重点事件、研判结论（置信度/关注级别/作者）。

7.3 协作工作流

入口：/gotham（协作区）。项目/成员/任务/评论/活动/通知/共享视图，WebSocket 实时通知——把结论推进为团队行动。

7.4 分析师推荐流程

1. 图谱展开关键人物（张远）→ 高亮邻居 → 确认关联网络；
2. 计算中心度/社群/PageRank，定位关键节点（资金流：玄武集团→天河贸易 weight=3, amount=500000）；
3. 切地图视图看地理分布，切时间轴看事件时间线，全局搜索快速定位；
4. 多视图联动将"北京"等条件广播，缩小范围；
5. 用 graph-partition 看社区分布、temporal 看关系随时间的演化（admin）；
6. 评估模式规则 → 命中记录处置；
7. 生成情报报告 → 导出 HTML/PDF/Word 分发决策者 → 建协作任务跟进。

8. 未实现边界（如实标注）

9. 常见问题