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

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