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 }

通用响应结构

// 成功
{ 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

请求:

{
  "code": "wx.login() 返回的 code"
}

响应:

{
  "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

响应:

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

2.2 更新个人信息

PATCH /api/user/profile

请求:

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

---

3. 错题模块（核心）

3.1 创建错题

POST /api/error-items

请求:

{
  "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": ""
}

响应:

{
  "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

响应:

{
  "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

响应:

{
  "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

请求:

{
  "imageUrl": "https://storage.example.com/errors/abc.png"
}

响应:

{
  "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

响应:

{
  "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

响应:

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

5.2 获取学科知识点树

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

响应:

{
  "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

响应:

{
  "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 测试

# 微信登录
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 | 基于: 模块设计 | 最后更新: 2026-05-26