微健（Wefitos）后台数据查询
ApiSecret 管理
ApiSecret 存储在 skill 内部 apisecret/config.md，格式：
ApiSecret: <密钥值>
每次调用流程：
- Read skill 目录下的
apisecret/config.md
- 文件存在 → 提取ApiSecret:后的值，直接使用
- 文件不存在 → 询问用户："请提供您的 Wefitos ApiSecret（接口认证密钥）" - 获取到值后，立即创建
apisecret/config.md，写入ApiSecret: <值>，后续调用自动读取，永不重复询问 - 使用 Read 工具提取值时，匹配行首
ApiSecret:后的内容即可
> 注意：该文件位于 skill 目录内部，随 skill 一起管理，跨会话持久有效
调用规范
- 所有 API 均为 POST，Base URL：
https://api.wefitos.com/open - 请求头必带：
APISECRET: <密钥>+Content-Type: application/x-www-form-urlencoded;charset=UTF-8 - 参数通过 body 传递，除
/getClubs外所有接口必须携带clubId
俱乐部检测（缓存优先）
俱乐部列表缓存在 skill 内部 apisecret/clubs.md，避免每次调用接口。
每次查询流程：
- Read skill 目录下的
apisecret/clubs.md
- 文件存在 → 直接使用缓存的俱乐部列表，跳过接口调用
- 文件不存在 → 调用POST /getClubs获取，然后立即创建apisecret/clubs.md - 俱乐部匹配规则不变：单俱乐部自动使用，多俱乐部按名称匹配或让用户选择
- 详细规则见
references/common/getclubs.md
错误码处理（最高优先级）
每次接口调用后，必须立即检查响应的 cn 字段：
cn == 0：成功，正常继续cn == 1（或任何非 0 值）：立即停止，不再发起任何后续请求（包括分页循环和其他接口调用），向用户报告错误信息：接口返回错误（cn=1）：<message 字段内容>
> 此规则适用于所有接口，包括 /getClubs、分页循环中的每一页、以及任何数据查询接口。绝不能在 cn != 0 时继续循环或重试。
分页规范
所有查询必须自动分页拉取全部数据：pageIndex 从 0 开始，pageSize 固定 100，循环直到已拉取条数 >= total。每页响应必须先检查 cn，非 0 立即中断循环。
工具函数见 references/common/utils.md
🔑 会员卡查询：两个概念，切勿混淆
会员卡相关查询分为两类完全不同的业务场景，对应不同的接口：
📋 会员卡状态查询（cards 系列）— "系统里有多少卡？卡现在什么状态？"
对应接口：/timeCardStats、/personalTrainerCardStats、/onceCardStats、/storedValueCardStats
适用场景（命中任意一条就用这个）：
- 查系统有多少张会员卡 / 有多少张时间卡、私教卡、次卡、储值卡
- 查会员卡到期情况、剩余天数、剩余次数、剩余额度
- 查会员卡状态（是否过期、是否激活）
- 查会员卡的剩余课时、剩余金额
- "有多少会员卡即将到期"、"查一下某会员的卡还有多少天"
- 筛选条件按到期时间（expireTimeStartTime/expireTimeEndTime）
> 这类查询关心的是卡的存量和当前状态，返回的是每张卡的"档案"。
💰 会员卡销售/发卡记录查询（recharge 系列）— "卖了多少卡？什么时候卖的？"
对应接口：/getTimeCardRecharge、/getPersonalTrainerCardRecharge、/getOnceCardRecharge、/getStoredValueCardRechange
适用场景（命中任意一条就用这个）：
- 查会员卡销售记录 / 发卡记录 / 录单记录 / 充值记录
- 查某段时间卖了多少张卡、销售额多少
- 查发卡明细、合同号、支付方式
- 查销售业绩（谁卖的、卖了多少钱）
- "这个月卖了多少时间卡"、"查一下某教练的发卡记录"
- 筛选条件按销售/发卡时间（rechargeDateStart/End 或 startInsertTime/endInsertTime）
> 这类查询关心的是交易流水，返回的是每笔销售/发卡操作的记录。
⚡ 快速判断
| 用户说的话 | 用哪个 |
|---|---|
| "有多少卡" / "卡什么状态" / "还剩多少天/次数/额度" / "卡到期了吗" | cards 系列（会员卡状态） |
| "卖了多少钱" / "发了多少卡" / "销售记录" / "发卡记录" / "录单记录" | recharge 系列（销售/发卡记录） |
| "收银记录" / "卖了多少水/蛋白粉" / "商品零售" / "前台收款" | cashRecords（商品收银，不含会员卡） |
🏪 商品收银 vs 会员卡销售 — 切勿混淆
| 场景 | 用哪个接口 |
|---|---|
| 卖水、卖蛋白粉、运动饮料等门店商品零售流水 | /cashRecords（收银记录） |
| 办时间卡、私教卡、次卡、储值卡等会员卡销售/发卡记录 | recharge 系列（如 /getTimeCardRecharge） |
> 关键区分：收银记录 = 商品零售（实物商品）；会员卡销售 = 卡务业务。两者数据源完全独立，不要用错。
接口索引
按需 Read 对应文档获取参数和返回字段详情。
📌 基础接口
| 数据类型 | 接口路径 | 文档路径 |
|---|---|---|
| 获取俱乐部 | /getClubs |
references/common/getclubs.md |
| 薪资报表 | /wageReport |
references/wage/report.md |
| 签到记录 | /signs |
references/sign/records.md |
| 收银记录 | /cashRecords |
references/cash/records.md |
📋 会员卡状态查询（查系统有多少卡、卡的当前状态）
> 场景：查会员卡数量、到期情况、剩余天数/次数/额度、卡状态等
| 数据类型 | 接口路径 | 文档路径 |
|---|---|---|
| 时间卡状态 | /timeCardStats |
references/cards/time_card/stats.md |
| 私教卡状态 | /personalTrainerCardStats |
references/cards/personal_trainer/stats.md |
| 次卡状态 | /onceCardStats |
references/cards/once/stats.md |
| 储值卡状态 | /storedValueCardStats |
references/cards/stored_value/stats.md |
💰 会员卡销售/发卡记录（查卖了多少钱、发卡明细）
> 场景：查销售记录、发卡记录、录单记录、充值记录、合同号、支付方式等
| 数据类型 | 接口路径 | 文档路径 |
|---|---|---|
| 时间卡销售记录 | /getTimeCardRecharge |
references/recharge/time_card/records.md |
| 私教卡销售记录 | /getPersonalTrainerCardRecharge |
references/recharge/personal_trainer/records.md |
| 次卡销售记录 | /getOnceCardRecharge |
references/recharge/once/records.md |
| 储值卡销售记录 | /getStoredValueCardRechange |
references/recharge/stored_value/records.md |
✂️ 核销记录（查会员卡的使用/消耗情况）
> 场景：查会员卡被核销/消耗的记录
| 数据类型 | 接口路径 | 文档路径 |
|---|---|---|
| 核销-私教卡 | /spendFormPersonalTrainerCard |
references/verify/personal_trainer/records.md |
| 核销-次卡 | /sendFormtOnceCard |
references/verify/once/records.md |
| 核销-储值卡 | /sendFormtSpendRecord |
references/verify/stored_value/records.md |
通用工具
| 文档 | 内容 |
|---|---|
references/common/utils.md |
分页函数、Excel 保存函数、请求头模板 |
references/common/getclubs.md |
getClubs 入口接口详细说明 |
调用流程
- 获取 clubId → 优先 Read
apisecret/clubs.md缓存，不存在才调/getClubs - Read 对应接口文档 → 从上方索引找到文档路径，获取参数和字段
- 确认筛选条件 → 时间范围、姓名等可选参数
- 自动分页拉取 → 使用
post_with_pagination工具函数 - 表格展示 → 列名用中文（见各接口文档的返回字段表）
- 自动保存 Excel → 桌面，文件名见各接口文档
注意事项
- 薪资接口仅返回已创建薪资模版的人员；用户说明其他统计方式时按用户要求
- 时间参数命名不同接口有差异：核销用
startTime/endTime，签到用timeRangeStart/End，充值用rechargeDateStart/End或startInsertTime/endInsertTime - Excel 保存失败时告知用户，不静默跳过
扩展方式
新增接口时：1) 在 references/ 下新增对应 .md 文档 → 2) 在上方「接口索引」表新增一行
