轻松聘AI开发

5.7 KiB

Raw Blame History

职来后端前端联调说明（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）

先启动基础设施容器：

cd backend-infra
docker compose up -d

然后设置环境变量并启动：

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

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

5. Token 使用方式

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

{
  "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 结构：

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

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

POST /auth/sms/send?phone=<手机号> 发送验证码
验证码打印在服务日志：MOCK SMS CODE: ... code=xxxxxx
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）：

{ "jobId": 123 }

8.2 岗位八维评价

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

{ "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 个公开岗位），返回公开字段与公开评分。

5.7 KiB Raw Blame History