# 采购交易信息管理 - API接口文档 ## 文档信息 - **模块名称**: 采购交易信息管理 - **Controller**: `CcdiPurchaseTransactionController` - **Base Path**: `/ccdi/purchaseTransaction` - **Swagger**: http://localhost:8080/swagger-ui/index.html - **生成时间**: 2026-02-06 --- ## 目录 1. [接口列表](#接口列表) 2. [接口详情](#接口详情) 3. [数据模型](#数据模型) 4. [错误码说明](#错误码说明) 5. [接口示例](#接口示例) --- ## 接口列表 | 序号 | 接口名称 | HTTP方法 | 路径 | 权限标识 | 说明 | |----|----------|--------|--------------------------|---------------------------------|-------------| | 1 | 查询采购交易列表 | GET | /list | ccdi:purchaseTransaction:list | 分页查询采购交易信息 | | 2 | 获取采购交易详情 | GET | /{purchaseId} | ccdi:purchaseTransaction:query | 根据ID获取详细信息 | | 3 | 新增采购交易 | POST | / | ccdi:purchaseTransaction:add | 新增采购交易记录 | | 4 | 修改采购交易 | PUT | / | ccdi:purchaseTransaction:edit | 修改采购交易记录 | | 5 | 删除采购交易 | DELETE | /{purchaseIds} | ccdi:purchaseTransaction:remove | 删除采购交易记录 | | 6 | 导出采购交易 | POST | /export | ccdi:purchaseTransaction:export | 导出Excel文件 | | 7 | 下载导入模板 | POST | /importTemplate | 无 | 下载带下拉框的模板 | | 8 | 导入采购交易 | POST | /importData | ccdi:purchaseTransaction:import | 异步导入Excel数据 | | 9 | 查询导入状态 | GET | /importStatus/{taskId} | ccdi:purchaseTransaction:import | 查询异步导入进度 | | 10 | 查询导入失败记录 | GET | /importFailures/{taskId} | ccdi:purchaseTransaction:import | 查询导入失败详情 | --- ## 接口详情 ### 1. 查询采购交易列表 **接口描述**: 分页查询采购交易信息列表，支持多条件查询 **请求方式**: `GET` **请求路径**: `/ccdi/purchaseTransaction/list` **权限要求**: `ccdi:purchaseTransaction:list` **请求参数**: | 参数名 | 类型 | 必填 | 说明 | 示例值 | |------------------------|---------|----|-------------|------------| | pageNum | Integer | 否 | 页码，默认1 | 1 | | pageSize | Integer | 否 | 每页条数，默认10 | 10 | | projectName | String | 否 | 项目名称（模糊查询） | 办公设备采购 | | subjectName | String | 否 | 标的物名称（模糊查询） | 电脑 | | applicantName | String | 否 | 申请人姓名（模糊查询） | 张三 | | params[beginApplyDate] | String | 否 | 申请日期起始 | 2025-01-01 | | params[endApplyDate] | String | 否 | 申请日期结束 | 2025-12-31 | **响应示例**: ```json { "code": 200, "msg": "查询成功", "rows": [ { "purchaseId": "PO20250206001", "purchaseCategory": "货物类", "projectName": "办公设备采购项目", "subjectName": "笔记本电脑", "subjectDesc": "高性能办公笔记本", "purchaseQty": 50.00, "budgetAmount": 500000.00, "bidAmount": 450000.00, "actualAmount": 455000.00, "contractAmount": 450000.00, "settlementAmount": 455000.00, "purchaseMethod": "公开招标", "supplierName": "某某科技有限公司", "contactPerson": "李四", "contactPhone": "13800138000", "supplierUscc": "91110000MA000000XX", "supplierBankAccount": "1234567890123456789", "applyDate": "2025-01-01", "planApproveDate": "2025-01-05", "announceDate": "2025-01-10", "bidOpenDate": "2025-01-15", "contractSignDate": "2025-01-20", "expectedDeliveryDate": "2025-02-01", "actualDeliveryDate": "2025-02-01", "acceptanceDate": "2025-02-05", "settlementDate": "2025-02-10", "applicantId": "E001001", "applicantName": "张三", "applyDepartment": "信息技术部", "purchaseLeaderId": "E002001", "purchaseLeaderName": "王五", "purchaseDepartment": "采购部", "createTime": "2025-02-06 10:00:00", "updateTime": "2025-02-06 10:00:00", "createdBy": "admin", "updatedBy": "admin" } ], "total": 100 } ``` --- ### 2. 获取采购交易详情 **接口描述**: 根据采购事项ID获取详细信息 **请求方式**: `GET` **请求路径**: `/ccdi/purchaseTransaction/{purchaseId}` **权限要求**: `ccdi:purchaseTransaction:query` **路径参数**: | 参数名 | 类型 | 必填 | 说明 | 示例值 | |------------|--------|----|--------|---------------| | purchaseId | String | 是 | 采购事项ID | PO20250206001 | **响应示例**: ```json { "code": 200, "msg": "操作成功", "data": { "purchaseId": "PO20250206001", "purchaseCategory": "货物类", "projectName": "办公设备采购项目", "subjectName": "笔记本电脑", "subjectDesc": "高性能办公笔记本", "purchaseQty": 50.00, "budgetAmount": 500000.00, "bidAmount": 450000.00, "actualAmount": 455000.00, "contractAmount": 450000.00, "settlementAmount": 455000.00, "purchaseMethod": "公开招标", "supplierName": "某某科技有限公司", "contactPerson": "李四", "contactPhone": "13800138000", "supplierUscc": "91110000MA000000XX", "supplierBankAccount": "1234567890123456789", "applyDate": "2025-01-01", "planApproveDate": "2025-01-05", "announceDate": "2025-01-10", "bidOpenDate": "2025-01-15", "contractSignDate": "2025-01-20", "expectedDeliveryDate": "2025-02-01", "actualDeliveryDate": "2025-02-01", "acceptanceDate": "2025-02-05", "settlementDate": "2025-02-10", "applicantId": "E001001", "applicantName": "张三", "applyDepartment": "信息技术部", "purchaseLeaderId": "E002001", "purchaseLeaderName": "王五", "purchaseDepartment": "采购部", "createTime": "2025-02-06 10:00:00", "updateTime": "2025-02-06 10:00:00", "createdBy": "admin", "updatedBy": "admin" } } ``` --- ### 3. 新增采购交易 **接口描述**: 新增采购交易记录 **请求方式**: `POST` **请求路径**: `/ccdi/purchaseTransaction` **权限要求**: `ccdi:purchaseTransaction:add` **请求头**: ``` Content-Type: application/json Authorization: Bearer {token} ``` **请求体** (`CcdiPurchaseTransactionAddDTO`): | 参数名 | 类型 | 必填 | 说明 | 示例值 | |----------------------|------------|----|----------------------|---------------------| | purchaseId | String | 是 | 采购事项ID（最大32字符） | PO20250206001 | | purchaseCategory | String | 否 | 采购类别（最大50字符） | 货物类 | | projectName | String | 否 | 项目名称（最大200字符） | 办公设备采购项目 | | subjectName | String | 否 | 标的物名称（最大200字符） | 笔记本电脑 | | subjectDesc | String | 否 | 标的物描述（最大500字符） | 高性能办公笔记本 | | purchaseQty | BigDecimal | 否 | 采购数量 | 50.00 | | budgetAmount | BigDecimal | 否 | 预算金额 | 500000.00 | | bidAmount | BigDecimal | 否 | 中标金额 | 450000.00 | | actualAmount | BigDecimal | 否 | 实际采购金额 | 455000.00 | | contractAmount | BigDecimal | 否 | 合同金额 | 450000.00 | | settlementAmount | BigDecimal | 否 | 结算金额 | 455000.00 | | purchaseMethod | String | 否 | 采购方式（最大50字符） | 公开招标 | | supplierName | String | 否 | 供应商名称（最大200字符） | 某某科技有限公司 | | supplierUscc | String | 否 | 供应商统一信用代码（最大18字符） | 91110000MA000000XX | | contactPerson | String | 否 | 供应商联系人（最大50字符） | 李四 | | contactPhone | String | 否 | 供应商联系电话（最大20字符） | 13800138000 | | supplierBankAccount | String | 否 | 供应商银行账户（最大50字符） | 1234567890123456789 | | applyDate | String | 否 | 采购申请日期（yyyy-MM-dd） | 2025-01-01 | | planApproveDate | String | 否 | 采购计划批准日期（yyyy-MM-dd） | 2025-01-05 | | announceDate | String | 否 | 采购公告发布日期（yyyy-MM-dd） | 2025-01-10 | | bidOpenDate | String | 否 | 开标日期（yyyy-MM-dd） | 2025-01-15 | | contractSignDate | String | 否 | 合同签订日期（yyyy-MM-dd） | 2025-01-20 | | expectedDeliveryDate | String | 否 | 预计交货日期（yyyy-MM-dd） | 2025-02-01 | | actualDeliveryDate | String | 否 | 实际交货日期（yyyy-MM-dd） | 2025-02-01 | | acceptanceDate | String | 否 | 验收日期（yyyy-MM-dd） | 2025-02-05 | | settlementDate | String | 否 | 结算日期（yyyy-MM-dd） | 2025-02-10 | | applicantId | String | 否 | 申请人工号（最大20字符） | E001001 | | applicantName | String | 否 | 申请人姓名（最大50字符） | 张三 | | applyDepartment | String | 否 | 申请部门（最大100字符） | 信息技术部 | | purchaseLeaderId | String | 否 | 采购负责人工号（最大20字符） | E002001 | | purchaseLeaderName | String | 否 | 采购负责人姓名（最大50字符） | 王五 | | purchaseDepartment | String | 否 | 采购部门（最大100字符） | 采购部 | **请求示例**: ```json { "purchaseId": "PO20250206001", "purchaseCategory": "货物类", "projectName": "办公设备采购项目", "subjectName": "笔记本电脑", "subjectDesc": "高性能办公笔记本", "purchaseQty": 50.00, "budgetAmount": 500000.00, "bidAmount": 450000.00, "actualAmount": 455000.00, "contractAmount": 450000.00, "settlementAmount": 455000.00, "purchaseMethod": "公开招标", "supplierName": "某某科技有限公司", "supplierUscc": "91110000MA000000XX", "contactPerson": "李四", "contactPhone": "13800138000", "supplierBankAccount": "1234567890123456789", "applyDate": "2025-01-01", "planApproveDate": "2025-01-05", "announceDate": "2025-01-10", "bidOpenDate": "2025-01-15", "contractSignDate": "2025-01-20", "expectedDeliveryDate": "2025-02-01", "actualDeliveryDate": "2025-02-01", "acceptanceDate": "2025-02-05", "settlementDate": "2025-02-10", "applicantId": "E001001", "applicantName": "张三", "applyDepartment": "信息技术部", "purchaseLeaderId": "E002001", "purchaseLeaderName": "王五", "purchaseDepartment": "采购部" } ``` **响应示例**: ```json { "code": 200, "msg": "操作成功" } ``` --- ### 4. 修改采购交易 **接口描述**: 修改采购交易记录 **请求方式**: `PUT` **请求路径**: `/ccdi/purchaseTransaction` **权限要求**: `ccdi:purchaseTransaction:edit` **请求头**: ``` Content-Type: application/json Authorization: Bearer {token} ``` **请求体** (`CcdiPurchaseTransactionEditDTO`): 参数同新增接口，但purchaseId为必填且不可修改。 **响应示例**: ```json { "code": 200, "msg": "操作成功" } ``` --- ### 5. 删除采购交易 **接口描述**: 删除采购交易记录（支持批量删除） **请求方式**: `DELETE` **请求路径**: `/ccdi/purchaseTransaction/{purchaseIds}` **权限要求**: `ccdi:purchaseTransaction:remove` **路径参数**: | 参数名 | 类型 | 必填 | 说明 | 示例值 | |-------------|----------|----|------------------|-----------------------------| | purchaseIds | String[] | 是 | 采购事项ID数组，多个用逗号分隔 | PO20250206001,PO20250206002 | **请求示例**: ``` DELETE /ccdi/purchaseTransaction/PO20250206001,PO20250206002 ``` **响应示例**: ```json { "code": 200, "msg": "操作成功" } ``` --- ### 6. 导出采购交易 **接口描述**: 导出采购交易信息到Excel文件 **请求方式**: `POST` **请求路径**: `/ccdi/purchaseTransaction/export` **权限要求**: `ccdi:purchaseTransaction:export` **请求参数**: 同查询接口，支持条件导出 **响应**: Excel文件流 **请求示例**: ```bash curl -X POST "http://localhost:8080/ccdi/purchaseTransaction/export" \ -H "Authorization: Bearer {token}" \ -d "projectName=办公设备&applicantName=张三" ``` --- ### 7. 下载导入模板 **接口描述**: 下载带字典下拉框的Excel导入模板 **请求方式**: `POST` **请求路径**: `/ccdi/purchaseTransaction/importTemplate` **权限要求**: 无 **响应**: Excel模板文件流（包含数据验证下拉框） **请求示例**: ```bash curl -X POST "http://localhost:8080/ccdi/purchaseTransaction/importTemplate" \ -H "Authorization: Bearer {token}" \ -o purchase_transaction_template.xlsx ``` --- ### 8. 导入采购交易 **接口描述**: 异步导入Excel数据 **请求方式**: `POST` **请求路径**: `/ccdi/purchaseTransaction/importData?updateSupport={updateSupport}` **权限要求**: `ccdi:purchaseTransaction:import` **请求头**: ``` Content-Type: multipart/form-data Authorization: Bearer {token} ``` **路径参数**: | 参数名 | 类型 | 必填 | 说明 | 示例值 | |---------------|---------|----|-----------|------------| | updateSupport | boolean | 是 | 是否更新已存在数据 | true/false | **表单参数**: | 参数名 | 类型 | 必填 | 说明 | |------|------|----|---------------------| | file | File | 是 | Excel文件（.xlsx或.xls） | **响应示例**: ```json { "code": 200, "msg": "导入任务已提交，任务ID：task-20250206-123456789" } ``` --- ### 9. 查询导入状态 **接口描述**: 查询异步导入任务的执行状态 **请求方式**: `GET` **请求路径**: `/ccdi/purchaseTransaction/importStatus/{taskId}` **权限要求**: `ccdi:purchaseTransaction:import` **路径参数**: | 参数名 | 类型 | 必填 | 说明 | 示例值 | |--------|--------|----|------|-------------------------| | taskId | String | 是 | 任务ID | task-20250206-123456789 | **响应示例**: ```json { "code": 200, "msg": "操作成功", "data": { "taskId": "task-20250206-123456789", "status": "completed", "total": 1000, "successCount": 980, "failureCount": 20, "errorMsg": null } } ``` **状态说明**: - `pending`: 等待执行 - `running`: 正在执行 - `completed`: 执行完成 - `failed`: 执行失败 --- ### 10. 查询导入失败记录 **接口描述**: 查询导入任务中失败的记录详情 **请求方式**: `GET` **请求路径**: `/ccdi/purchaseTransaction/importFailures/{taskId}` **权限要求**: `ccdi:purchaseTransaction:import` **路径参数**: | 参数名 | 类型 | 必填 | 说明 | 示例值 | |--------|--------|----|------|-------------------------| | taskId | String | 是 | 任务ID | task-20250206-123456789 | **响应示例**: ```json { "code": 200, "msg": "操作成功", "data": [ { "purchaseId": "PO20250206001", "rowNum": 5, "errorMessage": "采购事项ID已存在" }, { "purchaseId": "PO20250206002", "rowNum": 12, "errorMessage": "预算金额格式错误" } ] } ``` --- ## 数据模型 ### CcdiPurchaseTransactionVO (查询返回对象) 采购交易信息的视图对象，用于列表查询和详情展示。 ### CcdiPurchaseTransactionAddDTO (新增请求对象) 新增采购交易时的请求参数对象。 ### CcdiPurchaseTransactionEditDTO (修改请求对象) 修改采购交易时的请求参数对象。 ### CcdiPurchaseTransactionQueryDTO (查询请求对象) 查询条件参数对象。 ### CcdiPurchaseTransactionExcel (导入导出对象) Excel导入导出使用的数据对象，支持字典下拉框。 ### ImportStatusVO (导入状态对象) 异步导入任务的状态信息。 | 字段 | 类型 | 说明 | |--------------|---------|-------------------------------------| | taskId | String | 任务ID | | status | String | 状态：pending/running/completed/failed | | total | Integer | 总记录数 | | successCount | Integer | 成功数量 | | failureCount | Integer | 失败数量 | | errorMsg | String | 错误信息（失败时） | ### PurchaseTransactionImportFailureVO (导入失败记录对象) 导入失败的记录详情。 | 字段 | 类型 | 说明 | |--------------|---------|--------| | purchaseId | String | 采购事项ID | | rowNum | Integer | 行号 | | errorMessage | String | 错误信息 | --- ## 错误码说明 ### HTTP状态码 | 状态码 | 说明 | |-----|----------------| | 200 | 请求成功 | | 401 | 未授权，token无效或过期 | | 403 | 无权限访问 | | 404 | 资源不存在 | | 500 | 服务器内部错误 | ### 业务错误码 | code | msg | 说明 | |------|-------|-------------| | 200 | 操作成功 | 请求成功处理 | | 500 | 操作失败 | 服务器处理失败 | | 401 | 请先登录 | 未登录或token过期 | | 403 | 无权限访问 | 权限不足 | --- ## 接口示例 ### 1. 完整的CRUD流程 ```bash # 1. 登录获取token TOKEN=$(curl -s -X POST "http://localhost:8080/login/test" \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"admin123"}' \ | jq -r '.token') # 2. 查询列表 curl -X GET "http://localhost:8080/ccdi/purchaseTransaction/list?pageNum=1&pageSize=10" \ -H "Authorization: Bearer $TOKEN" # 3. 新增记录 curl -X POST "http://localhost:8080/ccdi/purchaseTransaction" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "purchaseId": "PO20250206001", "projectName": "办公设备采购项目", "subjectName": "笔记本电脑", "budgetAmount": 500000.00 }' # 4. 获取详情 curl -X GET "http://localhost:8080/ccdi/purchaseTransaction/PO20250206001" \ -H "Authorization: Bearer $TOKEN" # 5. 修改记录 curl -X PUT "http://localhost:8080/ccdi/purchaseTransaction" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "purchaseId": "PO20250206001", "projectName": "办公设备采购项目（修改）", "subjectName": "笔记本电脑", "budgetAmount": 550000.00 }' # 6. 删除记录 curl -X DELETE "http://localhost:8080/ccdi/purchaseTransaction/PO20250206001" \ -H "Authorization: Bearer $TOKEN" ``` ### 2. 导入导出流程 ```bash # 1. 下载模板 curl -X POST "http://localhost:8080/ccdi/purchaseTransaction/importTemplate" \ -H "Authorization: Bearer $TOKEN" \ -o template.xlsx # 2. 填写数据后导入 curl -X POST "http://localhost:8080/ccdi/purchaseTransaction/importData?updateSupport=false" \ -H "Authorization: Bearer $TOKEN" \ -F "file=@data.xlsx" # 响应: {"code":200,"msg":"导入任务已提交，任务ID：task-xxx"} # 3. 查询导入状态 curl -X GET "http://localhost:8080/ccdi/purchaseTransaction/importStatus/task-xxx" \ -H "Authorization: Bearer $TOKEN" # 4. 如果有失败，查询失败记录 curl -X GET "http://localhost:8080/ccdi/purchaseTransaction/importFailures/task-xxx" \ -H "Authorization: Bearer $TOKEN" # 5. 导出数据 curl -X POST "http://localhost:8080/ccdi/purchaseTransaction/export" \ -H "Authorization: Bearer $TOKEN" \ -d "projectName=办公设备" \ -o export_data.xlsx ``` ### 3. Postman测试步骤 1. **创建环境变量**: - `base_url`: http://localhost:8080 - `token`: (登录后获取) 2. **创建Pre-request Script**: ```javascript // 自动设置token if (!pm.environment.get("token")) { const loginRequest = { url: pm.environment.get("base_url") + "/login/test", method: "POST", header: {"Content-Type": "application/json"}, body: { mode: "raw", raw: JSON.stringify({username: "admin", password: "admin123"}) } }; pm.sendRequest(loginRequest, (err, res) => { pm.environment.set("token", res.json().token); }); } ``` 3. **设置Authorization**: - Type: Bearer Token - Token: `{{token}}` 4. **执行测试**: - 按接口顺序执行 - 查看响应结果 - 验证数据正确性 --- ## 附录 ### A. 数据库表结构 表名: `ccdi_purchase_transaction` | 字段名 | 类型 | 说明 | 备注 | |------------------------|---------------|-----------|------| | purchase_id | varchar(32) | 采购事项ID | 主键 | | purchase_category | varchar(50) | 采购类别 | | | project_name | varchar(200) | 项目名称 | | | subject_name | varchar(200) | 标的物名称 | | | subject_desc | varchar(500) | 标的物描述 | | | purchase_qty | decimal(10,2) | 采购数量 | | | budget_amount | decimal(15,2) | 预算金额 | | | bid_amount | decimal(15,2) | 中标金额 | | | actual_amount | decimal(15,2) | 实际采购金额 | | | contract_amount | decimal(15,2) | 合同金额 | | | settlement_amount | decimal(15,2) | 结算金额 | | | purchase_method | varchar(50) | 采购方式 | | | supplier_name | varchar(200) | 中标供应商名称 | | | contact_person | varchar(50) | 供应商联系人 | | | contact_phone | varchar(20) | 供应商联系电话 | | | supplier_uscc | varchar(18) | 供应商统一信用代码 | | | supplier_bank_account | varchar(50) | 供应商银行账户 | | | apply_date | date | 采购申请日期 | | | plan_approve_date | date | 采购计划批准日期 | | | announce_date | date | 采购公告发布日期 | | | bid_open_date | date | 开标日期 | | | contract_sign_date | date | 合同签订日期 | | | expected_delivery_date | date | 预计交货日期 | | | actual_delivery_date | date | 实际交货日期 | | | acceptance_date | date | 验收日期 | | | settlement_date | date | 结算日期 | | | applicant_id | varchar(20) | 申请人工号 | | | applicant_name | varchar(50) | 申请人姓名 | | | apply_department | varchar(100) | 申请部门 | | | purchase_leader_id | varchar(20) | 采购负责人工号 | | | purchase_leader_name | varchar(50) | 采购负责人姓名 | | | purchase_department | varchar(100) | 采购部门 | | | create_time | datetime | 创建时间 | 自动填充 | | update_time | datetime | 更新时间 | 自动填充 | | created_by | varchar(64) | 创建人 | 自动填充 | | updated_by | varchar(64) | 更新人 | 自动填充 | ### B. 菜单权限配置 执行以下SQL配置菜单权限： ```sql -- 文件路径: sql/ccdi_purchase_transaction_menu.sql -- 执行此文件以配置菜单和权限 source sql/ccdi_purchase_transaction_menu.sql; ``` ### C. 前端API文件 前端API定义文件: `ruoyi-ui/src/api/ccdiPurchaseTransaction.js` --- ## 导入功能交互说明 ### 前端交互流程 1. **上传文件** - 用户点击"导入"按钮 - 选择Excel文件 - 点击"确定"上传 - **导入对话框立即关闭** 2. **后台处理** - 右上角显示通知:"导入任务已提交,正在后台处理中,处理完成后将通知您" - 系统每2秒轮询一次导入状态 3. **导入完成** - 全部成功:显示绿色通知"导入完成!全部成功!共导入N条数据" - 部分失败:显示橙色通知"导入完成!成功N条,失败M条" - 如果有失败记录,操作栏显示"查看导入失败记录"按钮 4. **查看失败记录** - 点击"查看导入失败记录"按钮 - 打开对话框显示分页的失败记录 - 包含字段:采购事项ID、项目名称、标的物名称、失败原因 - 支持清除历史记录 ### 状态持久化 - 导入状态保存在localStorage中 - 刷新页面后仍可查看上次导入结果 - 状态保留7天,过期自动清除 ### 与员工信息导入的对比 采购交易导入完全复用了员工信息导入的逻辑,两者的交互方式完全一致。 --- ## 版本历史 | 版本 | 日期 | 说明 | 作者 | |-------|------------|-----------------|-------| | 1.0.0 | 2026-02-06 | 初始版本，采购交易信息管理接口 | ruoyi | | 1.1.0 | 2026-02-08 | 添加导入功能交互说明 | ruoyi | --- ## 联系方式 如有问题，请联系开发团队。