# Cyrene v2 — REST API 参考

> **Base URL**: `http://localhost:8080/api/v1`  
> **认证方式**: Bearer Token (JWT)

---

## 认证

所有认证端点无需 Token。受保护端点需在 Header 中携带 `Authorization: Bearer <token>`。

### `POST /auth/register`

注册新用户。

```bash
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"myuser","password":"mypassword"}'
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | ✅ | 用户名，不可重复 |
| password | string | ✅ | 密码，最少 6 位 |

**成功响应** (201)
```json
{"token": "eyJhbGciOiJIUzI1NiIs..."}
```

**错误**
| 状态码 | 说明 |
|--------|------|
| 400 | 用户名已存在 / 密码太短 |

---

### `POST /auth/login`

登录获取 Token。

```bash
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin12345"}'
```

**成功响应** (200)
```json
{"token": "eyJhbGciOiJIUzI1NiIs..."}
```

**错误**
| 状态码 | 说明 |
|--------|------|
| 401 | 用户名或密码错误 |

---

### `GET /health`

健康检查（无需认证）。

```bash
curl http://localhost:8080/api/v1/health
```

**响应** (200)
```json
{"status":"ok","service":"cyrene-gateway","version":"2.0.0-dev"}
```

---

## 会话管理

### `POST /sessions`

创建新会话。

```bash
curl -X POST http://localhost:8080/api/v1/sessions \
  -H 'Authorization: Bearer <token>'
```

**响应** (201)
```json
{"session_id": "a1b2c3d4e5f6"}
```

### `GET /sessions`

获取会话列表。

**响应** (200)
```json
{"sessions": []}
```

### `DELETE /sessions/:id`

删除指定会话。

**响应** (204) — 无内容

---

## 记忆管理

### `GET /memory`

获取当前用户的记忆列表。

```bash
curl http://localhost:8080/api/v1/memory \
  -H 'Authorization: Bearer <token>'
```

**响应** (200)
```json
{
  "data": [{
    "id": "uuid",
    "user_id": "admin",
    "content": "喜欢咖啡",
    "summary": "喜欢咖啡",
    "keywords": ["喜欢", "咖啡"],
    "category": "preference",
    "priority": 0.8
  }]
}
```

### `POST /memory`

创建新记忆。支持自动去重。

```bash
curl -X POST http://localhost:8080/api/v1/memory \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"用户喜欢喝咖啡","category":"preference","priority":0.8}'
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| content | string | ✅ | 记忆内容 |
| category | string | | 分类：fact/preference/event/plan (默认 fact) |
| priority | float | | 优先级 0.0-1.0 (默认 0.5) |

**响应** (201) — 返回创建的完整记忆对象

### `GET /memory/:id`

获取单条记忆。

**错误** — 404 Not Found

### `DELETE /memory/:id`

删除单条记忆。

**响应** (204) — 无内容

### `GET /memory/search?q=关键词`

搜索记忆（关键词匹配）。

```bash
curl "http://localhost:8080/api/v1/memory/search?q=咖啡" \
  -H 'Authorization: Bearer <token>'
```

**响应** (200) — 返回匹配的记忆列表

---

## 语音服务

### `POST /voice/stt`

语音识别（Speech to Text）。

```bash
curl -X POST http://localhost:8080/api/v1/voice/stt \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"audio_data":"base64..."}'
```

**响应** (200)
```json
{"text": "你好世界"}
```

> ⚠️ 当前为 stub 实现。生产环境需配置 DashScope API Key。

### `POST /voice/tts`

文字转语音（Text to Speech）。

```bash
curl -X POST http://localhost:8080/api/v1/voice/tts \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"text":"你好","voice":"zh-CN-XiaoxiaoNeural"}'
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| text | string | — | 要转换的文本 |
| voice | string | zh-CN-XiaoxiaoNeural | 语音角色 |

**响应** (200)
```json
{"audio_size": 0}
```

---

## 管理面板

### `GET /admin/dashboard`

获取系统状态（需 admin 角色）。

```bash
curl http://localhost:8080/api/v1/admin/dashboard \
  -H 'Authorization: Bearer <admin_token>'
```

**响应** (200)
```json
{
  "dashboard": {
    "status": "running",
    "version": "2.0.0-dev",
    "uptime_sec": 3600,
    "services": {
      "memory": true,
      "voice": true,
      "ai_core": true
    }
  }
}
```

---

## WebSocket

### `GET /ws/chat?token=<jwt>`

升级到 WebSocket 连接。详见 [WebSocket 协议文档](websocket.md)。

---

## 错误码总览

| 状态码 | 含义 | 常见场景 |
|--------|------|---------|
| 200 | 成功 | GET/PUT 请求 |
| 201 | 已创建 | POST 成功 |
| 204 | 无内容 | DELETE 成功 |
| 400 | 请求错误 | 参数缺失/格式错误 |
| 401 | 未认证 | Token 无效或过期 |
| 403 | 无权限 | 非 admin 访问管理端点 |
| 404 | 未找到 | 资源不存在 |
| 405 | 方法不允许 | 用了错误的 HTTP 方法 |
| 429 | 限流 | 请求频率过高 |
| 500 | 服务器错误 | 内部异常 |
| 503 | 服务不可用 | 依赖服务未就绪 |

**错误响应格式**
```json
{"error": "错误描述"}
```