taiji-AI-PAD/Docs/渠道修改租户密码接口文档.md

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

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位字符

请求体示例：

{
  "newPassword": "NewSecurePass123"
}

---

4. 响应参数

4.1 成功响应

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

成功响应示例：

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

4.2 错误响应

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

错误响应示例：

{
  "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 渠道管理员调用示例

请求：

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

响应：

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

6.2 超级管理员调用示例

请求：

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

响应：

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

6.3 cURL 调用示例

# 渠道管理员调用
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	初始版本	-