API 文档

⚠ 多项目说明(重要): 系统按「项目」隔离账号,同一账号只能登录其所属项目的客户端,不同项目可存在同名账号。
因此所有客户端接口(登录、心跳、自助改密)的地址都必须带上项目 ID: /api/p/<project_id>/user/...。
项目 ID 在后台「管理项目」中查看。客户端打包时把地址里的 <project_id> 写死成对应项目即可。
公告接口 /api/user/announcement 为全局公告,不带项目 ID。

所有 API 返回统一结构,通过 code 字段判断业务结果。

{
  "code": 200,        // 200 成功 / 400 参数错误 / 401 未授权 / 403 禁止 / 404 未找到 / 500 服务器错误
  "message": "success",
  "data": {}          // 实际数据,可能为对象、数组或 null
}

登录态: 管理员相关接口需要先调用登录接口,登录态通过 Cookie/Session 自动保持。

管理员登录,默认账号 xialaosan001 / qq6241515.A

参数	类型	必填	说明
username	string	是	管理员账号
password	string	是	管理员密码

管理员退出登录(需登录态)

管理员修改自己的密码(需登录态)。需要原密码验证身份,新旧密码不能相同。 修改成功后会清除登录态,前端需引导重新登录。

参数	类型	必填	说明
old_password	string	是	当前密码
new_password	string	是	新密码,不能与原密码相同

{
  "code": 200,
  "message": "密码修改成功, 请使用新密码重新登录",
  "data": { "username": "xialaosan001", "require_relogin": true }
}

code	说明
400	参数缺失 / 新旧密码相同
401	未登录 / 原密码错误

获取系统公告(管理员视角,包含更新时间和更新人)

{
  "code": 200, "message": "success",
  "data": {
    "content": "系统将于今晚 23:00 维护...",
    "updated_at": "2025-05-20 12:00:00",
    "updated_by": "xialaosan001"
  }
}

设置系统公告(需登录态,公告为全局一条)。公告会随登录接口 /api/p/<project_id>/user/login 返回给客户端, 也可通过 /api/user/announcement 单独拉取。传空字符串可清空公告。

参数	类型	必填	说明
content	string	是	公告内容,最长 5000 字符,传 "" 表示清空

{
  "code": 200, "message": "公告已更新",
  "data": {
    "content": "系统将于今晚 23:00 维护...",
    "updated_at": "2025-05-20 12:00:00",
    "updated_by": "xialaosan001"
  }
}

获取所有项目(含每个项目下的用户数)。创建用户、各列表的项目筛选都依赖这里返回的项目 ID。

{
  "code": 200, "message": "success",
  "data": {
    "list": [
      { "id": 1, "name": "默认项目", "remark": "",
        "user_count": 12, "created_at": "2026-06-05 21:00:00" }
    ],
    "total": 1
  }
}

新增项目。项目名称唯一。

参数	类型	必填	说明
name	string	是	项目名称(唯一, ≤100 字符)
remark	string	否	备注(≤255 字符)

{
  "code": 200, "message": "项目创建成功",
  "data": { "id": 2, "name": "项目A", "remark": "", "user_count": 0 }
}

删除项目(级联,不可恢复)。 会在同一事务里依次删除:该项目下所有登录/心跳记录 → 所有用户 → 项目本身。任一步失败则整体回滚。

{
  "code": 200, "message": "项目 \"项目A\" 已删除",
  "data": {
    "id": 2, "name": "项目A",
    "deleted_users": 12, "deleted_records": 340
  }
}

创建新用户。必须指定所属项目 project_id;账号在所属项目内唯一(不同项目可同名)。有效期通过天数指定,后端根据当前时间自动计算到期时间。

参数	类型	必填	说明
project_id	int	是	所属项目 ID
username	string	是	用户账号(项目内唯一)
password	string	是	用户密码
days	int	是	有效天数, 1 ~ 36500

