erpnew/docs/api_v1_customer_address_api_2026-07-07.md

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:

{
  "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

{
  "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:

{
  "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。

查询软删除记录：

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:

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 查询。
• 常用过滤参数。