wkc/ccdi

Files

wkc 22514b6509 docs: 更新API文档,添加导入交互说明

- 详细的前端交互流程
- 状态持久化说明
- 与员工信息导入的对比

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-08 14:04:25 +08:00

23 KiB

Raw Blame History

采购交易信息管理 - API接口文档

文档信息

模块名称: 采购交易信息管理
Controller: CcdiPurchaseTransactionController
Base Path: /ccdi/purchaseTransaction
Swagger: http://localhost:8080/swagger-ui/index.html
生成时间: 2026-02-06

接口列表

序号	接口名称	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

响应示例:

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

响应示例:

{
  "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字符）	采购部

请求示例:

{
  "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": "采购部"
}

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

4. 修改采购交易

接口描述: 修改采购交易记录

请求方式: PUT

请求路径: /ccdi/purchaseTransaction

权限要求: ccdi:purchaseTransaction:edit

请求头:

Content-Type: application/json
Authorization: Bearer {token}

请求体 (CcdiPurchaseTransactionEditDTO):

参数同新增接口，但purchaseId为必填且不可修改。

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

5. 删除采购交易

接口描述: 删除采购交易记录（支持批量删除）

请求方式: DELETE

请求路径: /ccdi/purchaseTransaction/{purchaseIds}

权限要求: ccdi:purchaseTransaction:remove

路径参数:

参数名	类型	必填	说明	示例值
purchaseIds	String[]	是	采购事项ID数组，多个用逗号分隔	PO20250206001,PO20250206002

请求示例:

DELETE /ccdi/purchaseTransaction/PO20250206001,PO20250206002

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

6. 导出采购交易

接口描述: 导出采购交易信息到Excel文件

请求方式: POST

请求路径: /ccdi/purchaseTransaction/export

权限要求: ccdi:purchaseTransaction:export

请求参数: 同查询接口，支持条件导出

响应: Excel文件流

请求示例:

curl -X POST "http://localhost:8080/ccdi/purchaseTransaction/export" \
  -H "Authorization: Bearer {token}" \
  -d "projectName=办公设备&applicantName=张三"

7. 下载导入模板

接口描述: 下载带字典下拉框的Excel导入模板

请求方式: POST

请求路径: /ccdi/purchaseTransaction/importTemplate

权限要求: 无

响应: Excel模板文件流（包含数据验证下拉框）

请求示例:

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）

响应示例:

{
  "code": 200,
  "msg": "导入任务已提交，任务ID：task-20250206-123456789"
}

9. 查询导入状态

接口描述: 查询异步导入任务的执行状态

请求方式: GET

请求路径: /ccdi/purchaseTransaction/importStatus/{taskId}

权限要求: ccdi:purchaseTransaction:import

路径参数:

参数名	类型	必填	说明	示例值
taskId	String	是	任务ID	task-20250206-123456789

响应示例:

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

响应示例:

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

# 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. 导入导出流程

# 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测试步骤

创建环境变量:
- base_url: http://localhost:8080
- token: (登录后获取)
创建Pre-request Script:

// 自动设置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);
  });
}

设置Authorization:
- Type: Bearer Token
- Token: {{token}}
执行测试:
- 按接口顺序执行
- 查看响应结果
- 验证数据正确性

附录

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/ccdi_purchase_transaction_menu.sql
-- 执行此文件以配置菜单和权限
source sql/ccdi_purchase_transaction_menu.sql;

C. 前端API文件

前端API定义文件: ruoyi-ui/src/api/ccdiPurchaseTransaction.js

导入功能交互说明

前端交互流程

上传文件
- 用户点击"导入"按钮
- 选择Excel文件
- 点击"确定"上传
- 导入对话框立即关闭
后台处理
- 右上角显示通知:"导入任务已提交,正在后台处理中,处理完成后将通知您"
- 系统每2秒轮询一次导入状态
导入完成
- 全部成功:显示绿色通知"导入完成!全部成功!共导入N条数据"
- 部分失败:显示橙色通知"导入完成!成功N条,失败M条"
- 如果有失败记录,操作栏显示"查看导入失败记录"按钮
查看失败记录
- 点击"查看导入失败记录"按钮
- 打开对话框显示分页的失败记录
- 包含字段:采购事项ID、项目名称、标的物名称、失败原因
- 支持清除历史记录

状态持久化

导入状态保存在localStorage中
刷新页面后仍可查看上次导入结果
状态保留7天,过期自动清除

与员工信息导入的对比

采购交易导入完全复用了员工信息导入的逻辑,两者的交互方式完全一致。

版本历史

版本	日期	说明	作者
1.0.0	2026-02-06	初始版本，采购交易信息管理接口	ruoyi
1.1.0	2026-02-08	添加导入功能交互说明	ruoyi

联系方式

如有问题，请联系开发团队。

23 KiB Raw Blame History Unescape Escape

采购交易信息管理 - API接口文档

文档信息

目录

接口列表

接口详情

1. 查询采购交易列表

2. 获取采购交易详情

3. 新增采购交易

4. 修改采购交易

5. 删除采购交易

6. 导出采购交易

7. 下载导入模板

8. 导入采购交易

9. 查询导入状态

10. 查询导入失败记录

数据模型

CcdiPurchaseTransactionVO (查询返回对象)

CcdiPurchaseTransactionAddDTO (新增请求对象)

CcdiPurchaseTransactionEditDTO (修改请求对象)

CcdiPurchaseTransactionQueryDTO (查询请求对象)

CcdiPurchaseTransactionExcel (导入导出对象)

ImportStatusVO (导入状态对象)

PurchaseTransactionImportFailureVO (导入失败记录对象)

错误码说明

HTTP状态码

业务错误码

接口示例

1. 完整的CRUD流程

2. 导入导出流程

3. Postman测试步骤

附录

A. 数据库表结构

B. 菜单权限配置

C. 前端API文件

导入功能交互说明

前端交互流程

状态持久化

与员工信息导入的对比

版本历史

联系方式

23 KiB

Raw Blame History