{
  "code": 200,
  "message": "用户创建成功",
  "data": {
    "id": 1,
    "project_id": 1,
    "username": "test",
    "expire_time": "2026-07-05 14:30:00",
    "days": 30
  }
}

获取用户列表(分页 + 筛选)。前端按选中项目传 project_id 过滤。

参数	类型	必填	说明
project_id	int	否	按项目过滤;不传则查所有项目
keyword	string	否	账号模糊搜索
status	string	否	all / active(默认, 未过期) / expired
ban_status	string	否	all(默认) / normal(正常) / banned(已封禁)
page	int	否	页码,默认 1
page_size	int	否	每页数量,默认 10,最大 100

{
  "code": 200, "message": "success",
  "data": {
    "list": [
      {
        "id": 1, "project_id": 1, "username": "test",
        "expire_time": "2026-07-05 14:30:00",
        "created_at": "2026-06-05 14:30:00",
        "is_expired": false, "status": "未过期",
        "is_banned": false, "ban_reason": "", "banned_at": "",
        "remaining_days": 30
      }
    ],
    "total": 100, "page": 1,
    "page_size": 10, "total_pages": 10
  }
}

用户续期。规则:用户未过期时,在原 expire_time 上加天数;用户已过期时,从当前时间开始加天数。

参数	类型	必填	说明
days	int	是	续期天数, 1 ~ 36500

{
  "code": 200, "message": "续期成功 (+30 天)",
  "data": {
    "id": 1, "username": "test",
    "old_expire_time": "2025-06-15 14:30:00",
    "new_expire_time": "2025-07-15 14:30:00",
    "added_days": 30
  }
}

管理员重置用户密码。无需提供原密码,直接强制设置新密码。

参数	类型	必填	说明
password	string	是	新密码,1-255 字符,不能与原密码相同

{
  "code": 200, "message": "密码重置成功",
  "data": { "id": 1, "username": "test" }
}

code	说明
400	密码为空 / 新密码与原密码相同
404	用户不存在

更新用户密码或直接设置到期时间(至少传一个字段)

参数	类型	必填	说明
password	string	否	新密码
expire_time	string	否	新到期时间, 格式 YYYY-MM-DD HH:MM:SS

封禁 / 解封用户(不删除数据,可逆,推荐用它替代删除来禁用账号)。 封禁后:该账号无法登录;心跳接口会返回 is_banned: true 及原因, 客户端据此可立即让用户退出(无需等待过期)。

参数	类型	必填	说明
reason	string	否	封禁原因(≤255 字符),会在用户登录时提示

{
  "code": 200, "message": "已封禁",
  "data": { "id": 1, "username": "test", "status": "banned", "ban_reason": "违规多开" }
}

code	说明
400	已处于封禁/未封禁状态 / 原因过长
404	用户不存在

删除用户(不可恢复)。如只是临时禁用,建议改用上面的封禁。

批量删除用户(不可恢复)。两种模式二选一:
① 传 ids 数组,按 ID 批量删除(单次最多 1000 条);
② 传 only_expired: true,删除指定项目内所有已过期用户。

参数	类型	必填	说明
project_id	int	条件必填	only_expired 模式下必填,限定清理范围;ids 模式下可选,传则附加项目限定防止跨项目误删
ids	int[]	条件必填	要删除的用户 ID 列表, 与 only_expired 二选一
only_expired	bool	条件必填	为 true 时, 删除该项目内所有已过期用户(忽略 ids)

{
  "code": 200, "message": "已删除 5 个用户",
  "data": {
    "deleted_count": 5,
    "requested_count": 5,
    "mode": "by_ids",
    "project_id": 1
  }
}

code	说明
400	ids 为空 / 超过 1000 条 / 既没传 ids 也没传 only_expired

用户登录接口(项目内)。必须传 username、password、device_id 三项。 服务端以 (project_id, username) 定位账号,因此 A 项目的账号无法登录 B 项目。 被封禁账号会被拒绝(403),并返回封禁原因。

参数	类型	必填	说明
project_id	int	是	项目 ID(在 URL 路径中)

