# 渠道修改租户密码接口文档

## 1. 接口概述

本接口用于渠道管理员为其管理的租户重置登录密码。支持渠道管理员、计费管理员和超级管理员角色调用。

---

## 2. 接口信息

| 属性 | 值 |
|------|-----|
| **接口路径** | `/api/channel/tenants/{tenant_id}/password` |
| **请求方式** | `PUT` |
| **权限要求** | `manage:tenants` |
| **支持角色** | `channel_admin`、`billing_admin`、`super_admin` |
| **Content-Type** | `application/json` |

---

## 3. 请求参数

### 3.1 路径参数 (Path Parameters)

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `tenant_id` | string (UUID) | 是 | 租户ID |

### 3.2 查询参数 (Query Parameters)

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `channel_id` | string (UUID) | 超级管理员必填 | 渠道ID。超级管理员必须提供此参数，渠道管理员自动使用所属渠道 |

### 3.3 请求头 (Headers)

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `Authorization` | string | 是 | Bearer Token，格式：`Bearer {access_token}` |
| `Content-Type` | string | 是 | `application/json` |

### 3.4 请求体 (Request Body)

| 参数名 | 类型 | 必填 | 说明 | 约束 |
|--------|------|------|------|------|
| `newPassword` | string | 是 | 新密码 | 最少8位字符 |

**请求体示例：**

```json
{
  "newPassword": "NewSecurePass123"
}
```

---

## 4. 响应参数

### 4.1 成功响应

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功，成功时为 `true` |
| `data` | object | 响应数据对象 |
| `data.tenantId` | string | 被修改密码的租户ID |
| `data.name` | string | 租户名称 |
| `message` | string | 操作结果消息 |

**成功响应示例：**

```json
{
  "success": true,
  "data": {
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "示例租户"
  },
  "message": "租户密码已重置"
}
```

### 4.2 错误响应

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功，失败时为 `false` |
| `detail` | string | 错误详情描述 |

**错误响应示例：**

```json
{
  "detail": "租户不存在或不属于该渠道"
}
```

---

## 5. 错误码说明

| HTTP状态码 | 错误描述 | 说明 |
|------------|----------|------|
| `200` | 成功 | 密码重置成功 |
| `400` | Bad Request | 请求参数错误，可能原因：超级管理员未提供 channel_id、无效的渠道ID格式、密码长度不足8位 |
| `401` | Unauthorized | 未授权，Token无效或已过期 |
| `403` | Forbidden | 权限不足，无 manage:tenants 权限 |
| `404` | Not Found | 租户不存在或不属于该渠道 |
| `422` | Unprocessable Entity | 请求体格式错误或字段验证失败 |

---

## 6. 调用示例

### 6.1 渠道管理员调用示例

**请求：**

```http
PUT /api/channel/tenants/550e8400-e29b-41d4-a716-446655440000/password HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "newPassword": "NewSecurePass123"
}
```

**响应：**

```json
{
  "success": true,
  "data": {
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "示例租户"
  },
  "message": "租户密码已重置"
}
```

### 6.2 超级管理员调用示例

**请求：**

```http
PUT /api/channel/tenants/550e8400-e29b-41d4-a716-446655440000/password?channel_id=660e8400-e29b-41d4-a716-446655440001 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "newPassword": "AdminResetPass456"
}
```

**响应：**

```json
{
  "success": true,
  "data": {
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "示例租户"
  },
  "message": "租户密码已重置"
}
```

### 6.3 cURL 调用示例

```bash
# 渠道管理员调用
curl -X PUT "https://api.example.com/api/channel/tenants/550e8400-e29b-41d4-a716-446655440000/password" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"newPassword": "NewSecurePass123"}'

# 超级管理员调用（需要 channel_id 参数）
curl -X PUT "https://api.example.com/api/channel/tenants/550e8400-e29b-41d4-a716-446655440000/password?channel_id=660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"newPassword": "AdminResetPass456"}'
```

---

## 7. 注意事项

1. **权限隔离**：渠道管理员只能修改本渠道下租户的密码，无法跨渠道操作
2. **超级管理员**：超级管理员必须通过 `channel_id` 查询参数指定目标渠道，才能修改该渠道下租户的密码
3. **密码要求**：新密码最少8位字符，建议包含大小写字母、数字和特殊字符以提高安全性
4. **密码即时生效**：密码修改后立即生效，租户下次登录时需使用新密码
5. **Token不失效**：修改密码后，租户现有的 Token 不会自动失效，如需强制下线请配合其他接口使用

---

## 8. 相关接口

| 接口 | 路径 | 说明 |
|------|------|------|
| 获取租户列表 | `GET /api/channel/tenants` | 获取渠道下的租户列表 |
| 创建租户 | `POST /api/channel/tenants/create` | 创建新租户 |
| 更新租户状态 | `PUT /api/channel/tenants/{tenant_id}/status` | 启用/禁用租户 |
| 更新租户权限 | `PUT /api/channel/tenants/{tenant_id}/permissions` | 管理租户功能权限 |
| 删除租户 | `DELETE /api/channel/tenants/{tenant_id}` | 删除租户（软删除） |

---

## 9. 更新记录

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| v1.0 | 2026-01-13 | 初始版本 | - |