Industry
/
aps-agent
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
aps-agent/APS系统操作手册.md

377 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 工业智核 APS 计划排产智能体 · 操作手册
> 版本：2026-09-01（对齐当前代码能力，含 round-65~67、DXF-01、FF-01 功能开关）
> 适用对象：计划员、实施顾问、演示/验收人员
> 相关文档：`docs/product/features.md`（功能清单）、`docs/product/journeys.md`（业务旅程）、`锐扬演示-操作手册.md`（锐扬演示剧本）、`docs/product/flex-simulation-guide.md`（柔性排产专项手册）
---
## 1. 系统是什么
左手**自然语言对话**、右手**可视化排产工作台**的计划排产智能体。核心链路：
```
销售订单 → MRP 分解（自制 / 采购 / 委外）→ 多策略试排（规则/CP/GA/NSGA-II）
→ 方案对比 → P2 确认发布 → MES 下发 → 报工回流
```
两大排产轨道：
| 轨道 | 模型 | 适用场景 |
| --- | --- | --- |
| **固定轨** | 产线选线 + 工位占槽（RuleEngine / CP / GA / HYBRID） | 产线固定的常规离散制造 |
| **柔性轨** | 能力池 + 虚拟产线（PoolEngine） | 多品种小批量、设备可移动（如康尼芜湖线束/PDU 共线） |
安全原则：一切写操作走**门禁确认卡**（P2 单确认 / P3 二次确认），执行前自动建检查点，全程审计链记账。试排只产出 DRAFT，不会自动发布；回滚前自动再存一次档。
---
## 2. 两种形态
| 形态 | 数据位置 | 启动命令 | 账号 |
| --- | --- | --- | --- |
| **Web** | 仓库 `server/data/`（或 `APS_HOME`） | `npm run dev:web` → 浏览器 http://localhost:5173 （API :8000） | JMS 企业账号登录（`.env` 配置，见 §3.2） |
| **桌面** | `C:\Users\<用户>\.aps`（与开发环境互不影响） | `npm run dev:desktop`（开发）/ 安装 `apps/desktop/release/aps-agent-desktop-0.1.0.exe` | 免账号，用授权码（见 §4） |
---
## 3. 安装与启动
### 3.1 依赖安装（一次性）
```powershell
cd <aps-agent-repo>
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env # 可选，按需修改
npm run bootstrap # 安装 apps/web + apps/desktop 依赖
```
### 3.2 Web 端登录配置（`.env`）
```ini
APS_AUTH_PROVIDER=jms
JMS_AUTH_BASE_URL=https://<your-jms-host>
JMS_AUTH_SESSION_SECRET=至少32个随机字符
APS_LICENSE_PROVIDER=mock
# 可选：限制单一企业
# JMS_AUTH_TENANT_CODE=xxx
# JMS_AUTH_TENANT_NAME=xxx
```
> JMS 没有自助注册/找回密码，账号创建与密码重置由企业管理员处理。
### 3.3 启动
```powershell
npm run dev:web # Web：前后端一起起
npm run dev:desktop # 桌面：Electron 窗口
```
只起后端 API：`npm run dev:server`（http://localhost:8000，OpenAPI 文档 /docs）。
### 3.4 打包
```powershell
npm run build:web # 静态前端 → apps/web/dist
npm run build:desktop # Electron 安装包 → apps/desktop/release
```
---
## 4. 登录与授权
- **Web**：打开页面 → 选择所属企业（从 JMS 读取启用企业列表）→ 输入真实账号密码登录。
- **桌面**：输入授权码，开发用演示码：
`APS-HOUR-DEMO`、`APS-DAY-DEMO`、`APS-WEEK-DEMO`、`APS-MONTH-DEMO`、`APS-YEAR-DEMO`、`APS-PERP-DEMO`。
---
## 5. 界面导览
```
┌──────────────────────────────────────────────────────┐
│ 顶部菜单栏（按功能开关过滤） │
├──────────┬─────────────────────────┬─────────────────┤
│ 左侧栏 │ 中部：对话区 / 工作台 │ 右侧工具导轨 │
│ · 项目/任务│ 左说右动：说一句话， │ · 多智能体编排 │
│ · 快捷入口 │ 右侧视图立即刷新 │ · DXF 图纸 │
│ · 订单 │ │ · 柔性工作台 │
│ · 主数据 │ │ · 知识库/治理台等 │
└──────────┴─────────────────────────┴─────────────────┘
```
- **Ctrl+K** 命令面板：快速跳转任意面板/视图（条目随功能开关过滤）。
- 对话块里会插入**方案卡、确认卡、知识引用、报告**等富块，可直接点按交互。
- 右侧视口：甘特（固定/柔性）/ 负荷 / 交期 / 分桶计划 / 利用率 / 对比表 / KPI 仪表盘 / 产能池 / 时间线。
---
## 6. 第一步：准备数据
### 6.1 工程目录导入（推荐）
左侧「新建任务 / 新建项目」→ 选择工程目录（目录内放 Excel/CSV：订单、物料、BOM、工艺、设备、班历等），然后在对话框输入：
```
分析一下数据文件
```
系统做项目深度分析（订单/物料/工艺/设备/BOM 计数 + 诊断），并自动导入世界。诊断口径：有效 / blocking（阻断）/ 跳过，blocking 会定位到具体文件具体行。
### 6.2 Excel/CSV 导入管线
主数据面板或订单面板的「导入」按钮 → `preview` 预览（表头映射 + 校验）→ P2 确认落库。支持：订单 / 物料 / BOM / 工艺路线 / 设备 / 模具 / 工序 / 区域。
### 6.3 DXF 工程图纸识别
右侧导轨「图纸」图标 → 上传 DXF / 填本地路径 / 扫描工程目录：
1. 自动解析标题栏（图号、名称、比例、版本，带字段级置信度徽标）；
2. SVG 预览（滚轮缩放、拖拽平移、图层开关）；
3. 物料候选表单人工核对 → 生成 P2 确认卡 → 批准后写入主数据。
> 图纸未承载的字段（材质、工时、外协、BOM 子件数量等）一律显式标 missing，绝不编造，必须人工确认。
### 6.4 康尼真实单（柔性演示）
```powershell
.venv\Scripts\python.exe scripts\load_kangni.py
```
或对话口令「导入完整生产路线」，替换演示 flex* 数据后再跑柔性排产。
### 6.5 主数据录入顺序（铁律）
**先工厂/产线 → 再物料 → 再 BOM → 再工序 → 再工艺路线 → 再产线-产品绑定 → 再订单**。缺一环，后续排产必然失败或"找不到依据"。
---
## 7. 主数据维护（侧栏「主数据」）
页签与能力：
| 页签 | 能做什么 | 权级 |
| --- | --- | --- |
| 资源 | 工厂→车间→产线→工位→设备树；产线编辑/停启用（停用不进新排产） | 编辑 P2 |
| 物料与 BOM | 库存/在途/安全库存/前置期编辑；BOM 明细用量、关键料编辑 | P2 |
| 日历与维保 | 班次/日历只读；维保窗口新增/取消（联动设备避让） | P2 |
| 工艺 | 工艺步骤工时 / 外协标记编辑 | P2 |
| 换型 | 产品族×产品族换型矩阵维护（口令「查看换型矩阵」） | P2 |
| 柔性资源 | 设备虚拟档案（能力集合、可移动/移动耗时、当前位置、工装适配）、能力池摘要 | 只读 + Excel 导入 |
注意：所有主数据修改**只影响之后的新排产版本**，历史版本不回写；执行前自动建检查点、写审计链。
---
## 8. 订单管理（左侧栏「订单」）
### 8.1 销售订单
- 列表 + 明细：新增 / 编辑 / 取消 / 完成，全部走 P2 确认卡。
- `CANCELLED` / `COMPLETED` 订单不进新排产版本。
- 状态机：仅 `APPROVED` 订单进排产。
### 8.2 订单池与审核
泳道看板：提交 / 批准 / 驳回 / 批量批准。口令：「订单池」「提交审核」「批量批准」。
### 8.3 预测订单
预测台账默认**不进**正式排产；可「预测纳入试排」做 what-if，确认后「预测转正」为正式 APPROVED 销售单。口令：「查看预测」「新建预测」「预测纳入试排」「预测转正」。
### 8.4 紧急插单
订单面板「插单」向导，或口令「插单快评」→ 查看影响评估 →「采用插单」（固定轨走 rush.evaluate/apply，柔性轨走 flex.rush；超扰动阈值自动升级为全量重排并出 P2 确认）。
### 8.5 订单追溯
任一订单可一键追溯完整链条：订单本体 → 主数据依据（BOM/工艺/库存）→ MRP 分解结果 → 排产版本与工单 → 缺失项（无 BOM / 无路线 / 未绑产线 / 库存不足）。柔性轨另走 FO→BOM→虚拟产线→工单→设备负荷，界面标明当前走哪条链。
---
## 9. MRP 订单分解
入口：订单面板「分解建议」/「分解此单」，或口令「分解订单 SO-001」「执行MRP分解」「生成采购建议」。
| 分支 | 依据 | 产出 |
| --- | --- | --- |
| 自制 | 订单明细成品 + 工艺路线 | 自制建议（交排产生成 PO/WO） |
| 采购 | BOM 净需求 = 毛需求 − 库存 − 在途 − 已下达供应 | 采购建议 DRAFT（数量 + 建议下单日按前置期倒排） |
| 委外 | 工艺步骤 `isExternal` 标记 | 委外建议 DRAFT |
- 分解是 **P1**：只写建议草稿，幂等替换，可重复执行。
- 下达：口令「下达MRP建议单」→ **P2** 确认卡 → 批准 → DRAFT 转 RELEASED（自动补预计到料日，供齐套检查使用）。
- 多层 BOM 完整展开：半成品缺工艺不会伪装成采购，缺工艺的条目会明示。
---
## 10. 排产
### 10.1 固定轨试排
口令示例：「试排一版交期优先」「按产能均衡排一下」「换型最小化试排」「战役合并试排」。
- 策略模板：`DELIVERY_FIRST`（交期优先）/ `FIFO` / `CAPACITY_BALANCE` / `CHANGEOVER_MIN`（换型最小化）/ `COST_FIRST` / `COMPREHENSIVE` / `CAMPAIGN`（批次合并）。
- 引擎：RULE / CP-SAT（工序级+Cumulative）/ GA / NSGA-II（三目标 Pareto）/ HYBRID。
- 滚动窗口：realtime60m / short2h / mid2d / long7d 多级时域。
- 产出 **DRAFT** 版本 + 冲突清单，右侧甘特/负荷/交期视图即时刷新。
### 10.2 柔性轨排产（能力池 + 虚拟产线）
口令「跑一版柔性排产」，或右侧「柔性工作台」点选；接口 `POST /api/flex/schedule`：
| 参数 | 取值 | 含义 |
| --- | --- | --- |
| `sortMode` | `ASC` / `DESC` / `BOTTLENECK` | 正排 / 倒排 / 瓶颈锚（默认） |
| `orderIds` | 订单 id 数组 | 只排指定订单 |
系统按订单工艺路线逐工序从能力池动态取设备，拼出虚拟产线（含模具换型与设备移动耗时），用完即散。柔性甘特可切「虚拟线预演」，支持正排/倒排/瓶颈锚**三模式对比**。
### 10.3 方案对比与采用
口令「对比几种策略」→ 沙盒并行多策略试排 → 返回方案卡（KPI / 差异 / Pareto + 偏好推荐）→ 点「采用此方案」落到主干草稿。**对比 ≠ 发布，主干世界在采用前不变。**
### 10.4 发布 / 重置 / 回滚
| 动作 | 口令 | 权级 | 说明 |
| --- | --- | --- | --- |
| 发布 | 「发布这个版本」 | P2 | DRAFT → PUBLISHED，执行前自动建档；只有完整 DRAFT 才能发布，证据一致的已发布版本才能进 MES |
| 存档 | 「存个档」 | P1 | 对话上下文 + 世界状态成对快照 |
| 回滚 | 点时间线检查点 / 「回滚」 | P2 | 回滚前自动再存一次档（安全网） |
| 重置 | 「清空数据重新初始化」 | P2 | 重播演示种子（电子装配演示工厂） |
### 10.5 工单拖拽调程
固定/柔性甘特均可直接拖动工单：15 分钟吸附、边拖边校验、松手生成 P2 确认卡，批准后形成新版本。
### 10.6 冲突处理
冲突中心按类型给出修复建议：安全修复 P1 一键应用；涉及重排的出 P2 确认卡。硬阻断（如缺料、无可用设备）会显示聚合计数、具体对象、证据和修复入口，**不会**显示绿色"排产完成"。
---
## 11. 计划层（Advanced Planning）
| 能力 | 口令 | 说明 |
| --- | --- | --- |
| 时间分桶计划 | 「时间分桶」「混合分桶」 | 近 7 日 / 中 4 周 / 远月混合时段 |
| 粗能力评估 | 「有限产能粗评」「无限产能粗评」「粗能力对比」 | FINITE / INFINITE 双模式对照 |
| 可行性分析 | 「可行性分析」「能否按期」 | 累计粗能力 vs 交期需求，定位缺口桶与订单 slack |
| 库存投影 | 「库存投影」「库存投影 CTRL-A」 | 期初+在途+毛需求+到货的日/周库存曲线，断料/安全库存告警 |
| 产能平衡 | 「削峰」「产能平衡」 | 超载桶→空档挪动建议，前后负荷对照 |
| 产供决策 | 「产供决策」「加班建议」 | 残留缺口→加班→扩线→外协结构化建议 |
| 交期承诺 | 对话询价 / 柔性工作台询价 | 询单插入 → 乐观/预计/悲观三区间 + 资源缺口提示 |
| 瓶颈产能 | 视口「产能池」 | 日产能=瓶颈工序可用工时÷单件工时；设备停机/调区即时重算，含 4h/1d/1w 预测与 85/95 预警 |
---
## 12. 动态调度（异常分级重排）
| 级别 | 触发 | 行为 |
| --- | --- | --- |
| L1 | 设备故障（优先） | 池内备机换机，最小扰动 |
| L2 | 短窗变化 | 窗内重排，P2 确认 |
| L3 | 日级变化 | 日窗重排，P2 确认 |
| L4 | 重大异常 | 全局重排，P2 确认 |
典型演示：可移动压接机坏一台 → 池有冗余、交期几乎不受影响；单一瓶颈设备（如激光焊接）故障 → 立即报「无可用设备」，提示备机/外包/重议交期。WMS 缺料事件 → 重排 → 确认 → MES 下发 → 回执全链路闭环。
---
## 13. 结果视图与报表
| 视口 | 内容 |
| --- | --- |
| 甘特 | 固定/柔性双轨，工单拖拽、冲突高亮 |
| 负荷 / 利用率 | 产线/设备负荷、柔性设备 7 日热力、班组并发触顶 |
| 交期看板 | 订单准时/延误一览 |
| 对比表 | 固定策略 + 柔性三模式 KPI 矩阵，最优格高亮与 delta |
| KPI 仪表盘 | 利用率/准时率/在制/延误汇总（口令「打开仪表盘」） |
| 产能池 | 池负载率、瓶颈色标、短中长期预测、设备调配 What-if |
| 时间线 | 检查点列表，点击回滚 |
报表：口令「生成日报」「版本对比」→ 数字来自冻结快照模板，不经 LLM 改写。审计支持哈希链校验、Merkle 树、断链检测与归档导出。
---
## 14. MES 下发与报工回流
1. 已发布版本 → 「MES 执行」（柔性工作台）或下发口令 → **P3** 二次确认 → Mock MES 幂等下发。
2. 报工回流：`mes.report`（P1）回报进度/完工 → 订单整单完工状态联动推进。
3. 订单页阶段状态来自持久化的闭环问题与 MES 事实，刷新后不退回静态"待确认"。
---
## 15. 多智能体编排（右侧栏「多智能体编排」）
1. **创建智能体**：输入名字、选角色（数据解析 / MRP 分解 / 柔性排产 / 报告…）。
2. **挂 Goal**：填标题 → 选模板（如「解析→分解→下达→排产→报告」5 任务）→ 看门狗开始监控。
3. **分发执行**：看门狗按能力边界分发给空闲智能体，没有合适的就**自动新建**。
4. **消息总线**：实时显示任务接力；也可手动给任意智能体发消息，对方回报自身状态与能力边界。
5. **看门狗**：RUNNING 超期（默认 45s，可一键调 10s 演示）→ 收回重排 → 重试耗尽升级 ATTENTION；全部完成自动结案 ACHIEVED。任务失败诚实落 FAILED 并升级，不会假装成功。
6. 重复演示前先点一次「恢复」（或 `POST /api/mesh/reset`）。
---
## 16. 对话口令速查
| 类别 | 口令 |
| --- | --- |
| 数据 | 分析一下数据文件 / 导入完整生产路线 / 清空数据重新初始化 |
| MRP | 执行MRP分解 / 分解订单 SO-001 / 生成采购建议 / 下达MRP建议单 |
| 排产 | 试排一版交期优先 / 按产能均衡排一下 / 换型最小化试排 / 战役合并试排 / 跑一版柔性排产 / 三模式对比 |
| 方案 | 对比几种策略 / 采用此方案 / 发布这个版本 |
| 插单 | 插单快评 / 采用插单 |
| 计划层 | 时间分桶 / 可行性分析 / 能否按期 / 库存投影 / 削峰 / 产供决策 / 加班建议 |
| 订单 | 订单池 / 提交审核 / 批量批准 / 查看预测 / 新建预测 / 预测纳入试排 / 预测转正 |
| 主数据 | 查看换型矩阵 / 提高VIP权重到10 |
| 知识 | 换线有什么规定 / @知识:标题 |
| 报告 | 生成日报 / 版本对比 / 打开仪表盘 |
| 存档 | 存个档 / 回滚 |
> 意图管线为「正则快路 → LLM JSON」两级；LLM 超时或非法输出自动降级正则，知识未命中会诚实说没有，不编造 SOP。
---
## 17. 治理与安全（设置 → 治理台）
- **门禁分级**：P0 只读 / P1 写草稿直通 / P2 单确认卡 / P3 外部副作用二次确认（当前用于 MES 下发）；审批角色可按动作分级。
- **审计链**：每次执行记账，哈希链可校验，支持断链检测（治理台 ⚠ 徽标）、归档加密与导出。
- **约束配置中心**：13 类约束目录，可配启停与硬/软；硬约束拦截发布。
- **行业规则包**：SOP → 排产约束编译，预览后 P2 应用。
- **唯一执行通道**：所有写操作最终都走 `/api/actions/confirm`，不存在绕过确认卡的"直接执行"接口。
### 功能开关（FF-01）
`server/data/features.json` 控制 12 个功能键（visual/orders/master/flex/timeline/drawing/mesh/knowledge/skills/gov/regen/settings）的界面可见性。改文件刷新浏览器即生效，无需重启；文件缺失/损坏时全部默认开启（fail-open）。注意：开关只隐藏入口，不替代 Harness 门禁。
---
## 18. 常见问题
| 问题 | 处理 |
| --- | --- |
| 排产失败提示缺失项 | 按 §6.5 顺序检查主数据：产线绑定 → BOM → 工艺路线 → 库存；用订单「追溯」看具体缺什么 |
| 排产被硬阻断（缺料/无设备） | 看冲突中心的聚合计数与证据：缺料先下达采购建议；无设备查设备停用/维保/故障状态 |
| 试排后想撤回 | 时间线点上一个检查点回滚（P2），回滚前系统自动再存档 |
| 三模式对比结果一样 | 产能宽裕时趋同；压缩交期制造压力后才分化 |
| 删了前端"项目"数据还在 | 项目/任务在前端工作区，排产世界在后端；清世界用「清空数据重新初始化」 |
| Web 登录不了 | 检查 `.env` 的 JMS 配置与会话密钥；账号问题找企业管理员 |
| 想看接口 | 后端起服后访问 http://localhost:8000/docs |
| 一键演示柔性全流程 | `.venv\Scripts\python.exe scripts\flex_simulation.py`（纯内存、结果确定，不起服务） |
### 验收快速路径
1. 「分析一下数据文件」→ 工程导入成功；
2. 「执行MRP分解」→ 采购建议出现；「下达MRP建议单」→ 批准后转 RELEASED；
3. 「对比几种策略」→ 方案卡 → 采用 → 右侧甘特刷新；
4. 「存个档」→ 点检查点回滚（P2 确认）；
5. 「跑一版柔性排产」→ 虚拟产线 / 工单出现；
6. 「发布这个版本」→ P2 批准 → 版本 PUBLISHED；
7. 回归测试：`pytest tests/golden -q`（当前基线 1071 passed / 1 既有失败 `test_preference_features`，与业务无关）。
---
*维护：能力变化以 `docs/product/features.md` 与 `docs/CHANGELOG.md` 为准，本手册随版本同步更新。*
Reference in New Issue View Git Blame Copy Permalink