# Jointo Tech Stack Skill 架构更新

**日期**: 2026-01-31  
**类型**: 文档更新  
**影响范围**: `.claude/skills/jointo-tech-stack/references/backend.md`

## 背景

在完成 AI Provider 架构简化后（删除 `app/clients/` 目录），需要同步更新 jointo-tech-stack skill 文档，确保架构描述与实际代码一致。

## 变更内容

### 1. 更新架构层次

**之前**：四层架构
```
API 层 → Service 层 → Provider 层 → Client 层
```

**现在**：三层架构
```
API 层 → Service 层 → Provider 层（直接使用 SDK 或 httpx）
```

### 2. 删除 Client 层相关内容

- ❌ 删除项目结构中的 `app/clients/` 目录
- ❌ 删除 `BaseHTTPClient` 相关示例
- ❌ 删除 Client 层测试示例

### 3. 更新架构原则

添加明确的架构原则：

```markdown
**架构原则**：
- ✅ 有官方 SDK：Provider 直接使用 SDK
- ⚠️ 无官方 SDK：Provider 使用 `httpx.AsyncClient`
- ❌ 不要创建独立的 Client 层（避免过度设计）
```

### 4. 更新代码示例

#### 新增 AI 厂商示例

**使用官方 SDK**：
```python
from openai import AsyncOpenAI

class AIHubMixProvider(BaseAIProvider):
    def __init__(self, model_name: str, config: Optional[Dict] = None):
        super().__init__(model_name, config)
        self.client = AsyncOpenAI(
            api_key=settings.AIHUBMIX_API_KEY,
            base_url=settings.AIHUBMIX_BASE_URL
        )
```

**无官方 SDK**：
```python
import httpx

class MyAIProvider(BaseAIProvider):
    def __init__(self, model_name: str, config: Optional[Dict] = None):
        super().__init__(model_name, config)
        self.client = httpx.AsyncClient(
            base_url=settings.MY_AI_BASE_URL,
            headers={"Authorization": f"Bearer {settings.MY_AI_API_KEY}"}
        )
```

#### 更新最佳实践

- ✅ 优先使用官方 SDK
- ✅ Provider 层负责数据适配
- ✅ Service 层负责业务编排

#### 更新错误处理

- 移除 Client 层错误处理示例
- Provider 层统一处理 HTTP 和业务错误

#### 更新测试示例

- 移除 Client 层测试
- Provider 层测试直接测试 SDK 调用
- 使用 Mock 测试 Provider 层

## 修改的文件

- ✅ `.claude/skills/jointo-tech-stack/references/backend.md`
  - 更新 AI Provider 架构章节
  - 删除所有 Client 层引用
  - 更新代码示例和最佳实践

## 验证

```bash
# 搜索是否还有 Client 层引用
grep -r "app/clients" .claude/skills/jointo-tech-stack/
grep -r "BaseHTTPClient" .claude/skills/jointo-tech-stack/
grep -r "Client 层" .claude/skills/jointo-tech-stack/

# 应该只返回架构说明中的"不再使用独立的 Client 层"
```

## 影响

- ✅ Skill 文档与实际代码架构一致
- ✅ 新开发者不会被误导创建 Client 层
- ✅ 明确了"优先使用官方 SDK"的原则

## 相关文档

- [AI Provider 架构简化](./2026-01-31-simplify-ai-provider-architecture.md)
- [AIHubMix Client 重构](./2026-01-30-aihubmix-client-refactor-and-skill-update.md)