维涛ERP库存查询

概述

ERP 库存查询（接口方式）

安全与合规声明

逐条对应常见的安全排查项：

• 只读：所有取数请求固定 type=read，不调用任何写接口，不建单、不改单、不保存数据。
• 无内置凭据：技能包内不含任何账号、密码、Token、默认地址或租户标识。四项登录信息全部由使用者在使用时提供。
• 凭据不落盘：脚本不写 Cookie 或密码到磁盘，不把密码写进任何输出文件，不在日志中打印密码；

报表「查询概要」页默认不写入 ERP 地址与登录账号（需显式加 --include-source-info 才会写）。

• 输出最小化：对使用者只输出「产品编号」与「可开单库存量(业务单位)」两列。

品牌、系列、仓库、批号、规格、价格、成本、实物库存等内部字段虽然会随接口返回，但在本地筛选完成后即被丢弃 —— 不写进结果文件、不打印、不进报表。

• 无外呼：除使用者显式指定的 ERP 地址外，不与任何第三方服务通信；无遥测、无埋点、无回传。
• 不下载远程脚本：所有逻辑都在包内脚本里，运行期不从网络拉取或执行任何代码。
• 依赖最小：仅 requests + openpyxl，无其他第三方包。
• 权限最小：仅需 Bash 与 Read。

定位与边界

• 做什么：向使用者取登录信息 → 接口登录 → 按功能号查询库存 → 过滤 → 只输出

「产品编号 + 可开单库存量(业务单位)」两列 → 生成 Excel 清单。

• 不做什么：不建单、不改单、不保存任何数据（纯 type=read 只读取数）。
• 输出边界（硬性）：对使用者只开放两个字段 —— 产品编号、可开单库存量（业务单位）。

取数时仍会拉回完整数据行（否则无法做本地区间筛选、也无法定位产品），但白名单之外的字段在落盘与打印之前一律被裁掉：报表里不会出现品牌、系列、仓库、批号、规格、价格、成本、实物库存等任何其他列。需要扩列时用 --fields，那属于内部核对用途，不要对使用者开放。

• 适用功能：默认 1800 仓库即时库存；同族库存功能只要换 --func 功能号即可（先用 --describe 探字段）。

换功能号后若字段名不同，脚本会提示「该功能的显示字段里没有 matname / freestock」。

• 适用使用者：同一款 ERP 在不同企业是各自独立部署的，本技能按「一套流程、多家使用」设计，

使用者可能是陶瓷、瓷砖、建材等行业的厂家或经销商，每个人用自己的地址、自己的账套。

• 发布方声明：本技能由「携简」发布并维护，面向携简 / victop 系 ERP 的通用接口取数场景；

文中的产品名仅用于说明适用对象，方便使用者搜索识别。使用者需自行确保已获得对目标 ERP 实例的合法访问授权，并自行承担因部署版本差异导致的接口不兼容风险。

前置：登录信息一律向使用者索取

技能包不含任何默认值，因为它服务的是多家企业各自的部署。启动任何取数前，先拿到这四项：

取值优先级：命令行参数 > 环境变量 > --ask 交互询问。四项缺任意一项，脚本都会打印MISSING=... 加一份中文索取清单，并以退出码 2 结束——绝不使用兜底值。

怎么问（可直接照这段话术发给使用者）

为了帮你查库存，需要你提供 4 项你自己企业的 ERP 信息：

1. ERP 地址——浏览器里登录页的网址直接发我就行
2. 登录账号
3. 登录密码
4. 公司代码——数字，在 ERP 的「用户信息」里能看到

这些信息只在本次查询中使用，我不会写进任何文件，也不会替你保存。

交互规则（AI 执行时遵守）

1. 一次问全：四项一起问，不要挤牙膏式的一项一项要。使用者只给了一部分时，只追问缺的那几项。
2. 本次对话内已给过就直接复用，不要重复询问。但换企业、换账号时必须重新确认，

不要把上一家的地址或凭据套到这一家身上。

1. 不知道就问，不要猜：不要用「上次那个地址应该是……」「公司代码一般是 1001」这类假设。

猜错地址会连到别人家的系统，这既是事故也是安全问题。

1. 密码不回显：拿到后优先用环境变量前缀的形式传参，而不是 --pwd 出现在参数列表里：

   XJ_ERP_HOST='http://<地址>' XJ_ERP_USER='<账号>' XJ_ERP_PWD='<密码>' 
     XJ_ERP_COMPANYID='<公司代码>' python scripts/erp_stock_query.py --func 1800 --filter "..."

