# 后端API文档

## 文档信息
- **文档版本**: V1.0
- **创建日期**: 2026-01-26
- **文档类型**: 后端API文档

---

## 1. API概述

### 1.1 基础信息

- **API前缀**: `/api`
- **API文档地址**: `/docs`
- **认证方式**: JWT Token (Bearer Token)
- **响应格式**: JSON
- **错误处理**: 统一错误响应格式

### 1.2 响应格式

#### 成功响应
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {...}
}
```

#### 错误响应
```json
{
  "code": 错误码,
  "message": "错误信息"
}
```

### 1.3 错误码

| 错误码 | 说明 |
|--------|------|
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
| 1001 | 用户名或密码错误 |
| 1002 | 用户不存在 |
| 1003 | 用户名已存在 |
| 1004 | 密码不一致 |
| 2001 | 项目不存在 |
| 2002 | 无权限操作 |

---

## 2. 认证API

### 2.1 登录

**接口地址**: `/api/auth/login`

**请求方法**: `POST`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| username | string | body | 是 | 用户名 |
| password | string | body | 是 | 密码 |

**请求示例**:
```json
{
  "username": "admin",
  "password": "123456"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": {
      "userId": "admin001",
      "username": "admin",
      "realName": "系统管理员",
      "department": "ADMIN",
      "role": "ADMIN"
    }
  }
}
```

### 2.2 退出登录

**接口地址**: `/api/auth/logout`

**请求方法**: `POST`

**请求参数**: 无

**响应示例**:
```json
{
  "code": 200,
  "message": "退出成功"
}
```

### 2.3 获取用户信息

**接口地址**: `/api/auth/userInfo`

**请求方法**: `GET`

**请求参数**: 无

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "userId": "admin001",
    "username": "admin",
    "realName": "系统管理员",
    "department": "ADMIN",
    "role": "ADMIN"
  }
}
```

---

## 3. 用户API

### 3.1 创建用户

**接口地址**: `/api/user`

**请求方法**: `POST`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| username | string | body | 是 | 用户名 |
| password | string | body | 是 | 密码 |
| realName | string | body | 是 | 真实姓名 |
| department | string | body | 是 | 部门 |
| phone | string | body | 否 | 联系电话 |
| email | string | body | 否 | 邮箱 |
| role | string | body | 是 | 角色 |

**请求示例**:
```json
{
  "username": "test",
  "password": "123456",
  "realName": "测试用户",
  "department": "技术部",
  "phone": "13800138000",
  "email": "test@example.com",
  "role": "OTHER"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "创建成功"
}
```

### 3.2 更新用户

**接口地址**: `/api/user/{id}`

**请求方法**: `PUT`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| id | string | path | 是 | 用户ID |
| realName | string | body | 否 | 真实姓名 |
| department | string | body | 否 | 部门 |
| phone | string | body | 否 | 联系电话 |
| email | string | body | 否 | 邮箱 |
| role | string | body | 否 | 角色 |

**请求示例**:
```json
{
  "realName": "测试用户1",
  "department": "市场部",
  "role": "MARKETING"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "更新成功"
}
```

### 3.3 删除用户

**接口地址**: `/api/user/{id}`

**请求方法**: `DELETE`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| id | string | path | 是 | 用户ID |

**响应示例**:
```json
{
  "code": 200,
  "message": "删除成功"
}
```

### 3.4 获取用户列表

**接口地址**: `/api/user`

