# Aethon（安拓）用户手册

> 覆盖平台全部 6 大模块、50 个功能视图的中文使用说明。
> 快速上手见 [QUICKSTART.md](QUICKSTART.md)，部署见 [DEPLOYMENT.md](DEPLOYMENT.md)。

## 目录

- [1. 平台概览](#1-平台概览)
- [2. 登录与角色权限](#2-登录与角色权限)
- [3. 总览（overview）](#3-总览overview)
- [4. 生产运营（operations）](#4-生产运营operations)
- [5. 生产运营 · 物料 · 质量（operations continue）](#5-生产运营--物料--质量operations-continue)
- [6. 智能平台（ai）](#6-智能平台ai)
- [7. 系统（system）](#7-系统system)
- [8. 配置 LLM / 数据 / 多租户](#8-配置-llm--数据--多租户)
- [9. 外部集成（MCP）](#9-外部集成mcp)
- [10. 常见问题](#10-常见问题)

---

## 1. 平台概览

### 1.1 平台定位

Aethon 是面向中国离散制造业的 **AI 原生 MES 平台**：

- **车间执行**：设备、工单、生产记录、批次、追溯
- **工厂运营**：库存、采购、质量、维护、MRP、APS
- **质量合规**：检验、SPC、NCR、CAPA、SOP、报废原因
- **智能平台**：AI 助手、智能体、预测维护、AI RFQ、约束引擎、Agent 授权
- **管理与开放**：用户、报表、审计、事件日志、MCP 集成

### 1.2 页面组织

顶部导航按 **6 大模块** 组织（产品视角分组），覆盖全部功能视图：

| 模块 | 分组与视图 |
|------|-----------|
| **总览**（overview） | 看板类：总览、待办中心、车间大屏、执行看板、在线表格 |
| **设计器**（designer） | 低代码/系统基础：表单设计器、低代码页面、数据页设计器、Excel 工作台、报表设计器/运行时、业务对象录入、实体管理、字段标签、状态机配置、工作流 |
| **生产运营**（operations） | 订单·计划·执行：订单、客户订单、工单、APS、工序成本、工艺路线、领料/报工/返工、批次/序列号追溯；供应·采购：供应商、AI RFQ、采购订单、收货检验；物料·仓库：物料主数据、BOM、MRP、库存、仓储 WMS；质量·设备：质检、SPC、NCR、CAPA、安灯、SOP、设备点检、报废原因、设备、状态/原因、维护、停机、排班、告警、布局 |
| **分析**（analytics） | 数据分析、报表、图表组件 |
| **智能平台**（ai） | AI 洞察、AI 助手、AI 推荐、IoT、智能体、Agent 授权、预测维护、约束引擎 |
| **系统**（system） | 用户、设置、审计日志、事件日志 |

可根据套餐裁减模块（starter / growth / enterprise），`总览` 与 `系统` 始终开放。

### 1.3 数据与演示

首次启动自动写入全量演示数据（DEFAULT 与 DEMO 两个租户）。所有页面开箱即有数据可看，无需手工录入即可浏览功能。

---

## 2. 登录与角色权限

### 2.1 登录

访问前端首页自动跳转登录页，登录页展示品牌标识（艾腾 Aethon）并附「体验 Demo」快捷入口与官网链接。内置账号：

| 账号 | 密码 | 租户 | 角色 |
|------|------|------|------|
| `admin` | `admin@2026` | DEFAULT | Admin |
| `demo` | `demo@2026` | DEMO | Supervisor |

> 生产环境务必修改默认密码，见 [DEPLOYMENT.md](DEPLOYMENT.md#7-安全清单上线前逐项确认)。

### 2.2 角色

系统内置 5 个角色：

| 角色 | 权限 |
|------|------|
| Admin | `*` 全部权限 |
| Supervisor | `read,write,reports,quality` |
| Operator | `read,write` |
| Engineer | `read,write,maintenance,quality` |
| Viewer | `read` 只读 |

### 2.3 多租户隔离

数据按租户（tenant_code）严格隔离，登录后只能看到本租户数据。管理端（admin）可在「管理 → 用户」维护账号。

---

## 3. 总览（overview）

### 3.0 Excel 工作台

批量数据录入/导入导出统一入口（符合国内 Excel 使用习惯）：

**支持实体**：物料主数据、生产工单、工艺路线、工艺路线工序、物料清单 BOM、库存物料、系统用户。

**使用流程**：
1. 选择业务实体
2. **下载模板**（xlsx：中文表头、必填标记、下拉选项、填写说明）
3. 本地 Excel 填表（可整行复制粘贴）
4. **上传导入** → 生成校验报告（通过 N / 错误 M，逐行定位错误原因）
5. 修正错误后重新上传；全部通过后 **确认提交** 入库
6. **导出当前数据**：将系统数据导出为同格式 xlsx，便于回读/备份

> 校验规则：必填、唯一、类型、范围、下拉枚举、外键存在性（如工艺路线号/零件号）。提交前不落库，全部通过才写入（事务）。

### 3.1 总览（Overview）

综合仪表盘：OEE、可用率/性能/质量、进行中工单、未完成订单、停机、告警、安灯、低库存等关键 KPI 一览。

### 3.2 设备（Machines）

- 查看全部设备：名称、状态（Running/Idle/Downtime）、利用率、所属产线
- 点击设备查看详情：生产记录、停机历史、点检记录、遥测
- 支持新建/编辑设备、更新状态

### 3.3 停机（Downtime）

- 停机事件列表：设备、原因、时长、起止时间
- 原因分布统计（按原因聚合停机时长）
- 演示数据含「主轴过热保护停机」等事件

### 3.4 排班（Shifts）

- 班次计划（Day/Night）
- 每班达成率、平均效率
- 支持新增/编辑班次记录

### 3.5 分析（Analytics）

- 多维度 KPI 趋势图：OEE、产量、良率、停机
- 支持时间范围筛选

---

## 4. 生产运营（operations）

### 4.1 工单（Work Orders）

生产工单管理：
- 查看工单列表与状态（Pending/InProgress/Completed）
- 新建工单（关联产品、数量、计划日期）
- 工单执行：开工、完成、报废

### 4.2 批次（Lot Tracking）

生产批次（Lot）管理：批次号、产品、数量、状态、关联工单与订单。

### 4.3 序列号追溯（Serial & Trace）

- 追踪项（Tracked Item）：序列号、类型、当前工序、当前位置
- 追溯事件：每个追踪项的加工/检验/移库事件时间线
- 检验计划与检验结果关联
- 序列号规则：自定义前缀/日期格式/流水位数的序列号生成规则
- 追溯链路（Trace Link）：父件-子件-原料的上下游关系

### 4.4 订单（Orders）

生产订单管理：订单号、产品、数量、交期、状态（开放/完成）。

### 4.5 客户订单（Customer Orders）

- 客户订单录入（含上传）
- 订单风险统计（风险状态、到期预警）

### 4.6 供应商（Suppliers）

供应商主数据：名称、联系人、付款条件、状态。支持增删改查。

### 4.7 采购订单（Purchase Orders）

- 采购单列表：单号、供应商、金额、状态（草稿/已下单/已收货）
- 采购明细行
- 新建采购单

### 4.8 收货检验（Receiving）

- 待收货采购单（Open POs）
- 到货登记 + 来料检验
- 检验不合格 → 生成 NCR

### 4.9 工作流（Workflows）

审批流管理：
- 流程定义：步骤、角色、自动完成标记
- 流程实例：运行中的审批实例、当前步骤
- 待办任务：审批/驳回
- 演示数据含 CAPA 审批流、采购订单审批流

### 4.10 工序成本（Phase Costing）

按工单工序展示成本：人工/设备/材料/外包费用、计划/实际工时、报废与返工数量。

### 4.11 工艺路线（Process Routes）

- 工艺路线定义：路线编号、产品、工序步骤序列
- 每道工序：设备类型、关键工序标记、是否需质检
- 工序步骤：顺序、描述

### 4.12 报废原因（Scrap Reasons）

报废原因代码管理：材料缺陷、刀具磨损、操作失误等，含分类与显示顺序。

---

## 5. 生产运营 · 物料 · 质量（operations continue）

### 5.1 库存（Inventory）

- 物料台账：编码、名称、现有量、安全库存、再订货点、库位
- 低库存清单（低于再订货点）
- 库存健康度：总值、低库存项数
- 新增/编辑物料

### 5.2 仓储 WMS（Warehouse）

- 库位管理：仓库、区域、通道、货架、类型、最大容量
- 循环盘点：创建盘点单、录入实盘数、差异/差异金额、调整
- 库存交易流水：收/发/调拨明细

### 5.3 质检（Quality）

- 检验记录：检验单号、数量、合格/不合格、缺陷分类、状态
- 良率分析：合格率、缺陷分布
- 录入新检验

### 5.4 维护（Maintenance / CMMS）

- 维护任务：任务号、设备、类型（预防性/维修）、优先级、计划日期、状态
- 维护排程：按 30 天周期自动建议预防性维护（由维护智能体触发）
- 设备点检在「设备点检」页

### 5.5 BOM（物料清单）

- BOM 头：BOM 号、产品、版本
- BOM 行：组件物料、数量、损耗
- 多级展开（Explode）：一键查看产品全层级物料需求

### 5.6 物料主数据（Parts）

物料主数据：零件号、名称、类型、单位、标准/材料/人工/制造费用、提前期、安全库存、是否关键件、是否需检验。

### 5.7 MRP（物料需求计划）

- 运行 MRP：输入计划展望期，系统分析所有零件需求
- 需求清单：物料、需求量、可用量、短缺量、来源（销售/工单）
- 短缺项与建议动作（采购/生产/催货）
- 对动作执行「应用」：生成采购订单或工单

### 5.8 布局（Factory Layout）

SVG 可视化工厂布局：设备节点按 Zone 分组排布，直观展示产线位置。

### 5.9 SPC 控制（SPC）

- 过程参数：参数、产品、USL/LSL/Target、样本量
- SPC 测量数据：180+ 组测量值
- CPK 计算：低于 1.33 的参数高亮提示（过程能力不足）

### 5.10 安灯（Andon）

- 安灯呼叫列表：状态（开/关）、紧急度、设备
- 按类型统计
- 响应/关闭呼叫

### 5.11 SOP 作业指导（SOP）

- 文档管理：编号、标题、产品、工序、版本、类型
- 内容含步骤（Steps）与安全注意事项
- 知识库可被 AI 检索（RAG），回答规范类问题

### 5.12 CAPA（纠正与预防措施）

- CAPA 记录：问题描述、根因、纠正措施、预防措施、责任人与状态
- 质量/设备类问题闭环管理
- 支持从 NCR 关联生成

### 5.13 NCR 不合格品（NCR）

- 不合格品记录：编号、来源（检验/收货）、产品、数量、缺陷类别、严重度
- 处置流程：Rework/Return/Scrap
- 状态流转：Open → 处置 → Closed
- 根因分析、负责人、到期日
- 关联/创建 CAPA

### 5.14 设备点检（Point Check）

- 点检项：检查内容、标准、频次
- 点检记录：完成情况、结果
- 点检汇总

### 5.15 状态/原因（Status & Reasons）

- 设备状态主数据（Running/Idle/Downtime 等）
- 停机/异常原因代码
- 状态流转定义

### 5.16 告警（Alerts）

- 告警列表：类型、严重度、标题、关联设备、解决状态
- 来源含：系统规则、智能体、AI
- 标记解决

---

## 6. 智能平台（ai）

### 6.1 IoT 指挥中心（IoT）

- 遥测信号：温度、振动、负载、转速、功率等实时值
- 按设备查看最近遥测
- 数据来自 PLC 模拟器（每 45 秒滚动）

### 6.2 AI 洞察（AI Insights）

- AI 生成的关键洞察与趋势
- 智能体动作指标：数量、类型、状态分布

### 6.3 AI 助手（Copilot）

对话式工厂数据分析：

- 输入自然语言问题，例如：
  - 「工厂整体状况如何？」
  - 「哪个设备风险最高？」
  - 「库存有哪些缺料？」
  - 「注塑机温度超限应该怎么做？」
- **引擎选择**：
  - 配置 LLM 后：`toolchain` 模式，AI 自主调用 27 个制造工具取数、推理、回答
  - 未配置：`rule` 模式，规则引擎兜底
- 会话记忆：同一会话自动记住上下文（session_id），支持多轮对话

### 6.4 智能体（Agents）

5 大制造智能体（维护/质量/补货/升级/良率）：

| 智能体 | 职责 | 触发条件 |
|--------|------|----------|
| maintenance | 预防性维护 | 设备 30 天无维护且无待排任务 |
| quality | 质量升级 | 近 10 次检验失败率 > 10% |
| reorder | 自动补货 | 库存 ≤ 再订货点 |
| escalation | 停机升级 | 设备处于停机且有停机记录 |
| yield | 良率改进 | 近 20 次检验良率 < 90% |

**运行方式**：
- 「运行巡检」按钮：默认 `auto`（有 LLM 走 AI 巡检，否则规则）
- `mode=llm`：强制 LLM 巡检（带置信度与推理，经 propose_action 走授权边界）
- `mode=rule`：强制规则巡检
- 动作结果展示在动作列表，可查看状态（Proposed/Approved）与决定方式（auto/human）

### 6.5 执行看板（Executive OEE）

高层驾驶舱：OEE 总览、告警统计、汇总 KPI。

### 6.6 APS 排程（APS）

- 产能排程：任务甘特图
- 负载图：设备负载分布
- 冲突检测：识别排程冲突

### 6.7 AI RFQ 报价（RFQ）

- 询价包管理：客户、状态、上传附件
- 解析询价文件 → 成本估算（材料/工时/制造费用）
- 生成报价单：明细行、单价、汇总、交期
- 成本分析：毛利/成本结构

### 6.8 预测维护（Predictive）

- 设备健康评分（数字孪生）
- 故障风险评分：含 IoT 遥测因素（温度 > 65°C / 振动 > 5mm/s / 负载 > 95% 计风险）
- 风险等级：Low/Medium/High/Critical
- 支持将高风险设备一键转为维护动作

### 6.9 约束引擎（Constraints）

- 规则集：名称、范围（SPC/设备等）、软限/硬限
- 规则求值：对指定变量执行软/硬限检查
- 违规审计：记录违规与影子模式（shadow）标记

### 6.10 Agent 授权（Agent Authz）

- 授权边界：按智能体定义可自主执行 vs 需人工审批的动作类别
- 参数：价格容忍度、最大锁定量、置信度阈值、每日自主上限
- 测试求值：对动作实时判定 auto/human
- 反馈驱动调参：历史效果反馈自动调整置信度阈值

### 6.11 AI 推荐（Recommendations）

- AI 推荐列表：类型（维护/补货/质量改进）、严重度、置信度、状态
- 操作：知悉（Acknowledge）、解决（Resolve）、忽略（Dismiss）

---

## 7. 系统（system）

### 7.1 报表（Reports）

- OEE 报表、质量报表
- 导出：CSV / HTML

### 7.2 审计日志（Audit Log）

- 系统操作留痕：操作人、动作、实体、详情、时间
- 合规追溯与安全审查

### 7.3 事件日志（Event Log）

- 领域事件流：设备状态变更、检验创建、库存调整、智能体动作、告警触发
- 按类型筛选

### 7.4 用户（Users）

- 用户列表与角色分配
- 新建/编辑/删除用户（Admin）
- 角色管理

### 7.5 设置（Settings）

- 租户配置：套餐、启用的功能包、品牌名称/颜色

---

## 8. 配置 LLM / 数据 / 多租户

### 8.1 配置 LLM

编辑 `backend/.env`：

```bash
# 单 Provider：
AETHON_LLM_API_KEY=sk-xxxx
AETHON_LLM_BASE_URL=https://api.deepseek.com/   # OpenAI 兼容端点
AETHON_LLM_MODEL=deepseek-chat

# 或多 Provider 链（按顺序回退）：
AETHON_LLM_PROVIDERS=[{"provider":"deepseek","api_key":"sk-..."},{"provider":"openai","api_key":"sk-..."}]
```

已知快捷 Provider：`deepseek` / `openai` / `qwen` / `moonshot` / `zhipu` / `ollama`。

配置后效果：
- Copilot / 巡检 / 编排使用 `toolchain` 引擎（AI 调用工具）
- 未配置或全部 Provider 失败时自动降级规则引擎，不会报错

### 8.2 数据存储

- 默认 SQLite（`./aethon.db`），零配置
- 生产用 PostgreSQL（`DATABASE_URL=postgresql+psycopg2://...`）
- Schema 迁移用 Alembic（生产启动自动执行，见 DEPLOYMENT.md）

### 8.3 多租户

- 租户代码（DEFAULT/DEMO）隔离数据
- 每个租户独立：设备/订单/库存/质量/知识库/授权边界/记忆
- MCP 独立模式下用 `AETHON_MCP_TENANT` 指定租户

---

## 9. 外部集成（MCP）

Aethon 通过 Model Context Protocol（2024-11-05）将制造工具暴露给外部智能体：

**27 个工具**：`get_factory_overview` / `query_oee` / `query_production` / `query_inventory` / `query_quality` / `query_downtime` / `query_maintenance` / `query_machine_health` / `query_telemetry` / `query_spc` / `query_andon` / `query_shift_performance` / `search_knowledge` / `query_priority` / `propose_action` / `execute_production` / `design_form` / `design_report` / `design_bigscreen` / `extend_fields` / `query_schedule_strategies` / `query_schedule_kpi` / `add_downtime` / `run_mrp` / `create_work_order` / `prefill_form` / `query_finance`

**三种接入方式**：

```bash
# 1) FastAPI 内嵌（推荐）：
POST /api/mcp/messages   # JWT Bearer，租户取自 token
GET  /api/mcp/tools

# 2) 独立 HTTP（未配置 --api-key 时一律 401，fail-closed）：
python -m app.mcp_server --http --port 8230 --tenant DEFAULT --api-key <key>

# 3) stdio（BYOE / Claude / VS Code）：
python -m app.mcp_server --tenant DEFAULT
```

**BYOE 接入示例**：

```python
from byoe.engine.mcp import MCPSession
sess = MCPSession.from_http("http://localhost:8230", name="aethon")
tools = sess.get_tools()          # 27 个工具
out = sess.call_tool("get_factory_overview", {})
```

**治理**：`propose_action` 仍走租户授权边界（auto vs human）；`query_*` 只读实时工厂数据。外部智能体无法越权变更工厂。

---

## 10. 常见问题

| 问题 | 解决 |
|------|------|
| 登录失败 | 确认账号密码；生产环境已修改默认密码 |
| 页面空数据 | 登录 admin（DEFAULT 租户）看全量演示数据 |
| AI 助手像模板回答 | 未配置 LLM，走规则引擎；配置后升级为 toolchain |
| 智能体不触发 | 触发条件未满足（如无停机设备则 escalation 不触发）；演示数据已覆盖各触发条件 |
| 无法导出报表 | 检查浏览器下载权限 |
| MCP 连不上 | 确认服务运行；HTTP 模式确认 API Key 正确 |
| 需要多租户 | 在用户管理创建新用户并指定租户代码 |

---

## 附录 A：内置账号与演示数据

| 项 | 值 |
|----|----|
| 管理员 | `admin` / `admin@2026`（DEFAULT） |
| 演示账号 | `demo` / `demo@2026`（DEMO） |
| 租户 | DEFAULT、DEMO |
| 设备 | 17 台（CNC/装配/QC/激光/折弯/焊接等） |
| 知识库 | 5 条 SOP（含中文）、工艺路线、检验计划、Agent 记忆 |
| 智能体动作 | 5 类 Agent 均会触发 |
| 遥测 | 温度/振动/负载实时采样 |

## 附录 B：默认端口

| 服务 | 地址 |
|------|------|
| 后端 API | http://localhost:8200 |
| 前端 | http://localhost:3000 |
| MCP 独立 HTTP | http://localhost:8230 |
| 健康检查 | http://localhost:8200/health |
