fundplatform/doc/API接口文档.md

资金服务平台 API 接口文档

版本: v1.0
更新日期: 2026-02-13
作者: zhangjf

---

一、API 规范

1.1 基础信息

项目	说明
协议	HTTPS（生产环境）/ HTTP（开发环境）
数据格式	JSON
字符编码	UTF-8
时间格式	ISO 8601（yyyy-MM-dd HH:mm:ss）
日期格式	yyyy-MM-dd
金额格式	Decimal（保留2位小数）

1.2 请求规范

请求头（Headers）

参数名	必填	说明
Content-Type	是	固定值：application/json
Authorization	是	Bearer Token：Bearer {accessToken}
X-Tenant-Id	是	租户ID
X-Trace-Id	否	链路追踪ID（系统自动生成）

请求示例

POST /api/v1/user/login HTTP/1.1
Host: api.fundplatform.com
Content-Type: application/json
X-Tenant-Id: 1

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

1.3 响应规范

统一响应格式

{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1707811200000,
  "traceId": "abc123def456"
}

响应字段说明

字段	类型	说明
code	Integer	状态码（200成功，其他为错误码）
message	String	提示信息
data	Object	业务数据（可为 null）
timestamp	Long	时间戳（毫秒）
traceId	String	链路追踪ID

分页响应格式

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [],
    "total": 100,
    "size": 10,
    "current": 1,
    "pages": 10
  },
  "timestamp": 1707811200000,
  "traceId": "abc123def456"
}

分页字段说明

字段	类型	说明
records	Array	数据列表
total	Long	总记录数
size	Integer	每页大小
current	Integer	当前页码（从1开始）
pages	Integer	总页数

1.4 状态码定义

成功状态码

状态码	说明
200	操作成功
201	创建成功
204	删除成功（无返回内容）

错误状态码

状态码	说明	处理建议
400	请求参数错误	检查请求参数格式
401	未授权	Token无效或过期，重新登录
403	禁止访问	无权限访问该资源
404	资源不存在	检查请求路径或ID
409	资源冲突	数据已存在或状态冲突
429	请求过于频繁	稍后重试
500	服务器内部错误	联系管理员
503	服务不可用	服务维护中

业务错误码（code字段）

错误码	说明
1001	用户名或密码错误
1002	账号已被禁用
1003	Token已过期
1004	Token无效
1005	无权限访问
2001	数据已存在
2002	数据不存在
2003	数据关联冲突
3001	租户已过期
3002	租户已被禁用

1.5 分页请求参数

参数名	类型	必填	默认值	说明
current	Integer	否	1	当前页码
size	Integer	否	10	每页大小（最大100）
sortField	String	否	-	排序字段
sortOrder	String	否	asc	排序方式：asc/desc

---

二、部门管理接口

2.1 获取部门树

接口地址： GET /api/v1/dept/tree

接口说明： 获取部门树形结构（含层级关系）

请求参数：

参数名	类型	必填	说明
tenantId	Long	否	租户ID（不传则使用默认租户）

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "deptId": 1,
      "tenantId": 1,
      "deptName": "万家布洛科技",
      "parentId": 0,
      "deptCode": "ROOT",
      "deptLevel": 1,
      "sortOrder": 1,
      "leader": "张三",
      "leaderPhone": "13800138000",
      "status": 1,
      "remark": "总公司",
      "children": [
        {
          "deptId": 2,
          "deptName": "技术部",
          "parentId": 1,
          "deptCode": "TECH",
          "deptLevel": 2,
          "sortOrder": 1,
          "leader": "李四",
          "leaderPhone": "13900139000",
          "status": 1,
          "children": []
        }
      ]
    }
  ]
}

---

2.2 获取部门列表

接口地址： GET /api/v1/dept/list

接口说明： 获取部门列表（扁平结构）

请求参数：

参数名	类型	必填	说明
tenantId	Long	否	租户ID（不传则使用默认租户）

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "deptId": 1,
      "tenantId": 1,
      "deptName": "万家布洛科技",
      "parentId": 0,
      "deptCode": "ROOT",
      "deptLevel": 1,
      "sortOrder": 1,
      "leader": "张三",
      "leaderPhone": "13800138000",
      "status": 1,
      "remark": "总公司"
    }
  ]
}

---

2.3 获取部门详情

接口地址： GET /api/v1/dept/{deptId}

接口说明： 根据ID查询部门详情

路径参数：

参数名	类型	必填	说明
deptId	Long	是	部门ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "deptId": 1,
    "tenantId": 1,
    "deptName": "万家布洛科技",
    "parentId": 0,
    "deptCode": "ROOT",
    "deptLevel": 1,
    "sortOrder": 1,
    "leader": "张三",
    "leaderPhone": "13800138000",
    "status": 1,
    "remark": "总公司",
    "createdTime": "2026-01-01 10:00:00"
  }
}

---

2.4 新增部门

接口地址： POST /api/v1/dept

接口说明： 创建新部门

请求参数：

参数名	类型	必填	说明
deptName	String	是	部门名称
parentId	Long	是	父部门ID（顶级部门为0）
deptCode	String	否	部门编码
deptLevel	Integer	否	部门层级（系统自动计算）
sortOrder	Integer	否	排序号
leader	String	否	负责人
leaderPhone	String	否	负责人电话
status	Integer	否	状态（0-禁用，1-启用，默认1）
remark	String	否	备注

请求示例：

{
  "deptName": "技术部",
  "parentId": 1,
  "deptCode": "TECH",
  "sortOrder": 1,
  "leader": "李四",
  "leaderPhone": "13900139000",
  "status": 1,
  "remark": "技术研发部门"
}

响应示例：

{
  "code": 200,
  "message": "创建成功",
  "data": null
}

