forked from erp-dev/erp
225 lines
6.7 KiB
Markdown
225 lines
6.7 KiB
Markdown
# API v1 Customer Address API
|
||
|
||
## Scope
|
||
|
||
客户地址 API 用于维护客户的一对多地址资料。地址归属 `basic_info.Customer`，并通过 `merchant` 做商户隔离。
|
||
|
||
所有接口需要登录。普通员工只能访问自己可见客户的地址；拥有 `basic_info.view_all_customers` 权限的员工可以访问本商户全部客户地址；superuser 可以访问全部数据。
|
||
|
||
## Data Model
|
||
|
||
| Field | Type | Description |
|
||
| --- | --- | --- |
|
||
| `id` | integer | 客户地址 ID |
|
||
| `merchant` | integer | 所属商户 ID，创建时由后端根据客户自动写入 |
|
||
| `merchant_name` | string | 所属商户名称，只读 |
|
||
| `customer` | integer | 客户 ID |
|
||
| `customer_name` | string | 客户名称，只读 |
|
||
| `address` | string | 地址 |
|
||
| `contact_name` | string | 联系人，可为空字符串 |
|
||
| `contact_phone` | string | 联系电话，可为空字符串 |
|
||
| `area` | string | 地区，可为空字符串 |
|
||
| `coordinates` | string/null | 经纬度字符串，格式由调用方决定 |
|
||
| `is_default` | boolean | 是否默认地址 |
|
||
| `remark` | string | 备注，可为空字符串 |
|
||
| `extra` | object/null | 扩展 JSON |
|
||
| `created_by` | integer/null | 创建员工 ID，只读 |
|
||
| `created_by_name` | string/null | 创建员工姓名，只读 |
|
||
| `deleted_at` | datetime/null | 软删除时间，只读 |
|
||
| `deleted_by` | integer/null | 删除员工 ID，只读 |
|
||
| `deleted_by_name` | string/null | 删除员工姓名，只读 |
|
||
| `created_at` | datetime | 创建时间，只读 |
|
||
| `updated_at` | datetime | 更新时间，只读 |
|
||
|
||
## Endpoints
|
||
|
||
| Method | Path | Description |
|
||
| --- | --- | --- |
|
||
| GET | `/api/v1/customer-addresses/` | 查询客户地址列表 |
|
||
| POST | `/api/v1/customer-addresses/` | 创建客户地址 |
|
||
| GET | `/api/v1/customer-addresses/{id}/` | 查询客户地址详情 |
|
||
| PUT | `/api/v1/customer-addresses/{id}/` | 完整更新客户地址 |
|
||
| PATCH | `/api/v1/customer-addresses/{id}/` | 部分更新客户地址 |
|
||
| DELETE | `/api/v1/customer-addresses/{id}/` | 软删除客户地址 |
|
||
| POST | `/api/v1/customer-address/{id}/set-default/` | 将客户地址设为默认地址 |
|
||
|
||
## Visibility Rules
|
||
|
||
普通员工可访问的客户地址必须同时满足：
|
||
|
||
- 地址所属商户等于当前员工商户。
|
||
- 地址所属客户对当前员工可见。
|
||
|
||
客户可见性规则：
|
||
|
||
- `customer.created_by == 当前员工`
|
||
- 或当前员工在 `customer.visible_employees` 中。
|
||
|
||
权限例外：
|
||
|
||
- `basic_info.view_all_customers`：可访问本商户全部客户地址。
|
||
- superuser：可访问全部客户地址。
|
||
|
||
创建地址时，`customer` 也必须在当前用户可访问范围内。`merchant` 不由前端传入，后端使用客户所属商户自动写入。
|
||
|
||
## Query Parameters
|
||
|
||
`GET /api/v1/customer-addresses/` 支持以下查询参数：
|
||
|
||
| Parameter | Description |
|
||
| --- | --- |
|
||
| `customer` | 按客户 ID 精确过滤 |
|
||
| `customer_name` | 按客户名称模糊过滤 |
|
||
| `address` | 按地址模糊过滤 |
|
||
| `contact_name` | 按联系人模糊过滤 |
|
||
| `contact_phone` | 按联系电话模糊过滤 |
|
||
| `area` | 按地区模糊过滤 |
|
||
| `is_default` | 按默认地址过滤，支持 `true/false/1/0/yes/no` |
|
||
| `include_deleted` | 是否包含软删除记录，支持 `true/false/1/0/yes/no` |
|
||
| `only_deleted` | 是否只查询软删除记录，支持 `true/false/1/0/yes/no` |
|
||
| `search` | 对客户名称、地址、联系人、电话、地区、备注做模糊搜索 |
|
||
| `ordering` | 排序字段，支持 `id`、`created_at`、`updated_at`、`is_default` 及其 `-` 倒序形式 |
|
||
| `limit` | 分页数量 |
|
||
| `offset` | 分页偏移 |
|
||
|
||
默认行为：
|
||
|
||
- 不传 `include_deleted` 和 `only_deleted` 时，只返回未删除地址。
|
||
- `only_deleted=true` 优先于 `include_deleted=true`。
|
||
|
||
## Create
|
||
|
||
`POST /api/v1/customer-addresses/`
|
||
|
||
Request body:
|
||
|
||
```json
|
||
{
|
||
"customer": 3,
|
||
"address": "杭州市测试路 1 号",
|
||
"contact_name": "张三",
|
||
"contact_phone": "13800138000",
|
||
"area": "杭州",
|
||
"coordinates": "120.1,30.2",
|
||
"is_default": true,
|
||
"remark": "默认收货地址",
|
||
"extra": {
|
||
"source": "manual"
|
||
}
|
||
}
|
||
```
|
||
|
||
Success response: HTTP 201
|
||
|
||
```json
|
||
{
|
||
"id": 10,
|
||
"merchant": 1,
|
||
"merchant_name": "测试印花厂",
|
||
"customer": 3,
|
||
"customer_name": "客户A",
|
||
"address": "杭州市测试路 1 号",
|
||
"contact_name": "张三",
|
||
"contact_phone": "13800138000",
|
||
"area": "杭州",
|
||
"coordinates": "120.1,30.2",
|
||
"is_default": true,
|
||
"remark": "默认收货地址",
|
||
"extra": {
|
||
"source": "manual"
|
||
},
|
||
"created_by": 5,
|
||
"created_by_name": "业务员A",
|
||
"deleted_at": null,
|
||
"deleted_by": null,
|
||
"deleted_by_name": null,
|
||
"created_at": "2026-07-07T12:00:00Z",
|
||
"updated_at": "2026-07-07T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
## Update
|
||
|
||
`PATCH /api/v1/customer-addresses/{id}/`
|
||
|
||
Example:
|
||
|
||
```json
|
||
{
|
||
"address": "杭州市更新路 2 号",
|
||
"contact_phone": "13900139000",
|
||
"coordinates": null
|
||
}
|
||
```
|
||
|
||
Notes:
|
||
|
||
- 不允许修改 `customer`。
|
||
- 不允许修改 `merchant`。
|
||
- `created_by`、`deleted_at`、`deleted_by` 为只读字段。
|
||
|
||
## Default Address
|
||
|
||
同一客户最多一个未删除默认地址。
|
||
|
||
以下操作会自动取消同一客户其他未删除地址的默认状态：
|
||
|
||
- 创建地址时传 `is_default=true`。
|
||
- 更新地址时传 `is_default=true`。
|
||
- 调用 `set-default` 接口。
|
||
|
||
`POST /api/v1/customer-address/{id}/set-default/`
|
||
|
||
Success response: HTTP 200，返回更新后的地址对象。
|
||
|
||
如果地址已经软删除，返回 HTTP 400。
|
||
|
||
## Soft Delete
|
||
|
||
`DELETE /api/v1/customer-addresses/{id}/`
|
||
|
||
删除是软删除，不会物理删除记录。后端会写入：
|
||
|
||
- `deleted_at`
|
||
- `deleted_by`
|
||
- `is_default=false`
|
||
|
||
Success response: HTTP 204。
|
||
|
||
查询软删除记录：
|
||
|
||
```http
|
||
GET /api/v1/customer-addresses/?include_deleted=true
|
||
GET /api/v1/customer-addresses/?only_deleted=true
|
||
```
|
||
|
||
## Error Cases
|
||
|
||
| Condition | Status | Notes |
|
||
| --- | --- | --- |
|
||
| 未登录 | 401 | 全部接口需要登录 |
|
||
| 查询不可见地址详情 | 404 | 不暴露不可见数据存在性 |
|
||
| 给不可见客户创建地址 | 400 | `customer` 字段校验失败 |
|
||
| 修改 `customer` | 400 | 不允许地址跨客户移动 |
|
||
| 已删除地址设为默认 | 400 | 通过 `set-default` 接口返回校验错误 |
|
||
|
||
## Test Coverage
|
||
|
||
Dedicated tests:
|
||
|
||
```bash
|
||
docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web uv run python manage.py test api_v1.test_customer_address_api --keepdb --noinput
|
||
```
|
||
|
||
Covered behavior:
|
||
|
||
- 商户隔离和客户可见性。
|
||
- `visible_employees` 授权后可见。
|
||
- `basic_info.view_all_customers` 可访问本商户全部客户地址。
|
||
- 创建地址时自动写入 `merchant` 和 `created_by`。
|
||
- 不可见客户创建地址失败。
|
||
- 默认地址互斥。
|
||
- `set-default` 接口互斥设置默认地址。
|
||
- 软删除和 `include_deleted` / `only_deleted` 查询。
|
||
- 常用过滤参数。
|