21 lines
1.2 KiB
Markdown
21 lines
1.2 KiB
Markdown
# shared/api-contract Specification
|
||
|
||
## Purpose
|
||
定义服务机构端 C0 的统一响应契约与业务错误码，作为前后端接口交互的唯一约定。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 统一响应结构
|
||
所有接口 MUST 返回统一响应结构 `{code, message, data, hint}`；`code=0` 成功，非 0 失败；硬锁拒绝时 `hint` MUST 提供用户可读的「怎么解」提示。
|
||
|
||
#### Scenario: 硬锁拒绝带 hint
|
||
- **WHEN** 接口因硬锁拒绝（如无有效待遇）
|
||
- **THEN** 返回非 0 code 与可读 message，且 `hint` 说明「先做什么才能做」
|
||
|
||
### Requirement: 业务错误码
|
||
业务错误码 MUST 落地为 5 位码 [域码2][序3]，并覆盖：1001 无有效待遇、1002 无有效计划、1003 无有效工单、1004 留痕不完整、1005 未质控、1006 资质不匹配（提示级）、2001 时间冲突（硬拒）、2002 项数不满足（提示）、3001 必拍未拍（硬拒）、3002 定位失败（非错误）、3003 扑空登记、3004 垫付不计费、4001 越权或自审自放行。
|
||
|
||
#### Scenario: 资质不匹配提示级
|
||
- **WHEN** 派单时护理员资质不匹配
|
||
- **THEN** 返回 1006，前端仅提示、允许继续（本期不拦截，二期改硬拒）
|