---

2.5 更新部门

接口地址： PUT /api/v1/dept/{deptId}

接口说明： 更新部门信息

路径参数：

参数名	类型	必填	说明
deptId	Long	是	部门ID

请求参数： 同2.4

响应示例：

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

---

2.6 删除部门

接口地址： DELETE /api/v1/dept/{deptId}

接口说明： 删除指定部门（若有子部门则无法删除）

路径参数：

参数名	类型	必填	说明
deptId	Long	是	部门ID

响应示例：

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

---

三、岗位管理接口

3.1 分页查询岗位列表

接口地址： GET /api/v1/post/list

接口说明： 分页查询岗位列表，支持多条件过滤

请求参数：

参数名	类型	必填	说明
current	Long	否	当前页码，默认1
size	Long	否	每页条数，默认10
postCode	String	否	岗位编码（模糊查询）
postName	String	否	岗位名称（模糊查询）
deptId	Long	否	所属部门ID
status	Integer	否	状态（0-禁用，1-启用）

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "postId": 1,
        "tenantId": 1,
        "postCode": "PM",
        "postName": "项目经理",
        "postDuty": "负责项目整体规划和执行",
        "postRequirement": "3年以上项目管理经验",
        "deptId": 2,
        "sortOrder": 1,
        "status": 1,
        "remark": "",
        "createdTime": "2026-02-13 10:00:00"
      }
    ],
    "total": 10,
    "size": 10,
    "current": 1
  }
}

---

3.2 按部门ID查询岗位列表

接口地址： GET /api/v1/post/list/dept/{deptId}

接口说明： 查询指定部门下所有启用的岗位

路径参数：

参数名	类型	必填	说明
deptId	Long	是	部门ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "postId": 1,
      "postCode": "PM",
      "postName": "项目经理",
      "deptId": 2,
      "status": 1
    }
  ]
}

---

3.3 获取所有启用的岗位列表

接口地址： GET /api/v1/post/list/enabled

接口说明： 获取所有状态为启用的岗位列表

响应示例： 同3.2

---

3.4 获取岗位详情

接口地址： GET /api/v1/post/{postId}

接口说明： 根据ID查询岗位详情

路径参数：

参数名	类型	必填	说明
postId	Long	是	岗位ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "postId": 1,
    "tenantId": 1,
    "postCode": "PM",
    "postName": "项目经理",
    "postDuty": "负责项目整体规划和执行",
    "postRequirement": "3年以上项目管理经验",
    "deptId": 2,
    "sortOrder": 1,
    "status": 1,
    "remark": "",
    "createdTime": "2026-02-13 10:00:00"
  }
}

---

3.5 创建岗位

接口地址： POST /api/v1/post

接口说明： 创建新岗位

请求参数：

参数名	类型	必填	说明
postCode	String	是	岗位编码
postName	String	是	岗位名称
postDuty	String	否	岗位职责描述
postRequirement	String	否	岗位要求
deptId	Long	否	所属部门ID
sortOrder	Integer	否	排序号
status	Integer	否	状态（0-禁用，1-启用，默认1）
remark	String	否	备注

请求示例：

{
  "postCode": "DEV",
  "postName": "开发工程师",
  "postDuty": "负责软件开发工作",
  "postRequirement": "计算机相关专业，1年以上开发经验",
  "deptId": 2,
  "sortOrder": 2,
  "status": 1
}

响应示例：

{
  "code": 200,
  "message": "创建成功",
  "data": null
}

---

3.6 更新岗位

接口地址： PUT /api/v1/post/{postId}

接口说明： 更新岗位信息

路径参数：

参数名	类型	必填	说明
postId	Long	是	岗位ID

请求参数： 同3.5

响应示例：

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

---

3.7 删除岗位

接口地址： DELETE /api/v1/post/{postId}

接口说明： 删除指定岗位

路径参数：

参数名	类型	必填	说明
postId	Long	是	岗位ID

响应示例：

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

---

3.8 更新岗位状态

接口地址： PUT /api/v1/post/{postId}/status

接口说明： 更新岗位状态（启用/禁用）

路径参数：

参数名	类型	必填	说明
postId	Long	是	岗位ID

请求参数：

参数名	类型	必填	说明
status	Integer	是	状态（0-禁用，1-启用）

响应示例：

{
  "code": 200,
  "message": "状态更新成功",
  "data": null
}

---

四、人员分配管理接口

4.1 分页查询用户分配列表

接口地址： GET /api/v1/user-assignment/list

接口说明： 分页查询用户分配列表，支持多条件过滤

请求参数：

参数名	类型	必填	说明
current	Long	否	当前页码，默认1
size	Long	否	每页条数，默认10
username	String	否	用户名（模糊查询）
realName	String	否	真实姓名（模糊查询）
deptId	Long	否	部门ID
postId	Long	否	岗位ID
status	Integer	否	状态（0-禁用，1-启用）

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "userId": 1,
        "username": "admin",
        "realName": "管理员",
        "gender": 1,
        "phone": "13800138000",
        "email": "admin@example.com",
        "deptId": 1,
        "deptName": "技术部",
        "postId": 1,
        "postName": "开发工程师",
        "position": "高级开发",
        "status": 1,
        "createdTime": "2026-01-01 10:00:00"
      }
    ],
    "total": 50,
    "size": 10,
    "current": 1
  }
}

---

4.2 根据部门ID查询用户列表

接口地址： GET /api/v1/user-assignment/list/dept/{deptId}

接口说明： 查询指定部门下的所有启用用户

路径参数：

参数名	类型	必填	说明
deptId	Long	是	部门ID

响应示例： 同4.1

---

4.3 分配用户到部门和岗位

接口地址： PUT /api/v1/user-assignment/{userId}