回复使用者时不要复述密码，也不要把它贴回聊天里确认。

1. 不写盘：不要把凭据写进技能目录、记忆文件、配置或任何脚本。凭据只存在于当次对话与当次进程环境里。
2. 看到 MISSING= 就去问：脚本打出 MISSING=host,user,pwd,companyid 就是明确信号——

该向使用者索取了。不要重试脚本、不要空跑、不要自己编一个值。

地址容错

使用者的输入可能五花八门，脚本会自动归一化成 scheme://host[:port]：

若某企业把 ERP 部署在非默认上下文路径下，用 --login-path / --erp-base 覆盖（详见 references/erp-api.md）。

铁律（先读这五条）

1. 走 HTTP 接口，不要走网页 / GUI 路线。 本技能按无图形界面环境设计；在服务器、容器、沙箱等环境下驱动真实浏览器往往直接失败（进程能起、页面随即被关闭）。所有操作必须走接口。
2. 登录信息由使用者提供，严禁写进技能或脚本。 运行时通过环境变量 / 参数传入，或 --ask 交互输入。这既是安全要求，也是上架审核的检查项。
3. 一企一凭据，不要串用。 同一个使用者在多家企业之间切换时，每次都重新确认是哪一家；不要缓存跨企业的地址或账号。
4. 会话只有几分钟。 登录与取数必须在同一次脚本执行内完成，不要「先登录存 Cookie，过一会儿再取数」。
5. 只读。 不碰任何写接口。取数结果落本地文件后，后续分析与出报表都读本地文件，不要为了同一份数据反复登录取数（会话短，且浪费）。

标准工作流

第 0 步：向使用者取四项登录信息

按上面的「交互规则」问齐 ERP 地址 + 账号 + 密码 + 公司代码。不要尝试网页登录、也不要让使用者去某个页面手工录入。本机人工手跑时，也可以用 --ask 让脚本逐项问（密码不回显）：

python scripts/erp_stock_query.py --ask --func 1800 --describe

第 1 步：先探字段（换功能号或换企业时必做）

XJ_ERP_HOST='<地址>' XJ_ERP_USER='<账号>' XJ_ERP_PWD='<密码>' XJ_ERP_COMPANYID='<公司代码>' 
  python scripts/erp_stock_query.py --func 1800 --describe

输出该功能的「查询条件（head.fields）」与「显示字段（body.fields）」清单 —— 这是从使用者自己的 ERP 动态获取字段字典的官方途径，也是本技能不内置任何字段字典的原因。拿到清单后再决定过滤条件怎么写。

⚠ --describe 的输出是功能元数据（用于确认功能与字段是否可用），不是查询结果。

它是给执行者看的，不要整份贴给使用者，也不要把它当作库存信息交付。

字段命名规律与常见列名见 references/field-conventions.md。换了企业一定要重跑这一步：自定义字段（CV 系列）各家不同。

第 2 步：取数

export XJ_ERP_HOST='<地址>' XJ_ERP_USER='<账号>' XJ_ERP_PWD='<密码>' XJ_ERP_COMPANYID='<公司代码>'

# 按产品编号查（产品编号常为后缀形态，务必用 like，脚本默认即 like）
python scripts/erp_stock_query.py --func 1800 --filter "产品编号=<编号>" --outdir ./erp_stock_out

# 多条件叠加（AND 关系，--filter 可重复）
python scripts/erp_stock_query.py --filter "仓库编号=<仓库>" --filter "品牌=<品牌>" 
  --filter "规格=<规格>" --outdir ./erp_stock_out

# 数值区间（自动走本地精确筛选，服务端会忽略区间条件）
python scripts/erp_stock_query.py --filter "可开单库存>1000" --outdir ./erp_stock_out

# 全量（不加条件）
python scripts/erp_stock_query.py --outdir ./erp_stock_out

# 直接写原始 cfilter（实体列名 + 运算符）
python scripts/erp_stock_query.py --filter-json '{"matname":{"like":"<编号>"}}' --outdir ./erp_stock_out

# 条件写法不确定时，加 --probe：先带条件查，无结果则全量拉回本地筛选
python scripts/erp_stock_query.py --filter "产品编号=<编号>" --probe --outdir ./erp_stock_out

产出 <outdir>/result_<func>.json。它的 rows 只有两列 —— matname（产品编号）与 freestock（可开单库存量 / 业务单位）；meta.fields_exposed 记录本次开放了哪些列。日常取数不再生成 config_<formid>.json（只有 --describe 时才落盘）。

