api-server/docs/ai-runtime-user-api.md

# AI Runtime 用户 API 接入文档

## 概述

本文档描述 AI Runtime 对外暴露的用户面 REST API。所有端点均需 Bearer Token 认证（`Authorization: Bearer <token>`），用户只能操作自己的资源。

Base URL: `/ai`

---

## 1. Job 管理

### 1.1 创建分析 Job

```
POST /ai/jobs
```

**Request Body:**
```json
{
  "jobType": "learning_state_analysis | weak_point_analysis | next_action_planning | quiz_generation | flashcard_generation",
  "targetType": "user | material | knowledge_base",
  "targetId": "string",
  "idempotencyKey": "string (optional)",
  "apiKeyMode": "platform_key | user_deepseek_key (optional, default from settings)",
  "credentialId": "string (optional, required for user_deepseek_key)",
  "questionCount": 5,
  "difficultyLevel": "easy | medium | hard",
  "questionTypes": ["choice", "judge"],
  "cardCount": 5,
  "knowledgePointIds": ["kp1", "kp2"]
}
```

**Response 201:**
```json
{ "jobId": "clx...", "status": "pending", "createdAt": "2026-...", "planId": "clx... (quiz/flashcard only)" }
```

**Error Codes:** `AI_ANALYSIS_DISABLED`, `INVALID_JOB_TYPE`, `INVALID_TARGET_TYPE`, `CREDENTIAL_REQUIRED`, `CREDENTIAL_NOT_FOUND`

### 1.2 查询 Job 列表

```
GET /ai/jobs?status=pending&take=20
```

**Response 200:**
```json
[
  { "id": "clx...", "jobType": "learning_state_analysis", "targetType": "material", "targetId": "m1",
    "status": "pending", "priority": 50, "errorCode": null, "cancelRequestedAt": null,
    "startedAt": null, "finishedAt": null, "createdAt": "2026-..." }
]
```

### 1.3 查询单个 Job

```
GET /ai/jobs/:jobId
```

**Response 200:**
```json
{
  "id": "clx...", "jobType": "...", "targetType": "...", "targetId": "...",
  "status": "succeeded", "priority": 50, "snapshotId": "snap-...",
  "attemptNo": 0, "retryCount": 0, "maxRetryCount": 3,
  "errorCode": null, "errorMessage": null,
  "cancelRequestedAt": null, "cancelledAt": null,
  "startedAt": "2026-...", "finishedAt": "2026-...",
  "createdAt": "2026-...", "updatedAt": "2026-..."
}
```

### 1.4 取消 Job

```
POST /ai/jobs/:jobId/cancel
```

**Response 200:** `{ "jobId": "clx...", "status": "cancelled | cancel_requested" }`

**Error Codes:** `JOB_NOT_FOUND`, `JOB_CANNOT_CANCEL`

---

## 2. 分析结果查询

### 2.1 查询分析列表

```
GET /ai/analyses?targetType=material&targetId=m1&take=20
```

**Response 200:**
```json
[
  { "id": "clx...", "targetType": "material", "targetId": "m1",
    "learningState": "mastered", "riskLevel": "low", "confidence": 0.85,
    "summary": "...", "createdAt": "2026-..." }
]
```

### 2.2 查询单个分析

```
GET /ai/analyses/:id
```

**Response 200:**
```json
{
  "id": "clx...", "userId": "...", "jobId": "...", "snapshotId": "...",
  "targetType": "material", "targetId": "m1",
  "learningState": "mastered", "summary": "...", "riskLevel": "low",
  "confidence": 0.85, "evidence": ["fact1", "fact2"],
  "nextActionIds": ["..."],
  "promptVersion": "learning_state_v1", "schemaVersion": "analysis_output_v1",
  "createdAt": "2026-...", "updatedAt": "2026-..."
}
```

### 2.3 触发重新分析

```
POST /ai/reanalyze
```

**Request Body:** `{ "targetType": "material", "targetId": "m1" }`

**Response 201:** `{ "jobId": "clx...", "status": "pending", "createdAt": "2026-..." }`

---

## 3. 建议 / 弱项查询

### 3.1 查询建议列表

```
GET /ai/recommendations?targetType=material&targetId=m1&status=active&take=20
```

**Response 200:**
```json
[
  { "id": "clx...", "actionType": "review", "targetType": "material", "targetId": "m1",
    "title": "...", "reason": "...", "priority": 10, "estimatedMinutes": 15,
    "deviceSuitability": "phone", "status": "active", "createdAt": "2026-..." }
]
```

### 3.2 查询弱项列表

```
GET /ai/weak-points?targetType=material&targetId=m1&status=active&take=20
```

**Response 200:**
```json
[
  { "id": "clx...", "knowledgePointId": "kp1", "title": "Grammar: Tense",
    "reason": "...", "confidence": 0.9, "evidence": ["..."],
    "status": "active", "targetType": "material", "targetId": "m1", "createdAt": "2026-..." }
]
```

---

## 4. 题目查询

