Robot 生产追溯系统菜单与功能页面详细方案（MVP）

1. 文档目标

基于 ../docs 项目方案，结合当前前端已实现的用户权限与设备类型能力，给出可直接用于前端页面开发和联调的菜单与功能页面设计，覆盖：

• 菜单结构
• 页面字段（查询区/列表区/表单区/详情区）
• 页面操作（按钮、状态流转、批量操作）
• 角色权限边界

本方案默认不改变现有公开路由与已存在按钮权限键；新增内容使用“建议新增”标记。

2. 当前项目现状（已实现基线）

2.1 已有菜单与路由

• / 首页（Dashboard 示例）
• /inbox 消息页（示例）
• /customers 客户页（示例）
• /base-info/device-types 设备类型（业务相关，已较完整）
• /settings 个人信息
• /settings/members 成员管理
• /settings/notifications 通知设置
• /settings/security 安全设置

2.2 当前角色体系（代码事实）

• 鉴权角色（登录态 roles）：admin、qa_manager、operator
• 成员资料角色（成员管理 role）：member、admin、customer

建议后续统一口径：

• “系统角色”用于 RBAC、菜单与按钮权限（如 admin/qa_manager/operator/customer_viewer）
• “成员标签”用于组织管理展示（如 member/admin/customer）

2.3 当前设备类型页面（代码事实）

当前设备类型核心字段：

• id
• name
• model
• category（robot/controller/vision/chassis/communication/power/sensor/actuator/other）
• lengthMm/widthMm/heightMm
• weightKg
• hasBattery
• batterySpec
• description
• updatedAt

当前设备类型操作：

• 查询：关键字、分类过滤、电池过滤
• 列表：分页、列显隐、行选择
• 新增/编辑/删除（含批量删除）
• 权限键：device-types.create、device-types.update、device-types.delete

3. MVP 菜单总体结构

建议菜单树（按业务闭环，不按技术模块）：

1. 工作台
2. 生产执行
3. 质量与异常
4. 追溯与报表
5. 基础资料
6. 系统管理

菜单与页面建议路由如下：

一级菜单	二级菜单	建议路由	MVP优先级
工作台	生产总览	/dashboard/overview	P0
生产执行	工单管理	/production/work-orders	P0
生产执行	SN 管理	/production/sn-items	P0
生产执行	工序执行台	/production/operations	P0
生产执行	扫码开工	/production/scan-start	P0
生产执行	测试结果录入	/production/test-results	P0
质量与异常	异常管理	/quality/exceptions	P0
质量与异常	返修闭环	/quality/repairs	P0
追溯与报表	SN 追溯查询	/trace/sn	P0
追溯与报表	工单/批次追溯	/trace/work-order-batch	P1
追溯与报表	质量报表导出	/reports/quality	P1
基础资料	设备类型	/base-info/device-types	已有/P0
基础资料	设备台账	/base-info/equipments	P0
基础资料	工位管理	/base-info/workstations	P0
基础资料	工艺路线	/base-info/process-routes	P0
基础资料	物料与批次	/base-info/materials	P1
系统管理	用户与成员	/settings/members	已有/P0
系统管理	角色权限	/settings/rbac	P0
系统管理	个人设置	/settings	已有/P1
系统管理	通知设置	/settings/notifications	已有/P1
系统管理	安全设置	/settings/security	已有/P1

4. 角色与菜单访问建议

4.1 角色定义（建议）

• admin：全权限
• qa_manager：质量、追溯、部分基础资料维护
• operator：执行端操作（扫码、工序、测试录入、异常提交）
• customer_viewer（建议新增）：采购方只读追溯和只读报表

4.2 菜单访问矩阵（建议）

页面	admin	qa_manager	operator	customer_viewer
生产总览	读	读	读(工位维度)	否
工单管理	读写审	读写(质量字段)	读	否
SN 管理	读写	读写	读	否
工序执行台	读写	读写	读写	否
扫码开工	读写	读写	读写	否
测试结果录入	读写	读写审	录入	否
异常管理	读写审	读写审	提交/查看本人	否
返修闭环	读写审	读写审	执行返修记录	否
SN 追溯查询	读	读	读(授权范围)	读(授权范围)
报表导出	读导出	读导出	只读	只读
设备类型	读写删	读写	读	否
用户与成员	读写	部分编辑	否	否
角色权限	读写	只读	否	否

