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

P01_errlens_app - 接口定义

接口规范

基础信息

• Base URL: /api（开发环境通过 Vite Proxy 代理到 http://localhost:3000/api）
• 请求格式: JSON
• 响应格式: Envelope Pattern { code, msg, data }

通用响应结构

// 成功响应
{
  code: 200,
  msg: "success",
  data: { ... }
}

// 错误响应
{
  code: 400 | 401 | 403 | 404 | 500,
  msg: "错误信息",
  data: null
}

---

用户模块

1. 用户登录

POST /api/auth/login

请求参数：

{
  "email": "string",
  "password": "string"
}

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "token": "jwt_token_here",
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "nickname": "用户名"
    }
  }
}

---

2. 用户注册

POST /api/auth/register

请求参数：

{
  "email": "string",
  "password": "string",
  "nickname": "string"
}

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "nickname": "用户名"
  }
}

---

3. 获取用户信息

GET /api/users/profile

请求头：

Authorization: Bearer <token>

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "nickname": "用户名",
    "avatar": "https://...",
    "createdAt": "2026-05-22T00:00:00Z"
  }
}

---

代码分析模块

1. 上传代码分析

POST /api/analyze

请求头：

Authorization: Bearer <token>

请求参数：

{
  "code": "string",
  "language": "javascript | python | typescript | ..."
}

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "uuid",
    "status": "completed",
    "results": [
      {
        "line": 10,
        "column": 5,
        "severity": "error",
        "message": "缺少分号",
        "suggestion": "在行末添加分号"
      }
    ]
  }
}

---

2. 获取分析结果

GET /api/analyze/:taskId

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "uuid",
    "status": "completed",
    "results": [...]
  }
}

---

3. 获取历史记录

GET /api/analyze/history

查询参数：

page: number (default: 1)
pageSize: number (default: 20)

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": "uuid",
        "codeSnippet": "function hello() {...}",
        "language": "javascript",
        "resultCount": 3,
        "createdAt": "2026-05-22T00:00:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

---

文件上传模块

1. 上传文件

POST /api/upload

请求头：

Authorization: Bearer <token>
Content-Type: multipart/form-data

请求参数：

file: binary

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "url": "https://storage.example.com/files/xxx.png",
    "filename": "xxx.png",
    "size": 1024
  }
}

---

错误码定义

错误码	说明
200	成功
400	请求参数错误
401	未授权 / Token 过期
403	权限不足
404	资源不存在
500	服务器内部错误

---

API 测试命令

开发环境测试

# 登录接口
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"123456"}'

# 获取用户信息
curl -X GET http://localhost:3000/api/users/profile \
  -H "Authorization: Bearer <token>"

# 代码分析
curl -X POST http://localhost:3000/api/analyze \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"code":"console.log(1)","language":"javascript"}'

---

文档版本：v1.0.0 最后更新：2026-05-22