docs: 补充 MPC 钱包余额可用性模型、资金锁定与 BTC/UTXO 说明并优化 12007/30010 错误码指引

[rcsh1]

意图

根据 developer 文档仓库中 7 个工单（严重程度：medium，反复出现的理解混淆，confidence 0.87，时间跨度 2026-01 至 2026-04）识别出的 7 个文档问题，集中在账户余额可用性如何建模以及资金如何被锁定这两方面。本次变更主要在 balance-amounts.mdx 中补充余额可用性模型、资金锁定、BTC/UTXO 相关说明、支付余额类型以及「余额不足」排查指引，并优化错误码 12007/30010 的描述与处理建议。

变更摘要

• v2/guides/mpc-wallets/balance-amounts.mdx：新增「Balance availability model」（映射 using_amount/locked_amount/spendable 到公开字段 data.balance.pending/locked/available 并给出 spendable 计算公式）、「Fund locking」（创建即锁定、释放条件、UTXO 跨地址并发锁定）、「Bitcoin and UTXO considerations」（充币后索引延迟导致可用余额为 0、按代币配置的尘埃阈值与错误 30010、UTXO 归集建议）、「Payment balances」（total = available + frozen）以及「Troubleshooting insufficient balance」决策树，解决工单反映的余额不足却无法定位、UTXO 提币失败、错误码含义不清等问题。
• v2_cn/guides/mpc-wallets/balance-amounts.mdx：同步上述全部新增章节的简体中文版本，章节锚点与术语与英文版对应。
• snippets/error-codes.mdx：完善错误码 12007/30012 的处理建议（区分当前余额与可用余额、链接到 balance-amounts 指南、提示极小金额可能改为 30010），并补充 30010 描述（尘埃阈值按代币配置、与 12007 的区别）。
• snippets/error-codes-cn.mdx：同步 12007/30012 与 30010 的简体中文描述。

API spec edits: 无（未改动任何 OpenAPI/spec 源文件）。
API spec sync: 无。

待确认事项

以下事实在文档中被有意省略或以保守措辞处理，合入前需人工与代码/规范核实其权威性：

1. BTC/UTXO 充币后索引服务：文档仅说明「索引完成前可用余额可能为 0」，但具体的索引/解析服务名称与预期延迟时长未在代码中核实，故未写入。
2. 单笔交易最大 UTXO 输入数：工单提及约 400 个上限及超限错误码，但未经代码确认，文档未给出具体数值，仅以「归集小额 UTXO」建议替代。
3. 尘埃阈值默认值（约 800 sats）：文档采用「按代币配置」的表述，未写入具体数值，需核实确切默认值及是否按链可配置。
4. dust_threshold 是否经公开 API 暴露：当前 v2 get-token-information 未暴露该字段；文档未声称可通过 API 查询，需确认是否有其他公开接口暴露。
5. 支付（Payment）字段命名与文档归属：total/available/frozen 三类余额的公开规范字段名，以及 MPC 钱包余额指南是否为其正式归属页面（还是仅交叉链接），需与 Payment 公开规范核对。
6. spendable 计算公式对外暴露的安全性：spendable = 链上余额 - using_amount - 待合规筛查金额 - 净冻结金额 是否适合对外部开发者公开，需确认。

备注：本次运行的 mintlify validate 退出码为 1，唯一告警来自 docs.json 导航中预先存在的 v2/api-references/autosweep/cancel-auto-sweep-task-by-id 引用，与本 PR 改动的 4 个文件无关。

[cobosteven]

Verdict: REQUEST_CHANGES

事实核查未发现任何被伪造或错误的 error code，双语一致性也确认 12007、30012、30010 及全部新增章节在 EN/CN 两侧均成对存在。但仍有 4 项 must_fix 未解决，因此建议 REQUEST_CHANGES。

1. 【must_fix】snippets/error-codes.mdx 与 snippets/error-codes-cn.mdx，条目 12007, 30012

   描述仍只复述余额不足错误，未解释校验机制：请求会按扣除 pending、locked、合规筛查与 frozen 后的 available/spendable 余额判断，而不是按 current/total 余额。请补充「交易金额 + 手续费」会与 available/spendable 比较，pending/locked/合规筛查/frozen 部分不可用，因此 current/total 充足时仍可能触发 12007。

2. 【must_fix】snippets/error-codes.mdx 与 snippets/error-codes-cn.mdx，条目 12007, 30012

   解决方案只要求确保来源地址有足够 available 余额并链接 MPC 余额指南，缺少可执行排查路径。请补充完整请求侧校验，例如对 List token balances by address 的 curl 调用，并说明将返回的 available 与「提币金额 + 手续费」比较；或给出等效完整公开 API/Portal 流程。

3. 【must_fix】snippets/error-codes.mdx 与 snippets/error-codes-cn.mdx，条目 30010

   解决方案要求开发者把金额提高到代币 dust threshold 之上，但没有给出如何确定该阈值。请给出查询 per-token dust threshold 的完整公开 API/curl 来源；若没有公开来源，应明示并改写为可执行替代排查动作，而不是只要求「提高金额」。

4. 【must_fix】v2_cn/guides/mpc-wallets/balance-amounts.mdx，新增章节「余额可用性模型」

   /v2/api-references/wallets/list-token-balances-by-address 的 API operation name 被翻译为「按地址列出代币余额」。中文文档中 API operation name 应保持英文，请改为 List token balances by address。

[cobosteven]

Verdict: REQUEST_CHANGES