5. 页面详细方案

以下页面均按统一结构设计：

• 查询区（筛选项）
• 列表区（表格主字段）
• 新增/编辑表单（必要字段与校验）
• 操作按钮（含批量操作）

---

5.1 工作台-生产总览 /dashboard/overview

查询区字段

字段	类型	说明
日期范围	daterange	默认最近14天
工厂/产线	select	数据权限范围内
工单状态	multi-select	草稿/待派工/执行中/异常中/待质检/已完成/已关闭

看板模块

模块	指标
工单进度	总工单、执行中、待质检、异常中
SN 进度	已完工SN、在制SN、冻结SN
质量趋势	首测通过率、复测通过率、异常率
设备状态	在线设备数、离线设备数、故障设备数

操作

• 刷新看板
• 导出当日汇总（CSV）
• 跳转到异常清单/工单列表

---

5.2 生产执行-工单管理 /production/work-orders

查询区字段

字段	类型	说明
工单号	input	支持模糊
产品型号	input/select	关联设备类型或产品主数据
批次号	input	支持模糊
状态	select	工单状态机
计划时间	daterange	plan_start/plan_end

列表字段

字段	说明
工单号 order_no	唯一
产品型号 product_model
批次号 batch_no
数量 qty
工艺路线 route_name/version
状态 status
计划开始/结束
完成率	已完工SN/总SN
创建人/创建时间

工单表单字段

字段	校验
工单号	必填、唯一、长度限制
产品型号	必填
批次号	必填
数量	必填、正整数
工艺路线ID	必填
计划开始/结束	必填，开始<=结束
备注	可选，长度限制

操作

• 新建草稿
• 编辑草稿
• 下达（待派工）
• 暂停/恢复
• 取消（草稿/待派工）
• 关闭（已完成后）
• 导出工单明细

---

5.3 生产执行-SN 管理 /production/sn-items

查询区字段

字段	类型
SN	input
工单号	input/select
状态	select（在制/冻结/完成/报废）
当前工序	select
异常状态	select

列表字段

字段	说明
SN	唯一主线
工单号
当前工序	current_step_id对应名称
状态
是否冻结	frozen
最近测试结果	Pass/Fail
最近异常等级
更新时间

操作

• 批量导入SN
• 冻结/解冻SN（需记录原因）
• 标记报废（需审批）
• 查看SN全流程详情

---

5.4 生产执行-工序执行台 /production/operations

查询区字段

字段	类型
工位	select
工序	select
操作员	select
任务状态	select（待开始/进行中/待测试/失败/返修中/已完成）
SN	input

列表字段

字段	说明
任务ID	operation_task.id
工单号/SN
工序	step名称
工位/设备
操作员
开始/结束时间
结果	Pass/Fail/待提交
状态

操作

• 开工（可由扫码页触发）
• 完成装配（转待测试）
• 提交测试结果（转通过/失败）
• 跳过工序（管理员授权）
• 查看任务审计事件

---

5.5 生产执行-扫码开工 /production/scan-start

输入字段

字段	校验
SN	必填，格式校验
工位	必填，默认当前登录工位
设备编号	必填（测试工序必填）
物料批次（可多条）	按工序要求校验

响应展示字段

字段	说明
工单号
当前工序
校验结果	成功/失败
下一步动作 nextAction	继续执行/录入测试/创建异常
错误码 errorCode	用于前端提示

操作

• 扫码开工提交（防抖+幂等键）
• 补扫码申请（管理员审批）
• 重复扫码冲突提示

---

5.6 生产执行-测试结果录入 /production/test-results

查询区字段

字段	类型
SN	input
工单号	input/select
测试项	select
结果	select（通过/失败）
时间范围	daterange

列表字段

字段	说明
SN/工单
工序/测试项
标准值/上下限	standard/lower_limit/upper_limit
实测值/单位	value/unit
判定结果	result
测试人/时间	tested_by/tested_at
附件	attachment_url/hash

测试录入表单字段

字段	校验
测试项	必填
标准/阈值	必填，数值逻辑合法
实测值	必填，数值
单位	可选
结果	后端判定优先，前端只展示
原始数据JSON	可选
附件上传	类型/大小/魔数校验
备注	可选

操作

• 单条录入提交
• 批量导入测试结果
• 附件上传与预览
• 锁定后禁止修改（返修复测除外）

