diff --git a/backend/README.md b/backend/README.md deleted file mode 100644 index 4f3abea..0000000 --- a/backend/README.md +++ /dev/null @@ -1,258 +0,0 @@ -# 接龙自动打卡系统 - 后端 API - -FastAPI 后端服务，提供用户管理、QQ 扫码登录、自动打卡等功能。 - -## 🚀 快速开始 - -### 1. 安装依赖 - -```bash -cd backend -pip install -r requirements.txt -``` - -### 2. 配置环境 - -创建 `.env` 文件（可选）： - -```env -# 邮件通知配置（可选） -SMTP_SERVER=smtp.example.com -SMTP_PORT=465 -SMTP_SENDER_EMAIL=your-email@example.com -SMTP_SENDER_PASSWORD=your-password-here - -# Chrome 浏览器配置（可选） -CHROME_BINARY_PATH= -CHROMEDRIVER_PATH= -``` - -### 3. 初始化数据库 - -数据库会在首次启动时自动初始化。 - -### 4. 创建管理员用户 - -```bash -python backend/scripts/create_admin.py -``` - -按照提示输入管理员信息： -- Signature: 管理员标识（唯一） -- ThreadId: 接龙 ID -- 邮箱: 接收通知的邮箱 - -### 5. 启动服务 - -```bash -# 开发模式（支持热重载） -cd backend -python main.py - -# 或者使用 uvicorn -uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000 - -# 生产模式 -uvicorn backend.main:app --host 0.0.0.0 --port 8000 --workers 4 -``` - -### 6. 访问 API 文档 - -启动后访问: http://localhost:8000/docs - -## 📁 项目结构 - -``` -backend/ -├── main.py # FastAPI 应用入口 -├── config.py # 配置管理 -├── dependencies.py # 认证中间件 -├── requirements.txt # Python 依赖 -├── models/ # 数据库模型 -│ ├── database.py # 数据库配置 -│ ├── user.py # User 模型 -│ └── check_in_record.py # CheckInRecord 模型 -├── schemas/ # Pydantic Schema -│ ├── user.py # 用户相关 Schema -│ ├── auth.py # 认证相关 Schema -│ └── check_in.py # 打卡相关 Schema -├── api/ # API 路由 -│ ├── auth.py # 认证 API -│ ├── users.py # 用户管理 API -│ ├── check_in.py # 打卡 API -│ └── admin.py # 管理员 API -├── services/ # 业务逻辑层 -│ ├── auth_service.py # 认证服务 -│ ├── user_service.py # 用户服务 -│ ├── check_in_service.py # 打卡服务 -│ └── scheduler_service.py # 调度服务 -├── workers/ # Selenium 工作模块 -│ ├── token_refresher.py # Token 刷新（QQ 扫码） -│ ├── check_in_worker.py # 打卡执行 -│ └── email_notifier.py # 邮件通知 -└── scripts/ # 工具脚本 - └── create_admin.py # 创建管理员用户 -``` - -## 🔌 API 端点 - -### 认证 API (`/api/auth`) - -- `POST /api/auth/request_qrcode` - 请求 QQ 扫码二维码 -- `GET /api/auth/qrcode_status/{session_id}` - 检查扫码状态 -- `POST /api/auth/verify_token` - 验证 Token 有效性 - -### 用户 API (`/api/users`) - -- `POST /api/users` - 创建用户（管理员） -- `GET /api/users/me` - 获取当前用户信息 -- `GET /api/users/me/token_status` - 获取 Token 状态 -- `GET /api/users` - 获取所有用户（管理员） -- `GET /api/users/{user_id}` - 获取指定用户 -- `PUT /api/users/{user_id}` - 更新用户信息 -- `DELETE /api/users/{user_id}` - 删除用户（管理员） - -### 打卡 API (`/api/check_in`) - -- `POST /api/check_in/manual` - 手动触发打卡 -- `GET /api/check_in/my_records` - 查看自己的打卡记录 -- `GET /api/check_in/records` - 查看所有打卡记录（管理员） -- `GET /api/check_in/records/count` - 获取打卡记录统计（管理员） - -### 管理员 API (`/api/admin`) - -- `POST /api/admin/batch_check_in` - 批量触发打卡 -- `GET /api/admin/logs` - 获取系统日志 -- `GET /api/admin/stats` - 获取系统统计 - -## ⚙️ 配置说明 - -### 邮件配置 (`config.ini`) - -在项目根目录创建 `config.ini`： - -```ini -[Email] -smtpserver = smtp.example.com -smtpport = 465 -senderemail = your-email@example.com -senderpassword = your-password -``` - -### 定时任务配置 - -在 `.env` 文件中配置（或在 `backend/config.py` 中设置默认值）： - -- `TOKEN_CHECK_INTERVAL_MINUTES`: Token 检查间隔（默认 30 分钟） -- `SESSION_CLEANUP_INTERVAL_HOURS`: 会话清理间隔（默认 24 小时） - -**注意**：每个任务的打卡时间由任务自身的 `cron_expression` 字段控制（支持标准 Crontab 表达式）。 - -## 🔐 认证流程 - -1. 用户输入 Signature 并请求二维码 -2. 后端启动 Selenium 获取 QQ 登录二维码 -3. 前端轮询检查扫码状态 -4. 用户使用手机 QQ 扫码 -5. 后端获取 Token 并解析 JWT -6. 用户后续请求使用 `Authorization: Bearer ` header - -## 📊 定时任务 - -系统会自动执行以下定时任务： - -1. **定时打卡**: 每天 20:00 为所有启用的用户执行打卡 -2. **Token 过期检查**: 每 30 分钟检查一次，Token 在 30 分钟内过期时发送邮件提醒 -3. **会话文件清理**: 每 24 小时清理超过 24 小时的旧会话文件 - -## 🛠️ 开发说明 - -### 添加新的 API 端点 - -1. 在 `backend/schemas/` 中定义请求/响应 Schema -2. 在 `backend/services/` 中实现业务逻辑 -3. 在 `backend/api/` 中创建 API 路由 -4. 在 `backend/main.py` 中注册路由 - -### 数据库迁移 - -如果修改了模型，删除 `data/checkin.db` 并重启服务即可重新创建数据库。 - -⚠️ 注意：生产环境建议使用 Alembic 进行数据库迁移。 - -## 🐛 故障排查 - -### 问题：无法启动 Selenium - -确保已安装 Chrome 和 ChromeDriver： - -```bash -# 检查路径配置 -ls chrome-linux64/chrome -ls chromedriver -``` - -### 问题：Token 验证失败 - -检查数据库中用户的 `authorization` 字段是否有值。 - -### 问题：定时任务未执行 - -检查日志文件 `logs/CheckIn.log`，确认调度器是否成功启动。 - -### 问题：邮件发送失败 - -检查 `config.ini` 配置是否正确，SMTP 服务器是否可访问。 - -## 📝 环境变量 - -可选的环境变量： - -- `DATABASE_URL`: 数据库 URL（默认使用 SQLite） -- `CORS_ORIGINS`: 允许的前端域名（默认 localhost:5173 和 localhost:3000） -- `SMTP_SERVER`: 邮件服务器地址（用于邮件通知，可选） -- `SMTP_SENDER_EMAIL`: 发件人邮箱（用于邮件通知，可选） -- `CHROME_BINARY_PATH`: Chrome 浏览器路径（可选，留空自动检测） -- `CHROMEDRIVER_PATH`: ChromeDriver 路径（可选，留空自动下载） - -## 🚀 部署建议 - -### 使用 Gunicorn - -```bash -pip install gunicorn -gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 -``` - -### 使用 Systemd - -创建 `/etc/systemd/system/checkin-api.service`： - -```ini -[Unit] -Description=CheckIn API Service -After=network.target - -[Service] -Type=simple -User=your-user -WorkingDirectory=/path/to/CheckInApp -Environment="PATH=/path/to/venv/bin" -ExecStart=/path/to/venv/bin/gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 -Restart=always - -[Install] -WantedBy=multi-user.target -``` - -启动服务： - -```bash -sudo systemctl enable checkin-api -sudo systemctl start checkin-api -sudo systemctl status checkin-api -``` - -## 📄 许可证 - -本项目仅供学习和研究使用。 diff --git a/frontend/README.md b/frontend/README.md deleted file mode 100644 index a5420fc..0000000 --- a/frontend/README.md +++ /dev/null @@ -1,230 +0,0 @@ -# 接龙自动打卡系统 - 前端 - -基于 Vue 3 + Vite + Element Plus 的现代化前端应用。 - -## 技术栈 - -- **框架**: Vue 3 (Composition API) -- **构建工具**: Vite -- **UI 库**: Element Plus -- **路由**: Vue Router 4 -- **状态管理**: Pinia -- **HTTP 客户端**: Axios -- **图标**: @element-plus/icons-vue - -## 项目结构 - -``` -frontend/ -├── src/ -│ ├── api/ # API 接口 -│ │ ├── client.js # Axios 客户端配置 -│ │ └── index.js # API 方法封装 -│ ├── assets/ # 静态资源 -│ ├── components/ # 公共组件 -│ │ ├── Layout.vue # 布局组件 -│ │ ├── Navbar.vue # 导航栏 -│ │ └── QRCodeModal.vue # QR 码扫码组件 -│ ├── router/ # 路由配置 -│ │ └── index.js -│ ├── stores/ # Pinia 状态管理 -│ │ ├── auth.js # 认证状态 -│ │ ├── user.js # 用户状态 -│ │ ├── checkIn.js # 打卡状态 -│ │ └── admin.js # 管理员状态 -│ ├── utils/ # 工具函数 -│ │ └── helpers.js # 通用辅助函数 -│ ├── views/ # 页面组件 -│ │ ├── LoginView.vue # 登录页 -│ │ ├── DashboardView.vue # 用户仪表盘 -│ │ ├── RecordsView.vue # 打卡记录 -│ │ ├── NotFoundView.vue # 404 页面 -│ │ └── admin/ # 管理员页面 -│ │ ├── UsersView.vue # 用户管理 -│ │ ├── RecordsView.vue # 所有打卡记录 -│ │ ├── StatsView.vue # 统计信息 -│ │ └── LogsView.vue # 系统日志 -│ ├── App.vue # 根组件 -│ ├── main.js # 入口文件 -│ └── style.css # 全局样式 -├── .env # 环境变量 -├── .env.development # 开发环境变量 -├── .env.production # 生产环境变量 -├── vite.config.js # Vite 配置 -├── package.json # 依赖配置 -└── README.md # 本文件 -``` - -## 快速开始 - -### 安装依赖 - -```bash -npm install -``` - -### 开发模式 - -```bash -npm run dev -``` - -访问 http://localhost:3000 - -### 生产构建 - -```bash -npm run build -``` - -构建产物在 `dist/` 目录。 - -### 预览生产构建 - -```bash -npm run preview -``` - -## 功能特性 - -### 用户功能 - -- **QQ 扫码登录**: 支持 QQ 扫码认证 -- **个人仪表盘**: 查看 Token 状态、手动打卡 -- **打卡记录**: 查看个人打卡历史和统计 -- **Token 管理**: 实时监控 Token 过期状态 - -### 管理员功能 - -- **用户管理**: CRUD 操作、批量启用/禁用、批量打卡 -- **打卡记录**: 查看所有用户的打卡记录 -- **统计信息**: 系统整体运行数据统计 -- **系统日志**: 实时查看系统运行日志 - -## API 代理配置 - -开发环境下，Vite 会自动代理 `/api` 请求到后端服务器： - -```javascript -// vite.config.js -server: { - port: 3000, - proxy: { - '/api': { - target: 'http://localhost:8000', - changeOrigin: true, - }, - }, -} -``` - -## 环境变量 - -创建 `.env.local` 文件自定义配置： - -```env -VITE_API_BASE_URL=http://localhost:8000 -``` - -## 路由结构 - -- `/login` - 登录页面 -- `/dashboard` - 用户仪表盘（需登录） -- `/records` - 打卡记录（需登录） -- `/admin/users` - 用户管理（需管理员权限） -- `/admin/records` - 所有打卡记录（需管理员权限） -- `/admin/stats` - 统计信息（需管理员权限） -- `/admin/logs` - 系统日志（需管理员权限） - -## 状态管理 - -使用 Pinia 进行全局状态管理： - -- **authStore**: 认证状态（Token、用户信息） -- **userStore**: 用户管理相关 -- **checkInStore**: 打卡记录相关 -- **adminStore**: 管理员功能相关 - -## 组件说明 - -### QRCodeModal - -QQ 扫码登录组件，支持： -- 自动获取二维码 -- 轮询扫码状态 -- 倒计时和进度显示 -- 二维码过期提示和刷新 - -### Navbar - -导航栏组件，支持： -- 基于角色的菜单显示 -- 当前路由高亮 -- 用户信息显示 -- 退出登录 - -### Layout - -页面布局组件，包含： -- 顶部导航栏 -- 主内容区域 -- 响应式布局 - -## 开发规范 - -1. **组件命名**: 使用 PascalCase -2. **文件命名**: 组件文件使用 PascalCase，工具文件使用 camelCase -3. **API 调用**: 统一通过 stores 调用，不直接在组件中调用 -4. **错误处理**: 使用 try-catch 并显示友好的错误提示 -5. **Loading 状态**: 异步操作需显示加载状态 - -## 浏览器支持 - -- Chrome >= 87 -- Firefox >= 78 -- Safari >= 14 -- Edge >= 88 - -## 常见问题 - -### 启动时端口被占用 - -修改 `vite.config.js` 中的 `server.port` 配置。 - -### API 请求失败 - -检查后端服务是否启动，默认应在 http://localhost:8000 运行。 - -### 构建产物过大 - -Element Plus 已配置按需加载，如需进一步优化，可以： -- 使用动态导入 (dynamic import) -- 配置 CDN 引入 -- 启用 gzip 压缩 - -## 部署 - -### Nginx 配置示例 - -```nginx -server { - listen 80; - server_name your-domain.com; - root /var/www/checkin/frontend/dist; - index index.html; - - location / { - try_files $uri $uri/ /index.html; - } - - location /api { - proxy_pass http://localhost:8000; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } -} -``` - -## 许可证 - -MIT diff --git a/test.md b/test.md deleted file mode 100644 index 759fbb7..0000000 --- a/test.md +++ /dev/null @@ -1,1001 +0,0 @@ -# Element Plus → Ant Design Vue 迁移功能测试清单 - -**项目**: CheckInApp 前端迁移 -**迁移范围**: Element Plus 2.13.0 → Ant Design Vue 4.x -**测试日期**: ____年__月__日 -**测试人员**: ________ - ---- - -## 测试环境 - -- **浏览器**: ________________ -- **设备类型**: ☐ 桌面 ☐ 平板 ☐ 手机 -- **操作系统**: ________________ -- **屏幕分辨率**: ________________ - ---- - -## 1. 登录与认证 (LoginView.vue) - -### 二维码登录 -- [x] 二维码正确显示 -- [x] 二维码刷新功能 -- [x] 扫码后正确跳转到仪表盘 -- [x] 登录失败显示错误提示 - -### 密码登录 -- [ ] 用户名/密码输入框正常工作 -- [ ] 表单验证正确（空值、格式） -- [ ] 登录成功后跳转 -- [ ] 登录失败显示错误提示 -- [ ] "记住我"开关正常工作 - -### 响应式 -- [ ] 移动端布局适配正常 -- [ ] 表单在小屏幕上可用 - -**备注**: ________________________________________ - ---- - -## 2. 仪表盘 (DashboardView.vue) - -### 数据显示 -- [ ] 统计卡片正确显示（今日打卡、本周打卡、本月打卡、待审批） -- [ ] 骨架屏加载动画 -- [ ] Token 状态显示（有效期、剩余天数） -- [ ] 最近打卡记录表格 - -### 功能交互 -- [ ] 刷新 Token 按钮 -- [ ] 手动打卡功能 -- [ ] 任务选择下拉框 -- [ ] 打卡成功/失败提示 - -### 响应式 -- [ ] 统计卡片在不同屏幕尺寸下正确排列 - - [ ] 移动端: 1列 - - [ ] 平板: 2列 - - [ ] 桌面: 4列 -- [ ] 表格在移动端可横向滚动或卡片视图 - -**备注**: ________________________________________ - ---- - -## 3. 任务管理 (TasksView.vue) - -### 任务列表 -- [ ] 任务卡片正确显示 -- [ ] 启用/禁用状态切换 -- [ ] 任务统计信息显示 - -### 创建任务 -- [ ] "新建任务" 对话框打开 -- [ ] 所有表单字段正常工作 - - [ ] 任务名称 - - [ ] 描述 - - [ ] 模板选择 - - [ ] Cron 表达式编辑器 - - [ ] 启用状态开关 -- [ ] Crontab 编辑器三种模式 - - [ ] 快速模式: 20:00 默认选项 - - [ ] 自定义模式: 时间选择器 + 频率选择 - - [ ] 高级模式: 原始表达式输入 -- [ ] 时间选择器（a-time-picker）正常工作 -- [ ] Cron 表达式验证 -- [ ] 下一个执行时间预览 -- [ ] 表单验证 -- [ ] 创建成功提示 - -### 编辑任务 -- [ ] 编辑对话框正确加载任务数据 -- [ ] 字段修改后保存成功 -- [ ] 更新成功提示 - -### 删除任务 -- [ ] 删除确认对话框 -- [ ] 删除成功提示 - -### 手动打卡 -- [ ] 打卡按钮可点击 -- [ ] 打卡成功/失败提示 - -### 响应式 -- [ ] 任务卡片网格响应式 - - [ ] 移动端: 1列 - - [ ] 平板: 2列 - - [ ] 桌面: 3列 -- [ ] 对话框在移动端全屏显示 - -**备注**: ________________________________________ - ---- - -## 4. 任务记录 (TaskRecordsView.vue) - -### 记录列表 -- [ ] 表格正确显示所有记录 -- [ ] 分页功能正常 -- [ ] 时间格式化正确 -- [ ] 状态标签显示 - -### 响应式 -- [ ] 桌面端: 表格正常显示，可水平滚动 -- [ ] 移动端: 卡片视图或隐藏次要列 - -**备注**: ________________________________________ - ---- - -## 5. 用户记录 (RecordsView.vue) - -### 记录列表 -- [ ] 表格正确显示 -- [ ] 分页正常 -- [ ] 数据加载骨架屏 - -### 响应式 -- [ ] 表格响应式布局 - -**备注**: ________________________________________ - ---- - -## 6. 设置 (SettingsView.vue) - -### 表单功能 -- [ ] 用户信息显示 -- [ ] 修改密码功能 -- [ ] 表单验证 -- [ ] 保存成功提示 - -**备注**: ________________________________________ - ---- - -## 7. 待审批 (PendingApprovalView.vue) - -### 提示信息 -- [ ] 待审批状态正确显示 -- [ ] Alert 组件样式正确 - -**备注**: ________________________________________ - ---- - -## 8. 404 页面 (NotFoundView.vue) - -### 页面显示 -- [ ] 404 结果页正确显示 -- [ ] "返回首页" 按钮可点击 -- [ ] 点击后正确跳转 - -**备注**: ________________________________________ - ---- - -## 9. 管理员 - 用户管理 (admin/UsersView.vue) - -### 用户列表 -- [ ] 标签页切换 - - [ ] 所有用户 - - [ ] 待审批 - - [ ] 已禁用 -- [ ] 表格显示用户数据 -- [ ] 行选择功能 -- [ ] 分页功能 - -### 批量操作 -- [ ] 批量启用按钮 -- [ ] 批量禁用按钮 -- [ ] 操作成功提示 - -### 用户审批 -- [ ] 审批按钮 -- [ ] 审批成功提示 - -### 创建/编辑用户 -- [ ] 对话框打开 -- [ ] 表单字段正常 -- [ ] 角色选择 -- [ ] 保存成功 - -### 响应式 -- [ ] 表格在移动端使用响应式列 -- [ ] 批量操作按钮在小屏幕上适配 - -**备注**: ________________________________________ - ---- - -## 10. 管理员 - 记录管理 (admin/RecordsView.vue) - -### 记录列表 -- [ ] 表格显示所有用户记录 -- [ ] 分页正常 -- [ ] 过滤功能（如果有） - -### 响应式 -- [ ] 表格响应式布局 - -**备注**: ________________________________________ - ---- - -## 11. 管理员 - 日志查看 (admin/LogsView.vue) - -### 日志列表 -- [ ] 表格显示日志 -- [ ] 分页正常 -- [ ] 日志级别过滤 - -### 响应式 -- [ ] 表格响应式布局 - -**备注**: ________________________________________ - ---- - -## 12. 管理员 - 统计信息 (admin/StatsView.vue) - -### 统计显示 -- [ ] 统计数字组件正确显示 -- [ ] Descriptions 组件正确显示 -- [ ] Progress 进度条正确显示 - -### 响应式 -- [ ] Descriptions 在移动端单列显示 -- [ ] 统计卡片响应式布局 - -**备注**: ________________________________________ - ---- - -## 13. 管理员 - 模板管理 (admin/TemplatesView.vue) ⭐ **关键** - -### 模板列表 -- [ ] 模板卡片正确显示 -- [ ] 启用/禁用状态显示 - -### 创建模板 -- [ ] "新建模板" 对话框打开 -- [ ] 基本信息输入 - - [ ] 模板名称 - - [ ] 描述 - - [ ] 父模板选择 - - [ ] 启用状态 -- [ ] 字段配置编辑器显示 - -### 字段配置编辑器 (FieldConfigEditor) -- [ ] 显示名称输入框 -- [ ] 字段类型选择 - - [ ] 📝 单行文本 - - [ ] 📄 多行文本 - - [ ] 🔢 数字输入 - - [ ] 📋 下拉选择 -- [ ] 值类型选择 - - [ ] string (字符串) - - [ ] int (整数) - - [ ] double (浮点数) - - [ ] bool (布尔值) - - [ ] json (JSON对象) -- [ ] 默认值输入 - - [ ] 普通类型: 单行输入框 - - [ ] JSON 类型: 多行文本框 -- [ ] 占位符输入 -- [ ] 必填开关 -- [ ] 隐藏开关 -- [ ] 必填/隐藏互斥逻辑正确 -- [ ] 隐藏时显示提示信息 -- [ ] 下拉选择类型的选项列表编辑 - - [ ] 添加选项 - - [ ] 编辑选项（显示文本、选项值） - - [ ] 删除选项 - -### 字段树操作 (FieldTreeNode) ⭐ **重点修复项** -- [ ] 添加字段下拉菜单 - - [ ] 普通字段 - - [ ] 数组字段 - - [ ] 对象字段 -- [ ] 新添加的字段显示在末尾 ✅ **已修复** -- [ ] 字段上移按钮正常工作 ✅ **已修复** -- [ ] 字段下移按钮正常工作 ✅ **已修复** -- [ ] 字段在边界位置时禁用上移/下移 -- [ ] 字段删除按钮正常工作 -- [ ] 字段折叠/展开按钮 -- [ ] 字段配置展开后显示编辑器 - -### 嵌套字段操作 -- [ ] 数组字段显示 - - [ ] 数组为空时显示提示 - - [ ] 添加元素按钮 - - [ ] 元素编号显示 -- [ ] 数组元素类型 - - [ ] 普通字段元素（显示 FieldConfigEditor） - - [ ] 对象元素（可添加子字段） - - [ ] 嵌套数组元素 -- [ ] 数组元素操作 - - [ ] 删除元素 - - [ ] 为对象元素添加字段 -- [ ] 对象字段显示 - - [ ] 对象为空时显示提示 - - [ ] 添加子字段按钮 - - [ ] 递归显示子字段 -- [ ] 嵌套字段的移动和删除 - -### 添加字段对话框 -- [ ] 字段名输入 -- [ ] 字段名保持原样（不转换大小写） -- [ ] 元素类型选择 - - [ ] 普通字段 - - [ ] 数组字段 - - [ ] 对象字段 -- [ ] 确定按钮添加字段 -- [ ] 字段已存在时显示警告 - -### 编辑模板 -- [ ] 编辑对话框正确加载模板数据 -- [ ] 字段配置正确反序列化（JSON.parse） -- [ ] 修改后保存成功 -- [ ] 字段配置正确序列化（JSON.stringify） - -### 预览模板 -- [ ] 预览对话框显示 -- [ ] 生成的 Payload 正确显示 -- [ ] 字段配置 JSON 正确显示 - -### 删除模板 -- [ ] 删除确认对话框 -- [ ] 删除成功提示 - -### JSON 预览 -- [ ] 实时 JSON 预览显示 -- [ ] JSON 格式化正确（2 空格缩进） -- [ ] 字段顺序与配置顺序一致 - -### 响应式 -- [ ] 对话框宽度响应式 - - [ ] 移动端: 100% 宽度，顶部对齐 - - [ ] 桌面端: 95% 宽度 -- [ ] 字段配置编辑器在小屏幕上可用 -- [ ] 字段树在移动端正常显示 - -**备注**: ________________________________________ - ---- - -## 14. 布局与导航 (Layout.vue & Navbar.vue) - -### 导航栏 -- [ ] Logo 和应用名称显示 -- [ ] 桌面端: 水平菜单正确显示 -- [ ] 移动端: 汉堡图标显示 -- [ ] 移动端: 抽屉菜单正确打开 -- [ ] 移动端: 抽屉菜单正确关闭 -- [ ] 用户下拉菜单 - - [ ] 设置选项 - - [ ] 注销选项 -- [ ] 注销确认对话框（Modal.confirm） -- [ ] 注销后跳转到登录页 - -### 菜单项 -- [ ] 仪表盘 -- [ ] 任务管理 -- [ ] 我的记录 -- [ ] 管理员菜单 - - [ ] 用户管理 - - [ ] 记录 - - [ ] 日志 - - [ ] 统计 - - [ ] 模板 -- [ ] 路由跳转正确 -- [ ] 当前路由高亮显示 - -### 响应式 -- [ ] 导航栏在不同屏幕尺寸下正确适配 -- [ ] 抽屉菜单在移动端可用 -- [ ] 菜单项在抽屉中垂直排列 - -**备注**: ________________________________________ - ---- - -## 15. 二维码模态框 (QRCodeModal.vue) - -### 功能 -- [ ] 二维码图片正确显示 -- [ ] 进度条显示（如果有） -- [ ] 关闭按钮正常工作 - -### 响应式 -- [ ] 模态框在移动端全宽显示 - -**备注**: ________________________________________ - ---- - -## 16. 自定义组件 - -### CrontabEditor -- [ ] 模式切换标签页显示 -- [ ] 快速模式 - - [ ] 默认 20:00 选项显示 - - [ ] 单选按钮正常工作 -- [ ] 自定义模式 - - [ ] 时间选择器（a-time-picker）正常工作 - - [ ] dayjs 时间格式化正确 - - [ ] 频率选择下拉框 - - [ ] 每天 - - [ ] 工作日（周一-周五） - - [ ] 周末（周六-周日） -- [ ] 高级模式 - - [ ] 原始 crontab 表达式输入框 - - [ ] 帮助文本显示 - - [ ] 外部链接可点击 -- [ ] Cron 表达式验证 -- [ ] 下一个执行时间预览 -- [ ] 验证消息样式（成功、错误、信息） - -### FieldConfigEditor -- [ ] 所有表单字段正常工作 -- [ ] 字段类型切换 - - [ ] 切换到下拉选择时自动添加 options 数组 -- [ ] 值类型切换 - - [ ] 切换到 JSON 时显示 textarea - - [ ] 切换回其他类型时显示 input -- [ ] 必填/隐藏开关互斥 - - [ ] 隐藏时自动取消必填 - - [ ] 隐藏时必填开关禁用 -- [ ] 隐藏时显示 Alert 提示 -- [ ] 下拉选择选项编辑 - - [ ] 添加选项 - - [ ] 编辑显示文本 - - [ ] 编辑选项值 - - [ ] 删除选项 - -### FieldTreeNode -- [ ] 普通字段展示 - - [ ] 蓝色标签和图标 - - [ ] 折叠/展开按钮 - - [ ] 上移/下移按钮 - - [ ] 删除按钮 - - [ ] 字段配置编辑器显示 -- [ ] 数组字段展示 - - [ ] 紫色标签和图标 - - [ ] 添加元素按钮 - - [ ] 元素列表显示 - - [ ] 删除元素按钮 -- [ ] 对象字段展示 - - [ ] 绿色标签和图标 - - [ ] 添加子字段按钮 - - [ ] 子字段递归渲染 -- [ ] 递归嵌套字段正确渲染 -- [ ] 折叠/展开动画流畅 - -**备注**: ________________________________________ - ---- - -## 17. 全局功能 - -### 消息提示 -- [ ] 成功提示（message.success）样式正确 -- [ ] 错误提示（message.error）样式正确 -- [ ] 警告提示（message.warning）样式正确 -- [ ] 提示自动关闭 - -### 确认对话框 -- [ ] Modal.confirm 正确显示 -- [ ] 标题和内容显示 -- [ ] 确认按钮（okText） -- [ ] 取消按钮（cancelText） -- [ ] 确认回调正常执行 -- [ ] 取消回调正常执行 - -### 加载状态 -- [ ] 骨架屏加载（a-skeleton） - - [ ] active 动画效果 - - [ ] 段落行数配置正确 -- [ ] 按钮加载状态（:loading） - - [ ] 加载图标显示 - - [ ] 按钮禁用 -- [ ] 表格加载状态 - - [ ] 加载指示器显示 - -### 表单验证 -- [ ] 必填字段验证 -- [ ] 格式验证（邮箱、密码等） -- [ ] 错误提示显示在字段下方 -- [ ] 验证通过后错误消息清除 - -**备注**: ________________________________________ - ---- - -## 18. 响应式设计总体验证 - -### 断点测试 -- [ ] xs (<576px) - 手机竖屏 -- [ ] sm (≥576px) - 手机横屏/小平板 -- [ ] md (≥768px) - 平板 -- [ ] lg (≥992px) - 桌面 -- [ ] xl (≥1200px) - 大屏桌面 - -### 关键组件响应式 -- [ ] Grid 布局正确响应 - - [ ] a-row / a-col 正确使用 :xs, :sm, :md, :lg 属性 -- [ ] 表格响应式策略 - - [ ] 桌面端: 正常表格 + 水平滚动 - - [ ] 移动端: 卡片视图或隐藏次要列 -- [ ] 对话框响应式 - - [ ] 移动端: 全屏或宽度 100% - - [ ] 桌面端: 固定宽度或百分比宽度 -- [ ] 导航栏响应式 - - [ ] 桌面端: 水平菜单 - - [ ] 移动端: 汉堡图标 + 抽屉菜单 -- [ ] 表单响应式 - - [ ] 字段在小屏幕上堆叠（vertical layout） - -**备注**: ________________________________________ - ---- - -## 19. 性能与兼容性 - -### 构建与性能 -- [ ] `npm run build` 成功无错误 -- [ ] Bundle 大小合理 - - [ ] Ant Design Vue: ~1.2MB (gzipped ~372KB) - - [ ] Vendor: ~345KB (gzipped ~113KB) - - [ ] 总体大小可接受 -- [ ] 无控制台错误 -- [ ] 无控制台警告（除 chunk size 警告外） -- [ ] 页面初始加载速度 <3秒 -- [ ] 组件渲染流畅无卡顿 -- [ ] 表格滚动流畅 -- [ ] 动画流畅（60fps） - -### 浏览器兼容性 -- [ ] Chrome/Edge（最新版） -- [ ] Firefox（最新版） -- [ ] Safari（最新版） -- [ ] iOS Safari -- [ ] Chrome Mobile (Android) - -**测试的浏览器版本**: ________________________________________ - -**备注**: ________________________________________ - ---- - -## 20. 主题与样式 - -### Material Design 3 主题 -- [ ] 主色调一致（绿色 #4caf50） -- [ ] 信息色（蓝色 #2196f3） -- [ ] 成功色（绿色 #4caf50） -- [ ] 警告色（橙色 #ff9800） -- [ ] 错误色（红色 #f56c6c） -- [ ] 卡片样式 - - [ ] fluent-card 类正确应用 - - [ ] md3-card 类正确应用 - - [ ] 圆角 12px - - [ ] 阴影效果正确 -- [ ] 按钮样式 - - [ ] md3-button-filled 填充按钮 - - [ ] md3-button-outlined 描边按钮 - - [ ] md3-button-text 文本按钮 -- [ ] 动画效果 - - [ ] animate-fade-in 淡入动画 - - [ ] animate-slide-up 上滑动画 - - [ ] hover 过渡流畅 - -### Ant Design 主题 -- [ ] Ant Design 组件使用自定义主题 -- [ ] 主色调与 MD3 协调 -- [ ] 组件颜色无冲突 -- [ ] 边框圆角一致（12px） - -### 样式一致性 -- [ ] 字体大小一致 -- [ ] 间距一致 -- [ ] 颜色使用一致 -- [ ] 无样式闪烁或跳动 - -**备注**: ________________________________________ - ---- - -## 已知修复项 ✅ - -以下问题已在迁移过程中修复： - -1. ✅ **FieldConfigEditor** - - v-model 绑定从 `:model-value`/`@update:model-value` 改为 `:value`/`@change` - - `clearable` 改为 `allow-clear` - - `el-alert` → `a-alert`，`title` → `message` + `#description` slot - - 多行文本从 `a-input type="textarea"` 改为 `a-textarea` - - Switch 绑定从 `:model-value` 改为 `:checked` - -2. ✅ **CrontabEditor** - - `el-form` → `a-form` with `:label-col`/`:wrapper-col` - - `el-time-select` → `a-time-picker` with dayjs - - 添加时间转换函数 `onCustomTimeChange` - - Radio 组正确包装 `a-radio` 组件 - -3. ✅ **NotFoundView** - - `el-result` → `a-result` with `status="404"` - -4. ✅ **FieldTreeNode** - - `v-model:open` → `v-model:value` for inputs - - `a-radio label` → `a-radio value` - -5. ✅ **TemplatesView 字段移动功能** - - 使用深拷贝 `JSON.parse(JSON.stringify())` 创建新对象 - - 替换整个 `formData.value` 而不只是 `field_config` - - 新字段正确添加到末尾 - - 字段移动功能正常工作 - ---- - -## 测试优先级 - -### 🔴 P0 - 关键功能（必须通过） -- 登录流程（二维码和密码） -- 仪表盘显示 -- 任务 CRUD 操作 -- 任务打卡 -- 模板管理（特别是字段移动功能） -- 导航功能 -- 无控制台错误 - -### 🟡 P1 - 重要功能 -- 用户管理（管理员） -- 表格分页和排序 -- 表单验证 -- 响应式布局（移动、平板、桌面） -- 消息提示和确认对话框 -- 记录查看 - -### 🟢 P2 - 次要功能 -- 统计信息显示 -- 日志查看 -- 动画效果 -- 主题一致性 -- 性能优化 - ---- - -## 测试结果汇总 - -### 通过统计 -- **P0 通过**: ____ / ____ -- **P1 通过**: ____ / ____ -- **P2 通过**: ____ / ____ -- **总通过率**: _____% - -### 失败项 -1. ________________________________________ -2. ________________________________________ -3. ________________________________________ - -### 阻塞项 -1. ________________________________________ -2. ________________________________________ - -### 性能指标 -- **首次加载时间**: ____ 秒 -- **Bundle 大小**: ____ MB (gzipped: ____ KB) -- **Lighthouse 分数**: - - Performance: ____ - - Accessibility: ____ - - Best Practices: ____ - ---- - -## 建议测试顺序 - -1. **第一轮：核心流程（P0）** - - 登录与认证 - - 导航和布局 - - 仪表盘 - - 任务管理（包括 CrontabEditor） - - 模板管理（包括字段移动） - -2. **第二轮：管理功能（P1）** - - 管理员用户管理 - - 记录管理 - - 表单验证 - -3. **第三轮：响应式和兼容性（P1 + P2）** - - 不同屏幕尺寸测试 - - 不同浏览器测试 - - 性能测试 - -4. **第四轮：细节和优化（P2）** - - 动画效果 - - 主题一致性 - - 边界情况测试 - ---- - -## 测试记录 - -### 测试会话 1 -- **日期**: ________ -- **测试人员**: ________ -- **测试范围**: ________ -- **发现问题**: ________ - -### 测试会话 2 -- **日期**: ________ -- **测试人员**: ________ -- **测试范围**: ________ -- **发现问题**: ________ - -### 测试会话 3 -- **日期**: ________ -- **测试人员**: ________ -- **测试范围**: ________ -- **发现问题**: ________ - ---- - -## 附录 - -### 组件映射速查 - -| Element Plus | Ant Design Vue | 主要变更 | -|-------------|----------------|---------| -| el-card | a-card | `#header` → `#title` | -| el-button | a-button | type 映射相同 | -| el-input | a-input / a-input-password | password 用专门组件 | -| el-form | a-form | 添加 `:layout` prop | -| el-select | a-select | 基本相同 | -| el-table | a-table | 使用 columns 配置 | -| el-pagination | a-pagination | v-model 属性名变更 | -| el-dialog | a-modal | `v-model` → `v-model:open` | -| el-switch | a-switch | `:model-value` → `:checked` | -| el-tag | a-tag | type 映射略不同 | -| el-tabs | a-tabs | `v-model` → `v-model:activeKey` | -| el-alert | a-alert | `:title` → `message` | -| ElMessage | message | 函数式 API 相似 | -| ElMessageBox | Modal.confirm | API 需调整 | - -### 响应式断点 - -```javascript -xs: <576px // 手机 -sm: ≥576px // 平板竖屏 -md: ≥768px // 平板横屏 -lg: ≥992px // 桌面 -xl: ≥1200px // 大屏 -``` - -### 常见问题排查 - -1. **组件不显示** → 检查 v-model 绑定和属性名 -2. **样式不正确** → 检查是否移除了 Element Plus CSS -3. **表格不工作** → 确认使用了 columns 配置 -4. **对话框不显示** → 检查 `v-model:open` 而非 `v-model` -5. **Switch 不工作** → 使用 `:checked` 而非 `:model-value` -6. **时间选择器问题** → 确认使用 dayjs 而非原生 Date - ---- - -## 签字确认 - -**测试人员**: ________________ **日期**: ________ - -**审核人员**: ________________ **日期**: ________ - -**项目负责人**: ________________ **日期**: ________ - ---- - -**迁移完成标准**: -- ✅ P0 功能 100% 通过 -- ✅ P1 功能 ≥95% 通过 -- ✅ 无阻塞性 bug -- ✅ 构建成功无错误 -- ✅ 响应式布局正常 -- ✅ 主要浏览器兼容 - ---- - -## 📱 响应式设计总结 - -### 已实现的响应式优化 - -#### 1. 登录页面 (LoginView.vue) -- ✅ 使用 `position: fixed` 确保全屏布局 -- ✅ 容器设置 `width: 100vw` 和 `height: 100vh` -- ✅ 添加 `overflow-y: auto` 支持内容滚动 -- ✅ 移动端优化 (≤768px): - - 减小边距和内边距 - - 调整字体大小 - - 优化卡片圆角 -- ✅ 小屏手机优化 (≤576px): - - 进一步减小间距 - - 调整标题和文本大小 -- ✅ 横屏优化 (高度≤600px): - - 调整垂直对齐方式 - - 减小间距以适应有限高度 - -#### 2. 导航栏 (Navbar.vue) -- ✅ 使用 `useBreakpoint` composable 检测屏幕尺寸 -- ✅ 桌面端 (≥768px): 水平导航菜单 -- ✅ 移动端 (<768px): 汉堡菜单 + 抽屉导航 -- ✅ 用户菜单响应式显示 -- ✅ 抽屉宽度固定为 280px - -#### 3. 全局样式优化 (style.css) -- ✅ 移动端表格优化 (≤768px): - - 减小字体大小到 13px - - 调整单元格内边距 -- ✅ 移动端表单优化: - - 调整表单项间距 - - 优化标签字体大小 -- ✅ 移动端卡片优化: - - 减小内边距 - - 调整标题大小 -- ✅ 移动端按钮优化: - - 调整按钮高度和内边距 -- ✅ 小屏手机优化 (≤576px): - - 更小的字体和间距 - - 更紧凑的布局 -- ✅ 横屏优化: - - 模态框内容滚动 - - 抽屉内边距调整 -- ✅ 平板优化 (768px-992px): - - 中等尺寸的内边距 - - 适中的表格单元格间距 - -#### 4. 断点系统 (useBreakpoint.js) -```javascript -// 简化断点 -isMobile: <768px // 手机 -isTablet: 768-992px // 平板 -isDesktop: ≥992px // 桌面 - -// Ant Design 断点（详细） -isXs: <576px // 小手机 -isSm: 576-768px // 大手机/小平板 -isMd: 768-992px // 平板 -isLg: 992-1200px // 小桌面 -isXl: 1200-1600px // 桌面 -isXxl: ≥1600px // 大屏 -``` - -#### 5. 页面布局响应式 -- ✅ DashboardView: 使用 `a-col` 响应式属性 - - `:xs="24"` - 手机单列 - - `:sm="24"` - 平板单列 - - `:md="24"` - 桌面全宽 -- ✅ 所有视图都使用 `a-row` 和 `a-col` 实现响应式网格 - -### 响应式测试检查点 - -#### 断点测试 -- [ ] **xs (<576px)** - 小手机竖屏 - - [ ] 登录页面正常显示 - - [ ] 卡片和按钮可点击 - - [ ] 文字可读 - -- [ ] **sm (576-768px)** - 大手机横屏/小平板 - - [ ] 导航抽屉正常工作 - - [ ] 表格可横向滚动 - -- [ ] **md (768-992px)** - 平板 - - [ ] 导航栏切换到水平布局 - - [ ] 卡片网格适配 - -- [ ] **lg (992-1200px)** - 桌面 - - [ ] 所有功能正常显示 - - [ ] 侧边栏和主内容区域合理分布 - -- [ ] **xl (≥1200px)** - 大屏 - - [ ] 布局居中 - - [ ] 最大宽度限制合理 - -#### 设备测试 -- [ ] iPhone SE (375x667) -- [ ] iPhone 12 Pro (390x844) -- [ ] iPad Mini (768x1024) -- [ ] iPad Pro (1024x1366) -- [ ] 桌面 (1920x1080) -- [ ] 4K 显示器 (2560x1440) - -#### 方向测试 -- [ ] 手机竖屏 -- [ ] 手机横屏 (高度受限) -- [ ] 平板竖屏 -- [ ] 平板横屏 - -### 响应式最佳实践 - -1. **使用相对单位** - - 使用 `%`, `vw`, `vh` 而非固定 `px` - - 字体使用 `rem` 或相对大小 - -2. **移动优先设计** - - 先设计移动端体验 - - 使用 `min-width` 媒体查询逐步增强 - -3. **触摸友好** - - 按钮至少 44x44px - - 足够的点击区域间距 - -4. **内容优先级** - - 移动端隐藏次要信息 - - 使用折叠面板节省空间 - -5. **性能考虑** - - 移动端图片优化 - - 懒加载非关键内容 - - 减少动画复杂度 - -### 已知响应式问题和改进建议 - -#### ✅ 已修复 -1. 登录页面高度不足导致布局错乱 → 使用 `position: fixed` 和 `100vh` -2. 移动端表格字体过大 → 添加媒体查询缩小字体 -3. 移动端卡片内边距过大 → 调整内边距 - -#### 🔄 待优化 -1. 表格在小屏幕上可能需要卡片视图替代 -2. 某些对话框在小屏幕可能需要全屏模式 -3. 复杂表单可能需要分步骤向导 - -### 响应式调试技巧 - -1. **Chrome DevTools** - ``` - F12 → Toggle device toolbar (Ctrl+Shift+M) - 选择设备预设或自定义尺寸 - ``` - -2. **实时预览多个尺寸** - ``` - 使用 Responsively App 或类似工具 - 同时查看多个断点 - ``` - -3. **检查元素布局** - ``` - 使用 Chrome Layout 面板 - 查看 box model 和 flexbox/grid 布局 - ``` - -### 响应式 CSS 速查 - -```css -/* 移动端 */ -@media (max-width: 768px) { - /* 移动端样式 */ -} - -/* 小屏手机 */ -@media (max-width: 576px) { - /* 小屏样式 */ -} - -/* 横屏 */ -@media (max-height: 600px) and (orientation: landscape) { - /* 横屏样式 */ -} - -/* 平板 */ -@media (min-width: 768px) and (max-width: 992px) { - /* 平板样式 */ -} - -/* 桌面 */ -@media (min-width: 992px) { - /* 桌面样式 */ -} -``` - ----