维涛ERP销售库存查询

概述

ERP 库存与销售查询（接口方式）

安全与合规声明

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

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

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

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

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

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

定位与边界

• 做什么：向使用者取登录信息 → 接口登录 → 按模式取数分析：
  • stock 库存模式：过滤 → 只输出「产品编号 + 可开单库存量(业务单位)」两列 → Excel 清单；
  • sales / cross / all 分析模式：销售明细多维报表、畅销×库存交叉分析与补货建议

（面向企业内部经营分析，字段范围见「销售明细（2931）与畅销分析」一节）;

• turnover 周转模式：1803 出入库流水 × 1800 库存快照 → 仓库周转率/周转天数/可支撑天数/

库销比/破损率/呆滞库存（见「仓库业务汇总（1803）与仓库周转分析」一节）。

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

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

• 适用功能：默认 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）。

统一入口 erp_query_all.py（推荐）

库存、销售、周转已合并为一个统一入口，五种模式一条命令切换（登录信息仍走环境变量，四项同前）：

# 库存清单（默认 1800，支持 --filter，出两列 Excel + 可选多 Sheet 报表）
python scripts/erp_query_all.py stock --filter 品牌=金意陶
# 销售明细 + 畅销分析报表（不填日期 = 自动探测库里实际最新有数据的月份，往前取 3 个月）
python scripts/erp_query_all.py sales --sales-begin 2025-01-01 --sales-end 2025-06-30
# 畅销产品 × 当前库存 交叉分析 + 补货建议（top 默认 10）
python scripts/erp_query_all.py cross --top 10 --sales-begin 2023-01-01 --sales-end 2025-06-30
# 仓库周转分析（1803 出入库流水 × 1800 库存快照；不填日期同样自动探测最新数据月）
python scripts/erp_query_all.py turnover --turnover-begin 2024-01-01 --turnover-end 2024-03-31
# 一次跑全：库存清单 + 销售分析 + 交叉分析 + 仓库周转
python scripts/erp_query_all.py all

要点：

• 凭据自动记录：首次运行前把四项登录信息交给脚本（环境变量或对话提供），之后 7 天内

直接跑即可（脚本输出 [凭据] 复用本地记录）；切换地址/账号/公司代码时带上新值即自动覆盖；超过 7 天脚本会拒绝执行并列出缺少的项，向使用者重新索取即可。

• 日期自动探测：sales / cross / turnover 模式不填日期时，脚本从当前月往前逐月探测

（空月份响应很快），找到实际有数据的最近月份，取该月往前 --months（默认 3）个自然月；跨月窗口按月分片抓取，单月超时自动降级分片并重新登录续抓。测试账套「本年无数据」的场景不再取空。

• 1803 断点续跑：周转模式按「公司 × 自然月」把原始流水缓存到 <outdir>/1803_raw/，

中断后重跑只补缺的月份；--refresh-flow 才强制重取。单公司单月可达 1.5 万行 / 2 分钟，3 个月窗口约 10~15 分钟，建议放后台跑。

• cross 模式自动取销售（2931）与库存（1800）两套数据合并；若 --outdir 里已有

result_1800.json 会直接复用（加 --refresh-stock 强制重取），也可用--sales-json / --stock-json 指定现成文件，避免重复登录拉数（呼应铁律第 5 条）。

• cross 报表 4 个 Sheet：畅销产品×库存（含可覆盖月数与状态着色）/ 补货建议 /

畅销产品仓库分布 / 查询概要。

• 库存状态口径：可开单≤0 断货；<1 个月严重偏低；<3 偏低；<6 偏紧；≥6 充足。

可覆盖月数 = 可开单库存 ÷ 月均销量（月均 = 累计销量 ÷ 有销量的自然月数）。

• 旧的单脚本入口（erp_stock_query.py + 两个报表脚本）仍然可用，统一入口内部就是

组合调用它们；--describe 探字段等高级用法走原脚本。

铁律（先读这五条）

1. 走 HTTP 接口，不要走网页 / GUI 路线。 本技能按无图形界面环境设计；在服务器、容器、沙箱等环境下驱动真实浏览器往往直接失败（进程能起、页面随即被关闭）。所有操作必须走接口。
2. 凭据本地记录，7 天有效。 首次使用时向使用者索取四项登录信息；提供后由统一入口

