# Phase 2：管理端读写接口 - Research

**Researched**: 2026-05-07
**Domain**: Django REST Framework 单例资源 + admin token 鉴权 + drf-yasg schema
**Confidence**: HIGH（全部结论基于仓库代码 grep + 文件 read 实证；无 [ASSUMED] 标签）

## Summary

本 phase 在已经成熟的项目上加两条 REST 端点（GET / PUT 同一 URL），所有需要的"积木"都已存在：路由汇总点、鉴权类、响应壳层、ModelSerializer 模板、`@swagger_auto_schema` 用法、单例模型与 `get_solo()` 入口、`mask_token` 工具——**没有任何新依赖、没有任何新基础设施需要落地**。

唯一需要 planner 显式决策的两个事项是：

1. **`/api/v1/admin/` 命名空间的注册位置**：已在 `qy_lty/urls.py:59` 通过 `path('v1/admin/', include('userapp.admin_urls'))` 汇总，对应文件是 `userapp/admin_urls.py`。本 phase 在 `userapp/admin_urls.py` 添加一行 `path('credential-slot/', CredentialSlotAdminView.as_view(), ...)` 并 import 视图即可。
2. **admin-only 权限的实现方式**：仓库中**没有** `IsAdminTokenAuthenticated` 这种 admin-only permission 类。现有 admin 端点（`AdminEmailLoginView` / `AdminLogoutView` / 各 `IsAdminOrReadOnly` 复刻）一律走 `permission_classes = [IsAuthenticated]` + 视图内 `if not request.user.is_staff: return error_response(..., code=403, status_code=403)`。本 phase 必须沿用这个 pattern（**不要发明新 permission class**）。

**Primary recommendation**：自定义 `APIView` + 手写 `get` / `put` 方法（不走 `RetrieveUpdateAPIView`，仓库 0 处使用），1:1 复刻 `aiapp.views.RTCChatHistoryAPIView`（同 app，结构 GET/POST/DELETE，最贴近本 phase 的"单 URL 多方法"形态）。响应一律用 `common.responses.success_response` / `error_response`，**不要**直接写 `Response({...})`——前者已经构造了壳层四字段，后者会被中间件二次包装为非预期形态。

## Architectural Responsibility Map

| 能力 | Primary Tier | Secondary Tier | Rationale |
|------|--------------|----------------|-----------|
| HTTP 路由 `/api/v1/admin/credential-slot/` 的注册 | API 层（`userapp/admin_urls.py`） | — | `qy_lty/urls.py:59` 已把 `/api/v1/admin/` 转给 `userapp.admin_urls` |
| GET / PUT 业务逻辑（脱敏读取 / 全字段覆写） | API 层（`aiapp/views.py` 末尾追加 `CredentialSlotAdminView`） | — | 凭据槽位是 aiapp 的子能力，CONTEXT.md 决策已锁定不新建 app；与 RTCChatHistoryAPIView 同 app 同风格 |
| 请求体校验（`app_id` / `access_token` 字段类型 + 长度） | Serializer 层（新建 `aiapp/serializers.py:CredentialSlotSerializer`） | — | aiapp/serializers.py 已存在，追加新类即可 |
| 单例数据访问 | Model 层（`aiapp.models.CredentialSlot.get_solo()`） | — | Phase 1 已落地 `get_solo()`，view 直接调用 |
| Access Token 脱敏 | 工具层（`common.utils.mask_token`） | View 层调用 | Phase 1 已落地，本 phase view 在返回前手动调一次 |
| admin token 鉴权 | 认证层（`userapp.authentication.RedisTokenAuthentication`） | View 层 `is_staff` 检查 | RedisTokenAuthentication 不区分 admin/user token，必须配合 `is_staff` 二次判断 |
| 标准响应壳层 | 中间件层（`common.middleware.StandardResponseMiddleware`） | View 层调用 `success_response/error_response` | Middleware 已注册，view 用现成 helper |
| Swagger / ReDoc 暴露 | View 层装饰器（`@swagger_auto_schema`） | 全局 schema_view（`qy_lty/urls.py:41`） | drf-yasg 自动扫描，零配置接入 |

## User Constraints (from CONTEXT.md)

### Locked Decisions

**URL 与路由**：
- 路径：`/api/v1/admin/credential-slot/`（trailing slash 沿用 Django 默认风格）
- HTTP 方法：GET 和 PUT 在同一 URL（不分两个 endpoint，符合 RESTful 单例资源约定）
- 路由注册位置：决策由 planner 基于 read_first 后选择
  - 候选 A：`aiapp/urls.py`（凭据槽位语义偏向 AI）
  - 候选 B：仓库现有的 admin namespace `/api/v1/admin/` 在哪个 urls 文件汇总
- **不**新建 `credential` app

**View 实现**：
- **不用** `ModelViewSet`
- **用** `RetrieveUpdateAPIView`（DRF 提供）或自定义 `APIView` + 手写 `get` / `put`
- **推荐**自定义 `APIView`——单例语义不走 `lookup_field`/`pk`
- View 类命名：`CredentialSlotAdminView`，放 `aiapp/views.py`

**Serializer**：
- **DRF ModelSerializer**：`CredentialSlotSerializer`，放 `aiapp/serializers.py`
- 字段：`app_id`、`access_token`、`updated_at`
- `updated_at` 在 GET 响应里 read_only（auto_now 自动维护）
- **Access Token 脱敏在 view 层处理，不在 serializer 层**
- 写入校验：`app_id` 和 `access_token` 都允许空字符串，但**不允许 None**

**鉴权**：
- 直接复用 `RedisTokenAuthentication`
- View 类上配 `authentication_classes = [RedisTokenAuthentication]` + `permission_classes = [IsAuthenticated]`（如果项目已有 admin-only permission；否则用 `IsAuthenticated` + 在 view 里加 `request.user.is_staff` 检查）
- 拒绝时返回 401（无 token）或 403（user token 但非 admin），错误响应必须经过 `StandardResponseMiddleware`

**Swagger / ReDoc**：
- 接口必须出现在 `/swagger/` + `/redoc/`
- View 类上加 `@swagger_auto_schema` 装饰器（method-level，给 GET / PUT 各写一份）
- response schema 显式标注 `access_token` 字段语义为「末 4 位脱敏掩码」

**跨项目联动（修改记录互引）**：
- `qy_lty/docs/修改记录.md` 顶部写一条："新增 Phase 2 管理端 REST 接口"
- `qy-lty-admin/docs/修改记录.md` 顶部写一条："锁定 Phase 2 后端 API 契约（消费方文档化）"