接口说明： 将用户分配到指定部门和岗位

路径参数：

参数名	类型	必填	说明
userId	Long	是	用户ID

请求参数：

参数名	类型	必填	说明
deptId	Long	否	部门ID
postId	Long	否	岗位ID
position	String	否	职位

响应示例：

{
  "code": 200,
  "message": "分配成功",
  "data": null
}

---

4.4 批量分配用户

接口地址： PUT /api/v1/user-assignment/batch

接口说明： 批量将用户分配到指定部门和岗位

请求参数：

参数名	类型	必填	说明
deptId	Long	是	部门ID
postId	Long	是	岗位ID

请求体：

[1, 2, 3, 4, 5]

响应示例：

{
  "code": 200,
  "message": "批量分配成功",
  "data": null
}

---

4.5 移除用户分配

接口地址： DELETE /api/v1/user-assignment/{userId}

接口说明： 移除用户的部门和岗位分配

路径参数：

参数名	类型	必填	说明
userId	Long	是	用户ID

响应示例：

{
  "code": 200,
  "message": "移除分配成功",
  "data": null
}

---

五、认证接口

5.1 用户登录

接口地址： POST /api/v1/auth/login

接口说明： 用户登录获取访问令牌

请求参数：

参数名	类型	必填	说明
username	String	是	用户名
password	String	是	密码（MD5加密后传输）
tenantCode	String	否	租户编码（多租户模式必填）

请求示例：

{
  "username": "admin",
  "password": "e10adc3949ba59abbe56e057f20f883e",
  "tenantCode": "SYSTEM"
}

响应参数：

参数名	类型	说明
accessToken	String	访问令牌
refreshToken	String	刷新令牌
expiresIn	Long	访问令牌过期时间（秒）
tokenType	String	令牌类型（Bearer）
userInfo	Object	用户信息

响应示例：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 7200,
    "tokenType": "Bearer",
    "userInfo": {
      "userId": 1,
      "username": "admin",
      "realName": "系统管理员",
      "avatar": "https://...",
      "tenantId": 1,
      "tenantName": "系统管理租户",
      "deptId": 1,
      "deptName": "总部",
      "roles": ["super_admin"],
      "permissions": ["*:*:*"]
    }
  },
  "timestamp": 1707811200000,
  "traceId": "abc123def456"
}

---

2.2 用户登出

接口地址： POST /api/v1/auth/logout

接口说明： 用户登出，使Token失效

请求头：

参数名	必填	说明
Authorization	是	Bearer Token

响应示例：

{
  "code": 200,
  "message": "登出成功",
  "data": null,
  "timestamp": 1707811200000,
  "traceId": "abc123def456"
}

---

2.3 刷新Token

接口地址： POST /api/v1/auth/refresh

接口说明： 使用刷新令牌获取新的访问令牌

请求参数：

参数名	类型	必填	说明
refreshToken	String	是	刷新令牌

响应参数： 同登录接口

---

2.4 获取当前用户信息

接口地址： GET /api/v1/auth/userinfo

接口说明： 获取当前登录用户详细信息

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "userId": 1,
    "username": "admin",
    "realName": "系统管理员",
    "gender": 1,
    "phone": "13800138000",
    "email": "admin@fundplatform.com",
    "avatar": "https://...",
    "deptId": 1,
    "deptName": "总部",
    "position": "系统管理员",
    "tenantId": 1,
    "tenantName": "系统管理租户",
    "roles": [
      {
        "roleId": 1,
        "roleCode": "super_admin",
        "roleName": "超级管理员"
      }
    ],
    "permissions": ["*:*:*"],
    "menus": [
      {
        "menuId": 1,
        "menuName": "系统管理",
        "menuType": "dir",
        "icon": "Setting",
        "path": "/system",
        "children": [...]
      }
    ]
  },
  "timestamp": 1707811200000,
  "traceId": "abc123def456"
}

---

六、用户管理接口

3.1 获取用户列表

接口地址： GET /api/v1/user/list

接口说明： 分页查询用户列表

请求参数：

参数名	类型	必填	说明
current	Integer	否	当前页码
size	Integer	否	每页大小
username	String	否	用户名（模糊查询）
realName	String	否	真实姓名（模糊查询）
deptId	Long	否	部门ID
status	Integer	否	状态：0-禁用，1-启用

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "userId": 1,
        "username": "admin",
        "realName": "系统管理员",
        "gender": 1,
        "phone": "13800138000",
        "email": "admin@fundplatform.com",
        "deptId": 1,
        "deptName": "总部",
        "position": "系统管理员",
        "status": 1,
        "lastLoginTime": "2026-02-13 14:30:00",
        "createdTime": "2024-01-01 00:00:00"
      }
    ],
    "total": 6,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "timestamp": 1707811200000,
  "traceId": "abc123def456"
}

---

3.2 获取用户详情

接口地址： GET /api/v1/user/{userId}

接口说明： 根据用户ID获取用户详细信息

路径参数：

参数名	类型	必填	说明
userId	Long	是	用户ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "userId": 1,
    "username": "admin",
    "realName": "系统管理员",
    "gender": 1,
    "phone": "13800138000",
    "email": "admin@fundplatform.com",
    "avatar": "https://...",
    "deptId": 1,
    "deptName": "总部",
    "position": "系统管理员",
    "status": 1,
    "roleIds": [1],
    "lastLoginTime": "2026-02-13 14:30:00",
    "lastLoginIp": "192.168.1.1",
    "createdTime": "2024-01-01 00:00:00",
    "updatedTime": "2026-02-13 10:00:00"
  },
  "timestamp": 1707811200000,
  "traceId": "abc123def456"
}

---

3.3 新增用户

接口地址： POST /api/v1/user

