KnowledgeBase/.kiro/specs/admin-management-features/requirements.md

管理后台功能增强 - 需求文档

项目概述

为知识库系统的Filament管理后台添加三个核心管理功能：系统设置与操作日志、大屏配置管理、SOP模板管理。

功能需求

1. 系统设置与操作日志页面

1.1 用户故事

作为系统管理员，我需要能够配置系统全局参数并查看所有用户的操作审计日志，以便管理系统配置和追踪系统变更。

1.2 功能描述

实现系统全局设置和操作审计日志的前端页面。

1.3 验收标准

• 系统设置页面

  • 嵌入模型配置（模型名称、API密钥、端点URL等）
  • 分块参数默认值（块大小、重叠大小等）
  • 全局参数（系统名称、超时设置等）
  • 配置保存和验证功能

• 操作日志列表

  • 显示字段：时间、用户、操作类型、对象、详情
  • 分页功能
  • 排序功能（按时间倒序）

• 日志筛选功能

  • 时间范围筛选（开始时间、结束时间）
  • 操作类型筛选（创建、更新、删除等）
  • 用户筛选（下拉选择）

• 日志详情弹窗

  • 显示完整操作信息
  • 变更前后数据对比（JSON diff视图）
  • 关联对象信息

• 日志导出功能

  • 支持导出为CSV格式
  • 支持导出为Excel格式
  • 根据当前筛选条件导出

1.4 数据模型需求

• SystemSetting 模型（系统设置）

  • key: string（配置键）
  • value: json（配置值）
  • group: string（配置分组）
  • description: text（配置说明）

• ActivityLog 模型（操作日志）

  • user_id: bigint（操作用户）
  • log_name: string（日志名称）
  • description: text（操作描述）
  • subject_type: string（对象类型）
  • subject_id: bigint（对象ID）
  • causer_type: string（操作者类型）
  • causer_id: bigint（操作者ID）
  • properties: json（变更数据）
  • created_at: timestamp（操作时间）

---

2. 大屏配置管理页面

2.1 用户故事

作为系统管理员，我需要能够管理大屏终端的配置，包括终端绑定、知识库关联和AI提示词设置，以便为不同的生产线站提供定制化的大屏展示。

2.2 功能描述

实现大屏终端配置的前端管理页面，支持终端绑定与提示词编辑。

2.3 验收标准

• 终端列表页

  • 显示在线状态（在线/离线，带状态指示器）
  • 按线站分组显示
  • 终端基本信息（名称、IP地址、最后在线时间）
  • 快速操作按钮（编辑、删除、查看详情）

• 终端配置编辑页

  • 线站绑定（选择生产线和工作站）
  • 组态图URL配置
  • 终端名称和描述
  • 显示参数配置（分辨率、刷新频率等）

• 知识库关联选择器

  • 多选功能
  • 搜索功能（按知识库名称）
  • 显示已选知识库列表
  • 支持拖拽排序优先级

• AI提示词编辑器

  • 使用Monaco Editor（语法高亮）
  • 变量提示功能（{user}, {station}, {time}等）
  • 模板预设选择
  • 实时预览功能

• 配置下发与同步

  • 配置下发按钮
  • 同步状态展示（待同步/同步中/已同步/失败）
  • 同步历史记录
  • 批量配置下发

2.4 数据模型需求

• Terminal 模型（大屏终端）

  • name: string（终端名称）
  • code: string（终端编码）
  • ip_address: string（IP地址）
  • station_id: bigint（线站ID）
  • diagram_url: string（组态图URL）
  • display_config: json（显示配置）
  • is_online: boolean（在线状态）
  • last_online_at: timestamp（最后在线时间）

• TerminalKnowledgeBase 模型（终端知识库关联）

  • terminal_id: bigint（终端ID）
  • knowledge_base_id: bigint（知识库ID）
  • priority: integer（优先级）