**兼容性**：
- 沿用 Django 4.2.13、DRF 3.x、Python 3.8
- 不引入新依赖

### Claude's Discretion

- 序列化器是否拆 `CredentialSlotReadSerializer` + `CredentialSlotWriteSerializer` 两个类
- view 是放 `aiapp/views.py` 末尾，还是新建 `aiapp/views/credential_slot.py` 子文件
- 错误响应的具体 message 文案（中文）
- View 里如何确保 `get_or_create(pk=1)` 在并发请求下不出竞态

### Deferred Ideas (OUT OF SCOPE)

- **客户端 GET `/api/credential-slot/`** — Phase 3
- **阿里云日志脱敏过滤器** — Phase 3
- **PUT 写入时旧 access_token 的审计日志** — 不在 v1.0 milestone 范畴
- **token 鉴权失败时尝试用其它 token 类型重试 / fallback** — 当前架构禁止此类降级
- **API 限流（防暴力 PUT）** — 现有架构未上限流
- **DB at-rest 加密** — 未来评估

## Phase Requirements

| ID | 描述 | Research Support |
|----|------|------------------|
| CRED-03 | 管理端 GET `/api/v1/admin/credential-slot/`：admin token 鉴权（`admin_token:{token}` Redis key 体系）；返回 `{ app_id, access_token: <masked>, updated_at }`，Access Token 仅返回末 4 位脱敏掩码 | View 模板：`RTCChatHistoryAPIView.get`；鉴权：`RedisTokenAuthentication` + `is_staff`；脱敏：`common.utils.mask_token`；序列化：新建 `CredentialSlotSerializer` + view 层覆写 access_token 字段 |
| CRED-04 | 管理端 PUT `/api/v1/admin/credential-slot/`：admin token 鉴权；接受 `{ app_id, access_token }` 全字段覆写更新；空记录场景自动 `get_or_create`；变更写入 `updated_at` | 数据访问：`CredentialSlot.get_solo()`（Phase 1 落地）；写入：`serializer.is_valid() + serializer.save()`；并发：单例 save 钩子已在 model 层兜底 |

## Project Constraints (from CLAUDE.md)

| 强制规则 | 出处 | 影响本 phase |
|---------|------|------------|
| 所有面向用户的回复使用中文 | CLAUDE.md `## 沟通语言` | 本 RESEARCH.md / 后续 PLAN.md / SUMMARY.md / VERIFICATION.md 全部中文 |
| 修改记录追加到 `docs/修改记录.md` 顶部，最新在最前 | CLAUDE.md `## 项目修改记录规则` | 落地后必须追加一条；格式见现有第 26、42 行模板 |
| `qy_lty` 与 `qy-lty-admin` 各自维护独立修改记录；跨项目联动两端各写一条**互相引用**对方条目 | CLAUDE.md `### qy_lty 与 qy-lty-admin 是独立项目` | Phase 2 是首次跨项目接口契约落地，**两端必须互引** |
| 修改记录条目五字段：文件路径 / 修改类型 / 修改内容 / 修改原因（+ 跨项目联动） | `qy_lty/docs/修改记录.md` 第 11-19 行 | PLAN 的最后一个 task 必须按此格式写两端条目 |

## Standard Stack

### Core（已在仓库内、无需新增）

| 库 | 已有版本 | 用途 | Why Standard |
|----|---------|------|--------------|
| Django | 4.2.13 | Web 框架 | 项目锁定 [VERIFIED: qy_lty/settings.py:4 + STACK.md] |
| Django REST Framework | 未锁定（requirements.txt 不固定版本） | REST API 实现 | 全仓使用，所有 API 走 DRF [VERIFIED: requirements.txt + 多文件 grep] |
| drf-yasg | 未锁定 | Swagger / OpenAPI schema 生成 | 全局 `schema_view` 已配在 `qy_lty/urls.py:41`；`/swagger/`、`/redoc/` 已暴露 [VERIFIED: qy_lty/urls.py:70-72] |

### Supporting（已在仓库内、复用即可）

| 模块 | 路径 | 用途 |
|------|------|------|
| `RedisTokenAuthentication` | `userapp/authentication.py:10-34` | DRF auth class；从 `Authorization: Bearer <token>` 解析 token，调 `get_user_id_from_token` 查 Redis，返回 `(ParadiseUser, None)` |
| `get_user_id_from_token` | `userapp/utils.py:39-45` | **优先**查 `admin_token:{token}`，未命中再查 `token:{token}`；两者都查不到返 None |
| `generate_token(user_id, is_admin=False)` | `userapp/utils.py:33-37` | 生成 token 并写 Redis；`is_admin=True` 时 key 前缀为 `admin_token:`，否则 `token:`；TTL 30 天 |
| `mask_token` | `common/utils.py:10-32` | 脱敏工具；空输入返 `''`；短于 visible_tail 全脱敏；保留末 N 位明文 |
| `success_response` / `error_response` / `api_response` | `common/responses.py` | 构造已带壳层四字段（`success` / `code` / `message` / `data`）的 DRF Response |
| `StandardResponseMiddleware` | `common/middleware.py:6-145` | 全局响应壳层；已注册在 `settings.py:94` |
| `CredentialSlot.get_solo()` | `aiapp/models.py:89-92` | 单例访问入口，`get_or_create(pk=1)` |
| `CredentialSlot.save()` 钩子 | `aiapp/models.py:82-87` | 任何 `save()` 在已有记录时把新对象 pk 重定向，DB 永远只有一行 |
| `@swagger_auto_schema` | drf-yasg 提供 | view 方法装饰器，定义 request_body + responses + operation_description |
| `get_standardized_response_schema()` | `common/swagger_utils.py:44-66` | 返回 OpenAPI Schema，包含 `success` / `code` / `message`；可选追加 `data` 子 schema |

### Alternatives Considered