接口说明： 创建新用户

请求参数：

参数名	类型	必填	说明
username	String	是	用户名（2-20位字母数字）
password	String	是	密码（6-20位）
realName	String	是	真实姓名
gender	Integer	否	性别：0-未知，1-男，2-女
phone	String	否	手机号码
email	String	否	邮箱地址
deptId	Long	否	部门ID
position	String	否	职位
roleIds	Array	否	角色ID列表
status	Integer	否	状态：0-禁用，1-启用（默认1）

请求示例：

{
  "username": "newuser",
  "password": "123456",
  "realName": "新用户",
  "gender": 1,
  "phone": "13800138010",
  "email": "newuser@fundplatform.com",
  "deptId": 2,
  "position": "开发工程师",
  "roleIds": [5],
  "status": 1
}

响应示例：

{
  "code": 201,
  "message": "创建成功",
  "data": {
    "userId": 7,
    "username": "newuser",
    "realName": "新用户",
    "createdTime": "2026-02-13 15:00:00"
  },
  "timestamp": 1707811200000,
  "traceId": "abc123def456"
}

---

3.4 更新用户

接口地址： PUT /api/v1/user/{userId}

接口说明： 更新用户信息

路径参数：

参数名	类型	必填	说明
userId	Long	是	用户ID

请求参数： 同新增用户（password可选）

---

3.5 删除用户

接口地址： DELETE /api/v1/user/{userId}

接口说明： 删除用户（逻辑删除）

路径参数：

参数名	类型	必填	说明
userId	Long	是	用户ID

---

3.6 重置密码

接口地址： PUT /api/v1/user/{userId}/reset-password

接口说明： 重置用户密码

请求参数：

参数名	类型	必填	说明
newPassword	String	是	新密码

---

七、租户管理接口

4.1 获取租户列表

接口地址： GET /api/v1/tenant/list

接口说明： 分页查询租户列表

请求参数：

参数名	类型	必填	说明
current	Integer	否	当前页码
size	Integer	否	每页大小
tenantCode	String	否	租户编码（模糊查询）
tenantName	String	否	租户名称（模糊查询）
status	Integer	否	状态：0-禁用，1-启用

---

4.2 获取租户详情

接口地址： GET /api/v1/tenant/{tenantId}

接口说明： 根据租户ID获取租户详细信息

---

4.3 新增租户

接口地址： POST /api/v1/tenant

接口说明： 创建新租户

请求参数：

参数名	类型	必填	说明
tenantCode	String	是	租户编码（唯一）
tenantName	String	是	租户名称
tenantType	Integer	是	租户类型：1-一库多租户，2-一库一租户
contactName	String	否	联系人姓名
contactPhone	String	否	联系人电话
contactEmail	String	否	联系人邮箱
expireTime	String	否	过期时间（yyyy-MM-dd HH:mm:ss）

---

4.4 更新租户

接口地址： PUT /api/v1/tenant/{tenantId}

接口说明： 更新租户信息

---

4.5 删除租户

接口地址： DELETE /api/v1/tenant/{tenantId}

接口说明： 删除租户

---

八、客户管理接口

5.1 获取客户列表

接口地址： GET /api/v1/customer/list

接口说明： 分页查询客户列表

请求参数：

参数名	类型	必填	说明
current	Integer	否	当前页码
size	Integer	否	每页大小
customerName	String	否	客户名称（模糊查询）
customerType	String	否	客户类型
level	String	否	客户等级
status	Integer	否	状态

---

5.2 获取客户详情

接口地址： GET /api/v1/customer/{customerId}

接口说明： 根据客户ID获取客户详细信息

---

5.3 新增客户

接口地址： POST /api/v1/customer

接口说明： 创建新客户

请求参数：

参数名	类型	必填	说明
customerCode	String	是	客户编码
customerName	String	是	客户名称
customerShort	String	否	客户简称
customerType	String	否	客户类型
industry	String	否	所属行业
scale	String	否	企业规模
level	String	否	客户等级
taxNo	String	否	纳税人识别号
legalPerson	String	否	法定代表人
address	String	否	公司地址
phone	String	否	联系电话
email	String	否	邮箱地址
website	String	否	公司网站

---

5.4 更新客户

接口地址： PUT /api/v1/customer/{customerId}

接口说明： 更新客户信息

---

5.5 删除客户

接口地址： DELETE /api/v1/customer/{customerId}

接口说明： 删除客户

---

5.6 获取联系人列表

接口地址： GET /api/v1/customer/{customerId}/contacts

接口说明： 获取客户的联系人列表

---

5.7 新增联系人

接口地址： POST /api/v1/customer/{customerId}/contacts

接口说明： 为客户添加联系人

请求参数：

参数名	类型	必填	说明
contactName	String	是	联系人姓名
position	String	否	职位
department	String	否	部门
phone	String	否	电话
mobile	String	否	手机
email	String	否	邮箱
isPrimary	Integer	否	是否主要联系人：0-否，1-是

---

九、项目管理接口

6.1 获取项目列表

接口地址： GET /api/v1/project/list

接口说明： 分页查询项目列表

请求参数：

参数名	类型	必填	说明
current	Integer	否	当前页码
size	Integer	否	每页大小
projectName	String	否	项目名称（模糊查询）
customerId	Long	否	客户ID
projectType	String	否	项目类型
status	String	否	项目状态

---

6.2 获取项目详情

接口地址： GET /api/v1/project/{projectId}

接口说明： 根据项目ID获取项目详细信息

---

6.3 新增项目

接口地址： POST /api/v1/project

接口说明： 创建新项目

请求参数：

