Skip to main content

EIOTCLUB / aovis-direct-store Claude 开发任务版

这份文档是给 Claude 直接用来开发 aovis-direct-store 流量卡能力的，不是给业务同事看的摘要。 目标是把 EIOTCLUB Apifox 文档里的关键信息收敛成可执行开发说明，减少 Claude 猜字段、漏签名、漏回调的概率。

目标​

  • 开发 aovis-direct-store 的流量卡相关接口层
  • 重点覆盖卡片查询、套餐查询、套餐订购、套餐退款、流量刷新、会话取消、云 eSIM、通知回调
  • 先打通主流程，再补边缘功能

统一约定​

  • 开放平台基地址：https://oapi.eiotclub.com
  • 请求方式：POST
  • 请求体：application/json
  • 请求参数分两类：
    • 系统级参数：appkey、timestamp、nonce、sign
    • 业务级参数：各接口自己的字段
  • timestamp 是 10 位时间戳
  • nonce 是 5 位随机正整数
  • 签名规则：
    • 按参数名 ASCII 升序排列非空参数
    • 拼成 key=value&key=value...
    • 末尾拼接 secret
    • sha1 后转大写
    • API 调用需要带 appkey
    • 回调签名不需要 appkey

开发优先级​

1. 卡片查询与状态​

  • POST /api/v3/card/getAllCardInfo
    • 作用：获取账号下全部卡片
    • 关键字段：pageNum, pageSize, cardStatus, iccids
    • 返回核心字段：iccid, imsi, cardStatus, flowTotal, flowRemain, packageType, packageName, packageCode, network, isRealName
  • POST /api/v3/card/getCardsInfo
    • 作用：按卡号查询单卡信息及流量使用信息
    • 关键字段：iccid
    • 返回核心字段：iccid, imsi, activateDate, cardStatus, monthRemainFlow, monthUseFlow, remainFlow, totalUseFlow, packageCode
  • POST /api/v3/card/product
    • 作用：查询卡片归属的产品

2. 套餐与订购​

  • POST /api/v3/package/listOrderPackageByIccid
    • 作用：按卡号查询可订购套餐
  • POST /api/v3/package/listOrderPackageByProduct
    • 作用：按产品查询可订购套餐
  • POST /api/v3/package/queryOrderPackageByPackageCode
    • 作用：按套餐编码查询套餐信息
  • POST /api/v3/package/orderPackage
    • 作用：套餐订购
    • 备注：主套餐立即生效，流量包支持次月生效
  • POST /api/v3/package/queryPackage
    • 作用：查询套餐订购订单状态
  • POST /api/v3/package/packageOrderRecord
    • 作用：查询卡片套餐订购记录
  • POST /api/v3/package/getOrderPackageDetails
    • 作用：批量查询订单对应套餐详情

3. 流量与会话​

  • POST /api/v3/card/refreshUsage
    • 作用：刷新套餐用量，同步运营商流量
  • POST /api/v3/card/cancelLocation
    • 作用：取消当前会话，让设备重新连接
  • POST /api/v3/cdr/traffic/query
    • 作用：ICCID 流量查询
    • 重点：该接口实际查询的是运营商推送的 CDR 文件，不是实时流量

4. 退款​

  • POST /api/v3/package/queryRefundAmount
    • 作用：查询可退款金额
  • POST /api/v3/package/refundPackage
    • 作用：套餐退款
  • POST /api/v3/esim/queryRefundAmount
    • 作用：eSIM 可退款金额
  • POST /api/v3/esim/refund
    • 作用：eSIM 退款

5. eSIM / 云 eSIM​

  • POST /api/v3/esim/goods
  • POST /api/v3/esim/purchase
  • POST /api/v3/esim/orderStatus
  • POST /api/v3/cloudesim/list
  • POST /api/v3/cloudesim/get
  • POST /api/v3/cloudesim/pkg/list
  • POST /api/v3/cloudesim/pkg/record/list
  • POST /api/v3/cloudesim/purchase
  • POST /api/v3/cloudesim/orderStatus
  • POST /api/v3/cloudesim/refreshUsage
  • POST /api/v3/cloudesim/cancelSession
  • POST /api/v3/cloudesim/queryRefundAmount
  • POST /api/v3/cloudesim/refund
  • POST /api/v3/cloudesim/transferPkg

6. 卡片控制与运营商​

  • POST /api/v3/card/switchOptions
    • 查询可切换的运营商列表
  • POST /api/v3/card/switchOperator
    • 切换卡片运营商
  • POST /api/v3/card/bindDevice
    • 机卡绑定
  • POST /api/v3/card/unbindDevice
    • 机卡解绑
  • POST /api/v3/card/transferPkg
    • 卡片转移套餐
  • POST /api/v3/card/reset
    • 批量重置卡

7. 通知回调​

  • POST /api/v3/outputApi/queryAccountWarningCard
    • 账户下国际卡片预警信息
  • POST /api/v3/sms/sendSms
    • 发送短信
  • POST /api/v3/outputApi/listProfitInfo
    • 本级分润查询
  • POST /api/v3/outputApi/queryCardNumber
    • 卡总数统计
  • 通知类页面还包括：
    • 流量预警
    • 订购通知-详细版
    • 套餐生效
    • 退款通知
    • 达量到期通知
    • 卡片断网通知
    • 产品切换
    • 锁卡通知
    • 解锁通知

代码实现建议​

推荐封装方式​

  • 写一个统一的 eiotclubClient
  • 统一处理：
    • base URL
    • 系统参数注入
    • sign 计算
    • JSON POST
    • 错误码映射
    • 请求日志脱敏

推荐数据流​

  1. 先调 getAllCardInfo 拉卡列表
  2. 再调 getCardsInfo 拉单卡详情
  3. 再调 listOrderPackageByIccid 或 listOrderPackageByProduct 拉可订购套餐
  4. 下单用 orderPackage
  5. 订购后轮询 queryPackage 或相关订单状态接口
  6. 需要同步流量时调 refreshUsage
  7. 需要终止连接时调 cancelLocation
  8. 退款走 queryRefundAmount + refundPackage

返回字段里最值得保留的内容​

卡详情​

  • iccid
  • imsi
  • cardStatus
  • activateDate
  • network
  • packageCode
  • packageName
  • packageType
  • flowTotal
  • flowRemain
  • monthRemainFlow
  • monthUseFlow
  • remainFlow
  • totalUseFlow
  • isRealName
  • isIMEIPool

套餐与订单​

  • orderId
  • packageCode
  • packageName
  • packageType
  • packageEndDate
  • gzhPackageName

实施注意事项​

  • 不要把 llms.txt 当成完整 schema，它只是索引，真正可执行的字段来自每页 .md
  • 不要把 cdr/traffic/query 当实时流量接口
  • 不要把测试环境的 whsec、测试 key、临时值混入生产实现
  • 不要把文档里的敏感值写进仓库
  • 不要依赖页面上看见的“展示值”代替签名参数或必填字段

给 Claude 的直接任务描述​

你可以把下面这段直接丢给 Claude：

读取 docs/eiotclub-apifox-openapi.json 和 docs/eiotclub-claude-dev-brief.md，为 aovis-direct-store 实现 EIOTCLUB 流量卡接口层。优先完成卡片列表、单卡详情、可购套餐、套餐订购、订单状态、流量刷新、会话取消、退款和回调处理。要求统一封装签名、请求参数注入、错误码处理和日志脱敏。不要使用测试密钥；按生产可用方式组织代码。