企业资产管理系统——接口设计文档（完整版）

1 文档修订记录

序号	版本	修订内容	修订人	修订日期
1	V1.0	初稿创建	—	2026-07-28

2 目录

引言
通用规范
认证授权模块
工作台模块
资产管理模块
申请管理模块
审批中心模块
员工管理模块
部门管理模块
操作日志模块
附录

3 引言

3.1 编写目的

本文档为“企业资产管理系统”的完整接口设计文档，旨在为前后端开发人员提供统一的接口规范和详细的接口定义，确保团队协作开发时的接口一致性。

3.2 适用范围

本文档涵盖系统所有功能模块的接口定义，包括：认证授权、工作台、资产管理、申请管理、审批中心、员工管理、部门管理、操作日志，共计 8 个模块，50 个接口。

3.3 接口设计原则

序号	原则	说明
1	RESTful 风格	使用 HTTP 方法表达操作语义，资源使用名词复数
2	统一响应格式	所有接口返回统一的 JSON 结构
3	无状态认证	使用 JWT Token 进行身份认证
4	权限控制	每个接口标注所需权限码
5	版本管理	接口路径包含版本号（/api/v1）

4 通用规范

4.1 基础信息

项目	规范
Base URL	`/api/v1`
字符编码	UTF-8
数据格式	JSON（请求/响应均为 `application/json`）
日期时间格式	`yyyy-MM-dd HH:mm:ss`
日期格式	`yyyy-MM-dd`
认证方式	`Authorization: Bearer <token>`（登录接口除外）

4.2 统一响应格式

所有接口返回统一的 JSON 结构：

{
    "code": 200,
    "msg": "操作成功",
    "data": { ... },
    "timestamp": 1721800000000
}

状态码说明：

状态码	含义
200	操作成功
400	请求参数错误
401	未登录或 Token 过期
403	无权限访问
404	资源不存在
409	数据冲突（如编码重复）
500	服务器内部错误

4.3 分页请求参数

参数名	类型	必填	默认值	说明
pageNum	int	否	1	当前页码（从 1 开始）
pageSize	int	否	10	每页记录数
orderBy	string	否	create_time DESC	排序字段

4.4 分页响应格式

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "list": [ ... ],
        "total": 100,
        "pageNum": 1,
        "pageSize": 10,
        "pages": 10
    },
    "timestamp": 1721800000000
}

5 认证授权模块

5.1 模块概述

负责用户身份认证和授权，包括登录、获取当前用户信息、登出和刷新 Token。

权限码映射： 本模块无特殊权限码要求

5.2 接口列表

序号	方法	URL	功能	权限要求
1	POST	`/auth/login`	用户登录	无
2	GET	`/auth/current-user`	获取当前用户信息	已登录
3	POST	`/auth/logout`	退出登录	已登录
4	POST	`/auth/refresh-token`	刷新 Token	已登录

5.3 接口详情

5.3.1 用户登录

请求：

POST /api/v1/auth/login
Content-Type: application/json

请求参数：

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

参数说明：

参数名	类型	必填	说明
username	string	是	登录账号
password	string	是	登录密码

响应（成功）：

{
    "code": 200,
    "msg": "登录成功",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "expiresIn": 7200,
        "userInfo": {
            "id": 1,
            "username": "admin",
            "realName": "系统管理员",
            "departmentId": 1,
            "departmentName": "研发部",
            "email": "admin@company.com",
            "phone": "13800000001",
            "roles": ["ADMIN"],
            "permissions": ["dashboard:view", "asset:list", "asset:add", "..."]
        },
        "menuTree": [
            {
                "id": 1,
                "permName": "工作台",
                "permCode": "dashboard:menu",
                "url": "/dashboard",
                "icon": "dashboard",
                "children": [
                    {
                        "id": 11,
                        "permName": "数据概览",
                        "permCode": "dashboard:view",
                        "url": "/dashboard/index",
                        "children": []
                    }
                ]
            }
        ]
    },
    "timestamp": 1721800000000
}

响应（失败）：

{
    "code": 401,
    "msg": "用户名或密码错误",
    "data": null,
    "timestamp": 1721800000000
}

5.3.2 获取当前用户信息

请求：

GET /api/v1/auth/current-user
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "username": "admin",
        "realName": "系统管理员",
        "departmentId": 1,
        "departmentName": "研发部",
        "email": "admin@company.com",
        "phone": "13800000001",
        "roles": ["ADMIN"],
        "permissions": ["dashboard:view", "asset:list", ...],
        "menuTree": [...]
    },
    "timestamp": 1721800000000
}