**请求方法**: `GET`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| page | integer | query | 否 | 页码，默认1 |
| size | integer | query | 否 | 每页数量，默认10 |
| username | string | query | 否 | 用户名（模糊查询） |
| department | string | query | 否 | 部门 |
| role | string | query | 否 | 角色 |

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "userId": "admin001",
      "username": "admin",
      "realName": "系统管理员",
      "department": "ADMIN",
      "role": "ADMIN",
      "status": 1,
      "createTime": "2025-01-01 00:00:00",
      "lastLoginTime": "2025-01-15 10:00:00"
    }
  ],
  "total": 1
}
```

### 3.5 重置密码

**接口地址**: `/api/user/resetPassword/{id}`

**请求方法**: `PUT`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| id | string | path | 是 | 用户ID |
| password | string | body | 是 | 新密码 |

**请求示例**:
```json
{
  "password": "123456"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "密码重置成功"
}
```

---

## 4. 项目API

### 4.1 创建项目

**接口地址**: `/api/project`

**请求方法**: `POST`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| projectName | string | body | 是 | 项目名称 |
| status | string | body | 是 | 项目状态 |
| leader | string | body | 是 | 负责人 |
| phone | string | body | 否 | 联系电话 |
| email | string | body | 否 | 邮箱 |
| background | string | body | 否 | 项目背景 |
| goal | string | body | 否 | 项目目标 |
| scope | string | body | 否 | 项目范围 |
| startDate | string | body | 是 | 开始日期 |
| plannedEndDate | string | body | 是 | 预计结束日期 |
| actualEndDate | string | body | 否 | 实际结束日期 |
| totalBudget | number | body | 是 | 总预算 |
| usedBudget | number | body | 否 | 已使用预算 |
| members | array | body | 否 | 项目成员 |
| milestones | array | body | 否 | 项目里程碑 |
| risks | array | body | 否 | 项目风险 |
| remarks | string | body | 否 | 备注 |

**请求示例**:
```json
{
  "projectName": "测试项目",
  "status": "NOT_STARTED",
  "leader": "张三",
  "phone": "13800138000",
  "email": "zhangsan@example.com",
  "background": "为了提升企业运营效率",
  "goal": "完成企业内部管理系统的全面数字化改造",
  "scope": "包括人力资源、财务管理、供应链管理等模块",
  "startDate": "2025-01-15",
  "plannedEndDate": "2025-06-30",
  "totalBudget": 500000,
  "usedBudget": 0,
  "members": [
    {
      "name": "张三",
      "role": "项目经理",
      "department": "市场部"
    },
    {
      "name": "李四",
      "role": "技术负责人",
      "department": "技术部"
    }
  ],
  "milestones": [
    {
      "name": "需求分析完成",
      "plannedDate": "2025-02-15",
      "status": "NOT_STARTED"
    },
    {
      "name": "系统设计完成",
      "plannedDate": "2025-03-15",
      "status": "NOT_STARTED"
    }
  ],
  "risks": [
    {
      "description": "技术难度较高，可能影响进度",
      "level": "HIGH",
      "measure": "增加技术团队人员投入"
    }
  ],
  "remarks": "项目需要与现有系统进行数据对接"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "创建成功",
  "data": {
    "projectId": "PRJ2025001"
  }
}
```

### 4.2 更新项目

**接口地址**: `/api/project/{id}`

**请求方法**: `PUT`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| id | string | path | 是 | 项目ID |
| projectName | string | body | 否 | 项目名称 |
| status | string | body | 否 | 项目状态 |
| leader | string | body | 否 | 负责人 |
| phone | string | body | 否 | 联系电话 |
| email | string | body | 否 | 邮箱 |
| background | string | body | 否 | 项目背景 |
| goal | string | body | 否 | 项目目标 |
| scope | string | body | 否 | 项目范围 |
| startDate | string | body | 否 | 开始日期 |
| plannedEndDate | string | body | 否 | 预计结束日期 |
| actualEndDate | string | body | 否 | 实际结束日期 |
| totalBudget | number | body | 否 | 总预算 |
| usedBudget | number | body | 否 | 已使用预算 |
| members | array | body | 否 | 项目成员 |
| milestones | array | body | 否 | 项目里程碑 |
| risks | array | body | 否 | 项目风险 |
| remarks | string | body | 否 | 备注 |

**请求示例**:
```json
{
  "projectName": "测试项目1",
  "status": "IN_PROGRESS",
  "usedBudget": 100000
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "更新成功"
}
```

### 4.3 删除项目

**接口地址**: `/api/project/{id}`

**请求方法**: `DELETE`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| id | string | path | 是 | 项目ID |

**响应示例**:
```json
{
  "code": 200,
  "message": "删除成功"
}
```

### 4.4 获取项目列表

**接口地址**: `/api/project`

**请求方法**: `GET`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| page | integer | query | 否 | 页码，默认1 |
| size | integer | query | 否 | 每页数量，默认10 |
| projectName | string | query | 否 | 项目名称（模糊查询） |
| status | string | query | 否 | 项目状态 |
| leader | string | query | 否 | 负责人（模糊查询） |

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "projectId": "PRJ2025001",
      "projectNo": "PRJ2025001",
      "projectName": "测试项目",
      "status": "IN_PROGRESS",
      "leader": "张三",
      "createTime": "2025-01-15 00:00:00",
      "updateTime": "2025-01-20 10:00:00"
    }
  ],
  "total": 1
}
```

