erp-java/services/supplier-service/API_DOC.md

Supplier Service API Documentation

Base URL

/api/suppliers

供应商管理

创建供应商

POST /api/suppliers

Request Body:

{
  "supplierName": "深圳华强电子有限公司",
  "supplierType": "manufacturer",
  "industry": "电子元器件",
  "businessLicense": "91440300MA5XXXXX",
  "registeredCapital": 10000000,
  "legalPerson": "张三",
  "phone": "0755-12345678",
  "email": "hq@example.com",
  "province": "广东省",
  "city": "深圳市",
  "district": "福田区",
  "address": "华强北路100号",
  "mainBusiness": "电子元器件生产销售",
  "settlementMethod": "monthly",
  "paymentDays": 30,
  "minimumOrderQuantity": 1000,
  "remark": "优质供应商"
}

Response:

{
  "code": 200,
  "data": {
    "id": 1,
    "supplierCode": "S20260401ABC123",
    "supplierName": "深圳华强电子有限公司",
    "supplierType": "manufacturer",
    "status": "pending",
    "grade": "C",
    "creditScore": 60,
    "auditStatus": "pending",
    "createdAt": "2026-04-01 12:00:00"
  },
  "message": "供应商创建成功"
}

查询供应商列表

GET /api/suppliers?page=1&limit=20&status=active&grade=A

Query Parameters:

参数	类型	必填	说明
page	int	否	页码，默认1
limit	int	否	每页数量，默认20
status	string	否	状态: pending/active/inactive/blacklist
grade	string	否	等级: A/B/C/D
supplierType	string	否	类型: manufacturer/trader/agent/individual
industry	string	否	行业
keyword	string	否	关键词(名称/编码)
startDate	string	否	开始日期
endDate	string	否	结束日期

获取供应商详情

GET /api/suppliers/{id}

更新供应商

PUT /api/suppliers/{id}

删除供应商

DELETE /api/suppliers/{id}

审核供应商

POST /api/suppliers/{id}/audit

Request Body:

{
  "action": "approve",
  "comment": "审核通过"
}

action: approve/reject

---

联系人管理

创建联系人

POST /api/suppliers/{supplierId}/contacts

Request Body:

{
  "contactName": "张三",
  "gender": "male",
  "department": "采购部",
  "position": "采购经理",
  "mobile": "13800138001",
  "email": "zhangsan@example.com",
  "qq": "123456",
  "wechat": "zhangsan123",
  "isPrimary": 1,
  "isEmergency": 0,
  "remark": "主要联系人"
}

查询联系人列表

GET /api/suppliers/{supplierId}/contacts

更新联系人

PUT /api/suppliers/{supplierId}/contacts/{contactId}

删除联系人

DELETE /api/suppliers/{supplierId}/contacts/{contactId}

---

银行账户管理

创建银行账户

POST /api/suppliers/{supplierId}/bank-accounts

Request Body:

{
  "accountName": "深圳华强电子有限公司",
  "bankName": "中国工商银行深圳分行",
  "bankAccount": "400012345678901234",
  "branchName": "深圳福田支行",
  "branchCode": "102584001234",
  "province": "广东省",
  "city": "深圳市",
  "accountType": "basic",
  "isDefault": 1,
  "reservedPhone": "13800138000",
  "remark": "基本户"
}

查询银行账户列表

GET /api/suppliers/{supplierId}/bank-accounts

更新银行账户

PUT /api/suppliers/{supplierId}/bank-accounts/{accountId}

删除银行账户

DELETE /api/suppliers/{supplierId}/bank-accounts/{accountId}

设置默认账户

PUT /api/suppliers/{supplierId}/bank-accounts/{accountId}/default

---

供应商评级

创建评级

POST /api/suppliers/ratings

Request Body:

{
  "supplierId": 1,
  "ratingPeriod": "monthly",
  "ratingYear": 2026,
  "ratingMonth": 4,
  "qualityScore": 95.00,
  "deliveryScore": 92.00,
  "priceScore": 88.00,
  "serviceScore": 90.00,
  "strengths": "质量稳定，交期准时",
  "weaknesses": "价格略高",
  "suggestions": "建议优化价格",
  "remark": "月度评估"
}

评分权重:

• 质量: 30%
• 交期: 25%
• 价格: 25%
• 服务: 20%

查询评级列表

GET /api/suppliers/ratings?page=1&limit=20&supplierId=1&grade=A

获取评级详情

GET /api/suppliers/ratings/{id}

获取供应商最新评级

GET /api/suppliers/{supplierId}/ratings/latest

---

采购询价

创建询价单

POST /api/suppliers/inquiries

Request Body:

{
  "supplierId": 1,
  "inquiryType": "product",
  "productId": 100,
  "productName": "贴片电容",
  "productSpec": "100nF/50V",
  "unit": "个",
  "quantity": 10000,
  "expectedDeliveryDate": "2026-04-15",
  "quoteDeadline": "2026-04-10",
  "qualityStandard": "GB/T 1234",
  "paymentTerms": "月结30天",
  "remark": "急需"
}

查询询价单列表

GET /api/suppliers/inquiries?page=1&limit=20&supplierId=1&inquiryStatus=sent

状态: draft/sent/replied/compared/confirmed/cancelled

获取询价单详情

GET /api/suppliers/inquiries/{id}

更新询价单

PUT /api/suppliers/inquiries/{id}

发送询价单

POST /api/suppliers/inquiries/{id}/send

供应商报价

POST /api/suppliers/inquiries/{id}/reply?quotedPrice=0.05&quoteValidUntil=2026-04-30&deliveryCycle=7

确认询价单

POST /api/suppliers/inquiries/{id}/confirm?selectionReason=价格合理，选择该供应商

取消询价单

POST /api/suppliers/inquiries/{id}/cancel

---

统计分析

获取供应商统计

GET /api/suppliers/statistics

Response:

{
  "code": 200,
  "data": {
    "totalSuppliers": 100,
    "activeSuppliers": 80,
    "pendingSuppliers": 15,
    "gradeDistribution": {
      "A": 20,
      "B": 35,
      "C": 30,
      "D": 15
    },
    "typeDistribution": {
      "manufacturer": 40,
      "trader": 35,
      "agent": 20,
      "individual": 5
    },
    "topGradeSuppliers": [...],
    "recentCooperationSuppliers": [...]
  }
}

---

选项接口

获取状态选项

GET /api/suppliers/options/status

获取等级选项

GET /api/suppliers/options/grade

获取类型选项

GET /api/suppliers/options/type

---

响应格式

成功响应

{
  "code": 200,
  "data": {...},
  "message": "success"
}

错误响应

{
  "code": 400,
  "data": null,
  "message": "参数错误"
}

分页响应

{
  "code": 200,
  "data": {
    "list": [...],
    "total": 100,
    "currentPage": 1,
    "lastPage": 5,
    "pageSize": 20
  },
  "message": "success"
}