@trustbaseai/protocol 0.1.0

package/dist/sp-framework.d.ts

@@ -0,0 +1,686 @@
+/**
+ * sp-framework.ts —— TrustBase 服务商抽象层 (Service Provider Framework)
+ *
+ * ## 这是什么
+ *
+ * TrustBase 的服务商 (SP) 是商户与主链/支付通道之间的网关角色：帮商户进件
+ * (微信支付特约商户)、接收并验证支付回调、把支付事实上链、按登记比例抽佣分账、
+ * 支持商户自由迁出迁入。服务商行业形态多样（附近商圈/国内电商/垂直私域/网课/
+ * 订阅/技术服务），本文件把它们收敛成**一组必须实现的接口 + 每行业一个扩展点**。
+ *
+ * **成为 TrustBase 服务商 = 实现本文件里的 `ServiceProviderGateway`。**
+ *
+ * ## 本文件的纪律（与 @trustbase/protocol 全包一致）
+ *
+ * - **纯类型 + 接口 + 常量**：零实现、零依赖、零副作用，Node/浏览器通用。
+ * - 私钥、签名、网络、存储都不在这里（实现参考 trustbase-seller-backend）。
+ *
+ * ## 三层映射（每个接口方法都用 JSDoc 标注）
+ *
+ * | 层 | 含义 | 出处 |
+ * |---|---|---|
+ * | `@chain` | 链上对应 Msg / Query | trustchain-relmerge `proto/trustchain/serviceprovider/v1/*.proto` |
+ * | `@backend` | 后端对应路由/实现文件 | trustbase-seller-backend `routes/sp-*.js`、`payments/wechat/profitsharing.js` |
+ * | `@wechat` | 微信对应 APIv3 接口 | pay.weixin.qq.com 服务商/特约商户文档 |
+ *
+ * ## 设计依据（口径冲突以这些文档为准）
+ *
+ * - 《商户经济模型最终方案-2026-09-24》§六 迁移协议、§七之二 抽佣（30% 硬顶）
+ * - 《支付服务商子链实现规划-2026-09-21》（x/serviceprovider 模块落地口径）
+ * - 《行业扩展图景与国内合规红线-2026-09-23》（六行业判定 + 合规红线）
+ *
+ * ## 红线（实现者不可违反）
+ *
+ * 1. 商户私钥永不出商户设备；服务商只持有自己的 SP 签名 key。
+ * 2. 进件敏感资料本地加密留存，链上零 PII（只上 evidence_hash）。
+ * 3. 商户迁移不可阻拦：迁出导出是义务，不是功能选项。
+ * 4. 抽佣比例 ≤ 30% 硬顶（`SP_COMMISSION_HARD_CAP_BP`），登记公开、商户可查。
+ * 5. devreward 是链上奖励池发给服务商的，不挪用、不从商户扣。
+ */
+/** 链上 Msg type URL（逐条核对 trustchain/serviceprovider/v1/tx.proto） */
+export declare const SP_MSG_TYPE_URLS: {
+    /** 服务商注册：质押 + 绑定微信商户号（唯一性约束）。signer = provider 自己 */
+    readonly RegisterServiceProvider: "/trustchain.serviceprovider.v1.MsgRegisterServiceProvider";
+    /** 提交支付事实：仅 ACTIVE 服务商可提交，psp_txn_id 幂等防重 */
+    readonly SubmitPaymentFact: "/trustchain.serviceprovider.v1.MsgSubmitPaymentFact";
+    /** 踢出服务商 + 全额罚没。signer = authority（gov/emergency 双轨） */
+    readonly KickOutServiceProvider: "/trustchain.serviceprovider.v1.MsgKickOutServiceProvider";
+    /** 罚没质押但不踢出（惩罚性）。signer = authority */
+    readonly SlashServiceProvider: "/trustchain.serviceprovider.v1.MsgSlashServiceProvider";
+    /** 领取累计贡献奖励（credits）。signer = provider 自己 */
+    readonly ClaimProviderReward: "/trustchain.serviceprovider.v1.MsgClaimProviderReward";
+    /** 保障链 C5 确认支付事实 → 贡献分。signer = authority 或 params 白名单 */
+    readonly ConfirmPaymentFact: "/trustchain.serviceprovider.v1.MsgConfirmPaymentFact";
+};
+/** 链上 Query 端点（LCD REST，proto query.proto 的 google.api.http 注解） */
+export declare const SP_QUERY_ENDPOINTS: {
+    readonly Params: "/oxiaom/trustchain/serviceprovider/v1/params";
+    readonly ServiceProviders: "/oxiaom/trustchain/serviceprovider/v1/providers";
+    readonly ServiceProvider: "/oxiaom/trustchain/serviceprovider/v1/provider/{address}";
+    readonly PaymentFacts: "/oxiaom/trustchain/serviceprovider/v1/facts/{provider}";
+};
+/** 后端路由（trustbase-seller-backend 已实现，参考实现即官方服务商"无锡小播鼠"） */
+export declare const SP_BACKEND_ROUTES: {
+    /** 支付回调统一入口：验签→解密→幂等落账→上链→转发商户→分账。routes/sp-notify.js */
+    readonly NotifyWechat: "POST /api/sp/notify/wechat";
+    /** 进件资料上传（证件照 → 微信 media/upload）。routes/sp-applyment.js */
+    readonly ApplymentUpload: "POST /api/sp/applyment/upload";
+    /** 进件提交（→ 微信 applyment4sub）。routes/sp-applyment.js */
+    readonly ApplymentSubmit: "POST /api/sp/applyment/submit";
+    /** 进件状态查询（含 sign_url / sub_mchid / 驳回明细）。routes/sp-applyment.js */
+    readonly ApplymentStatus: "GET /api/sp/applyment/status/:business_code";
+    /** 抽佣比例登记/更新（admin，x-sp-admin-key）。routes/sp-commission.js */
+    readonly CommissionRatePut: "PUT /api/sp/commission-rate";
+    /** 抽佣比例商户自查（公开只读）。routes/sp-commission.js */
+    readonly CommissionRateGet: "GET /api/sp/commission-rate/:sub_mchid";
+};
+/** 微信支付 APIv3（服务商模式；网关 = https://api.mch.weixin.qq.com） */
+export declare const WECHAT_APIS: {
+    /** 图片/证件上传 → media_id */
+    readonly MediaUpload: "POST /v3/merchant/media/upload";
+    /** 特约商户进件提交 → applyment_id */
+    readonly ApplymentSubmit: "POST /v3/applyment4sub/applyment/";
+    /** 进件状态查询（按 business_code）→ applyment_state / sign_url / sub_mchid */
+    readonly ApplymentStatus: "GET /v3/applyment4sub/applyment/business_code/{business_code}";
+    /** 添加分账接收方 */
+    readonly ProfitsharingAddReceiver: "POST /v3/profitsharing/receivers/add";
+    /** 请求分账（out_order_no 幂等键） */
+    readonly ProfitsharingOrders: "POST /v3/profitsharing/orders";
+    /** 查询分账结果 */
+    readonly ProfitsharingQuery: "GET /v3/profitsharing/orders/{out_order_no}";
+};
+/**
+ * 服务商行业类型（决定商品模型 / 履约方式 / 结算周期的扩展点选择）。
+ * 依据《行业扩展图景与国内合规红线》六行业判定，映射为本框架六类：
+ * 外卖/打车等参数敏感行业归入 LOCAL_LIFE 并建议走服务包子链（x/subchain）。
+ */
+export declare enum SpIndustry {
+    /** 附近商圈/本地生活：核销码履约，即时或 T+1 结算，争议窗口短（可走子链独立参数） */
+    LOCAL_LIFE = "LOCAL_LIFE",
+    /** 国内电商实物：SKU 商品模型，物流履约，T+1 结算（v0 原生主战场） */
+    ECOMMERCE = "ECOMMERCE",
+    /** 垂直私域：社群/会员制实物或虚拟混合，履约按商户自定义 */
+    PRIVATE_DOMAIN = "PRIVATE_DOMAIN",
+    /** 网课/知识付费：章节商品模型，自动交付（license/兑换码上链防复制），一次性结算 */
+    COURSE = "COURSE",
+    /** 订阅制：周期扣款授权 + 按周期结算（国内注意：委托代扣本身要牌照，合规前置） */
+    SUBSCRIPTION = "SUBSCRIPTION",
+    /** 技术服务/软件：工时或许可证商品模型，API 交付 */
+    TECH_SERVICE = "TECH_SERVICE",
+    /** 其他：兜底类型，扩展点全自定义 */
+    OTHER = "OTHER"
+}
+/** 链上金额（utct 字符串，proto 口径；1 TCT = 1,000,000 utct） */
+export type UtctAmount = string;
+/** 微信侧金额（分，整数） */
+export type FenAmount = number;
+/** 商户/服务商链上地址（tct1... bech32） */
+export type TctAddress = string;
+/** 微信支付交易号（transaction_id） */
+export type PspTxnId = string;
+/** 订单引用（tb-xxxx 形态，与 seller-backend agent-pay 会话关联） */
+export type OrderRef = string;
+/** 微信特约商户号（sub_mchid） */
+export type SubMchId = string;
+/** 服务商链上状态（proto serviceprovider.proto:24 status 字段口径） */
+export declare enum SpStatus {
+    ACTIVE = "ACTIVE",
+    KICKED = "KICKED",
+    SLASHED = "SLASHED"
+}
+/** 支付事实链上状态（proto paymentfact.proto:30） */
+export declare enum PaymentFactStatus {
+    PENDING = "PENDING",
+    CONFIRMED = "CONFIRMED",
+    REJECTED = "REJECTED"
+}
+/**
+ * 服务商链上身份。镜像 proto `ServiceProvider`（serviceprovider.proto），
+ * 一个微信服务商商户号全链只能绑定一个服务商（唯一性约束）。
+ */
+export interface ServiceProviderIdentity {
+    /** 服务商链上地址（tct1...） */
+    readonly address: TctAddress;
+    /** 服务商名称（如"无锡小播鼠服务商"） */
+    readonly name: string;
+    /** 绑定的微信支付服务商商户号（唯一） */
+    readonly wechatMchid: string;
+    /** 质押 TCT（utct；作恶时按 params.slash_ratio 罚没，踢出默认 100%） */
+    readonly stake: UtctAmount;
+    /** 链上状态 */
+    readonly status: SpStatus;
+    /** 累计赚取 credits（ConfirmPaymentFact 每笔 +params.reward_per_fact） */
+    readonly creditsEarned: string;
+    /** 注册时间（unix 秒） */
+    readonly registeredAt: number;
+    /** 踢出时间（0 = 未踢出） */
+    readonly kickedAt: number;
+    /** 踢出原因 */
+    readonly kickReason: string;
+}
+/** 链上模块参数（proto params.proto；治理可写，MsgUpdateParams 双轨） */
+export interface ServiceProviderParams {
+    /** 注册最低质押（utct；初始 1,000,000,000 = 1000 TCT） */
+    minStake: UtctAmount;
+    /** 踢出罚没比例（per-10000，10000 = 100%） */
+    slashRatio: string;
+    /** 每笔确认支付事实的奖励积分（credits；初始 5） */
+    rewardPerFact: string;
+    /** 单服务商每日最大提交量（防刷） */
+    maxFactPerDay: string;
+    /** 单服务商同时在线最大子商户数 */
+    maxSubMerchants: string;
+    /** C5 确认人白名单（逗号分隔地址；gov/emergency 始终有权） */
+    confirmerAddresses: string;
+}
+export interface IdentityRegistry {
+    /**
+     * 链上注册服务商（质押真实托管进 x/serviceprovider 模块账户）。
+     * @chain MsgRegisterServiceProvider（tx.proto:50，signer = provider）
+     * @backend routes/agent-serviceprovider.js POST /api/agent/serviceprovider/register
+     * @wechat 前置条件：先拿到微信支付服务商资质（sp_mchid），本方法只绑不定资质
+     */
+    register(input: {
+        name: string;
+        wechatMchid: string;
+        stake: UtctAmount;
+    }): Promise<{
+        address: TctAddress;
+        txhash: string;
+    }>;
+    /**
+     * 查询自己/他人的链上身份与状态。
+     * @chain Query ServiceProvider（query.proto:23）
+     * @backend 无（直读 LCD）
+     * @wechat 无
+     */
+    getIdentity(address: TctAddress): Promise<ServiceProviderIdentity | null>;
+    /**
+     * 读取模块参数（最低质押/罚没比例/每日上限……实现前必读，别硬编码）。
+     * @chain Query Params（query.proto:14）
+     * @backend 无
+     * @wechat 无
+     */
+    getParams(): Promise<ServiceProviderParams>;
+    /**
+     * 领取累计贡献奖励（credits 清零入账）。
+     * @chain MsgClaimProviderReward（tx.proto:102，signer = provider）
+     * @backend 无（服务商自己的运营台发起）
+     * @wechat 无
+     */
+    claimReward(): Promise<{
+        claimed: string;
+        txhash: string;
+    }>;
+}
+/** 进件状态（微信 applyment_state 原样透传） */
+export declare enum ApplymentState {
+    EDITTING = "APPLYMENT_STATE_EDITTING",
+    AUDITING = "APPLYMENT_STATE_AUDITING",
+    REJECTED = "APPLYMENT_STATE_REJECTED",
+    TO_BE_CONFIRMED = "APPLYMENT_STATE_TO_BE_CONFIRMED",
+    TO_BE_SIGNED = "APPLYMENT_STATE_TO_BE_SIGNED",
+    SIGNING = "APPLYMENT_STATE_SIGNING",
+    FINISHED = "APPLYMENT_STATE_FINISHED",
+    CANCELED = "APPLYMENT_STATE_CANCELED"
+}
+/** 经营场景（微信 sales_scenes_type 三选一） */
+export declare enum SalesScene {
+    /** 线下门店（默认，需门头/店内照片） */
+    STORE = "SALES_SCENES_STORE",
+    /** 互联网网站（需已上线 + ICP 备案域名） */
+    WEB = "SALES_SCENES_WEB",
+    /** 公众号/小程序 */
+    MP = "SALES_SCENES_MP"
+}
+/**
+ * 进件表单（脱敏视角；敏感字段实现层用微信支付公钥 RSA-OAEP-SHA256 加密后上送）。
+ * 完整字段口径见 trustbase-seller-backend routes/sp-applyment.js buildApplymentBody()。
+ */
+export interface ApplymentForm {
+    /** 幂等键（TB{毫秒}{6位随机}，重复提交带同码直接返回已有 applyment_id） */
+    businessCode?: string;
+    subjectType: 'SUBJECT_TYPE_INDIVIDUAL' | 'SUBJECT_TYPE_ENTERPRISE';
+    salesScene: SalesScene;
+    merchantName: string;
+    merchantShortname: string;
+    licenseNumber: string;
+    legalName: string;
+    /** 敏感字段（contact/id_card/account 系列）在实现层加密，本类型不展开 */
+    sensitiveFieldsEncrypted: boolean;
+    /** 必备照片 media_id（执照/身份证正反面；STORE 场景另需门头+店内） */
+    mediaIds: Record<string, string>;
+    /** 结算类目（微信 settlement_id，如通用类目 716/719/727） */
+    settlementId: string;
+}
+export interface ApplymentResult {
+    businessCode: string;
+    applymentId: string;
+    state: ApplymentState;
+    /** 超管签约链接（TO_BE_SIGNED/SIGNING 态返回，发给商户扫码签约） */
+    signUrl: string;
+    /** 审核通过后微信分配的特约商户号 */
+    subMchid: SubMchId;
+    /** 驳回明细（field / field_name / reject_reason，必须原样展示给商户） */
+    auditDetail: ReadonlyArray<{
+        field: string;
+        fieldName: string;
+        rejectReason: string;
+    }>;
+}
+export interface OnboardingChannel {
+    /**
+     * 上传证件/门店照片拿 media_id（multipart，meta JSON 串参与签名）。
+     * @chain 无
+     * @backend POST /api/sp/applyment/upload（routes/sp-applyment.js）
+     * @wechat POST /v3/merchant/media/upload
+     */
+    uploadCredential(file: {
+        filename: string;
+        content: Uint8Array;
+    }): Promise<{
+        mediaId: string;
+    }>;
+    /**
+     * 提交进件申请（敏感字段本机/服务商侧公钥加密，HTTP 头带 Wechatpay-Serial=公钥ID）。
+     * @chain 无（进件是微信侧动作；商户链上注册另走卖家自己的 onboarding）
+     * @backend POST /api/sp/applyment/submit（routes/sp-applyment.js；mock: SP_APPLYMENT_MOCK=1）
+     * @wechat POST /v3/applyment4sub/applyment/
+     */
+    submitApplication(form: ApplymentForm): Promise<{
+        businessCode: string;
+        applymentId: string;
+    }>;
+    /**
+     * 查询进件状态（驳回原因必须透传给商户，不许吞）。
+     * @chain 无
+     * @backend GET /api/sp/applyment/status/:business_code
+     * @wechat GET /v3/applyment4sub/applyment/business_code/{business_code}
+     */
+    queryApplication(businessCode: string): Promise<ApplymentResult>;
+    /**
+     * sub_mchid 分配回调/轮询落定后，登记商户路由（链上地址 ↔ sub_mchid ↔ webhook）。
+     * @chain 无（台账动作；商户链上卖家注册由商户自己设备完成）
+     * @backend sp_sub_merchants 台账（routes/sp-notify.js ensureTables）
+     * @wechat 签约完成后微信侧生效
+     */
+    bindSubMerchant(binding: {
+        subMchid: SubMchId;
+        sellerAddress: TctAddress;
+        shopName: string;
+        /** 空 = 不转发支付结果（商户查单模式） */
+        webhookUrl?: string;
+    }): Promise<void>;
+}
+/**
+ * 下单请求的商品载荷按行业不同（见第 8 节行业扩展点），此处只约束公共字段。
+ * `payload` 的具体形态由 `IndustryExtension['product']` 决定。
+ */
+export interface CreateOrderInput<TProduct = unknown> {
+    industry: SpIndustry;
+    /** 商户侧订单号（幂等键） */
+    outTradeNo: string;
+    /** 金额（分） */
+    amountFen: FenAmount;
+    /** 行业商品载荷（SKU/章节/订阅计划/工时……） */
+    product: TProduct;
+    /** 买家标识（设备伪名，非实名） */
+    buyerHint?: string;
+}
+/** 解密后的支付事实（微信回调明文的最小必要子集，零 PII） */
+export interface VerifiedPayment {
+    txnId: PspTxnId;
+    outTradeNo: string;
+    /** 实付金额（分） */
+    amountFen: FenAmount;
+    subMchid: SubMchId;
+    tradeState: 'SUCCESS' | string;
+    /** 证据哈希口径（与 ShopXO 插件/agent-serviceprovider 一致）：sha256(order_ref + psp_txn_id + amount) */
+    evidenceHash: string;
+}
+export interface PaymentRail {
+    /**
+     * 按行业商品模型创建支付单（返回微信支付参数/二维码/调起串）。
+     * @chain 无（链上订单另由卖家设备 MsgCreateOrder，本接口只产生支付单）
+     * @backend agent-pay 下单通道（routes/agent-pay.js）
+     * @wechat JSAPI/Native/小程序下单（服务商模式带 sp_mchid + sub_mchid）
+     */
+    createPayment<TProduct>(input: CreateOrderInput<TProduct>): Promise<{
+        outTradeNo: string;
+        /** 支付调起参数（形态随支付产品而定） */
+        payPayload: Record<string, string>;
+    }>;
+    /**
+     * 支付回调处理：平台证书验签 → AES-256-GCM 解密 → 幂等（txn_id 主键）→
+     * 非 SUCCESS 不落账。验签/解密失败回 4xx/5xx 让微信重试，后续步骤失败一律回 200。
+     * @chain 间接产生 MsgSubmitPaymentFact（见 submitPaymentFact）
+     * @backend POST /api/sp/notify/wechat（routes/sp-notify.js:145）
+     * @wechat 支付结果通知（平台证书验签 + APIv3 key 解密 resource）
+     */
+    handleNotify(rawBody: string, headers: {
+        signature: string;
+        serial: string;
+        timestamp: string;
+        nonce: string;
+    }): Promise<{
+        accepted: boolean;
+        payment?: VerifiedPayment;
+        ignoredReason?: string;
+    }>;
+    /**
+     * 支付事实上链（失败 warn 不阻塞商户回调，台账留空由 retryPending 定时补链）。
+     * @chain MsgSubmitPaymentFact（tx.proto:63，signer = provider；仅 ACTIVE 可提交）
+     * @backend routes/sp-notify.js submitPaymentFactToChain() + retryPending()
+     * @wechat 无（数据源是回调明文，链上零 PII 只存 evidence_hash）
+     */
+    submitPaymentFact(payment: VerifiedPayment): Promise<{
+        txhash: string;
+    } | {
+        deferred: true;
+    }>;
+    /**
+     * 查单（回调不可达场景的兜底，每 2 分钟主动查单模式同样走本接口语义）。
+     * @chain 无
+     * @backend agent-pay 查单通道（routes/agent-pay.js）
+     * @wechat 微信支付订单查询（by out_trade_no / transaction_id）
+     */
+    queryPayment(outTradeNo: string): Promise<VerifiedPayment | null>;
+    /**
+     * 支付结果转发商户 webhook（3s 超时，结果记台账 forward_status）。
+     * @chain 无
+     * @backend routes/sp-notify.js 第 7 步转发
+     * @wechat 无
+     */
+    forwardToMerchant(merchant: {
+        webhookUrl: string;
+    }, payment: VerifiedPayment): Promise<'ok' | 'failed' | 'none'>;
+}
+/**
+ * 抽佣硬顶：万分比 3000 = 30%（微信平台分账上限，《商户经济模型最终方案》§七之二 定稿）。
+ * 链上 params 对齐同值；超出必须拒绝（422），mock 模式护栏同样生效。
+ */
+export declare const SP_COMMISSION_HARD_CAP_BP = 3000;
+/** 抽佣比例登记（rate_bp 万分比：150 = 1.50%） */
+export interface CommissionRate {
+    subMchid: SubMchId;
+    /** 万分比整数，0..3000 */
+    rateBp: number;
+    /** 人性化展示（"1.50%"），商户后台可见 */
+    ratePct: string;
+    updatedAt: number;
+}
+/** 分账回单（微信分账是执行通道：自动、实时、有回单可证；不做线下私下结算） */
+export interface ProfitsharingReceipt {
+    /** 分账单号（out_order_no，幂等键，建议 "ps-" + txn_id） */
+    outOrderNo: string;
+    transactionId: PspTxnId;
+    /** 分账金额（分），护栏：≤ 交易金额 × 30% */
+    amountFen: FenAmount;
+    receiverAccount: string;
+    /** mock=true 表示 WXPAY_PROFITSHARING_ENABLED 未开，未真调微信 */
+    mock: boolean;
+}
+export interface CommissionPolicy {
+    /**
+     * 登记/更新抽佣比例（admin 鉴权；比例登记公开是商户比价的权利）。
+     * @chain v3.9.6 计划：ServiceProvider proto 加 commission_rate 字段上链；v0 先 indexer/台账登记
+     * @backend PUT /api/sp/commission-rate（routes/sp-commission.js，x-sp-admin-key）
+     * @wechat 无
+     */
+    registerRate(subMchid: SubMchId, rateBp: number): Promise<CommissionRate>;
+    /**
+     * 商户自查当前比例（公开只读，未登记 404）。
+     * @chain 同上（v3.9.6 后链上可查）
+     * @backend GET /api/sp/commission-rate/:sub_mchid
+     * @wechat 无
+     */
+    getRate(subMchid: SubMchId): Promise<CommissionRate | null>;
+    /**
+     * 支付成功后按登记比例触发分账（fire-and-forget，失败只 warn 不阻塞回调）。
+     * @chain 分账结果（分账单号+比例）随支付事实证据留存，商户可对账
+     * @backend routes/sp-notify.js maybeTriggerProfitsharing() → payments/wechat/profitsharing.js
+     * @wechat POST /v3/profitsharing/receivers/add + POST /v3/profitsharing/orders
+     */
+    executeProfitsharing(payment: VerifiedPayment, rate: CommissionRate): Promise<ProfitsharingReceipt>;
+}
+/**
+ * 标准迁移包（《商户经济模型最终方案》§六 迁移协议）：
+ * 换服务商 = 换供应商，不是搬家。链上状态（商品/订单/信誉/KYC 标记）自动跟随商户地址，
+ * 本包只承载 off-chain 内容；content_hash 供新服务商校验完整性。
+ */
+export interface SpMigrationPackage {
+    version: string;
+    sellerAddress: TctAddress;
+    /** 旧服务商地址（信息性，不构成任何审批权） */
+    fromProvider: TctAddress;
+    exportedAt: number;
+    /** off-chain 内容（结构化 JSON：店铺配置/商品详情页素材/物流模板……） */
+    offChainContent: Record<string, unknown>;
+    /** 内容哈希（canonical JSON → sha256，口径同 @trustbase/protocol bundle-hash） */
+    contentHash: string;
+    /** KYC 原件转交凭据（跟人不跟服务商；按商户授权转交，链上只记 evidence_hash + level） */
+    kycTransferEvidence?: string;
+}
+export interface MigrationSupport {
+    /**
+     * 迁出导出（义务接口）：商户要包必须给，不可阻拦、不可扣留。
+     * @chain 链上状态零迁移（锚定商户地址天然可携带）
+     * @backend SDK tb-migrate 导出侧（S4；参考 config/export-import.js 的配置导出形态）
+     * @wechat 无
+     */
+    exportMigrationPackage(sellerAddress: TctAddress): Promise<SpMigrationPackage>;
+    /**
+     * 迁入导入：校验 content_hash → 落库 → 商户在新服务商重新进件（sub_mchid 会换）。
+     * @chain 同上
+     * @backend SDK tb-migrate 导入侧
+     * @wechat 迁入后重新走 OnboardingChannel（新服务商主体下重新进件）
+     */
+    importMigrationPackage(pkg: SpMigrationPackage): Promise<{
+        imported: true;
+    }>;
+    /**
+     * feegrant 切换：旧服务商 revoke + 新服务商新发（AllowedMsgAllowance 白名单 + 双限额）。
+     * 质押切换走链上 redelegate：即时生效，资金不解锁、不等 21 天。
+     * @chain MsgRevokeAllowance + MsgGrantAllowance（cosmos feegrant）；redelegate（staking）
+     * @backend 冷启动 feegrant 三道闸实现（seller-backend feegrant 模块）
+     * @wechat 无
+     */
+    switchFeegrant(input: {
+        sellerAddress: TctAddress;
+        newProvider: TctAddress;
+    }): Promise<{
+        revoked: string;
+        granted: string;
+    }>;
+}
+/** 结算周期形态（按行业不同） */
+export declare enum SettlementCycleKind {
+    /** 实物电商：确认收货后 T+N（默认 T+1） */
+    T_PLUS_N = "T_PLUS_N",
+    /** 订阅制：按订阅周期结算 */
+    PERIODIC = "PERIODIC",
+    /** 课程/虚拟商品：交付即结算（一次性） */
+    ONE_SHOT = "ONE_SHOT",
+    /** 本地生活：核销即结算（即时或当日） */
+    ON_REDEMPTION = "ON_REDEMPTION",
+    /** 技术服务：里程碑/验收结算 */
+    MILESTONE = "MILESTONE"
+}
+export interface SettlementRule {
+    kind: SettlementCycleKind;
+    /** T_PLUS_N 的 N（天）；其他形态忽略 */
+    delayDays?: number;
+    /** PERIODIC 的周期（天） */
+    periodDays?: number;
+    /** 争议窗口（小时）：窗口内资金冻结；外卖等即时行业必须显著短于默认 3 天（→ 服务包子链独立参数） */
+    disputeWindowHours: number;
+    /** 行业特定的补充说明（实现层自由文本，进商户协议） */
+    notes?: string;
+}
+export interface SettlementPolicy {
+    /**
+     * 给出某行业某商户的结算规则（进件时明示，写进商户协议）。
+     * @chain 结算锚定走 escrow/订单状态机（x/order）；参数敏感行业走 x/subchain 子链参数
+     * @backend 无独立路由（随订单/回调流程生效）
+     * @wechat 微信侧实际结算周期以微信支付协议为准，本规则是链上 escrow 释放口径
+     */
+    ruleFor(industry: SpIndustry, subMchid?: SubMchId): SettlementRule;
+}
+/** 退款规则（行业差异：实物有退货物流，虚拟/课程交付后原则上不退，订阅按剩余周期折算） */
+export interface RefundPolicy {
+    /** 交付后是否可退 */
+    refundableAfterDelivery: boolean;
+    /** 退款窗口（小时，自支付/交付起算，口径自选并写进 notes） */
+    windowHours: number;
+    /** 部分退款支持（按比例/按章节/按剩余周期……） */
+    partialRefund: boolean;
+    notes?: string;
+}
+/** 附近商圈/本地生活扩展 */
+export interface LocalLifeExtension {
+    /** 商品模型：券/套餐（核销次数、有效期、适用门店） */
+    product: {
+        voucherSkuId: string;
+        redemptionCount: number;
+        validDays: number;
+        storeIds: string[];
+    };
+    /** 履约：核销码（买家出示 → 商户扫码核销 → 链上确认） */
+    fulfillment: {
+        kind: 'REDEMPTION_CODE';
+        codeTtlMinutes: number;
+    };
+    refund: RefundPolicy;
+}
+/** 国内电商实物扩展（v0 原生主战场） */
+export interface EcommerceExtension {
+    /** 商品模型：多规格 SKU（spu + sku 列表，单件质押 CHAIN_STAKE_PER_UNIT） */
+    product: {
+        spuId: string;
+        skus: ReadonlyArray<{
+            skuId: string;
+            attrs: Record<string, string>;
+            priceFen: FenAmount;
+            stock: number;
+        }>;
+    };
+    /** 履约：物流（物流事实卖家推送，保障链 C5 结合支付事实判 NORMAL/WASH） */
+    fulfillment: {
+        kind: 'LOGISTICS';
+        carrier?: string;
+        trackingNo?: string;
+    };
+    refund: RefundPolicy;
+}
+/** 垂直私域扩展（社群/会员制，实物虚拟混合） */
+export interface PrivateDomainExtension {
+    /** 商品模型：任意（引用实物或虚拟模型之一） */
+    product: {
+        ref: 'ECOMMERCE' | 'COURSE' | 'CUSTOM';
+        customSchema?: Record<string, unknown>;
+    };
+    /** 履约：按引用模型；私域特有的是触达通道（群/私信），不进本框架 */
+    fulfillment: {
+        kind: 'LOGISTICS' | 'AUTO_DELIVERY' | 'CUSTOM';
+    };
+    refund: RefundPolicy;
+}
+/** 网课/知识付费扩展 */
+export interface CourseExtension {
+    /** 商品模型：课程 → 章节（试看章节标记、时长、资料附件哈希） */
+    product: {
+        courseId: string;
+        chapters: ReadonlyArray<{
+            chapterId: string;
+            title: string;
+            preview: boolean;
+            durationSec?: number;
+        }>;
+    };
+    /** 履约：自动交付（license/兑换码；交付凭据上链防复制）；结业证书链上凭证可选 */
+    fulfillment: {
+        kind: 'AUTO_DELIVERY';
+        licenseKey?: string;
+        certificateOnChain?: boolean;
+    };
+    refund: RefundPolicy;
+}
+/** 订阅制扩展 */
+export interface SubscriptionExtension {
+    /** 商品模型：订阅计划（周期、档位、首期优惠） */
+    product: {
+        planId: string;
+        intervalDays: number;
+        tier?: string;
+        trialDays?: number;
+    };
+    /** 履约：周期开通权益；扣款授权上链（周期扣款授权 msg）
+     *  ⚠️ 合规前置：国内微信"委托代扣"本身要牌照，未取得前不得上线扣款 */
+    fulfillment: {
+        kind: 'RECURRING_ENTITLEMENT';
+        deductionAuthMsg?: string;
+    };
+    refund: RefundPolicy;
+}
+/** 技术服务/软件扩展 */
+export interface TechServiceExtension {
+    /** 商品模型：工时包/许可证/里程碑 */
+    product: {
+        offeringId: string;
+        unit: 'HOUR' | 'LICENSE' | 'MILESTONE';
+        quantity: number;
+    };
+    /** 履约：API 交付（key 签发/额度开通/工单验收） */
+    fulfillment: {
+        kind: 'API_DELIVERY';
+        deliveryEndpoint?: string;
+        acceptanceRequired?: boolean;
+    };
+    refund: RefundPolicy;
+}
+/** 兜底：自定义扩展 */
+export interface OtherExtension {
+    product: Record<string, unknown>;
+    fulfillment: {
+        kind: 'CUSTOM';
+        description: string;
+    };
+    refund: RefundPolicy;
+}
+/** SpIndustry → 扩展接口映射（实现网关时用本类型约束扩展载荷） */
+export interface IndustryExtensionMap {
+    [SpIndustry.LOCAL_LIFE]: LocalLifeExtension;
+    [SpIndustry.ECOMMERCE]: EcommerceExtension;
+    [SpIndustry.PRIVATE_DOMAIN]: PrivateDomainExtension;
+    [SpIndustry.COURSE]: CourseExtension;
+    [SpIndustry.SUBSCRIPTION]: SubscriptionExtension;
+    [SpIndustry.TECH_SERVICE]: TechServiceExtension;
+    [SpIndustry.OTHER]: OtherExtension;
+}
+/**
+ * 服务商网关聚合接口。六个核心接口全部必须实现（迁移支持是义务不是选项），
+ * 行业扩展点按自己服务的行业至少实现一个。
+ *
+ * 参考实现（官方服务商"无锡小播鼠"）：trustbase-seller-backend 的
+ * routes/sp-notify.js / sp-applyment.js / sp-commission.js / payments/wechat/profitsharing.js。
+ */
+export interface ServiceProviderGateway {
+    /** ① 链上身份：注册/质押/参数/领奖 */
+    readonly identity: IdentityRegistry;
+    /** ② 进件通道：资料上传/提交/状态/sub_mchid 绑定 */
+    readonly onboarding: OnboardingChannel;
+    /** ③ 支付通道：下单/回调验签解密/支付事实上链/查单/转发 */
+    readonly payment: PaymentRail;
+    /** ④ 抽佣分账：比例登记公开 + 微信分账执行（≤30% 硬顶） */
+    readonly commission: CommissionPolicy;
+    /** ⑤ 迁移支持：迁出导出/迁入导入/feegrant 切换（不可阻拦） */
+    readonly migration: MigrationSupport;
+    /** ⑥ 结算规则：按行业给出结算周期与争议窗口 */
+    readonly settlement: SettlementPolicy;
+}
+/** 行业化网关 = 通用网关 + 某行业的扩展点实现 */
+export interface IndustryGateway<I extends SpIndustry> extends ServiceProviderGateway {
+    readonly industry: I;
+    readonly extension: IndustryExtensionMap[I];
+}
+//# sourceMappingURL=sp-framework.d.ts.map