| 锁定方案 | 候选替代 | 为什么不选 |
|---------|---------|----------|
| 自定义 `APIView` + 手写 `get` / `put` | `RetrieveUpdateAPIView` | 仓库**零处使用** `RetrieveUpdateAPIView`/`UpdateAPIView`/`RetrieveAPIView`（grep 实证）；单例不走 `pk` lookup，需要重写 `get_object()` 反而绕路；自定义 APIView 与 `RTCChatHistoryAPIView` 风格一致 |
| 自定义 `APIView` + 手写 `get` / `put` | `ModelViewSet` | CONTEXT.md 已锁定不用 ModelViewSet；ModelViewSet 默认带 list/create/destroy，单例不需要 |
| 单一 `CredentialSlotSerializer`（同一个类，view 层脱敏） | 拆 `Read` / `Write` 两个 serializer | CONTEXT.md 决策"脱敏放 view 层不放 serializer"，序列化器只做字段校验；拆两个类反而引入"哪个 view 用哪个"的认知负担 |
| `permission_classes = [IsAuthenticated]` + 视图内 `if not request.user.is_staff` | 自定义 `IsAdminTokenAuthenticated` permission class | 仓库**没有** admin-only permission class（grep 实证）；现有所有 admin-only 端点（`AdminEmailLoginView`、`AdminLogoutView`、`IsAdminOrReadOnly`）一律走 `is_staff` 视图内检查；新发明 permission class 与现有约定相悖 |
| `success_response()` / `error_response()` 调用 | 直接 `Response({...}, status=200)` | 项目约定全部 view 走 `common.responses.*` helper（grep `device_interaction/views.py` 即返回 0 处直接用 `Response` 构造、全是 `success_response`/`error_response`）；中间件对二者都能处理，但用 helper 更对齐项目风格 |

**安装**：无任何新依赖。所有积木都在仓库 `requirements.txt` 中。

**版本验证**：跳过——`requirements.txt` 未锁定版本，运行版本由 Docker 镜像决定（Python 3.8 + Django 4.2.13）。drf-yasg `@swagger_auto_schema` 在 4.2 + DRF 3.x 已稳定多年，无版本风险。

## Architecture Patterns

### System Architecture Diagram

```
HTTP 请求
   │
   ▼  PUT/GET /api/v1/admin/credential-slot/  +  Header: Authorization: Bearer <admin_token>
qy_lty/urls.py:66 (api_urlpatterns include)
   │
   ▼  match prefix "v1/admin/" -> userapp.admin_urls
qy_lty/urls.py:59
   │
   ▼  match path "credential-slot/" (新增)
userapp/admin_urls.py
   │
   ▼  CredentialSlotAdminView.as_view()(request)
DRF dispatch:
   │
   ├─→ RedisTokenAuthentication.authenticate(request)
   │     │
   │     ▼  get_user_id_from_token(token):
   │         先查 admin_token:{token}（命中即 admin token）
   │         否则查 token:{token}（命中即 user token）
   │         都查不到 → AuthenticationFailed → 401
   │     │
   │     ▼  ParadiseUser.objects.get(id=user_id) → request.user
   │
   ├─→ permission_classes = [IsAuthenticated] 通过（已认证）
   │
   ├─→ View 内手写：if not request.user.is_staff:
   │     return error_response("需要管理员权限", code=403, status_code=403)
   │   （这一步把 user token 当作非 admin 拦下；CONTEXT.md success #5）
   │
   ├─→ GET 路径：
   │     instance = CredentialSlot.get_solo()
   │     serializer = CredentialSlotSerializer(instance)
   │     data = dict(serializer.data)
   │     data['access_token'] = mask_token(instance.access_token)
   │     return success_response(data=data)
   │
   └─→ PUT 路径：
         instance = CredentialSlot.get_solo()
         serializer = CredentialSlotSerializer(instance, data=request.data)
         if not serializer.is_valid(): return error_response(..., 400)
         serializer.save()                  # auto_now 刷 updated_at
         data = dict(serializer.data)
         data['access_token'] = mask_token(instance.access_token)
         return success_response(data=data)
   │
   ▼  DRF Response 对象
StandardResponseMiddleware.process_response (settings.py:94)
   │
   ▼  检查 response.data 已带 success/code → 不再二次包装（middleware.py:53-55）
HTTP 响应：{"success": ..., "code": ..., "message": ..., "data": {...}}
```

### Recommended Project Structure（增量改动）

```
qy_lty/
├── userapp/
│   └── admin_urls.py           # ← 追加 1 行 path() + 1 行 import
├── aiapp/
│   ├── views.py                # ← 文件末尾追加 CredentialSlotAdminView
│   └── serializers.py          # ← 追加 CredentialSlotSerializer 类
└── docs/
    └── 修改记录.md              # ← 顶部追加一条 Phase 2 条目（含跨项目联动）

../qy-lty-admin/
└── docs/
    └── 修改记录.md              # ← 顶部追加一条互引条目
```

### Pattern 1：单 URL 多方法 APIView（参考 RTCChatHistoryAPIView）

**What**：一个 URL、多个 HTTP 方法（GET / PUT），每个方法用自己的实例方法实现，方法各自挂 `@swagger_auto_schema`。

**When to use**：单例资源 + 不需要 list/create/delete 的场景。

**Example**（直接来源仓库代码 `aiapp/views.py:434-555`，可 1:1 套用骨架）：

```python
# 来源：qy_lty/aiapp/views.py:434-498（RTCChatHistoryAPIView GET 方法）
class RTCChatHistoryAPIView(APIView):
    """
    RTC 语音智能体聊天记录接口

    GET: 获取当前用户的 RTC 聊天历史
    POST: 保存一条 RTC 聊天消息
    DELETE: 清空当前用户的 RTC 聊天记录
    """
    authentication_classes = [RedisTokenAuthentication]
    permission_classes = [IsAuthenticated]

    def get(self, request):
        # ... 业务逻辑 ...
        return success_response(data=data)

    def post(self, request):
        # ... 业务逻辑 ...
        return created_response(data={...})
```

**Phase 2 复刻骨架**：

```python
# 拟落地于：qy_lty/aiapp/views.py 文件末尾
from .models import CredentialSlot          # 已在 import 区
from .serializers import CredentialSlotSerializer  # 新增
from common.utils import mask_token          # 新增 import

class CredentialSlotAdminView(APIView):
    """
    通用凭据槽位管理端读写接口（admin token 鉴权）

    GET: 返回脱敏后的凭据槽位
    PUT: 全字段覆写凭据槽位
    """
    authentication_classes = [RedisTokenAuthentication]
    permission_classes = [IsAuthenticated]

    def _ensure_admin(self, request):
        """admin-only 二次校验：拒绝非 staff 用户（含 user token 持有者）"""
        if not request.user.is_staff:
            return error_response(
                message="需要管理员权限",
                code=403,
                status_code=status.HTTP_403_FORBIDDEN,
            )
        return None

    @swagger_auto_schema(...)  # 详见 Pattern 4
    def get(self, request):
        forbidden = self._ensure_admin(request)
        if forbidden:
            return forbidden
        instance = CredentialSlot.get_solo()
        serializer = CredentialSlotSerializer(instance)
        data = dict(serializer.data)
        data['access_token'] = mask_token(instance.access_token)
        return success_response(data=data)

    @swagger_auto_schema(...)  # 详见 Pattern 4
    def put(self, request):
        forbidden = self._ensure_admin(request)
        if forbidden:
            return forbidden
        instance = CredentialSlot.get_solo()
        serializer = CredentialSlotSerializer(instance, data=request.data)
        if not serializer.is_valid():
            return error_response(message="参数无效", data=serializer.errors, code=400)
        serializer.save()  # auto_now 自动刷 updated_at
        data = dict(serializer.data)
        data['access_token'] = mask_token(instance.access_token)
        return success_response(data=data, message="凭据已更新")
```

