# 科研创新与学科竞赛综合管理系统 API接口规范文档

## 文档信息
- **版本**: v1.0
- **创建日期**: 2024年
- **API版本**: v1
- **基础URL**: `https://api.inno-res-comp.edu.cn/v1`

## 目录
1. [接口设计原则](#接口设计原则)
2. [通用规范](#通用规范)
3. [认证与授权](#认证与授权)
4. [用户管理模块API](#用户管理模块api)
5. [产教融合模块API](#产教融合模块api)
6. [学科竞赛模块API](#学科竞赛模块api)
7. [实验室管理模块API](#实验室管理模块api)
8. [工作室建设与管理模块API](#工作室建设与管理模块api)
9. [科研与国际化模块API](#科研与国际化模块api)
10. [系统管理模块API](#系统管理模块api)
11. [错误码定义](#错误码定义)

## 接口设计原则

### RESTful设计原则
- 使用HTTP动词表示操作：GET(查询)、POST(创建)、PUT(更新)、DELETE(删除)
- 使用名词表示资源，避免动词
- 使用复数形式表示资源集合
- 使用嵌套路径表示资源关系

### 响应格式统一
所有API响应均采用以下JSON格式：
```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": "2024-01-01T12:00:00Z",
  "requestId": "uuid"
}
```

### 分页格式统一
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  }
}
```

## 通用规范

### 请求头
```
Content-Type: application/json
Authorization: Bearer {token}
X-Request-ID: {uuid}
X-Client-Version: 1.0.0
```

### 状态码
- 200: 成功
- 201: 创建成功
- 400: 请求参数错误
- 401: 未授权
- 403: 权限不足
- 404: 资源不存在
- 409: 资源冲突
- 422: 数据验证失败
- 500: 服务器内部错误

### 时间格式
统一使用ISO 8601格式：`2024-01-01T12:00:00Z`

### 分页参数
- `page`: 页码，从1开始
- `size`: 每页大小，默认20，最大100
- `sort`: 排序字段，格式：`field,direction`（如：`createdAt,desc`）

## 认证与授权

### 登录认证
```http
POST /auth/login
Content-Type: application/json

{
  "username": "string",
  "password": "string",
  "captcha": "string",
  "captchaId": "string"
}
```

**响应**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 7200,
    "user": {
      "id": 1,
      "username": "admin",
      "realName": "管理员",
      "email": "admin@example.com",
      "roles": ["ADMIN"],
      "permissions": ["*"]
    }
  }
}
```

### 刷新Token
```http
POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "string"
}
```

### 登出
```http
POST /auth/logout
Authorization: Bearer {token}
```

## 用户管理模块API

### 用户信息管理

#### 获取用户列表
```http
GET /users?page=1&size=20&keyword=&departmentId=&status=
Authorization: Bearer {token}
```

**查询参数**:
- `keyword`: 关键词搜索（用户名、姓名、邮箱）
- `departmentId`: 部门ID
- `status`: 用户状态（0-禁用，1-启用）

**响应**:
```json
{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "username": "student001",
        "realName": "张三",
        "email": "zhangsan@example.com",
        "phone": "13800138000",
        "department": {
          "id": 1,
          "name": "计算机学院"
        },
        "roles": ["STUDENT"],
        "status": 1,
        "lastLoginTime": "2024-01-01T12:00:00Z",
        "createdAt": "2024-01-01T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  }
}
```

#### 获取用户详情
```http
GET /users/{id}
Authorization: Bearer {token}
```

#### 创建用户
```http
POST /users
Authorization: Bearer {token}
Content-Type: application/json

{
  "username": "string",
  "password": "string",
  "realName": "string",
  "email": "string",
  "phone": "string",
  "departmentId": 1,
  "roleIds": [1, 2],
  "gender": 1,
  "birthDate": "1990-01-01"
}
```

#### 更新用户
```http
PUT /users/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "realName": "string",
  "email": "string",
  "phone": "string",
  "departmentId": 1,
  "status": 1
}
```

#### 删除用户
```http
DELETE /users/{id}
Authorization: Bearer {token}
```

#### 重置密码
```http
POST /users/{id}/reset-password
Authorization: Bearer {token}
Content-Type: application/json

{
  "newPassword": "string"
}
```

### 角色权限管理

#### 获取角色列表
```http
GET /roles?page=1&size=20
Authorization: Bearer {token}
```

#### 创建角色
```http
POST /roles
Authorization: Bearer {token}
Content-Type: application/json

{
  "roleName": "string",
  "roleCode": "string",
  "description": "string",
  "permissions": ["permission1", "permission2"]
}
```

#### 更新角色
```http
PUT /roles/{id}
Authorization: Bearer {token}
```

#### 删除角色
```http
DELETE /roles/{id}
Authorization: Bearer {token}
```

### 部门管理

#### 获取部门树
```http
GET /departments/tree
Authorization: Bearer {token}
```

#### 创建部门
```http
POST /departments
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "string",
  "code": "string",
  "parentId": 0,
  "managerId": 1,
  "description": "string"
}
```

## 产教融合模块API

### 企业管理

#### 获取企业列表
```http
GET /enterprises?page=1&size=20&keyword=&industry=&enterpriseType=
Authorization: Bearer {token}
```

**查询参数**:
- `keyword`: 企业名称关键词
- `industry`: 所属行业
- `enterpriseType`: 企业类型（1-国企，2-民企，3-外企，4-合资）

#### 创建企业
```http
POST /enterprises
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "string",
  "shortName": "string",
  "unifiedSocialCreditCode": "string",
  "enterpriseType": 1,
  "industry": "string",
  "scale": 1,
  "contactPerson": "string",
  "contactPhone": "string",
  "contactEmail": "string",
  "address": "string",
  "website": "string",
  "businessScope": "string",
  "tags": ["技术领域1", "设备类型1"]
}
```

#### 智能匹配推荐
```http
POST /enterprises/match-recommendations
Authorization: Bearer {token}
Content-Type: application/json

{
  "departmentId": 1,
  "technicalFields": ["AI", "大数据"],
  "cooperationType": 1,
  "budgetRange": [10000, 100000]
}
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "recommendations": [
      {
        "enterprise": {
          "id": 1,
          "name": "科技公司A",
          "industry": "人工智能"
        },
        "matchScore": 8.5,
        "matchReasons": ["技术领域匹配", "合作历史良好"],
        "cooperationPotential": "高"
      }
    ],
    "heatMap": {
      "demandSupplyGap": {
        "AI": 0.8,
        "大数据": 0.6
      }
    }
  }
}
```

### 校企合作项目管理

#### 获取合作项目列表
```http
GET /cooperation-projects?page=1&size=20&projectType=&progressStatus=&enterpriseId=
Authorization: Bearer {token}
```

#### 创建合作项目
```http
POST /cooperation-projects
Authorization: Bearer {token}
Content-Type: application/json

{
  "projectName": "string",
  "projectCode": "string",
  "enterpriseId": 1,
  "departmentId": 1,
  "projectType": 1,
  "cooperationMode": 1,
  "projectLeaderId": 1,
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "budget": 100000,
  "projectDescription": "string",
  "objectives": "string",
  "deliverables": "string"
}
```

#### 更新项目进度
```http
PUT /cooperation-projects/{id}/progress
Authorization: Bearer {token}
Content-Type: application/json

{
  "progressStatus": 2,
  "progressPercentage": 50,
  "progressDescription": "string",
  "nextMilestone": "string",
  "riskAssessment": "string"
}
```

#### 三维进度管理
```http
GET /cooperation-projects/{id}/progress-dashboard
Authorization: Bearer {token}
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "administrativeProgress": {
      "percentage": 60,
      "milestones": [
        {
          "name": "合同签署",
          "status": "completed",
          "completedAt": "2024-01-15T10:00:00Z"
        }
      ]
    },
    "academicProgress": {
      "percentage": 45,
      "milestones": [
        {
          "name": "需求分析",
          "status": "in_progress",
          "expectedAt": "2024-02-01T10:00:00Z"
        }
      ]
    },
    "financialProgress": {
      "percentage": 30,
      "budgetUsed": 30000,
      "budgetTotal": 100000,
      "milestones": [
        {
          "name": "首期款项",
          "status": "completed",
          "amount": 30000
        }
      ]
    },
    "riskWarnings": [
      {
        "level": "medium",
        "message": "学术进度略有延迟",
        "suggestion": "建议增加人力投入"
      }
    ]
  }
}
```

### 技术成熟度评估

#### 创建评估
```http
POST /tech-maturity-assessments
Authorization: Bearer {token}
Content-Type: application/json

{
  "projectId": 1,
  "technologyReadinessLevel": 5,
  "marketReadinessScore": 7.5,
  "commercialPotentialScore": 8.0,
  "riskLevel": 2,
  "assessmentContent": "string",
  "improvementSuggestions": "string",
  "nextMilestone": "string"
}
```

#### 获取评估历史
```http
GET /tech-maturity-assessments?projectId=1
Authorization: Bearer {token}
```

### 路演匹配系统

#### 自动推送投资机构
```http
POST /roadshow-matches/auto-match
Authorization: Bearer {token}
Content-Type: application/json

{
  "projectId": 1,
  "investmentStage": "A轮",
  "fundingAmount": 5000000,
  "industryPreference": ["人工智能", "大数据"]
}
```

#### 创建路演安排
```http
POST /roadshow-matches
Authorization: Bearer {token}
Content-Type: application/json

{
  "projectId": 1,
  "investorType": 2,
  "investorName": "string",
  "contactPerson": "string",
  "contactInfo": "string",
  "roadshowDate": "2024-02-01T14:00:00Z"
}
```

## 学科竞赛模块API

### 竞赛信息管理

#### 获取竞赛列表
```http
GET /competitions?page=1&size=20&competitionType=&level=&year=&status=
Authorization: Bearer {token}
```

#### 创建竞赛
```http
POST /competitions
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "string",
  "englishName": "string",
  "competitionCode": "string",
  "competitionType": 1,
  "level": 2,
  "category": "string",
  "organizer": "string",
  "competitionYear": 2024,
  "registrationStartDate": "2024-03-01",
  "registrationEndDate": "2024-03-31",
  "competitionStartDate": "2024-04-01",
  "competitionEndDate": "2024-04-30",
  "venue": "string",
  "description": "string",
  "prizeSetting": "string",
  "maxTeamSize": 5
}
```

### 获奖信息管理

#### 提交获奖信息
```http
POST /awards
Authorization: Bearer {token}
Content-Type: multipart/form-data

{
  "competitionId": 1,
  "awardName": "string",
  "awardLevel": 2,
  "teamName": "string",
  "isTeam": 1,
  "teamLeaderId": 1,
  "teamMembers": [2, 3, 4],
  "instructorId": 5,
  "workTitle": "string",
  "workDescription": "string",
  "certificateNumber": "string",
  "awardDate": "2024-04-30",
  "certificate": "file",
  "supportingMaterials": ["file1", "file2"]
}
```

#### 获奖信息审核
```http
PUT /awards/{id}/audit
Authorization: Bearer {token}
Content-Type: application/json

{
  "auditStatus": 1,
  "auditComment": "string",
  "requiredMaterials": "string"
}
```

#### 智能查询系统
```http
GET /awards/search?keyword=&competitionType=&level=&awardLevel=&year=&instructorId=&studentId=&auditStatus=
Authorization: Bearer {token}
```

**查询参数**:
- `keyword`: 关键词（竞赛名称、获奖名称、作品标题）
- `competitionType`: 竞赛类型
- `level`: 竞赛级别
- `awardLevel`: 获奖等级
- `year`: 获奖年份
- `instructorId`: 指导教师ID
- `studentId`: 学生ID
- `auditStatus`: 审核状态

#### 一键Excel导出
```http
GET /awards/export?format=excel&filters={}
Authorization: Bearer {token}
```

**响应**: 返回Excel文件流

### 个人空间模块

#### 获取个人获奖记录
```http
GET /awards/personal?userId=1&page=1&size=20
Authorization: Bearer {token}
```

#### 获奖记录进度追踪
```http
GET /awards/{id}/progress
Authorization: Bearer {token}
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "currentStatus": "审核中",
    "progressSteps": [
      {
        "step": "提交申请",
        "status": "completed",
        "completedAt": "2024-01-01T10:00:00Z"
      },
      {
        "step": "材料审核",
        "status": "in_progress",
        "startedAt": "2024-01-02T09:00:00Z"
      },
      {
        "step": "公示期",
        "status": "pending"
      },
      {
        "step": "审核完成",
        "status": "pending"
      }
    ],
    "estimatedCompletionTime": "2024-01-10T17:00:00Z",
    "nextAction": "等待审核结果"
  }
}
```

## 实验室管理模块API

### 实验室信息管理

#### 获取实验室列表
```http
GET /laboratories?page=1&size=20&labType=&departmentId=&status=
Authorization: Bearer {token}
```

#### 创建实验室
```http
POST /laboratories
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "string",
  "labCode": "string",
  "labType": 1,
  "departmentId": 1,
  "building": "string",
  "floor": "string",
  "roomNumber": "string",
  "area": 100.5,
  "capacity": 30,
  "managerId": 1,
  "assistantManagers": [2, 3],
  "safetyLevel": 2,
  "accessControl": 1,
  "openingHours": "string",
  "description": "string",
  "rules": "string"
}
```

### 设备管理

#### 获取设备列表
```http
GET /equipment?page=1&size=20&labId=&equipmentType=&status=&usageStatus=
Authorization: Bearer {token}
```

#### 创建设备
```http
POST /equipment
Authorization: Bearer {token}
Content-Type: application/json

{
  "labId": 1,
  "equipmentName": "string",
  "equipmentCode": "string",
  "equipmentType": 1,
  "brand": "string",
  "model": "string",
  "specifications": "string",
  "purchaseDate": "2024-01-01",
  "purchasePrice": 50000,
  "supplier": "string",
  "warrantyPeriod": 36,
  "location": "string",
  "responsiblePersonId": 1,
  "remoteControllable": 1,
  "remoteControlUrl": "string"
}
```

#### 设备状态监控
```http
GET /equipment/{id}/status
Authorization: Bearer {token}
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "equipmentId": 1,
    "equipmentName": "高性能计算机",
    "networkStatus": 1,
    "powerStatus": 1,
    "usageStatus": 0,
    "currentUser": null,
    "temperature": 45.5,
    "cpuUsage": 15.2,
    "memoryUsage": 32.8,
    "diskUsage": 68.5,
    "lastHeartbeat": "2024-01-01T12:00:00Z",
    "uptime": "72:15:30"
  }
}
```

### 设备借用管理

#### 申请设备借用
```http
POST /equipment-borrowings
Authorization: Bearer {token}
Content-Type: application/json

{
  "equipmentId": 1,
  "borrowerType": 1,
  "purpose": "string",
  "projectId": 1,
  "plannedStartTime": "2024-01-01T09:00:00Z",
  "plannedEndTime": "2024-01-01T17:00:00Z",
  "usageNotes": "string"
}
```

#### 审批借用申请
```http
PUT /equipment-borrowings/{id}/approve
Authorization: Bearer {token}
Content-Type: application/json

{
  "approved": true,
  "approvalComment": "string"
}
```

#### 设备归还
```http
PUT /equipment-borrowings/{id}/return
Authorization: Bearer {token}
Content-Type: application/json

{
  "returnCondition": "string",
  "damageDescription": "string",
  "rating": 5,
  "feedback": "string"
}
```

#### 获取借用记录
```http
GET /equipment-borrowings?page=1&size=20&equipmentId=&borrowerId=&status=&startDate=&endDate=
Authorization: Bearer {token}
```

### 远程设备控制

#### 远程开机
```http
POST /equipment/{id}/remote-control/power-on
Authorization: Bearer {token}
```

#### 远程关机
```http
POST /equipment/{id}/remote-control/power-off
Authorization: Bearer {token}
Content-Type: application/json

{
  "force": false,
  "delaySeconds": 60
}
```

#### 远程重启
```http
POST /equipment/{id}/remote-control/restart
Authorization: Bearer {token}
```

#### 获取远程控制日志
```http
GET /equipment/{id}/remote-control/logs?page=1&size=20
Authorization: Bearer {token}
```

#### 网络连接提醒
```http
POST /equipment/{id}/network-reminder
Authorization: Bearer {token}
Content-Type: application/json

{
  "message": "请勿拔除网线，以免影响远程控制功能",
  "reminderType": "popup"
}
```

## 工作室建设与管理模块API

### 学生能力信息化

#### 获取学生技能标签
```http
GET /student-skills?studentId=1&skillCategory=&verified=
Authorization: Bearer {token}
```

#### 添加技能标签
```http
POST /student-skills
Authorization: Bearer {token}
Content-Type: application/json

{
  "studentId": 1,
  "skillCategory": 1,
  "skillName": "Java编程",
  "skillLevel": 3,
  "proficiencyScore": 8.5,
  "certificationName": "Oracle Java认证",
  "certificationUrl": "string",
  "certificationDate": "2024-01-01",
  "selfAssessment": "string",
  "projectExperience": "string"
}
```

#### 技能验证
```http
PUT /student-skills/{id}/verify
Authorization: Bearer {token}
Content-Type: application/json

{
  "verified": true,
  "teacherAssessment": "string",
  "adjustedLevel": 3,
  "adjustedScore": 8.0
}
```

#### 获取学生可用时间
```http
GET /student-availability?studentId=1&semester=2024春
Authorization: Bearer {token}
```

#### 设置可用时间
```http
POST /student-availability
Authorization: Bearer {token}
Content-Type: application/json

{
  "studentId": 1,
  "semester": "2024春",
  "weekDay": 1,
  "startTime": "09:00:00",
  "endTime": "17:00:00",
  "availabilityType": 1,
  "description": "空闲时间",
  "isFlexible": 1,
  "priority": 3
}
```

### 项目管理

#### 获取项目列表
```http
GET /projects?page=1&size=20&projectType=&teacherId=&departmentId=&recruitmentStatus=&projectStatus=
Authorization: Bearer {token}
```

#### 创建项目
```http
POST /projects
Authorization: Bearer {token}
Content-Type: application/json

{
  "projectName": "string",
  "projectCode": "string",
  "projectType": 1,
  "projectCategory": "string",
  "teacherId": 1,
  "coTeachers": [2, 3],
  "departmentId": 1,
  "projectDescription": "string",
  "objectives": "string",
  "expectedOutcomes": "string",
  "technicalRequirements": "string",
  "skillRequirements": ["Java", "Spring Boot", "MySQL"],
  "teamSizeMin": 3,
  "teamSizeMax": 6,
  "difficultyLevel": 2,
  "estimatedDuration": 120,
  "startDate": "2024-01-01",
  "endDate": "2024-05-01",
  "budget": 10000
}
```

#### 项目可视化仪表盘
```http
GET /projects/{id}/dashboard
Authorization: Bearer {token}
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "projectOverview": {
      "id": 1,
      "name": "智能推荐系统",
      "status": "进行中",
      "phase": "开发阶段",
      "progressPercentage": 65,
      "healthStatus": "健康",
      "daysRemaining": 45
    },
    "teamComposition": {
      "totalMembers": 5,
      "memberRoles": [
        {"role": "组长", "count": 1},
        {"role": "核心成员", "count": 2},
        {"role": "普通成员", "count": 2}
      ],
      "workloadDistribution": [
        {"memberId": 1, "memberName": "张三", "workloadPercentage": 25},
        {"memberId": 2, "memberName": "李四", "workloadPercentage": 20}
      ]
    },
    "taskStatistics": {
      "totalTasks": 20,
      "completedTasks": 13,
      "inProgressTasks": 5,
      "pendingTasks": 2,
      "tasksByType": [
        {"type": "需求分析", "count": 3, "completed": 3},
        {"type": "设计", "count": 5, "completed": 4},
        {"type": "开发", "count": 8, "completed": 4},
        {"type": "测试", "count": 4, "completed": 2}
      ]
    },
    "qualityMetrics": {
      "qualityScore": 8.5,
      "reworkCount": 3,
      "reworkRate": 15,
      "codeReviewPassRate": 85,
      "testCoverage": 78
    },
    "riskAssessment": {
      "overallRisk": "低",
      "riskFactors": [
        {
          "factor": "进度风险",
          "level": "低",
          "description": "当前进度正常"
        },
        {
          "factor": "质量风险",
          "level": "中",
          "description": "部分模块需要重构"
        }
      ]
    }
  }
}
```

#### 智能匹配推荐
```http
POST /projects/{id}/match-students
Authorization: Bearer {token}
Content-Type: application/json

{
  "requiredSkills": ["Java", "Spring Boot"],
  "preferredLevel": 2,
  "timeRequirement": 20,
  "teamRole": 2
}
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "recommendations": [
      {
        "student": {
          "id": 1,
          "name": "王五",
          "department": "计算机学院",
          "grade": "大三"
        },
        "matchScore": 9.2,
        "skillMatch": {
          "Java": {"level": 3, "score": 8.5},
          "Spring Boot": {"level": 2, "score": 7.0}
        },
        "availableTime": 25,
        "previousProjects": 2,
        "averageRating": 4.5,
        "matchReasons": [
          "技能匹配度高",
          "时间充足",
          "项目经验丰富"
        ]
      }
    ]
  }
}
```

### 项目成员管理

#### 获取项目成员
```http
GET /projects/{id}/members
Authorization: Bearer {token}
```

#### 添加项目成员
```http
POST /projects/{id}/members
Authorization: Bearer {token}
Content-Type: application/json

{
  "studentId": 1,
  "memberRole": 2,
  "responsibilities": "string",
  "plannedWorkload": 20
}
```

#### 更新成员表现
```http
PUT /project-members/{id}/performance
Authorization: Bearer {token}
Content-Type: application/json

{
  "actualWorkload": 22,
  "contributionRate": 18.5,
  "performanceScore": 8.5,
  "attendanceRate": 95,
  "taskCompletionRate": 90,
  "qualityRating": 4,
  "collaborationRating": 5,
  "innovationRating": 4,
  "achievements": "string",
  "feedbackFromTeacher": "string"
}
```

### 任务管理

#### 获取项目任务
```http
GET /projects/{id}/tasks?assigneeId=&taskStatus=&taskType=
Authorization: Bearer {token}
```

#### 创建任务
```http
POST /project-tasks
Authorization: Bearer {token}
Content-Type: application/json

{
  "projectId": 1,
  "parentTaskId": 0,
  "taskName": "string",
  "taskDescription": "string",
  "taskType": 3,
  "priority": 3,
  "difficulty": 2,
  "estimatedHours": 16,
  "assigneeId": 1,
  "reviewerId": 2,
  "plannedStartDate": "2024-01-01",
  "plannedEndDate": "2024-01-05",
  "acceptanceCriteria": "string"
}
```

#### 更新任务进度
```http
PUT /project-tasks/{id}/progress
Authorization: Bearer {token}
Content-Type: application/json

{
  "progressPercentage": 50,
  "actualHours": 8,
  "progressDescription": "string",
  "deliverables": "string",
  "notes": "string"
}
```

#### 任务返工追踪
```http
POST /project-tasks/{id}/rework
Authorization: Bearer {token}
Content-Type: application/json

{
  "reworkReason": "string",
  "qualityIssues": "string",
  "improvementPlan": "string"
}
```

### 项目申请与遴选

#### 学生申请加入项目
```http
POST /project-applications
Authorization: Bearer {token}
Content-Type: application/json

{
  "projectId": 1,
  "applicationType": 1,
  "desiredRole": 2,
  "motivation": "string",
  "relevantSkills": ["Java", "MySQL"],
  "previousExperience": "string",
  "availableTimePerWeek": 20,
  "expectedContribution": "string",
  "portfolioUrl": "string"
}
```

#### 教师审核申请
```http
PUT /project-applications/{id}/review
Authorization: Bearer {token}
Content-Type: application/json

{
  "applicationStatus": 2,
  "reviewComment": "string",
  "interviewRequired": 1,
  "interviewTime": "2024-01-05T14:00:00Z"
}
```

#### 获取申请列表
```http
GET /project-applications?projectId=1&studentId=&applicationStatus=
Authorization: Bearer {token}
```

## 科研与国际化模块API

### 短期交流项目

#### 获取交流项目列表
```http
GET /exchange-programs?page=1&size=20&programType=&partnerCountry=&targetAudience=&programStatus=
Authorization: Bearer {token}
```

#### 创建交流项目
```http
POST /exchange-programs
Authorization: Bearer {token}
Content-Type: application/json

{
  "programName": "string",
  "programCode": "string",
  "programType": 1,
  "partnerInstitution": "string",
  "partnerCountry": "string",
  "partnerCity": "string",
  "programDuration": 30,
  "startDate": "2024-06-01",
  "endDate": "2024-06-30",
  "applicationDeadline": "2024-04-01",
  "maxParticipants": 20,
  "targetAudience": 1,
  "languageRequirement": "英语四级",
  "gpaRequirement": 3.0,
  "majorRequirements": ["计算机", "软件工程"],
  "programDescription": "string",
  "learningObjectives": "string",
  "activities": "string",
  "accommodationInfo": "string",
  "costInfo": "string",
  "scholarshipAvailable": 1,
  "scholarshipAmount": 5000
}
```

#### 快速报名
```http
POST /exchange-programs/{id}/apply
Authorization: Bearer {token}
Content-Type: multipart/form-data

{
  "applicationForm": "json",
  "motivationLetter": "file",
  "recommendationLetters": ["file1", "file2"],
  "transcript": "file",
  "languageCertificate": "file",
  "passport": "file",
  "currentGpa": 3.5,
  "languageProficiency": "CET-6",
  "previousExperience": "string",
  "specialRequirements": "string",
  "emergencyContact": "json"
}
```

#### 申请状态查询
```http
GET /exchange-applications/{id}/status
Authorization: Bearer {token}
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "applicationId": 1,
    "currentStatus": "初审通过",
    "statusCode": 2,
    "progressSteps": [
      {
        "step": "提交申请",
        "status": "completed",
        "completedAt": "2024-01-01T10:00:00Z"
      },
      {
        "step": "材料审核",
        "status": "completed",
        "completedAt": "2024-01-05T15:00:00Z"
      },
      {
        "step": "面试环节",
        "status": "scheduled",
        "scheduledAt": "2024-01-10T14:00:00Z"
      },
      {
        "step": "最终录取",
        "status": "pending"
      }
    ],
    "nextAction": "准备面试",
    "interviewInfo": {
      "time": "2024-01-10T14:00:00Z",
      "location": "国际交流中心201室",
      "interviewer": "张教授",
      "requirements": "请携带相关证书原件"
    },
    "estimatedResult": "2024-01-15T17:00:00Z"
  }
}
```

### 科研项目管理

#### 获取科研项目列表
```http
GET /research-projects?page=1&size=20&projectType=&researchField=&currentPhase=&projectStatus=
Authorization: Bearer {token}
```

#### 创建科研项目
```http
POST /research-projects
Authorization: Bearer {token}
Content-Type: application/json

{
  "projectName": "string",
  "projectCode": "string",
  "projectType": 1,
  "fundingAgency": "string",
  "principalInvestigatorId": 1,
  "coInvestigators": [2, 3],
  "departmentId": 1,
  "researchField": "string",
  "keywords": ["AI", "机器学习"],
  "projectAbstract": "string",
  "researchObjectives": "string",
  "researchMethodology": "string",
  "expectedOutcomes": "string",
  "innovationPoints": "string",
  "totalBudget": 500000,
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "milestonePlan": "json"
}
```

#### 项目进展报告
```http
POST /research-projects/{id}/progress-report
Authorization: Bearer {token}
Content-Type: application/json

{
  "reportPeriod": "2024年第一季度",
  "progressSummary": "string",
  "achievedMilestones": ["里程碑1", "里程碑2"],
  "currentPhase": 3,
  "progressPercentage": 25,
  "budgetUsage": {
    "used": 125000,
    "remaining": 375000,
    "categories": [
      {"category": "人员费", "used": 80000},
      {"category": "设备费", "used": 30000},
      {"category": "材料费", "used": 15000}
    ]
  },
  "achievements": [
    {
      "type": "论文",
      "title": "基于深度学习的图像识别研究",
      "journal": "计算机学报",
      "status": "已发表"
    }
  ],
  "challenges": "string",
  "nextSteps": "string",
  "riskAssessment": "string"
}
```

## 系统管理模块API

### 系统配置

#### 获取系统配置
```http
GET /system-configs?configGroup=&configKey=
Authorization: Bearer {token}
```

#### 更新系统配置
```http
PUT /system-configs/{key}
Authorization: Bearer {token}
Content-Type: application/json

{
  "configValue": "string",
  "description": "string"
}
```

### 文件管理

#### 文件上传
```http
POST /files/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

{
  "file": "file",
  "businessType": "string",
  "businessId": 1,
  "accessLevel": 1
}
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "fileId": 1,
    "originalName": "document.pdf",
    "storedName": "20240101_abc123.pdf",
    "filePath": "/uploads/2024/01/01/20240101_abc123.pdf",
    "fileSize": 1024000,
    "fileType": "pdf",
    "downloadUrl": "https://api.example.com/files/download/1"
  }
}
```

#### 文件下载
```http
GET /files/download/{id}
Authorization: Bearer {token}
```

#### 文件删除
```http
DELETE /files/{id}
Authorization: Bearer {token}
```

### 通知管理

#### 发送通知
```http
POST /notifications
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "string",
  "content": "string",
  "notificationType": 1,
  "receiverIds": [1, 2, 3],
  "businessType": "string",
  "businessId": 1,
  "priority": 3
}
```

#### 获取通知列表
```http
GET /notifications?page=1&size=20&isRead=&notificationType=
Authorization: Bearer {token}
```

#### 标记已读
```http
PUT /notifications/{id}/read
Authorization: Bearer {token}
```

#### 批量标记已读
```http
PUT /notifications/batch-read
Authorization: Bearer {token}
Content-Type: application/json

{
  "notificationIds": [1, 2, 3]
}
```

### 操作日志

#### 获取操作日志
```http
GET /operation-logs?page=1&size=20&userId=&operationType=&startDate=&endDate=
Authorization: Bearer {token}
```

### 数据统计

#### 系统概览统计
```http
GET /statistics/overview
Authorization: Bearer {token}
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "userStatistics": {
      "totalUsers": 1500,
      "activeUsers": 1200,
      "newUsersThisMonth": 50,
      "usersByRole": [
        {"role": "学生", "count": 1000},
        {"role": "教师", "count": 400},
        {"role": "管理员", "count": 100}
      ]
    },
    "projectStatistics": {
      "totalProjects": 200,
      "activeProjects": 150,
      "completedProjects": 45,
      "projectsByType": [
        {"type": "科研项目", "count": 80},
        {"type": "竞赛项目", "count": 70},
        {"type": "实训项目", "count": 50}
      ]
    },
    "competitionStatistics": {
      "totalCompetitions": 50,
      "totalAwards": 300,
      "awardsByLevel": [
        {"level": "国家级", "count": 50},
        {"level": "省部级", "count": 100},
        {"level": "校级", "count": 150}
      ]
    },
    "labStatistics": {
      "totalLabs": 30,
      "totalEquipment": 500,
      "equipmentUtilization": 75.5,
      "activeBorrowings": 45
    }
  }
}
```

## 错误码定义

### 通用错误码
- `200`: 成功
- `400`: 请求参数错误
- `401`: 未授权
- `403`: 权限不足
- `404`: 资源不存在
- `409`: 资源冲突
- `422`: 数据验证失败
- `500`: 服务器内部错误

### 业务错误码
- `10001`: 用户名或密码错误
- `10002`: 验证码错误
- `10003`: 账户已被禁用
- `10004`: Token已过期
- `10005`: Token无效

- `20001`: 项目不存在
- `20002`: 项目已满员
- `20003`: 重复申请
- `20004`: 申请已截止

- `30001`: 竞赛不存在
- `30002`: 获奖信息重复
- `30003`: 证书文件无效
- `30004`: 审核权限不足

- `40001`: 实验室不存在
- `40002`: 设备不可用
- `40003`: 借用时间冲突
- `40004`: 远程控制失败

- `50001`: 交流项目不存在
- `50002`: 申请材料不完整
- `50003`: 不符合申请条件
- `50004`: 申请已截止

### 错误响应格式
```json
{
  "code": 400,
  "message": "请求参数错误",
  "details": "用户名不能为空",
  "timestamp": "2024-01-01T12:00:00Z",
  "requestId": "uuid",
  "path": "/api/v1/users"
}
```

---

## 版本历史
- **v1.0** (2024年): 初始版本，包含所有核心功能模块的API接口定义

## 联系信息
- **技术支持**: tech-support@inno-res-comp.edu.cn
- **API文档**: https://docs.inno-res-comp.edu.cn/api
- **开发者社区**: https://community.inno-res-comp.edu.cn