灵策中台验收样例 center-demo

本页目录

目录接入要点（照着抄）

样例源码在灵策内部仓库，暂未公开。正式接入时可以向运营索取。

一个最小的「第三方产品」，只用 SDK（@ai-employee/center-sdk）和接入文档接好灵策中台的四件事：

能力	本样例里的做法	对应文档
登录	「用灵策账号登录」：授权码 + PKCE(S256) + state + nonce，回调里 `handleCallback` 换令牌并验 id_token；签名的 HttpOnly 会话 cookie；`offline_access` 续期；单点登出（`center.logout`）	统一登录
支付	「购买」：先记本地单再 `createOrder`；`native` / `precreate` 显示二维码串，`page` 跳转收银台；订单页轮询，服务端 `getOrder`；已付订单可部分退款（`outRefundNo` 幂等）	收款与 Webhook
通知	Webhook 收到 `payment.succeeded` 后 `sendNotification` 给用户发「支付成功」，`eventKey = pay-succeeded:<orderNo>`	通知与文件
文件	服务端 `presignFileUpload`，浏览器带返回的 headers 直接 PUT，页面显示 `publicUrl`	通知与文件

它同时是后续新产品接入的参考实现：纯 Node 24 node:http、服务端渲染、零运行时依赖，一共不到一千行。

#目录

文本

server.mjs          入口（读环境变量、组装、监听）
src/config.mjs      环境变量 → 配置（缺密钥时对应功能 fail-closed）
src/session.mjs     签名 cookie（HMAC-SHA256，绑定 cookie 名，带过期）+ 服务端会话 / 待完成登录
src/store.mjs       本地订单 + 已处理事件的 JSON 文件存储，事件去重
src/webhook.mjs     原始 body 验签 → 事件 id 去重 → 处理 → 2xx
src/orders.mjs      发货（记已付 + 通知）、记退款等业务规则
src/app.mjs         路由
src/html.mjs        页面
test/*.test.mjs     单测（node:test）
acceptance.mjs      对着本地 API + 运行中的 demo 的端到端验收

#接入要点（照着抄）

state / nonce / code_verifier 只在服务端：cookie 里只有一条暂存记录的随机 id，回调时一次性取出。
令牌只在服务端：浏览器只拿签名的会话 id（HttpOnly、SameSite=Lax）。生产请把会话放 Redis / 数据库、refresh_token 加密存储。
续期：center.refresh() 每次返回新的 refresh_token，旧的立即作废；invalid_grant 按「已退出」处理。续期签发的 id_token 不带 nonce。
先记本地单再下单：outTradeNo 用本地主键，网络错误用同号重试；发货只认 Webhook（验签 + 事件 id 去重）或服务端 getOrder，不认前端回跳；核对金额再发货。
Webhook：一定用原始 body 验签；处理完才把事件 id 记为已处理，失败回 5xx 让中台重投；同一事件正在处理时回 409。
退款：部分退款必须带 outRefundNo；502 / 网络错误表示结果未知，用同一个 outRefundNo 重试；确定性拒绝换新单号。
文件：headers 原样带上；publicUrl 公共可读，不要传隐私文件。浏览器直传需要对象存储允许你的域名跨域 PUT。