API 文档

欢迎使用进北资源共享平台 API v1.0。本篇文档详细介绍了所有可用的 API 接口、请求参数和响应格式。

基础 URL

所有 API 请求的基础 URL 为：

https://jcbx.nstu.top

认证方式

大部分需要用户权限的接口，都需要在 HTTP Header 中携带 Bearer Token。
Authorization: Bearer <YOUR_TOKEN>

外部 API 接口需要携带 API Key。
X-API-KEY: <YOUR_API_KEY>

1. 认证 (Authentication)

1.1 用户注册

POST /api/auth/register

使用邀请码创建一个新用户账号。

请求 Body:

{
  "username": "testuser",
  "password": "a_strong_password",
  "inviteCode": "JCBX-NSTR-2025"
}

成功响应 (201 Created):

{
  "message": "Registration successful",
  "userId": "..."
}

1.2 用户登录

POST /api/auth/login

使用用户名和密码登录，获取会话 Token。

请求 Body:

{
  "username": "testuser",
  "password": "a_strong_password"
}

成功响应 (200 OK):

{
  "message": "Login successful",
  "token": "a_long_session_token..."
}

2. 用户 (Users)

2.1 获取当前用户信息

GET /api/users/me

获取当前登录用户的详细信息。 需要用户 Token

成功响应 (200 OK):

{
  "id": "...",
  "username": "testuser",
  "roles": ["USER"],
  "badges": [],
  "createdAt": "2023-10-27T10:00:00.000Z",
  "invitationCodes": ["CODE1", "CODE2", "CODE3"]
}

3. 管理后台 (Admin)

3.1 管理员登录

POST /api/admin/login

使用全局后台密码登录，获取管理员 Token。

请求 Body:

{
  "password": "jcBxsHarE-2025@adMin.nsTu.tOp"
}

成功响应 (200 OK):

{
  "message": "Admin login successful",
  "token": "admin-a_long_session_token..."
}

3.2 封禁用户

POST /api/admin/users/ban

封禁指定用户。 需要 Staff Token

请求 Body:

{
  "targetUserId": "user_id_to_ban",
  "reason": "发布不当内容",
  "duration": 86400
}

成功响应 (200 OK):

{
  "message": "User user_id_to_ban has been banned by testuser. Reason: 发布不当内容"
}

3.3 生成 API Key

POST /api/admin/apikeys/generate

为指定用户生成一个 API Key。 需要 Admin Token

请求 Body:

{
  "targetUserId": "user_id_for_api_key",
  "permissions": ["read_only", "read_posts"]
}

成功响应 (200 OK):

{
  "message": "API Key generated successfully",
  "apiKey": "jcbx_key_..."
}

4. 外部 API (API Key)

4.1 获取最新文章

GET /api/external/latest-posts

使用 API Key 获取最新的文章列表。 需要 API Key

成功响应 (200 OK):

{
  "message": "API Key is valid for user ...",
  "latestPosts": [
    { "id": 1, "title": "欢迎来到进北资源共享平台" }
  ]
}