### Pattern 2：DRF ModelSerializer 写法

**What**：基于现有 Model 自动生成 serializer，声明 `Meta.fields` 与 `Meta.read_only_fields`。

**Example**（来源 `qy_lty/aiapp/serializers.py:1-9`）：

```python
# 现有代码 - aiapp/serializers.py 全文
from rest_framework import serializers
from .models import ChatMessage

class ChatMessageSerializer(serializers.ModelSerializer):
    class Meta:
        model = ChatMessage
        fields = ['id', 'user', 'bot', 'message', 'timestamp', 'sender', 'message_type', 'message_audio_url', 'message_video_url']
        read_only_fields = ['id', 'timestamp', 'sender']
```

**Phase 2 新增骨架**（追加到同文件）：

```python
from .models import ChatMessage, CredentialSlot

class CredentialSlotSerializer(serializers.ModelSerializer):
    """通用凭据槽位序列化器（明文）

    GET 时 view 层会用 mask_token 把 access_token 替换为掩码后再返回；
    PUT 时直接以明文进入 is_valid + save，由 view 层在响应阶段脱敏。
    """

    class Meta:
        model = CredentialSlot
        fields = ['app_id', 'access_token', 'updated_at']
        read_only_fields = ['updated_at']
        extra_kwargs = {
            # 与模型 blank=True / default='' 一致：允许空字符串、不允许 None
            'app_id': {'allow_blank': True, 'allow_null': False, 'required': False},
            'access_token': {'allow_blank': True, 'allow_null': False, 'required': False},
        }
```

**注意事项**：
- 模型字段 `blank=True, default=''`（`aiapp/models.py:65-72`），因此 `required=False`；PUT body 缺字段会用现有值兜底
- "全字段覆写"语义在 PUT body 既给两个字段时成立；缺字段时由 ModelSerializer 默认行为回填
- 如果"全字段覆写"严格要求两字段都必须出现，可改 `'required': True`——但 CONTEXT.md 没硬性要求，按 PUT 习惯（部分缺失允许）即可

### Pattern 3：标准响应封装（三种调用法）

**What**：所有 view 都通过 `common.responses` 的 helper 返回。

**Examples**（grep 实证 — 全仓所有 admin-related view 都用这套）：

```python
# qy_lty/userapp/views.py:146-155 (success)
return success_response(
    data={'token': token, 'user_id': ...},
    message="登录成功"
)

# qy_lty/userapp/views.py:750-754 (forbidden — admin 校验失败)
return error_response(
    message="Access denied. Admin privileges required.",
    code=403,
    status_code=status.HTTP_403_FORBIDDEN
)

# qy_lty/aiapp/views.py:478-479 (validation error)
return error_response(message='since_id 必须是整数')  # 默认 code=400, status=400
```

**Phase 2 错误响应矩阵**（CONTEXT.md success criteria #1-#5 对应）：

| 场景 | HTTP 状态 | code | message（建议中文文案） | helper 调用 |
|------|----------|------|------------------------|------------|
| GET / PUT 成功 | 200 | 200 | "操作成功"（默认）/ "凭据已更新" | `success_response(data=...)` |
| 无 Authorization 头 | 401 | 401 | DRF 默认 "Authentication credentials were not provided." → 由 middleware `process_exception` 包装 | DRF 自动（`NotAuthenticated`） |
| Authorization 头存在但 token 在 Redis 查不到 | 401 | 401 | "Invalid token"（DRF AuthenticationFailed） | DRF 自动 |
| Token 命中但用户非 staff（user token 持有者） | 403 | 403 | "需要管理员权限" | `error_response(code=403, status_code=status.HTTP_403_FORBIDDEN)` |
| PUT body 字段类型错误（如非字符串） | 400 | 400 | "参数无效" + serializer.errors as data | `error_response(code=400, data=serializer.errors)` |

### Pattern 4：drf-yasg `@swagger_auto_schema`（method-level）

**What**：在 APIView 的方法上挂装饰器，drf-yasg 自动生成 OpenAPI schema。

**Example**（来源 `qy_lty/userapp/views.py:92-100`，最简洁的样板）：

```python
# AdminEmailLoginView.post —— 同样 admin namespace、同样 IsAuthenticated/AllowAny 风格
@swagger_auto_schema(
    request_body=AdminEmailLoginRequestSchema,
    responses={
        200: openapi.Response('登录成功', get_standardized_response_schema()),
        400: openapi.Response('请求参数错误', get_standardized_response_schema()),
        403: openapi.Response('权限不足', get_standardized_response_schema())
    },
    operation_description="专用于管理员通过邮箱和密码登录..."
)
def post(self, request):
    ...
```

**关键约定**：
- `request_body=` 接受 `serializers.Serializer` 子类（不是 ModelSerializer，是手写的 schema 类——见 `userapp/views.py:38-78`，把请求/响应字段建模为独立的 `serializers.Serializer` 子类专门给 swagger 用）
- `responses=` 用 `openapi.Response('描述文案', schema_obj)` 字典；schema_obj 推荐用 `common.swagger_utils.get_standardized_response_schema()`，自动产出符合壳层四字段的 OpenAPI Schema
- `operation_description=` 中文文案
- `security=[{'Bearer': []}]` 用于声明该接口需 Bearer token（非必需，但已存在的 admin 接口有用，建议加）

**Phase 2 装饰器骨架**：

