docs(project): align product names and source directories
This commit is contained in:
QiuSW
+11
-11
@@ -1,6 +1,6 @@
|
||||
# API 合约
|
||||
|
||||
> 本文定义 web 端对外的 HTTP 接口，以及 desk 端本地模块的合约。
|
||||
> 本文定义采购服务（`admin/`）对外的 HTTP 接口，以及采购工具（`client/`）本地模块的合约。
|
||||
> **这是双端之间的唯一权威。** 实现前可细化，但不得在代码里另起一套不兼容接口。
|
||||
>
|
||||
> 本合约的设备心跳、任务领取、事件、证据、授权命令与 ack 结构参考了前序项目
|
||||
@@ -20,7 +20,7 @@
|
||||
| 客户端 | 方式 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 管理 Web | Session Cookie + CSRF Token | 表单提交必须带 CSRF |
|
||||
| desk 端 | `Authorization: Bearer <device_token>` | 凭据绑定设备标识，可单独撤销 |
|
||||
| 采购工具 | `Authorization: Bearer <device_token>` | 凭据绑定设备标识，可单独撤销 |
|
||||
| ERP 对接 | `Authorization: Bearer <connector_token>` | 只能调用货运同步接口 |
|
||||
|
||||
三种身份互不通用。设备凭据**不能**创建任务或签发授权；管理会话**不能**调用设备接口。
|
||||
@@ -79,7 +79,7 @@
|
||||
}
|
||||
```
|
||||
|
||||
- 只接受当前状态为 `DRAFT` 的任务；该动作含义是允许 desk 端领取第一趟试选，**不签发下单
|
||||
- 只接受当前状态为 `DRAFT` 的任务；该动作含义是允许采购工具领取第一趟试选，**不签发下单
|
||||
授权、不建立提交围栏、不创建订单、不付款**。
|
||||
- 服务端在一个事务内校验全部任务存在、属于当前管理范围、状态仍为 `DRAFT` 且版本匹配，
|
||||
然后统一转 `PENDING` 并递增版本。任一项失败返回 `409 conflict`，整批不产生部分成功。
|
||||
@@ -109,7 +109,7 @@
|
||||
转人工核查，不能重新开放为可执行。
|
||||
- MVP 没有「选择理由 / 拒绝理由」——那是多候选择一时的留档需求。这里只有可选 `note`。
|
||||
|
||||
## 二、设备侧接口（desk 端调用）
|
||||
## 二、设备侧接口（采购工具调用）
|
||||
|
||||
全部要求有效设备 Bearer；凭据中的设备标识是权威身份，请求体里的设备字段仅作核对。
|
||||
|
||||
@@ -192,7 +192,7 @@
|
||||
|
||||
### dry-run 与真实提交协议
|
||||
|
||||
`POST /api/v1/tasks/{id}/order-dry-runs/start` 创建或重放一次演练记录。desk 端随后只允许
|
||||
`POST /api/v1/tasks/{id}/order-dry-runs/start` 创建或重放一次演练记录。采购工具随后只允许
|
||||
进入订单确认页、读取非敏感摘要和验证提交控件唯一，不允许点击。完成后调用
|
||||
`POST /api/v1/order-dry-runs/{rid}/ready`：
|
||||
|
||||
@@ -210,7 +210,7 @@
|
||||
- dry-run 只证明当次页面达到 `READY`，不冻结授权，也不能作为稍后真实点击时的页面事实。
|
||||
- `has_address` 只报布尔值，**不得回传地址原文或手机号**。
|
||||
|
||||
真实第二趟重新通过三道闸门后，desk 端在点击前调用
|
||||
真实第二趟重新通过三道闸门后，采购工具在点击前调用
|
||||
`POST /api/v1/tasks/{id}/order-submissions/start`：
|
||||
|
||||
```json
|
||||
@@ -227,7 +227,7 @@
|
||||
|
||||
- 服务端在一个事务中校验命令、任务版本、授权未消费、闸门值与唯一性，创建或重放唯一
|
||||
`order_submission` 并把授权置为 `FENCED`。同一授权或命令不得产生第二条提交记录。
|
||||
- 只有明确收到 `201/200` 且响应中的 `click_permitted: true`，desk 端才允许点击一次。
|
||||
- 只有明确收到 `201/200` 且响应中的 `click_permitted: true`，采购工具才允许点击一次。
|
||||
超时、网络错误、冲突或响应无法解析时**不得点击**，转人工查询该幂等键。
|
||||
- `dry_run_id` 只证明曾完成安全演练；服务端仍以本次真实提交请求携带的闸门读数复核。
|
||||
|
||||
@@ -255,7 +255,7 @@
|
||||
- 拒绝含 `authorization:`、`api_key`、`bearer ` 的内容，防止凭据误入审计日志。
|
||||
- **超长必须由客户端截断后再发，服务端拒绝而不是静默截断。**
|
||||
|
||||
## 三、desk 端本地模块合约
|
||||
## 三、采购工具本地模块合约
|
||||
|
||||
### `TaskSource` / `ResultSink`
|
||||
|
||||
@@ -275,14 +275,14 @@ class ResultSink(ABC):
|
||||
|
||||
| 实现 | 用途 |
|
||||
| --- | --- |
|
||||
| `HttpTaskSource` | 从 web 端领取任务（默认） |
|
||||
| `HttpResultSink` | 回传结果到 web 端（默认） |
|
||||
| `HttpTaskSource` | 从采购服务领取任务（默认） |
|
||||
| `HttpResultSink` | 回传结果到采购服务（默认） |
|
||||
| `FixtureTaskSource` | 仅测试 / 演示：读取仓库内假数据，不接触真实订单 |
|
||||
| `JsonlResultSink` | 仅测试 / 断连暂存：本地追加写入，恢复连接后按幂等键补传 |
|
||||
|
||||
### 真机流程模块
|
||||
|
||||
`desk/src/android/pdd_flow.py` 的公开入口，每个都不得越界：
|
||||
`client/src/android/pdd_flow.py` 的公开入口，每个都不得越界：
|
||||
|
||||
| 函数 | 输入 | 输出 | 副作用边界 |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
Reference in New Issue
Block a user