自动记录到技能目录下 .credentials.json（密码 Base64 混淆，仅本机可读）。之后 7 天内复用，不再重复询问；切换地址/账号/公司代码，或记录超过 7 天有效期后，必须重新向使用者索取才能执行。凭据不写进脚本源码、不进对话记忆文件；分享技能包前剔除.credentials.json。

1. 一企一凭据，不要串用。 同一个使用者在多家企业之间切换时，统一入口会检测到

地址/账号/公司代码变化并自动覆盖本地记录；对话里仍应先确认是哪一家，不要拿 A 企业的记录去猜 B 企业缺的项。

1. 会话只有几分钟。 登录与取数必须在同一次脚本执行内完成，不要「先登录存 Cookie，过一会儿再取数」。
2. 只读。 不碰任何写接口。取数结果落本地文件后，后续分析与出报表都读本地文件，不要为了同一份数据反复登录取数（会话短，且浪费）。

标准工作流

第 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 路径给使用者。

销售明细（2931）与畅销分析

与库存模式的差别（先看清边界）

销售分析模式是内部经营分析用途，字段范围天然更宽（含客户、业务员、金额）。

若交付对象是外部经销商，仍应回到库存模式的两列契约。

取数（脚本自动识别协议）

--proto auto（默认）会在给了 --beginday/--endday 或功能号在 FUNC_DEFAULT_FIELDS（当前含 2931）时自动切到 deltaXml 协议，其余走 runProject。也可用 --proto deltaxml 强制。

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

# 近 3 年销售明细（日期必填；缺省时自动取「本年年初 ~ 今天」）
python scripts/erp_stock_query.py --func 2931 
  --beginday 2023-10-01 --endday 2026-10-28 --outdir ./erp_stock_out

# 指定客户 + 品牌（头部条件，走服务端）
python scripts/erp_stock_query.py --func 2931 --beginday 2026-01-01 --endday 2026-10-28 
  --filter "客户名称=<客户>" --filter "品牌=<品牌>" --outdir ./erp_stock_out

# 销量/金额区间（区间条件不进头部，拉回后本地精确筛选）
python scripts/erp_stock_query.py --func 2931 --beginday 2026-01-01 --endday 2026-10-28 
  --filter "销售额>10000" --outdir ./erp_stock_out

产出 <outdir>/result_2931.json：meta 里记录 proto=deltaxml、modelid、beginday/endday、headfilter（实际下发的头部条件）；rows 为多维销售行（默认 25 列，可用 --fields 调整）。

生成畅销分析报表

python scripts/erp_sales_report.py --input ./erp_stock_out/result_2931.json 
  --out ./kb/2931销售明细分析报表.xlsx --title "销售明细分析（近3年）"

--input 可传多个文件（如按年/按月分批取的结果），脚本自动合并并按 rowid 去重。

产出 9 个 Sheet：

口径（务必统一）

• 销量 = basedigit（基本单位）；平方 = pfcount；销售额 = nattotalmoney（本币）。
• 平均单价 = 销售额 / 销量；销售额占比 = 组内销售额 / 总销售额。
• 订单数按 doccode 去重；客户数按 cltname 去重；SKU 数按 matcode 去重。
• 2931 的字段命名与 1800 相反：matcode=产品编码、matname=产品名称、xilie=系列。

大数据量分片

单年数据过大时 getAlldata 可能 300 秒超时（响应体过大）。处理办法：按年/半年/季度分批取（多个 --beginday/--endday），分别落盘后用 erp_sales_report.py --input a.json b.json ... 合并。一次性拉全历史（跨 5 年以上）通常会超时，不要这么做。

销售明细（2931）可用条件

文本类（映射到模型头部字段，服务端包含匹配）：

数值区间类（本地筛选）：销量/数量→basedigit、数量(业务单位)→digit、平方数→pfcount、销售额/金额→nattotalmoney、单价→price。

头部固定项由功能配置的 defvalue 自动预填：dealflag_h=全部（冲销选项）、

saletype_h=销售、includefsub=否、formid_h=2931。

仓库业务汇总（1803）与仓库周转分析

这个功能和另外两个的区别

关键差异（实测踩过，务必按这个来）：

• 头部字段没有 _h 后缀：是 beginday / endday / stcodeh / companyidh / doctypeh，

不是 2931 那种 beginday_h。写错了服务端不报错，直接安静返回 0 行。

• companyidh 与 stcodeh 都是必填：任一为空 → 0 行（不是全量）。
• stcodeh 支持逗号分隔多仓（"QN06,QN09"）：一个公司一次就能把全部仓库拉完。
• 登录账套的公司代码（如 1001）不等于业务公司代码；仓库归属公司要从 1800 快照读

