微健（Wefitos）后台数据查询

ApiSecret 管理

ApiSecret 存储在 skill 内部 apisecret/config.md，格式：

ApiSecret: <密钥值>

每次调用流程：

1. Read skill 目录下的 apisecret/config.md
   • 文件存在 → 提取 ApiSecret: 后的值，直接使用
   • 文件不存在 → 询问用户："请提供您的 Wefitos ApiSecret（接口认证密钥）"
2. 获取到值后，立即创建 apisecret/config.md，写入 ApiSecret: <值>，后续调用自动读取，永不重复询问
3. 使用 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，避免每次调用接口。

每次查询流程：

1. Read skill 目录下的 apisecret/clubs.md
   • 文件存在 → 直接使用缓存的俱乐部列表，跳过接口调用
   • 文件不存在 → 调用 POST /getClubs 获取，然后立即创建 apisecret/clubs.md
2. 俱乐部匹配规则不变：单俱乐部自动使用，多俱乐部按名称匹配或让用户选择
3. 详细规则见 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 入口接口详细说明 |

调用流程

1. 获取 clubId → 优先 Read apisecret/clubs.md 缓存，不存在才调 /getClubs
2. Read 对应接口文档 → 从上方索引找到文档路径，获取参数和字段
3. 确认筛选条件 → 时间范围、姓名等可选参数
4. 自动分页拉取 → 使用 post_with_pagination 工具函数
5. 表格展示 → 列名用中文（见各接口文档的返回字段表）
6. 自动保存 Excel → 桌面，文件名见各接口文档

注意事项

• 薪资接口仅返回已创建薪资模版的人员；用户说明其他统计方式时按用户要求
• 时间参数命名不同接口有差异：核销用 startTime/endTime，签到用 timeRangeStart/End，充值用 rechargeDateStart/End 或 startInsertTime/endInsertTime
• Excel 保存失败时告知用户，不静默跳过

扩展方式

新增接口时：1) 在 references/ 下新增对应 .md 文档 → 2) 在上方「接口索引」表新增一行