API 文档

所有 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/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"
  }
}

创建新用户。有效期通过天数指定,后端根据当前时间自动计算到期时间。

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

{
  "code": 200,
  "message": "用户创建成功",
  "data": {
    "id": 1,
    "username": "test",
    "expire_time": "2025-06-15 14:30:00",
    "days": 30
  }
}

获取用户列表(分页 + 筛选)

参数	类型	必填	说明
keyword	string	否	账号模糊搜索
status	string	否	all / active(默认, 未过期) / expired
page	int	否	页码,默认 1
page_size	int	否	每页数量,默认 10,最大 100

{
  "code": 200, "message": "success",
  "data": {
    "list": [
      {
        "id": 1, "username": "test",
        "expire_time": "2025-06-15 14:30:00",
        "created_at": "2025-05-16 14:30:00",
        "is_expired": false, "status": "未过期",
        "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

删除用户(不可恢复)

批量删除用户(不可恢复)。两种模式二选一:
① 传 ids 数组,按 ID 批量删除(单次最多 1000 条);
② 传 only_expired: true,一键删除所有已过期用户(忽略 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"
  }
}

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

用户登录接口。必须传 username、password、device_id 三项。 通过 device_id 可统计今日活跃用户和活跃设备。

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

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

说明: announcement 字段返回系统公告内容, 若管理员未设置则为空字符串 ""。 客户端可在登录成功后展示给用户。如需单独拉取, 见下方 公告接口。

用户心跳 / 过期检测接口。客户端可定时调用以更新本地的到期时间(例如管理员后台续期后, 客户端无需重新登录即可获取新的 expire_time)。 该接口不写入登录记录,可高频调用。

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

{
  "code": 200, "message": "success",
  "data": {
    "username": "test",
    "expire_time": "2025-06-15 14:30:00",
    "is_expired": false,
    "status": "未过期",
    "remaining_days": 25,
    "remaining_seconds": 2160000,
    "server_time": "2025-05-21 14:30:00"
  }
}

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

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

{
  "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	账号已过期

获取登录记录列表(分页 + 筛选)

参数	类型	必填	说明
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) 的所有记录

{
  "code": 200, "message": "已清理 128 条超过 30 天的登录记录",
  "data": {
    "deleted_count": 128,
    "days": 30,
    "before": "2025-04-21 14:30:00"
  }
}

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

{
  "code": 200, "message": "success",
  "data": {
    "today_active_users": 12,
    "today_active_devices": 18,
    "today_login_count": 35,
    "total_users": 100,
    "expired_users": 5,
    "date": "2025-05-16"
  }
}