（脚本已自动做：discover_stock_dims() → <outdir>/stock_dims.json）。

• 销售出库行的 outamount/map/matcost 为空，只有非销售类单据带成本，所以金额口径

不可靠；数量口径请用 平方（㎡），基本单位混了片/箱/个。

取数

# 方式一：统一入口，取数 + 出周转分析报表（推荐）
python scripts/erp_query_all.py turnover 
  --turnover-begin 2024-01-01 --turnover-end 2024-03-31

# 限定仓库/公司（例如只看成品仓）
python scripts/erp_query_all.py turnover --stcode T01,QN06 --company-list 1003,1006 
  --turnover-begin 2024-01-01 --turnover-end 2024-03-31

# 方式二：只取 1803 流水，自己再分析
python scripts/erp_stock_query.py --func 1803 
  --beginday 2024-01-01 --endday 2024-03-31 --outdir ./erp_stock_out

产出 <outdir>/result_1803.json（默认 24 列：凭证/仓库/产品/业务类型/数量三口径/金额/加权价）

• <outdir>/1803_raw/{公司}_{年-月}.json（按月缓存，可断点续跑）。

周转分析报表（erp_turnover.py）

python scripts/erp_turnover.py --flow ./erp_stock_out/result_1803.json 
  --stock ./erp_stock_out/result_1800.json 
  --out ./kb/仓库周转分析报表.xlsx --title "仓库周转分析"

--stock 必须传带「仓库 + 平方」字段的库存快照，默认两列白名单的 result_1800.json

会被裁成两列、算不出期末库存（脚本会提示「缺库存快照」）。正确做法：

BASH复制

python scripts/erp_stock_query.py --func 1800 

  --fields stcode,stname,matname,unlimitstockpf,freestockpf 

  --outfile ./erp_stock_out/stock_1800_full.json

走统一入口 turnover 模式时脚本会自动取这份完整快照（stock_1800_full.json），无需手工处理。

6 个 Sheet：

读数要点（汇报时必须讲，否则容易被数字误导）：

• 「出库」含内部流转：打包出库、快速移仓、转色、拆样板、转级等都算进出库。
• 成品仓看销售口径（如 T01、QN06、QN18）：销售出库占比 90%+，「销售口径可支撑天数」

才代表真实动销。

• 半成品仓只看全口径（如 T08、QN09）：几乎不走销售出库，其「打包出库」就是转成品的

正常流转；脚本对这种仓自动不给销售口径数字（占比 <5% 时置空）。

• 破损率 正常应 <1%；调货占比 高的仓（如某仓 96%）说明它主要在做中转，不是终端仓。

公式（报表首页也写，汇报时要一起讲）：

• 期末库存 = 1800 快照；期初库存 = 期末 −（期间入库 − 期间出库），为倒推值
• 平均库存 =（期初 + 期末）/ 2
• 周转次数 = 期间出库 ÷ 平均库存；周转天数 = 统计天数 ÷ 周转次数
• 可支撑天数 = 期末库存 ÷ 日均出库（不依赖倒推，最稳健，优先看这个）
• 库销比 = 期末库存 ÷ 期间出库；破损率 = 破损出库㎡ ÷ 总出库㎡

⚠ 口径陷阱（必须向使用者说明）：期初是靠「当前库存快照 + 期间净变动」倒推的。

若快照时点与统计期间末日相差超过 31 天（测试账套常见：流水停在 2025-06、库存快照是

2026-11），周转率/可支撑天数会严重失真，报表会在状态列打 ⚠口径 并给出提示。

这种情况只信「期间流量（入库/出库/净变动）」与「业务类型结构」两张表。

1803 可用条件

数量/金额字段：indigit/outdigit（基本单位，混合单位仅参考）、indigitpf/outdigitpf（平方，周转计算用这个）、inamount/outamount（记账金额，销售出库为空）、map（加权平均价）、matcost（仓库记账金额）。

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

过滤条件速查

--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 参数、getAlldata.action + deltaXml（销售明细 2931 / 仓库业务汇总 1803）、

formid 命名规则、配置接口、响应结构、字段命名规律，以及 --login-path / --erp-base 的用法。

• references/field-conventions.md —— 字段命名规律、单位三套口径、常见列名词表，以及「如何用 --describe 从自己的 ERP 动态取字段字典」。

上架元数据说明

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

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

依赖

Python 3 + requests + openpyxl。