5.3.3 退出登录

请求：

POST /api/v1/auth/logout
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "退出成功",
    "data": null,
    "timestamp": 1721800000000
}

5.3.4 刷新 Token

请求：

POST /api/v1/auth/refresh-token
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "刷新成功",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "expiresIn": 7200
    },
    "timestamp": 1721800000000
}

6 工作台模块

6.1 模块概述

为登录用户提供首页数据概览和待办事项聚合，根据用户角色展示不同内容。

权限码映射： dashboard:menu（目录）、dashboard:view（数据概览）

6.2 接口列表

序号	方法	URL	功能	权限要求
5	GET	`/dashboard/statistics`	获取数据概览	`dashboard:view`
6	GET	`/dashboard/todos`	待办事项列表	`dashboard:view`
7	GET	`/dashboard/chart/status`	资产状态分布	`dashboard:view`

6.3 接口详情

6.3.1 获取数据概览

请求：

GET /api/v1/dashboard/statistics
Authorization: Bearer <token>

响应（管理员）：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "totalAssets": 1568,
        "inStockCount": 320,
        "usedCount": 1120,
        "repairingCount": 68,
        "scrappedCount": 60,
        "pendingApprovals": 12,
        "thisMonthAdded": 45
    },
    "timestamp": 1721800000000
}

响应（普通员工）：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "totalAssets": 1568,
        "myUsedCount": 3,
        "myPendingApplications": 1,
        "myApprovedApplications": 5,
        "thisMonthAdded": 45
    },
    "timestamp": 1721800000000
}

6.3.2 待办事项列表

请求：

GET /api/v1/dashboard/todos?pageNum=1&pageSize=10
Authorization: Bearer <token>

请求参数：

参数名	类型	必填	说明
pageNum	int	否	页码
pageSize	int	否	每页数量

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "list": [
            {
                "id": 1,
                "type": "approve",
                "title": "您有 3 条待审批的资产申请",
                "content": "张三申请领用 联想ThinkPad X1，请及时审批",
                "url": "/approve/pending",
                "priority": 1,
                "priorityLabel": "高",
                "status": 0,
                "statusLabel": "待处理",
                "createTime": "2026-07-23 09:30:00"
            }
        ],
        "total": 2,
        "pageNum": 1,
        "pageSize": 10
    },
    "timestamp": 1721800000000
}

6.3.3 资产状态分布

请求：

GET /api/v1/dashboard/chart/status
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "series": [
            { "name": "在库", "value": 320 },
            { "name": "已领用", "value": 1120 },
            { "name": "维修中", "value": 68 },
            { "name": "已报废", "value": 60 }
        ]
    },
    "timestamp": 1721800000000
}

7 资产管理模块

7.1 模块概述

负责资产分类和资产档案的增删改查，以及资产的导入导出功能。

权限码映射： asset:menu（目录）、asset:list（资产列表）、asset:category（资产分类）、asset:add（添加）、asset:edit（编辑）、asset:delete（删除）、asset:export（导出）

7.2 资产分类接口

序号	方法	URL	功能	权限要求
10	GET	`/asset/categories/tree`	查询分类树	`asset:list`
11	POST	`/asset/categories`	新增分类	`asset:add`
12	PUT	`/asset/categories/{id}`	编辑分类	`asset:edit`
13	DELETE	`/asset/categories/{id}`	删除分类	`asset:delete`

7.3 资产档案接口

序号	方法	URL	功能	权限要求
14	GET	`/asset/assets`	分页查询资产	`asset:list`
15	GET	`/asset/assets/{id}`	查询资产详情	`asset:list`
16	POST	`/asset/assets`	新增资产（入库）	`asset:add`
17	PUT	`/asset/assets/{id}`	编辑资产	`asset:edit`
18	DELETE	`/asset/assets/{id}`	删除资产（逻辑）	`asset:delete`
19	PUT	`/asset/assets/{id}/status`	变更资产状态	`asset:edit`
20	GET	`/asset/assets/export`	导出资产列表	`asset:export`
21	POST	`/asset/assets/import`	批量导入资产	`asset:add`
22	GET	`/asset/assets/{id}/logs`	查询资产操作履历	`asset:list`

7.4 接口详情

7.4.1 分页查询资产

请求：

