Files
ccdi/doc/api/ccdi_purchase_transaction_api.md

753 lines
22 KiB
Markdown
Raw Normal View History

# 采购交易信息管理 - 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": "导入任务已提交任务IDtask-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":"导入任务已提交任务IDtask-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.0.0 | 2026-02-06 | 初始版本,采购交易信息管理接口 | ruoyi |
---
## 联系方式
如有问题,请联系开发团队。