# lingma-openai-gateway 测试计划（tests）

## 1. 目标
- 覆盖网关核心稳定性路径：认证、并发限流、会话复用、协议内容规范化。
- 在不引入外部依赖（Lingma 进程/Playwright）的前提下，使用 `unittest` 完成可重复回归。
- 与现有 `tests/test_tool_call_bridge.py` 互补：该文件聚焦工具桥接，本计划补齐基础模块行为。

## 2. 范围与优先级
- **P0（必须）**
  1) 认证行为（`app/auth.py`）
  2) 并发守卫行为（`app/concurrency.py`）
  3) 会话缓存与工具配置指纹（`app/session_cache.py`）
- **P1（应覆盖）**
  4) OpenAI/Anthropic 内容规范化（`app/openai_schema.py`, `app/anthropic_schema.py`）

## 3. 用例矩阵
| 用例ID | 优先级 | 模块 | 场景 | 预期 |
|---|---|---|---|---|
| TC-AUTH-01 | P0 | auth | Bearer 正确 token | 认证通过 |
| TC-AUTH-02 | P0 | auth | 缺失/错误 Authorization | 401 + `invalid_api_key` |
| TC-AUTH-03 | P0 | auth | Anthropic `x-api-key` 与 Bearer 兜底 | 正确 key 通过，缺失时报 `AnthropicAuthError` |
| TC-AUTH-04 | P0 | auth | metrics 在未配置 token 且非 public | 503 + `metrics_disabled` |
| TC-CONC-01 | P0 | concurrency | `max_in_flight<=0` 无限制模式 | 获取/释放计数正确，release 幂等 |
| TC-CONC-02 | P0 | concurrency | 单槽占用后第二请求超时 | 抛 `BackpressureRejected`，rejected 计数+1 |
| TC-SESS-01 | P0 | session_cache | `hash_user_context` 忽略 assistant/tool | 哈希不受 assistant/tool 变化影响 |
| TC-SESS-02 | P0 | session_cache | key 包含 tool_config 指纹 | 同语义配置同 key，配置变化 key 变化 |
| TC-SESS-03 | P0 | session_cache | LRU 淘汰 | 超限后旧项淘汰，`evict_total` 增加 |
| TC-SESS-04 | P0 | session_cache | TTL 过期 | 读取 miss，`expire_total` 增加 |
| TC-SCHEMA-01 | P1 | openai_schema | 多类型 content flatten | 文本合并，图片/音频占位 |
| TC-SCHEMA-02 | P1 | anthropic_schema | tool_use/tool_result flatten | 生成可读文本片段 |
| TC-SCHEMA-03 | P1 | anthropic_schema | `anthropic_to_internal_messages` | system + messages 正确映射 |
| TC-SCHEMA-04 | P1 | anthropic_schema | `affinity_key_for_anthropic` 优先级 | `metadata.user_id` 优先，fallback 为 hash 前缀 |

## 4. 测试文件落地
- 既有：`tests/test_tool_call_bridge.py`
- 新增：
  - `tests/test_auth_concurrency.py`
  - `tests/test_session_cache_tooling.py`
  - `tests/test_schema_normalization.py`

## 5. 执行步骤
1. 定点执行新增测试文件。
2. 全量执行 `tests/` 下 `test_*.py`。
3. 汇总通过率与失败项（若失败，给出定位与修复建议）。

## 6. 执行命令
```bash
python3 -m unittest tests/test_auth_concurrency.py
python3 -m unittest tests/test_session_cache_tooling.py
python3 -m unittest tests/test_schema_normalization.py
python3 -m unittest tests/test_tool_call_bridge.py
python3 -m unittest discover -s tests -p "test_*.py"
```