# 职来后端前端联调说明（RC）

## 1. API Base URL

| 环境 | Base URL |
|------|----------|
| 本地开发 | `http://127.0.0.1:8080/api/v1` |
| 生产（示例） | `https://api.mydreamjob.example.com/api/v1` |

所有接口统一前缀 `/api/v1`，OpenAPI 文档：`GET /api/v1/v3/api-docs`（Swagger UI：`/api/v1/swagger-ui/index.html`）。

## 2. 后端启动（Windows）

先启动基础设施容器：
```powershell
cd backend-infra
docker compose up -d
```

然后设置环境变量并启动：
```powershell
cd mydreamjob-server
$env:DB_URL = "jdbc:mysql://127.0.0.1:3307/mydreamjob?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai"
$env:DB_USERNAME = "mydreamjob"
$env:DB_PASSWORD = "<你的数据库密码>"
$env:RABBITMQ_USERNAME = "mydreamjob_dev"
$env:RABBITMQ_PASSWORD = "<你的 RabbitMQ 密码>"
$env:JWT_SECRET = "<至少256位的随机密钥>"
$env:SMS_MOCK_ENABLED = "true"
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

健康检查：`http://127.0.0.1:8080/api/v1/health` 返回 `status: UP`。

## 3. Mock 验证码日志位置

开发环境短信为 Mock，验证码打印在**服务控制台/stdout 日志**中：

```
MOCK SMS CODE: phone=13800000002, purpose=login, code=483920
```

- 运行 `mvn spring-boot:run` → 看终端输出
- 后台运行 → 看重定向的日志文件（如 `logs/mydreamjob.log`）
- 每次发码后取**最新一条** `code=<6位数字>`

## 4. Apifox 导入 OpenAPI

1. 打开 Apifox → 新建项目
2. 左侧「导入数据」→ 选择「OpenAPI/Swagger」
3. 上传 [docs/openapi-rc.json](../docs/openapi-rc.json)（或填 URL `http://127.0.0.1:8080/api/v1/v3/api-docs`）
4. 点击「确认导入」，Apifox 自动生成全部接口、参数、响应模型
5. 在 Apifox 中可直接调试：登录接口获取 token 后，设置「环境变量 `token`」，在接口「Authorization」填 `Bearer {{token}}`

## 5. Token 使用方式

登录成功返回 `accessToken`（有效期 24h）与 `refreshToken`。

```json
{
  "code": 200,
  "data": {
    "userId": 2,
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "expiresIn": 86400,
    "role": "STUDENT"
  }
}
```

**后续请求**：所有需要认证的接口在请求头携带
```
Authorization: Bearer <accessToken>
```

## 3. 请求头

| Header | 必需 | 说明 |
|--------|------|------|
| `Authorization` | 认证接口 | `Bearer <token>` |
| `Content-Type` | POST/PUT/PATCH | `application/json` |
| `X-Request-Id` | 可选 | 全链路追踪 ID，审计日志会记录 |
| `User-Agent` | 可选 | 客户端标识，审计日志会记录 |

**注意**：`X-Request-Id` 和 `User-Agent` 会被写入 audit_logs，联调时建议带自定义值便于排查。

## 4. 分页格式

列表接口统一使用 `page`（从 0 起）和 `size` 参数，返回 `PageResponse` 结构：

```json
{
  "code": 200,
  "data": {
    "items": [ ... ],
    "total": 42,
    "page": 0,
    "size": 20,
    "totalPages": 3
  }
}
```

| 接口 | 默认 size | 最大 size |
|------|-----------|-----------|
| GET /jobs | 20 | 50 |
| GET /applications/me | 20 | 100 |
| GET /company/applications | 20 | 100 |
| GET /jobs/{id}/reviews | 20 | 50 |
| GET /conversations/{id}/messages | 20 | 50 |
| GET /notifications | 20 | 50 |

## 5. 统一响应与错误码

所有接口返回统一 `ApiResponse`：
```json
{ "code": 200, "message": "ok", "data": {...}, "requestId": "...", "timestamp": "..." }
```

| HTTP | 业务 code | 含义 |
|------|-----------|------|
| 401 | 2001 | 未登录 / token 失效 |
| 403 | 2002 | 无角色权限 / 越权 |
| 400 | 1001, 3002-3006, 8004... | 参数错误 |
| 404 | 4001, 5001, 6001, 7001, 8002, 9102, 9104, 9105 | 资源不存在 |
| 409 | 5003, 7003, 8001, 8003, 9101, 9103 | 重复 / 非法状态流转 |
| 500 | 1002, 9001 | 服务器内部错误 |

**前端策略**：优先判断 HTTP 状态码，再读取 `body.code` 显示业务信息。

## 6. 测试账号

| 账号 | 角色 | 说明 |
|------|------|------|
| `13800000002` | STUDENT | 学生，可投递/匹配/查看通知 |
| `13800000003` | COMPANY | 企业，可创建岗位/查看投递/更新状态 |
| `13800000001` | ADMIN | 管理员（预留） |

**登录方式**（开发环境 Mock）：
1. `POST /auth/sms/send?phone=<手机号>` 发送验证码
2. 验证码打印在服务日志：`MOCK SMS CODE: ... code=xxxxxx`
3. `POST /auth/login` 携带 `{phone, code, purpose:"login"}` 获取 token

## 7. 典型联调流程

```
学生端：
  发码 → 登录 → GET /jobs → GET /jobs/{id}/match → POST /applications
        → GET /notifications → POST /notifications/{id}/read

企业端：
  发码 → 登录 → POST /companies/me → POST /jobs → PATCH /jobs/{id}/status
        → GET /company/applications?jobId= → PATCH /applications/{id}/status
```

## 8. 投递接口与评价/对比补充

### 8.1 投递接口（正确写法）

创建投递为 **`POST /applications`**，请求体 `{"jobId": 123}`（不要写成 `POST /jobs/{jobId}/applications`）：

```json
{ "jobId": 123 }
```

### 8.2 岗位八维评价

`POST /jobs/{jobId}/reviews` 可附加可选 `dimensionScores`（八个固定维度，值 1-5，可稀疏提交）：

```json
{ "rating": 4, "content": "岗位信息真实", "tags": ["团队氛围"],
  "dimensionScores": { "AUTHENTICITY": 5, "TEAM_ATMOSPHERE": 4 } }
```

- 不传 `dimensionScores` 时旧接口完全兼容；
- 评价列表/详情返回 `dimensionScores`；
- 汇总 `GET /jobs/{jobId}/reviews/summary` 返回 `dimensionSummary`（`INSUFFICIENT` sampleCount<3 / `SUFFICIENT` >=3）；
- 详情见 `docs/job-review-api.md`。

### 8.3 岗位对比（公开）

`GET /jobs/compare?ids=1,2,3`（无需登录，2-3 个公开岗位），返回公开字段与公开评分。