学习追踪系统

Appearance

项目委派功能 ​

📋 功能概述 ​

项目委派功能是学习追踪系统中的重要管理功能，允许管理员将学习项目指派给特定的普通用户，实现项目访问权限的精确控制。该功能支持多用户指派和批量操作，提供了直观的模态框界面来简化管理操作。

🎯 核心特性 ​

🔐 权限控制 ​

  • 管理员权限：可以创建项目并指派给一个或多个用户
  • 普通用户权限：只能看到自己创建的项目和指派给自己的项目
  • 强制指派：管理员创建的项目必须指派给至少一个用户才能被使用

👥 多用户指派 ​

  • 支持多选：一个项目可以同时指派给多个用户
  • 批量操作：支持批量指派多个项目给多个用户
  • 灵活管理：可以随时修改项目的指派用户列表

🎨 直观界面 ​

  • 模态框设计：左右两列显示已指派和未指派用户
  • 拖拽式操作：点击用户卡片在两列之间移动
  • 固定高度：模态框高度固定，不会因用户数量变化
  • 背景锁定：模态框打开时阻止背景页面滚动

📊 数据管理 ​

  • 数据库结构：使用 project_assignments 表存储多对多关系
  • 向后兼容：保持对旧 assigned_user_id 字段的兼容性
  • 缓存优化：自动清理相关缓存，确保数据一致性

🗄️ 数据库设计 ​

主要表结构 ​

study_projects 表 ​

sql
-- 保持向后兼容的字段
assigned_user_id INTEGER REFERENCES users(id) -- 第一个指派用户（兼容性）

project_assignments 表（新增） ​

sql
CREATE TABLE project_assignments (
    id SERIAL PRIMARY KEY,
    project_id INTEGER NOT NULL REFERENCES study_projects(id) ON DELETE CASCADE,
    user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    assigned_at TIMESTAMP DEFAULT NOW(),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(project_id, user_id) -- 防止重复指派
);

索引优化 ​

  • project_id 索引：快速查询项目的所有指派用户
  • user_id 索引：快速查询用户的所有指派项目
  • 复合索引：优化多表关联查询

🔌 API 接口 ​

1. 获取项目列表 ​

http
GET /api/projects

权限逻辑：

  • 管理员：可以看到所有项目
  • 普通用户：只能看到自己的项目 + 指派给自己的项目

查询逻辑：

sql
-- 普通用户可见项目查询
WHERE user_id = ? OR 
      EXISTS (SELECT 1 FROM project_assignments 
              WHERE project_id = study_projects.id AND user_id = ?) OR
      assigned_user_id = ? -- 兼容旧字段

2. 创建项目 ​

http
POST /api/projects

请求参数：

json
{
    "name": "项目名称",
    "description": "项目描述",
    "assigned_user_ids": [1, 2, 3] // 多用户指派
}

验证规则：

  • 管理员创建项目时必须选择至少一个指派用户
  • 普通用户创建项目时不需要指派

3. 更新项目 ​

http
PUT /api/projects/:id

请求参数：

json
{
    "name": "项目名称",
    "assigned_user_ids": [1, 2, 3] // 更新指派用户列表
}

4. 批量指派 ​

http
POST /api/projects/batch-assign

请求参数：

json
{
    "project_ids": [1, 2, 3],
    "assigned_user_ids": [1, 2, 3] // 多用户指派，空数组表示取消所有指派
}

功能：

  • 批量更新多个项目的指派用户
  • 支持取消所有指派（传入空数组）
  • 使用事务确保数据一致性
  • 自动清理相关缓存

5. 获取用户列表（用于指派） ​

http
GET /api/projects/users

权限：仅管理员可访问 返回：所有活跃的普通用户列表

🎨 前端界面 ​

创建/编辑项目弹窗 ​

  • 多选下拉框：支持选择多个用户
  • 必填验证：管理员必须选择至少一个用户
  • 用户信息：显示用户名和邮箱

项目列表页面 ​

  • 指派用户列：显示所有指派用户（头像、用户名、邮箱）
  • 批量操作：支持批量指派给多个用户
  • 权限控制：仅管理员可见指派相关功能

批量指派功能 ​

  • 多选项目：复选框选择要指派的项目
  • 模态框界面：左右两列显示已指派和未指派用户
  • 拖拽式操作：点击用户卡片在两列之间移动
  • 实时预览：直观显示指派状态变化
  • 固定高度：模态框高度固定，不会因用户数量变化
  • 背景锁定：模态框打开时阻止背景页面滚动

🔄 业务逻辑 ​

项目可见性规则 ​

  1. 管理员：可以看到所有项目
  2. 普通用户：
    • 自己创建的项目
    • 指派给自己的项目（支持多用户指派）

项目创建规则 ​

  1. 管理员创建：

    • 必须指派给至少一个用户
    • 支持指派给多个用户
    • 项目对未指派用户不可见

  2. 普通用户创建：

    • 不需要指派给其他用户
    • 项目仅自己可见
    • 管理员可以查看和编辑