### 4.5 获取项目详情

**接口地址**: `/api/project/{id}`

**请求方法**: `GET`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| id | string | path | 是 | 项目ID |

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "projectId": "PRJ2025001",
    "projectNo": "PRJ2025001",
    "projectName": "测试项目",
    "status": "IN_PROGRESS",
    "leader": "张三",
    "phone": "13800138000",
    "email": "zhangsan@example.com",
    "background": "为了提升企业运营效率",
    "goal": "完成企业内部管理系统的全面数字化改造",
    "scope": "包括人力资源、财务管理、供应链管理等模块",
    "startDate": "2025-01-15",
    "plannedEndDate": "2025-06-30",
    "actualEndDate": null,
    "totalBudget": 500000,
    "usedBudget": 100000,
    "remainingBudget": 400000,
    "members": [
      {
        "name": "张三",
        "role": "项目经理",
        "department": "市场部"
      },
      {
        "name": "李四",
        "role": "技术负责人",
        "department": "技术部"
      }
    ],
    "milestones": [
      {
        "name": "需求分析完成",
        "plannedDate": "2025-02-15",
        "actualDate": null,
        "status": "NOT_STARTED"
      },
      {
        "name": "系统设计完成",
        "plannedDate": "2025-03-15",
        "actualDate": null,
        "status": "NOT_STARTED"
      }
    ],
    "risks": [
      {
        "description": "技术难度较高，可能影响进度",
        "level": "HIGH",
        "measure": "增加技术团队人员投入"
      }
    ],
    "remarks": "项目需要与现有系统进行数据对接",
    "creator": "marketing",
    "createTime": "2025-01-15 00:00:00",
    "lastModifier": "admin",
    "updateTime": "2025-01-20 10:00:00"
  }
}
```

---

## 5. 历史记录API

### 5.1 获取项目历史

**接口地址**: `/api/history/{projectId}`

**请求方法**: `GET`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| projectId | string | path | 是 | 项目ID |
| page | integer | query | 否 | 页码，默认1 |
| size | integer | query | 否 | 每页数量，默认10 |
| operator | string | query | 否 | 操作人（模糊查询） |
| startDate | string | query | 否 | 开始日期 |
| endDate | string | query | 否 | 结束日期 |

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "historyId": "HIS2025001",
      "projectId": "PRJ2025001",
      "projectNo": "PRJ2025001",
      "operationType": "UPDATE",
      "operator": "admin",
      "operationTime": "2025-01-20 10:00:00",
      "fieldName": "status",
      "oldValue": "NOT_STARTED",
      "newValue": "IN_PROGRESS"
    }
  ],
  "total": 1
}
```

---

## 6. 统计API

### 6.1 筛选项目

**接口地址**: `/api/statistics/filter`

**请求方法**: `POST`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| projectNo | string | body | 否 | 项目编号 |
| projectName | string | body | 否 | 项目名称（模糊查询） |
| status | string | body | 否 | 项目状态 |
| leader | string | body | 否 | 负责人（模糊查询） |
| creator | string | body | 否 | 创建人（模糊查询） |
| createStartDate | string | body | 否 | 创建开始日期 |
| createEndDate | string | body | 否 | 创建结束日期 |
| updateStartDate | string | body | 否 | 更新开始日期 |
| updateEndDate | string | body | 否 | 更新结束日期 |
| page | integer | body | 否 | 页码，默认1 |
| size | integer | body | 否 | 每页数量，默认10 |