参数名	类型	必填	说明
projectCode	String	是	项目编号
projectName	String	是	项目名称
projectShort	String	否	项目简称
customerId	Long	是	客户ID
projectType	String	否	项目类型
projectManagerId	Long	否	项目经理ID
startDate	String	否	开始日期（yyyy-MM-dd）
endDate	String	否	结束日期（yyyy-MM-dd）
budgetAmount	BigDecimal	否	预算金额
contractAmount	BigDecimal	否	合同金额
description	String	否	项目描述

---

6.4 更新项目

接口地址： PUT /api/v1/project/{projectId}

接口说明： 更新项目信息

---

6.5 删除项目

接口地址： DELETE /api/v1/project/{projectId}

接口说明： 删除项目

---

6.6 获取项目成员列表

接口地址： GET /api/v1/project/{projectId}/members

接口说明： 获取项目成员列表

---

6.7 添加项目成员

接口地址： POST /api/v1/project/{projectId}/members

接口说明： 为项目添加成员

请求参数：

参数名	类型	必填	说明
userId	Long	是	用户ID
role	String	是	项目角色
workload	BigDecimal	否	工作量占比

---

6.6 获取项目成员列表（按项目ID）

接口地址： GET /api/v1/project-member/list/project/{projectId}

接口说明： 查询指定项目的所有成员

路径参数：

参数名	类型	必填	说明
projectId	Long	是	项目ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "memberId": 1,
      "tenantId": 1,
      "projectId": 1,
      "userId": 5,
      "role": "pm",
      "joinDate": "2026-01-01",
      "leaveDate": null,
      "workload": 80.00,
      "status": 1,
      "remark": "项目负责人",
      "createdTime": "2026-01-01 10:00:00"
    }
  ]
}

---

6.7 获取用户的项目列表（按用户ID）

接口地址： GET /api/v1/project-member/list/user/{userId}

接口说明： 查询指定用户参与的所有项目

路径参数：

参数名	类型	必填	说明
userId	Long	是	用户ID

响应示例： 同6.6

---

6.8 获取项目成员详情

接口地址： GET /api/v1/project-member/{memberId}

接口说明： 根据ID查询项目成员详情

路径参数：

参数名	类型	必填	说明
memberId	Long	是	成员关系ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "memberId": 1,
    "tenantId": 1,
    "projectId": 1,
    "userId": 5,
    "role": "pm",
    "joinDate": "2026-01-01",
    "leaveDate": null,
    "workload": 80.00,
    "status": 1,
    "remark": "项目负责人",
    "createdTime": "2026-01-01 10:00:00"
  }
}

---

6.9 添加项目成员

接口地址： POST /api/v1/project-member

接口说明： 添加新的项目成员

请求参数：

参数名	类型	必填	说明
projectId	Long	是	项目ID
userId	Long	是	用户ID
role	String	是	项目角色（pm/dev/test/finance/member）
joinDate	Date	否	加入日期
workload	Decimal	否	工作量占比（0-100）
remark	String	否	备注说明

请求示例：

{
  "projectId": 1,
  "userId": 5,
  "role": "dev",
  "joinDate": "2026-02-16",
  "workload": 50.00,
  "remark": "后端开发"
}

响应示例：

{
  "code": 200,
  "message": "添加成功",
  "data": null
}

---

6.10 更新项目成员

接口地址： PUT /api/v1/project-member/{memberId}

接口说明： 更新项目成员信息

路径参数：

参数名	类型	必填	说明
memberId	Long	是	成员关系ID

请求参数： 同6.9

响应示例：

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

---

6.11 移除项目成员

接口地址： DELETE /api/v1/project-member/{memberId}

接口说明： 从项目中移除成员

路径参数：

参数名	类型	必填	说明
memberId	Long	是	成员关系ID

响应示例：

{
  "code": 200,
  "message": "移除成功",
  "data": null
}

---

6.12 更新成员状态

接口地址： PUT /api/v1/project-member/{memberId}/status

接口说明： 更新项目成员状态（在职/离开）

路径参数：

参数名	类型	必填	说明
memberId	Long	是	成员关系ID

请求参数：

参数名	类型	必填	说明
status	Integer	是	状态（0-已离开，1-在职）

响应示例：

{
  "code": 200,
  "message": "状态更新成功",
  "data": null
}

---

十、需求工单接口

7.1 获取需求列表

接口地址： GET /api/v1/requirement/list

接口说明： 分页查询需求工单列表

请求参数：

参数名	类型	必填	说明
current	Integer	否	当前页码
size	Integer	否	每页大小
requirementName	String	否	需求名称（模糊查询）
projectId	Long	否	项目ID
priority	String	否	优先级
status	String	否	状态

---

7.2 获取需求详情

接口地址： GET /api/v1/requirement/{requirementId}

接口说明： 根据需求ID获取需求详细信息

---

7.3 新增需求

接口地址： POST /api/v1/requirement

接口说明： 创建新需求工单

请求参数：

参数名	类型	必填	说明
requirementCode	String	是	需求编号
requirementName	String	是	需求名称
description	String	否	需求描述
projectId	Long	是	项目ID
customerId	Long	是	客户ID
priority	String	否	优先级
estimatedHours	BigDecimal	否	预估工时
plannedStart	String	否	计划开始日期
plannedEnd	String	否	计划结束日期
receivableAmount	BigDecimal	否	应收款金额
receivableDate	String	否	应收款日期

---

7.4 更新需求

接口地址： PUT /api/v1/requirement/{requirementId}

接口说明： 更新需求信息

---

7.5 删除需求

接口地址： DELETE /api/v1/requirement/{requirementId}

接口说明： 删除需求

---

十一、支出管理接口

8.1 获取支出类型列表

接口地址： GET /api/v1/expense-type/list

接口说明： 获取支出类型树形列表

---

8.2 获取支出列表

接口地址： GET /api/v1/expense/list

