xsl/xsl_node

Fork 0

Files

T

Your Name 40d2f3f6ac save code

2026-01-26 12:29:56 +08:00

17 KiB

Raw Blame History

后端API文档

文档信息

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

1. API概述

1.1 基础信息

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

1.2 响应格式

成功响应

{
  "code": 200,
  "message": "操作成功",
  "data": {...}
}

错误响应

{
  "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	是	密码

请求示例:

{
  "username": "admin",
  "password": "123456"
}

响应示例:

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

2.2 退出登录

接口地址: /api/auth/logout

请求方法: POST

请求参数: 无

响应示例:

{
  "code": 200,
  "message": "退出成功"
}

2.3 获取用户信息

接口地址: /api/auth/userInfo

请求方法: GET

请求参数: 无

响应示例:

{
  "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	是	角色

请求示例:

{
  "username": "test",
  "password": "123456",
  "realName": "测试用户",
  "department": "技术部",
  "phone": "13800138000",
  "email": "test@example.com",
  "role": "OTHER"
}

响应示例:

{
  "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	否	角色

请求示例:

{
  "realName": "测试用户1",
  "department": "市场部",
  "role": "MARKETING"
}

响应示例:

{
  "code": 200,
  "message": "更新成功"
}

3.3 删除用户

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

请求方法: DELETE

请求参数:

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

响应示例:

{
  "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	否	角色

响应示例:

{
  "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	是	新密码

请求示例:

{
  "password": "123456"
}

响应示例:

{
  "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	否	备注

请求示例:

{
  "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": "项目需要与现有系统进行数据对接"
}

响应示例:

{
  "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	否	备注

请求示例:

{
  "projectName": "测试项目1",
  "status": "IN_PROGRESS",
  "usedBudget": 100000
}

响应示例:

{
  "code": 200,
  "message": "更新成功"
}

4.3 删除项目

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

请求方法: DELETE

请求参数:

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

响应示例:

{
  "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	否	负责人（模糊查询）

响应示例:

{
  "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

响应示例:

{
  "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	否	结束日期

响应示例:

{
  "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

请求示例:

{
  "projectName": "测试",
  "status": "IN_PROGRESS",
  "createStartDate": "2025-01-01",
  "createEndDate": "2025-12-31"
}

响应示例:

{
  "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	否	结束日期

请求示例:

{
  "dimension": "status",
  "startDate": "2025-01-01",
  "endDate": "2025-12-31"
}

响应示例:

{
  "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	否	结束日期

响应示例:

{
  "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 认证流程

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

8.2 授权流程

服务端从 Token 中解析出用户信息
根据用户角色和权限判断是否有权限访问请求的资源
有权限则继续处理请求，无权限则返回 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	-	初始版本创建

17 KiB Raw Blame History

后端API文档

文档信息

1. API概述

1.1 基础信息

1.2 响应格式

成功响应

错误响应

1.3 错误码

2. 认证API

2.1 登录

2.2 退出登录

2.3 获取用户信息

3. 用户API

3.1 创建用户

3.2 更新用户

3.3 删除用户

3.4 获取用户列表

3.5 重置密码

4. 项目API

4.1 创建项目

4.2 更新项目

4.3 删除项目

4.4 获取项目列表

4.5 获取项目详情

5. 历史记录API

5.1 获取项目历史

6. 统计API

6.1 筛选项目

6.2 统计项目

7. 系统API

7.1 获取操作日志

8. 认证与授权

8.1 认证流程

8.2 授权流程

8.3 角色权限

9. 附录

9.1 数据字典

项目状态

角色

风险等级

操作类型

9.2 开发规范

9.3 变更记录

17 KiB

Raw Blame History