在 HarmonyOS 应用里接入 @wps/wps_sdk 做文档二开时，联调最容易卡在「能编译、能调到接口，但不知道失败该看哪里」。打开失败、注册失败、关窗回传失败，表面都是「没成功」，落在 Result 上却是不同语义。本文按调用链把 Result.code、Result.msg、Result.data 拆开看，区分 reject（抛异常） 与 resolve（带错误码），覆盖注册、打开、关闭回传三阶段，并给出可落地的日志与检查清单。字段含义以官方对接实践为准，表述按工程联调习惯重写。

一、失败在调用链上的落点

典型时序是：应用启动完成 registerApp → 业务侧构造 OpenFileRequest → WPSApi.sendRequest 拉起 WPS → 用户预览或编辑 →（若开启回传）关窗后 Promise 落定，result.data 可能带文件信息。

错误并不只出现在「打开那一下」。建议按层归因，而不是把所有非零 code 都当成同一种「打开异常」：

阶段	主要入口	失败常见表现
注册	registerApp / 注册类请求	code=1013 或其它非 OK；凭据与包名问题
打开前	尚未注册成功就 sendRequest	抛异常（不是带 code 的 Result）
打开	OpenFileRequest + sendRequest	多为 ResultCode.ERROR（-2）
关闭回传	开启回传后的关窗结果	code 为业务侧正整数，或 OK 但 data 需再校验

一次堆满水印、回传、可编辑再联调时，-2 很难归因。建议顺序：注册到 OK → 沙箱路径只读打开 → 再开编辑与回传。

二、Result 结构：先读字段再谈常量

sendRequest 在多数已注册场景下会 resolve 一个 Result，即便业务失败也是如此。因此「Promise 成功」不等于「业务成功」。需要同时看：

字段	作用
requestType	产生该结果的请求类型，便于日志归类
code	状态码，与 ResultCode 常量对照
msg	可读说明，适合直接进埋点/Toast（注意脱敏）
data	业务数据；关闭回传成功时常见 fileUri / transferFd 等

ResultData 侧常见字段包括 fileUri、parameters、transferFd、transferFileName、transferFileSize、extraData。回传路径拿到后，应按对接要求拷贝到本应用沙箱再消费，不要假设 URI 长期可读。

常量与场景对照（联调备忘）：

code	常量	场景	含义（工程表述）
0	ResultCode.OK	通用	成功
-1	ResultCode.NONE	通用	默认值，勿当成功
-2	ResultCode.ERROR	通用	参数错误、不支持的请求、打开异常等
1013	ResultCode.ERROR_CODE_AUTH_FAILURE	注册	接入凭据校验失败
其它正整数	—	关闭回传	回传失败时的业务错误码
抛异常	—	sendRequest	应用尚未注册成功

三、注册层：1013 与「先注册后打开」

凭据校验失败时，注册回调 / 注册请求的 Result 会给出 ERROR_CODE_AUTH_FAILURE（1013）。工程上优先核对：appKey / appSecret 是否为空或粘贴错误、当前 bundleName 是否与申请凭据一致、调试包与正式包是否共用了不匹配的凭据、换 HAR 后是否未 clean 导致旧包名残留。

另一类致命错误是：在 registerApp 尚未到 ResultCode.OK 时就调用打开类 sendRequest。对接实践明确此时会 抛异常，不会给你一个「打开失败」的 code。因此业务封装里要有「就绪门闩」，UI 在未就绪时禁用打开按钮，冷启动在 Application 或入口 Ability 完成注册。

import { common } from '@kit.AbilityKit';
import { WPSApi, Result, ResultCode, SdkConstants } from '@wps/wps_sdk';

let wpsReady = false;

function bootstrapRegister(activationSn?: string): void {
  WPSApi.registerApp(APP_KEY, APP_SECRET, {
    onCallback: (result: Result) => {
      if (result.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
        console.error(`auth 1013: ${result.msg ?? ''}`);
        wpsReady = false;
        return;
      }
      if (result.code !== ResultCode.OK) {
        console.error(`register fail code=${result.code} msg=${result.msg}`);
        wpsReady = false;
        return;
      }
      // 形态判定 API：当前形态若需要激活序列号，在 OK 后注入
      if (activationSn) {
        WPSApi.setWpsFileToken(activationSn);
      }
      // 也可用 SdkConstants 侧 checker 决定是否注入序列号
      void SdkConstants;
      wpsReady = true;
    }
  });
}