```python
# request body schema（追加到 aiapp/views.py 顶部 schema 区，类似 userapp/views.py:38-78）
class CredentialSlotPutRequestSchema(serializers.Serializer):
    app_id = serializers.CharField(required=False, allow_blank=True, help_text="第三方服务商分配的 APP ID")
    access_token = serializers.CharField(required=False, allow_blank=True, help_text="第三方服务商访问令牌（明文写入）")

# response data schema（access_token 显式标注脱敏掩码语义）
credential_slot_data_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'app_id': openapi.Schema(type=openapi.TYPE_STRING, description='第三方服务商分配的 APP ID'),
        'access_token': openapi.Schema(
            type=openapi.TYPE_STRING,
            description='Access Token 末 4 位脱敏掩码（如 "*********1234"）',
        ),
        'updated_at': openapi.Schema(type=openapi.TYPE_STRING, format='date-time', description='最近一次更新时间'),
    },
)

# 在 view 方法上挂：
@swagger_auto_schema(
    operation_description="读取通用凭据槽位（access_token 末 4 位脱敏返回）",
    responses={
        200: openapi.Response('读取成功', get_standardized_response_schema(credential_slot_data_schema)),
        401: openapi.Response('未提供有效 token', get_standardized_response_schema()),
        403: openapi.Response('需要管理员权限', get_standardized_response_schema()),
    },
    security=[{'Bearer': []}],
)
def get(self, request):
    ...

@swagger_auto_schema(
    request_body=CredentialSlotPutRequestSchema,
    operation_description="全字段覆写通用凭据槽位（写入后返回脱敏值）",
    responses={
        200: openapi.Response('更新成功', get_standardized_response_schema(credential_slot_data_schema)),
        400: openapi.Response('参数无效', get_standardized_response_schema()),
        401: openapi.Response('未提供有效 token', get_standardized_response_schema()),
        403: openapi.Response('需要管理员权限', get_standardized_response_schema()),
    },
    security=[{'Bearer': []}],
)
def put(self, request):
    ...
```

### Anti-Patterns to Avoid

- **直接构造 `Response({...}, status=200)`**：仓库其它 admin view（如 `AdminEmailLoginView`、`AdminLogoutView`）从不直接构造，全部用 helper；直接构造也能跑（middleware 会包装），但与项目约定相悖
- **试图给 view 同时加 `IsAdminUser` permission**：`IsAdminUser`（DRF 内置）依赖 `request.user.is_staff`——能用，但与本仓库已有的"`IsAuthenticated` + 视图内 `is_staff` 检查"模式不一致；统一走视图内检查更可读
- **在 serializer 内做脱敏**（如 `to_representation` 覆写）：CONTEXT.md 已锁定"脱敏放 view 层"；混着写会让 PUT 写入路径需要二次序列化
- **试图从 token 字符串本身判断 admin**：`token` 是 UUID，没有载荷；admin/user 区分只能通过 Redis key 前缀（已由 `RedisTokenAuthentication` 透明处理，且后续 `request.user.is_staff` 才是真正的判定）
- **新建 `IsAdminTokenAuthenticated` permission class**：仓库零先例；如果坚持封装，会引入"为什么和 IsAdminOrReadOnly 不一样"的认知负担

## Don't Hand-Roll

| 问题 | 不要自己写 | 用现成的 | 理由 |
|------|----------|---------|------|
| Admin token 鉴权 | 自己写 BaseAuthentication 子类 | `userapp.authentication.RedisTokenAuthentication`（已存在） | 全项目统一鉴权类，绑定到 `ParadiseUser` model；自己写会脱节 |
| Admin / User token 区分 | 自己解析 Redis key 前缀 | 间接通过 `request.user.is_staff` 判断 | `get_user_id_from_token` 已优先匹配 admin_token 前缀；user model 的 `is_staff` 字段才是权限来源 |
| 单例数据访问 | 自己写 `get_or_create` 包装 | `CredentialSlot.get_solo()`（Phase 1 已落地） | Phase 1 已确立 single source of truth，重复实现会脱钩 |
| Token 脱敏 | 自己写字符串切片 | `common.utils.mask_token`（Phase 1 已落地） | 已含边界处理（空 / 短于 visible_tail），有 7 个表驱动用例的可信度，Phase 3 阿里云日志 formatter 也将复用同一函数 |
| 标准响应壳层 | 自己写 `Response({"success": True, ...})` | `common.responses.success_response/error_response/api_response` | 中间件已注册，helper 是最安全的入口（与 middleware 约定的"已含 success/code 字段不再二次包装"语义对齐） |
| OpenAPI Schema 类型 | 自己写裸 `openapi.Schema(...)` | `common.swagger_utils.get_standardized_response_schema(data_schema=...)` | 自动产出含壳层四字段的 schema，前端直接基于 swagger 生成 client 时拿到正确签名 |
| Swagger 装饰器组合 | 抽样照抄/拼装 | `common.swagger_utils.swagger_schema(...)` 装饰器 | 已合并默认 401/403 响应；但仓库内同时存在直接用 `@swagger_auto_schema` 的写法（`userapp/views.py` 各处），二者均可，**保持单一文件内一致**即可——本 phase 的 `aiapp/views.py` 现有代码两种都用过，任选其一无伤大雅 |

**核心洞见**：本 phase **没有任何"复杂度藏在哪"的隐患**——所有可能"自己写出问题"的环节都已有标准实现。如果出现"我想自己实现 XX"的冲动，先回头查 `common/` 与 `userapp/` 是不是已经有了。

## Runtime State Inventory

> 本 phase 是新增端点，**不**涉及 rename / refactor / migration。但仍简短列出检查结果以避免遗漏：

| 类别 | 检查项 | 结果 |
|-----|--------|------|
| 数据存储 | DB 是否已存在 CredentialSlot 单例记录 | 已存在（Phase 1 探针 `pk=1, app_id='probe_app', access_token='probe_secret_xxxx'` 已写入；本 phase PUT 第一次调用会原地覆写这条而非创建新记录） |
| 服务运行时配置 | 现有 admin 端点是否登记到 `userapp.admin_urls` | 是（仅 `login/`、`logout/` 两个；本 phase 追加 `credential-slot/` 是第三个） |
| OS 注册状态 | 无 | 不涉及 |
| 密钥 / 环境变量 | 无新增 | 不涉及（Phase 2 只读写 DB，不读环境变量） |
| 构建产物 | 无 | 不涉及（Python 解释执行，无 build step） |

**未发现遗留状态需要清理**。

## Common Pitfalls

### Pitfall 1：把 user token 当 admin token 错放进去

**What goes wrong**：CONTEXT.md 决策 #5 要求"携带 user token 调用本接口必须返 403"。如果只配 `permission_classes=[IsAuthenticated]` 而不在 view 内 check `is_staff`，user token 持有者会被放行（200 OK + 数据返回）。

**Why it happens**：`RedisTokenAuthentication.authenticate` 不区分 admin/user token，两类 token 都能通过 IsAuthenticated 这一关。区分点是 `ParadiseUser.is_staff` 字段——但仅当用户主动调过 `AdminEmailLoginView`（生成 admin token）后，token 持有者本身才会是 staff 用户；user token 持有者一般是手机号/MAC 登录的普通用户，`is_staff=False`。

