极客场馆开放平台 · 会员接口

版本 v1 · 配套文档：加密与签名接入 · 通用约定与错误码 所有路径前缀 https://www.gymker.com/api/open/v1。响应/错误码/幂等/限流见通用约定。

---

1. 能力总览

能力	scope	典型用途
按 ID 查会员	member:read	下单前确认会员身份
按手机号查会员	member:read	用真实手机号反查
全店会员列表 + 资产	member:read	第三方拉全量会员做本地映射
时段内新增会员	member:read	按注册时间增量拉取新客

每个 AppId 只对应一家门店，所有接口自动按该门店过滤。

---

2. 按 ID 查会员 · GET /members/{memberId}

按会员 ID 查基础信息（手机号脱敏）。scope member:read。响应 data：

{
  "id": 12345, "gymId": 1001, "realName": "张三",
  "phoneMasked": "138****1234", "gender": 1,
  "birthday": "1990-05-20", "memberType": "GYM_MEMBER"
}

---

3. 按手机号查会员 · GET /members/phone/{phone}

按真实手机号（11 位，非脱敏）反查会员。scope member:read。响应结构同 §2。

同一门店内手机号唯一，可作为会员的稳定关联键。

---

4. 全店会员列表 + 资产 · GET /members

分页拉取本门店全部会员，并直接带上资产（余额 / 剩余节数 / 剩余周期），方便第三方一次拿全、本地按 ID 映射后再查询。scope member:read。

• 资产为对客口径（合同剩余）：剩余节数 = 活跃节数单总购买 − 已上课；剩余周期天数 = 活跃周期单中最长剩余天数。
• Query：page（默认 1）/ size（默认 20，上限 100），可选 keyword（姓名或手机号模糊）。

data：{ records[], total, current, size }，records[] 单元素：

{
  "id": 12345, "realName": "张三", "phoneMasked": "138****1234",
  "memberType": "GYM_MEMBER",
  "assets": {
    "walletBalance": 1500.00,        // 充值卡可用余额（本金+赠送）
    "remainingSessions": 12,         // 剩余私教节数（对客）
    "remainingCycleDays": 86         // 剩余周期天数（对客，无则 0）
  }
}

---

5. 时段内新增会员 · GET /members/new

按注册时间（createTime）拉取某时段内新增的会员，用于增量同步新客。scope member:read。

Query	类型	必填	说明
startDate	yyyy-MM-dd	是	createTime >= startDate
endDate	yyyy-MM-dd	是	createTime <= endDate
page / size	int	否	默认 1 / 20，size ≤ 100

startDate / endDate 必填，跨度 ≤ 90 天。data：{ records[], total, current, size }，records[] 单元素结构同 §2（手机号脱敏），按注册时间倒序。