chore: 导入旧记忆备份供恢复

projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/天河链官方文档勘误与联调坑.md

@@ -0,0 +1,31 @@
+---
+title: 天河链官方文档勘误与联调坑
+type: experience
+permalink: main/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/天河链官方文档勘误与联调坑
+stable_id: 92e5c8d9-c4ef-4ab7-99ac-1b81f3228b59
+scope: project
+memory_type: experience
+project_id: d44c219a-0b31-4de1-b160-323eb34a4c6a
+usage_profile_id: 7aee455b-24cc-4008-bdaf-443721e6f939
+status: active
+revision: 1
+request_id: artveris-migrate-2026-09-03-exp-01
+created_at: '2026-09-03T03:44:33.692130+00:00'
+updated_at: '2026-09-03T03:44:33.692130+00:00'
+tags:
+- blockchain
+- tianhe
+- pitfall
+---
+
+勿被官方文档（语雀版）误导，以 APIFox 在线文档 + 实测为准：
+- 交易详情接口（接口5）真实路径 `/api/v2/nfr/transaction/detail`（语雀少 `/nfr`）。
+- 确认接口（接口9）是 GET 但参数放 JSON 请求体（query 会报 "request body missing"），需用 `node:http/https` 底层发带 body 的 GET，appKey 不进 URL；`status` 语义 "0x0"=成功否则失败。
+- upload 的 multipart 必须手工构造：whatwg FormData+Blob 会被 undici 强加 filename 导致 500；userDto 分段需“无 filename + Content-Type: application/json”。
+- publish 的 `operateId` 限 20 字符；name≤42、author≤120、feature≤500。
+- 确认接口对纯存证 upload 交易结构性返回 `500 "Index: 3, Size: 1"`（非偶发），仅对 token 交易有效。
+- 发行可能返回 tokenId=-1，需确认后回填。
+- 接口成功只代表交易已提交，不代表链上最织确认；实测 mint 提交同秒即可查到进块。
+- 严格校验 `code===0` 且 publish 必须返回交易哈希，否则走 FAILED，杜绝用本地 dataHash 冒充链上哈希的“假上链”。
+- 本地 `/uploads/` 相对路径不能直接写链（feature），发行前以 BASE_URL 转绝对地址。
+- 天河请求/响应/异常文本与持久化 raw 必须脱敏 appKey/userKey/newUserKey（先脱敏再截断）。