• TerminalPrompt 模型（终端提示词）

  • terminal_id: bigint（终端ID）
  • prompt_template: text（提示词模板）
  • variables: json（变量配置）

• TerminalSyncLog 模型（终端同步日志）

  • terminal_id: bigint（终端ID）
  • status: enum（待同步/同步中/已同步/失败）
  • config_snapshot: json（配置快照）
  • synced_at: timestamp（同步时间）
  • error_message: text（错误信息）

2.5 技术依赖

• 需要安装：composer require amidesfahani/filament-monaco-editor

---

3. SOP 模板管理页面

3.1 用户故事

作为内容管理员，我需要能够创建和管理SOP（标准操作程序）模板，包括步骤编辑和交互任务配置，以便为不同的操作场景提供标准化的指导流程。

3.2 功能描述

实现SOP模板与步骤的前端管理页面，支持可视化编辑。

3.3 验收标准

• SOP模板列表页

  • 状态筛选（草稿/已发布/已归档）
  • 分类浏览（按业务分类）
  • 搜索功能（按模板名称、标签）
  • 模板卡片展示（名称、描述、步骤数、状态）

• 模板创建/编辑表单

  • 基本信息（名称、描述、分类、标签）
  • 适用范围（部门、岗位）
  • 版本管理（版本号、变更说明）
  • 状态管理（草稿/发布/归档）

• 步骤可视化编辑器

  • 富文本编辑器（支持图片、表格、代码块）
  • 拖拽排序功能
  • 步骤编号自动更新
  • 步骤折叠/展开
  • 步骤复制/删除

• 交互任务配置组件

  • 任务类型选择（确认、输入、选择、拍照、扫码等）
  • 参数设定（必填项、验证规则、默认值）
  • 条件分支配置
  • 任务超时设置

• 模板预览与发布

  • 预览模式（模拟实际使用场景）
  • 发布前验证（检查必填项、步骤完整性）
  • 发布确认弹窗
  • 版本历史查看

• 模板导入/导出

  • 导出为JSON格式
  • 导出为PDF格式（用于打印）
  • 从JSON导入
  • 批量导入功能

3.4 数据模型需求

• SopTemplate 模型（SOP模板）

  • name: string（模板名称）
  • description: text（模板描述）
  • category: string（分类）
  • tags: json（标签）
  • version: string（版本号）
  • status: enum（草稿/已发布/已归档）
  • applicable_departments: json（适用部门）
  • applicable_positions: json（适用岗位）
  • published_at: timestamp（发布时间）

• SopStep 模型（SOP步骤）

  • sop_template_id: bigint（模板ID）
  • step_number: integer（步骤序号）
  • title: string（步骤标题）
  • content: text（步骤内容，富文本）
  • sort_order: integer（排序）
  • is_required: boolean（是否必需）

• SopInteractiveTask 模型（交互任务）

  • sop_step_id: bigint（步骤ID）
  • task_type: enum（确认/输入/选择/拍照/扫码）
  • task_config: json（任务配置）
  • validation_rules: json（验证规则）
  • timeout_seconds: integer（超时时间）
  • is_required: boolean（是否必需）

• SopTemplateVersion 模型（模板版本）

  • sop_template_id: bigint（模板ID）
  • version: string（版本号）
  • change_log: text（变更说明）
  • content_snapshot: json（内容快照）
  • created_by: bigint（创建人）
  • created_at: timestamp（创建时间）

---

4. 权限管理系统

4.1 用户故事

作为系统管理员，我需要能够灵活地为用户、角色和分组配置不同功能模块的访问权限，以便实现细粒度的权限控制和数据隔离。

4.2 功能描述

实现基于角色、用户和分组的多维度权限管理系统，支持功能模块级和数据级权限控制。

4.3 验收标准

• 角色管理

  • 角色列表（名称、描述、权限数量、用户数量）
  • 角色创建/编辑（名称、描述、权限配置）
  • 角色删除（检查是否有关联用户）
  • 预设角色（超级管理员、管理员、普通用户）

