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 }`

### 通用响应结构

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

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

---

## 用户模块

### 1. 用户登录

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

**请求参数**：
```json
{
  "email": "string",
  "password": "string"
}
```

**响应示例**：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "token": "jwt_token_here",
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "nickname": "用户名"
    }
  }
}
```

---

### 2. 用户注册

```
POST /api/auth/register
```

**请求参数**：
```json
{
  "email": "string",
  "password": "string",
  "nickname": "string"
}
```

**响应示例**：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "nickname": "用户名"
  }
}
```

---

### 3. 获取用户信息

```
GET /api/users/profile
```

**请求头**：
```
Authorization: Bearer <token>
```

**响应示例**：
```json
{
  "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>
```

**请求参数**：
```json
{
  "code": "string",
  "language": "javascript | python | typescript | ..."
}
```

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

---

### 2. 获取分析结果

```
GET /api/analyze/:taskId
```

**响应示例**：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "uuid",
    "status": "completed",
    "results": [...]
  }
}
```

---

### 3. 获取历史记录

```
GET /api/analyze/history
```

**查询参数**：
```
page: number (default: 1)
pageSize: number (default: 20)
```

**响应示例**：
```json
{
  "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
```

**响应示例**：
```json
{
  "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 测试命令

### 开发环境测试

```bash
# 登录接口
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