---

5.7 质量与异常-异常管理 /quality/exceptions

查询区字段

字段	类型
异常单号	input
SN/工单号	input
异常类型	select（测试失败/漏扫/物料不匹配/设备离线/权限问题）
等级	select（一般/严重/致命）
状态	select（待处理/处理中/已关闭）
责任人	select

列表字段

字段	说明
异常单号
SN/工单
触发工序
类型/等级
原因
决策	返修/放行/报废
责任人	owner_id
状态
创建/关闭时间

操作

• 创建异常
• 分配责任人
• 冻结SN
• 处理决策（返修/放行/报废）
• 关闭异常（必须填写处理结论）

---

5.8 质量与异常-返修闭环 /quality/repairs

查询区字段

字段	类型
返修单号/异常单号	input
SN	input
状态	select（返修中/待复测/通过/失败）
返修人	select

列表字段

字段	说明
返修单号
异常单号
SN
返修动作	action
返修人/时间
复测任务	retest_task_id
复测结果	result
闭环状态

操作

• 填写返修动作
• 发起复测
• 复测结论提交
• 返修关闭（自动回写异常状态）

---

5.9 追溯与报表-SN 追溯查询 /trace/sn

查询区字段

字段	类型
SN	input（必填）
展示层级	select（简版/完整链路）

结果视图字段

区块	字段
基本信息	SN、工单号、批次号、产品型号、当前状态
工序链路	工序序号、状态、操作员、工位、设备、开始/结束时间
测试结果	测试项、阈值、实测值、结果、附件
物料绑定	物料编码、批次、供应商、数量、绑定时间
异常返修	异常类型、原因、决策、返修动作、复测结论
事件审计	action、before/after、actor、occurred_at、hash

操作

• 查询
• 导出单SN追溯报告（PDF/CSV）
• 复制追溯链接（仅内网）

---

5.10 追溯与报表-工单/批次追溯 /trace/work-order-batch

查询区字段

字段	类型
工单号	input
批次号	input
型号	select/input
时间范围	daterange

结果字段

字段	说明
总SN数
完成数/在制数/冻结数
首测通过率
异常率
返修率
关联异常Top N

操作

• 导出批次追溯报告
• 下钻到SN列表

---

5.11 追溯与报表-质量报表导出 /reports/quality

筛选字段

字段	类型
时间范围	daterange
维度	select（工单/产线/设备/人员/型号）
指标	multi-select（通过率/异常率/返修率/设备可用率）

操作

• 生成图表
• 导出 CSV/XLSX
• 导出任务异步化（大数据量）

---

5.12 基础资料-设备类型 /base-info/device-types（已实现对齐）

查询区字段（现状）

字段	说明
关键字 q	匹配 name/model/category
分类 categoryFilter	all + 分类枚举
电池过滤 batteryFilter	all/with/without

列表字段（现状）

字段	说明
选择列	支持批量删除
ID	id
名称	name
型号	model
分类	category 文案化
尺寸	length×width×height
重量	weightKg
电池	hasBattery badge
更新时间	updatedAt

表单字段与校验（现状）

字段	校验
名称 name	必填，<=60
型号 model	必填，<=40
分类 category	必填，枚举
长宽高 lengthMm/widthMm/heightMm	>0 且 <=100000
重量 weightKg	>0 且 <=10000
是否带电池 hasBattery	bool
电池规格 batterySpec	带电池时必填，<=80
描述 description	<=200

页面操作（现状）

• 新增
• 编辑
• 删除（单条/批量）
• 列显隐
• 分页

可扩展字段（建议新增）

字段	用途
code 设备类型编码	与 ERP/MES 对接
testProfileId 测试模板	自动带出测试项
safetyLevel 安全等级	工艺与权限联动
status 启用状态	停用后禁止新工单引用

---

5.13 基础资料-设备台账 /base-info/equipments

字段

字段	说明
设备编号 equipment_no	唯一
设备名称
设备类型ID	引用 device_type
所属工位	workstation_id
状态	在线/离线/故障/维护
最近心跳时间
负责人

操作

• 新增/编辑/停用
• 绑定工位
• 状态切换（维护/恢复）

---

5.14 基础资料-工位管理 /base-info/workstations

字段