中间文件 result_*.json 的 meta.usercode 会记录本次登录账号（便于核对是哪家账套取的数据）。

该文件用于本地分析，对外发送前请先确认是否需要删除或脱敏。

白名单之外的字段在落盘前已被丢弃，所以：

• 不要试图从 result_*.json 里找品牌、仓库、批号、价格等字段 —— 它们不在文件里；
• 需要按这些维度筛选，照常用 --filter（筛选发生在裁剪之前，不受影响）。

第 3 步：生成库存清单

python scripts/erp_stock_report.py --input ./erp_stock_out/result_1800.json 
  --out ./kb/库存清单.xlsx --title "库存查询"

产出 2 个 Sheet：查询概要 + 库存清单。

库存清单 只有两列 —— 产品编号、可开单库存量(业务单位)，末行为合计；品牌 / 系列 / 仓库 / 批号 / 规格 / 价格等一律不进报表。查询概要 页默认对 ERP 地址与登录账号做脱敏；确实需要写入时加 --include-source-info。

第 4 步：回读校验并交付

生成后必须用 openpyxl 回读一次，核对：

• Sheet 名称与数量应为 查询概要、库存清单；
• 库存清单 表头只有两列，且为「产品编号」「可开单库存量(业务单位)」；
• 明细行数 == 取数行数；
• 末行合计 == 各行可开单库存量之和。

确认无误再把 xlsx 路径给使用者。

多企业（多租户）使用注意

过滤条件速查

--filter "中文名=值" 支持的中文名（→ 实际传给接口的实体列名）：

• 默认运算符 like（包含匹配）。不要用 equal 查产品编号 —— 产品编号常为后缀形态（前缀是品牌/工厂码，同一编号会以多个前缀出现），equal 会一条都查不到。
• 多条件之间是 AND。
• 数值 / 日期区间条件一律走本地筛选：这类区间运算符（gt/ge/lt/le 以及头部的库存区间、入仓日期区间条件）在部分部署下会被服务端静默忽略——不报错，直接返回全量。所以直接写 --filter "可开单库存>1000" 即可，脚本会自动拉全量后本地精确筛选。
• 筛选口径与输出口径一致：可开单库存 筛的是业务单位（箱 / 片 / 个）的数字，也就是报表里那一列，两者可以直接对照；要用基本单位口径筛，写 可开单库存(基本单位)>1000。
• 其余数值中文名 实物库存 / 开单未提量 / 留货量 / 在途量 / 滞留天数 / 可开单平方 仍按基本单位或 ㎡ 计算 —— 它们只用于筛选，不会出现在输出里。
• 筛选维度可以比输出字段更宽：按品牌、仓库、批号、规格等筛选都支持，筛选发生在字段裁剪之前，只是这些列不会进结果文件与报表。
• 上表的字段映射在 victop 系 ERP 中通用，但不同部署的自定义字段（CV 系列）会有差异，换环境时请先 --describe 核对。

输出与汇报规范

• 对使用者只给两个字段：产品编号、可开单库存量（业务单位）。

报表里没有第三列；聊天回复里同样不要附带品牌、系列、仓库、批号、规格、价格、成本、实物库存、占用量等任何其他字段 —— 这是本技能的输出约定，不是可选项。

• 报表落 kb/（或使用者指定目录），命名 {功能号}库存清单.xlsx，2 个 Sheet（查询概要 + 库存清单）。
• 数量口径是业务单位（箱 / 片 / 个），不换算、不与基本单位混加、不给平方数。
• 聊天回复只给摘要：取数时间、是哪家企业/地址、过滤条件、命中行数、产品编号数、

可开单库存量合计；需要明细时给 xlsx 路径。

• 回复中不要出现密码；账号与地址按需表述，不必逐字复述。
• 用中文、结构化表格呈现。

常见坑

参考文件

• references/erp-api.md —— 接口协议细节：登录表单、runProject 参数、formid 命名规则、配置接口、响应结构、字段命名规律，以及 --login-path / --erp-base 的用法。
• references/field-conventions.md —— 字段命名规律、单位三套口径、常见列名词表，以及「如何用 --describe 从自己的 ERP 动态取字段字典」。

上架元数据说明

本技能的 frontmatter 同时包含两套发布通道所需字段，便于一次打包、两处上架：

author 与 license 按发布方的实际情况填写；如需声明开源许可，请在提交前替换 license 的值。

依赖

Python 3 + requests + openpyxl。