批量查询最后活跃时间（adminx）

1. 接口定位

• 接口名称: 批量查询最后活跃时间
• 所属域: admin/user（adminx）
• 业务目标: 运营或测试侧按用户 ID 批量核对最后活跃时间及其来源

2. 请求定义

• Method: POST
• Path: /adminx/user/last-active/batch
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效管理员登录令牌
• 幂等性: 幂等（只读查询）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员登录令牌

Body 参数

字段	必填	类型	说明
userIDs	是	array<string>	待查询用户 ID 列表

字段约束

• userIDs 不能为空。
• userID 会在服务端做首尾空白裁剪。
• 同一请求内重复 userID 允许输入，响应会按输入顺序逐条返回。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	object	业务数据

data 字段

字段	类型	说明
total	uint32	输入条目总数
users	array<object>	逐条查询结果

users 子字段:

字段	类型	说明
userID	string	用户 ID（空值时保留原始输入）
lastActiveTime	int64	最后活跃时间，Unix 毫秒时间戳
source	string	时间来源

source 可选值:

• LAST_ACTIVE_AT: 命中精确在线活跃时间（Redis 用户级时间戳键）
• DAU_DAY: 未命中精确时间时，回退到 DAU 最后活跃日期 00:00（Asia/Shanghai）
• LAST_LOGIN: 未命中前两者时，回退到最后登录时间
• NONE: 无可用活跃时间
• INVALID_USER_ID: 输入 userID 为空或仅空白

5. 业务规则

• 仅管理员可调用。
• 回退顺序固定为: LAST_ACTIVE_AT -> DAU_DAY -> LAST_LOGIN -> NONE。
• DAU 回退窗口为最近 45 天。
• DAU 回退命中时返回的是日期起点（00:00）时间戳，不代表当天精确时分秒。

6. 错误码与失败场景

错误码	场景	典型报错
1001	userIDs 为空	userIDs is empty
-	鉴权失败	由管理员鉴权链路返回
-	查询登录记录失败	由数据库层返回原始错误

说明:

• 请求合法时，即使包含空 userID，接口仍返回 errCode = 0，并在该条 source 返回 INVALID_USER_ID。

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/user/last-active/batch", {
  method: "POST",
  headers: {
    operationID: "adminx-last-active-batch-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userIDs: ["u1001", " u1002 ", "", "u1001"],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userIDs": ["u1001", " u1002 ", "", "u1001"]
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 4,
    "users": [
      {
        "userID": "u1001",
        "lastActiveTime": 1735718400000,
        "source": "LAST_ACTIVE_AT"
      },
      {
        "userID": "u1002",
        "lastActiveTime": 1735689600000,
        "source": "DAU_DAY"
      },
      {
        "userID": "",
        "lastActiveTime": 0,
        "source": "INVALID_USER_ID"
      },
      {
        "userID": "u1001",
        "lastActiveTime": 1735718400000,
        "source": "LAST_ACTIVE_AT"
      }
    ]
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. 服务端归一化 userIDs（trim）并去重用于内部查询。
3. 批量读取精确在线活跃时间。
4. 对未命中用户按最近 45 天倒序查询 DAU 日桶。
5. 对仍未命中用户查询最后登录时间。
6. 按原请求顺序组装结果并返回。

9. 变更记录

• 2026-08-31: 首版发布，新增 adminx 批量查询最后活跃时间接口。