Nges Data 360

nges-data-360 — 重楼数据洞察与分析

把用户的业务问题转化为重楼 GQL 查询，拉取数据并给出可解读的洞察。所有平台交互（查元数据、查下属、跑查询）全部通过 MCP 工具完成，不依赖任何本地脚本或 .nges 配置。

定位：只读的数据洞察。专注 query / 聚合 / 分组 / 排名 / 趋势，不做 insert/update/delete（写操作请用 paris-gql-query）。这样既贴合"分析"诉求，也避免在探索性分析中误改数据。

1) 为什么这样设计

数据洞察的难点不在于写 SQL，而在于三件容易出错的事：问对对象和字段、框对数据范围、给出有意义的解读。本 Skill 把流程固化为：先用元数据接口把对象/字段问清楚（绝不猜字段名），再根据用户角色框定他能看、且想看的数据范围（自己 vs 下属团队），最后构造查询并把数字翻译成业务结论。

2) 核心工作流

用户的业务问题（"本月我团队的拜访量怎么样？"）
        │
        ▼
Step 1 拆解分析意图  ──→ 指标 / 维度 / 时间范围 / 过滤 / 排序
        │
        ▼
Step 2 框定数据范围  ──→ 自己 or 下属团队？（角色感知，见 §4）
        │
        ▼
Step 3 解析对象与字段 ──→ MCP 实时查元数据（绝不猜字段，见 §3）
        │
        ▼
Step 4 构造 GQL      ──→ 过滤/聚合/分组/排序/分页/关联（见 §5、references）
        │
        ▼
Step 5 执行查询      ──→ MCP GraphqlQuery
        │
        ▼
Step 6 洞察输出+可视化 ─→ 数据 + 业务解读 + （必要时）图表 + 建议

Step 1 — 拆解分析意图

把自然语言翻成结构化的分析五要素，缺失项先合理假设并在结果里说明，不要为小事反复打断用户：

• 指标：要算什么？计数（拜访次数）、求和（费用）、平均、占比、去重计数、排名。
• 维度：按什么分组？按人（owner/岗位）、按时间（天/月）、按类型、按产品。
• 时间范围：默认按"本月"理解相对时间；记住日期字段是秒级 Unix 时间戳（见 §6）。
• 过滤：状态、类型、特定对象等约束。
• 范围：本人数据，还是下属/团队数据？（进入 Step 2）

Step 2 — 框定数据范围（角色感知）

核心原则：重楼按角色配置了行权限，执行 GQL 时会自动注入对应的数据范围过滤。 因此默认情况下无需手写 owner 或 belong_territory 条件——医药代表查到的自动就是本人数据，地区/大区经理查到的自动就是其团队/下属链数据。手动再叠加范围条件多此一举，还可能与行权限取交集导致结果偏窄。

角色识别仍然有用，但用途变了：用来理解返回数据的口径、组织洞察措辞、判断是否要逐人对比，而不是拼范围条件。调用 MCP GetStaffUserInfo（无参，当前登录用户）取 identity_tag：

只有少数场景才需要显式加范围条件：

• 管理者想"只看自己"而非整个团队 → 加 owner: $_uin 主动收窄。
• 聚焦/对比"某个特定下属或某层级" → 用 ListSubordinateTerritory 取目标 territory_code，再显式 belong_territory: {_in: [...]}。
• "按每个成员拆开对比" → 直接 _group_by: [owner] 即可（行权限已把数据限定在可见集合内，分组自然按可见的本人/下属拆分），无需额外范围条件。

数据范围与角色的完整说明见 references/roles-and-data-scope.md。

Step 3 — 解析对象与字段（绝不猜字段）

元数据是运行时配置，存在平台数据库里，代码库里搜不到、也不能凭记忆猜。字段名/类型一旦猜错，查询要么报错要么静默返回错数据。所以编写任何 GQL 前必须先确认对象与字段：

1. 不确定对象名时 → MCP GetObjectList（DataServer.MetadataService）按关键词搜索，拿到准确对象名。
2. 拿对象字段详情 → MCP GetObjectsByNames（DataServer.MetadataService），批量传入对象名，返回每个对象的 fields（含 name、value_type、选项配置）和 relations（关联关系）。编写聚合/过滤/赋值前必须核对 value_type。

常用业务对象（拜访、会议、用户行为）的语义说明与典型分析模板见 references/common-scenarios.md——但其中字段仅为典型示例，实际字段一律以 GetObjectsByNames 返回为准。

Step 4 — 构造 GQL

根据五要素拼装查询。最常用的是聚合 + 分组 + 时间过滤 + 排序：

# "本月我团队各成员的拜访次数排名"
# 行权限自动限定为当前用户可见范围（团队），无需手写 belong_territory
# 拜访明细在 visit_item（含 hcp_id）；actual_date 实际拜访日期；status=2 已提交
{
  visit_item(
    _where: {
      actual_date: {_gte: 1717171200, _lt: 1719763200}
      status: 2
    }
    _group_by: [owner]
    _order_by: {cnt: _desc}
  ) {
    owner
    cnt: _count(id)
  }
}

完整语法（过滤运算符、聚合函数、分组 having、关联查询、子查询、系统变量/函数）见 references/gql-syntax.md；高频分析模板见 references/common-scenarios.md。

Step 5 — 执行查询

通过 MCP DataServer__DataService__GraphqlQuery执行：参数 {"query": "<GQL>"}，返回 {"affect_rows": "0", "data": {"<对象名>": [...]}}（data 为结构化对象，按对象名取结果数组；详见 mcp-tools.md）。

• 查询为只读，验证通过即可直接执行并展示，无需再次找用户确认。
• 若查询语法没把握，可先用 GraphqlQuery 传 {"query": "...", "only_validate": true} 做 dry-run 校验（不实际取数）。

MCP 工具的 server 名、方法名、参数与返回结构详见 references/mcp-tools.md。

Step 6 — 洞察输出与可视化

不要只甩数字。把结果翻译成业务结论：指出关键数值、对比/排名、异常点，必要时给一句可执行建议。

必要时生成图表：当结果呈现趋势、排名/对比、占比时，可视化比文字更直观——折线看变化、柱状比高低、饼图看构成。用脚本 ${SKILL_DIR}/scripts/render_chart.py（SKILL_DIR=本 skill 根目录）把结果渲染成自包含 HTML 图表，再把路径告知用户预览。作图前记得把枚举 value 翻成中文 label、金额（×100）还原为元。单值或两三行的小结果用文字/表格即可，不必强行作图。何时作图、图型选择、结果→spec 转换详见 references/chart-output.md。

输出结构见 §7。

3) 工具调用规范

平台数据交互（识别角色、查元数据、查下属、跑查询）全部通过 MCP 完成，不用 python 脚本访问平台、不读 .nges。调用前先用 mcp_get_tool_description 获取该工具的参数 schema，再用 mcp_call_tool 执行。

例外：结果可视化的 scripts/render_chart.py 属本地输出渲染，不访问平台，不在此限。

server 名以 mcp.json 实际配置为准

4) 角色与数据范围速记

默认不手写 owner/belong_territory，行权限按角色自动过滤。仅在「管理者只看自己」（加 owner: $_uin）或「聚焦/对比特定下属」（ListSubordinateTerritory + belong_territory {_in}）时才显式收窄。角色用 GetStaffUserInfo 的 identity_tag 判断（见 Step 2）。详见 references/roles-and-data-scope.md。

5) 关键约束（沿用重楼 GQL 规则）

字段类型与赋值/过滤格式速查见 references/gql-syntax.md 末尾的数据类型对照表。

6) 必须参考（渐进式披露）

加载策略：任何分析都先读 mcp-tools.md + gql-syntax.md；涉及下属/团队读 roles-and-data-scope.md；命中拜访/会议/用户行为场景读 common-scenarios.md 直接套模板；需要作图读 chart-output.md。

7) 输出契约

📊 {分析主题}

- 数据范围: {本人 / 团队（含下属）/ 指定岗位}
- 时间范围: {起 ~ 止}
- 涉及对象: {对象名}

【结果】
{表格或要点：关键数值、排名、对比}

【洞察】
{1-3 条业务解读：趋势、异常、对比结论}

【图表】（必要时）
{生成的 HTML 图表路径，提示在 IDE/浏览器预览}

【GQL】
\`\`\`gql
{执行的查询}
\`\`\`

简单问题可直接给结论+数字，不必拘泥格式。复杂对比/排名建议用表格；趋势/排名/占比可叠加一张图（见 chart-output.md）。

8) 澄清策略

能假设就假设并说明，只在以下情况澄清（猜错代价高）：

• 分析对象完全不明：连查哪类数据都无法判断时（拜访？会议？行为？）。
• 数据范围歧义且影响结论：分不清要"本人"还是"团队"，且两者结果差异大时。
• 指标口径模糊：如"活跃度"可能指多种定义，需确认口径。

时间范围、排序方向、返回条数等小事，先用合理默认（本月、降序、Top 20）并在输出中注明即可。