# mydreamjob API v0.1 接口清单

> 版本: 0.1.0 | 更新日期: 2026-08-03 | 基础路径: `http://localhost:8080/api/v1`

## 认证模块 `/api/v1/auth`

### 1. 发送短信验证码（Mock）
```
POST /api/v1/auth/sms/send
Query: phone=13800000001, purpose=login
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": { "message": "验证码已发送（Mock）" },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}
```

**限制:**
- 60秒内同一手机号只能发送1次
- 5次错误后锁定5分钟
- Mock 环境验证码**不输出到日志**；本地按 `docs/frontend-integration.md` §3 的受控方式取得（生产禁止查表）

### 2. Mock 登录
```
POST /api/v1/auth/login
Content-Type: application/json
```

**请求体:**
```json
{
  "phone": "13800000001",
  "code": "123456",
  "purpose": "login"
}
```

**响应示例:**
```json
{
  "code": 201,
  "message": "created",
  "data": {
    "userId": 1,
    "phone": "13800000001",
    "nickname": "管理员",
    "role": "ADMIN",
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc...",
    "expiresIn": 86400
  },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}
```

### 3. 当前用户信息
```
GET /api/v1/auth/me
Authorization: Bearer <accessToken>
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "phone": "13800000001",
    "email": "admin@mydreamjob.com",
    "nickname": "管理员",
    "role": "ADMIN",
    "active": true,
    "verified": true,
    "createdAt": "2026-08-03T10:00:00Z"
  },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}
```

## 系统模块 `/api/v1`

### 4. 健康检查
```
GET /api/v1/health
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "status": "UP",
    "components": {
      "db": { "status": "UP", "detail": { "database": "MySQL" } },
      "redis": { "status": "UP" },
      "diskSpace": { "status": "UP" },
      "rabbitmq": { "status": "UP" }
    }
  },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}
```

### 5. 应用信息
```
GET /api/v1/info
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "application": "mydreamjob-server",
    "version": "0.0.1-SNAPSHOT",
    "javaVersion": "17.0.18",
    "uptimeSeconds": 120,
    "springProfile": "dev"
  },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}
```

### 6. 详细健康检查
```
GET /api/v1/health/details
```

返回 Actuator 健康端点的完整信息，包括各依赖服务状态。

## 错误码说明

| 错误码 | 含义 | 场景 |
|--------|------|------|
| 1000 | success | 成功 |
| 1001 | bad request | 请求参数错误 |
| 1002 | internal server error | 服务器内部错误 |
| 2001 | unauthorized | 未认证 |
| 2002 | forbidden | 无权限 |
| 2003 | token expired | Token 已过期 |
| 2004 | token invalid | Token 无效 |
| 2005 | invalid credentials | 凭证错误 |
| 3001 | sms code sent | 验证码已发送 |
| 3002 | sms code expired | 验证码已过期 |
| 3003 | sms code invalid | 验证码错误 |
| 3004 | sms code attempts exceeded | 验证码尝试次数超限 |
| 3005 | sms rate limited | 短信发送频率限制 |
| 4001 | user not found | 用户不存在 |
| 4002 | user already exists | 用户已存在 |
| 9002 | rate limited | 系统限流 |

## Swagger/OpenAPI 文档

```
http://localhost:8080/swagger-ui.html
http://localhost:8080/v3/api-docs
```

### 4. 刷新 Token（S02）

```
POST /api/v1/auth/refresh
Content-Type: application/json

{ "refreshToken": "<refreshToken>" }
```

- 匿名可调用；是否成功取决于 Refresh Token 校验结果。
- **只接受 Refresh Token**；把 Access Token 传进来一律 401。
- 请求体只允许 `refreshToken` 一个字段；Token 不接受 query/path 参数。
- 成功后返回新的 Token 对，**旧 Refresh Token 立即失效**（强制轮换）。
- 已消费/已撤销的 Refresh Token 再次提交 → 401，并撤销该登录会话（重放处置）。
- 失败响应不说明 Token 是"不存在""已消费"还是"已撤销"。

**成功响应:**
```json
{
  "code": 200,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "expiresIn": 86400
  },
  "requestId": "<request-id>"
}
```

### 5. 登出（S02）

```
POST /api/v1/auth/logout
Authorization: Bearer <accessToken>
```

- 必须已认证；**无请求体**。
- 身份与会话来自 Access Token，不接受客户端传入 `userId`/`sessionId`/`refreshToken`。
- 只撤销**当前登录会话**，其他设备会话不受影响。
- 重复登出按幂等处理；成功响应不包含任何 Token。

## Token 与会话模型（S02）

| Token | 用途 | 说明 |
|---|---|---|
| Access Token | 普通业务接口的 `Authorization` 头 | 带 `type=access`，有效期 24h；每次请求都会校验服务端会话状态 |
| Refresh Token | 仅用于 `POST /auth/refresh` | 带 `type=refresh`，有效期 7 天；不落库，数据库只保存其 HMAC-SHA256 摘要 |

- Access 与 Refresh **使用不同签名密钥**，交叉验签必然失败。
- 每次登录创建独立的**登录会话**（`sessionId`）；同一用户可同时存在多个会话。
- 登出只撤销当前会话；账号注销完成、用户禁用会撤销该用户**全部会话**。
- 本版**不再兼容**无 `type` 的旧 Token（所有旧 Token 失效，用户需重新登录一次）。
- Token 原文不进入数据库、日志、审计、URL 或错误响应。

## 已知限制

1. 短信验证码为 Mock 实现，应用日志**不输出验证码**，不发送真实短信；未接入真实供应商时发码返回“服务不可用”
2. 无企业注册/认证流程
3. 无密码修改/重置功能
4. 未提供查看全部登录设备、远程踢出单个设备、Token introspection 等接口
5. RabbitMQ 未实现消息监听器（仅队列定义）
6. Actuator 健康检查部分依赖（Redis/RabbitMQ）在未启动时返回 DOWN