**How to avoid**：
- 在每个方法体最开始调用 `_ensure_admin(request)` helper（见 Pattern 1 骨架）
- 1:1 抄 `AdminEmailLoginView.post` 第 748-754 行的 `if not user.is_staff: return error_response(..., code=403, status_code=status.HTTP_403_FORBIDDEN)` 模式

**Warning signs**：
- 用户用手机端 token 调 GET 返回 200 + 真实数据 → bug
- 单元测试只测了 admin token 路径没测 user token 路径 → 漏测

### Pitfall 2：`StandardResponseMiddleware` 二次包装

**What goes wrong**：如果 view 直接 `return Response({'success': True, 'data': {...}})`，middleware 看到 response.data 已含 `success`/`code` 字段（middleware.py:53-55），就**不会**二次包装；但如果你只写 `Response({'foo': 'bar'})`，middleware 会把整个 dict 当 data 包进去，最终得到 `{success: True, code: 200, data: {foo: 'bar'}}`——这通常是想要的行为，但容易误判。

**Why it happens**：middleware 通过 "data 中是否同时存在 success 和 code 两个 key" 判断"已经是标准格式"。`success_response` helper 主动放入这两个字段；裸 `Response` 不会。

**How to avoid**：
- 一律用 `common.responses.success_response` / `error_response` / `api_response` / `not_found_response` 等 helper
- 不要为了追求最小 diff 写 `Response({'app_id': ..., 'access_token': ..., 'updated_at': ...})`——middleware 会按照 dict-not-yet-wrapped 路径处理（middleware.py:71-98），把整个 dict 当 data 包进去；功能上 OK，但与项目风格不符

**Warning signs**：
- 响应里 `data` 字段嵌套了一层 `data` → 双重包装
- 响应里没有 `success` 字段 → middleware 没识别成 DRF response（不太可能，但要注意）

### Pitfall 3：PUT 写入后忘记脱敏返回

**What goes wrong**：CONTEXT.md 决策"PUT 响应也走脱敏（写入成功后用脱敏值返回）"。如果 view PUT 路径用 `return success_response(data=serializer.data)` 直接返回，serializer.data 含**明文** access_token（因为 serializer 未做脱敏），就会把刚刚写入的明文回显给运营。

**Why it happens**：脱敏放 view 层，serializer 本身不脱敏；忘记脱敏 = 明文泄露。

**How to avoid**：PUT 路径与 GET 路径都必须执行：
```python
data = dict(serializer.data)
data['access_token'] = mask_token(instance.access_token)
return success_response(data=data)
```
（`dict(serializer.data)` 是因为 `serializer.data` 是 `OrderedDict`，可以直接修改；安全起见 cast 一下避免不可变问题）

**Warning signs**：
- Verify 阶段用 curl PUT 后看到响应 `data.access_token` 是明文 → 漏脱敏
- 单元测试只断言"access_token 字段存在"没断言"是脱敏掩码格式" → 漏断言

### Pitfall 4：admin_urls.py 漏注册

**What goes wrong**：`userapp/admin_urls.py` 只有 `login/` + `logout/` 两个 path。如果只在 `aiapp/views.py` 写了 view 但忘了在 `userapp/admin_urls.py` 加 path()，URL 不存在，curl 返 404（被 `StandardResponseMiddleware` 处理后是 `{success: false, code: 404, ...}`，但与 401/403 含义不同）。

**How to avoid**：
- PLAN 中显式拆出"修改 `userapp/admin_urls.py`"作为独立 task
- 在该 task 的 verify 步骤里 curl 一次，确认从 router 层就能命中

**Warning signs**：
- 401/403/200 全都不返回，返回 404 → 路由注册漏了

### Pitfall 5：`auto_now` 字段被写入策略覆盖

**What goes wrong**：`updated_at` 字段配 `auto_now=True`（`aiapp/models.py:73`），DRF ModelSerializer 默认会把这个字段当作 read-only（因为 `editable=False`），但显式写 `Meta.read_only_fields = ['updated_at']` 是双重保险。如果忘了 `read_only_fields`，DRF 在 PUT 时仍然不会写它（auto_now 优先），但 swagger schema 可能错误地把它当作可写字段。

**How to avoid**：显式写 `read_only_fields = ['updated_at']`（见 Pattern 2 骨架）

**Warning signs**：swagger UI 上 PUT body schema 出现 `updated_at` 字段 → 漏配 read_only

## Code Examples

### 完整 PLAN 落地后的 view 与 serializer 示意

**`aiapp/serializers.py`** —— 在现有 `ChatMessageSerializer` 之后追加：

```python
# 来源（参考）：qy_lty/aiapp/serializers.py 现有结构
from .models import ChatMessage, CredentialSlot

class CredentialSlotSerializer(serializers.ModelSerializer):
    """通用凭据槽位序列化器（明文存储，view 层脱敏）"""

    class Meta:
        model = CredentialSlot
        fields = ['app_id', 'access_token', 'updated_at']
        read_only_fields = ['updated_at']
        extra_kwargs = {
            'app_id': {'allow_blank': True, 'allow_null': False, 'required': False},
            'access_token': {'allow_blank': True, 'allow_null': False, 'required': False},
        }
```

**`userapp/admin_urls.py`** —— 在现有 `path('logout/', ...)` 之后追加：

```python
# 来源：qy_lty/userapp/admin_urls.py 现有结构
from django.urls import path
from .views import AdminEmailLoginView, AdminLogoutView
from aiapp.views import CredentialSlotAdminView   # 新增 import

urlpatterns = [
    path('login/', AdminEmailLoginView.as_view(), name='admin_login'),
    path('logout/', AdminLogoutView.as_view(), name='admin_logout'),
    path('credential-slot/', CredentialSlotAdminView.as_view(), name='admin_credential_slot'),  # 新增
]
```

**`aiapp/views.py`** —— 在文件末尾追加（紧跟 `RTCChatHistoryAPIView` 之后）：

完整骨架已在 Pattern 1 + Pattern 4 给出，此处不重复。需要新增的顶部 import：

```python
# 已在 import 区
from .models import ChatMessage, Bot   # 改为 from .models import ChatMessage, Bot, CredentialSlot
from .serializers import ChatMessageSerializer  # 改为 from .serializers import ChatMessageSerializer, CredentialSlotSerializer
# 新增
from common.utils import mask_token
from common.swagger_utils import get_standardized_response_schema
```

## State of the Art

本仓库基于 Django 4.2.13 + DRF 3.x + drf-yasg 都是稳定栈，本 phase 不涉及新技术或废弃 pattern 切换。