参数	类型	必填	说明
username	string	是	账号
password	string	是	密码
device_id	string	是	设备唯一标识

{
  "code": 200, "message": "登录成功",
  "data": {
    "username": "test",
    "expire_time": "2026-07-05 14:30:00",
    "device_id": "DEVICE_001",
    "announcement": "系统将于今晚 23:00 维护, 请提前保存数据"
  }
}

code	说明
401	账号或密码错误
403	账号已被封禁 / 账号已过期

说明: announcement 为全局公告, 未设置则为空字符串。如需单独拉取见 公告接口。

用户心跳 / 过期检测接口(项目内)。客户端定时调用以更新本地到期时间,并感知账号是否被封禁。 每次有效心跳会把客户端 IP 与时间记入记录(type=heartbeat),用于后台按 IP 检测多开。 建议客户端在收到 is_banned 或 is_expired 为 true 时主动退出登录。

参数	类型	必填	说明
project_id	int	是	项目 ID(在 URL 路径中)

参数	类型	必填	说明
username	string	是	账号
password	string	是	密码
device_id	string	否	设备标识, 会一并记入心跳记录

{
  "code": 200, "message": "success",
  "data": {
    "username": "test",
    "expire_time": "2026-07-05 14:30:00",
    "is_expired": false,
    "is_banned": false,
    "ban_reason": "",
    "status": "未过期",
    "remaining_days": 25,
    "remaining_seconds": 2160000,
    "server_time": "2026-06-10 14:30:00"
  }
}

code	说明
400	账号或密码为空
401	账号或密码错误

注意: 封禁/过期账号此接口仍返回 200,通过 is_banned / is_expired 字段判断,而非错误码。

用户端单独获取全局系统公告(无需登录态,不带 project_id)。客户端可定时拉取以展示最新公告。

{
  "code": 200, "message": "success",
  "data": {
    "announcement": "系统将于今晚 23:00 维护...",
    "updated_at": "2025-05-20 12:00:00"
  }
}

用户自助修改密码(项目内)。需要传入原密码进行身份验证。 已过期账号无法修改密码,请联系管理员重置。

参数	类型	必填	说明
username	string	是	账号
old_password	string	是	原密码
new_password	string	是	新密码,不能与原密码相同

{
  "code": 200, "message": "密码修改成功",
  "data": { "username": "test" }
}

code	说明
400	参数缺失 / 新旧密码相同
401	账号或原密码错误
403	账号已过期

获取登录记录列表(分页 + 筛选)。含登录与心跳两类,用 type 区分。

参数	类型	必填	说明
project_id	int	否	按项目过滤;不传则查所有项目
type	string	否	login(默认) / heartbeat(心跳) / all
username	string	否	按账号模糊搜索
device_id	string	否	按设备 ID 模糊搜索
status	string	否	all / success / fail
page	int	否	页码,默认 1
page_size	int	否	每页数量,默认 10,最大 100

清理超过指定天数的登录记录(需登录态, 不可恢复)。 默认清理超过 30 天的记录,可通过 days 参数调整。

参数	类型	必填	说明
days	int	否	保留天数, 默认 30, 范围 1 ~ 3650。删除 login_time 早于 (NOW - days) 的所有记录
project_id	int	否	只清理该项目的旧记录;不传则清理所有项目

{
  "code": 200, "message": "已清理 128 条超过 30 天的登录记录",
  "data": {
    "deleted_count": 128,
    "days": 30,
    "project_id": 1,
    "before": "2026-05-06 14:30:00"
  }
}

获取统计数据(用户总数 / 今日活跃用户 / 今日活跃设备 / 今日登录次数 / 已过期用户)。可按项目过滤。

参数	类型	必填	说明
project_id	int	否	只统计该项目;不传则全局统计

{
  "code": 200, "message": "success",
  "data": {
    "today_active_users": 12,
    "today_active_devices": 18,
    "today_login_count": 35,
    "total_users": 100,
    "expired_users": 5,
    "date": "2026-06-10"
  }
}