版本: 1.1 (release prepare) 日期: 2025-07-27
修订历史
| 版本 | 日期 | 作者 | 说明 |
|---|
| 1.0 | 2025-07-27 | @cym | 初始版本 |
| 1.1 | 2025-07-28 | @phil616 | 发布准备版 |
| 1.2 | 2025-07-29 | @phil616 | 发布版本 |
目录
- 引言
- 总体描述
- 功能需求
- 非功能需求
- 外部接口需求
- 数据需求
- 业务流程与用例
- 可追溯性矩阵
- 术语表
- 附录
1. 引言
1.1 文档目的
本需求规格说明文档旨在定义工件质量溯源系统的所有软件需求，明确系统功能、性能及接口，为项目经理、开发、测试及运维人员提供统一、可验证的依据。
1.2 范围
工件质量溯源系统由以下子系统组成：
- 后端服务，混用名称：API端、后端、业务端
- 微信小程序用户端，混用名称：用户终端，小程序端，用户端，客户端
- 管理端，混用名称： 管理员端，Dashboard端
- 图像识别模块 (第三方 API)，混用名称：CV端，视觉处理、图像识别、图像处理端
系统支持工件类型和型号自动识别、检查员质检记录、调度流程、维修员任务管理及常规系统管理（用户、日志、通知等）。
不在范围: ERP/MES 深度集成、移动原生 App、离线模式。
1.3 术语、缩写与定义
| 缩写/术语 | 定义 |
|---|
| SRS | Software Requirements Specification 软件需求规格文档 |
| API | Application Program Interface 应用程序接口 |
| CV | Computer Vision 计算机视觉 |
1.3.1 系统定义说明
| 缩写、术语 | 定义、意义 |
|---|
| api-platform | API 平台 |
| miniapp | 微信小程序 |
| admin-dashboard | 管理端 |
| cvcore-proxy | 图像识别模块 |
1.3.2 角色定义
| 缩写、术语 | 定义、意义 |
|---|
| Inspector | Industrial Inspector 工业检验员角色 |
| Maintenance | Maintenance Technician 维护人员角色 |
| Administrator | Dispatch Administrator 调度员管理员角色 |
1.3.3 实体定义
| 缩写、术语 | 定义、意义 |
|---|
| Workpiece | 工件实体 |
| WorkpieceMapping | 工件图片映射实体 |
| User | 用户实体 |
| AccessLog | 操作日志 |
| Role | 权限控制 |
| IssueTicket | 问题工单 |
1.4 参考资料
1.5 文档结构
本说明书依 IEEE 830 建议，按"总体描述 → 具体需求 → 附件"顺序组织，以便对应项目生命周期。
2. 总体描述
2.1 产品视角
系统作为独立质量管理模块，可与上层 ERP/MES 系统通过 RESTful 接口集成。下图示意其体系结构：
- 微信小程序用户端（用户终端）
- Dashboard管理端（管理员终端）
- API端（服务后端）
- 图像识别模块（第三方 API）
2.2 产品功能摘要
- 图像识别：工件类型、型号和 ID 自动识别
- 质检记录：维修员上传结果、图片与备注
- 工件检查：检察员上传工件情况。
- 任务调度：调度员分配任务，维修员接收并反馈
- 系统管理：用户/角色管理、日志查看、参数配置
2.3 用户特征
| 用户角色 | 对应角色 | 使用环境 |
|---|
| 检查员 | Inspector | 现场 |
| 调度员 | Administrator | 管控中心 |
| 维修员 | Maintenance | 现场 |
| 管理员 | System | 办公室 |
2.4 运行环境
2.5 设计与实现约束
- 使用 RESTful API 设计原则
- 接口遵循 OpenAPI 3.0 规范
- JWT 鉴权机制
- 图像识别延时必须 ≤500ms
2.6 假设与依赖
- 第三方图像识别服务可用且满足 SLA
- 网络环境稳定，带宽≥10Mbps
3. 功能需求
每项功能均需编号 (F(1 位模块)(2 位序号)，例如F0301)，并包含以下属性：
- 需求 ID
- 描述
- 前置条件
- 输入
- 处理
- 输出
- 错误/异常处理
- 优先级 (高、中、低)
- 可追溯性 (关联用例)
3.1 用户认证与授权模块
3.1.1 微信联合登录
| 需求ID | F101 |
|---|
| 描述 | 允许用户通过微信身份认证体系登录小程序，并与系统用户绑定 |
| 前置条件 | 用户已安装微信小程序 |
| 输入 | 微信授权信息（OpenID、用户基本信息） |
| 处理 | 验证微信授权，检查OpenID是否已绑定，创建或关联系统用户 |
| 输出 | JWT令牌，用户基本信息 |
| 异常 | 微信授权失败、网络异常、重复绑定异常 |
| 优先级 | 高 |
| 可追溯性 | UC101 |
3.1.2 管理员登录
| 需求ID | F102 |
|---|
| 描述 | 管理员通过用户名密码方式登录Dashboard管理端 |
| 前置条件 | 管理员账户已创建并激活 |
| 输入 | 用户名、密码 |
| 处理 | 验证用户名密码，检查用户权限，生成JWT |
| 输出 | JWT令牌，用户权限信息 |
| 异常 | 用户名密码错误、账户未激活、权限不足 |
| 优先级 | 高 |
| 可追溯性 | UC102 |
3.1.3 权限管理
| 需求ID | F103 |
|---|
| 描述 | 管理员可进行用户权限管理和角色分配 |
| 前置条件 | 管理员已登录且具有权限管理权限 |
| 输入 | 用户ID、角色信息、权限范围 |
| 处理 | 验证管理员权限，更新用户角色和权限配置 |
| 输出 | 权限更新结果 |
| 异常 | 权限不足、用户不存在、角色配置错误 |
| 优先级 | 中 |
| 可追溯性 | 管理功能用例 |
3.2 图像识别模块
3.2.1 工件图像识别
| 需求ID | F201 |
|---|
| 描述 | 通过图像识别技术自动识别工件类型、型号和ID |
| 前置条件 | 用户已登录，图像识别服务可用 |
| 输入 | 工件图像文件 |
| 处理 | 调用第三方CV API，解析识别结果，匹配工件数据库 |
| 输出 | 工件ID、类型、型号、置信度 |
| 异常 | 图像格式不支持、识别失败、网络超时、置信度过低 |
| 优先级 | 高 |
| 可追溯性 | UC103, UC105 |
3.2.2 图像存储管理
| 需求ID | F202 |
|---|
| 描述 | 管理工件图像的存储和映射关系 |
| 前置条件 | 图像识别完成 |
| 输入 | 图像文件、工件ID、识别结果 |
| 处理 | 存储图像文件，创建工件图像映射记录 |
| 输出 | 图像URL、映射记录ID |
| 异常 | 存储空间不足、文件格式错误、映射创建失败 |
| 优先级 | 中 |
| 可追溯性 | F201 |
3.3 检查管理模块
3.3.1 检查任务分配
| 需求ID | F301 |
|---|
| 描述 | 系统自动或管理员手动分配检查任务给检查员 |
| 前置条件 | 存在待检查工件，检查员已登录 |
| 输入 | 工件ID、检查员ID、检查类型 |
| 处理 | 创建检查任务记录，分配给指定检查员 |
| 输出 | 检查任务ID、任务详情 |
| 异常 | 工件不存在、检查员不可用、重复分配 |
| 优先级 | 高 |
| 可追溯性 | UC103 |
3.3.2 检查结果上报
| 需求ID | F302 |
|---|
| 描述 | 检查员完成检查后上报检查结果和相关图片 |
| 前置条件 | 检查员已接收检查任务 |
| 输入 | 检查任务ID、检查结果、问题描述、现场图片 |
| 处理 | 更新工件状态，记录检查结果，如有问题则创建问题工单 |
| 输出 | 检查完成确认、问题工单ID（如适用） |
| 异常 | 任务不存在、图片上传失败、状态更新失败 |
| 优先级 | 高 |
| 可追溯性 | UC103 |
3.4 问题工单管理模块
3.4.1 问题工单生成
| 需求ID | F401 |
|---|
| 描述 | 当检查发现问题时自动生成问题工单 |
| 前置条件 | 检查员上报了问题 |
| 输入 | 工件ID、问题类型、问题描述、检查员ID |
| 处理 | 创建问题工单记录，设置初始状态为已生成 |
| 输出 | 问题工单ID、工单详情 |
| 异常 | 工件信息错误、工单创建失败 |
| 优先级 | 高 |
| 可追溯性 | F302 |
3.4.2 维修任务分配
| 需求ID | F402 |
|---|
| 描述 | 调度员将问题工单分配给维修人员 |
| 前置条件 | 存在未分配的问题工单，调度员已登录 |
| 输入 | 问题工单ID、维修人员ID |
| 处理 | 更新工单分配信息，通知维修人员 |
| 输出 | 分配确认、通知结果 |
| 异常 | 工单不存在、维修人员不可用、重复分配 |
| 优先级 | 高 |
| 可追溯性 | UC104 |
3.4.3 维修结果确认
| 需求ID | F403 |
|---|
| 描述 | 维修人员完成维修后上报结果，调度员进行确认 |
| 前置条件 | 维修任务已分配，维修人员已完成维修 |
| 输入 | 工单ID、维修结果、维修图片、维修说明 |
| 处理 | 更新工单状态，记录维修结果，更新工件状态 |
| 输出 | 维修完成确认、工件状态更新 |
| 异常 | 工单状态错误、图片上传失败、状态更新失败 |
| 优先级 | 高 |
| 可追溯性 | UC105 |
3.5 调度管理模块
3.5.1 任务调度总览
| 需求ID | F501 |
|---|
| 描述 | 调度员查看所有待处理的检查和维修任务 |
| 前置条件 | 调度员已登录 |
| 输入 | 查询条件（状态、时间范围、优先级等） |
| 处理 | 查询数据库，汇总任务信息 |
| 输出 | 任务列表、统计信息、优先级排序 |
| 异常 | 数据库查询失败、权限不足 |
| 优先级 | 中 |
| 可追溯性 | UC104 |
3.5.2 自动调度规则
| 需求ID | F502 |
|---|
| 描述 | 系统根据预设规则自动分配检查和维修任务 |
| 前置条件 | 调度规则已配置 |
| 输入 | 任务类型、人员可用性、优先级规则 |
| 处理 | 执行调度算法，自动分配任务 |
| 输出 | 自动分配结果、分配日志 |
| 异常 | 规则配置错误、人员不足、分配冲突 |
| 优先级 | 中 |
| 可追溯性 | UC106 |
3.6 系统管理模块
3.6.1 用户管理
| 需求ID | F601 |
|---|
| 描述 | 管理员进行用户账户的创建、修改、删除 |
| 前置条件 | 管理员已登录且具有用户管理权限 |
| 输入 | 用户信息（用户名、邮箱、角色等） |
| 处理 | 验证输入信息，执行用户管理操作 |
| 输出 | 操作结果确认 |
| 异常 | 权限不足、用户名重复、邮箱格式错误 |
| 优先级 | 中 |
| 可追溯性 | 管理功能用例 |
3.6.2 操作日志记录
| 需求ID | F602 |
|---|
| 描述 | 系统自动记录所有用户操作和系统事件 |
| 前置条件 | 系统正常运行 |
| 输入 | 用户操作、系统事件 |
| 处理 | 记录操作详情到日志表 |
| 输出 | 日志记录ID |
| 异常 | 日志存储失败、磁盘空间不足 |
| 优先级 | 中 |
| 可追溯性 | 所有功能模块 |
3.6.3 系统参数配置
| 需求ID | F603 |
|---|
| 描述 | 管理员配置系统运行参数和业务规则 |
| 前置条件 | 管理员已登录且具有系统配置权限 |
| 输入 | 配置参数名称、参数值 |
| 处理 | 验证参数有效性，更新系统配置 |
| 输出 | 配置更新确认 |
| 异常 | 参数格式错误、配置冲突、权限不足 |
| 优先级 | 低 |
| 可追溯性 | 系统管理用例 |
3.7 轮询检查模块
3.7.1 定时轮询检查
| 需求ID | F701 |
|---|
| 描述 | 系统定时检查工件状态，自动生成检查任务 |
| 前置条件 | 轮询服务已启动，检查规则已配置 |
| 输入 | 轮询间隔、检查规则、工件列表 |
| 处理 | 定时查询数据库，根据规则生成检查任务 |
| 输出 | 新生成的检查任务列表 |
| 异常 | 数据库连接失败、规则配置错误、服务异常 |
| 优先级 | 中 |
| 可追溯性 | UC106 |
3.7.2 手动触发轮询
| 需求ID | F702 |
|---|
| 描述 | 管理员可手动触发系统轮询检查 |
| 前置条件 | 管理员已登录且具有轮询管理权限 |
| 输入 | 轮询触发请求 |
| 处理 | 立即执行轮询检查逻辑 |
| 输出 | 轮询执行结果、生成的任务数量 |
| 异常 | 权限不足、轮询服务异常、并发冲突 |
| 优先级 | 低 |
| 可追溯性 | UC106 |
4. 数据需求
4.1 逻辑数据库设计
- ER 图附后
- 主要实体: Workpiece, WorkpieceMapping, User, AccessLog, Role, IssueTicket
4.2 数据字典示例
Workpiece 工件表workpiece
| 列名 | 类型 | 属性 | 说明 |
|---|
| workpiece_id | int | pk | 工件id |
| workpiece_name | string(255) | | 工件名称 |
| workpiece_description | string(255) | | 工件描述 |
| workpiece_specification | string(255) | | 工件类型 |
| workpiece_manufacturer | string(255) | | 工件厂商 |
| workpiece_status | string(255) | 枚举字符串(已检查checked，未检查unknow，有问题issue) | 工件当前状态 |
| workpiece_last_inspect | datetime | | 工件上一次检查时间 |
| created_by | string(255) | | 数据库记录创建人 |
| created_at | datetime | | 数据库记录创建于 |
| update_by | string(255) | | 数据库记录更新人 |
| update_at | datetime | | 数据库记录更新于 |
InspectTicket 检查任务表inspect_ticket
| 列名 | 类型 | 属性 | 说明 |
|---|
| inspect_id | int | pk | 检查任务id |
| assign_to | int | 默认-1 | 被分配的人，-1为未分配 |
| inspect_type | string(255) | 默认normal | 检查任务的类型 |
| workpiece_id | int | | 工件ID |
| inspect_description | string(255) | | 检查任务的描述 |
| inspect_status | string(255) | 枚举字符串(系统分配system，人工分配admin) | 检查任务的状态 |
| created_by | string(255) | | 数据库记录创建人 |
| created_at | datetime | | 数据库记录创建于 |
| update_by | string(255) | | 数据库记录更新人 |
| update_at | datetime | | 数据库记录更新于 |
WorkpieceMapping 工件图像映射表workpiece_mapping
| 列名 | 类型 | 属性 | 说明 |
|---|
| workpiece_id | int | | 工件id |
| image_id | int | | 图像id |
| resource_url | string(255) | | 图像的url |
| created_by | string(255) | | 数据库记录创建人 |
| created_at | datetime | | 数据库记录创建于 |
| update_by | string(255) | | 数据库记录更新人 |
| update_at | datetime | | 数据库记录更新于 |
User 用户表user
| 列名 | 类型 | 属性 | 说明 |
|---|
| user_id | int | | 用户id |
| username | string(255) | | 用户名 |
| password | string(510) | | 密码 |
| openid | string(255) | | 微信的openid |
| email | string(255) | | 用户邮箱 |
| sms | string(255) | | 用户手机号（收短信的号码） |
| is_active | bool | | 是否激活 |
| is_system | bool | | 是否是系统运维人员 |
| created_by | string(255) | | 数据库记录创建人 |
| created_at | datetime | | 数据库记录创建于 |
| update_by | string(255) | | 数据库记录更新人 |
| update_at | datetime | | 数据库记录更新于 |
AccessLog 动作日志表access_log
| 列名 | 类型 | 属性 | 说明 |
|---|
| action_id | int | | ID |
| action_user | int | | 动作人 |
| action_type | string(255) | | 动作类型 |
| action_result | string(255) | | 动作结果 |
| action_position | string(255) | | 动作位置 |
| action_datetime | string(255) | | 动作时间 |
| action_description | string(255) | | 动作描述 |
| created_by | string(255) | | 数据库记录创建人 |
| created_at | datetime | | 数据库记录创建于 |
| update_by | string(255) | | 数据库记录更新人 |
| update_at | datetime | | 数据库记录更新于 |
IssueTicket 问题工单表issue_ticket
| 列名 | 类型 | 属性 | 说明 |
|---|
| issue_id | int | | 问题ID |
| inspector | int | | 问题检察员（检查出问题的人） |
| dispatcher | int | | 调度员（应该归谁调度） |
| workpiece_id | int | | 工件ID（出问题的ID） |
| issue_status | string(255) | 枚举字符串(已生成generated,已维修repaired,已确认confirmed) | 问题状态 |
| issue_type | string(255) | | 问题类型 |
| issue_description | string(255) | | 问题描述 |
| assign_to | int | 默认-1 | 分配给的维修人（-1为尚未分配） |
| result_action | int | | 对应一个action id |
| created_by | string(255) | | 数据库记录创建人 |
| created_at | datetime | | 数据库记录创建于 |
| update_by | string(255) | | 数据库记录更新人 |
| update_at | datetime | | 数据库记录更新于 |
Role 权限表role
| 列名 | 类型 | 属性 | 说明 |
|---|
| user_id | int | | 用户id |
| scope_list | string(255) | | 权限列表 |
| scope_group | string(255) | | 所属组名称 |
| created_by | string(255) | | 数据库记录创建人 |
| created_at | datetime | | 数据库记录创建于 |
| update_by | string(255) | | 数据库记录更新人 |
| update_at | datetime | | 数据库记录更新于 |
5. 核心用例
5.1 用例 UC101: 用户小程序登录
| 步骤 | 描述 |
|---|
| 1 | 用户使用微信创建用户 |
| 2 | 判断微信用户是否绑定了系统用户 |
| 3 | 将微信用户与系统用户绑定 |
| 4 | 颁发JWT |
5.2 用例UC102：Dashboard登录
| 步骤 | 描述 |
|---|
| 1 | 用户通过用户名密码登录 |
| 2 | 是否涉及F2A |
| 3 | 颁发JWT |
5.3 用例UC103：Inspector检查
| 步骤 | 描述 |
|---|
| 1 | 查看检查任务 |
| 2 | 前往拍照 |
| 3 | 更新检查状态（有问题，无问题） |
5.4 用例UC104：Dispatcher调度
| 步骤 | 描述 |
|---|
| 1 | 查看所有出问题的工件ID |
| 2 | 给一个问题工单分配一个维修人 |
| 3 | 维修人维修完成后确认 |
5.5 用例UC105：维修人维修
5.6 用例UC106：轮询检查
| 步骤 | 描述 |
|---|
| 1 | 定时查询数据库 |
| 2 | 手动触发轮询 |
| 3 | 自动触发前查看上一次触发时间 |
6. 业务流程
6.1 FZ101 维修人员业务流程
-
任务查看：检查人员作为系统基本角色，进入小程序后，可看到调度员分配的检查任务以及自己此前未完成的任务，这些任务在调度员视角可见。
-
任务详情与开启：检查人员点击任务可查看详情，如应前往何处检查哪个工件，点击“开始任务”，任务正式进入检查流程。
-
检查结果处理：
- 无问题情况：检查员到达舱室工件附近检查，若未发现问题，拍一张照片并报告无问题，任务结束。
- 有问题情况：若发现问题，维修人员（此处疑似表述有误，应为检查人员）新建问题工单，上报面临的问题及状况，任务结束。
-
功能差异：检查人员可在Dashboard端登录账号，其主要功能与小程序端大致相同，但Dashboard端无拍照API，因此无法使用与拍照相关功能，在展示内容上需与小程序端有所区别，如Dashboard端不能出现拍照上传功能。
-
接口复用：Dashboard端和小程序端接口可复用，但呈现给用户的内容不一致。
6.2 FZ102 调度人员业务流程
- 任务分配：调度人员即系统业务管理员，并非运维人员，无法直接操作数据库和底层API。主要工作是将检查任务分配给检查员，把维修任务分配给维修员。
- 问题工单处理：若检查人员报告某工件存在问题，调度人员看到该有问题工单后，将其分配给维修人员，分配完成调度员此环节工作结束。
- 维修确认：维修人员完成维修后上传维修完成照片，调度人员需对照片进行确认，确认无误后该工单才算完结。
- 检查作业分配： 调度人员可查看所有的工件信息，并且手动的未某个工件进行检查作业分配。
6.3 FZ103 维修人员业务流程
- 任务查看：维修人员登录小程序后，可查看调度员分配给自己的维修任务，如维修某工件。
- 维修与反馈：前往指定地点完成维修后，拍摄维修完成照片上传至平台，即完成主要维修任务流程。
- 特殊情况：维修任务有可能被打回，但这属于额外情况。维修人员主要功能为查看并执行维修任务、上传维修完成照片。
6.4 FZ104 工件维护的检查周期管理流程
- 检查方式：每个工件都设有检查周期，如每三天需检查一次是否存在问题。检查方式分为两种：
- 系统自动检查：系统通过定时任务，轮巡检查哪些工件的检查周期超过3天。
- 手动分配检查：调度员在发现有工件快到三天检查周期时，手动进行任务分配。
- 工件维护检查周期定时优化：每个工件在手动检查后，会更新检查周期，如每三天检查一次，那么下一次检查时间为当前时间加三天。
6.5 FZ201 权限管理流程
- 权限赋予：调度员作为系统管理员，有权对刚注册、无任何权限或身份的账户手动赋予权限，可将其设定为调度员、管理员、维修人员或检查人员等角色。
- 多角色切换：若一个账户同时拥有调度员、管理员、维修人员、检查人员等多种角色，在UI界面上无需重新登录，即可进行角色切换。
6.6 FZ202 基于图像识别的工件识别管理流程
- 图片资源管理：针对依赖外部API接口的图像识别，需对图片库进行管理。其中图片资源管理方面，可对存储的图片进行筛选。如存储桶内100张图片用于训练，仅20张有用，可删除无用的80张；若有用图片数量不足，可进行添加。
- 图片打分与管理：对每张图片进行打分，以保证识别准确性。例如，由四张图片组合识别一个商品，若其中一张误加入，需将其删除，对组合图片进行有效管理。同时系统需对这部分功能进行监控，涵盖打分、日志及记录等方面。
6.7 FZ301 OAuth2.0登录体系
- 微信登录：采用微信生态登录体系，获取Openid并与后台user ID绑定。
- Dashboard端登录：传统userpass登录体系。适用于Dashboard端登录，可能涉及TOTP问题，系统需保留相应接口。
- 识别方式：userpass方式混用，支持用户名、邮箱、手机号混合。