jdShopServer v1.0.0

注册新用户。注册后自动获得 "user" 角色。

请求体 (JSON)

请求示例

{"username":"testuser","password":"test123","nickname":"测试用户","email":"test@example.com"}

成功响应

HTTP 200
{"code":0,"message":"success","data":{"id":2,"username":"testuser","nickname":"测试用户"}}

错误响应

// 用户名已存在
HTTP 409  {"code":10005,"message":"用户名已被占用","data":null}

// 参数校验失败
HTTP 400  {"code":10001,"message":"用户名长度须为3-32字符","data":null}

登录，返回 JWT token 对。Access Token 有效期 2 小时，Refresh Token 有效期 30 天。

请求体 (JSON)

请求示例

{"username":"admin","password":"your-password"}

成功响应

HTTP 200
{"code":0,"message":"success","data":{
  "access_token":"eyJhbGciOi...",       // JWT, 2h 有效期
  "refresh_token":"C33IPlK98wiuA...",   // 刷新 Token, 30d 有效期
  "expires_in":7200,                     // Access Token 有效秒数
  "user":{"id":1,"username":"admin","nickname":"管理员","roles":["admin"]}
}}

错误响应

// 用户名或密码错误
HTTP 400  {"code":10001,"message":"用户名或密码错误","data":null}

// 账号已禁用
HTTP 403  {"code":10003,"message":"账号已被禁用","data":null}

// 登录过于频繁（5次/15分钟）
HTTP 403  {"code":10003,"message":"登录尝试过于频繁，请15分钟后再试","data":null}

使用 Refresh Token 换取新的 Token 对。轮转策略：旧 Refresh Token 使用后立即吊销，同时签发新的。如果 Token 被盗，合法用户刷新时会发现旧 Token 已失效，从而触发重新登录并全局吊销。

请求体 (JSON)

请求示例

{"refresh_token":"C33IPlK98wiuA9Ax5xdO..."}

成功响应

HTTP 200
{"code":0,"message":"success","data":{
  "access_token":"eyJhbGciOi...",
  "refresh_token":"新的refresh_token",
  "expires_in":7200
}}

错误响应

// Token 已被吊销（轮转冲突）
HTTP 401  {"code":10002,"message":"Token已失效，请重新登录","data":null}

// Token 已过期
HTTP 401  {"code":10002,"message":"Token已过期，请重新登录","data":null}

获取已发布公告列表。客户端启动后拉取展示。

Query 参数

请求示例

GET /api/v1/announcements
GET /api/v1/announcements?level=warning&page=1&page_size=10

成功响应

HTTP 200
{"code":0,"message":"success","data":{
  "items":[{
    "id":1,"title":"系统维护通知","content":"7月10日进行系统维护",
    "level":"warning","is_published":1,
    "published_at":"2026-07-04T09:06:34Z","created_by":1,
    "created_at":"2026-07-04 09:06:34","updated_at":"2026-07-04T09:06:34Z"
  }],
  "total":1,"page":1,"page_size":20
}}

检查指定平台是否有新版本。服务端比较 current_version_code 与数据库中的最新 version_code。

Query 参数

请求示例

GET /api/v1/version/latest
GET /api/v1/version/latest?platform=windows¤t_version_code=2026070100

有更新时响应

HTTP 200
{"code":0,"data":{
  "has_update":true,
  "is_force":false,
  "version":{
    "id":1,"platform":"windows","version_code":2026070401,
    "version_name":"v1.0.1","title":"v1.0.1 更新",
    "description":"- 修复若干bug\n- 性能优化",
    "download_url":"https://...", "file_size":52428800,
    "file_hash":"sha256:...", "is_force":0, "is_latest":1
  }
}}

无更新时响应

HTTP 200
{"code":0,"data":{"has_update":false,"is_force":false}}

获取当前登录用户的个人信息、邮箱、状态、角色等。

请求头

Authorization: Bearer <access_token>

成功响应

