ai_soc_sw/projects/P01_errlens_app/docs/03_接口定义.md

# P01_errlens_app — 接口定义

## 接口规范

### 基础信息
- **Base URL**: `/api`（开发环境通过 Vite Proxy 到 `http://localhost:3000/api`）
- **请求格式**: JSON（文件上传使用 multipart/form-data）
- **响应格式**: `{ code: number, msg: string, data: T | null }`

### 通用响应结构

```typescript
// 成功
{ code: 200, msg: "success", data: { ... } }

// 客户端错误
{ code: 400 | 401 | 403 | 404, msg: "错误描述", data: null }

// 服务端错误
{ code: 500, msg: "服务器内部错误", data: null }
```

### 鉴权

除登录接口外，所有 API 需在 Header 携带 JWT Token：

```
Authorization: Bearer <token>
```

---

## 1. 鉴权模块

### 1.1 微信登录

```
POST /api/auth/login
```

**请求**:
```json
{
  "code": "wx.login() 返回的 code"
}
```

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "token": "jwt_token",
    "user": {
      "id": "uuid",
      "nickname": "微信昵称",
      "avatarUrl": "https://..."
    }
  }
}
```

### 1.2 刷新 Token

```
POST /api/auth/refresh
```

---

## 2. 用户模块

### 2.1 获取个人信息

```
GET /api/user/profile
```

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "nickname": "微信昵称",
    "avatarUrl": "https://...",
    "grade": "初中二年级",
    "subjects": ["数学", "英语"],
    "createdAt": "2026-05-26T00:00:00Z"
  }
}
```

### 2.2 更新个人信息

```
PATCH /api/user/profile
```

**请求**:
```json
{
  "grade": "初中三年级",
  "subjects": ["数学", "英语", "物理"]
}
```

---

## 3. 错题模块（核心）

### 3.1 创建错题

```
POST /api/error-items
```

**请求**:
```json
{
  "imageUrl": "https://storage.example.com/errors/abc.png",
  "thumbnailUrl": "https://storage.example.com/errors/abc_thumb.png",
  "questionText": "已知二次函数 y = x² - 4x + 3，求顶点坐标...",
  "wrongAnswer": "顶点坐标 (2, 1)",
  "correctAnswer": "顶点坐标 (2, -1)",
  "subjectId": 1,
  "knowledgePointIds": [1021],
  "errorType": "knowledge_gap",
  "difficulty": "medium",
  "note": ""
}
```

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "createdAt": "2026-05-26T10:00:00Z"
  }
}
```

### 3.2 查询错题列表

```
GET /api/error-items?page=1&pageSize=20&subjectId=1&errorType=knowledge_gap&keyword=二次函数&sort=createdAt&order=desc
```

**查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认 1 |
| pageSize | int | 否 | 每页条数，默认 20，最大 50 |
| subjectId | int | 否 | 学科筛选 |
| errorType | string | 否 | 错误类型筛选 |
| knowledgePointId | int | 否 | 知识点筛选 |
| keyword | string | 否 | 题目文本搜索 |
| sort | string | 否 | 排序字段: createdAt/updatedAt |
| order | string | 否 | asc/desc，默认 desc |

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": "uuid",
        "thumbnailUrl": "https://...",
        "questionText": "已知二次函数...",
        "subject": { "id": 1, "name": "数学" },
        "knowledgePoints": [
          { "id": 1021, "name": "顶点坐标" }
        ],
        "errorType": "knowledge_gap",
        "difficulty": "medium",
        "createdAt": "2026-05-26T10:00:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 20
  }
}
```

### 3.3 获取错题详情

