# 对接可靠性、安全与排错

## 为什么这样设计

- **Cookie 复用**：星空用服务端会话；每次新建连接不携带 Cookie 会表现为「随机过期」。
- **业务错误不重试**：`IsSuccess=false` 重试可能重复建单；只对超时/5xx 做有限退避。
- **分页**：ExecuteBillQuery 大结果集一次拉全会拖垮网关与内存。
- **单会话非线程安全**：多线程共用一个 `K3CloudApi` 会串会话；要么每线程一会话，要么串行化调用。

## 安全与审计

- `app_secret` / `password` 加密存储，日志脱敏；生产用 HTTPS。
- 写操作记录 formId、单据号、结果；可选 `request_id` 贯穿日志。

## 常见问题

| 现象 | 常见原因 | 处理方向 |
|------|----------|----------|
| 登录失败 | 账套/应用配置错误 | 核对 acct_id、app_id、app_secret |
| 会话过期 | 未复用 Cookie | 同一客户端实例登录后调用 |
| FormId 无效 | 拼写或未安装模块 | QueryBusinessInfo / 业务对象查询 |
| 字段错误 | FieldKey 不对 | View 单据结构 |
| 保存失败基础资料 | 引用编码不存在 | 核对 FNumber；或联调期关 IsVerifyBaseDataField |
| 审核失败 | 未先 Submit | Submit 后再 Audit |
| 下推失败 | 源单未审核 | 状态 C 再 Push |

FormId、RuleId 目录仅为示例，**以当前账套为准**。