GET /api/v1/asset/assets?pageNum=1&pageSize=10&assetName=电脑&categoryId=11&status=1
Authorization: Bearer <token>

请求参数：

参数名	类型	必填	说明
pageNum	int	否	页码
pageSize	int	否	每页数量
assetCode	string	否	资产编码（精确）
assetName	string	否	资产名称（模糊）
categoryId	long	否	分类 ID
status	int	否	状态（1-4）
deptId	long	否	归属部门 ID
userId	long	否	使用人 ID

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "list": [
            {
                "id": 1,
                "assetCode": "ASSET-2026-001",
                "assetName": "联想ThinkPad X1",
                "categoryId": 11,
                "categoryName": "计算机设备",
                "specification": "i7-1260P/16G/512G",
                "unit": "台",
                "originalValue": 9800.00,
                "purchaseDate": "2026-01-10",
                "supplier": "联想集团",
                "location": "研发一部-3号位",
                "status": 2,
                "statusLabel": "已领用",
                "currentUserId": 2,
                "currentUserRealName": "张三",
                "currentDepartmentId": 4,
                "departmentName": "研发一部",
                "createTime": "2026-01-10 10:00:00"
            }
        ],
        "total": 50,
        "pageNum": 1,
        "pageSize": 10
    },
    "timestamp": 1721800000000
}

7.4.2 查询资产详情

请求：

GET /api/v1/asset/assets/{id}
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "assetCode": "ASSET-2026-001",
        "assetName": "联想ThinkPad X1",
        "categoryId": 11,
        "categoryName": "计算机设备",
        "specification": "i7-1260P/16G/512G",
        "unit": "台",
        "originalValue": 9800.00,
        "purchaseDate": "2026-01-10",
        "supplier": "联想集团",
        "location": "研发一部-3号位",
        "status": 2,
        "statusLabel": "已领用",
        "currentUserId": 2,
        "currentUserRealName": "张三",
        "currentDepartmentId": 4,
        "departmentName": "研发一部",
        "isDeleted": 0,
        "createBy": 1,
        "createByRealName": "系统管理员",
        "updateBy": 1,
        "updateByRealName": "系统管理员",
        "createTime": "2026-01-10 10:00:00",
        "updateTime": "2026-01-15 14:30:00"
    },
    "timestamp": 1721800000000
}

7.4.3 新增资产（入库）

请求：

POST /api/v1/asset/assets
Authorization: Bearer <token>
Content-Type: application/json

请求参数：

{
    "assetName": "联想ThinkPad X1",
    "categoryId": 11,
    "specification": "i7-1260P/16G/512G",
    "unit": "台",
    "originalValue": 9800.00,
    "purchaseDate": "2026-01-10",
    "supplier": "联想集团",
    "location": "研发一部-3号位",
    "status": 1,
    "currentUserId": null,
    "currentDepartmentId": 4
}

参数说明：

参数名	类型	必填	说明
assetName	string	是	资产名称
categoryId	long	是	分类 ID
specification	string	否	规格型号
unit	string	否	计量单位
originalValue	decimal(18,2)	否	原值
purchaseDate	date	否	购入日期
supplier	string	否	供应商
location	string	否	存放位置
status	int	否	状态（默认 1）
currentUserId	long	否	当前使用人 ID
currentDepartmentId	long	否	当前归属部门 ID

响应：

{
    "code": 200,
    "msg": "入库成功",
    "data": {
        "id": 1,
        "assetCode": "ASSET-2026-001"
    },
    "timestamp": 1721800000000
}

7.4.4 编辑资产

请求：

PUT /api/v1/asset/assets/{id}
Authorization: Bearer <token>
Content-Type: application/json

请求参数：（与新增相同，字段均为可选）

{
    "assetName": "联想ThinkPad X1 升级版",
    "location": "研发一部-5号位",
    "status": 2
}

响应：

{
    "code": 200,
    "msg": "编辑成功",
    "data": null,
    "timestamp": 1721800000000
}

7.4.5 删除资产（逻辑删除）

请求：

DELETE /api/v1/asset/assets/{id}
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "删除成功",
    "data": null,
    "timestamp": 1721800000000
}

7.4.6 变更资产状态

请求：

PUT /api/v1/asset/assets/{id}/status
Authorization: Bearer <token>
Content-Type: application/json

请求参数：

{
    "status": 2,
    "remark": "已领用给张三"
}

参数说明：

参数名	类型	必填	说明
status	int	是	1- 在库，2- 已领用，3- 维修中，4- 已报废
remark	string	否	变更说明

