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

# Supplier Service API Documentation

## Base URL
```
/api/suppliers
```

## 供应商管理

### 创建供应商
```
POST /api/suppliers
```

**Request Body:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "action": "approve",
  "comment": "审核通过"
}
```

**action:** approve/reject

---

## 联系人管理

### 创建联系人
```
POST /api/suppliers/{supplierId}/contacts
```

**Request Body:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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
```

---

## 响应格式

### 成功响应
```json
{
  "code": 200,
  "data": {...},
  "message": "success"
}
```

### 错误响应
```json
{
  "code": 400,
  "data": null,
  "message": "参数错误"
}
```

### 分页响应
```json
{
  "code": 200,
  "data": {
    "list": [...],
    "total": 100,
    "currentPage": 1,
    "lastPage": 5,
    "pageSize": 20
  },
  "message": "success"
}
```