all-project/docs/开发文档/API/后端API数据格式示例-班级名额显示.md

后端API数据格式示例 - 班级名额显示功能

创建时间: 2025-01-27
功能: 班主任批量申请奖学金页面显示班级名额和全校名额
接口: getScholarshipTypesWithQuota(batchId, classId)

📋 接口说明

接口路径

GET /jcbt/scholarshipApplication/scholarshipTypesWithQuota

请求参数

{
  "batchId": "批次ID",
  "classId": "班级ID"
}

🎯 返回数据结构

完整数据格式

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "name": "国家奖学金",
      "amount": 8000,
      "levelType": "国家级",
      "typeCategory": "奖学金",
      
      // 班级名额信息（优先显示）
      "classQuota": {
        "hasQuota": true,
        "totalQuota": 5,
        "usedQuota": 2,
        "availableQuota": 3,
        "quotaStatus": "available"
      },
      
      // 全校名额信息（参考显示）
      "schoolQuota": {
        "hasQuota": true,
        "totalQuota": 100,
        "usedQuota": 30,
        "availableQuota": 70,
        "quotaStatus": "available"
      }
    },
    {
      "id": 2,
      "name": "省政府奖学金",
      "amount": 6000,
      "levelType": "省级",
      "typeCategory": "奖学金",
      
      // 班级名额已满的情况
      "classQuota": {
        "hasQuota": true,
        "totalQuota": 2,
        "usedQuota": 2,
        "availableQuota": 0,
        "quotaStatus": "full"
      },
      
      "schoolQuota": {
        "hasQuota": true,
        "totalQuota": 50,
        "usedQuota": 35,
        "availableQuota": 15,
        "quotaStatus": "available"
      }
    },
    {
      "id": 3,
      "name": "学院奖学金",
      "amount": 2000,
      "levelType": "校级",
      "typeCategory": "奖学金",
      
      // 无班级名额限制，只有全校名额
      "classQuota": null,
      
      "schoolQuota": {
        "hasQuota": false,
        "totalQuota": 0,
        "usedQuota": 0,
        "availableQuota": 0,
        "quotaStatus": "unlimited"
      }
    }
  ]
}

🔧 数据字段说明

基础字段

字段名	类型	说明
id	Long	奖学金类型ID
name	String	奖学金名称
amount	BigDecimal	奖学金金额
levelType	String	等级类型（国家级、省级、校级等）
typeCategory	String	类型分类

班级名额字段 (classQuota)

字段名	类型	说明
hasQuota	Boolean	是否有班级名额限制
totalQuota	Integer	班级总名额
usedQuota	Integer	班级已用名额
availableQuota	Integer	班级可用名额
quotaStatus	String	班级名额状态

全校名额字段 (schoolQuota)

字段名	类型	说明
hasQuota	Boolean	是否有全校名额限制
totalQuota	Integer	全校总名额
usedQuota	Integer	全校已用名额
availableQuota	Integer	全校可用名额
quotaStatus	String	全校名额状态

📊 名额状态说明

quotaStatus 枚举值

状态值	说明	前端显示
available	有可用名额	绿色标签 "可申请"
full	名额已满	橙色标签 "已满"
unlimited	无名额限制	蓝色标签 "无限制"

🎨 前端显示逻辑

1. 标签颜色优先级

// 优先基于班级名额状态
if (type.classQuota && type.classQuota.hasQuota) {
  return type.classQuota.quotaStatus === 'available' ? 'success' : 'warning';
}

// 其次基于全校名额状态
if (type.schoolQuota) {
  return type.schoolQuota.quotaStatus === 'unlimited' ? 'info' : 
         type.schoolQuota.quotaStatus === 'available' ? 'success' : 'warning';
}

2. 可选择性判断

// 优先基于班级名额
if (type.classQuota && type.classQuota.hasQuota) {
  return type.classQuota.availableQuota > 0;
}

// 其次基于全校名额
if (type.schoolQuota) {
  return type.schoolQuota.quotaStatus === 'unlimited' || 
         type.schoolQuota.availableQuota > 0;
}

3. 显示文本格式

班级名额: 3/5 | 全校名额: 70/100
班级名额: 0/2 (已满) | 全校名额: 15/50  
全校名额: 无限制

🚨 重要说明

数据一致性要求

1. 班级名额计算: availableQuota = totalQuota - usedQuota
2. 状态同步: quotaStatus 必须与实际名额数量一致
3. 实时性: 名额信息应该实时更新，反映当前最新状态

兼容性处理

• 如果后端暂时无法提供新格式数据，前端会自动降级到旧格式显示
• 支持 classQuota 为 null 的情况，此时只显示全校名额
• 保持与现有API的向后兼容性

权限控制

• 确保班主任只能看到自己班级的名额分配情况
• 不同班级的名额信息应该隔离
• 接口需要验证 classId 与当前用户的权限匹配

📝 后端实现建议

SQL查询示例

-- 查询班级名额分配情况
SELECT 
    st.id,
    st.name,
    st.amount,
    st.level_type,
    st.type_category,
    
    -- 班级名额信息
    cq.total_quota as class_total_quota,
    cq.used_quota as class_used_quota,
    (cq.total_quota - cq.used_quota) as class_available_quota,
    CASE 
        WHEN cq.total_quota IS NULL THEN NULL
        WHEN (cq.total_quota - cq.used_quota) > 0 THEN 'available'
        ELSE 'full'
    END as class_quota_status,
    
    -- 全校名额信息  
    sq.total_quota as school_total_quota,
    sq.used_quota as school_used_quota,
    (sq.total_quota - sq.used_quota) as school_available_quota,
    CASE
        WHEN sq.has_quota = 0 THEN 'unlimited'
        WHEN (sq.total_quota - sq.used_quota) > 0 THEN 'available' 
        ELSE 'full'
    END as school_quota_status
    
FROM scholarship_type st
LEFT JOIN class_quota cq ON st.id = cq.scholarship_type_id AND cq.class_id = ?
LEFT JOIN school_quota sq ON st.id = sq.scholarship_type_id
WHERE st.batch_id = ?

Java实体类建议

@Data
public class ScholarshipTypeWithQuotaVO {
    private Long id;
    private String name;
    private BigDecimal amount;
    private String levelType;
    private String typeCategory;
    
    private QuotaInfo classQuota;
    private QuotaInfo schoolQuota;
}

@Data
public class QuotaInfo {
    private Boolean hasQuota;
    private Integer totalQuota;
    private Integer usedQuota;
    private Integer availableQuota;
    private String quotaStatus;
}

---

文档更新: 2025-01-27
状态: 待后端实现
前端适配: 已完成