# Platform SDK

平台基础设施客户端SDK，提供统一的统计上报、日志记录、链路追踪等功能。

## 安装

SDK作为共享模块使用，通过软链接引用：

```bash
# 在 _shared 目录创建软链接
cd AgentWD/_shared
ln -s ../projects/000-platform/sdk platform
```

## 在项目中使用

### 1. 添加路径

在项目的 `main.py` 开头添加：

```python
import sys
from pathlib import Path

# 添加 _shared 到路径
sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent.parent / "_shared"))

from platform import get_logger, StatsClient, LoggingMiddleware
```

### 2. 日志

```python
from platform import get_logger

logger = get_logger("011-ai-interview")

# 基础日志
logger.info("用户开始面试", user_id=123)
logger.error("面试出错", error=e)

# 审计日志
logger.audit("create", "interview", "123", operator="admin")
```

### 3. AI统计上报

```python
from platform import StatsClient

stats = StatsClient(tenant_id=1, app_code="011-ai-interview")

# 上报AI调用
stats.report_ai_call(
    module_code="interview",
    prompt_name="generate_question",
    model="gpt-4",
    input_tokens=100,
    output_tokens=200,
    latency_ms=1500
)
```

### 4. 链路追踪

```python
from platform import TraceContext, get_trace_id

# 在请求处理中
with TraceContext(tenant_id=1, user_id=100) as ctx:
    print(f"当前trace_id: {ctx.trace_id}")
    # 所有操作共享同一个trace_id
```

### 5. FastAPI中间件

```python
from fastapi import FastAPI
from platform import LoggingMiddleware, TraceMiddleware

app = FastAPI()

# 添加中间件（顺序重要）
app.add_middleware(LoggingMiddleware, app_code="011-ai-interview")
app.add_middleware(TraceMiddleware)
```

### 6. HTTP客户端

```python
from platform import PlatformHttpClient

client = PlatformHttpClient(base_url="https://api.example.com")

# 自动传递trace_id和API Key
response = await client.get("/users/1")
```

### 7. 配置读取

```python
from platform import ConfigReader

config = ConfigReader(tenant_id=1)

# 读取平台配置
app_id = await config.get("wechat", "app_id")

# 读取环境变量
debug = config.get_env("DEBUG", False)
```

## 环境变量

SDK使用以下环境变量：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `PLATFORM_URL` | 平台服务地址 | - |
| `PLATFORM_API_KEY` | 平台API Key | - |

## 更新日志

### v0.1.0

- 初始版本
- 支持日志、统计、链路追踪
- 支持FastAPI中间件
- 支持配置读取