智能体物料导入 - 前端联调方案
涉及页面
- 物料管理 - 物料列表（入口与结果确认）
- 物料管理 - 智能体导入（上传、审核、提交、回执）
业务定位
智能体导入是独立于 Excel 批量导入的新入口：用户上传物料清单，智能体解析并调用 Java 主数据预检，用户核对后提交。**本阶段只新建物料**；编码已存在时跳过，不更新原物料，不触发 MES 同步。
业务流程与数据带入
- 进入导入页 → 前端创建补录会话，拿到
sessionId。
- 选择 Excel/CSV → 走既有文件上传，拿到
blobId。
- 将
blobId 绑定到会话 → 拿到 attachmentId。附件归属、大小与格式由后端校验。
- 用
attachmentId 创建智能体任务 → 返回任务 ID、候选行、Java 预检结果（分类、单位、编码状态）与人审中断信息。
- 用户在审核页修订字段并重新检查 → 每次修订后
revision 加 1，并重新预检。
- 用户确认 → 提交；成功后展示逐行回执。
- 结果页可再次查询回执；任务 ID 可回查任务状态。
关键带入关系：
| 来源 |
带入目标 |
字段 |
| 文件上传 |
会话绑定 |
blobId |
| 会话绑定 |
创建任务 |
attachmentId（不是 blobId） |
| 创建任务响应 |
审核页 |
task_id、state.revision、state.preflight、interrupts |
| 预检结果 |
确认请求 |
state.preflight_hash |
| 审核修订 |
下一次预检 |
修订后的字段值，revision 自增 |
| 提交响应 |
回执页 |
receipt.rows[].targetItemId、status |
API
Java 管理端（/admin-api，携带用户 Bearer token）
| 方法 |
路径 |
说明 |
| POST |
/agent/bridge/import-sessions |
创建补录会话，返回 sessionId |
| POST |
/agent/bridge/import-sessions/{sessionId}/attachments |
绑定附件，返回 attachmentId |
绑定请求参数：
| 参数 |
类型 |
必填 |
说明 |
blobId |
Long |
是 |
既有上传接口返回的 blob ID |
限制：
- 同一会话重复绑定会替换旧附件，旧
attachmentId 随后不可用。
- 文件上限 8 MiB，仅允许 CSV/XLSX。
- 用户需具备
mdm:item:import 权限，否则返回 403 FORBIDDEN。
Python 智能体服务（默认 http://127.0.0.1:8091，携带同一用户 Bearer token）
Python 服务不在 /admin-api 下，需由网关或前端代理转发；服务口令 X-Agent-Service-Token 由 Python 服务内部使用，**前端不得携带或下发**。
| 方法 |
路径 |
说明 |
| POST |
/v1/material-imports |
创建任务并触发预检，返回任务与审核中断 |
| GET |
/v1/material-imports/{task_id} |
读取任务当前状态 |
| POST |
/v1/material-imports/{task_id}/review |
修订或确认 |
| GET |
/v1/material-imports/{task_id}/receipt |
查询提交回执 |
创建任务请求参数：
| 参数 |
类型 |
必填 |
说明 |
attachment_id |
String |
是 |
Java 返回的附件 ID |
filename |
String |
否 |
兼容字段，解析以 Java 返回的文件名为准 |
创建任务响应：
| 字段 |
类型 |
说明 |
task_id |
String |
任务 ID，后续读取/审核/回执均使用 |
state.revision |
Integer |
方案版本，确认时必须回传当前值 |
state.candidates |
Array |
解析后的候选行及单元格来源 |
state.issues |
Array |
字段缺失、重复编码等本地校验问题 |
state.preflight |
Object |
Java 预检结果：can_commit、summary、rows[] 等 |
state.preflight_hash |
String |
预检计划摘要 |
interrupts |
Array |
人审中断信息，type=material_review |
审核请求参数：
| 参数 |
类型 |
必填 |
说明 |
expected_revision |
Integer |
是 |
当前 state.revision |
action |
String |
是 |
revise / confirm / cancel |
corrections |
Array |
修订时必填 |
每项含 candidate_id、field、value、reason |
expected_preflight_hash |
String |
确认时建议填写 |
当前 state.preflight_hash |
expected_proposal_hash |
String |
否 |
二次确认时校验方案未变化 |
回执响应关键字段：
| 字段 |
说明 |
status |
SUCCEEDED / PARTIAL_FAILED / FAILED / UNKNOWN |
summary |
total/success/failed/skipped/unknown |
rows[].action |
CREATE / SKIP |
rows[].status |
SUCCESS / SKIPPED / FAILED / UNKNOWN |
rows[].targetItemId |
新建物料 ID；SKIP 行为已有物料 ID |
rows[].errorCode / errorMessage |
行级失败原因 |
rows[].retryable |
是否建议重试 |
字段展示规则
| 字段 |
展示位置 |
说明 |
| 物料编码 |
审核列表、回执 |
文件内重复时整批阻断 |
| 物料名称 |
审核列表、回执 |
为空时阻断该行 |
| 规格型号 |
审核列表 |
可选 |
| 分类编码 |
审核列表 |
预检解析为 resolved.categoryName 后优先显示名称 |
| 计量单位编码 |
审核列表 |
预检解析为 resolved.unitMeasureName 后优先显示名称 |
| 行动作 |
审核列表 |
CREATE 新建、SKIP 已存在将跳过、BLOCKED 阻断 |
| 阻断/警告 |
审核列表行内 |
展示 blockers[]、warnings[] 的 message，并高亮该行 |
| 预检汇总 |
审核页顶部 |
总数、新建、跳过、阻断 |
| 是否可提交 |
审核页底部 |
由 preflight.can_commit 与 state.issues 共同决定 |
| 目标物料 ID |
回执页 |
rows[].targetItemId，可跳转物料详情 |
| 回执汇总 |
回执页顶部 |
成功、跳过、失败、未知数量 |
业务规则说明
| 场景 |
规则 |
| 编码已存在 |
预检 SKIP，不阻断整批；提交时跳过，不更新原物料 |
| 分类/单位不存在 |
该行 BLOCKED，整批不可提交；提示用户修正编码 |
| 文件内编码重复 |
所有重复行均 BLOCKED |
| 请求同步 MES |
返回阻断项 MES_SYNC_DISABLED；本阶段不支持 |
| 超过 5000 行 |
整批阻断 ROW_LIMIT_EXCEEDED |
| 方案被修订 |
revision 自增，必须用新版本重新确认 |
| 确认后数据变化 |
提交时重新预检；计划变化返回 409 PLAN_STALE，需重新读取并确认 |
| 重复点击提交 |
服务端幂等，返回原回执，不重复建物料 |
| 提交超时 |
前端应查询回执，不要重新发起确认 |
| 写开关关闭 |
Python 返回 409 COMMIT_DISABLED；Java 返回 503 WRITE_DISABLED |
注意事项
- 前端只携带用户登录 token；服务口令、附件下载接口仅限 Python 服务内网访问。
attachmentId 不是 blobId，绑定接口返回的才是任务入参。- 确认前必须重新读取任务，使用最新的
revision 与 preflight_hash；禁止缓存旧值直接确认。
- 409
PLAN_STALE 与 409 COMMIT_DISABLED 语义不同：前者需重新预检，后者需联系管理员打开写开关。
SKIP 行也会出现在回执中，展示为“已存在，已跳过”，不是失败。- 任务按租户 + 用户隔离，换账号或跨租户访问返回 404。
- 本阶段不提供进度推送；提交为同步请求，前端需设置足够长的超时（建议 120 秒），超时后查询回执。
- 不支持更新已有物料；如业务需要修改物料，仍走既有物料编辑流程。
