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（创建时间）

---

技术栈

• 后端框架: 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密钥）需要加密存储
• 操作日志不可删除，只能归档
• 权限控制：系统设置仅管理员可访问

可用性要求

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

可维护性要求

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

依赖项

Composer包

composer require spatie/laravel-activitylog
composer require amidesfahani/filament-monaco-editor
composer require maatwebsite/excel  # 用于日志导出

数据库表

• system_settings
• activity_log
• terminals
• terminal_knowledge_bases
• terminal_prompts
• terminal_sync_logs
• sop_templates
• sop_steps
• sop_interactive_tasks
• sop_template_versions

实施优先级

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

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

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

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

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

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

验收测试计划

功能测试

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

集成测试

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

性能测试

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

风险与限制

技术风险

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

业务风险

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

限制条件

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