响应：

{
    "code": 200,
    "msg": "状态变更成功",
    "data": null,
    "timestamp": 1721800000000
}

7.4.7 导出资产列表

请求：

GET /api/v1/asset/assets/export?assetName=电脑&categoryId=11
Authorization: Bearer <token>

请求参数： 同分页查询

响应： 返回 Excel 文件流（application/vnd.openxmlformats-officedocument.spreadsheetml.sheet）

7.4.8 批量导入资产

请求：

POST /api/v1/asset/assets/import
Authorization: Bearer <token>
Content-Type: multipart/form-data

请求参数：

参数名	类型	必填	说明
file	MultipartFile	是	Excel 文件（.xlsx）

响应：

{
    "code": 200,
    "msg": "导入成功，共导入 20 条数据",
    "data": {
        "total": 20,
        "success": 20,
        "fail": 0,
        "failList": []
    },
    "timestamp": 1721800000000
}

导入失败响应：

{
    "code": 400,
    "msg": "导入完成，成功 18 条，失败 2 条",
    "data": {
        "total": 20,
        "success": 18,
        "fail": 2,
        "failList": [
            {
                "row": 5,
                "reason": "资产编码 ASSET-2026-009 已存在"
            },
            {
                "row": 12,
                "reason": "分类编码 CAT-ELEC 不存在"
            }
        ]
    },
    "timestamp": 1721800000000
}

7.4.9 查询资产操作履历

请求：

GET /api/v1/asset/assets/{id}/logs
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "list": [
            {
                "traceType": "入库",
                "fromUser": null,
                "toUser": "系统管理员",
                "fromDept": null,
                "toDept": "研发部",
                "fromLocation": null,
                "toLocation": "研发一部-3号位",
                "remark": "原值9800.00元",
                "operationTime": "2026-01-10 10:00:00"
            },
            {
                "traceType": "领用",
                "fromUser": null,
                "toUser": "张三",
                "fromDept": "研发部",
                "toDept": "研发一部",
                "fromLocation": "研发一部-3号位",
                "toLocation": "研发一部-3号位",
                "remark": "新员工入职配置",
                "operationTime": "2026-01-15 14:30:00"
            }
        ]
    },
    "timestamp": 1721800000000
}

8 申请管理模块

8.1 模块概述

负责普通员工提交资产申请、编辑草稿、提交审批、撤销申请等功能。

权限码映射： apply:menu（目录）、apply:my（我的申请）、apply:add（新建申请）

8.2 接口列表

序号	方法	URL	功能	权限要求
23	GET	`/asset/applications`	分页查询申请单	`apply:my`
24	GET	`/asset/applications/{id}`	查询申请单详情	`apply:my`
25	POST	`/asset/applications`	新建申请（草稿）	`apply:add`
26	PUT	`/asset/applications/{id}`	编辑申请（草稿态）	`apply:add`
27	PUT	`/asset/applications/{id}/submit`	提交申请	`apply:add`
28	PUT	`/asset/applications/{id}/cancel`	撤销申请	`apply:add`
29	DELETE	`/asset/applications/{id}`	删除申请（草稿态）	`apply:add`

8.3 接口详情

8.3.1 分页查询申请单

请求：

GET /api/v1/asset/applications?pageNum=1&pageSize=10&status=1
Authorization: Bearer <token>

请求参数：

参数名	类型	必填	说明
pageNum	int	否	页码
pageSize	int	否	每页数量
status	int	否	状态（0-4）
startTime	string	否	开始时间
endTime	string	否	结束时间

数据权限： 普通员工仅看自己，部门经理看本部门，管理员看全部

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "list": [
            {
                "id": 1,
                "applicationNo": "APP-20260701-001",
                "applicantId": 2,
                "applicantName": "张三",
                "departmentId": 4,
                "departmentName": "研发一部",
                "assetId": 6,
                "assetName": "工学办公桌",
                "assetCode": "ASSET-2026-006",
                "applyQuantity": 1,
                "applyReason": "新员工入职，需配备办公桌",
                "applyTime": "2026-07-01 09:30:00",
                "status": 2,
                "statusLabel": "已通过",
                "currentLevel": 1
            }
        ],
        "total": 15,
        "pageNum": 1,
        "pageSize": 10
    },
    "timestamp": 1721800000000
}

8.3.2 查询申请单详情

请求：

