调用开放平台

云应用后端接通凭据后，可以使用 SDK 调用信多帮开放 API。开放平台仍然要求独立的 appid 和 appsecret；Core 登录只解决“当前用户是谁”，不会自动获得读取商家业务数据的权限。

V2 签名已内置

JavaScript 和 Python SDK 已内置 V2 签名，不需要手写签名函数；默认根据 AppID 的 V2 前缀启用，其他 V2 凭据可显式指定签名模式。普通服务端项目也能使用，安装与最简示例见V2 接入示例：使用 SDK 自动签名。

编码前安排请求频率

SDK 目前不自动限速、合并业务请求或缓存业务结果，也不自动重试业务请求。即使本地使用 WorkBuddy 和 xdbapp dev，业务接口仍按商家共享额度，当前默认每秒最多 4 次，部分商家更低。页面、分页与后台同步需要共用后端调用预算；完整实现和测试要求见业务接口稳定性。

凭据由平台自动管理

创建云应用时，平台会自动创建并绑定一组专属 AppID 和 AppSecret。它不占用商家手工创建开放平台密钥的 10 个名额；应用存在期间不能从开放平台页面修改或删除。

开发者不需要查看、复制或保存这组凭据。托管环境会自动获得 XDB_OPEN_APP_ID、XDB_OPEN_APP_SECRET，浏览器和页面代码不会接触明文 Secret。

一份代码，两种安全方式

业务代码始终通过 SDK 调用开放平台，不需要判断自己运行在哪里。长期 AppSecret 只留在平台控制面和托管容器，本地开发改用短期 Token：

运行位置	谁负责注入	使用的凭据	何时消失
本地开发	`xdbapp dev` 校验管理员/开发者和 App 权限，在 `127.0.0.1` 启动临时凭据代理	可续签的短期 Preview Token，不下发 AppSecret	退出该命令后
托管 Preview	平台启动 Preview 容器时自动注入	该应用绑定的开放平台凭据	容器停止后
托管 Production	平台启动 Production 容器时自动注入	该应用绑定的开放平台凭据	容器停止后

Preview 数据库、文件存储的隔离不等于开放平台业务数据隔离。 开放平台请求仍访问凭据所属商家的业务数据，本地或预览中的写接口也可能修改真实订单、营员等记录；测试优先使用模拟响应或约定的测试业务，不能把 Preview 当成自动隔离的商家沙箱。

因此，开发者既不需要在本地创建 .env，也不需要在上线时配置 AppID 或 AppSecret。应用从本地开发到正式运行始终使用同一份服务端代码。

本地开发

本地开发时仍使用同一份 SDK 业务代码，但必须用 xdbapp dev -- <原启动命令> 启动。CLI 会向 SDK 提供本机临时代理，由代理按需续签短期 Preview Token，而不是把 AppID / AppSecret 复制到开发电脑。

xdbapp dev 同时负责 Preview 环境变量、数据库代理、当前用户和 Storage 本地代理。命令用法、数据流转和限制集中说明在本地开发：xdbapp dev，不再由 SDK 文档重复定义 CLI 行为。

Node.js

import { xdbPaaS } from "@xinduobang/xdb-paas-sdk/server";

const open = xdbPaaS.openPlatform.createClient();
const result = await open.request("/api/productList", {pageNum: 1});

Python

from xdb_paas import xdb_paas

open_platform = xdb_paas.open_platform.create_client()
result = open_platform.request("/api/productList", {"pageNum": 1})

SDK 自动处理的事情

托管环境自动读取 XDB_OPEN_APP_ID、XDB_OPEN_APP_SECRET 并调用 /api/getToken；
本地环境自动通过 127.0.0.1 临时代理续签短期 Token；
在进程内缓存 Token，并在到期前刷新；
0.1.0 起自动为 V2 AppID 的 Token 和业务请求附加签名；
固定请求信多帮官方开放平台地址，避免 Secret 被误发到第三方域名；
将网络、取 Token 和业务请求错误转换为稳定的 SDK 错误类型。

业务接口参数

通用 request 可以调用开放平台已授权的接口，具体路径和参数以API 文档为准；新增业务 API 不要求先更新 CLI。0.1.0 另提供订单与营员专用方法，处理 JSON 参数和这些接口特殊的成功/失败规则。

上例使用获取营种列表的真实接口和分页字段。业务代码应按对应接口文档传参，SDK 负责附加 Token；不要把示意路径当成已存在的开放接口。

SDK 缓存的是访问 Token，不会自动缓存业务查询结果或免除接口限流。同步大量数据时，应按接口的分页与调用频率要求执行；只读查询遇到限流或暂时失败，可由业务代码有限退避，写操作不自动重试。不能只用串行 await 代替限速，也不能把失败响应转为空数据。