接口说明： 分页查询支出列表

请求参数：

参数名	类型	必填	说明
current	Integer	否	当前页码
size	Integer	否	每页大小
expenseTypeId	Long	否	支出类型ID
projectId	Long	否	项目ID
startDate	String	否	开始日期
endDate	String	否	结束日期
status	String	否	状态

---

8.3 新增支出

接口地址： POST /api/v1/expense

接口说明： 创建新支出记录

请求参数：

参数名	类型	必填	说明
expenseCode	String	是	支出编号
expenseTypeId	Long	是	支出类型ID
expenseAmount	BigDecimal	是	支出金额
expenseDate	String	是	支出日期
expenseReason	String	否	支出事由
projectId	Long	否	项目ID
paymentMethod	String	否	付款方式

---

8.4 更新支出

接口地址： PUT /api/v1/expense/{expenseId}

接口说明： 更新支出信息

---

8.5 删除支出

接口地址： DELETE /api/v1/expense/{expenseId}

接口说明： 删除支出记录

---

十二、应收款管理接口

9.1 获取应收款列表

接口地址： GET /api/v1/receivable/list

接口说明： 分页查询应收款列表

请求参数：

参数名	类型	必填	说明
current	Integer	否	当前页码
size	Integer	否	每页大小
projectId	Long	否	项目ID
customerId	Long	否	客户ID
status	String	否	状态

---

9.2 获取应收款详情

接口地址： GET /api/v1/receivable/{receivableId}

接口说明： 根据应收款ID获取详细信息

---

9.3 新增应收款

接口地址： POST /api/v1/receivable

接口说明： 创建新应收款

请求参数：

参数名	类型	必填	说明
receivableCode	String	是	应收款编号
requirementId	Long	是	需求ID
projectId	Long	是	项目ID
customerId	Long	是	客户ID
receivableAmount	BigDecimal	是	应收款金额
receivableDate	String	是	应收款日期
paymentDueDate	String	否	付款截止日期

---

9.4 获取收款记录列表

接口地址： GET /api/v1/receivable/{receivableId}/receipts

接口说明： 获取应收款的收款记录

---

9.5 新增收款记录

接口地址： POST /api/v1/receivable/{receivableId}/receipts

接口说明： 添加收款记录

请求参数：

参数名	类型	必填	说明
receiptAmount	BigDecimal	是	收款金额
receiptDate	String	是	收款日期
receiptMethod	String	否	收款方式
receiptAccount	String	否	收款账户
payerName	String	否	付款方名称

---

十三、收款记录管理接口

10.1 获取收款记录列表

接口地址： GET /api/v1/receipt/list

接口说明： 分页查询收款记录列表

请求参数：

参数名	类型	必填	说明
current	Integer	否	当前页码（默认1）
size	Integer	否	每页大小（默认10）
receiptCode	String	否	收款编号（模糊查询）
receivableId	Long	否	应收款ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "receiptId": 1,
        "tenantId": 1,
        "receiptCode": "REC-2026-001",
        "receivableId": 1,
        "receiptAmount": 5000.00,
        "receiptDate": "2026-02-15",
        "receiptMethod": "transfer",
        "receiptAccount": "6222021234567890",
        "payerName": "阿里巴巴集团",
        "receiptVoucher": "V-20260215-001",
        "operatorId": 1,
        "remark": "首次付款",
        "createdTime": "2026-02-15 10:30:00"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}

---

10.2 获取收款记录详情

接口地址： GET /api/v1/receipt/{receiptId}

接口说明： 根据ID查询收款记录详情

路径参数：

参数名	类型	必填	说明
receiptId	Long	是	收款记录ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "receiptId": 1,
    "tenantId": 1,
    "receiptCode": "REC-2026-001",
    "receivableId": 1,
    "receiptAmount": 5000.00,
    "receiptDate": "2026-02-15",
    "receiptMethod": "transfer",
    "receiptAccount": "6222021234567890",
    "payerName": "阿里巴巴集团",
    "receiptVoucher": "V-20260215-001",
    "operatorId": 1,
    "remark": "首次付款",
    "createdTime": "2026-02-15 10:30:00"
  }
}

---

10.3 创建收款记录

接口地址： POST /api/v1/receipt

接口说明： 创建新的收款记录

请求参数：

参数名	类型	必填	说明
receiptCode	String	是	收款编号
receivableId	Long	是	应收款ID
receiptAmount	Decimal	是	收款金额
receiptDate	Date	否	收款日期
receiptMethod	String	否	收款方式（transfer/cash/check/other）
receiptAccount	String	否	收款账户
payerName	String	否	付款方名称
receiptVoucher	String	否	收款凭证
operatorId	Long	否	经办人ID（默认为当前用户）
remark	String	否	备注说明

请求示例：

{
  "receiptCode": "REC-2026-002",
  "receivableId": 1,
  "receiptAmount": 3000.00,
  "receiptDate": "2026-02-16",
  "receiptMethod": "transfer",
  "receiptAccount": "6222021234567890",
  "payerName": "阿里巴巴集团",
  "receiptVoucher": "V-20260216-001",
  "remark": "二次付款"
}

响应示例：

{
  "code": 200,
  "message": "创建成功",
  "data": null
}

---

10.4 更新收款记录

接口地址： PUT /api/v1/receipt/{receiptId}

接口说明： 更新收款记录信息

路径参数：

参数名	类型	必填	说明
receiptId	Long	是	收款记录ID

请求参数： 同创建接口

响应示例：

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

---

10.5 删除收款记录

接口地址： DELETE /api/v1/receipt/{receiptId}

接口说明： 删除收款记录

路径参数：

参数名	类型	必填	说明
receiptId	Long	是	收款记录ID

响应示例：

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