HTTP 200
{"code":0,"message":"success","data":{
  "id":2,"username":"testuser","email":"test@example.com",
  "nickname":"Test User","avatar_url":null,"status":1,
  "last_login_at":"2026-07-04T09:06:20Z",
  "created_at":"2026-07-04 09:06:16","updated_at":"2026-07-04 09:06:16",
  "roles":["user"]
}}

错误响应

// 未提供 Token
HTTP 401  {"code":10002,"message":"未提供认证凭证","data":null}

// Token 过期
HTTP 401  {"code":10002,"message":"认证凭证无效或已过期","data":null}

修改个人信息。只更新传入的非空字段（不传或传空字符串的字段保持不变）。

请求体 (JSON)

请求示例

{"nickname":"新的昵称","email":"new@example.com"}

成功响应

HTTP 200  → 返回更新后的完整用户信息（结构同 GET /profile）

修改密码。成功后所有 Refresh Token 全部吊销，需要重新登录。

请求体 (JSON)

请求示例

{"old_password":"your-password","new_password":"newPassword456"}

成功响应

HTTP 200  {"code":0,"message":"密码修改成功","data":null}

错误响应

HTTP 400  {"code":10001,"message":"旧密码错误","data":null}

客户端心跳上报（建议每 1 分钟）。服务端记录到 heartbeat_logs 表，并在响应中告知是否有新版本。

请求体 (JSON)

请求示例

{"device_id":"dev-001","platform":"windows","app_version":"v1.0.0"}

成功响应

// 有新版本
HTTP 200
{"code":0,"data":{"has_new_version":true,"latest_version_name":"v1.0.1","is_force_update":false}}

// 无新版本
HTTP 200
{"code":0,"data":{"has_new_version":false,"is_force_update":false}}

按当前用户隔离的 SSE 实时控制流。账号状态、使用期或板块权限变化后立即通知客户端；客户端收到通知后必须通过心跳接口确认最终授权。

事件示例

event: control
data: {"type":"access_changed","issued_at":"2026-07-22T10:00:00Z"}

请使用 curl -N 或流式 HTTP 客户端测试；普通接口测试按钮不适用于长连接。

获取用户列表（分页、搜索、按状态筛选）。需要 admin 角色。

Query 参数

请求示例

GET /api/v1/admin/users
GET /api/v1/admin/users?keyword=admin&status=1&page=1&page_size=10

成功响应

HTTP 200
{"code":0,"data":{"items":[{
  "id":1,"username":"admin","email":null,"nickname":"管理员",
  "avatar_url":null,"status":1,
  "last_login_at":"2026-07-04T09:06:33Z",
  "created_at":"2026-07-04 09:06:16","updated_at":"2026-07-04 09:06:16",
  "RoleNames":"admin"
}],"total":1,"page":1,"page_size":20}}

错误响应

// 非 admin 用户
HTTP 403  {"code":10003,"message":"无操作权限","data":null}

启用或禁用用户。禁用后用户无法登录（返回"账号已被禁用"）。

URL 参数

{id} — 用户 ID

请求体 (JSON)

请求示例

PUT /api/v1/admin/users/2/status
{"status":0}

成功响应

HTTP 200  {"code":0,"message":"状态修改成功","data":null}

错误响应

HTTP 404  {"code":10004,"message":"用户不存在","data":null}

分配用户角色。替换模式：全量替换用户当前所有角色。传空数组清空所有角色。

URL 参数

{id} — 用户 ID

请求体 (JSON)

请求示例

POST /api/v1/admin/users/2/roles
{"role_ids":[2]}

// 提升为管理员
{"role_ids":[1,2]}

// 清空所有角色（用户失去一切权限）
{"role_ids":[]}

成功响应

HTTP 200  {"code":0,"message":"角色分配成功","data":null}

获取所有角色列表，每个角色包含其拥有的权限列表。

成功响应

HTTP 200
{"code":0,"data":[{
  "id":1,"name":"admin","description":"系统管理员",
  "created_at":"2026-07-04 09:06:16",
  "permissions":[
    {"id":1,"code":"user:list","name":"查看用户列表"},
    {"id":2,"code":"user:update","name":"修改用户状态"},
    ...
  ]
},{
  "id":2,"name":"user","description":"普通用户",
  "permissions":[
    {"id":7,"code":"announcement:list","name":"查看公告列表"},
    {"id":13,"code":"version:list","name":"查看版本列表"}
  ]
}]}