• 权限配置界面

  • 按功能模块分组展示权限
  • 权限类型：viewAny（列表）、view（详情）、create（创建）、update（编辑）、delete（删除）、特殊操作
  • 支持批量授权/撤销
  • 权限继承关系展示

• 用户权限管理

  • 用户角色分配（支持多角色）
  • 用户特殊权限配置（覆盖角色权限）
  • 用户分组关联
  • 权限预览（显示用户的最终权限）

• 分组权限管理

  • 分组数据访问权限（如专用知识库）
  • 分组成员管理
  • 跨分组访问控制

• 权限验证

  • 菜单项根据权限动态显示/隐藏
  • 操作按钮根据权限动态显示/隐藏
  • API请求权限验证
  • 数据查询自动应用权限过滤

4.4 权限模块定义

使用 Spatie Permission 的命名约定（module.action格式）：

• 文档管理：

  • document.viewAny - 查看文档列表
  • document.view - 查看文档详情
  • document.create - 创建文档
  • document.update - 编辑文档
  • document.delete - 删除文档
  • document.download - 下载文档

• 系统设置：

  • system-setting.viewAny - 查看系统设置
  • system-setting.view - 查看设置详情
  • system-setting.update - 修改系统设置

• 操作日志：

  • activity-log.viewAny - 查看操作日志
  • activity-log.view - 查看日志详情
  • activity-log.export - 导出日志

• 终端管理：

  • terminal.viewAny - 查看终端列表
  • terminal.view - 查看终端详情
  • terminal.create - 创建终端
  • terminal.update - 编辑终端
  • terminal.delete - 删除终端
  • terminal.sync - 同步终端配置

• SOP模板：

  • sop-template.viewAny - 查看SOP列表
  • sop-template.view - 查看SOP详情
  • sop-template.create - 创建SOP
  • sop-template.update - 编辑SOP
  • sop-template.delete - 删除SOP
  • sop-template.publish - 发布SOP
  • sop-template.archive - 归档SOP

• 分组管理：

  • group.viewAny - 查看分组列表
  • group.view - 查看分组详情
  • group.create - 创建分组
  • group.update - 编辑分组
  • group.delete - 删除分组

• 用户管理：

  • user.viewAny - 查看用户列表
  • user.view - 查看用户详情
  • user.create - 创建用户
  • user.update - 编辑用户
  • user.delete - 删除用户

• 角色管理：

  • role.viewAny - 查看角色列表
  • role.view - 查看角色详情
  • role.create - 创建角色
  • role.update - 编辑角色
  • role.delete - 删除角色

4.5 数据模型需求

使用 Spatie Laravel Permission 包提供的模型和表结构：

• Role 模型（角色）- 由 Spatie 包提供

  • name: string（角色名称，如 super-admin）
  • guard_name: string（守卫名称，默认 web）
  • 关联关系：belongsToMany(Permission)、belongsToMany(User)

• Permission 模型（权限）- 由 Spatie 包提供

  • name: string（权限名称，如 document.create）
  • guard_name: string（守卫名称，默认 web）
  • 关联关系：belongsToMany(Role)

• model_has_permissions 表（用户直接权限）- 由 Spatie 包提供

  • permission_id: bigint
  • model_type: string（通常是 User）
  • model_id: bigint（用户ID）

• model_has_roles 表（用户角色关联）- 由 Spatie 包提供

  • role_id: bigint
  • model_type: string（通常是 User）
  • model_id: bigint（用户ID）

• role_has_permissions 表（角色权限关联）- 由 Spatie 包提供

  • permission_id: bigint
  • role_id: bigint

注：Spatie 包会自动创建这些表和模型，无需手动创建。

4.6 技术实现

• 使用 Spatie Laravel Permission 包实现权限管理
• 包提供的核心功能：
  • Role（角色）模型和管理
  • Permission（权限）模型和管理
  • 用户角色和权限关联
  • 权限检查方法（hasPermissionTo、hasRole等）
  • 中间件支持（role、permission）
  • Blade指令支持（@role、@can等）