GET /api/v1/asset/applications/{id}
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "applicationNo": "APP-20260701-001",
        "applicantId": 2,
        "applicantName": "张三",
        "departmentId": 4,
        "departmentName": "研发一部",
        "assetId": 6,
        "assetName": "工学办公桌",
        "assetCode": "ASSET-2026-006",
        "applyQuantity": 1,
        "applyReason": "新员工入职，需配备办公桌",
        "applyTime": "2026-07-01 09:30:00",
        "status": 2,
        "statusLabel": "已通过",
        "currentLevel": 1,
        "approvalRecords": [
            {
                "approverId": 3,
                "approverName": "李四",
                "approveLevel": 1,
                "approveAction": 1,
                "approveActionLabel": "通过",
                "approveComment": "同意购买，费用从部门经费出",
                "approveTime": "2026-07-01 10:00:00"
            }
        ]
    },
    "timestamp": 1721800000000
}

8.3.3 新建申请（草稿）

请求：

POST /api/v1/asset/applications
Authorization: Bearer <token>
Content-Type: application/json

请求参数：

{
    "assetId": 7,
    "applyQuantity": 2,
    "applyReason": "办公区更换新椅子"
}

响应：

{
    "code": 200,
    "msg": "草稿创建成功",
    "data": {
        "id": 4,
        "applicationNo": "APP-20260705-004"
    },
    "timestamp": 1721800000000
}

8.3.4 提交申请（草稿→待审批）

请求：

PUT /api/v1/asset/applications/{id}/submit
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "提交成功，等待审批",
    "data": null,
    "timestamp": 1721800000000
}

错误响应（库存不足）：

{
    "code": 400,
    "msg": "库存不足，当前在库数量为 0",
    "data": null,
    "timestamp": 1721800000000
}

8.3.5 撤销申请

请求：

PUT /api/v1/asset/applications/{id}/cancel
Authorization: Bearer <token>
Content-Type: application/json

请求参数：

{
    "reason": "申请内容有误，需要修改"
}

响应：

{
    "code": 200,
    "msg": "撤销成功",
    "data": null,
    "timestamp": 1721800000000
}

8.3.6 删除申请（仅草稿态）

请求：

DELETE /api/v1/asset/applications/{id}
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "删除成功",
    "data": null,
    "timestamp": 1721800000000
}

9 审批中心模块

9.1 模块概述

负责部门经理和管理员的审批操作，包括待审批列表、审批通过、审批驳回、审批历史等功能。

权限码映射： approve:menu（目录）、approve:pending（待审批）、approve:history（已审批）、approve:pass（通过）、approve:reject（驳回）

9.2 接口列表

序号	方法	URL	功能	权限要求
30	GET	`/asset/approvals/pending`	待审批列表	`approve:pending`
31	GET	`/asset/approvals/history`	已审批历史	`approve:history`
32	PUT	`/asset/approvals/pass`	审批通过	`approve:pass`
33	PUT	`/asset/approvals/reject`	审批驳回	`approve:reject`

9.3 接口详情

9.3.1 待审批列表

请求：

GET /api/v1/asset/approvals/pending?pageNum=1&pageSize=10
Authorization: Bearer <token>

数据权限： 部门经理仅看本部门，管理员看全部

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "list": [
            {
                "id": 2,
                "applicationNo": "APP-20260702-002",
                "applicantId": 4,
                "applicantName": "王五",
                "departmentId": 2,
                "departmentName": "销售部",
                "assetId": 5,
                "assetName": "华为Mate 40 Pro",
                "applyQuantity": 1,
                "applyReason": "销售外勤需要通讯设备",
                "applyTime": "2026-07-02 14:20:00",
                "currentLevel": 1
            }
        ],
        "total": 5,
        "pageNum": 1,
        "pageSize": 10
    },
    "timestamp": 1721800000000
}

9.3.2 已审批历史

请求：

GET /api/v1/asset/approvals/history?pageNum=1&pageSize=10
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "list": [
            {
                "id": 1,
                "applicationNo": "APP-20260701-001",
                "applicantName": "张三",
                "departmentName": "研发一部",
                "assetName": "工学办公桌",
                "approveAction": 1,
                "approveActionLabel": "通过",
                "approveComment": "同意",
                "approveTime": "2026-07-01 10:00:00"
            }
        ],
        "total": 20,
        "pageNum": 1,
        "pageSize": 10
    },
    "timestamp": 1721800000000
}

9.3.3 审批通过（核心事务接口）