创建新角色并设置权限。

请求体 (JSON)

权限 ID 速查

请求示例

{"name":"editor","description":"内容编辑","permission_ids":[8,9,10,11,12]}

成功响应

HTTP 200  → 返回创建的完整角色对象（含权限列表）

更新角色信息或权限（替换模式）。

URL 参数

{id} — 角色 ID

请求体 (JSON) — 所有字段可选

请求示例

PUT /api/v1/admin/roles/3
{"name":"senior-editor","permission_ids":[8,9,10,11,12]}

成功响应

HTTP 200  → 返回更新后的完整角色对象

删除角色（不能删除 admin 角色）。关联的 user_roles 和 role_permissions 自动 CASCADE 删除。

URL 参数

{id} — 角色 ID

成功响应

HTTP 200  {"code":0,"message":"删除成功","data":null}

错误响应

HTTP 403  {"code":10003,"message":"不能删除admin角色","data":null}
HTTP 404  {"code":10004,"message":"角色不存在","data":null}

获取全部 16 个预置权限码。用于角色管理页面的权限选择器。

成功响应

HTTP 200
{"code":0,"data":[
  {"id":1,"code":"user:list","name":"查看用户列表","description":"查看所有注册用户"},
  {"id":2,"code":"user:update","name":"修改用户状态","description":"启用或禁用用户"},
  {"id":3,"code":"user:role:assign","name":"分配用户角色","description":"为用户分配角色"},
  {"id":4,"code":"role:list","name":"查看角色列表","description":"查看所有角色"},
  {"id":5,"code":"role:create","name":"创建角色"},
  {"id":6,"code":"role:update","name":"修改角色"},
  {"id":7,"code":"role:delete","name":"删除角色"},
  {"id":8,"code":"announcement:list","name":"查看公告列表"},
  {"id":9,"code":"announcement:create","name":"创建公告"},
  {"id":10,"code":"announcement:update","name":"修改公告"},
  {"id":11,"code":"announcement:delete","name":"删除公告"},
  {"id":12,"code":"announcement:publish","name":"发布公告","description":"发布或下架公告"},
  {"id":13,"code":"version:list","name":"查看版本列表"},
  {"id":14,"code":"version:create","name":"发布新版本"},
  {"id":15,"code":"version:update","name":"修改版本"},
  {"id":16,"code":"version:delete","name":"删除版本"}
]}

管理端公告列表（含草稿和已下架）。参数与公开接口相同。

Query 参数

创建公告（默认草稿状态，需调用 publish 接口发布）。

请求体 (JSON)

请求示例

{"title":"系统维护通知","content":"将于7月10日凌晨2:00-4:00维护","level":"warning"}

成功响应

HTTP 200  → 返回创建的公告对象（含 id, is_published:0）

编辑公告。所有字段可选，只更新传入的非空字段。

请求体 (JSON) — 所有字段可选

请求示例

PUT /api/v1/admin/announcements/1
{"title":"修改后的标题","level":"critical"}

硬删除公告，不可恢复。

URL 参数

{id} — 公告 ID

错误响应

HTTP 404  {"code":10004,"message":"公告不存在","data":null}

发布公告。将 is_published 设为 1，记录发布时间。公告将出现在公开列表接口中。

下架公告。将 is_published 设为 0，公告从公开列表消失。

版本列表（分页、按平台筛选）。

Query 参数

发布新版本。创建后自动将同平台其他版本的 is_latest 设为 0。

请求体 (JSON)

请求示例

{"platform":"windows","version_code":2026070501,"version_name":"v1.0.2","title":"v1.0.2 更新","description":"- 修复bug\n- 性能优化","is_force":false}

编辑版本信息。所有字段可选。不支持修改 platform 和 version_code。（如果需要，请删除后重新创建。）

请求体 (JSON) — 所有字段可选

删除版本。