---

十四、操作日志管理接口

11.1 获取操作日志列表

接口地址： GET /api/v1/operation-log/list

接口说明： 分页查询操作日志列表，支持多条件过滤

请求参数：

参数名	类型	必填	说明
current	Long	否	当前页码，默认1
size	Long	否	每页条数，默认10
module	String	否	模块名称（模糊查询）
operationType	String	否	操作类型（SELECT/INSERT/UPDATE/DELETE/IMPORT/EXPORT/LOGIN/LOGOUT）
operatorId	Long	否	操作人ID
startTime	DateTime	否	开始时间（格式：yyyy-MM-dd HH:mm:ss）
endTime	DateTime	否	结束时间（格式：yyyy-MM-dd HH:mm:ss）

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "logId": 1,
        "tenantId": 1,
        "module": "用户管理",
        "operationType": "INSERT",
        "description": "创建用户",
        "requestMethod": "POST",
        "requestUrl": "/api/v1/user",
        "requestParams": "{\"username\":\"test\"}",
        "responseResult": "{\"code\":200}",
        "executionTime": 150,
        "operatorId": 1,
        "operatorName": "admin",
        "operatorIp": "192.168.1.100",
        "operatorLocation": "北京市",
        "status": 1,
        "errorMsg": null,
        "createdTime": "2026-02-13 10:00:00"
      }
    ],
    "total": 100,
    "size": 10,
    "current": 1
  }
}

---

11.2 获取操作日志详情

接口地址： GET /api/v1/operation-log/{logId}

接口说明： 根据ID查询操作日志详情

路径参数：

参数名	类型	必填	说明
logId	Long	是	日志ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "logId": 1,
    "tenantId": 1,
    "module": "用户管理",
    "operationType": "INSERT",
    "description": "创建用户",
    "requestMethod": "POST",
    "requestUrl": "/api/v1/user",
    "requestParams": "{\"username\":\"test\",\"email\":\"test@example.com\"}",
    "responseResult": "{\"code\":200,\"message\":\"操作成功\"}",
    "executionTime": 150,
    "operatorId": 1,
    "operatorName": "admin",
    "operatorIp": "192.168.1.100",
    "operatorLocation": "北京市",
    "status": 1,
    "errorMsg": null,
    "createdTime": "2026-02-13 10:00:00"
  }
}

---

11.3 删除操作日志

接口地址： DELETE /api/v1/operation-log/{logId}

接口说明： 删除指定的操作日志

路径参数：

参数名	类型	必填	说明
logId	Long	是	日志ID

响应示例：

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

---

11.4 批量删除操作日志

接口地址： DELETE /api/v1/operation-log/batch

接口说明： 批量删除指定天数之前的操作日志

请求参数：

参数名	类型	必填	说明
days	Long	是	天数（删除N天前的日志，建议7-365）

响应示例：

{
  "code": 200,
  "message": "批量删除成功",
  "data": null
}

---

11.5 操作类型说明

操作类型	说明	标签颜色
SELECT	查询操作	默认
INSERT	新增操作	绿色
UPDATE	更新操作	橙色
DELETE	删除操作	红色
IMPORT	导入操作	灰色
EXPORT	导出操作	灰色
LOGIN	登录操作	绿色
LOGOUT	登出操作	灰色

---

十五、数据统计分析接口

13.1 获取仪表盘统计数据

接口地址： GET /api/v1/dashboard

接口说明： 获取仪表盘全部统计数据，包含概览、收支、趋势、分布等多维度数据

请求参数：

参数名	类型	必填	说明
tenantId	Long	否	租户ID（不传则使用默认租户）

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "projectCount": 15,
    "customerCount": 28,
    "contractCount": 12,
    "requirementCount": 45,
    "totalIncome": 1250000.00,
    "totalExpense": 850000.00,
    "netProfit": 400000.00,
    "totalReceivable": 500000.00,
    "totalUnpaid": 150000.00,
    "overdueAmount": 30000.00,
    "monthIncome": 120000.00,
    "monthExpense": 80000.00,
    "monthNewProjects": 3,
    "monthNewCustomers": 5,
    "incomeTrend": [
      { "month": "2025-03", "amount": 95000.00 },
      { "month": "2025-04", "amount": 110000.00 },
      { "month": "2026-02", "amount": 120000.00 }
    ],
    "expenseTrend": [
      { "month": "2025-03", "amount": 65000.00 },
      { "month": "2025-04", "amount": 72000.00 },
      { "month": "2026-02", "amount": 80000.00 }
    ],
    "projectStatusDistribution": [
      { "name": "筹备中", "count": 3 },
      { "name": "进行中", "count": 8 },
      { "name": "已完成", "count": 3 },
      { "name": "已归档", "count": 1 }
    ],
    "expenseTypeDistribution": [
      { "name": "人力成本", "amount": 450000.00 },
      { "name": "设备采购", "amount": 200000.00 },
      { "name": "差旅费", "amount": 100000.00 },
      { "name": "其他", "amount": 100000.00 }
    ],
    "receivableStatusDistribution": [
      { "name": "待收款", "count": 5, "amount": 100000.00 },
      { "name": "部分收款", "count": 2, "amount": 30000.00 },
      { "name": "已收款", "count": 10, "amount": 350000.00 },
      { "name": "逾期", "count": 1, "amount": 20000.00 }
    ]
  }
}

---

13.2 响应字段说明

概览数据

字段名	类型	说明
projectCount	Long	项目总数
customerCount	Long	客户总数
contractCount	Long	合同总数
requirementCount	Long	需求工单总数

收支统计