请求：

PUT /api/v1/asset/approvals/pass
Authorization: Bearer <token>
Content-Type: application/json

请求参数：

{
    "applicationId": 2,
    "approveComment": "批准，请采购部配合"
}

响应：

{
    "code": 200,
    "msg": "审批通过，资产已更新领用状态",
    "data": null,
    "timestamp": 1721800000000
}

事务说明：

1. 校验：申请单状态为“待审批(1)”
2. 插入：asset_approval_record（审批记录）
3. 更新：asset_application.status = 2（已通过）
4. 更新：asset.status = 2（已领用）
5. 更新：asset.current_user_id = 申请人ID
6. 更新：asset.current_department_id = 申请人部门ID
7. 记录：operation_log（操作日志）
8. todo标记为已处理
9. 事务提交（任一步骤失败，全部回滚）

9.3.4 审批驳回

请求：

PUT /api/v1/asset/approvals/reject
Authorization: Bearer <token>
Content-Type: application/json

请求参数：

{
    "applicationId": 3,
    "approveComment": "现有打印机还能用，暂不采购"
}

响应：

{
    "code": 200,
    "msg": "驳回成功",
    "data": null,
    "timestamp": 1721800000000
}

事务说明：

1. 校验：申请单状态为“待审批(1)”
2. 插入：asset_approval_record（审批记录，action=2）
3. 更新：asset_application.status = 3（已驳回）
4. 记录：operation_log（操作日志）
5. todo标记为已处理
6. 事务提交（资产状态不变）

10 员工管理模块

10.1 模块概述

负责系统用户的增删改查、状态管理、角色分配、密码重置等功能。

权限码映射： user:menu（目录）、user:list（员工列表）、user:add（添加）、user:edit（编辑）、user:delete（删除）、user:assign（分配角色）

10.2 接口列表

序号	方法	URL	功能	权限要求
34	GET	`/system/users`	分页查询员工	`user:list`
35	GET	`/system/users/{id}`	查询员工详情	`user:list`
36	POST	`/system/users`	新增员工	`user:add`
37	PUT	`/system/users/{id}`	编辑员工	`user:edit`
38	DELETE	`/system/users/{id}`	删除员工（逻辑）	`user:delete`
39	PUT	`/system/users/{id}/status`	启用/禁用员工	`user:edit`
40	PUT	`/system/users/{id}/roles`	分配角色	`user:assign`
41	PUT	`/system/users/{id}/password`	重置密码	`user:edit`
42	GET	`/system/users/roles/list`	查询全部角色列表	`user:list`

10.3 接口详情

10.3.1 分页查询员工

请求：

GET /api/v1/system/users?pageNum=1&pageSize=10&realName=张&deptId=1
Authorization: Bearer <token>

请求参数：

参数名	类型	必填	说明
pageNum	int	否	页码
pageSize	int	否	每页数量
realName	string	否	姓名（模糊）
username	string	否	账号（精确）
deptId	long	否	部门 ID
status	int	否	状态（0 禁用 1 启用）

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "list": [
            {
                "id": 2,
                "username": "zhangsan",
                "realName": "张三",
                "departmentId": 4,
                "departmentName": "研发一部",
                "email": "zhangsan@company.com",
                "phone": "13800000002",
                "status": 1,
                "statusLabel": "启用",
                "roleNames": ["普通员工"],
                "createTime": "2026-01-01 09:00:00"
            }
        ],
        "total": 20,
        "pageNum": 1,
        "pageSize": 10
    },
    "timestamp": 1721800000000
}

10.3.2 新增员工

请求：

POST /api/v1/system/users
Authorization: Bearer <token>
Content-Type: application/json

请求参数：

{
    "username": "zhangsan",
    "password": "123456",
    "realName": "张三",
    "email": "zhangsan@company.com",
    "phone": "13800000002",
    "departmentId": 4,
    "roleIds": [3]
}

参数说明：

参数名	类型	必填	说明
username	string	是	登录账号（唯一）
password	string	是	登录密码
realName	string	是	真实姓名
email	string	否	邮箱
phone	string	否	手机号
departmentId	long	否	部门 ID
roleIds	array	否	角色 ID 列表

响应：

{
    "code": 200,
    "msg": "新增成功",
    "data": {
        "id": 2
    },
    "timestamp": 1721800000000
}

10.3.3 分配角色

请求：

PUT /api/v1/system/users/{id}/roles
Authorization: Bearer <token>
Content-Type: application/json