**已废弃 / 不推荐**：
- 拆 `Read` / `Write` 两个 serializer：CONTEXT.md 已锁定单一 serializer + view 层脱敏（避免 serializer 双重责任）
- `RetrieveUpdateAPIView`：仓库零先例，单例资源不走 pk lookup 反而绕路
- 自定义 admin permission class：仓库零先例，统一走视图内 `is_staff` 检查

## Assumptions Log

> 列出所有 `[ASSUMED]` 标签的声明。本 phase 的所有结论都通过 grep / read 在仓库内实证。

| # | 声明 | 章节 | 风险 |
|---|------|------|------|
| — | — | — | — |

**本表为空**：所有声明都来自代码 grep / 文件 read 实证；DRF / drf-yasg / Django 的 API 行为无 [ASSUMED] 依赖（仓库内已有大量样板，足以验证）。

## Open Questions

无。研究问题的 8 个全部解决：

1. ✅ `/api/v1/admin/` 汇总点 — `qy_lty/urls.py:59` → `userapp/admin_urls.py`
2. ✅ View 模板 — `aiapp/views.py:434-555 RTCChatHistoryAPIView`（同 app、单 URL 多方法、与本 phase 形态最贴近）；次选 `userapp/views.py:778-823 AdminLogoutView`（admin namespace 内、含 admin 校验）
3. ✅ admin/user token 区分 — 在 `RedisTokenAuthentication` 内不区分；`get_user_id_from_token` 优先查 admin_token，再查 token；admin-only **没有现成 permission 类**，本 phase 必须在 view 内自加 `is_staff` 检查
4. ✅ `StandardResponseMiddleware` 与 DRF Response 兼容 — middleware 检查 response.data 是否含 `success` + `code`，已含则不二次包装；用 `success_response/error_response` helper 总是正确路径
5. ✅ DRF Serializer 模式 — `aiapp/serializers.py` 存在，含 `ChatMessageSerializer` 模板（`Meta.fields` + `Meta.read_only_fields`）；新增 `CredentialSlotSerializer` 追加即可
6. ✅ `@swagger_auto_schema` 用法 — 最佳样板：`userapp/views.py:92-100`（method-level + `request_body` + `responses` + `operation_description` + `security`）；与 `common.swagger_utils.get_standardized_response_schema()` 配合
7. ✅ `qy-lty-admin/docs/修改记录.md` 状态 — **已存在**（`qy-lty-admin/docs/修改记录.md`），头部含完整"修改格式说明"段（同款骨架），第 24 行 `## 修改历史` 之下追加新条目即可（最新在最前）
8. ✅ DRF 单例资源模式 — 自定义 `APIView` + 手写 `get` / `put`（仓库 0 处使用 `RetrieveUpdateAPIView`），1:1 复刻 `RTCChatHistoryAPIView` 风格

## Environment Availability

> 本 phase 不引入任何新外部依赖；运行时依赖（PostgreSQL / Redis / Django 4.2.13 / DRF / drf-yasg）已被 Phase 1 验证通过。

| 依赖 | 用途 | 是否可用 | 版本 | 备用 |
|------|------|---------|------|------|
| PostgreSQL | DB 存储（CredentialSlot 表） | ✓ | Phase 1 已迁移 0004_credentialslot 生效 | — |
| Redis | admin token 查询 + cache backend | ✓ | 已运行（Phase 1 verify 已实证） | — |
| Django 4.2.13 + DRF | view / serializer / urlconf | ✓ | Docker 镜像 / requirements.txt | — |
| drf-yasg | swagger schema 生成 | ✓ | `qy_lty/urls.py:41-46` 已配 schema_view | — |

**无缺失依赖**。

## Validation Architecture

> `.planning/config.json` 未显式设 `workflow.nyquist_validation`，按缺省=启用处理。但本仓库无 pytest / unittest 基础设施（grep `tests.py` 都是空文件骨架，REQUIREMENTS.md 候选优先级 #5 明确"测试基础设施搭建"在下个 milestone）。

### Test Framework

| 属性 | 值 |
|------|-----|
| 框架 | 无单元测试框架（Django 自带 `TestCase` 可即时使用，但项目无现成测试套件） |
| 配置文件 | 无 `pytest.ini` / `pyproject.toml` 测试段；`conftest.py` 不存在 |
| 快速验证命令 | `python manage.py shell` + Django test client（沿用 Phase 1 的 verify 风格） |
| 完整套件命令 | `python manage.py test` —— 但仓库 tests.py 全空，跑了等于啥都没测 |

### Phase 需求 → 验证手段映射

| Req | Behavior | 类型 | 自动化命令 | 现成 fixtures |
|-----|----------|------|-----------|--------------|
| CRED-03 GET 脱敏 | curl 携 admin token → 200 + masked | smoke（curl） | `curl -H "Authorization: Bearer <admin_token>" http://localhost:8000/api/v1/admin/credential-slot/` | ❌ Wave 0 需先签发 admin token（Django shell + `generate_token(user_id, is_admin=True)`） |
| CRED-04 PUT 写入 | curl PUT 全字段 → 200 + DB 更新 + updated_at 刷新 | smoke（curl） | `curl -X PUT -H "Authorization: Bearer <admin_token>" -H "Content-Type: application/json" -d '{"app_id":"x","access_token":"y"}' .../credential-slot/` | ❌ Wave 0 同上 |
| 401 拒绝 | 不带 token | smoke | `curl http://localhost:8000/api/v1/admin/credential-slot/` | ✓（无需 fixture） |
| 403 拒绝 | 携 user token（非 admin） | smoke | `curl -H "Authorization: Bearer <user_token>" .../credential-slot/` | ❌ Wave 0 需先签发 user token（`generate_token(user_id)` 不带 is_admin） |
| Swagger 暴露 | `/swagger/` HTML 页面含路径条目 | smoke（HTML grep） | `curl http://localhost:8000/swagger.json \| python -c "import json,sys; print('credential-slot' in json.dumps(json.load(sys.stdin)))"` | ✓（无需 fixture） |
| 修改记录两端互引 | 文件 grep | static check | `grep -l "Phase 2" qy_lty/docs/修改记录.md qy-lty-admin/docs/修改记录.md` | ✓ |

### 采样频率

- **任务 commit 后**：Django shell + test client 调 `Client(...).get/.put('/api/v1/admin/credential-slot/', HTTP_AUTHORIZATION='Bearer ...')` 跑 5 个判据（200/401/403 + GET 脱敏 + PUT 回显脱敏）；这与 Phase 1 verify 风格 1:1（`force_login` 风格的程序化验收）
- **Wave 合并后**：跑一次 full `curl` 套件（含 swagger.json 校验）
- **Phase gate**：`/gsd-verify-work` 用 Django test client + curl 两层都跑