字段名	类型	说明
totalIncome	Decimal	总收入（已收款金额）
totalExpense	Decimal	总支出（已付款金额）
netProfit	Decimal	净利润（总收入 - 总支出）
totalReceivable	Decimal	应收款总额
totalUnpaid	Decimal	未收款金额
overdueAmount	Decimal	逾期应收款金额

本月数据

字段名	类型	说明
monthIncome	Decimal	本月收入
monthExpense	Decimal	本月支出
monthNewProjects	Long	本月新增项目数
monthNewCustomers	Long	本月新增客户数

趋势数据

字段名	类型	说明
incomeTrend	List	月度收入趋势（最近12个月）
expenseTrend	List	月度支出趋势（最近12个月）

趋势项结构：

• month: 月份（格式：yyyy-MM）
• amount: 金额

分布数据

字段名	类型	说明
projectStatusDistribution	List	项目状态分布
expenseTypeDistribution	List	支出类型分布
receivableStatusDistribution	List	应收款状态分布

分布项结构：

• name: 名称/类型
• count: 数量（可选）
• amount: 金额（可选）

---

十六、文件管理接口

16.1 上传文件

接口地址： POST /api/v1/file/upload

接口说明： 上传文件到服务器

请求参数（multipart/form-data）：

参数名	类型	必填	说明
file	File	是	文件（支持图片、PDF、Office文档、文本等）
businessType	String	否	业务类型：contract-合同，receipt-收款凭证，expense-支出凭证，other-其他
businessId	Long	否	关联业务ID
uploadBy	Long	否	上传人ID
uploadName	String	否	上传人名称

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "fileId": 1,
    "tenantId": 1,
    "fileName": "a1b2c3d4e5f6.pdf",
    "originalName": "合同附件.pdf",
    "fileType": "application/pdf",
    "fileSize": 1024567,
    "filePath": "2026/02/13/a1b2c3d4e5f6.pdf",
    "fileUrl": "/uploads/2026/02/13/a1b2c3d4e5f6.pdf",
    "storageType": "local",
    "businessType": "contract",
    "businessId": 1001,
    "uploadBy": 1,
    "uploadName": "管理员",
    "status": 1,
    "createdTime": "2026-02-13 10:00:00"
  }
}

---

16.2 分页查询文件列表

接口地址： GET /api/v1/file/list

接口说明： 分页查询文件列表

请求参数：

参数名	类型	必填	说明
current	Long	否	当前页码，默认1
size	Long	否	每页条数，默认10
fileName	String	否	文件名（模糊查询）
businessType	String	否	业务类型
businessId	Long	否	关联业务ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "fileId": 1,
        "fileName": "a1b2c3d4e5f6.pdf",
        "originalName": "合同附件.pdf",
        "fileType": "application/pdf",
        "fileSize": 1024567,
        "fileUrl": "/uploads/2026/02/13/a1b2c3d4e5f6.pdf",
        "businessType": "contract",
        "businessId": 1001,
        "uploadName": "管理员",
        "createdTime": "2026-02-13 10:00:00"
      }
    ],
    "total": 50,
    "size": 10,
    "current": 1
  }
}

---

16.3 根据业务类型和ID查询文件列表

接口地址： GET /api/v1/file/list/business

接口说明： 查询指定业务关联的所有文件

请求参数：

参数名	类型	必填	说明
businessType	String	是	业务类型
businessId	Long	是	关联业务ID

响应示例： 同16.2

---

16.4 获取文件详情

接口地址： GET /api/v1/file/{fileId}

接口说明： 根据ID查询文件详情

路径参数：

参数名	类型	必填	说明
fileId	Long	是	文件ID

响应示例： 同16.1

---

16.5 删除文件

接口地址： DELETE /api/v1/file/{fileId}

接口说明： 删除指定文件（物理+逻辑删除）

路径参数：

参数名	类型	必填	说明
fileId	Long	是	文件ID

响应示例：

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

---

16.6 获取文件访问URL

接口地址： GET /api/v1/file/{fileId}/url

接口说明： 获取文件的访问URL

路径参数：

参数名	类型	必填	说明
fileId	Long	是	文件ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": "/uploads/2026/02/13/a1b2c3d4e5f6.pdf"
}

---

16.7 文件类型说明

支持的文件类型：

类型	MIME类型
图片	image/jpeg, image/png, image/gif, image/bmp
PDF	application/pdf
Word	application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document
Excel	application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
PPT	application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation
文本	text/plain, text/csv

限制：

• 最大文件大小：50MB

---

十七、附录

17.1 枚举值定义

性别（gender）

值	说明
0	未知
1	男
2	女

状态（status）

值	说明
0	禁用/停用
1	启用/正常

租户类型（tenantType）

值	说明
1	一库多租户
2	一库一租户

客户类型（customerType）

值	说明
enterprise	企业
individual	个人

客户等级（level）

值	说明
A	A级客户
B	B级客户
C	C级客户
D	D级客户
normal	普通客户

项目类型（projectType）

值	说明
development	开发
maintenance	维护
consulting	咨询

项目状态（status）

值	说明
preparing	筹备中
ongoing	进行中
completed	已完成
archived	已归档
cancelled	已取消

需求优先级（priority）

值	说明
high	高
normal	中
low	低

需求状态（status）

值	说明
pending	待开发
developing	开发中
delivered	已交付
completed	已完成

支出状态（status）

值	说明
pending	待付款
paid	已付款
completed	已完成
cancelled	已作废

应收款状态（status）

值	说明
pending	待收款
partial	部分收款
received	已收款
overdue	逾期

---

10.2 数据类型说明

类型	说明	示例
String	字符串	"hello"
Integer	整数	100
Long	长整数	10000000000
BigDecimal	高精度小数（金额）	100.50
Boolean	布尔值	true/false
Array	数组	[1, 2, 3]
Object	对象	{"key": "value"}

---

文档结束