**请求示例**:
```json
{
  "projectName": "测试",
  "status": "IN_PROGRESS",
  "createStartDate": "2025-01-01",
  "createEndDate": "2025-12-31"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "projectId": "PRJ2025001",
      "projectNo": "PRJ2025001",
      "projectName": "测试项目",
      "status": "IN_PROGRESS",
      "leader": "张三",
      "createTime": "2025-01-15 00:00:00",
      "updateTime": "2025-01-20 10:00:00"
    }
  ],
  "total": 1
}
```

### 6.2 统计项目

**接口地址**: `/api/statistics/statistics`

**请求方法**: `POST`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| dimension | string | body | 是 | 统计维度：status, department, leader, month |
| startDate | string | body | 否 | 开始日期 |
| endDate | string | body | 否 | 结束日期 |

**请求示例**:
```json
{
  "dimension": "status",
  "startDate": "2025-01-01",
  "endDate": "2025-12-31"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "统计成功",
  "data": {
    "dimension": "status",
    "total": 10,
    "details": [
      {
        "name": "NOT_STARTED",
        "value": 2
      },
      {
        "name": "IN_PROGRESS",
        "value": 5
      },
      {
        "name": "COMPLETED",
        "value": 2
      },
      {
        "name": "PAUSED",
        "value": 1
      }
    ]
  }
}
```

---

## 7. 系统API

### 7.1 获取操作日志

**接口地址**: `/api/system/log`

**请求方法**: `GET`

**请求参数**:

| 参数名 | 类型 | 位置 | 必填 | 说明 |
|--------|------|------|------|------|
| page | integer | query | 否 | 页码，默认1 |
| size | integer | query | 否 | 每页数量，默认10 |
| username | string | query | 否 | 用户名（模糊查询） |
| operation | string | query | 否 | 操作内容（模糊查询） |
| startDate | string | query | 否 | 开始日期 |
| endDate | string | query | 否 | 结束日期 |

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "logId": "LOG2025001",
      "username": "admin",
      "operation": "登录系统",
      "ipAddress": "127.0.0.1",
      "userAgent": "Mozilla/5.0...",
      "operationTime": "2025-01-20 10:00:00"
    }
  ],
  "total": 1
}
```

---

## 8. 认证与授权

### 8.1 认证流程

1. 客户端发送登录请求到 `/api/auth/login`
2. 服务端验证用户名和密码
3. 验证成功后生成 JWT Token
4. 客户端保存 Token 到 localStorage
5. 后续请求在请求头中携带 Token: `Authorization: Bearer <token>`
6. 服务端验证 Token 的有效性
7. 验证通过后处理请求

### 8.2 授权流程

1. 服务端从 Token 中解析出用户信息
2. 根据用户角色和权限判断是否有权限访问请求的资源
3. 有权限则继续处理请求，无权限则返回 403 错误

### 8.3 角色权限

| 角色 | 权限 |
|------|------|
| ADMIN | 所有权限 |
| MARKETING | 创建项目、编辑项目、查看项目、查看历史记录 |
| OTHER | 编辑项目、查看项目、查看历史记录 |

---

## 9. 附录

### 9.1 数据字典

#### 项目状态
| 值 | 说明 |
|----|------|
| NOT_STARTED | 未开始 |
| IN_PROGRESS | 进行中 |
| COMPLETED | 已完成 |
| PAUSED | 已暂停 |
| CANCELLED | 已取消 |

#### 角色
| 值 | 说明 |
|----|------|
| ADMIN | 管理员 |
| MARKETING | 市场部 |
| OTHER | 其他部门 |

#### 风险等级
| 值 | 说明 |
|----|------|
| HIGH | 高 |
| MEDIUM | 中 |
| LOW | 低 |

#### 操作类型
| 值 | 说明 |
|----|------|
| CREATE | 创建 |
| UPDATE | 更新 |
| DELETE | 删除 |

### 9.2 开发规范

- **API设计**: 遵循 RESTful API 设计规范
- **参数验证**: 使用 Pydantic 进行参数验证
- **错误处理**: 使用统一的错误处理机制
- **日志记录**: 记录重要操作的日志
- **测试**: 为每个 API 编写单元测试

### 9.3 变更记录

| 版本 | 日期 | 修改人 | 修改内容 |
|------|------|--------|----------|
| V1.0 | 2026-01-26 | - | 初始版本创建 |