```
GET /api/error-items/:id
```

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "imageUrl": "https://...",
    "thumbnailUrl": "https://...",
    "questionText": "已知二次函数 y = x² - 4x + 3，求顶点坐标...",
    "wrongAnswer": "顶点坐标 (2, 1)",
    "correctAnswer": "顶点坐标 (2, -1)",
    "subject": { "id": 1, "name": "数学" },
    "knowledgePoints": [
      { "id": 1021, "name": "顶点坐标", "relevance": 100 }
    ],
    "errorType": "knowledge_gap",
    "difficulty": "medium",
    "note": "符号搞反了",
    "aiAnalysis": {
      "diagnosis": "将 x=2 代入时，常数项符号计算错误，应为 3-4=-1 而非 3-4=1。建议回顾二次函数配方法求顶点坐标的完整步骤。",
      "errorType": "knowledge_gap",
      "confidence": 0.92
    },
    "createdAt": "2026-05-26T10:00:00Z",
    "updatedAt": "2026-05-26T10:00:00Z"
  }
}
```

### 3.4 更新错题

```
PATCH /api/error-items/:id
```

**请求**: 同创建参数，所有字段可选。

### 3.5 删除错题

```
DELETE /api/error-items/:id
```

**响应**: `{ code: 200, msg: "success", data: null }`

---

## 4. AI 分析模块

### 4.1 分析错题图片

```
POST /api/ai/analyze
```

**请求**:
```json
{
  "imageUrl": "https://storage.example.com/errors/abc.png"
}
```

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "uuid",
    "status": "completed",
    "result": {
      "questionText": "已知二次函数 y = x² - 4x + 3...",
      "subjectId": 1,
      "subjectName": "数学",
      "knowledgePoints": [
        { "id": 1021, "name": "顶点坐标", "confidence": 0.95 }
      ],
      "errorType": "knowledge_gap",
      "errorTypeConfidence": 0.88,
      "difficulty": "medium",
      "diagnosis": "顶点坐标计算错误，符号混淆..."
    }
  }
}
```

### 4.2 获取薄弱点报告

```
GET /api/ai/report?period=week
```

**查询参数**: `period`: week | month

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "periodStart": "2026-05-19",
    "periodEnd": "2026-05-26",
    "totalErrors": 15,
    "trend": "down",
    "weakPoints": [
      {
        "knowledgePointId": 1021,
        "name": "二次函数顶点坐标",
        "errorCount": 5,
        "weight": 0.85,
        "trend": "up"
      }
    ],
    "errorTypeDistribution": {
      "knowledge_gap": 8,
      "careless": 3,
      "misread": 2,
      "concept_confusion": 2
    }
  }
}
```

---

## 5. 学科模块

### 5.1 获取学科列表

```
GET /api/subjects
```

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": [
    { "id": 1, "name": "数学", "icon": "math" },
    { "id": 2, "name": "英语", "icon": "english" }
  ]
}
```

### 5.2 获取学科知识点树

```
GET /api/subjects/:id/knowledge-points
```

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 10,
      "name": "代数",
      "children": [
        {
          "id": 102,
          "name": "二次函数",
          "children": [
            { "id": 1021, "name": "顶点坐标", "children": [] }
          ]
        }
      ]
    }
  ]
}
```

---

## 6. 文件上传模块

### 6.1 上传图片

```
POST /api/upload/image
Content-Type: multipart/form-data
```

**请求**: `file: binary`

**响应**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "url": "https://storage.example.com/errors/abc.png",
    "thumbnailUrl": "https://storage.example.com/errors/abc_thumb.png",
    "size": 204800
  }
}
```

**约束**:
- 最大 10MB
- 格式: jpg/png/webp
- 自动生成缩略图 (200x200)

---

## 7. 错误码

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 / Token 过期 |
| 403 | 无权访问该资源 |
| 404 | 资源不存在 |
| 413 | 文件过大 |
| 429 | 请求频率超限 |
| 500 | 服务器内部错误 |
| 502 | AI 服务不可用 |

---

## 8. API 测试

```bash
# 微信登录
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"code":"wx_test_code"}'

# 获取错题列表
curl -X GET "http://localhost:3000/api/error-items?page=1&pageSize=20" \
  -H "Authorization: Bearer <token>"

# 创建错题
curl -X POST http://localhost:3000/api/error-items \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://storage.example.com/errors/test.png",
    "questionText": "已知二次函数 y = x² - 4x + 3，求顶点坐标",
    "wrongAnswer": "(2, 1)",
    "subjectId": 1,
    "knowledgePointIds": [1021],
    "errorType": "knowledge_gap",
    "difficulty": "medium"
  }'

# 上传图片
curl -X POST http://localhost:3000/api/upload/image \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/photo.jpg"
```

---

**文档版本**: v0.1.0 | **基于**: [模块设计](../../../docs/02_系统架构/模块设计.md) | **最后更新**: 2026-05-26