本次文档 PR 在 balance-amounts.mdx（EN/CN）补充的余额可用性模型、资金锁定与 BTC/UTXO 说明结构清晰，且事实核验未发现伪造或写错的错误码。但还有 3 个 must_fix 阻断问题需要先修复：12007/30012 与 30010 的解决方案在 EN/CN 两侧均缺少可执行的完整 curl 命令或精确 Portal 点击路径，且 CN 版 Fund locking 将 "coin selection" 误译为「币种选择」导致 UTXO 选币含义错误。建议 REQUEST_CHANGES。

[must_fix] snippets/error-codes.mdx 与 snippets/error-codes-cn.mdx 条目 12007, 30012：解决方案不可执行。 当前仅指引调用 List token balances by address 并在 Cobo Portal 中打开源地址查看，缺少完整的 curl 命令或精确的 Portal 点击路径。修复：补全包含必要 headers/占位符与路径参数的完整 curl 示例，或给出精确的 Portal 点击路径（EN 与 CN 两侧均需补全）。

[must_fix] snippets/error-codes.mdx 与 snippets/error-codes-cn.mdx 条目 30010：解决方案不可执行。 当前仅提示调用 Get token information 并以更大金额重试，缺少完整 curl 命令、必需路径参数 token_id、headers/占位符，以及需要比对的响应字段 dust_threshold。修复：给出完整可执行的 Get token information 调用示例（含 token_id），并明确说明如何用返回的 dust_threshold 判定最小可发送金额（EN 与 CN 两侧均需补全）。

[must_fix] v2_cn/guides/mpc-wallets/balance-amounts.mdx，Fund locking 章节：误译。 EN 原文 "when coin selection spans more than one address" 被译为「当币种选择跨越多个地址时」，将 UTXO 选币（coin selection）误解为币种/代币选择，技术含义错误。修复：改为「当选币/UTXO 选择跨越多个地址时」之类表述。
_{🤖 自动文档 PR 独立审查(doc-pr-review)。}

[rcsh1]

Addressed all three must-fix items from the latest review in commit 9a893d3f:

1. 12007, 30012 executable troubleshooting: Updated snippets/error-codes.mdx:11 and snippets/error-codes-cn.mdx:13 with a complete List token balances by address GET example, including wallet_id and address, the required Biz-Api-* headers, and guidance for reading data[].balance.available. The text now distinguishes same-token fees (compare available balance with withdrawal amount plus expected fee) from separate fee tokens (check principal and fee balances separately), and calls out the Custodial Wallet wallet-level evaluation caveat. Verified against custody/waas2/base/urls_dev.py:72, custody/waas2/base/views/dev/wallet_address_token_balances.py:39, custody/waas2/authentications/universal_access_control/authentications/api_key_authentication.py:56, custody/waas2/base/controllers/dev/wallet_balances.py:187, custody/waas2/base/bo/dev/wallet_balance.py:7, custody/custody/web3/controllers/request_builder/portal_mpc_transaction_request_builder.py:586, and custody/waas2/transfer/managers/custodial/asset/utils.py:244.

2. 30010 executable threshold lookup: Updated snippets/error-codes.mdx:25 and snippets/error-codes-cn.mdx:27 with a complete Get token information GET example, including the required token_id path parameter and Biz-Api-* headers. The instructions identify dust_threshold, explain that it is returned in display units, and state that the transfer amount must be greater than or equal to it. Verified against custody/waas2/base/urls_dev.py:55, custody/waas2/base/views/dev/tokens.py:28, custody/waas2/base/controllers/dev/tokens.py:167, custody/cobo/utils/__init__.py:52, and custody/waas2/transfer/managers/custodial/asset/utils.py:353.

3. UTXO coin-selection translation: Replaced “当币种选择跨越多个地址时” with “当选币/UTXO 选择跨越多个地址时” in v2_cn/guides/mpc-wallets/balance-amounts.mdx:86.

No item was deferred.

运行过程记录（自动生成）

• 读取的评审意见与修订要点（来自 revision brief）：核对了最新 review summary 中的三项 must-fix；分别为补全 12007, 30012 的可执行余额排查、补全 30010 的可执行尘埃阈值查询，以及修正 Fund locking 中 coin selection 的中文译法。内联 review comments 与 issue-level comments 均为空。
• 代码核查结论与证据（repo/path:line，如有）：地址余额接口路由和 GET 参数见 custody/waas2/base/urls_dev.py:72、custody/waas2/base/views/dev/wallet_address_token_balances.py:39；鉴权 headers 见 custody/waas2/authentications/universal_access_control/authentications/api_key_authentication.py:56；返回路径 data[].balance.available 见 custody/waas2/base/controllers/dev/wallet_balances.py:187、custody/waas2/base/bo/dev/wallet_balance.py:7；代币信息路由与 dust_threshold 见 custody/waas2/base/urls_dev.py:55、custody/waas2/base/controllers/dev/tokens.py:167；显示单位转换见 custody/cobo/utils/__init__.py:52；amount < dust_threshold 才触发 30010、等于阈值可接受，见 custody/waas2/transfer/managers/custodial/asset/utils.py:353。
• 本次推送的改动（来自 git log -1 --stat）：commit 9a893d3fd2567f48e110610e238907a491e079db（docs: address review feedback）；修改 snippets/error-codes-cn.mdx、snippets/error-codes.mdx、v2_cn/guides/mpc-wallets/balance-amounts.mdx，共 3 files changed, 5 insertions(+), 5 deletions(-)。
• 同步基线：a8ad72ddedd1676dad804f6fe444bce0795c76ab