forked from erp-dev/erp
106 lines
2.2 KiB
Markdown
106 lines
2.2 KiB
Markdown
# 客户员工绑定 API
|
||
|
||
## 接口说明
|
||
|
||
将指定员工添加到指定客户的可见员工列表中（`Customer.visible_employees`）。
|
||
|
||
## 接口信息
|
||
|
||
- **URL**: `/api/v2/customers/bind-employee/`
|
||
- **方法**: `POST`
|
||
- **认证**: 需要登录（Bearer Token）
|
||
|
||
## 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| customer_name | string | 是 | 客户名称 |
|
||
| employee_name | string | 是 | 员工姓名 |
|
||
|
||
## 请求示例
|
||
|
||
```bash
|
||
curl -X POST "http://your-domain/api/v2/customers/bind-employee/" \
|
||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"customer_name": "张三服装厂",
|
||
"employee_name": "李四"
|
||
}'
|
||
```
|
||
|
||
## 响应说明
|
||
|
||
### 成功响应（201 Created）
|
||
|
||
```json
|
||
{
|
||
"message": "成功将员工 \"李四\" 添加到客户 \"张三服装厂\" 的可见列表",
|
||
"customer_id": 123,
|
||
"customer_name": "张三服装厂",
|
||
"employee_id": 456,
|
||
"employee_name": "李四"
|
||
}
|
||
```
|
||
|
||
### 已存在响应（200 OK）
|
||
|
||
如果该员工已经在客户的可见列表中：
|
||
|
||
```json
|
||
{
|
||
"message": "员工 \"李四\" 已在客户 \"张三服装厂\" 的可见列表中",
|
||
"customer_id": 123,
|
||
"employee_id": 456
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
#### 未找到数据（400 Bad Request）
|
||
|
||
```json
|
||
{
|
||
"error": "未找到名为 \"李四\" 的员工"
|
||
}
|
||
```
|
||
|
||
或
|
||
|
||
```json
|
||
{
|
||
"error": "未找到名为 \"张三服装厂\" 的客户"
|
||
}
|
||
```
|
||
|
||
#### 找到多条数据（403 Forbidden）
|
||
|
||
```json
|
||
{
|
||
"error": "找到多个名为 \"李四\" 的员工（3 个），请使用更精确的标识"
|
||
}
|
||
```
|
||
|
||
或
|
||
|
||
```json
|
||
{
|
||
"error": "找到多个名为 \"张三服装厂\" 的客户（2 个），请使用更精确的标识"
|
||
}
|
||
```
|
||
|
||
#### 参数验证失败（400 Bad Request）
|
||
|
||
```json
|
||
{
|
||
"customer_name": ["该字段是必填项。"],
|
||
"employee_name": ["该字段是必填项。"]
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 该操作是**幂等的**：重复绑定同一对客户和员工不会报错，会返回 200 状态码
|
||
2. 如果客户或员工名称不唯一，系统会返回 403 错误，建议在数据库中确保名称唯一性
|
||
3. 绑定关系为多对多，一个客户可以有多个可见员工，一个员工也可以被多个客户可见
|