说明：用回调风格把「注册结果」收口到 wpsReady。1013 单独打点，避免和参数类 -2 混在同一告警桶。需要序列号的形态在 OK 后再 setWpsFileToken，不要拖到构造 OpenFileRequest 时再猜。

四、打开层：ERROR(-2) 与路径/参数

注册成功后，打开失败多数落在 ResultCode.ERROR（-2）。常见诱因包括：构造参数不完整、路径不可读、请求类型或参数组合不被支持、打开过程异常。联调时不要只看 code，把 msg、requestType、当时的 enableEdit / 回传开关一并写入日志。

路径建议：系统选择器拿到的 URI，先拷贝到应用沙箱（如 context.filesDir），再传给 OpenFileRequest。直接传外部 URI 时，权限不足往往直接变成 -2，文案却未必写清「权限」。enableEdit 未设或为 false 时默认只读；若业务期望可编辑却忘记置 true，用户侧像「打不开编辑」，日志里却可能是 OK——这属于能力语义，不是错误码问题，但应在验收清单里单独列项。

import { common } from '@kit.AbilityKit';
import { WPSApi, OpenFileRequest, Result, ResultCode } from '@wps/wps_sdk';

async function openSandboxDoc(
  context: common.UIAbilityContext,
  sandboxPath: string,
  editable: boolean
): Promise<Result> {
  if (!wpsReady) {
    throw new Error('WPS not registered; refuse sendRequest');
  }
  const request = new OpenFileRequest(context, sandboxPath);
  request.enableEdit = editable;
  try {
    const result = await WPSApi.sendRequest(request);
    if (result.code === ResultCode.OK) {
      return result;
    }
    console.error(
      `open fail type=${result.requestType} code=${result.code} msg=${result.msg}`
    );
    return result;
  } catch (e) {
    // 未注册等：走异常通道，不要当成 ResultCode.ERROR
    console.error(`sendRequest threw: ${(e as Error).message}`);
    throw e;
  }
}

说明：业务层必须同时处理 .then/await 的非 OK，以及 catch 中的抛异常。把「未注册」在入口提前拦截，可减少线上难复现的 throw。

五、关闭回传：正整数业务码与 data

开启关闭回传后，成功判定要分场景：用户关窗且回传成功时 code=0，data 中有回传内容；未开启回传时，成功拉起即可 code=0 且 data 常为空；回传失败时 code 为非 0，关闭回传场景下常见 正整数业务错误码。

因此不要把「任意正整数」一律映射成「打开失败」。日志里应用阶段标签区分 register / open / transfer。消费 data.fileUri 或 FD 字段前，先确认 code === ResultCode.OK，再做沙箱拷贝与业务入库。

六、日志与埋点建议

建议每条 SDK 结果固定打四元组：stage、requestType、code、msg（截断）。另加布尔：wpsReady、enableEdit、transferEnabled。1013、-2、回传正整数分三个监控项。异常通道单独计数 sendRequest_throw。Release 禁止打印完整 appSecret。

七、联调清单与小结

联调可按下列清单自检：

1. HAR 与 bundleName、凭据是否同一套申请记录
2. registerApp 是否已到 ResultCode.OK，wpsReady 是否为真
3. 是否出现过 1013，若是则先修凭据而非改打开参数
4. 选择器文件是否已拷入沙箱再构造 OpenFileRequest
5. enableEdit 是否符合产品预期（默认只读）
6. sendRequest 是否同时处理非 OK 的 Result 与 throw
7. 开启回传时，非 0 正整数是否按「回传失败」归因，并检查 data
8. 形态相关激活是否在注册 OK 后通过形态判定 / SdkConstants checker 决定注入

小结：鸿蒙侧 WPS 二开排错的核心，不是背一张大表，而是分清 异常通道 与 Result 通道，再按注册 / 打开 / 回传三阶段读 code。把 msg 与 data 纳入同一套日志，1013、-2、回传正整数就不会再搅在一起。按本文分层落地封装后，联调耗时通常会从「到处改参数」变成「按阶段打勾」。

---

基于 WPS Open SDK 鸿蒙版对接实践整理，仅供开发者参考。
官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT