NW ERP数据查询

要解决什么问题

ERP 系统沉淀了大量业务单据数据，但工程师或业务人员想取数分析时，往往要依赖 DBA 写 SQL、导出 Excel，或者在多个查询界面之间来回切换。这个技能把 ERP 数据查询收敛到一个 MCP HTTP 接口层：AI 通过统一的工具调用直接取数，鉴权、字段映射、聚合计算都由服务端完成，不需要关心数据库表结构。

核心能力与工作方式

鉴权与安全：所有请求必须在请求头携带 X-MCP-SECRET，密钥由用户在 ERP 个人资料页生成，与个人账号一一对应。系统采用三层安全机制：

• 身份认证：appsecret 是 32 位 UUID，重新生成后旧密钥立即失效
• 功能权限：无菜单权限的模块不会出现在列表中，直接查询会被拒绝；模块还需管理员开启 if_authorize=Y
• 数据权限：按用户所属公司（pk_corp）和部门过滤，跨公司数据不可见

查询工具链（8 个 HTTP 接口）：

• 单据侧：list_bill_types 列出可用单据类型 → get_bill_fields 查字段元数据 → query_bill_list 查列表（含汇总行）、get_bill_detail 查明细、query_bill_summary 做聚合统计
• 报表侧：list_report_types → get_report_fields → query_report_data，报表数据已执行公式、PK 字段自动转成名称

典型流程：先匹配业务名词到编码（如“销售合同”→ xsht），再确认字段映射（如“金额”→ ntotalamount），然后传日期范围和 conditions 查询。当用户要求“分析”“趋势”“占比”时，技能会聚合数据并用 show_widget 渲染 Chart.js 图表，数值字段自动做千分位清洗。

适用边界与注意点

• 只能查询当前用户角色权限范围内的数据，查不到不一定是“没有单据”，也可能是没权限
• conditions 只接受简单 SQL WHERE 片段，注释符、分号、子查询都会被 SqlSecurityUtils 拦截
• ERP 本身不提供分析能力，趋势判断、风险分析由 LLM 基于返回数据自行推理
• 图表颜色必须硬编码十六进制（Canvas 读不了 CSS 变量），多张图要分次调用 show_widget
• 环境变量 ERP_BASE_URL 和 APP_SECRET 必须预先配置，否则应停止执行并引导用户配置