### Wave 0 缺口

- [ ] 测试用 admin token 与 user token 的签发脚本（一次性 Django shell 命令，写在 PLAN 的 setup task）
- [ ] 不需要新建 test 文件（Phase 1 已确立用 Django test client 程序化验收的模式，无需框架）
- [ ] 不需要装新依赖

## Security Domain

> CLAUDE.md 与 PROJECT.md 未明确启用 `security_enforcement` flag，但本 phase 涉及凭据存储 + 鉴权 + 脱敏，仍按基础 ASVS 类别梳理。

### Applicable ASVS Categories

| ASVS Category | 适用 | 标准控制 |
|---------------|------|---------|
| V2 Authentication | 是 | `RedisTokenAuthentication` Bearer token；30 天 TTL |
| V3 Session Management | 是 | Token 存储于 Redis，由 `generate_token` 创建、`get_user_id_from_token` 验证；登出走 `cache.delete(f"admin_token:{token}")`（`userapp/views.py:819`） |
| V4 Access Control | 是 | View 层 `is_staff` 二次校验；admin token 来自 `AdminEmailLoginView` 路径，普通用户 token 来自 `MacAddressLoginView`/`PhoneLoginView` 等 |
| V5 Input Validation | 是 | `CredentialSlotSerializer` 的 `is_valid()` 校验：CharField 类型 + max_length（128 / 512） + `allow_null=False` |
| V6 Cryptography | 部分 | DB at-rest 加密 **不在本 phase 范畴**（CONTEXT.md deferred ideas 明确）；`access_token` 在 DB 中明文，但响应脱敏；transport 加密由生产环境的 Nginx HTTPS 反代提供（与本 phase 无关） |
| V7 Error Handling | 是 | DRF 的 `AuthenticationFailed` / `PermissionDenied` 异常被 `StandardResponseMiddleware.process_exception` 接住，转 JSON 壳层 |
| V14 Configuration | 部分 | `.env` 不入版本库；本 phase 不读环境变量，配置全在 DB |

### 本 stack 的已知威胁模式

| 模式 | STRIDE | 标准缓解 |
|------|--------|---------|
| user token 被滥用调 admin 端点 | Elevation of Privilege | View 层 `is_staff` 二次校验（CONTEXT.md success #5） |
| Access Token 明文落入日志 | Information Disclosure | 本 phase view 层脱敏返回（GET 与 PUT 响应都脱敏）；Phase 3 阿里云日志 formatter 进一步过滤请求体里的 `access_token` |
| PUT 重放攻击（无幂等性保护） | Tampering | 全字段覆写本身就是幂等的；写两次同样 body 结果一致；不需额外保护 |
| Token 在 URL 中泄露（access log） | Information Disclosure | 本 phase 强制 Header `Authorization: Bearer ...`，**不**支持 URL 携 token；与 WebSocket 路径下的 `/ws/device/token/{token}/` 不同 |
| 暴力 PUT（消耗 DB） | Denial of Service | CONTEXT.md deferred ideas 明确"API 限流不在本 phase 范畴"；现有架构无限流（这是已知风险，由 PROJECT.md candidate priorities #2 跟踪） |
| 序列化器接受未声明字段（mass assignment） | Tampering | DRF ModelSerializer 默认拒绝未在 fields 中声明的字段；`Meta.fields = ['app_id', 'access_token', 'updated_at']` 三字段封死，无 mass assignment 风险 |

## Sources

### Primary（HIGH confidence）

仓库内代码 grep + 文件 read（全部一手实证）：

- `qy_lty/urls.py:59` — `path('v1/admin/', include('userapp.admin_urls'))` 路由汇总点
- `userapp/admin_urls.py` — admin namespace urlconf 全文（仅 login/logout 两条）
- `userapp/authentication.py:10-34` — `RedisTokenAuthentication` 完整实现
- `userapp/utils.py:33-45` — `generate_token` + `get_user_id_from_token` 实现
- `userapp/views.py:705-823` — `AdminEmailLoginView` + `AdminLogoutView`（admin-only 二次校验模板）
- `aiapp/views.py:434-555` — `RTCChatHistoryAPIView`（单 URL 多方法 APIView 模板，本 phase 1:1 复刻）
- `aiapp/views.py:80-114` — `ChatBotAPIView`（method-level `@swagger_auto_schema` 简洁样板）
- `aiapp/serializers.py` 全文 — `ChatMessageSerializer`（ModelSerializer 模板）
- `aiapp/models.py:55-93` — `CredentialSlot` 模型 + `get_solo()` + save 钩子
- `aiapp/admin.py:18-53` — `CredentialSlotAdmin` Phase 1 落地的脱敏样板
- `common/middleware.py:6-145` — `StandardResponseMiddleware` 完整实现（含二次包装规避逻辑 line 53-55）
- `common/responses.py` 全文 — `success_response` / `error_response` / `api_response`
- `common/utils.py:10-32` — `mask_token` 工具函数
- `common/swagger_utils.py` 全文 — `get_standardized_response_schema()` + `swagger_schema()` 装饰器
- `qy_lty/settings.py:82-95` — `MIDDLEWARE` 注册顺序（含 `StandardResponseMiddleware`）
- `qy_lty/docs/修改记录.md:1-90` — 修改记录格式 + Phase 1 已落地两条样板
- `qy-lty-admin/docs/修改记录.md:1-58` — 已存在的修改记录格式 + 已有跨项目联动条目样板
- `requirements.txt` — 确认无新依赖（drf-yasg / djangorestframework / django 都已在）
- `.planning/phases/01-credential-data-layer/01-VERIFICATION.md` — Phase 1 verify 模式（test client 程序化验收）

### Secondary（MEDIUM confidence）

无需要——本 phase 全部决策都在 primary 一手代码内可证。

### Tertiary（LOW confidence）

无。

## Metadata

**Confidence breakdown**:
- Standard stack: HIGH — 全部组件在仓库内已用过，无版本风险
- Architecture: HIGH — `RTCChatHistoryAPIView` 是 1:1 模板，单例 + 鉴权 + middleware 链路全部已在仓库实证
- Pitfalls: HIGH — 5 个 pitfall 都基于现有代码 + middleware 行为推导（特别是 Pitfall 2 关于 middleware 二次包装的逻辑直接来自 middleware.py:53-55）

**Research date**: 2026-05-07
**Valid until**: 2026-06-07（30 天 — 仓库结构稳定，无外部 API 依赖，时效较长）

---

*Phase: 02-admin-rest*
*Researched: 2026-05-07 by gsd-researcher*