Excel 批量导入
把客户手里格式不规范的 Excel(物料表、产品表、BOM、工单、库存)导进轻排:读懂表头、按导入契约转换列名、先预览再落库。 用户说“把这个 Excel 导进轻排”“这批物料怎么批量导进去”“我的表头对不上系统字段”“初始化一下基础资料”“BOM 表能不能直接导入”“库存盘点表导进去”时使用;用户拿着一张表说‘这个怎么进系统’也属于本技能。 不触发:排产、交期评审、缺料检查、插单测算、报工(用 pmclite-scheduler);只解释已有排程(用 pmclite-schedule-explainer)。本技能只做基础资料与初始单据的导入,不改排程、不调整工单优先级。
Excel 批量导入(pmclite-excel-import)
客户的表是给人看的,系统的契约是给机器看的,这两个对不上才是导入失败的真正原因。本技能的职责是做翻译:把客户的列名、合并单元格、多余列,转成契约要求的字段名与类型,再让客户在预览里自己做最后确认。
主技能 pmclite-scheduler 明确把“基础资料录入”划在范围外,所以用户提这类需求时不要推回桌面端,那正是本技能要接的活。
前置:先确认连得上
调 get_import_schema(只读,不带参数)。成功说明 MCP 通、契约可取。失败按 references/install.md 走未安装引导,不要凭空猜字段名。
强制四步,顺序不能变
- 取契约:
get_import_schema看当前版本认可的表与字段。字段名必须逐字一致,中文列名不会自动映射——这一步就是拿到唯一权威。 - 翻译数据:按契约把用户的表转成 JSON。表头怎么对、多余列怎么处理、合并单元格怎么取值,见
references/header-mapping.md。字段与必填项见references/schema.md。 - 预览:
import_data(mode="preview", data=...)。拿到「新增 N / 更新 M / 错误 K」和字段级差异。- 把统计复述给用户,AUTO 编码逐条说明(哪些编码是系统生成的,生成规则是
AUTO-MAT-xxxxx/AUTO-PRD-xxxxx); - warning 要转述,特别是“有 N 条未提供单位,已默认为个”,让客户知道以后可以改;
- 有错误 K 时,整批不会写入,把每条错误的行号和原因列给用户,请他们改表或确认改法。
- 把统计复述给用户,AUTO 编码逐条说明(哪些编码是系统生成的,生成规则是
- 落库:用户明确确认后才
import_data(mode="apply", idempotency_key=<UUID>, data=...)。同一批数据重试必须复用同一个 key,否则会重复写。
跳过预览直接 apply 是违规调用,工具层也会拒绝。
表与处理顺序
五张表:materials → products → bomItems → workOrders → inventory。
顺序有意义:后面的表可以引用前面刚生成的编码(比如 BOM 行引用本批 AUTO 出来的物料编码),反过来就会因“引用不存在”整批被拒。工具是按这个顺序内部处理的,但你在组装数据时要保证被引用的对象在同一批里出现过。
翻译时的三条判断
- 缺单位不拦:
materials.unit缺失时工具会默认「个」并回执 warning。不要为了问单位把整个导入停下来,客户表格里本来就没有这列。 - 缺编码不拦:
code可以不填,系统按name+spec匹配现有物料,匹配不到就生成 AUTO 编码。所以客户表里没有编码列也能导。 - 多余列直接丢:序号、备注、制表人、审批签字这些列对导入没有意义,不要硬塞进字段,也不要因为“这列处理不了”就整表报错。
有错误时怎么办
有错误行时整批不写入(事务),这是设计而非故障。处理顺序是:定位行 → 说明原因 → 给两个选项(改表重导 / 你按规则修正后重导)。
不要为了让数据符合契约而删掉客户的行,也不要擅自把“1,200.00”改成“1200”就当作没问题——数字里的千分位、全角字符、单位混写都要先跟用户确认口径,再统一转换。
常见问题与救援
| 现象 | 原因 | 处理 |
|---|---|---|
productCode 不存在 | BOM 或工单引用的产品不在本批也不在系统里 | 先导产品表,或把产品信息补进同一批的 products |
| 优先级报错 | 契约只认「高/中/低」 | 把 P0、加急、Urgent 这类写法统一转成三档,并告诉用户你按什么规则转的 |
| 日期不认 | 契约要 YYYY-MM-DD | 把 2026/11/20、11月20日 统一成标准格式再导 |
| 数字变成 1 | 千分位或全角数字被直接解析 | 先清洗成纯数字,必要时向用户复述“你说的 1,200 是 1200 吗” |
| 表头根本认不出 | 首行就是数据,或表头在第三行 | 让用户确认哪一行是表头;参考 references/header-mapping.md 的“无表头”一节 |
不知道能不能读文件时
读取用户表格属于通用能力,不属于轻排 MCP 的范围。如果你当前环境读不了 xlsx,不要因此中断任务:请用户把表头行和前 5 行数据贴出来,或者导出成 CSV 再处理。宁可多问一句,也不要照着猜测的列名硬导。
未安装时怎么演示
用户还没装 MRP-PMC 时,get_import_schema 会失败。这时不要讲一堆配置步骤,先用 assets/demo.json 里的三条物料说明“导进去之后是什么样”,再给官网下载入口和一句配置命令(见 references/install.md)。演示数据只是说明形态,不要声称已经写入了用户系统。
- Downloads
- Security audit
- Pass
- Last updated
- 3d ago
- Current version
- v1.0.0
- License
- MIT-0