• 使用 Laravel Policy 实现业务逻辑权限验证
• 使用 Gate 定义额外的权限规则
• 在 Filament Resource 中集成权限检查
• 权限缓存自动管理

---

技术栈

• 后端框架: Laravel 12
• 管理面板: Filament 3.x
• 数据库: MySQL 8.0
• 前端组件: Livewire 3.x
• 代码编辑器: Monaco Editor (via filament-monaco-editor)
• 活动日志: spatie/laravel-activitylog

非功能性需求

性能要求

• 操作日志列表页面加载时间 < 2秒
• 大屏配置同步响应时间 < 3秒
• SOP模板预览加载时间 < 1秒

安全要求

• 所有操作需要身份验证
• 敏感配置（API密钥）需要加密存储
• 操作日志不可删除，只能归档
• 权限管理：
  • 支持基于角色的权限控制（RBAC）
  • 支持基于用户的权限控制
  • 支持基于分组的权限控制
  • 功能模块级别的权限控制（查看、创建、编辑、删除、特殊操作）
  • 数据级别的权限控制（如文档的全局/专用访问）

可用性要求

• 界面响应式设计，支持1920x1080及以上分辨率
• 表单验证提供清晰的错误提示
• 关键操作需要二次确认
• 支持键盘快捷键操作

可维护性要求

• 代码遵循Laravel最佳实践
• 使用Filament标准组件
• 数据库迁移文件完整
• 关键功能需要单元测试

依赖项

Composer包

composer require spatie/laravel-activitylog
composer require spatie/laravel-permission  # 权限管理包
composer require amidesfahani/filament-monaco-editor
composer require maatwebsite/excel  # 用于日志导出

数据库表

• system_settings
• activity_log（由 spatie/laravel-activitylog 创建）
• terminals
• terminal_knowledge_bases
• terminal_prompts
• terminal_sync_logs
• sop_templates
• sop_steps
• sop_interactive_tasks
• sop_template_versions
• roles（由 spatie/laravel-permission 创建）
• permissions（由 spatie/laravel-permission 创建）
• model_has_permissions（由 spatie/laravel-permission 创建）
• model_has_roles（由 spatie/laravel-permission 创建）
• role_has_permissions（由 spatie/laravel-permission 创建）

实施优先级

1. 高优先级（第一阶段）

   • 系统设置页面基础功能
   • 操作日志列表和筛选
   • 大屏终端列表和基础配置

2. 中优先级（第二阶段）

   • 日志详情和导出功能
   • 大屏知识库关联和提示词编辑
   • SOP模板列表和基础编辑

3. 低优先级（第三阶段）

   • 配置下发和同步状态
   • SOP步骤可视化编辑器
   • SOP交互任务配置
   • 模板导入/导出功能

验收测试计划

功能测试

• 系统设置保存和读取
• 操作日志记录和查询
• 日志筛选和导出
• 终端配置CRUD操作
• 知识库关联和提示词编辑
• SOP模板CRUD操作
• 步骤编辑和排序
• 模板发布和版本管理

集成测试

• 操作日志自动记录
• 终端配置同步
• SOP模板导入导出

性能测试

• 10000条日志记录的查询性能
• 100个终端的列表加载性能
• 50个步骤的SOP模板编辑性能

风险与限制

技术风险

• Monaco Editor在Filament中的集成可能需要额外配置
• 大屏终端实时同步可能需要WebSocket支持
• 富文本编辑器的内容安全性需要特别注意

业务风险

• SOP模板的版本管理可能导致数据量快速增长
• 操作日志的长期存储需要考虑归档策略
• 大屏配置的实时性要求可能影响系统性能

限制条件

• 本期不包含移动端适配
• 不包含多语言支持
• 不包含高级权限管理（如字段级权限）