请求参数：

{
    "roleIds": [2, 3]
}

响应：

{
    "code": 200,
    "msg": "角色分配成功",
    "data": null,
    "timestamp": 1721800000000
}

10.3.4 重置密码

请求：

PUT /api/v1/system/users/{id}/password
Authorization: Bearer <token>
Content-Type: application/json

请求参数：

{
    "newPassword": "123456"
}

响应：

{
    "code": 200,
    "msg": "密码重置成功",
    "data": null,
    "timestamp": 1721800000000
}

11 部门管理模块

11.1 模块概述

负责部门的树形结构管理，包括部门的增删改查和部门经理设置。

权限码映射： dept:menu（目录）、dept:list（部门列表）、dept:add（添加）、dept:edit（编辑）、dept:delete（删除）

11.2 接口列表

序号	方法	URL	功能	权限要求
43	GET	`/system/depts/tree`	查询部门树	`dept:list`
44	POST	`/system/depts`	新增部门	`dept:add`
45	PUT	`/system/depts/{id}`	编辑部门	`dept:edit`
46	DELETE	`/system/depts/{id}`	删除部门	`dept:delete`
47	GET	`/system/depts/list`	查询部门下拉列表	`dept:list`

11.3 接口详情

11.3.1 查询部门树

请求：

GET /api/v1/system/depts/tree
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "id": 1,
            "deptName": "研发部",
            "parentId": null,
            "leaderId": null,
            "leaderName": null,
            "sortNum": 1,
            "children": [
                {
                    "id": 4,
                    "deptName": "研发一部",
                    "parentId": 1,
                    "leaderId": 3,
                    "leaderName": "李四",
                    "sortNum": 1,
                    "children": []
                }
            ]
        }
    ],
    "timestamp": 1721800000000
}

12 操作日志模块

12.1 模块概述

负责系统操作日志的记录和查询，所有关键操作通过 AOP 切面自动记录。

权限码映射： log:menu（目录）、log:list（操作日志）、log:detail（详情）、log:export（导出）

12.2 接口列表

序号	方法	URL	功能	权限要求
48	GET	`/system/logs`	分页查询操作日志	`log:list`
49	GET	`/system/logs/{id}`	查询日志详情	`log:detail`
50	GET	`/system/logs/export`	导出操作日志	`log:export`

12.3 接口详情

12.3.1 分页查询操作日志

请求：

GET /api/v1/system/logs?pageNum=1&pageSize=10&username=admin&module=审批管理&startTime=2026-07-01&endTime=2026-07-31
Authorization: Bearer <token>

请求参数：

参数名	类型	必填	说明
pageNum	int	否	页码
pageSize	int	否	每页数量
username	string	否	操作用户（精确）
module	string	否	操作模块
operation	string	否	操作内容（模糊）
startTime	string	否	开始时间
endTime	string	否	结束时间

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "list": [
            {
                "id": 1,
                "userId": 1,
                "username": "admin",
                "module": "审批管理",
                "operation": "审批通过申请单 APP-20260701-001",
                "ipAddress": "192.168.1.100",
                "requestUrl": "/api/v1/asset/approvals/pass",
                "requestMethod": "PUT",
                "durationMs": 32,
                "createTime": "2026-07-01 10:00:00.000"
            }
        ],
        "total": 1250,
        "pageNum": 1,
        "pageSize": 10
    },
    "timestamp": 1721800000000
}

12.3.2 查询日志详情

请求：

GET /api/v1/system/logs/{id}
Authorization: Bearer <token>

响应：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "userId": 1,
        "username": "admin",
        "module": "审批管理",
        "operation": "审批通过申请单 APP-20260701-001",
        "ipAddress": "192.168.1.100",
        "requestUrl": "/api/v1/asset/approvals/pass",
        "requestMethod": "PUT",
        "requestParams": "{\"applicationId\":1,\"approveComment\":\"同意\"}",
        "result": "{\"code\":200,\"msg\":\"审批通过\"}",
        "durationMs": 32,
        "createTime": "2026-07-01 10:00:00.000"
    },
    "timestamp": 1721800000000
}

13 附录

13.1 接口统计

模块	接口数量	权限要求
认证授权模块	4	1 个无权限 + 3 个需登录
工作台模块	5	需 `dashboard:view`
资产管理模块	13	需对应 `asset:*` 权限
申请管理模块	7	需 `apply:my` 或 `apply:add`
审批中心模块	4	需 `approve:*` 权限
员工管理模块	9	需 `user:*` 权限
部门管理模块	5	需 `dept:*` 权限
操作日志模块	3	需 `log:*` 权限
合计	50	—

