样品申请与追踪 · 接口清单
说明:以下为接口契约草案,落地时统一走站点既有数据访问层,字段命名与数据库表保持一致。所有接口需带站点身份头,错误返回统一 { code, message }。
1. 样品任务
创建申请
POST /sample_task
{
"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
{ "unitPrice": 120, "leadTimeDays": 5, "shipDate": "2026-12-05", "remark": "string" }POST /sample_task/{id}/reject → { "reason": "string" }
状态推进
POST /sample_task/{id}/transition
{ "to": "in_production|shipped|received|passed|conditional|failed|rework|refunded|cancelled|closed", "note": "string" }约束:服务端按状态机校验,非法流转返回 SAMPLE_STATUS_INVALID。
验收
POST /sample_task/{id}/acceptance
{ "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
{
"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依赖对象存储;未开通时仅保存文件名与说明文本。 - 不提供支付、退款资金流转接口;退款状态由线下确认后在管理中登记。
- 不提供短信、邮件、推送接口;站内仅以列表标记与角标提示。

