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包
```bash
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模板的版本管理可能导致数据量快速增长
- 操作日志的长期存储需要考虑归档策略
- 大屏配置的实时性要求可能影响系统性能

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