feat: 新增 Docker 部署支持、Swoole/Octane 集成及相关优化

- 添加 Dockerfile 与多套 docker-compose 配置（开发/生产环境） - 集成 Laravel Octane (Swoole) 提升性能 - 新增健康检查、监控脚本及部署文档 - 新增 Docker 镜像离线导入包（MySQL/Redis/Meilisearch） - 优化文档转换、预览服务及队列任务 - 添加 CreateAdminUser 命令与路由健康检查接口 - 新增 Swoole 队列兼容性测试套件 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-28 15:51:19 +08:00
parent acf549c43c
commit 3c206e9e06
90 changed files with 12731 additions and 1255 deletions
--- a/.kiro/specs/docker-deployment/design.md
+++ b/.kiro/specs/docker-deployment/design.md
@@ -0,0 +1,290 @@
+# Docker部署设计文档
+
+## 概述
+
+本设计文档描述了将Laravel知识库系统Docker化部署到OpenEuler服务器的完整解决方案。系统采用微服务架构，通过Docker容器化技术实现应用的标准化部署和运维。
+
+设计目标：
+- 构建适用于OpenEuler服务器的amd64架构Docker镜像
+- 实现完整的应用栈容器化编排
+- 确保数据持久化和服务高可用性
+- 支持开发和生产环境的不同配置需求
+- 提供便捷的镜像打包和离线部署能力
+
+## 架构
+
+### 整体架构
+
+系统采用多容器架构，包含以下核心组件：
+
+```mermaid
+graph TB
+    subgraph "Docker Host (OpenEuler)"
+        subgraph "Application Stack"
+            nginx[Nginx容器<br/>Web服务器]
+            app[Laravel应用容器<br/>PHP-FPM]
+            queue[队列处理容器<br/>Laravel Queue]
+        end
+        
+        subgraph "Data Layer"
+            mysql[MySQL容器<br/>主数据库]
+            redis[Redis容器<br/>缓存/会话]
+            meilisearch[Meilisearch容器<br/>搜索引擎]
+        end
+        
+        subgraph "Storage"
+            app_data[应用数据卷]
+            db_data[数据库数据卷]
+            search_data[搜索数据卷]
+            logs[日志卷]
+        end
+    end
+    
+    nginx --> app
+    app --> mysql
+    app --> redis
+    app --> meilisearch
+    queue --> mysql
+    queue --> redis
+    
+    app --> app_data
+    mysql --> db_data
+    meilisearch --> search_data
+    nginx --> logs
+    app --> logs
+```
+
+### 网络架构
+
+- **外部网络**: 通过宿主机端口映射提供Web服务访问
+- **内部网络**: 创建专用Docker网络供容器间通信
+- **服务发现**: 通过容器名称进行服务间通信
+
+### 存储架构
+
+- **代码存储**: 项目目录映射到应用容器，支持开发时热重载
+- **数据持久化**: 数据库、搜索引擎、上传文件使用Docker卷持久化
+- **日志管理**: 应用日志映射到宿主机便于监控和调试
+
+## 组件和接口
+
+### Docker镜像组件
+
+#### 1. Laravel应用镜像 (knowledge-base-app)
+- **基础镜像**: php:8.2-fpm-alpine
+- **运行时**: PHP-FPM + Nginx
+- **依赖**: Composer包、NPM构建产物、Pandoc
+- **配置**: PHP扩展、Nginx配置、应用配置
+
+#### 2. 数据库组件 (MySQL)
+- **镜像**: mysql:8.0
+- **配置**: 字符集utf8mb4、时区设置
+- **存储**: 数据目录持久化
+
+#### 3. 缓存组件 (Redis)
+- **镜像**: redis:7-alpine
+- **配置**: 内存限制、持久化策略
+- **用途**: 会话存储、应用缓存、队列存储
+
+#### 4. 搜索组件 (Meilisearch)
+- **镜像**: getmeili/meilisearch:v1.5
+- **配置**: 主密钥、环境模式
+- **存储**: 索引数据持久化
+
+### 服务接口
+
+#### Web服务接口
+- **端口**: 80 (HTTP)
+- **协议**: HTTP/1.1
+- **负载均衡**: Nginx upstream配置
+
+#### 数据库接口
+- **端口**: 3306 (内部)
+- **协议**: MySQL Protocol
+- **连接池**: Laravel数据库连接配置
+
+#### 缓存接口
+- **端口**: 6379 (内部)
+- **协议**: Redis Protocol
+- **连接**: phpredis扩展
+
+#### 搜索接口
+- **端口**: 7700 (内部)
+- **协议**: HTTP REST API
+- **认证**: Master Key
+
+## 数据模型
+
+### 容器配置模型
+
+```yaml
+# docker-compose.yml结构
+services:
+  app:
+    image: knowledge-base-app:latest
+    platform: linux/amd64
+    environment:
+      - APP_ENV=production
+      - DB_HOST=mysql
+      - REDIS_HOST=redis
+      - MEILISEARCH_HOST=http://meilisearch:7700
+    volumes:
+      - ./:/var/www/html
+      - storage_data:/var/www/html/storage
+    depends_on:
+      - mysql
+      - redis
+      - meilisearch
+```
+
+### 环境变量模型
+
+```bash
+# 生产环境变量
+APP_ENV=production
+APP_DEBUG=false
+DB_CONNECTION=mysql
+DB_HOST=mysql
+DB_PORT=3306
+REDIS_HOST=redis
+REDIS_PORT=6379
+MEILISEARCH_HOST=http://meilisearch:7700
+```
+
+### 存储卷模型
+
+```yaml
+volumes:
+  mysql_data:
+    driver: local
+  redis_data:
+    driver: local
+  meilisearch_data:
+    driver: local
+  storage_data:
+    driver: local
+```
+
+## 正确性属性
+
+*属性是应该在系统的所有有效执行中保持为真的特征或行为——本质上是关于系统应该做什么的正式声明。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*
+
+### 属性1: 镜像架构一致性
+*对于任何*构建的Docker镜像，检查其架构信息应该返回linux/amd64
+**验证: 需求 1.1**
+
+### 属性2: PHP环境完整性
+*对于任何*构建的应用镜像，在容器内执行PHP版本检查应该返回8.2.x版本且包含所有必需扩展
+**验证: 需求 1.2**
+
+### 属性3: 构建产物存在性
+*对于任何*构建的应用镜像，vendor目录和public/js、public/css目录应该存在且包含必要文件
+**验证: 需求 1.3**
+
+### 属性4: 服务启动一致性
+*对于任何*docker-compose启动操作，所有定义的服务容器应该成功启动并达到健康状态
+**验证: 需求 2.1, 2.2, 2.3, 2.4, 2.5**
+
+### 属性5: 数据持久化保证
+*对于任何*容器重启操作，持久化存储中的数据应该保持不变且可访问
+**验证: 需求 3.2, 3.3, 3.4**
+
+### 属性6: 服务连接性
+*对于任何*运行中的服务栈，应用容器应该能够成功连接到所有依赖服务
+**验证: 需求 4.2, 4.3, 4.4**
+
+### 属性7: 健康检查响应性
+*对于任何*运行中的服务，健康检查端点应该在合理时间内返回成功响应
+**验证: 需求 5.1, 5.2, 5.3, 5.4**
+
+### 属性8: 容器自愈能力
+*对于任何*模拟的容器故障，系统应该根据重启策略自动恢复服务
+**验证: 需求 5.5**
+
+### 属性9: 镜像导出完整性
+*对于任何*导出的Docker镜像tar文件，应该包含完整的镜像层和元数据信息
+**验证: 需求 6.1**
+
+### 属性10: 镜像导入兼容性
+*对于任何*导出的镜像tar文件，在OpenEuler环境中导入后应该能够正常运行
+**验证: 需求 6.2**
+
+### 属性11: 压缩效率
+*对于任何*镜像压缩操作，压缩后的文件大小应该显著小于原始大小
+**验证: 需求 6.3**
+
+### 属性12: 完整性验证
+*对于任何*镜像文件，完整性检查应该能够验证文件未被损坏且架构正确
+**验证: 需求 6.4**
+
+### 属性13: 开发环境热重载
+*对于任何*开发环境中的代码修改，应用应该在合理时间内反映更改
+**验证: 需求 7.1**
+
+## 错误处理
+
+### 容器启动失败
+- **检测**: 健康检查失败或容器退出
+- **处理**: 自动重启策略，最大重试次数限制
+- **日志**: 详细错误日志记录到宿主机
+
+### 服务连接失败
+- **检测**: 连接超时或拒绝连接
+- **处理**: 重试机制，降级服务
+- **监控**: 连接状态监控和告警
+
+### 数据持久化失败
+- **检测**: 卷挂载失败或权限错误
+- **处理**: 容器启动前预检查
+- **恢复**: 数据备份和恢复机制
+
+### 镜像构建失败
+- **检测**: 构建过程中的错误退出
+- **处理**: 分阶段构建，错误定位
+- **优化**: 构建缓存和依赖管理
+
+## 测试策略
+
+### 单元测试方法
+
+**容器构建测试**:
+- 验证Dockerfile语法正确性
+- 测试构建过程中的关键步骤
+- 检查构建产物的完整性
+
+**配置文件测试**:
+- 验证docker-compose.yml语法
+- 测试环境变量配置的正确性
+- 检查网络和存储配置
+
+**脚本功能测试**:
+- 测试部署脚本的执行流程
+- 验证健康检查脚本的准确性
+- 测试备份和恢复脚本
+
+### 属性测试方法
+
+**测试框架**: 使用Bash脚本结合Docker命令进行属性测试，每个属性测试运行100次迭代以确保可靠性。
+
+**测试环境**: 
+- 本地Docker环境用于开发测试
+- OpenEuler虚拟机用于兼容性测试
+- CI/CD环境用于自动化测试
+
+**测试数据生成**:
+- 随机生成不同的环境配置
+- 模拟各种故障场景
+- 生成不同规模的测试数据
+
+**属性测试实现要求**:
+- 每个正确性属性必须实现为单独的属性测试
+- 测试必须标注对应的设计文档属性编号
+- 使用格式: `# Feature: docker-deployment, Property X: [属性描述]`
+- 每个属性测试最少运行100次迭代
+- 测试应该覆盖各种输入组合和边界条件
+
+**集成测试**:
+- 端到端部署流程测试
+- 服务间通信测试
+- 数据一致性测试
+- 性能基准测试
--- a/.kiro/specs/docker-deployment/requirements.md
+++ b/.kiro/specs/docker-deployment/requirements.md
@@ -0,0 +1,102 @@
+# Docker部署需求文档
+
+## 介绍
+
+本文档定义了将Laravel知识库系统Docker化部署到OpenEuler服务器的需求。系统需要支持完整的生产环境运行，包括Web应用、数据库、缓存、搜索引擎和队列处理等所有组件。
+
+## 术语表
+
+- **Docker镜像**: 包含应用程序及其运行环境的可执行包
+- **容器编排**: 使用docker-compose管理多个相关容器的技术
+- **知识库系统**: 基于Laravel框架的文档管理和搜索系统
+- **OpenEuler服务器**: 目标部署环境的Linux服务器
+- **生产环境**: 实际运行业务的服务器环境
+- **数据持久化**: 确保容器重启后数据不丢失的机制
+- **健康检查**: 监控容器运行状态的机制
+
+## 需求
+
+### 需求1
+
+**用户故事:** 作为系统管理员，我希望能够构建包含完整运行环境的Docker镜像，以便在OpenEuler服务器上部署知识库系统。
+
+#### 验收标准
+
+1. WHEN 构建Docker镜像时 THEN 系统应构建为linux/amd64架构以确保OpenEuler兼容性
+2. WHEN 构建Docker镜像时 THEN 系统应包含PHP 8.2运行环境和所有必需的扩展
+3. WHEN 构建Docker镜像时 THEN 系统应包含Composer依赖和NPM构建产物
+4. WHEN 构建Docker镜像时 THEN 系统应包含Nginx Web服务器配置
+5. WHEN 构建Docker镜像时 THEN 系统应包含文档转换工具Pandoc
+6. WHEN 构建Docker镜像时 THEN 系统应优化镜像大小并使用多阶段构建
+
+### 需求2
+
+**用户故事:** 作为系统管理员，我希望通过docker-compose编排所有服务，以便一键启动完整的应用栈。
+
+#### 验收标准
+
+1. WHEN 启动服务时 THEN 系统应启动MySQL数据库服务并配置持久化存储
+2. WHEN 启动服务时 THEN 系统应启动Redis缓存服务并配置内存限制
+3. WHEN 启动服务时 THEN 系统应启动Meilisearch搜索引擎并配置数据持久化
+4. WHEN 启动服务时 THEN 系统应启动Laravel应用容器并连接所有依赖服务
+5. WHEN 启动服务时 THEN 系统应启动队列处理容器处理后台任务
+
+### 需求3
+
+**用户故事:** 作为系统管理员，我希望配置数据持久化和目录映射，以便数据在容器重启后不丢失。
+
+#### 验收标准
+
+1. WHEN 配置存储时 THEN 系统应将项目代码目录映射到容器内部
+2. WHEN 配置存储时 THEN 系统应将上传文档存储目录持久化到宿主机
+3. WHEN 配置存储时 THEN 系统应将数据库数据目录持久化到宿主机
+4. WHEN 配置存储时 THEN 系统应将搜索引擎数据目录持久化到宿主机
+5. WHEN 配置存储时 THEN 系统应将日志目录映射到宿主机便于查看
+
+### 需求4
+
+**用户故事:** 作为系统管理员，我希望配置环境变量和网络，以便服务间能够正确通信。
+
+#### 验收标准
+
+1. WHEN 配置网络时 THEN 系统应创建专用Docker网络供服务间通信
+2. WHEN 配置环境时 THEN 系统应设置数据库连接参数指向MySQL容器
+3. WHEN 配置环境时 THEN 系统应设置Redis连接参数指向Redis容器
+4. WHEN 配置环境时 THEN 系统应设置Meilisearch连接参数指向搜索容器
+5. WHEN 配置环境时 THEN 系统应配置应用密钥和调试模式
+
+### 需求5
+
+**用户故事:** 作为系统管理员，我希望实现健康检查和自动重启，以便确保服务的高可用性。
+
+#### 验收标准
+
+1. WHEN 服务运行时 THEN 系统应对Web应用进行HTTP健康检查
+2. WHEN 服务运行时 THEN 系统应对数据库进行连接健康检查
+3. WHEN 服务运行时 THEN 系统应对Redis进行连接健康检查
+4. WHEN 服务运行时 THEN 系统应对Meilisearch进行API健康检查
+5. WHEN 服务异常时 THEN 系统应自动重启失败的容器
+
+### 需求6
+
+**用户故事:** 作为系统管理员，我希望能够导出和导入Docker镜像，以便在离线环境中部署。
+
+#### 验收标准
+
+1. WHEN 导出镜像时 THEN 系统应将构建好的amd64架构镜像打包为tar文件
+2. WHEN 导入镜像时 THEN 系统应能够从tar文件加载镜像到OpenEuler服务器的Docker
+3. WHEN 传输镜像时 THEN 系统应支持压缩以减少文件大小
+4. WHEN 验证镜像时 THEN 系统应提供镜像完整性和架构兼容性检查方法
+5. WHEN 部署镜像时 THEN 系统应提供详细的OpenEuler部署文档和脚本
+
+### 需求7
+
+**用户故事:** 作为开发人员，我希望有开发环境的Docker配置，以便本地开发和测试。
+
+#### 验收标准
+
+1. WHEN 开发环境启动时 THEN 系统应启用代码热重载功能
+2. WHEN 开发环境启动时 THEN 系统应启用调试模式和详细日志
+3. WHEN 开发环境启动时 THEN 系统应映射源代码目录支持实时编辑
+4. WHEN 开发环境启动时 THEN 系统应暴露所有必要的端口供调试
+5. WHEN 开发环境启动时 THEN 系统应包含开发工具和测试数据
--- a/.kiro/specs/docker-deployment/tasks.md
+++ b/.kiro/specs/docker-deployment/tasks.md
@@ -0,0 +1,157 @@
+# Docker部署实施计划
+
+- [x] 1. 创建Docker镜像构建配置
+  - 创建多阶段Dockerfile，优化镜像大小
+  - 配置PHP 8.2-fpm基础环境和必需扩展
+  - 安装Composer依赖和NPM构建工具
+  - 集成Nginx Web服务器配置
+  - 安装Pandoc文档转换工具
+  - 确保构建为linux/amd64架构
+  - _需求: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6_
+
+- [ ]* 1.1 编写属性测试验证镜像架构
+  - **属性1: 镜像架构一致性**
+  - **验证: 需求 1.1**
+
+- [ ]* 1.2 编写属性测试验证PHP环境
+  - **属性2: PHP环境完整性**
+  - **验证: 需求 1.2**
+
+- [ ]* 1.3 编写属性测试验证构建产物
+  - **属性3: 构建产物存在性**
+  - **验证: 需求 1.3**
+
+- [x] 2. 配置生产环境容器编排
+  - 创建生产环境docker-compose.yml文件
+  - 配置MySQL数据库服务和持久化存储
+  - 配置Redis缓存服务和内存限制
+  - 配置Meilisearch搜索引擎和数据持久化
+  - 配置Laravel应用容器和队列处理容器
+  - 设置服务间依赖关系和启动顺序
+  - _需求: 2.1, 2.2, 2.3, 2.4, 2.5_
+
+- [ ]* 2.1 编写属性测试验证服务启动
+  - **属性4: 服务启动一致性**
+  - **验证: 需求 2.1, 2.2, 2.3, 2.4, 2.5**
+
+- [x] 3. 实现数据持久化和目录映射
+  - 配置项目代码目录映射到容器
+  - 设置上传文档存储目录持久化
+  - 配置数据库数据目录持久化
+  - 设置搜索引擎数据目录持久化
+  - 配置日志目录映射到宿主机
+  - _需求: 3.1, 3.2, 3.3, 3.4, 3.5_
+
+- [ ]* 3.1 编写属性测试验证数据持久化
+  - **属性5: 数据持久化保证**
+  - **验证: 需求 3.2, 3.3, 3.4**
+
+- [x] 4. 配置环境变量和网络设置
+  - 创建专用Docker网络配置
+  - 设置数据库连接环境变量
+  - 配置Redis连接参数
+  - 设置Meilisearch连接参数
+  - 配置应用密钥和运行模式
+  - _需求: 4.1, 4.2, 4.3, 4.4, 4.5_
+
+- [ ]* 4.1 编写属性测试验证服务连接
+  - **属性6: 服务连接性**
+  - **验证: 需求 4.2, 4.3, 4.4**
+
+- [x] 5. 实现健康检查和自动重启机制
+  - 配置Web应用HTTP健康检查
+  - 实现数据库连接健康检查
+  - 配置Redis连接健康检查
+  - 设置Meilisearch API健康检查
+  - 配置容器自动重启策略
+  - _需求: 5.1, 5.2, 5.3, 5.4, 5.5_
+
+- [ ]* 5.1 编写属性测试验证健康检查
+  - **属性7: 健康检查响应性**
+  - **验证: 需求 5.1, 5.2, 5.3, 5.4**
+
+- [ ]* 5.2 编写属性测试验证自动重启
+  - **属性8: 容器自愈能力**
+  - **验证: 需求 5.5**
+
+- [x] 6. 创建镜像打包和部署脚本
+  - 编写Docker镜像导出脚本
+  - 实现镜像压缩和完整性检查
+  - 创建OpenEuler服务器部署脚本
+  - 编写镜像导入和验证脚本
+  - 生成详细的部署文档
+  - _需求: 6.1, 6.2, 6.3, 6.4, 6.5_
+
+- [ ]* 6.1 编写属性测试验证镜像导出
+  - **属性9: 镜像导出完整性**
+  - **验证: 需求 6.1**
+
+- [ ]* 6.2 编写属性测试验证镜像导入
+  - **属性10: 镜像导入兼容性**
+  - **验证: 需求 6.2**
+
+- [ ]* 6.3 编写属性测试验证压缩效率
+  - **属性11: 压缩效率**
+  - **验证: 需求 6.3**
+
+- [ ]* 6.4 编写属性测试验证完整性检查
+  - **属性12: 完整性验证**
+  - **验证: 需求 6.4**
+
+- [ ] 7. 配置开发环境支持
+  - 创建开发环境docker-compose.dev.yml
+  - 配置代码热重载功能
+  - 启用调试模式和详细日志
+  - 设置开发工具和测试数据
+  - 配置端口映射供调试使用
+  - _需求: 7.1, 7.2, 7.3, 7.4, 7.5_
+
+- [ ]* 7.1 编写属性测试验证热重载
+  - **属性13: 开发环境热重载**
+  - **验证: 需求 7.1**
+
+- [ ] 8. 创建Nginx配置文件
+  - 编写生产环境Nginx配置
+  - 配置PHP-FPM upstream
+  - 设置静态文件服务
+  - 配置日志格式和路径
+  - 优化性能参数
+  - _需求: 1.4_
+
+- [ ] 9. 编写环境配置模板
+  - 创建生产环境.env模板
+  - 创建开发环境.env模板
+  - 配置数据库连接参数
+  - 设置缓存和搜索服务配置
+  - 添加配置说明文档
+  - _需求: 4.2, 4.3, 4.4, 4.5_
+
+- [ ] 10. 实现启动和管理脚本
+  - 编写一键启动脚本
+  - 创建服务状态检查脚本
+  - 实现日志查看脚本
+  - 编写数据备份脚本
+  - 创建清理和重置脚本
+  - _需求: 2.1, 2.2, 2.3, 2.4, 2.5_
+
+- [ ] 11. 第一次检查点 - 确保所有测试通过
+  - 确保所有测试通过，如有问题请询问用户
+
+- [ ] 12. 创建部署文档
+  - 编写OpenEuler服务器环境准备指南
+  - 创建Docker安装和配置文档
+  - 编写应用部署步骤说明
+  - 添加故障排除指南
+  - 创建运维管理文档
+  - _需求: 6.5_
+
+- [ ] 13. 优化和安全配置
+  - 配置容器安全策略
+  - 设置资源限制和配额
+  - 实现日志轮转和清理
+  - 配置网络安全规则
+  - 添加监控和告警配置
+  - _需求: 2.2, 5.1, 5.2, 5.3, 5.4_
+
+- [ ] 14. 最终检查点 - 确保所有测试通过
+  - 确保所有测试通过，如有问题请询问用户
--- a/.kiro/specs/swoole-integration/design.md
+++ b/.kiro/specs/swoole-integration/design.md
@@ -0,0 +1,300 @@
+# 设计文档 - Swoole 集成
+
+## 概述
+
+本设计文档详细描述了将 Laravel 知识库系统从传统的 PHP-FPM + Nginx 架构迁移到基于 Swoole 的高性能异步架构的技术方案。通过集成 Laravel Octane 和 Swoole，系统将获得显著的性能提升和更好的并发处理能力。
+
+## 架构
+
+### 当前架构 vs 目标架构
+
+**当前架构:**
+```
+请求 → Nginx → PHP-FPM → Laravel 应用
+```
+
+**目标架构:**
+```
+请求 → Swoole HTTP Server → Laravel 应用 (内存驻留)
+```
+
+### 系统架构图
+
+```mermaid
+graph TB
+    subgraph "Docker 容器"
+        subgraph "应用容器 (新架构)"
+            A[Swoole HTTP Server] --> B[Laravel Octane]
+            B --> C[Laravel 应用]
+            D[队列工作进程] --> C
+            E[定时任务] --> C
+        end
+        
+        subgraph "数据层"
+            F[MySQL 容器]
+            G[Redis 容器]
+            H[Meilisearch 容器]
+        end
+    end
+    
+    I[客户端请求] --> A
+    C --> F
+    C --> G
+    C --> H
+    
+    style A fill:#e1f5fe
+    style B fill:#f3e5f5
+    style C fill:#e8f5e8
+```
+
+## 组件和接口
+
+### 简化的集成方案
+
+**核心原则**: 最小化代码修改，最大化利用 Laravel Octane 的默认配置和行为。
+
+### 1. Laravel Octane 包
+
+**使用现有组件:**
+- 直接使用 `laravel/octane` 包，无需自定义接口
+- 使用默认的 Swoole 配置，仅调整必要参数
+- 利用 Octane 的内置命令和服务管理
+
+**配置方式:**
+```php
+// config/octane.php (Laravel Octane 默认配置文件)
+return [
+    'server' => 'swoole',
+    'host' => env('OCTANE_HOST', '0.0.0.0'),
+    'port' => env('OCTANE_PORT', 8000),
+    'workers' => env('OCTANE_WORKERS', 4),
+    'task_workers' => env('OCTANE_TASK_WORKERS', 2),
+    'max_requests' => env('OCTANE_MAX_REQUESTS', 500),
+];
+```
+
+### 2. 现有代码兼容性
+
+**无需修改的组件:**
+- 现有的 Controllers、Models、Services 保持不变
+- 队列处理逻辑无需修改
+- 数据库连接和缓存逻辑保持原样
+- Filament 管理界面无需调整
+
+**需要注意的事项:**
+- 避免使用全局变量和静态变量
+- 确保单例服务的正确重置
+- 检查文件上传和会话处理
+
+## 数据模型
+
+### 简化的配置模型
+
+**使用环境变量配置 (无需新建模型类):**
+
+```bash
+# .env 文件中的 Swoole 相关配置
+OCTANE_SERVER=swoole
+OCTANE_HOST=0.0.0.0
+OCTANE_PORT=8000
+OCTANE_WORKERS=4
+OCTANE_TASK_WORKERS=2
+OCTANE_MAX_REQUESTS=500
+OCTANE_WATCH=false
+```
+
+**现有模型保持不变:**
+- Document 模型
+- User 模型  
+- Group 模型
+- DownloadLog 模型
+
+所有现有的 Eloquent 模型和数据库操作保持完全不变，Swoole 集成是透明的。
+
+## 正确性属性
+
+现在我需要使用 prework 工具来分析验收标准的可测试性：
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### 服务器启动和运行属性
+
+**属性 1: Swoole 服务器启动一致性**
+*对于任何* 有效的配置参数，当系统启动时，应该能够检测到 Swoole HTTP 服务器进程在运行并监听指定端口
+**验证: 需求 1.1**
+
+**属性 2: HTTP 请求处理一致性**
+*对于任何* 有效的 HTTP 请求，Swoole 服务器应该能够处理请求并返回适当的响应
+**验证: 需求 1.2**
+
+**属性 3: 内存驻留持久性**
+*对于任何* 运行中的 Swoole 服务器，应用进程应该保持内存驻留状态，不会在请求间重新初始化
+**验证: 需求 1.3**
+
+### 命令行接口属性
+
+**属性 4: Artisan 命令执行一致性**
+*对于任何* 有效的 Octane 命令参数，php artisan octane 命令应该正确执行相应的服务器操作
+**验证: 需求 2.1, 2.4, 2.5**
+
+**属性 5: 端口配置正确性**
+*对于任何* 指定的有效端口号，Swoole 服务器应该在该端口上启动并接受连接
+**验证: 需求 2.2**
+
+**属性 6: 工作进程数量一致性**
+*对于任何* 指定的工作进程数量，Swoole 服务器应该创建相应数量的工作进程
+**验证: 需求 2.3**
+
+### Docker 集成属性
+
+**属性 7: Swoole 扩展安装完整性**
+*对于任何* 构建的 Docker 镜像，应该包含正确安装和配置的 Swoole PHP 扩展
+**验证: 需求 3.1**
+
+**属性 8: 容器进程替换正确性**
+*对于任何* 启动的应用容器，应该运行 Swoole 进程而不是 PHP-FPM 或 Nginx 进程
+**验证: 需求 3.2**
+
+**属性 9: 容器端口暴露正确性**
+*对于任何* 配置的 Swoole 服务端口，容器应该正确暴露该端口供外部访问
+**验证: 需求 3.3**
+
+### 队列处理属性
+
+**属性 10: 队列处理兼容性**
+*对于任何* 队列任务，在 Swoole 环境下应该能够正常处理，与传统环境行为一致
+**验证: 需求 4.1, 4.2**
+
+**属性 11: 队列监听器自动启动**
+*对于任何* 系统启动，队列监听器应该自动启动并保持运行状态
+**验证: 需求 4.3**
+
+**属性 12: 队列错误处理一致性**
+*对于任何* 失败的队列任务，系统应该记录错误信息并按配置进行重试
+**验证: 需求 4.4**
+
+### 系统稳定性属性
+
+**属性 13: 高并发处理稳定性**
+*对于任何* 高并发请求负载，Swoole 服务器应该保持稳定运行而不崩溃
+**验证: 需求 5.1**
+
+**属性 14: 内存使用稳定性**
+*对于任何* 长时间运行的系统，内存使用应该保持在合理范围内，不出现持续增长
+**验证: 需求 5.2**
+
+**属性 15: 健康检查响应一致性**
+*对于任何* 健康检查请求，系统应该返回正确的健康状态信息
+**验证: 需求 5.4**
+
+### 部署和配置属性
+
+**属性 16: 部署脚本镜像构建正确性**
+*对于任何* 执行的部署脚本，应该生成包含 Swoole 配置的有效 Docker 镜像
+**验证: 需求 6.1**
+
+**属性 17: 配置文件更新正确性**
+*对于任何* 更新的 docker-compose 配置，应该正确移除 Nginx 依赖并配置 Swoole 服务
+**验证: 需求 6.2**
+
+**属性 18: 环境变量配置生效性**
+*对于任何* 设置的 Swoole 相关环境变量，应该在系统运行时正确生效
+**验证: 需求 6.3**
+
+## 错误处理
+
+### 简化的错误处理策略
+
+**利用 Laravel Octane 内置错误处理:**
+- 使用 Octane 的默认异常处理机制
+- 利用 Laravel 现有的日志系统
+- 保持现有的错误报告和监控
+
+**最小化自定义错误处理:**
+```php
+// 仅在必要时添加 Swoole 特定的错误处理
+// 在 app/Exceptions/Handler.php 中添加
+public function register()
+{
+    $this->reportable(function (Throwable $e) {
+        if (app()->bound('octane')) {
+            // 记录 Swoole 相关错误
+            Log::channel('swoole')->error('Swoole error: ' . $e->getMessage());
+        }
+    });
+}
+```
+
+**依赖现有机制:**
+- 使用现有的队列失败处理
+- 保持现有的数据库连接错误处理
+- 利用现有的缓存错误恢复机制
+
+## 测试策略
+
+### 双重测试方法
+
+本项目将采用单元测试和基于属性的测试相结合的方法：
+
+- **单元测试**: 验证具体的功能实现和边界条件
+- **基于属性的测试**: 验证系统在各种输入下的通用属性
+
+### 单元测试覆盖
+
+单元测试将覆盖：
+- Octane 配置加载和验证
+- Swoole 服务器启动和停止
+- 命令行接口功能
+- 错误处理逻辑
+- 队列集成功能
+
+### 基于属性的测试
+
+将使用 **Pest** 作为基于属性的测试框架，配置每个属性测试运行最少 100 次迭代。
+
+每个基于属性的测试必须：
+- 使用注释明确标识对应的设计文档属性
+- 使用格式: `**Feature: swoole-integration, Property {number}: {property_text}**`
+- 生成合适的测试数据来验证属性
+- 验证系统在各种输入条件下的行为一致性
+
+### 测试环境配置
+
+```php
+// 测试配置示例
+return [
+    'octane' => [
+        'server' => 'swoole',
+        'host' => '127.0.0.1',
+        'port' => 8000,
+        'workers' => 2,
+        'task_workers' => 1,
+        'max_requests' => 100,
+    ],
+    'swoole' => [
+        'options' => [
+            'log_file' => storage_path('logs/swoole.log'),
+            'log_level' => SWOOLE_LOG_INFO,
+        ],
+    ],
+];
+```
+
+### 性能测试
+
+除了功能测试外，还需要进行性能测试：
+- 并发请求处理能力测试
+- 内存使用监控测试
+- 响应时间分布测试
+- 长时间运行稳定性测试
+
+### 集成测试
+
+集成测试将验证：
+- Docker 容器间的通信
+- 数据库连接池管理
+- 缓存系统集成
+- 搜索服务集成
+- 队列系统集成
+
+这些测试确保 Swoole 集成不会破坏现有的系统功能，同时提供预期的性能改进。
--- a/.kiro/specs/swoole-integration/requirements.md
+++ b/.kiro/specs/swoole-integration/requirements.md
@@ -0,0 +1,87 @@
+# 需求文档 - Swoole 集成
+
+## 介绍
+
+本规范旨在将现有的 Laravel 知识库系统从传统的 PHP-FPM + Nginx 架构迁移到使用 Swoole 的高性能异步架构。Swoole 是一个高性能的 PHP 异步网络通信引擎，能够显著提升应用性能和并发处理能力。
+
+## 术语表
+
+- **Swoole**: 高性能的 PHP 异步网络通信引擎
+- **Laravel_Octane**: Laravel 官方的高性能应用服务器包，支持 Swoole 和 RoadRunner
+- **PHP_Artisan**: Laravel 的命令行工具
+- **Docker_Container**: 应用程序的容器化运行环境
+- **Hot_Reload**: 代码变更时自动重启服务的功能
+
+## 需求
+
+### 需求 1
+
+**用户故事:** 作为系统管理员，我希望使用 Swoole 替代传统的 PHP-FPM 运行方式，以便获得更高的性能和并发处理能力。
+
+#### 验收标准
+
+1. WHEN 系统启动时 THEN Laravel_Octane SHALL 使用 Swoole 驱动启动 HTTP 服务器
+2. WHEN 接收 HTTP 请求时 THEN Swoole_Server SHALL 处理请求并返回响应
+3. WHEN 系统运行时 THEN Swoole_Server SHALL 维持长连接和内存驻留
+4. WHEN 配置变更时 THEN 系统 SHALL 支持热重载功能
+5. WHEN 监控系统性能时 THEN Swoole_Server SHALL 提供性能指标接口
+
+### 需求 2
+
+**用户故事:** 作为开发人员，我希望通过 php artisan 命令启动 Swoole 服务，以便保持与 Laravel 生态系统的一致性。
+
+#### 验收标准
+
+1. WHEN 执行启动命令时 THEN php artisan octane:start SHALL 启动 Swoole 服务器
+2. WHEN 指定端口参数时 THEN 系统 SHALL 在指定端口上启动服务
+3. WHEN 指定工作进程数时 THEN Swoole_Server SHALL 创建指定数量的工作进程
+4. WHEN 执行停止命令时 THEN php artisan octane:stop SHALL 优雅关闭服务器
+5. WHEN 执行重启命令时 THEN php artisan octane:restart SHALL 重启服务器
+
+### 需求 3
+
+**用户故事:** 作为运维人员，我希望更新 Docker 镜像配置，以便支持 Swoole 运行环境和相关依赖。
+
+#### 验收标准
+
+1. WHEN 构建 Docker 镜像时 THEN 系统 SHALL 安装 Swoole PHP 扩展
+2. WHEN 容器启动时 THEN 系统 SHALL 使用 Swoole 替代 PHP-FPM 和 Nginx
+3. WHEN 配置容器时 THEN 系统 SHALL 暴露 Swoole 服务端口
+4. WHEN 容器运行时 THEN 系统 SHALL 支持进程管理和监控
+5. WHEN 容器重启时 THEN 系统 SHALL 自动恢复 Swoole 服务
+
+### 需求 4
+
+**用户故事:** 作为系统架构师，我希望保持现有的队列处理和后台任务功能，以便确保系统功能完整性。
+
+#### 验收标准
+
+1. WHEN Swoole 服务运行时 THEN 队列处理器 SHALL 继续正常工作
+2. WHEN 处理文档转换任务时 THEN 后台队列 SHALL 正常执行任务
+3. WHEN 系统启动时 THEN 队列监听器 SHALL 自动启动
+4. WHEN 队列任务失败时 THEN 系统 SHALL 记录错误并支持重试
+5. WHEN 监控队列状态时 THEN 系统 SHALL 提供队列健康检查接口
+
+### 需求 5
+
+**用户故事:** 作为质量保证工程师，我希望验证 Swoole 集成后的系统稳定性，以便确保生产环境的可靠性。
+
+#### 验收标准
+
+1. WHEN 系统负载测试时 THEN Swoole_Server SHALL 处理高并发请求而不崩溃
+2. WHEN 长时间运行时 THEN 系统 SHALL 保持内存使用稳定
+3. WHEN 发生异常时 THEN Swoole_Server SHALL 记录详细错误日志
+4. WHEN 进行健康检查时 THEN 系统 SHALL 响应健康检查请求
+5. WHEN 系统重启时 THEN 所有服务 SHALL 在合理时间内恢复正常
+
+### 需求 6
+
+**用户故事:** 作为部署工程师，我希望更新部署脚本和配置，以便支持新的 Swoole 架构部署。
+
+#### 验收标准
+
+1. WHEN 执行部署脚本时 THEN 系统 SHALL 构建包含 Swoole 的新镜像
+2. WHEN 更新 docker-compose 配置时 THEN 系统 SHALL 移除 Nginx 容器依赖
+3. WHEN 配置环境变量时 THEN 系统 SHALL 支持 Swoole 相关配置参数
+4. WHEN 验证部署时 THEN 系统 SHALL 确认 Swoole 服务正常运行
+5. WHEN 回滚部署时 THEN 系统 SHALL 支持回退到之前的架构
--- a/.kiro/specs/swoole-integration/tasks.md
+++ b/.kiro/specs/swoole-integration/tasks.md
@@ -0,0 +1,185 @@
+# 实施计划 - Swoole 集成
+
+## 概述
+
+本实施计划将现有的 Laravel 知识库系统从 PHP-FPM + Nginx 架构迁移到基于 Swoole 的高性能架构。采用最小化代码修改的策略，主要通过安装 Laravel Octane 包和更新配置来实现。
+
+## 任务列表
+
+- [x] 1. 安装和配置 Laravel Octane
+  - 安装 laravel/octane 包
+  - 发布 Octane 配置文件
+  - 配置 Swoole 相关环境变量
+  - _需求: 1.1, 2.1_
+
+- [ ]* 1.1 编写 Octane 启动测试
+  - **属性 1: Swoole 服务器启动一致性**
+  - **验证: 需求 1.1**
+
+- [ ]* 1.2 编写命令行接口测试
+  - **属性 4: Artisan 命令执行一致性**
+  - **验证: 需求 2.1, 2.4, 2.5**
+
+- [x] 2. 更新 Composer 依赖
+  - 添加 laravel/octane 到 composer.json
+  - 安装 Swoole PHP 扩展依赖
+  - 更新 composer 脚本以支持 Swoole 启动
+  - _需求: 1.1, 2.1_
+
+- [ ]* 2.1 编写依赖安装验证测试
+  - **属性 7: Swoole 扩展安装完整性**
+  - **验证: 需求 3.1**
+
+- [ ] 3. 更新 Docker 配置
+  - 修改 Dockerfile 安装 Swoole 扩展
+  - 移除 Nginx 和 PHP-FPM 相关配置
+  - 更新容器启动命令使用 Octane
+  - 调整端口映射配置
+  - _需求: 3.1, 3.2, 3.3_
+
+- [ ]* 3.1 编写 Docker 镜像验证测试
+  - **属性 8: 容器进程替换正确性**
+  - **验证: 需求 3.2**
+
+- [ ]* 3.2 编写端口配置测试
+  - **属性 5: 端口配置正确性**
+  - **属性 9: 容器端口暴露正确性**
+  - **验证: 需求 2.2, 3.3**
+
+- [x] 4. 更新 docker-compose.yml
+  - 移除 Nginx 服务配置
+  - 更新应用服务使用 Swoole 端口
+  - 调整服务依赖关系
+  - 更新健康检查配置
+  - _需求: 3.2, 6.2_
+
+- [ ]* 4.1 编写 docker-compose 配置验证测试
+  - **属性 17: 配置文件更新正确性**
+  - **验证: 需求 6.2**
+
+- [x] 5. 配置环境变量
+  - 更新 .env 文件添加 Octane 配置
+  - 设置 Swoole 工作进程数量
+  - 配置最大请求数和其他性能参数
+  - _需求: 1.4, 2.2, 2.3, 6.3_
+
+- [ ]* 5.1 编写环境变量配置测试
+  - **属性 6: 工作进程数量一致性**
+  - **属性 18: 环境变量配置生效性**
+  - **验证: 需求 2.3, 6.3**
+
+- [x] 6. 验证队列系统兼容性
+  - 测试现有队列任务在 Swoole 环境下的运行
+  - 验证文档转换队列功能
+  - 确认队列监听器自动启动
+  - _需求: 4.1, 4.2, 4.3_
+
+- [ ]* 6.1 编写队列兼容性测试
+  - **属性 10: 队列处理兼容性**
+  - **属性 11: 队列监听器自动启动**
+  - **验证: 需求 4.1, 4.2, 4.3**
+
+- [ ]* 6.2 编写队列错误处理测试
+  - **属性 12: 队列错误处理一致性**
+  - **验证: 需求 4.4**
+
+- [ ] 7. 更新部署脚本
+  - 修改 Docker 镜像构建脚本
+  - 更新部署验证脚本
+  - 调整健康检查脚本
+  - _需求: 6.1, 6.4_
+
+- [ ]* 7.1 编写部署脚本验证测试
+  - **属性 16: 部署脚本镜像构建正确性**
+  - **验证: 需求 6.1**
+
+- [ ] 8. 第一次检查点 - 确保所有测试通过
+  - 确保所有测试通过，如有问题请询问用户
+
+- [ ] 9. 性能和稳定性测试
+  - 配置负载测试环境
+  - 执行并发请求测试
+  - 监控内存使用情况
+  - 验证长时间运行稳定性
+  - _需求: 5.1, 5.2_
+
+- [ ]* 9.1 编写性能测试
+  - **属性 13: 高并发处理稳定性**
+  - **属性 14: 内存使用稳定性**
+  - **验证: 需求 5.1, 5.2**
+
+- [ ] 10. 健康检查和监控
+  - 实现 Swoole 服务健康检查接口
+  - 配置系统监控和告警
+  - 验证错误日志记录功能
+  - _需求: 5.3, 5.4_
+
+- [ ]* 10.1 编写健康检查测试
+  - **属性 15: 健康检查响应一致性**
+  - **验证: 需求 5.4**
+
+- [ ] 11. 文档更新
+  - 更新部署指南
+  - 更新运维文档
+  - 创建 Swoole 配置说明
+  - _需求: 6.4_
+
+- [ ] 12. 回滚机制准备
+  - 准备回滚到原架构的脚本
+  - 测试回滚流程
+  - 文档化回滚步骤
+  - _需求: 6.5_
+
+- [ ]* 12.1 编写回滚功能测试
+  - 验证回滚机制的正确性
+  - _需求: 6.5_
+
+- [ ] 13. 最终检查点 - 确保所有测试通过
+  - 确保所有测试通过，如有问题请询问用户
+
+## 实施注意事项
+
+### 最小化代码修改原则
+
+1. **保持现有代码不变**: 所有 Controllers、Models、Services 保持原样
+2. **利用 Laravel Octane 默认配置**: 避免自定义复杂的配置逻辑
+3. **渐进式迁移**: 先在开发环境验证，再部署到生产环境
+4. **保留回滚能力**: 确保可以快速回退到原有架构
+
+### 关键配置参数
+
+```bash
+# 核心 Swoole 配置
+OCTANE_SERVER=swoole
+OCTANE_HOST=0.0.0.0
+OCTANE_PORT=8000
+OCTANE_WORKERS=4
+OCTANE_TASK_WORKERS=2
+OCTANE_MAX_REQUESTS=500
+```
+
+### 验证检查清单
+
+- [ ] Swoole 扩展正确安装
+- [ ] Octane 命令正常工作
+- [ ] HTTP 请求正确处理
+- [ ] 队列任务正常执行
+- [ ] 数据库连接稳定
+- [ ] 缓存系统正常
+- [ ] 搜索功能可用
+- [ ] 文件上传下载正常
+- [ ] 性能指标符合预期
+
+### 性能预期
+
+- **响应时间**: 比原架构提升 30-50%
+- **并发处理**: 支持更高的并发连接数
+- **内存使用**: 更高效的内存利用
+- **CPU 使用**: 更好的 CPU 利用率
+
+### 风险缓解
+
+1. **充分测试**: 在开发环境完整测试所有功能
+2. **分阶段部署**: 先部署到测试环境，再到生产环境
+3. **监控告警**: 部署后密切监控系统指标
+4. **快速回滚**: 准备好快速回滚方案
--- a/.kiro/specs/ui-enhancement/design.md
+++ b/.kiro/specs/ui-enhancement/design.md
@@ -1,484 +0,0 @@
-# 设计文档
-
-## 概述
-
-本设计文档描述了知识库系统UI界面美化的技术实现方案。通过集成Alpine.js和Tailwind CSS，我们将为现有的Filament界面添加现代化的视觉效果和流畅的交互动画，提升用户体验。
-
-设计遵循以下原则：
- **渐进增强**：在不破坏现有功能的基础上添加视觉增强
- **性能优先**：使用CSS动画和轻量级JavaScript，避免性能问题
- **响应式设计**：确保在所有设备上都有良好的显示效果
- **无障碍访问**：遵循WCAG 2.1标准，支持键盘导航和屏幕阅读器
- **主题一致性**：与Filament的设计语言保持一致
-
-## 架构
-
-### 技术栈
-
- **Alpine.js 3.x**：用于添加交互行为和状态管理
- **Tailwind CSS 3.x**：用于样式设计和响应式布局
- **Filament 3.x**：现有的管理面板框架
- **Laravel Blade**：模板引擎
- **CSS Transitions/Animations**：用于动画效果
-
-### 组件层次
-
-```
-┌─────────────────────────────────────┐
-│         Blade Templates             │
-│  (搜索页面、预览模态框、文档列表)    │
-└──────────────┬──────────────────────┘
-               │
-┌──────────────┴──────────────────────┐
-│      Alpine.js Components           │
-│  (交互逻辑、状态管理、事件处理)      │
-└──────────────┬──────────────────────┘
-               │
-┌──────────────┴──────────────────────┐
-│      Tailwind CSS Classes           │
-│  (样式、动画、响应式布局)            │
-└─────────────────────────────────────┘
-```
-
-### 文件结构
-
-```
-resources/
-├── views/
-│   ├── filament/
-│   │   ├── pages/
-│   │   │   ├── search-page.blade.php (增强版搜索页面)
-│   │   │   └── document-preview-modal.blade.php (增强版预览模态框)
-│   │   └── resources/
-│   │       └── document/
-│   │           └── card.blade.php (新增：文档卡片组件)
-│   └── components/
-│       ├── ui/
-│       │   ├── button.blade.php (新增：增强按钮组件)
-│       │   ├── input.blade.php (新增：增强输入框组件)
-│       │   ├── card.blade.php (新增：卡片组件)
-│       │   └── badge.blade.php (新增：徽章组件)
-│       └── animations/
-│           ├── fade-in.blade.php (新增：淡入动画)
-│           └── slide-in.blade.php (新增：滑入动画)
-├── css/
-│   └── custom/
-│       ├── animations.css (新增：自定义动画)
-│       ├── components.css (新增：组件样式)
-│       └── utilities.css (新增：工具类)
-└── js/
-    └── alpine/
-        ├── search.js (新增：搜索页面逻辑)
-        ├── preview.js (新增：预览模态框逻辑)
-        └── filters.js (新增：筛选器逻辑)
-```
-
-## 组件和接口
-
-### 1. 搜索页面组件
-
-**职责**：提供美化的搜索界面和结果展示
-
-**Alpine.js数据结构**：
-```javascript
-{
-    // 搜索状态
-    searchQuery: '',
-    isSearching: false,
-    hasSearched: false,
-    
-    // 筛选器状态
-    filters: {
-        type: null,
-        groupId: null
-    },
-    showFilters: false,
-    
-    // 结果状态
-    results: [],
-    resultCount: 0,
-    
-    // UI状态
-    viewMode: 'grid', // 'grid' 或 'list'
-    sortBy: 'created_at',
-    sortOrder: 'desc'
-}
-```
-
-**方法**：
- `search()`：执行搜索
- `clearSearch()`：清空搜索
- `toggleFilters()`：切换筛选器显示
- `applyFilter(key, value)`：应用筛选条件
- `removeFilter(key)`：移除筛选条件
- `toggleViewMode()`：切换视图模式
- `sortResults(field)`：排序结果
-
-### 2. 文档卡片组件
-
-**职责**：以卡片形式展示文档信息
-
-**Props**：
- `document`：文档对象
- `showActions`：是否显示操作按钮
- `compact`：是否使用紧凑模式
-
-**样式类**：
- `document-card`：基础卡片样式
- `document-card-hover`：悬停效果
- `document-card-compact`：紧凑模式
-
-### 3. 预览模态框组件
-
-**职责**：提供优雅的文档预览体验
-
-**Alpine.js数据结构**：
-```javascript
-{
-    // 模态框状态
-    isOpen: false,
-    isLoading: true,
-    
-    // 内容状态
-    content: null,
-    error: null,
-    
-    // UI状态
-    scrollProgress: 0,
-    showScrollTop: false
-}
-```
-
-**方法**：
- `open()`：打开模态框
- `close()`：关闭模态框
- `loadContent()`：加载内容
- `scrollToTop()`：滚动到顶部
- `updateScrollProgress()`：更新滚动进度
-
-### 4. 增强按钮组件
-
-**职责**：提供统一的按钮样式和交互效果
-
-**Props**：
- `variant`：按钮变体（primary, secondary, danger等）
- `size`：按钮大小（sm, md, lg）
- `loading`：加载状态
- `disabled`：禁用状态
- `icon`：图标名称
-
-**样式类**：
- `btn-enhanced`：基础增强样式
- `btn-loading`：加载状态
- `btn-pulse`：脉冲效果
-
-### 5. 增强输入框组件
-
-**职责**：提供友好的输入交互效果
-
-**Props**：
- `label`：标签文本
- `placeholder`：占位符
- `maxLength`：最大长度
- `showCounter`：显示字符计数
- `validation`：验证规则
-
-**Alpine.js数据结构**：
-```javascript
-{
-    value: '',
-    isFocused: false,
-    hasError: false,
-    errorMessage: '',
-    charCount: 0
-}
-```
-
-## 数据模型
-
-本功能主要涉及UI增强，不需要修改现有数据模型。所有数据仍使用现有的Document、Group等模型。
-
-## 正确性属性
-
-*属性是一个特征或行为，应该在系统的所有有效执行中保持为真。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*
-
-### 属性 1：文档类型徽章颜色一致性
-
-*对于任何*文档，当显示为卡片时，全局文档应该使用绿色徽章，专用文档应该使用蓝色徽章
-
-**验证需求：2.3**
-
-### 属性 2：ARIA标签完整性
-
-*对于任何*可交互元素，该元素应该包含适当的ARIA标签或role属性
-
-**验证需求：10.2**
-
-### 属性 3：颜色对比度合规性
-
-*对于任何*文本元素，其前景色和背景色的对比度应该至少为4.5:1（普通文本）或3:1（大文本）
-
-**验证需求：10.5**
-
-## 错误处理
-
-### 1. 动画性能问题
-
-**场景**：在低性能设备上动画可能导致卡顿
-
-**处理策略**：
- 检测设备性能，在低性能设备上禁用复杂动画
- 使用CSS `will-change`属性优化动画性能
- 遵循用户的`prefers-reduced-motion`设置
-
-### 2. Alpine.js加载失败
-
-**场景**：CDN不可用或网络问题导致Alpine.js加载失败
-
-**处理策略**：
- 使用本地备份的Alpine.js文件
- 确保核心功能在没有JavaScript的情况下仍可用
- 显示友好的降级界面
-
-### 3. 深色模式切换问题
-
-**场景**：主题切换时可能出现闪烁
-
-**处理策略**：
- 在页面加载前检测主题偏好
- 使用CSS变量实现平滑过渡
- 将主题偏好保存到localStorage
-
-### 4. 响应式布局问题
-
-**场景**：某些设备上布局可能错乱
-
-**处理策略**：
- 使用Tailwind的响应式断点
- 在多种设备上测试
- 提供最小宽度限制
-
-## 测试策略
-
-### 单元测试
-
-使用PHPUnit和Pest进行后端测试：
-
-1. **组件渲染测试**
-   - 测试Blade组件是否正确渲染
-   - 测试props是否正确传递
-   - 测试条件渲染逻辑
-
-2. **样式类测试**
-   - 测试CSS类是否正确应用
-   - 测试响应式类是否存在
-
-### 前端测试
-
-使用Jest和Testing Library进行前端测试：
-
-1. **Alpine.js组件测试**
-   - 测试数据绑定
-   - 测试事件处理
-   - 测试状态变化
-
-2. **交互测试**
-   - 测试按钮点击
-   - 测试表单输入
-   - 测试键盘导航
-
-3. **视觉回归测试**
-   - 使用Percy或Chromatic进行截图对比
-   - 测试不同主题下的显示效果
-   - 测试不同屏幕尺寸下的布局
-
-### 无障碍测试
-
-1. **自动化测试**
-   - 使用axe-core进行无障碍扫描
-   - 测试ARIA标签
-   - 测试键盘导航
-
-2. **手动测试**
-   - 使用屏幕阅读器测试
-   - 测试键盘完整导航
-   - 测试颜色对比度
-
-### 性能测试
-
-1. **动画性能**
-   - 使用Chrome DevTools测试FPS
-   - 测试动画是否触发重排
-   - 测试低性能设备表现
-
-2. **加载性能**
-   - 测试CSS和JS文件大小
-   - 测试首次内容绘制时间
-   - 测试交互就绪时间
-
-### 浏览器兼容性测试
-
-测试以下浏览器：
- Chrome（最新版本和前一版本）
- Firefox（最新版本和前一版本）
- Safari（最新版本）
- Edge（最新版本）
- 移动浏览器（iOS Safari、Chrome Mobile）
-
-## 实现细节
-
-### 1. Tailwind CSS配置
-
-扩展Tailwind配置以支持自定义动画和颜色：
-
-```javascript
-// tailwind.config.js
-module.exports = {
-    theme: {
-        extend: {
-            animation: {
-                'fade-in': 'fadeIn 0.3s ease-in-out',
-                'slide-in': 'slideIn 0.3s ease-out',
-                'scale-in': 'scaleIn 0.2s ease-out',
-                'shake': 'shake 0.5s ease-in-out',
-            },
-            keyframes: {
-                fadeIn: {
-                    '0%': { opacity: '0' },
-                    '100%': { opacity: '1' },
-                },
-                slideIn: {
-                    '0%': { transform: 'translateY(-10px)', opacity: '0' },
-                    '100%': { transform: 'translateY(0)', opacity: '1' },
-                },
-                scaleIn: {
-                    '0%': { transform: 'scale(0.95)', opacity: '0' },
-                    '100%': { transform: 'scale(1)', opacity: '1' },
-                },
-                shake: {
-                    '0%, 100%': { transform: 'translateX(0)' },
-                    '25%': { transform: 'translateX(-10px)' },
-                    '75%': { transform: 'translateX(10px)' },
-                },
-            },
-        },
-    },
-}
-```
-
-### 2. Alpine.js集成
-
-在Blade模板中集成Alpine.js：
-
-```html
-<div x-data="searchComponent()" x-init="init()">
-    <!-- 组件内容 -->
-</div>
-
-<script>
-function searchComponent() {
-    return {
-        // 数据和方法
-    }
-}
-</script>
-```
-
-### 3. 自定义CSS动画
-
-创建可复用的动画类：
-
-```css
-/* animations.css */
-.animate-stagger > * {
-    animation: fadeIn 0.3s ease-in-out;
-    animation-fill-mode: both;
-}
-
-.animate-stagger > *:nth-child(1) { animation-delay: 0.05s; }
-.animate-stagger > *:nth-child(2) { animation-delay: 0.1s; }
-.animate-stagger > *:nth-child(3) { animation-delay: 0.15s; }
-/* ... */
-
-.hover-lift {
-    transition: transform 0.2s ease, box-shadow 0.2s ease;
-}
-
-.hover-lift:hover {
-    transform: translateY(-4px);
-    box-shadow: 0 10px 25px rgba(0, 0, 0, 0.15);
-}
-```
-
-### 4. 深色模式支持
-
-使用Tailwind的深色模式类：
-
-```html
-<div class="bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100">
-    <!-- 内容 -->
-</div>
-```
-
-### 5. 响应式设计
-
-使用Tailwind的响应式前缀：
-
-```html
-<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-    <!-- 卡片 -->
-</div>
-```
-
-### 6. 无障碍支持
-
-添加适当的ARIA属性：
-
-```html
-<button 
-    aria-label="搜索文档"
-    aria-pressed="false"
-    role="button"
-    tabindex="0"
->
-    搜索
-</button>
-```
-
-### 7. 性能优化
-
- 使用CSS `contain`属性隔离动画
- 使用`will-change`提示浏览器优化
- 延迟加载非关键动画
- 使用`requestAnimationFrame`优化JavaScript动画
-
-```css
-.animated-card {
-    contain: layout style paint;
-    will-change: transform;
-}
-```
-
-## 部署考虑
-
-### 1. 资源打包
-
- 使用Laravel Mix或Vite打包CSS和JS
- 启用CSS和JS压缩
- 使用版本控制避免缓存问题
-
-### 2. CDN配置
-
- 考虑使用CDN加速Alpine.js加载
- 提供本地备份文件
-
-### 3. 浏览器支持
-
- 添加必要的polyfills
- 提供降级方案
-
-### 4. 监控
-
- 监控动画性能
- 收集用户反馈
- 跟踪错误日志
--- a/.kiro/specs/ui-enhancement/requirements.md
+++ b/.kiro/specs/ui-enhancement/requirements.md
@@ -1,138 +0,0 @@
-# 需求文档
-
-## 简介
-
-本文档定义了知识库系统UI界面美化的需求。系统当前使用Filament框架构建，需要通过Alpine.js和Tailwind CSS增强用户界面的视觉效果和交互体验，使界面更加现代化、美观和易用。
-
-## 术语表
-
- **知识库系统（Knowledge Base System）**：基于Laravel和Filament构建的文档管理系统
- **Alpine.js**：轻量级JavaScript框架，用于添加交互行为
- **Tailwind CSS**：实用优先的CSS框架，用于样式设计
- **Filament**：Laravel的管理面板框架
- **搜索页面（Search Page）**：用户搜索文档的界面
- **文档预览（Document Preview）**：在模态框中显示文档内容的功能
- **文档列表（Document List）**：显示文档资源的表格界面
- **响应式设计（Responsive Design）**：适配不同屏幕尺寸的界面设计
-
-## 需求
-
-### 需求 1
-
-**用户故事：** 作为用户，我希望搜索页面具有现代化的视觉设计，以便获得更好的使用体验。
-
-#### 验收标准
-
-1. WHEN 用户访问搜索页面 THEN 系统应当显示具有渐变背景和阴影效果的搜索表单卡片
-2. WHEN 用户将鼠标悬停在搜索按钮上 THEN 系统应当显示平滑的过渡动画效果
-3. WHEN 用户输入搜索关键词 THEN 系统应当在输入框获得焦点时显示高亮边框效果
-4. WHEN 搜索表单加载完成 THEN 系统应当显示淡入动画效果
-5. WHEN 用户在移动设备上访问 THEN 系统应当显示适配移动端的响应式布局
-
-### 需求 2
-
-**用户故事：** 作为用户，我希望搜索结果以卡片形式展示，以便更直观地浏览文档信息。
-
-#### 验收标准
-
-1. WHEN 搜索返回结果 THEN 系统应当以卡片网格布局显示文档列表
-2. WHEN 用户将鼠标悬停在文档卡片上 THEN 系统应当显示卡片上浮和阴影增强效果
-3. WHEN 文档卡片包含类型标签 THEN 系统应当使用不同颜色的徽章区分全局和专用文档
-4. WHEN 搜索结果加载完成 THEN 系统应当显示交错淡入动画效果
-5. WHEN 文档卡片显示内容片段 THEN 系统应当使用渐变遮罩处理文本溢出
-
-### 需求 3
-
-**用户故事：** 作为用户，我希望文档预览模态框具有优雅的设计，以便舒适地阅读文档内容。
-
-#### 验收标准
-
-1. WHEN 用户点击预览按钮 THEN 系统应当显示带有缩放淡入动画的模态框
-2. WHEN 模态框打开时 THEN 系统应当显示半透明背景遮罩和模糊效果
-3. WHEN 文档内容较长 THEN 系统应当提供带有自定义滚动条样式的滚动区域
-4. WHEN 文档包含代码块 THEN 系统应当使用语法高亮和圆角边框样式
-5. WHEN 文档包含表格 THEN 系统应当使用斑马纹和悬停高亮效果
-
-### 需求 4
-
-**用户故事：** 作为用户，我希望操作按钮具有清晰的视觉反馈，以便明确操作状态。
-
-#### 验收标准
-
-1. WHEN 用户将鼠标悬停在按钮上 THEN 系统应当显示颜色加深和轻微缩放效果
-2. WHEN 用户点击按钮 THEN 系统应当显示按下动画效果
-3. WHEN 按钮处于加载状态 THEN 系统应当显示旋转的加载图标
-4. WHEN 按钮处于禁用状态 THEN 系统应当显示降低透明度和禁用鼠标指针
-5. WHEN 操作成功完成 THEN 系统应当显示带有图标的成功通知动画
-
-### 需求 5
-
-**用户故事：** 作为用户，我希望表单输入具有友好的交互效果，以便更好地完成输入操作。
-
-#### 验收标准
-
-1. WHEN 输入框获得焦点 THEN 系统应当显示边框颜色变化和标签上移动画
-2. WHEN 用户输入内容 THEN 系统应当实时显示字符计数或验证状态
-3. WHEN 输入验证失败 THEN 系统应当显示红色边框和抖动动画效果
-4. WHEN 下拉选择框展开 THEN 系统应当显示下滑淡入动画
-5. WHEN 用户清空输入 THEN 系统应当显示清除按钮的淡入淡出效果
-
-### 需求 6
-
-**用户故事：** 作为用户，我希望页面加载和状态变化具有流畅的过渡效果，以便获得连贯的使用体验。
-
-#### 验收标准
-
-1. WHEN 页面首次加载 THEN 系统应当显示骨架屏加载动画
-2. WHEN 搜索正在执行 THEN 系统应当显示加载指示器和脉冲动画
-3. WHEN 内容状态改变 THEN 系统应当使用淡入淡出过渡效果
-4. WHEN 列表项添加或删除 THEN 系统应当显示滑入滑出动画
-5. WHEN 错误发生 THEN 系统应当显示带有图标的错误提示和抖动效果
-
-### 需求 7
-
-**用户故事：** 作为用户，我希望界面支持深色模式，以便在不同光线环境下舒适使用。
-
-#### 验收标准
-
-1. WHEN 系统检测到深色模式偏好 THEN 系统应当自动切换到深色主题
-2. WHEN 深色模式激活 THEN 系统应当使用深色背景和浅色文字
-3. WHEN 深色模式下显示卡片 THEN 系统应当使用深色卡片背景和适当的边框
-4. WHEN 深色模式下显示按钮 THEN 系统应当调整按钮颜色以保持对比度
-5. WHEN 主题切换时 THEN 系统应当显示平滑的颜色过渡动画
-
-### 需求 8
-
-**用户故事：** 作为用户，我希望界面元素具有微交互效果，以便获得更生动的使用体验。
-
-#### 验收标准
-
-1. WHEN 用户将鼠标悬停在图标上 THEN 系统应当显示图标旋转或缩放动画
-2. WHEN 用户点击收藏按钮 THEN 系统应当显示心形填充动画
-3. WHEN 通知消息出现 THEN 系统应当从右侧滑入并自动淡出
-4. WHEN 用户滚动页面 THEN 系统应当显示返回顶部按钮的淡入效果
-5. WHEN 用户拖拽元素 THEN 系统应当显示拖拽阴影和位置指示器
-
-### 需求 9
-
-**用户故事：** 作为用户，我希望文档列表具有高级筛选和排序界面，以便快速找到目标文档。
-
-#### 验收标准
-
-1. WHEN 用户点击筛选按钮 THEN 系统应当显示侧边栏滑入动画
-2. WHEN 用户选择筛选条件 THEN 系统应当实时更新结果数量徽章
-3. WHEN 用户应用筛选 THEN 系统应当显示已选筛选条件的标签
-4. WHEN 用户点击排序选项 THEN 系统应当显示排序图标的旋转动画
-5. WHEN 筛选结果为空 THEN 系统应当显示友好的空状态插图和提示
-
-### 需求 10
-
-**用户故事：** 作为用户，我希望界面具有无障碍访问支持，以便所有用户都能使用系统。
-
-#### 验收标准
-
-1. WHEN 用户使用键盘导航 THEN 系统应当显示清晰的焦点指示器
-2. WHEN 屏幕阅读器访问页面 THEN 系统应当提供适当的ARIA标签
-3. WHEN 用户使用Tab键切换 THEN 系统应当按逻辑顺序聚焦可交互元素
-4. WHEN 动画效果播放 THEN 系统应当遵循用户的减少动画偏好设置
-5. WHEN 界面显示颜色信息 THEN 系统应当确保足够的颜色对比度
--- a/.kiro/specs/ui-enhancement/tasks.md
+++ b/.kiro/specs/ui-enhancement/tasks.md
@@ -1,334 +0,0 @@
-# 实施计划
-
- [ ] 1. 配置开发环境和依赖
- [ ] 1.1 确认Alpine.js和Tailwind CSS已安装
-  - 检查package.json中的依赖
-  - 如需要则安装Alpine.js 3.x
-  - 确认Tailwind CSS 3.x已配置
-  - _需求：所有需求的基础_
-
- [ ] 1.2 扩展Tailwind配置文件
-  - 在tailwind.config.js中添加自定义动画
-  - 添加自定义关键帧（fadeIn, slideIn, scaleIn, shake）
-  - 配置动画时长和缓动函数
-  - _需求：1.2, 1.4, 2.2, 2.4, 3.1, 4.1, 5.1, 5.3, 6.1-6.5, 8.1-8.5_
-
- [ ] 1.3 创建自定义CSS文件结构
-  - 创建resources/css/custom/animations.css
-  - 创建resources/css/custom/components.css
-  - 创建resources/css/custom/utilities.css
-  - 在app.css中导入自定义CSS文件
-  - _需求：所有需求_
-
- [ ] 2. 创建可复用的UI组件
- [ ] 2.1 创建增强按钮组件
-  - 创建resources/views/components/ui/button.blade.php
-  - 实现按钮变体（primary, secondary, danger等）
-  - 添加悬停效果（颜色加深、轻微缩放）
-  - 添加点击动画效果
-  - 添加加载状态（旋转图标）
-  - 添加禁用状态样式
-  - _需求：4.1, 4.2, 4.3, 4.4_
-
- [ ]* 2.2 编写属性测试验证按钮组件
-  - **属性 1：文档类型徽章颜色一致性**
-  - **验证需求：2.3**
-
- [ ] 2.3 创建增强输入框组件
-  - 创建resources/views/components/ui/input.blade.php
-  - 实现焦点状态（边框颜色变化、标签上移）
-  - 添加字符计数功能
-  - 添加验证错误状态（红色边框、抖动动画）
-  - 添加清除按钮（淡入淡出效果）
-  - _需求：5.1, 5.2, 5.3, 5.5_
-
- [ ] 2.4 创建卡片组件
-  - 创建resources/views/components/ui/card.blade.php
-  - 实现基础卡片样式（渐变背景、阴影）
-  - 添加悬停效果（上浮、阴影增强）
-  - 支持深色模式样式
-  - _需求：1.1, 2.1, 2.2, 7.3_
-
- [ ] 2.5 创建徽章组件
-  - 创建resources/views/components/ui/badge.blade.php
-  - 实现不同颜色变体（success, info, warning, danger）
-  - 为全局文档使用绿色徽章
-  - 为专用文档使用蓝色徽章
-  - 支持深色模式
-  - _需求：2.3, 7.4_
-
- [ ] 3. 增强搜索页面UI
- [ ] 3.1 更新搜索表单样式
-  - 修改resources/views/filament/pages/search-page.blade.php
-  - 应用渐变背景和阴影效果到搜索卡片
-  - 添加表单加载时的淡入动画
-  - 使用增强输入框组件替换原有输入框
-  - 使用增强按钮组件替换原有按钮
-  - _需求：1.1, 1.2, 1.3, 1.4_
-
- [ ] 3.2 实现响应式搜索表单布局
-  - 添加移动端适配样式
-  - 使用Tailwind响应式类（sm:, md:, lg:）
-  - 测试不同屏幕尺寸下的显示效果
-  - _需求：1.5_
-
- [ ] 3.3 创建文档卡片视图组件
-  - 创建resources/views/filament/resources/document/card.blade.php
-  - 实现卡片网格布局
-  - 添加文档标题、类型徽章、内容片段
-  - 添加悬停效果（卡片上浮、阴影增强）
-  - 使用渐变遮罩处理文本溢出
-  - _需求：2.1, 2.2, 2.3, 2.5_
-
- [ ] 3.4 添加搜索结果动画
-  - 实现交错淡入动画（stagger animation）
-  - 为每个卡片添加延迟动画
-  - 添加加载骨架屏
-  - _需求：2.4, 6.1_
-
- [ ] 3.5 集成Alpine.js到搜索页面
-  - 创建resources/js/alpine/search.js
-  - 实现搜索状态管理（isSearching, hasSearched）
-  - 实现筛选器切换逻辑
-  - 实现视图模式切换（网格/列表）
-  - 添加搜索加载指示器
-  - _需求：6.2, 9.1, 9.2_
-
- [ ] 3.6 实现高级筛选器界面
-  - 添加筛选按钮和侧边栏
-  - 实现侧边栏滑入动画
-  - 显示已选筛选条件的标签
-  - 实时更新结果数量徽章
-  - 添加清空筛选按钮
-  - _需求：9.1, 9.2, 9.3_
-
- [ ] 3.7 实现空状态UI
-  - 创建友好的空状态插图
-  - 添加提示文本
-  - 提供建议操作
-  - _需求：9.5_
-
- [ ] 4. 增强文档预览模态框
- [ ] 4.1 更新预览模态框样式
-  - 修改resources/views/filament/pages/document-preview-modal.blade.php
-  - 添加模态框打开动画（缩放淡入）
-  - 添加半透明背景遮罩和模糊效果
-  - 优化内容区域样式
-  - _需求：3.1, 3.2_
-
- [ ] 4.2 自定义滚动条样式
-  - 为预览内容区域添加自定义滚动条
-  - 使用Tailwind的scrollbar插件或自定义CSS
-  - 支持深色模式滚动条
-  - _需求：3.3_
-
- [ ] 4.3 增强Markdown内容样式
-  - 优化代码块样式（语法高亮、圆角边框）
-  - 优化表格样式（斑马纹、悬停高亮）
-  - 优化标题、列表、引用样式
-  - 优化图片显示（响应式、圆角）
-  - _需求：3.4, 3.5_
-
- [ ] 4.4 集成Alpine.js到预览模态框
-  - 创建resources/js/alpine/preview.js
-  - 实现模态框状态管理（isOpen, isLoading）
-  - 实现滚动进度跟踪
-  - 添加返回顶部按钮（滚动时淡入）
-  - _需求：8.4_
-
- [ ] 5. 实现深色模式支持
- [ ] 5.1 配置深色模式检测
-  - 在主布局中添加深色模式检测脚本
-  - 检测系统偏好（prefers-color-scheme）
-  - 从localStorage读取用户偏好
-  - 应用深色模式类到html元素
-  - _需求：7.1_
-
- [ ] 5.2 更新所有组件的深色模式样式
-  - 为搜索页面添加深色模式样式
-  - 为文档卡片添加深色模式样式
-  - 为预览模态框添加深色模式样式
-  - 为按钮和输入框添加深色模式样式
-  - 确保颜色对比度符合标准
-  - _需求：7.2, 7.3, 7.4_
-
- [ ] 5.3 实现主题切换动画
-  - 添加主题切换时的颜色过渡效果
-  - 使用CSS变量实现平滑过渡
-  - 避免切换时的闪烁
-  - _需求：7.5_
-
- [ ] 6. 添加微交互效果
- [ ] 6.1 实现图标动画
-  - 为搜索图标添加悬停旋转效果
-  - 为下载图标添加悬停缩放效果
-  - 为筛选图标添加点击动画
-  - _需求：8.1_
-
- [ ] 6.2 实现通知动画
-  - 优化Filament通知的显示动画
-  - 实现从右侧滑入效果
-  - 实现自动淡出效果
-  - 添加成功/错误图标动画
-  - _需求：4.5, 8.3_
-
- [ ] 6.3 实现排序动画
-  - 为排序图标添加旋转动画
-  - 添加排序方向指示器
-  - 实现列表重排动画
-  - _需求：9.4_
-
- [ ] 7. 实现页面过渡和加载状态
- [ ] 7.1 创建骨架屏组件
-  - 创建搜索结果骨架屏
-  - 创建文档卡片骨架屏
-  - 添加脉冲动画效果
-  - _需求：6.1_
-
- [ ] 7.2 实现加载指示器
-  - 为搜索按钮添加加载状态
-  - 为预览模态框添加加载指示器
-  - 使用旋转动画和脉冲效果
-  - _需求：6.2_
-
- [ ] 7.3 实现内容过渡动画
-  - 为内容状态变化添加淡入淡出效果
-  - 为列表项添加滑入滑出动画
-  - 优化动画时序
-  - _需求：6.3, 6.4_
-
- [ ] 7.4 实现错误状态UI
-  - 创建错误提示组件
-  - 添加抖动动画效果
-  - 显示错误图标
-  - _需求：6.5_
-
- [ ] 8. 实现无障碍访问支持
- [ ] 8.1 添加键盘导航支持
-  - 为所有交互元素添加tabindex
-  - 实现清晰的焦点指示器样式
-  - 测试Tab键导航顺序
-  - 添加键盘快捷键（如Esc关闭模态框）
-  - _需求：10.1, 10.3_
-
- [ ] 8.2 添加ARIA标签
-  - 为按钮添加aria-label
-  - 为模态框添加role和aria-modal
-  - 为加载状态添加aria-busy
-  - 为展开/折叠元素添加aria-expanded
-  - _需求：10.2_
-
- [ ]* 8.3 编写属性测试验证ARIA标签
-  - **属性 2：ARIA标签完整性**
-  - **验证需求：10.2**
-
- [ ] 8.4 实现动画偏好支持
-  - 检测prefers-reduced-motion设置
-  - 在用户偏好减少动画时禁用动画
-  - 提供静态替代方案
-  - _需求：10.4_
-
- [ ] 8.5 验证颜色对比度
-  - 使用工具检查所有文本的对比度
-  - 确保至少4.5:1（普通文本）或3:1（大文本）
-  - 调整不符合标准的颜色
-  - _需求：10.5_
-
- [ ]* 8.6 编写属性测试验证颜色对比度
-  - **属性 3：颜色对比度合规性**
-  - **验证需求：10.5**
-
- [ ] 9. 优化性能
- [ ] 9.1 优化CSS
-  - 移除未使用的Tailwind类
-  - 压缩CSS文件
-  - 使用PurgeCSS减小文件大小
-  - _需求：性能优化_
-
- [ ] 9.2 优化JavaScript
-  - 延迟加载非关键JavaScript
-  - 使用代码分割
-  - 压缩JavaScript文件
-  - _需求：性能优化_
-
- [ ] 9.3 优化动画性能
-  - 使用CSS transform和opacity（避免重排）
-  - 添加will-change提示
-  - 使用contain属性隔离动画
-  - 在低性能设备上禁用复杂动画
-  - _需求：性能优化_
-
- [ ] 10. 测试和验证
- [ ]* 10.1 编写组件单元测试
-  - 测试按钮组件的各种状态
-  - 测试输入框组件的交互
-  - 测试卡片组件的渲染
-  - 测试徽章组件的颜色逻辑
-  - _需求：所有组件相关需求_
-
- [ ]* 10.2 编写Alpine.js组件测试
-  - 测试搜索组件的状态管理
-  - 测试筛选器逻辑
-  - 测试预览模态框逻辑
-  - _需求：所有交互相关需求_
-
- [ ]* 10.3 进行无障碍测试
-  - 使用axe-core进行自动化扫描
-  - 使用屏幕阅读器测试
-  - 测试键盘完整导航
-  - _需求：10.1-10.5_
-
- [ ]* 10.4 进行视觉回归测试
-  - 截图对比测试（使用Percy或Chromatic）
-  - 测试深色模式显示
-  - 测试响应式布局
-  - _需求：所有视觉相关需求_
-
- [ ]* 10.5 进行性能测试
-  - 使用Chrome DevTools测试动画FPS
-  - 测试首次内容绘制时间
-  - 测试交互就绪时间
-  - 在低性能设备上测试
-  - _需求：性能相关需求_
-
- [ ]* 10.6 进行浏览器兼容性测试
-  - 在Chrome、Firefox、Safari、Edge上测试
-  - 在移动浏览器上测试
-  - 修复兼容性问题
-  - _需求：所有需求_
-
- [ ] 11. 文档和部署
- [ ] 11.1 更新开发文档
-  - 记录新增的UI组件使用方法
-  - 记录Alpine.js组件的API
-  - 记录自定义CSS类的用法
-  - 添加样式指南
-  - _需求：文档需求_
-
- [ ] 11.2 创建组件演示页面
-  - 创建Storybook或类似的组件展示页面
-  - 展示所有UI组件的各种状态
-  - 提供代码示例
-  - _需求：文档需求_
-
- [ ] 11.3 优化生产构建
-  - 配置Laravel Mix或Vite进行生产构建
-  - 启用CSS和JS压缩
-  - 配置资源版本控制
-  - 测试生产环境构建
-  - _需求：部署需求_
-
- [ ] 11.4 准备部署清单
-  - 列出需要部署的文件
-  - 列出需要运行的命令
-  - 列出需要检查的配置
-  - 创建回滚计划
-  - _需求：部署需求_
-
- [ ] 12. 最终检查点
-  - 确保所有UI增强功能正常工作
-  - 验证在不同设备和浏览器上的显示效果
-  - 确认无障碍访问功能正常
-  - 验证性能指标达标
-  - 如有问题请咨询用户
-  - _需求：所有需求_