### 4.1 查询题目列表

```
GET /ai/quizzes?knowledgeBaseId=kb1&status=active&take=20
```

**Response 200:**
```json
[
  { "id": "clx...", "knowledgeBaseId": "kb1", "title": "...", "questionCount": 10,
    "sourceType": "ai", "status": "active", "createdAt": "2026-..." }
]
```

### 4.2 查询单个 Quiz

```
GET /ai/quizzes/:quizId
```

**Response 200:**
```json
{
  "id": "clx...", "knowledgeBaseId": "kb1", "title": "...", "description": "...",
  "questionCount": 10, "sourceType": "ai", "sourceId": "job-...",
  "status": "active", "createdAt": "2026-...", "updatedAt": "2026-..."
}
```

### 4.3 查询 Quiz 题目详情

```
GET /ai/quizzes/:quizId/questions
```

**Response 200:**
```json
[
  { "id": "clx...", "type": "choice", "stem": "...", "options": ["A", "B", "C", "D"],
    "answer": "A", "explanation": "...", "sourceBlockIds": ["..."], "orderIndex": 0 }
]
```

### 4.4 发布 Quiz (draft → active)

```
POST /ai/quizzes/:quizId/publish
```

**Response 200:** `{ "quizId": "clx...", "status": "active" }`

**Error Codes:** `QUIZ_NOT_FOUND`, `QUIZ_NOT_READY`

---

## 5. 卡片查询

### 5.1 查询卡片列表

```
GET /ai/flashcards?knowledgePointId=kp1&status=active&take=20
```

**Response 200:**
```json
[
  { "id": "clx...", "front": "...", "back": "...", "hint": "...",
    "difficultyLevel": "medium", "knowledgePointId": "kp1",
    "sourceType": "ai", "status": "active", "createdAt": "2026-..." }
]
```

### 5.2 查询单个卡片

```
GET /ai/flashcards/:cardId
```

**Response 200:**
```json
{
  "id": "clx...", "front": "...", "back": "...", "hint": "...",
  "difficultyLevel": "medium", "knowledgePointId": "kp1",
  "sourceBlockIds": ["..."],
  "sourceType": "ai", "sourceId": "job-...", "generatedByJobId": "job-...",
  "status": "active", "createdAt": "2026-...", "updatedAt": "2026-..."
}
```

### 5.3 发布卡片 (draft → active)

```
POST /ai/flashcards/:cardId/publish
```

**Response 200:** `{ "cardId": "clx...", "status": "active" }`

**Error Codes:** `FLASHCARD_NOT_FOUND`, `FLASHCARD_NOT_DRAFT`

---

## 6. 反馈

### 6.1 通用反馈

```
POST /ai/feedback
```

**Request Body:** `{ "category": "bug|feature|ux|other", "content": "...", "email": "optional", "deviceInfo": {} }`

**Response 201:** `{ "id": "clx...", "status": "open", "createdAt": "2026-..." }`

### 6.2 AI 产出物反馈

```
POST /ai/artifacts/:type/:id/feedback
```

**Path Params:** `type` = `analysis | quiz | flashcard`

**Request Body:** `{ "feedbackType": "correct|incorrect|helpful|not_helpful|...", "reason": "optional" }`

**Response 201:** `{ "id": "clx...", "feedbackType": "correct", "createdAt": "2026-..." }`

**Error Codes:** `ARTIFACT_NOT_FOUND`

---

## 错误码汇总

| 错误码 | HTTP Status | 说明 |
|--------|------------|------|
| `AI_ANALYSIS_DISABLED` | 400 | 用户关闭了 AI 分析 |
| `INVALID_JOB_TYPE` | 400 | 不支持的 jobType |
| `INVALID_TARGET_TYPE` | 400 | targetType 不匹配 jobType 要求 |
| `CREDENTIAL_REQUIRED` | 400 | user_deepseek_key 模式需提供 credentialId |
| `CREDENTIAL_NOT_FOUND` | 404 | 凭证不存在或未激活 |
| `JOB_NOT_FOUND` | 404 | Job 不存在或不属于用户 |
| `JOB_CANNOT_CANCEL` | 400 | Job 已处于终态，无法取消 |
| `QUIZ_NOT_FOUND` | 404 | Quiz 不存在或不属于用户 |
| `QUIZ_NOT_READY` | 400 | Quiz 非 ready 状态，无法发布 |
| `FLASHCARD_NOT_FOUND` | 404 | 卡片不存在或不属于用户 |
| `FLASHCARD_NOT_DRAFT` | 400 | 卡片非 draft 状态，无法发布 |
| `ANALYSIS_NOT_FOUND` | 404 | 分析结果不存在 |
| `ARTIFACT_NOT_FOUND` | 404 | 产出物不存在或不属于用户 |

## 认证

所有端点使用 `Authorization: Bearer <JWT>` 认证，用户身份从 JWT payload 提取。内部端点（`/internal/runtime/*`）使用 Service Token 认证，不对外暴露。