字段	说明
工位编码	唯一
工位名称
产线
可执行工序	多选
绑定角色	操作员/质检等
状态	启用/停用

操作

• 新增/编辑/启停
• 绑定设备
• 绑定可执行工序

---

5.15 基础资料-工艺路线 /base-info/process-routes

路线主表字段

字段	说明
路线编码 code	唯一
路线名称 name
版本 version
生效时间 effective_from
状态	草稿/生效/停用

工序子表字段

字段	说明
序号 seq_no
工序编码 step_code
工序名称 step_name
类型 type	装配/测试/终检
必需角色 required_role_id
是否测试工序 need_test
是否质检工序 is_qc

操作

• 新增路线
• 复制历史版本
• 发布生效
• 停用

---

5.16 基础资料-物料与批次 /base-info/materials

字段

字段	说明
物料编码	唯一
物料名称
规格型号
供应商
批次号
入库日期
有效期	可选
状态	可用/冻结/失效

操作

• 新增/编辑物料
• 批次入库
• 批次冻结/解冻
• 查询关联SN

---

5.17 系统管理-用户与成员 /settings/members（已实现对齐）

列表字段（现状）

字段	说明
头像 avatar
姓名 name
用户名 username
角色 role	member/admin/customer

成员表单字段（现状）

字段	校验
name	最短2位
email	email格式
username	最短2位
role	枚举 member/admin/customer
avatar	可选
bio	可选

页面操作（现状）

• 邀请成员 members.invite
• 编辑成员 members.edit
• 更新角色 members.role.update
• 移除成员 members.remove

能力缺口（建议）

• 成员角色目前与系统角色分离，缺少“系统角色绑定”字段
• 建议新增字段：systemRoles: string[]、dataScope（工厂/产线/工位）

---

5.18 系统管理-角色权限 /settings/rbac（建议新增）

角色管理字段

字段	说明
角色编码	唯一
角色名称
角色类型	系统/业务
角色状态	启用/停用

权限配置字段

字段	说明
页面权限	路由级
按钮权限	操作级
数据权限	工厂/产线/工位/工单范围

操作

• 新增角色
• 复制角色
• 分配页面与按钮权限
• 分配数据范围

---

6. 按钮权限键规划

6.1 已存在（保持不变）

• members.invite
• members.edit
• members.role.update
• members.remove
• customers.create
• customers.delete
• device-types.create
• device-types.update
• device-types.delete

6.2 建议新增（按模块）

• 工单：work-orders.create work-orders.update work-orders.release work-orders.pause work-orders.close
• SN：sn.freeze sn.unfreeze sn.scrap
• 工序：operations.start operations.complete operations.skip
• 测试：test-results.submit test-results.import test-results.retest
• 异常：exceptions.create exceptions.assign exceptions.decide exceptions.close
• 返修：repairs.record repairs.retest repairs.close
• 追溯与报表：trace.export reports.export
• RBAC：rbac.role.create rbac.role.update rbac.permission.assign

7. 页面交互与状态统一约定

所有提交类接口统一响应结构：

• success: boolean
• state: string
• nextAction: string
• errorCode: string | null
• message: string

前端处理规则：

• success=false：只走错误提示，不自行变更业务状态
• 有 nextAction：驱动页面按钮状态和后续引导
• 任何关键动作失败必须保留上下文（不清空输入）

8. 与当前项目对齐的实施顺序

阶段 A（先落地真实业务骨架）

1. 新增菜单组与基础空页：生产执行/质量与异常/追溯与报表
2. 完成工单管理、SN管理、扫码开工、异常管理四个P0页面
3. 复用当前权限框架扩展按钮键与路由可见性

阶段 B（补齐闭环）

1. 工序执行台与测试结果录入
2. 返修闭环
3. SN追溯详情页

阶段 C（管理完善）

1. 设备台账、工位、工艺路线
2. 角色权限配置页
3. 报表导出和批次追溯

9. 本方案可直接用于任务拆解的最小单位

建议研发任务单按“页面 + API + 权限键”三元组拆分，例如：

• 工单管理页 + /api/work-orders* + work-orders.*
• 扫码开工页 + /api/sn/{sn}/scan-start + operations.start
• 异常管理页 + /api/exceptions* + exceptions.*

每个任务单必须包含：

• 字段定义（查询、列表、表单）
• 操作按钮
• 状态流转
• 权限键
• 失败态与空态