docs: 完善 webhook 事件载荷与订阅指南 - #386
Open
rcsh1 wants to merge 9 commits into
Open
Conversation
Reconstructed from ~/.workmate/playbook-traces/run_8d40a6d96746/events.jsonl (25 captured Edit/Write ops replayed). Worktree was deleted on success before the changes were committed; all real doc edits recovered intact.
…0a6d96746 # Conflicts: # docs.json
- CN upgrade-guide.mdx: restore WaaS 2.0 API operation names to English (Create wallet, Create addresses in wallet, Transfer token, Speed up transaction, Drop transaction, Cancel transaction, Call smart contract, Sign message, List all transactions, Get transaction information) - transfer-routing.mdx EN+CN: add note clarifying force_internal / force_external are mutually exclusive, and add JSON code examples showing force-Cobo-Loop, force-on-chain, and default routing - status.mdx EN+CN: update FailedSignerTimeout remedy to specify retry operation by original transaction type (Transfer token / Call smart contract / Sign message) instead of always pointing to Transfer token Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Collaborator
Author
|
关联 product-manual PR：CoboGlobal/product-manual#754 |
Collaborator
Author
运行过程记录（自动生成）本评论记录本次 doc 运行的内部过程，便于审查每个结论的来源。 1. 意图（确认后）来源：Phabricator T96128（https://pha.1cobo.com/T96128）。任务及其交易历史通过 mcp-now Phabricator bridge 直接获取；最新描述取代了较早的措辞变更，且没有其他讨论评论。
2. 探索发现（按仓库 × explorer）原始探索 findings 总量超过 GitHub 单条评论限制。本节按规范截断为每个 explorer 的 handoff_brief 摘要，并保留关键 code_evidence；完整 findings 保存在本次运行产物中，未静默省略。 custody × explorer codexhandoff_brief：主要改动应进入 developer-site，而非 product-manual。新增 EN/CN 成对的 Transaction payload、TSSRequest payload 与场景订阅指南，并更新 code_evidence： custody × explorer claudehandoff_brief：确认 tasks 3–9 的核心 runtime 行为：updated 对每个已处理变更触发，终态额外触发 succeeded/failed；common dispatcher 不按 initiator/category 过滤，因此 AutoSweep 与 Portal-originated transactions 走同一路径。endpoint 以 organization channel 注册。payload/schema 与 retention 的初步探索存在缺口，要求在写作前进一步核对 TSS modules、wire names 与外部 webhook service。 code_evidence： custody-2.0-website × explorer codexhandoff_brief：Portal frontend 只确认 UI 与 API 调用，不是 payload/runtime source of truth。Portal 注册每个 endpoint 时要求 event selection 和 wallet scope；事件详情页展示完整 data 与 delivery attempts，并允许 Failed/Retrying 事件 resend。Frontend 的 30-day filters 不能证明 storage TTL。 code_evidence： custody-2.0-website × explorer claudehandoff_brief：确认 Portal-facing statuses、resend action、retryLeft/retryable 与逐次 WebhookAttemptsTable。tasks 1–8 的事件常量、serializer 和 dispatch 仍需 custody backend。task 10 多数基础 retry/timeout 文案已存在，应只补 retention、recovery 和已验证的 UI 路径。 code_evidence： developer-site-waas2 × explorer codexhandoff_brief：spec-source 确认公开 inventory 与 model wiring，但不能单独证明 runtime triggers。应在 developer-site 新增三组成对指南；任何 API wording/example 修改都必须从 developer-site-waas2 source YAML 发起。本次无需 API spec 编辑。 code_evidence： developer-site-waas2 × explorer claudehandoff_brief：确认 code_evidence： cobo-libs × explorer codexhandoff_brief：cobo-libs 仅保存并原样提交 producer-supplied opaque payload，可证明 organization channel scope、history/log/retry proxy，不能证明 Transaction/TSSRequest 内容或 delivery worker 的 retry/TTL。相关运行时事实应来自 custody 与外部 webhook service。 code_evidence： cobo-libs × explorer claudehandoff_brief：确认 custody 只向外部 webhook service 提交一次；服务 REST surface 提供 list events、event logs、manual retry，endpoint/subscription 以 code_evidence： 3. 综合结论result：这十项诉求构成一个连贯的文档问题，而非十个孤立缺陷：客户缺少一套可发现的契约，把 event names、payload shapes、transaction state、subscription choices 与 delivery recovery 串联起来。主目标是 developer-site，并保持 v2/v2_cn 对等；新增 Transaction payload、MPC TSSRequest payload、场景订阅指南三组成对内容，更新导航与现有 webhook/status/setup/introduction 页面。product-manual 只承担 Portal 注册、事件详情、delivery attempts 与 resend 的 EN/CN 说明。公开 OpenAPI inventory 与 backend runtime evidence 足以支持最终批准范围；未核实的 universal threshold、KYT、unexpected deposit、retry/backoff、per-endpoint state 与 storage TTL 均从发布内容中排除。无需修改 API spec。 confidence：0.91 open_questions：
汇总代码证据：
4. 编辑计划[{"task_id":"webhook-payload-wallets-transaction-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/wallets-transaction-payload.mdx","repo_alias":"primary","doc_edit_description":"Create the English wallets.transaction payload reference. Enumerate created, updated, succeeded, and failed triggers; document the full webhook envelope and shared Transaction field semantics; explain conditional source, destination, fee, raw_tx_info, token_id, asset_id, result, request_id, replacement, and cobo_category values; include complete deposit and withdrawal JSON examples covering EVM, UTXO, and TRON plus native-coin and token cases. Link to existing source/destination, RBF, status, and category guides. Do not claim the configured confirmation-threshold invariant until separately verified.","code_evidence":["custody/waas2/webhooks/data/enums.py:20","custody/waas2/webhooks/managers/wallet_event.py:33","custody/waas2/webhooks/managers/wallet_event_by_source.py:51","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:178","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:469","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:504","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:597","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:620","custody/waas2/transactions/mongo/manager/write/fields/token.py:15"],"code_evidence_missing":false},{"task_id":"webhook-payload-wallets-transaction-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/wallets-transaction-payload.mdx","repo_alias":"primary","doc_edit_description":"Create the Chinese counterpart of the wallets.transaction payload reference with the same trigger table, complete field coverage, scenario matrix, JSON examples, and language-local links. Keep all event, field, status, and enum identifiers in English.","code_evidence":["custody/waas2/webhooks/data/enums.py:20","custody/waas2/webhooks/managers/wallet_event.py:33","custody/waas2/webhooks/managers/wallet_event_by_source.py:51","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:178","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:597","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:620"],"code_evidence_missing":false},{"task_id":"webhook-payload-wallets-transaction-index-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","doc_edit_description":"Link every wallets.transaction event row and the data-structure section to the new Transaction payload reference so the schema, triggers, and complete examples are discoverable.","code_evidence":["custody/waas2/webhooks/data/enums.py:20","custody/waas2/webhooks/managers/wallet_event.py:33"],"code_evidence_missing":false},{"task_id":"webhook-payload-wallets-transaction-index-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","doc_edit_description":"Mirror the English event-index links to the Chinese Transaction payload reference.","code_evidence":["custody/waas2/webhooks/data/enums.py:20","custody/waas2/webhooks/managers/wallet_event.py:33"],"code_evidence_missing":false},{"task_id":"webhook-payload-wallets-mpc-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/wallets-mpc-tss-request-payload.mdx","repo_alias":"primary","doc_edit_description":"Create the English TSSRequest webhook payload reference for wallets.mpc.tss_request.created, updated, succeeded, and failed. Give exact producer scope, state-to-event triggers including suppressed intermediate states, a complete field table with nullable fields, public statuses, and realistic full JSON examples.","code_evidence":["custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:21","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:26","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:110","custody/waas2/mpc/bo/dev/vault.py:235","custody/waas2/mpc/enums/dev/mpc_vault.py:175"],"code_evidence_missing":false},{"task_id":"webhook-payload-wallets-mpc-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/wallets-mpc-tss-request-payload.mdx","repo_alias":"primary","doc_edit_description":"Create the Chinese counterpart of the TSSRequest payload reference with identical trigger, field, nullability, status, and complete-example coverage. Preserve all identifiers in English.","code_evidence":["custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:21","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:26","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:110","custody/waas2/mpc/bo/dev/vault.py:235","custody/waas2/mpc/enums/dev/mpc_vault.py:175"],"code_evidence_missing":false},{"task_id":"webhook-payload-wallets-mpc-index-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","doc_edit_description":"Link each wallets.mpc.tss_request event row to the new TSSRequest payload reference and make clear that this is the supported wallets.mpc event family.","code_evidence":["custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:21","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:26"],"code_evidence_missing":false},{"task_id":"webhook-payload-wallets-mpc-index-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","doc_edit_description":"Mirror the English MPC event-index links and supported-family clarification in Chinese.","code_evidence":["custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:21","custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:26"],"code_evidence_missing":false},{"task_id":"callback-payload-field-semantics-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/wallets-transaction-payload.mdx","repo_alias":"primary","doc_edit_description":"Add the owning field-semantics section: webhook data uses TransactionDetail; distinguish token_id from nullable asset_id; explain lifecycle-dependent cobo_id, request_id, result, source/destination variants, replacement hashes, and AutoSweep. Use the public wire field names, including replaced_by_transaction_hash, in examples.","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:51","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:178","custody/waas2/transactions/mongo/manager/write/fields/token.py:15","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:430","custody/waas2/transactions/mongo/enums/transaction_fields.py:45"],"code_evidence_missing":false},{"task_id":"callback-payload-field-semantics-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/wallets-transaction-payload.mdx","repo_alias":"primary","doc_edit_description":"Mirror the Transaction callback/webhook field-semantics section in Chinese, preserving public field and enum identifiers in English.","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:51","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:178","custody/waas2/transactions/mongo/manager/write/fields/token.py:15","custody/waas2/transactions/mongo/manager/read/waas_transaction.py:430","custody/waas2/transactions/mongo/enums/transaction_fields.py:45"],"code_evidence_missing":false},{"task_id":"webhook-crediting-readiness-en","action":"fix_docs","doc_file":"v2/guides/transactions/status.mdx","repo_alias":"primary","doc_edit_description":"Connect transaction statuses to webhook semantics: Confirming is nonterminal progress reported through updated; Completed/Success additionally produces succeeded and is the positive completion signal. Link to the subscription guide. Do not publish an absolute confirmed_num-versus-confirming_threshold guarantee until the owning transition code is verified.","code_evidence":["custody/waas2/transactions/dev/enums/transaction.py:220","custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},{"task_id":"webhook-crediting-readiness-cn","action":"fix_docs","doc_file":"v2_cn/guides/transactions/status.mdx","repo_alias":"primary","doc_edit_description":"Mirror the verified Confirming/updated and Completed/succeeded relationship and subscription-guide link in Chinese, without adding the unverified threshold invariant.","code_evidence":["custody/waas2/transactions/dev/enums/transaction.py:220","custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},{"task_id":"webhook-subscription-deposit-crediting-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/transaction-event-subscriptions.mdx","repo_alias":"primary","doc_edit_description":"Create the English scenario guide and add a deposit auto-crediting recipe: use succeeded/Completed as the positive crediting signal, created and updated for progress, failed plus status/sub_status for rejection/failure, relevant compliance events for KYT state, idempotent processing, and API reconciliation. Do not claim every compliance-blocked deposit emits failed or that every such path suppresses all webhooks until the remaining KYT paths are verified.","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116","custody/waas2/transaction_query/enums/transaction_query.py:48","custody/waas2/transactions/dev/views/transaction_by_id.py:35"],"code_evidence_missing":false},{"task_id":"webhook-subscription-deposit-crediting-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/transaction-event-subscriptions.mdx","repo_alias":"primary","doc_edit_description":"Create the Chinese counterpart and mirror the verified deposit crediting, progress, rejection/failure, compliance, idempotency, and reconciliation guidance while omitting unverified universal KYT behavior.","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116","custody/waas2/transaction_query/enums/transaction_query.py:48","custody/waas2/transactions/dev/views/transaction_by_id.py:35"],"code_evidence_missing":false},{"task_id":"webhook-subscription-withdrawal-status-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/transaction-event-subscriptions.mdx","repo_alias":"primary","doc_edit_description":"Add a withdrawal progression and event matrix for PendingAuthorization, Broadcasting, Confirming, Completed, Rejected, and Failed. Recommend subscriptions and state that Portal/API withdrawals share mapping, every processed change produces updated, Completed additionally produces succeeded, and Guard/reviewer rejection appears as Rejected with failed plus the relevant sub_status.","code_evidence":["custody/waas2/transactions/dev/enums/transaction.py:220","custody/waas2/transaction_query/handlers/withdraw_request.py:337","custody/waas2/transaction_query/enums/transaction_query.py:48","custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},{"task_id":"webhook-subscription-withdrawal-status-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/transaction-event-subscriptions.mdx","repo_alias":"primary","doc_edit_description":"Mirror the withdrawal status-to-event matrix, recommended subscriptions, Portal/API parity, and rejection handling in Chinese.","code_evidence":["custody/waas2/transactions/dev/enums/transaction.py:220","custody/waas2/transaction_query/handlers/withdraw_request.py:337","custody/waas2/transaction_query/enums/transaction_query.py:48","custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},{"task_id":"webhook-subscription-event-overlap-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","doc_edit_description":"Replace the ambiguous updated-only note with an overlap matrix: updated is attempted for every processed transition; created is additional on creation; succeeded and failed are additional terminal notifications. Explain that updated-only consumers must inspect payload status, while dedicated terminal events are clearer; retain the existing non-guaranteed ordering and deduplication guidance by cross-link.","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},{"task_id":"webhook-subscription-event-overlap-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx","repo_alias":"primary","doc_edit_description":"Mirror the event-overlap matrix and subscription tradeoff in Chinese; do not imply payload containment or delivery ordering.","code_evidence":["custody/waas2/webhooks/managers/wallet_event_by_source.py:25","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},{"task_id":"webhook-subscription-boundary-scenarios-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/transaction-event-subscriptions.mdx","repo_alias":"primary","doc_edit_description":"Add verified boundary rows for AutoSweep and Portal-originated withdrawals: both use the common transaction event path, with AutoSweep identified by cobo_category=AutoSweep and Portal/API withdrawals sharing state mapping. Omit a categorical unexpected-deposit row until its detection path and exceptions are traced.","code_evidence":["custody/waas2/transactions/mongo/enums/transaction_fields.py:45","custody/waas2/transactions/mongo/manager/write/fields/cobo_category.py:149","custody/waas2/transaction_query/handlers/withdraw_request.py:337","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},{"task_id":"webhook-subscription-boundary-scenarios-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/transaction-event-subscriptions.mdx","repo_alias":"primary","doc_edit_description":"Mirror the verified AutoSweep and Portal-originated withdrawal boundary rows in Chinese and omit the unresolved unexpected-deposit claim.","code_evidence":["custody/waas2/transactions/mongo/enums/transaction_fields.py:45","custody/waas2/transactions/mongo/manager/write/fields/cobo_category.py:149","custody/waas2/transaction_query/handlers/withdraw_request.py:337","custody/waas2/webhooks/managers/wallet_event_by_source.py:116"],"code_evidence_missing":false},{"task_id":"webhook-subscription-scope-and-reconciliation-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/introduction.mdx","repo_alias":"primary","doc_edit_description":"Explain that each endpoint is configured once for its organization with selected event types and an optional wallet scope. Add the notification-plus-reconciliation pattern: deduplicate deliveries by event_id, reconcile transactions by transaction_id, and use cobo_id, request_id, or hash where appropriate with Get transaction information/List all transactions.","code_evidence":["custody/waas2/webhooks/controller/webhook_endpoint.py:22","custody/waas2/transactions/dev/views/transaction_by_id.py:35","custody/waas2/transactions/dev/bo/transaction_query/transaction.py:159"],"code_evidence_missing":false},{"task_id":"webhook-subscription-scope-and-reconciliation-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/introduction.mdx","repo_alias":"primary","doc_edit_description":"Mirror the organization ownership, selected-event/wallet scope, deduplication, and transaction reconciliation guidance in Chinese.","code_evidence":["custody/waas2/webhooks/controller/webhook_endpoint.py:22","custody/waas2/transactions/dev/views/transaction_by_id.py:35","custody/waas2/transactions/dev/bo/transaction_query/transaction.py:159"],"code_evidence_missing":false},{"task_id":"webhook-subscription-scope-portal-en","action":"fix_docs","doc_file":"en/portal/developer-console/webhooks-create.mdx","repo_alias":"alt-docs","alt_docs_repo":"product-manual","doc_edit_description":"Update the English Portal registration flow to explain one configuration per endpoint, organization ownership, required event selection, and the Portal wallet-scope selection shown by the current UI. Link to Developer Hub for payload and reconciliation behavior.","code_evidence":["custody/waas2/webhooks/controller/webhook_endpoint.py:22","custody-2.0-website/src/pages/Developers/Webhooks/AddOrWebhooksModal/index.tsx:215"],"code_evidence_missing":false},{"task_id":"webhook-subscription-scope-portal-cn","action":"fix_docs","doc_file":"cn/portal/developer-console/webhooks-create.mdx","repo_alias":"alt-docs","alt_docs_repo":"product-manual","doc_edit_description":"Mirror the Portal endpoint, organization, event-selection, wallet-scope, and Developer Hub link updates in Chinese.","code_evidence":["custody/waas2/webhooks/controller/webhook_endpoint.py:22","custody-2.0-website/src/pages/Developers/Webhooks/AddOrWebhooksModal/index.tsx:215"],"code_evidence_missing":false},{"task_id":"webhook-delivery-operations-en","action":"fix_docs","doc_file":"v2/guides/webhooks-callbacks/set-up-endpoint.mdx","repo_alias":"primary","doc_edit_description":"Make a targeted operations revision rather than a rewrite. Preserve the existing verified success codes, timeout, published attempt limits, ordering, duplicate, log, and resend guidance; add the public 30-day List all webhook events window and a recovery flow using event detail/logs, manual retry, and canonical transaction reconciliation. Do not add retry schedule/backoff, total-attempt semantics, endpoint-independent retry claims, or storage-TTL claims until the external delivery service is verified; do not confuse the 30-day public window with custody's seven-day staging cleanup.","code_evidence":["custody/waas2/webhooks/client/client.py:206","custody/waas2/webhooks/views/event_retries.py:19","custody/waas2/transactions/dev/views/transaction_by_id.py:35","developer-site-waas2/v2/cobo_waas2_openapi_spec/paths/webhooks/events.yaml:6","custody/waas2/webhooks/managers/wallet_event.py:153"],"code_evidence_missing":false},{"task_id":"webhook-delivery-operations-cn","action":"fix_docs","doc_file":"v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx","repo_alias":"primary","doc_edit_description":"Mirror the targeted 30-day event-query window and recovery/reconciliation workflow in Chinese, retaining existing delivery guidance and omitting unverified delivery-service mechanics.","code_evidence":["custody/waas2/webhooks/client/client.py:206","custody/waas2/webhooks/views/event_retries.py:19","custody/waas2/transactions/dev/views/transaction_by_id.py:35","developer-site-waas2/v2/cobo_waas2_openapi_spec/paths/webhooks/events.yaml:6","custody/waas2/webhooks/managers/wallet_event.py:153"],"code_evidence_missing":false},{"task_id":"webhook-delivery-operations-portal-en","action":"fix_docs","doc_file":"en/portal/developer-console/webhook-events.mdx","repo_alias":"alt-docs","alt_docs_repo":"product-manual","doc_edit_description":"Expand the English Portal event-history page with the verified event detail, delivery-attempt log, Failed/Retrying resend flow, and 30-day API query window. Link to Developer Hub for full recovery and reconciliation guidance; do not state a Portal storage TTL or retry backoff.","code_evidence":["custody-2.0-website/src/pages/Developers/Events/Detail/index.tsx:125","custody-2.0-website/src/pages/Developers/Events/Detail/index.tsx:160","developer-site-waas2/v2/cobo_waas2_openapi_spec/paths/webhooks/events.yaml:6"],"code_evidence_missing":false},{"task_id":"webhook-delivery-operations-portal-cn","action":"fix_docs","doc_file":"cn/portal/developer-console/webhook-events.mdx","repo_alias":"alt-docs","alt_docs_repo":"product-manual","doc_edit_description":"Mirror the Portal event detail, attempt-log, resend, 30-day query-window, and Developer Hub recovery-link updates in Chinese.","code_evidence":["custody-2.0-website/src/pages/Developers/Events/Detail/index.tsx:125","custody-2.0-website/src/pages/Developers/Events/Detail/index.tsx:160","developer-site-waas2/v2/cobo_waas2_openapi_spec/paths/webhooks/events.yaml:6"],"code_evidence_missing":false},{"task_id":"webhook-reference-navigation","action":"fix_docs","doc_file":"docs.json","repo_alias":"primary","doc_edit_description":"Register the two new payload references and transaction-event subscription guide in the existing Webhooks and callbacks groups for both v2 and v2_cn, preserving parallel ordering and the current information architecture.","code_evidence":[],"code_evidence_missing":false}]5. 评审轮次第 1 轮：未批准反馈：修正 第 2 轮：未批准反馈：主 payload examples 与 repo 内 OpenAPI wire schema 不一致。所有 第 3 轮：primary revision 已批准反馈：10 项 reviewer findings 均已修复并完成 EN/CN 镜像。created wording、terminal mapping、nullable 第 4 轮：alt-docs 已批准反馈： 6. 基线与同步
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
关联来源
意图
补充 Custody/WaaS 2.0 的
wallets.transaction.*与wallets.mpc.tss_request.*webhook 载荷参考，覆盖触发条件、字段语义和完整示例。明确交易事件的重叠关系、充值入账与提现状态订阅策略，并补充 endpoint 作用域、重试恢复和 API 对账指引。中英文内容保持同步，所有结论均基于已确认的实现或公开规范。变更摘要
docs.json：在中英文 Webhooks and callbacks 导航中注册两个载荷参考页和交易事件订阅指南。v2/guides/webhooks-callbacks/wallets-transaction-payload.mdx：新增wallets.transaction.*英文载荷参考，说明事件触发、字段语义及跨链完整示例。v2_cn/guides/webhooks-callbacks/wallets-transaction-payload.mdx：新增对应中文载荷参考，并保持字段和枚举标识符不变。v2/guides/webhooks-callbacks/wallets-mpc-tss-request-payload.mdx：新增wallets.mpc.tss_request.*英文载荷参考，说明状态映射、可空字段和完整示例。v2_cn/guides/webhooks-callbacks/wallets-mpc-tss-request-payload.mdx：新增对应中文载荷参考，并同步触发条件与字段说明。v2/guides/webhooks-callbacks/transaction-event-subscriptions.mdx：新增英文场景订阅指南，覆盖充值入账、提现状态、AutoSweep、Portal 发起交易和 API 对账。v2_cn/guides/webhooks-callbacks/transaction-event-subscriptions.mdx：新增对应中文场景订阅指南。v2/guides/webhooks-callbacks/webhook-event-type.mdx：补充英文载荷参考链接及 created、updated、succeeded、failed 的事件重叠关系。v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx：同步中文事件索引、载荷链接和事件重叠说明。v2/guides/webhooks-callbacks/introduction.mdx：说明英文 endpoint 的组织与钱包作用域，以及事件去重和交易对账方式。v2_cn/guides/webhooks-callbacks/introduction.mdx：同步中文 endpoint 作用域、去重和对账指引。v2/guides/webhooks-callbacks/set-up-endpoint.mdx：补充英文 30 天事件查询窗口及详情、日志、重试和交易对账恢复流程。v2_cn/guides/webhooks-callbacks/set-up-endpoint.mdx：同步中文事件查询窗口和恢复流程。v2/guides/transactions/status.mdx：关联英文交易状态与updated、succeededwebhook 语义。v2_cn/guides/transactions/status.mdx：同步中文交易状态与 webhook 语义。关联 PR
product-manual中 4 个中英文 Portal webhook 页面由后续步骤单独创建 PR，并以评论形式回链本 PR。代码证据
custody/waas2/webhooks/data/enums.py:20与custody/waas2/webhooks/managers/wallet_event.py:33：确认交易事件名称为 created、updated、succeeded、failed，并组成wallets.transaction.<event_name>。custody/waas2/webhooks/managers/wallet_event_by_source.py:25与custody/waas2/webhooks/managers/wallet_event_by_source.py:116：确认每次已处理的交易变更会尝试发送 updated，创建和终态会额外发送对应事件。custody/waas2/webhooks/managers/wallet_event_by_source.py:51与custody/waas2/transactions/mongo/manager/read/waas_transaction.py:178：确认 webhook 复用公开TransactionDetail，并包含文档列出的交易字段。custody/waas2/transactions/mongo/manager/read/waas_transaction.py:430、:469、:504、:597、:620：确认 replacement、source、destination、fee 与 raw_tx_info 的条件化结构。custody/waas2/transactions/mongo/manager/write/fields/token.py:15：确认token_id是链上币种标识，asset_id来自unique_asset_id且可为空。custody/waas2/transactions/mongo/enums/transaction_fields.py:45与custody/waas2/transactions/mongo/manager/write/fields/cobo_category.py:149：确认cobo_category包含AutoSweep，并用于自动归集交易。custody/waas2/mpc/managers/dev/webhook_wallet_mpc.py:21、:26、:110：确认wallets.mpc.tss_request的事件清单、状态触发规则和TSSRequest载荷结构。custody/waas2/mpc/bo/dev/vault.py:235与custody/waas2/mpc/enums/dev/mpc_vault.py:175：确认TSSRequest字段可空性及公开状态集合。custody/waas2/transactions/dev/enums/transaction.py:220与custody/waas2/transaction_query/handlers/withdraw_request.py:337：确认公开交易状态以及 Portal/API 提现共用的状态映射。custody/waas2/transaction_query/enums/transaction_query.py:48：确认 Success、Rejected、Canceled、Failed 终态及 KYT/审核拒绝子状态。custody/waas2/webhooks/controller/webhook_endpoint.py:22：确认 endpoint 归属请求组织，并保存 URL、订阅事件和可选钱包范围。custody/waas2/transactions/dev/views/transaction_by_id.py:35与custody/waas2/transactions/dev/bo/transaction_query/transaction.py:159：确认交易详情和列表 API 可用于标识符对账。custody/waas2/webhooks/client/client.py:206与custody/waas2/webhooks/views/event_retries.py:19：确认事件详情、日志及手动重试由公开接口委托 webhook 服务处理。developer-site-waas2/v2/cobo_waas2_openapi_spec/components/schemas/webhooks/event_type.yaml:3：确认公开规范列出 4 个 transaction 事件和 4 个mpc.tss_request事件。developer-site-waas2/v2/cobo_waas2_openapi_spec/components/schemas/webhooks/transaction_event_data.yaml:1与developer-site-waas2/v2/cobo_waas2_openapi_spec/components/schemas/wallets/mpcs/tss_request.yaml:1：确认 webhook 数据分别复用Transaction与TSSRequestschema。developer-site-waas2/v2/cobo_waas2_openapi_spec/paths/webhooks/events.yaml:6：确认 List all webhook events 提供最近 30 天的事件。无