订单导入与营员维护（0.1.0）

能力	JavaScript	Python
营种详情	`getProductInfo(pid)`	`get_product_info(pid)`
导入模板	`getImportTemplate(pid)`	`get_import_template(pid)`
批量导入	`importOrders(orders)`	`import_orders(orders)`
编辑营员	`editStudent(...)`	`edit_student(...)`
新增营员	`addStudent(...)`	`add_student(...)`

专用方法直接返回接口的 data。营种详情可取得 spec_period.period_list[].sku_plu，模板可取得 form_fields.child/big；按模板提供必填字段与选项值后再导入。

const template = await open.getImportTemplate(1001);
const imported = await open.importOrders([{
  out_order_sn: "YOUR_UNIQUE_ORDER_ID", plu: "YOUR_PLU", user_phone: "13800000000",
  students: [{ name: "张小明" }], // 按 template 补齐必填字段
}]);
if (imported.hasFailures) {
  // 显示失败原因；已成功与重复订单仍保留在各自清单中
  console.error(imported.fail_list);
}
await open.editStudent({ order_num: "NO...", sid: 88123, student_info: completeStudentInfo });
await open.addStudent({ order_num: "NO...", student_info: newStudentInfo, is_children: 1 });

template = open_platform.get_import_template(1001)
imported = open_platform.import_orders([{
    "out_order_sn": "YOUR_UNIQUE_ORDER_ID", "plu": "YOUR_PLU", "user_phone": "13800000000",
    "students": [{"name": "张小明"}],  # 按 template 补齐必填字段
}])
if imported["has_failures"]:
    print(imported["fail_list"])
open_platform.edit_student(order_num="NO...", sid=88123, student_info=complete_student_info)
open_platform.add_student(order_num="NO...", student_info=new_student_info, is_children=1)

导入每批为 1–10 单，SDK 不自动拆批。success_list、fail_list、duplicate_list 全部保留；重复订单不是重新建单。部分失败不会抛异常，必须查看 hasFailures（Python has_failures）与失败清单。
编辑营员是全量替换，未传字段会清空；新增营员受已购名额限制，is_children=0 仅亲子营支持。
这些工具接口可能返回 HTTP 200、code=0，但 msg 非空、data=[]，实际表示业务失败。专用方法会抛出 OPEN_PLATFORM_BUSINESS_FAILED；格式不完整则抛出 OPEN_PLATFORM_RESPONSE_INVALID，不当成成功。
SDK 不自动重试写入。导入订单可由业务方使用相同 out_order_sn 手动重试；新增营员不能照搬订单幂等逻辑，网络超时后先确认实际是否已新增。
0.1.1 的类型声明支持先建纯订单、再补营员；students 可缺省或为空，number、small_number、big_number 原样传入。需要后续补录时先声明购买名额，不要把“没有营员”当成“有剩余名额”。具体优先级以导入接口文档为准。
旧 request() 保持原始响应与 V1 数组编码，不能仅看 HTTP 或 code=0 判定业务成功。直接调用导入接口时，将整个订单数组转为 JSON.stringify(orders) / json.dumps(orders)，不能传重复的 orders 表单字段。

接口细节见导入订单、编辑/新增营员、营种详情、导入模板。

V2 接入与旧版本兼容

托管服务端使用 V2 开头的 AppID 时，SDK 自动对 /api/getToken 和业务请求签名。signing 支持 auto（默认）、v1、v2；只有 Token 的独立 V2 接入必须显式指定 v2 并在服务端提供 secret。缺 Secret 会报错，不会静默降级。

V2 请求体按参数 key 升序和 PHP http_build_query 规则编码，签名与实际发送的 body 一致。复杂对象/数组采用 PHP 嵌套字段；接口要求 JSON 字符串时先序列化，专用方法已自动处理。

平台 xdbapp dev 短期 Token 代理的调用方式保持不变，不要求用户把长期 Secret 放到本地。签名算法见V2 接入示例。旧项目升级后仍可使用 request()；如需上述专用方法，应更新业务调用并重新测试、发布预览。

只能从服务端调用

需要 App Secret 的开放接口只能由 Node.js/Python 后端调用。纯静态应用如需读取业务数据，必须增加服务端接口，由服务端调用开放平台；不要在浏览器代码、构建后的 JavaScript、日志或接口响应中暴露 Secret。

凭据由平台自动管理​

一份代码，两种安全方式​

本地开发​

Node.js​

Python​

SDK 自动处理的事情​

业务接口参数​

订单导入与营员维护（0.1.0）​

V2 接入与旧版本兼容​