# 样品申请与追踪 · 接口清单

说明：以下为接口契约草案，落地时统一走站点既有数据访问层，字段命名与数据库表保持一致。所有接口需带站点身份头，错误返回统一 `{ code, message }`。

## 1. 样品任务

### 创建申请
`POST /sample_task`
```json
{
  "productId": "string|null",
  "supplierId": "string",
  "layers": 4,
  "material": "FR-4",
  "boardThickness": 1.6,
  "copperWeight": 1,
  "size": "100x100",
  "quantity": 10,
  "surfaceFinish": "HASL",
  "impedance": "50±10%",
  "expectedDate": "2026-12-01",
  "receiver": { "name": "string", "phone": "string", "address": "string" },
  "remark": "string"
}
```
返回：`{ id, status: "submitted", quota: { total, used, remain } }`
校验：数量 1–200；板层 1–32；供应商必须处于可接单状态；配额不足返回 `SAMPLE_QUOTA_EXCEEDED`。

### 查询列表
`GET /sample_task?role=buyer|supplier&status=&keyword=&page=1&pageSize=20`
返回：`{ list: SampleTask[], total }`

### 查询详情
`GET /sample_task/{id}` → `{ task, logs, defects, quota }`

### 供应商响应
`POST /sample_task/{id}/accept`
```json
{ "unitPrice": 120, "leadTimeDays": 5, "shipDate": "2026-12-05", "remark": "string" }
```
`POST /sample_task/{id}/reject` → `{ "reason": "string" }`

### 状态推进
`POST /sample_task/{id}/transition`
```json
{ "to": "in_production|shipped|received|passed|conditional|failed|rework|refunded|cancelled|closed", "note": "string" }
```
约束：服务端按状态机校验，非法流转返回 `SAMPLE_STATUS_INVALID`。

### 验收
`POST /sample_task/{id}/acceptance`
```json
{ "result": "passed|conditional|failed", "note": "string" }
```
`failed` 时必须已存在至少一条瑕疵记录，否则返回 `SAMPLE_DEFECT_REQUIRED`。

## 2. 流程日志
`GET /sample_flow_log?taskId=`
`POST /sample_flow_log` → `{ taskId, node, role, operator, note, attachmentUrl }`
约束：日志只追加，不提供更新与删除接口。

## 3. 样品配额
`GET /sample_quota?supplierId=` → `{ total, used, frozen, remain, resetAt }`
`POST /sample_quota/adjust` → `{ supplierId, delta, reason }`（仅运营，走管理后台 CRUD）

## 4. 瑕疵记录
`POST /sample_defect`
```json
{
  "taskId": "string",
  "defectType": "开短路|孔壁|阻焊|字符|板翘|尺寸|其他",
  "location": "string",
  "severity": "low|medium|high",
  "imageUrls": ["string"],
  "expectation": "rework|refund|discuss",
  "description": "string"
}
```
`GET /sample_defect?taskId=`
`POST /sample_defect/{id}/response` → `{ "action": "rework|refund|discuss", "note": "string" }`

## 5. 错误码

| 码 | 场景 |
| --- | --- |
| SAMPLE_QUOTA_EXCEEDED | 当周配额不足 |
| SAMPLE_STATUS_INVALID | 非法状态流转 |
| SAMPLE_DEFECT_REQUIRED | 验收不通过但缺少瑕疵记录 |
| SAMPLE_SUPPLIER_CLOSED | 供应商暂停接单 |
| SAMPLE_TASK_LOCKED | 任务已关闭，禁止修改 |
| SAMPLE_FORBIDDEN | 非任务关联方操作 |

## 6. 边界说明

- 附件字段 `attachmentUrl` / `imageUrls` 依赖对象存储；未开通时仅保存文件名与说明文本。
- 不提供支付、退款资金流转接口；退款状态由线下确认后在管理中登记。
- 不提供短信、邮件、推送接口；站内仅以列表标记与角标提示。