项目编辑规则 ​

  1. 管理员：可以编辑所有项目，包括修改指派用户
  2. 普通用户：只能编辑自己创建的项目

批量指派规则 ​

  1. 模态框操作：

    • 在模态框中直观地管理用户指派状态
    • 点击用户卡片可以将其在已指派和未指派之间移动
    • 支持实时预览指派状态变化

  2. 批量保存：

    • 一次性保存所有选中项目的指派关系
    • 自动处理用户分配和去重
    • 支持取消所有指派（将用户全部移到未指派列表）

📝 使用场景示例 ​

场景1：初始项目分配 ​

  1. 管理员创建"数学练习"项目
  2. 在批量指派模态框中，将用户A、B、C从右侧移到左侧
  3. 点击"保存指派"
  4. 结果：项目只对A、B、C可见

场景2：后续添加新用户 ​

  1. 项目已指派给用户A、B、C
  2. 新用户D加入系统
  3. 在批量指派模态框中，将用户D从右侧移到左侧
  4. 点击"保存指派"
  5. 结果：项目对A、B、C、D都可见

场景3：重新分配项目 ​

  1. 项目已指派给用户A、B、C、D
  2. 需要重新分配给用户E、F
  3. 在批量指派模态框中，将所有用户移到右侧，然后将E、F移到左侧
  4. 点击"保存指派"
  5. 结果：项目只对E、F可见，A、B、C、D失去访问权限

💾 缓存策略 ​

缓存键设计 ​

projects:{userId}:{userRole}:{page}:{limit}:{status}:{category}:{search}:{created_by}
project-list-chart:{userId}

缓存清理 ​

  • 项目创建/更新/删除时自动清理
  • 指派关系变更时清理相关缓存
  • 支持按用户、角色、筛选条件清理

🔄 兼容性说明 ​

向后兼容 ​

  • 保持对旧 assigned_user_id 字段的支持
  • 查询逻辑同时检查新旧字段
  • 前端显示兼容单用户和多用户指派

数据迁移 ​

  • 自动迁移现有的单用户指派数据
  • 保持数据完整性
  • 支持渐进式升级

🚀 使用示例 ​

管理员创建多用户指派项目 ​

  1. 点击"新建项目"
  2. 填写项目信息
  3. 在"指派给用户"多选框中选择多个用户
  4. 保存项目

批量指派项目（新界面） ​

  1. 在项目列表中选择多个项目（复选框）
  2. 点击"批量指派"按钮
  3. 在弹出的模态框中：
    • 左侧显示已指派用户列表
    • 右侧显示可指派用户列表
    • 点击用户卡片可以将其在两列之间移动
  4. 调整完成后点击"保存指派"
  5. 系统会自动保存所有指派关系

普通用户查看指派项目 ​

  1. 登录系统
  2. 在项目列表中可以看到：
    • 自己创建的项目
    • 管理员指派给自己的项目
  3. 在学习记录页面可以选择这些项目

🔧 技术实现 ​

数据库查询优化 ​

  • 使用 EXISTS 子查询优化多表关联
  • 合理使用索引提升查询性能
  • 支持分页和筛选

前端交互优化 ​

  • 多选下拉框支持搜索和键盘操作
  • 实时验证和错误提示
  • 响应式设计适配不同屏幕

安全性保障 ​

  • 严格的权限验证
  • SQL注入防护
  • XSS攻击防护
  • CSRF保护

📋 更新日志 ​

v3.1 (2025-09-02) ​

  • 🔧 优化项目委派与积分系统的集成
  • ✅ 确保委派项目能正常触发积分规则
  • 🎯 完善项目评级标准与积分获取的关联
  • 📊 优化项目委派后的积分统计功能

v3.0 (2025-01-17) ​

  • ✨ 重新设计批量指派界面
  • 🎨 新增模态框界面，左右两列显示用户
  • 🖱️ 支持点击用户卡片在两列之间移动
  • 📏 固定模态框高度，防止页面撑开
  • 🔒 阻止背景页面滚动
  • 🔧 简化API接口，移除复杂的模式选择

v2.1 (2025-01-17) ​

  • ✨ 新增追加模式功能
  • 🔄 支持保留现有用户，添加新用户
  • 🎯 新增指派模式选择（覆盖/追加）
  • 💬 增强确认对话框，显示详细操作信息
  • 🔧 优化批量指派逻辑，支持智能去重

v2.0 (2025-01-17) ​

  • ✨ 新增多用户指派功能
  • 🗄️ 新增 project_assignments 表
  • 🔄 更新API接口支持多用户指派
  • 🎨 更新前端界面支持多选
  • 🔧 优化查询性能和缓存策略

v1.0 (2025-01-17) ​

  • 🎯 基础项目指派功能
  • 👤 单用户指派支持
  • 🔐 权限控制机制
  • 📊 批量操作功能

💡 提示

项目委派功能是管理员管理学习项目的重要工具，合理使用可以提高项目管理的效率和精确度。建议定期检查和调整项目指派关系，确保用户能够访问到合适的项目。

Released under the MIT License.

Copyright © 2024-present Study Tracker Team