13.2 权限码与菜单映射

权限码	类型	父级	说明
`dashboard:menu`	目录	—	工作台
`dashboard:view`	菜单	`dashboard:menu`	数据概览
`asset:menu`	目录	—	资产管理
`asset:list`	菜单	`asset:menu`	资产列表
`asset:category`	菜单	`asset:menu`	资产分类
`asset:add`	按钮	`asset:list`	添加资产
`asset:edit`	按钮	`asset:list`	编辑资产
`asset:delete`	按钮	`asset:list`	删除资产
`asset:export`	按钮	`asset:list`	导出资产
`apply:menu`	目录	—	申请管理
`apply:my`	菜单	`apply:menu`	我的申请
`apply:add`	菜单	`apply:menu`	新建申请
`approve:menu`	目录	—	审批中心
`approve:pending`	菜单	`approve:menu`	待审批
`approve:history`	菜单	`approve:menu`	已审批
`approve:pass`	按钮	`approve:pending`	审批通过
`approve:reject`	按钮	`approve:pending`	审批驳回
`dept:menu`	目录	—	部门管理
`dept:list`	菜单	`dept:menu`	部门列表
`dept:add`	按钮	`dept:list`	添加部门
`dept:edit`	按钮	`dept:list`	编辑部门
`dept:delete`	按钮	`dept:list`	删除部门
`user:menu`	目录	—	员工管理
`user:list`	菜单	`user:menu`	员工列表
`user:add`	按钮	`user:list`	添加员工
`user:edit`	按钮	`user:list`	编辑员工
`user:delete`	按钮	`user:list`	删除员工
`user:assign`	按钮	`user:list`	分配角色
`log:menu`	目录	—	日志管理
`log:list`	菜单	`log:menu`	操作日志
`log:detail`	按钮	`log:list`	日志详情
`log:export`	按钮	`log:list`	日志导出

文档版本：V1.0 编写日期：2026-07-28 适用项目：企业资产管理系统 接口总数：50 个 编制单位：项目技术组

Investigator Veritatis

Explorer

接口详细文档

企业资产管理系统——接口设计文档（完整版）

1 文档修订记录

2 目录

3 引言

3.1 编写目的

3.2 适用范围

3.3 接口设计原则

4 通用规范

4.1 基础信息

4.2 统一响应格式

4.3 分页请求参数

4.4 分页响应格式

5 认证授权模块

5.1 模块概述

5.2 接口列表

5.3 接口详情

5.3.1 用户登录

5.3.2 获取当前用户信息

5.3.3 退出登录

5.3.4 刷新 Token

6 工作台模块

6.1 模块概述

6.2 接口列表

6.3 接口详情

6.3.1 获取数据概览

6.3.2 待办事项列表

6.3.3 资产状态分布

7 资产管理模块

7.1 模块概述

7.2 资产分类接口

7.3 资产档案接口

7.4 接口详情

7.4.1 分页查询资产

7.4.2 查询资产详情

7.4.3 新增资产（入库）

7.4.4 编辑资产

7.4.5 删除资产（逻辑删除）

7.4.6 变更资产状态

7.4.7 导出资产列表

7.4.8 批量导入资产

7.4.9 查询资产操作履历

8 申请管理模块

8.1 模块概述

8.2 接口列表

8.3 接口详情

8.3.1 分页查询申请单

8.3.2 查询申请单详情

8.3.3 新建申请（草稿）

8.3.4 提交申请（草稿→待审批）

8.3.5 撤销申请

8.3.6 删除申请（仅草稿态）

9 审批中心模块

9.1 模块概述

9.2 接口列表

9.3 接口详情

9.3.1 待审批列表

9.3.2 已审批历史

9.3.3 审批通过（核心事务接口）

9.3.4 审批驳回

10 员工管理模块

10.1 模块概述

10.2 接口列表

10.3 接口详情

10.3.1 分页查询员工

10.3.2 新增员工

10.3.3 分配角色

10.3.4 重置密码

11 部门管理模块

11.1 模块概述

11.2 接口列表

11.3 接口详情

11.3.1 查询部门树

12 操作日志模块

12.1 模块概述

12.2 接口列表

12.3 接口详情

12.3.1 分页查询操作日志