51 lines
64 KiB
JSON
51 lines
64 KiB
JSON
{"role":"user","message":{"content":[{"type":"text","text":"<timestamp>Wednesday, Jun 10, 2026, 10:50 AM (UTC+8)</timestamp>\n<user_query>\n评审docs 下面的USTD.md 需求\n</user_query>"}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" I'm looking at the USTD.md file in the docs folder."},{"type":"tool_use","name":"Glob","input":{"glob_pattern":"**/docs/**/USTD*.md"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"Read","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"我已通读 `docs/requirements/USTD.md`（crypto-pay 第一期：USDT-TRC20 自建收款）。整体结构完整、边界清晰、幂等和私钥安全意识到位。下面按严重程度给出评审意见。\n\n## 一、与团队分层规范冲突（必须先对齐）\n\n文档第 11、25 节定义的分层是 `Service + Model + Command + Support`，由 **Service 承载业务流程编排**。这与本仓库强制的 `backend-layering` 规则直接冲突：\n\n- 规则要求：`Controller → Validate → DTO → Logic → Service → Model`，其中 **Logic 才是业务用例入口/流程编排/事务控制**，**Service 只放公共能力**（SDK、跨服务调用、公共计算），禁止承载单业务用例编排。\n- 文档把 `TronDepositScanService / TronDepositConfirmService / CryptoNotifyService` 等编排逻辑都放进 Service，等于规则里明令禁止的「Logic 型 Service」。\n- 文档完全没有 **Validate 层和 DTO 层**，但规则要求参数校验在 Validate、已校验入参用 DTO 承载。\n\n建议：\n- 把「业务流程编排」改名/归位到 `app/{api,admin}/logic/`（如 `CryptoDepositLogic`、`TronAddressLogic`），事务边界放 Logic。\n- Service 仅保留真正的公共能力：`TronClient` 网关封装、`CryptoNotifyService`（跨服务调 pay，建议走 slot_sdk/Gateway）、`AmountConverter`、`PrivateKeyEncryptor`。\n- 补 Validate + DTO 章节。\n\n这一条会影响目录、命名和验收口径，应在动工前定稿。\n\n## 二、核心业务风险（高优先级）\n\n1. **固定地址 + 按金额匹配订单 = 撞单风险**（第 5.3、16.3 节）\n 一个用户一个固定地址被所有充值复用，pay 仅靠 `uid + pay_address + amount` 匹配待支付订单。若用户同时存在两笔相同金额的待支付订单，或先后多次充值，金额无法唯一区分订单，匹配会错乱或落入异常。\n 建议明确二选一：① 订单金额加随机尾数（如 ±0.0x USDT）保证金额唯一；② 既然地址已绑定 uid，链上到账直接按 uid 入账而非强绑订单。当前「按金额精确匹配」是最脆弱点。\n\n2. **用户直接向旧地址充值（无待支付订单）被判异常**（第 6.3 节第 4 条）\n 地址是长期固定的，用户很可能不走下单流程直接打币。文档将其判为异常等人工处理，体验差。加密充值惯例是「认地址即认人，直接入账」。需明确产品决策：是否允许「无订单入账」。\n\n3. **链上扫描方式与性能**（第 17.1 节）\n 「按区块范围扫描 TRC20-USDT Transfer 事件再过滤 to_address」在 USDT（全链最活跃合约）上每个区块事件量极大，TronGrid 拉全量事件再本地过滤成本和限流压力都很高。\n 建议改为**按用户地址轮询**（TronGrid `/v1/accounts/{address}/transactions/trc20`），只查系统地址的入账，数据量和 QPS 都可控；游标可退化为「每地址 last_tx_timestamp/last_block」。当前游标表是单一全局游标，与按地址轮询不匹配，需重新设计。\n\n4. **区块重组（reorg）未处理**\n 扫描应只处理 `latest_block - safe_gap` 以内、或在确认数累计期间校验 tx 仍在主链。否则 tip 附近写入的 tx 在重组后可能失效，但确认数仍在累加。建议明确「安全确认间隔」和「确认期内校验 tx 仍存在」。\n\n5. **金额换算的截断精度**（第 7 节）\n `system_amount = raw_amount / 1000` 是整数除法：USDT 6 位小数、系统 3 位小数，低于 0.001 USDT 的部分被截断（例 `1000500`→`1000`）。需明确取整策略（截断/四舍五入），且这直接影响第二点的金额匹配是否相等。\n\n## 三、数据表问题\n\n- **缺少 `min_confirm_count` 的存储**：第 8 节给出配置项形态，但 5 张表都没有，仅靠 env `TRON_MIN_CONFIRM_COUNT`。若要按链/币种配置，应落到 `crypto_api_provider` 或单独配置表；否则删掉「配置项」表述统一用 env。\n- **`confirm_count = current_block - block_number`**（第 17.2 节）存在 off-by-one，通常确认数应为 `current - block + 1`，需定义清楚以免「6 确认」实际差 1 块。\n- **`crypto_deposit_tx.uk_tx_hash` 全局唯一**：单链没问题，未来多链时 tx_hash 跨链理论可碰撞，建议预留 `uk_chain_tx_hash`。\n- **`notify` 缺重试上限/退避策略字段**：第 14 节说「多次失败转异常」，但没定义阈值（如 `notify_count >= N`）和重试间隔，建议写死阈值并在文档明确。\n- 时间字段（`block_time`）需注明时区（TRON 为 UTC 毫秒），避免与 `created_at` 混用本地时区。\n\n## 四、接口与安全\n\n- **内部接口缺鉴权说明**：`/api/crypto/address/get-or-create`、`/api/crypto/deposit/query`、通知 pay 的 `/internal/...` 均无签名/鉴权约定。按 `cross-service-sdk` 规则，跨服务应走 slot_sdk 并带 `server-name`，且 api 应用需限制来源。建议补「内部接口鉴权/白名单/签名」一节。\n- **pay 失败返回码不足**：第 14 节只给了 `1001 No matched deposit order`。异常流程（金额不一致、订单过期、无订单）需要不同 code，crypto-pay 才能写准确的 `error_msg` 并决定是否重试。建议定义返回码表。\n- 通知接口路径 `/internal/pay/...` 与第 15 节 admin 路径风格不一致，确认是 pay 侧路由。\n\n## 五、幂等与并发\n\n- **地址 get-or-create 并发**（第 13.1 节）：两个并发请求都「查无→生成→插入」，靠 `uk_uid_chain_token` 兜底，但需明确「捕获唯一键冲突后回查返回已存在地址」，并加 Redis 锁。文档应写出这一兜底逻辑。\n- **确认/通知进程并发**（第 17.2 节）：只给扫描进程要求了 Redis 锁，确认+通知进程也需加锁，否则同一 tx 可能被重复通知 pay（虽 pay 侧 tx_hash 幂等兜底，但应双保险）。\n- 第 20 节的三层幂等（链上 tx_hash / 通知 / wallet biz_no）设计合理，保持。\n\n## 六、一致性/格式小问题\n\n- 标题层级：`## 12.1`、`## 13.1`、`## 14.1`、`## 15.1` 等应为 `###`（当前都是二级），影响目录结构。\n- 第 11 节目录里 `Support` 含 `AmountConverter/PrivateKeyEncryptor/TronClient`，与第二节「Service 公共能力」职责有重叠，需明确 Support 与 Service 边界（建议 Support = 纯工具/无状态，外部网关归 Service）。\n- 归集流程「判断 TRX 是否足够、不足补 TRX」（第 17.3 节）依赖热钱包给每个用户地址供能量/带宽，第一期标注延后即可，但建议在「不做事项」或「风险」里点明 gas 供给方案待定。\n\n## 七、建议补充的章节\n\n- 返回码/错误码表（pay 与 crypto-pay 双向）。\n- 内部接口鉴权方案。\n- reorg / 安全确认间隔策略。\n- 通知重试策略（次数、退避、转异常阈值）。\n- 金额取整规则与「金额匹配相等」判定。\n- master_key 轮转预案（私钥重加密）。\n\n---\n\n需要我把这些评审意见整理成「修订建议清单」直接落进 `USTD.md`（如新增「风险与待决策」章节、补返回码/鉴权/reorg 小节），还是先就「分层改用 Logic / 固定地址匹配策略 / 扫描方式」这三个关键决策点确认方向？\n\n I'm reviewing a USDT-TRC20 self-custody deposit system requirements document, checking for completeness, consistency, and potential issues across architecture, data model, business logic, security, and idempotency. I'm starting to examine key areas like amount precision and other critical components.\n\nThere's a precision mismatch I need to flag: USDT has 6 decimals while the system uses 3, so converting raw_amount to system_amount via integer division loses fractional cents below 0.001 USDT—this truncation policy needs explicit specification. The order matching logic is also fragile: it relies on uid, pay_address, and amount, but since the address is fixed per user and reused across all deposits, two simultaneous orders with the same amount create ambiguity. This is a significant collision risk that most systems mitigate with unique amounts per order or unique addresses. Additionally, the confirmation count calculation appears to have an off-by-one error that needs clarification.\n\nThe min_confirm_count comes from the TRON_MIN_CONFIRM_COUNT environment variable rather than a config table, which is fine. However, block reorganization isn't addressed—if a block reorgs after the transaction is recorded but before reaching confirmation, the transaction could disappear. More critically, the scanning approach is inefficient: querying all USDT Transfer events across entire block ranges is extremely expensive since USDT is the most active contract on Tron. A per-address transaction polling approach using TronGrid's account-specific endpoints would be far more performant than filtering all transfers to find matches. The fixed address model also means each user address needs TRX for gas when collecting USDT, though the document mentions this is handled later in the collection flow.\n\nAddress generation uses random keypair generation per user with encrypted private key storage, which is acceptable for v1 but means managing N private keys. There's a potential race condition in concurrent address creation—two requests could both miss the database check and attempt to insert, though the unique constraint would catch one failure. This needs graceful duplicate-key handling and should be documented. The internal service calls lack any mention of authentication or signature verification beyond the server-name header, which should be explicitly addressed. The retry mechanism in section 14 is vague about the actual schedule, backoff strategy, and maximum attempts before marking a notification as failed. Finally, the error handling for amount mismatches is unclear—the pay service returns a generic 1001 error code, but the document should specify distinct response codes for different failure scenarios like missing orders, amount mismatches, or expired requests so crypto-pay can record the proper error details. Scanning should avoid the chain tip to prevent reorg issues. The deposit controller query lacks authorization checks. There's a concurrency risk in the confirm command—it needs locking like the scan does to prevent duplicate notifications. The status transitions from 1→2→3 happen quickly, with state 2 being transient. Deposits below minimum aren't addressed, and key rotation for the encrypted credentials isn't covered. The confirm logic depends on fetching the latest block each loop, which could hit rate limits despite the qps_limit field existing.\n\nNow I'm noticing a significant architectural mismatch: the doc proposes Service layer handling business orchestration with no Logic layer, but the team's backend-layering rules mandate Logic as the use-case entry point and Service only for shared utilities. This contradicts the established governance. The doc also doesn't mention Validate or DTO layers that the rules require. I should flag this as a notable inconsistency and suggest aligning the architecture—renaming the orchestration layer to Logic and keeping Service for shared capabilities like the TronClient gateway.\n\nI'll structure the review by severity: starting with this architecture and layering conflict as high priority, then covering core business risks like amount matching, fixed address reuse, and scanning performance, followed by data model issues, interface and security concerns, idempotency and concurrency, consistency problems, and finally recommendations for what needs to be added."}]}}
|
||
{"role":"user","message":{"content":[{"type":"text","text":"<timestamp>Wednesday, Jun 10, 2026, 10:58 AM (UTC+8)</timestamp>\n<user_query>\n一. 按团队分层规范，顺便更新需求文档。 其他问题都按你的建议处理，并更新需求文档\n</user_query>"}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"I'll update the requirements doc to align with the team layering规范 and address all the review points. Let me track the work.\n\n I need to update the requirements document to align with the team's layering architecture, restructuring it to use Controller/Validate/DTO/Logic/Service/Model layers instead of the current Service-orchestration approach. I'll work through the USTD.md file systematically, making comprehensive edits to incorporate these changes and address the other outstanding issues.\n\nFor the address matching risk, I'm weighing the two approaches I suggested earlier. Since the user wants me to handle all other issues per my recommendations, I need to make a pragmatic decision here. I'll go with adding a random tail to the order amount to ensure uniqueness as the primary matching strategy, and document the edge case of orders without pending payments as an abnormal scenario that can be handled via uid-based credit as a fallback.\n\nFor the scanning approach, I'm redesigning this to use per-address polling instead of the current method. I'll keep the cursor table structure simple by maintaining a global last_block_number, then for each cycle iterate through active user addresses and query their TRC20 transactions within that block range. This avoids bloating the cursor table while still achieving per-address polling.\n\nI also need to add the safe_gap concept to handle blockchain reorganizations, clarify the amount rounding rule as floor/truncate, fix the confirm_count formula to be current_block - tx_block + 1, and update the tx_hash uniqueness constraint to be chain + tx_hash composite. For the min_confirm_count, I'll make it clear it's environment-based configuration, not a database table entry.\n\nBeyond that, there's a longer list of improvements: defining notification retry thresholds and backoff logic, noting that block times are in UTC, adding sections for internal interface authentication, payment failure return codes, and concurrency handling with Redis locks for address creation and command processing. I also need to fix the heading levels throughout — many `## X.Y` should be `### X.Y` — and add missing sections on return codes, authentication, reorganization handling, notification retries, amount rounding, and master key rotation. Given the file size, I'll need to be systematic about these edits rather than making scattered changes. I'm mapping out the directory structure with clear separation: controllers and validators split by API and admin, shared DTOs, logic layer handling orchestration and transactions, services for cross-cutting concerns like TronGrid integration and payment notifications, commands for async tasks, support utilities for low-level operations, and models unchanged. I'll also add random trailing digits to deposit amounts for uniqueness and document that in section 16, then start editing from section 11 onward given the scope of changes needed. Continuing the directory structure...\n\nNow I'm laying out the layered architecture with clear responsibilities: Controllers handle requests and validation, DTOs carry validated data, Logic orchestrates business logic and transactions, Services provide shared capabilities like blockchain gateway integration, Models manage data persistence, Commands serve as entry points for background tasks, and Support utilities handle stateless operations like encryption and amount conversion. The key insight is that both API and admin modules reuse the same Logic and Service layers to avoid duplicating business logic.\n\nI need to update several sections throughout the document: refining the rounding logic in section 7, clarifying the confirmation formula and minimum confirmations in section 8, updating the deposit notification and cursor scanning logic to account for safe block gaps and reorg protection, ensuring the collect operation uses proper unique keys, adding concurrency locking details, establishing consistent return codes and retry thresholds, implementing amount randomization for matching, and updating the command flow to call Logic instead of Service directly while incorporating per-address scanning with safe gaps. Now I'm ready to execute the edits. I'll start by replacing the section 11 content, matching the exact original text from the directory structure through the end of section 11.3. Now I'm outlining the naming conventions for the data models and establishing the core architectural principles—separating concerns so that Models handle only data mapping and queries, Services orchestrate business logic, Controllers avoid complex logic, and Commands simply dispatch to Services. The key insight is that API and admin interfaces can share Services to prevent duplicating business logic across different entry points."},{"type":"tool_use","name":"TodoWrite","input":{"merge":false,"todos":[{"id":"layering","content":"重构分层为 Controller/Validate/DTO/Logic/Service/Model（第11、17、25节）","status":"in_progress"},{"id":"matching","content":"修正固定地址按金额匹配风险（第16节，金额唯一尾数 + 无订单策略）","status":"pending"},{"id":"scan","content":"扫描改为按地址轮询 + 安全确认间隔/reorg（第8、17.1节）","status":"pending"},{"id":"amount","content":"金额取整规则与确认数公式修正（第7、8、17.2节）","status":"pending"},{"id":"tables","content":"表结构调整：tx_hash 唯一键预留多链、cursor/通知阈值说明（第12节）","status":"pending"},{"id":"auth-codes","content":"补内部接口鉴权、pay 返回码表、通知重试策略（第13、14节）","status":"pending"},{"id":"idempotency","content":"地址并发与确认/通知进程加锁（第13.1、17节）","status":"pending"},{"id":"misc","content":"master_key 轮转、风险与待决策、标题层级修正","status":"pending"}]}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Starting with the layering restructure (section 11)."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 11. 应用目录建议\n\n第一期采用：\n\n```text\n多应用 + Service + Model + Command + Support\n```\n\n不使用 `Repository` 层。\n\n目录建议：\n\n```text\ncrypto-pay\n├── app\n│ ├── api\n│ │ └── controller\n│ │ ├── AddressController.php\n│ │ └── DepositController.php\n│ │\n│ ├── admin\n│ │ └── controller\n│ │ ├── AddressController.php\n│ │ ├── DepositController.php\n│ │ ├── CollectController.php\n│ │ └── ProviderController.php\n│ │\n│ ├── service\n│ │ ├── TronAddressService.php\n│ │ ├── TronDepositScanService.php\n│ │ ├── TronDepositConfirmService.php\n│ │ ├── TronCollectService.php\n│ │ ├── CryptoNotifyService.php\n│ │ └── CryptoProviderService.php\n│ │\n│ ├── model\n│ │ ├── UserCryptoAddress.php\n│ │ ├── CryptoDepositTx.php\n│ │ ├── CryptoCollectTx.php\n│ │ ├── CryptoApiProvider.php\n│ │ └── CryptoScanCursor.php\n│ │\n│ ├── command\n│ │ ├── TronDepositScanCommand.php\n│ │ ├── TronDepositConfirmCommand.php\n│ │ └── TronCollectCommand.php\n│ │\n│ └── support\n│ ├── TronClient.php\n│ ├── PrivateKeyEncryptor.php\n│ └── AmountConverter.php\n```\n\n### 11.1 分层职责\n\n```text\napi/controller = 内部服务接口控制器\nadmin/controller = 后台管理接口控制器\nService = 业务流程编排\nModel = ThinkORM 数据模型，负责数据表映射和基础查询\nCommand = 常驻任务入口\nSupport = 工具封装、链客户端、金额换算、私钥加密\n```\n\n### 11.2 Model 命名规则\n\n```text\nuser_crypto_address => UserCryptoAddress\ncrypto_deposit_tx => CryptoDepositTx\ncrypto_collect_tx => CryptoCollectTx\ncrypto_api_provider => CryptoApiProvider\ncrypto_scan_cursor => CryptoScanCursor\n```\n\n### 11.3 业务逻辑放置规则\n\n```text\n1. 复杂业务逻辑不放 Model\n2. Model 只做数据表映射和基础查询\n3. Service 负责完整业务流程\n4. Controller 不直接写复杂业务逻辑\n5. Command 只负责调度 Service\n6. api 和 admin 可以共用 Service\n7. api 和 admin 不重复写业务逻辑\n```","new_string":"## 11. 应用目录建议\n\n第一期采用团队统一分层（见 `backend-layering` 规则）：\n\n```text\n多应用 + Controller + Validate + DTO + Logic + Service + Model + Command + Support\n```\n\n不使用 `Repository` 层。\n\n分层原则（强制）：\n\n```text\n1. 业务用例编排与事务边界放 Logic\n2. Service 只放公共能力：链上网关、跨服务调用 pay、公共计算\n3. 禁止「Logic 型 Service」，即只转发 Model / Logic、无公共能力的中间层\n4. 参数校验放 Validate，已校验入参用 DTO 承载\n5. Command 只调度 Logic，不写业务逻辑\n6. Support 只放无状态工具：链客户端、金额换算、私钥加解密\n```\n\n目录建议：\n\n```text\ncrypto-pay\n├── app\n│ ├── api\n│ │ ├── controller\n│ │ │ ├── AddressController.php\n│ │ │ └── DepositController.php\n│ │ └── validate\n│ │ ├── AddressValidate.php\n│ │ └── DepositValidate.php\n│ │\n│ ├── admin\n│ │ ├── controller\n│ │ │ ├── AddressController.php\n│ │ │ ├── DepositController.php\n│ │ │ ├── CollectController.php\n│ │ │ └── ProviderController.php\n│ │ └── validate\n│ │ ├── DepositValidate.php\n│ │ ├── CollectValidate.php\n│ │ └── ProviderValidate.php\n│ │\n│ ├── dto\n│ │ ├── AddressGetOrCreateDTO.php\n│ │ ├── DepositConfirmNotifyDTO.php\n│ │ └── CollectCreateDTO.php\n│ │\n│ ├── logic\n│ │ ├── TronAddressLogic.php\n│ │ ├── TronDepositScanLogic.php\n│ │ ├── TronDepositConfirmLogic.php\n│ │ ├── CryptoDepositNotifyLogic.php\n│ │ ├── TronCollectLogic.php\n│ │ └── CryptoProviderLogic.php\n│ │\n│ ├── service\n│ │ ├── TronGatewayService.php\n│ │ └── PayNotifyGatewayService.php\n│ │\n│ ├── model\n│ │ ├── UserCryptoAddress.php\n│ │ ├── CryptoDepositTx.php\n│ │ ├── CryptoCollectTx.php\n│ │ ├── CryptoApiProvider.php\n│ │ └── CryptoScanCursor.php\n│ │\n│ ├── command\n│ │ ├── TronDepositScanCommand.php\n│ │ ├── TronDepositConfirmCommand.php\n│ │ └── TronCollectCommand.php\n│ │\n│ └── support\n│ ├── TronClient.php\n│ ├── PrivateKeyEncryptor.php\n│ └── AmountConverter.php\n```\n\n### 11.1 分层职责\n\n```text\nController = 接收请求、调用 Validate、构建 DTO、调用 Logic、返回统一响应\nValidate = 参数必填、类型、长度、格式、枚举、数组结构校验\nDTO = 承载已校验参数；不查库、不写业务规则\nLogic = 业务用例编排、流程控制、事务边界；调用 Model 与 Service\nService = 公共能力：链上网关（TronGrid 封装）、跨服务调用 pay、公共计算\nModel = ThinkORM 数据模型，负责数据表映射和基础查询\nCommand = 常驻任务入口，只调度 Logic\nSupport = 无状态工具：链客户端、金额换算、私钥加解密\n```\n\n说明：\n\n```text\n1. TronGatewayService 封装 TronGrid / 第三方 API（公共链上能力）\n2. PayNotifyGatewayService 通过 slot_sdk 调用 pay（跨服务能力）\n3. 地址生成、扫描、确认、归集、Provider 配置等用例编排一律放 Logic\n4. api 与 admin 复用同一批 Logic / Service，不重复写业务逻辑\n```\n\n### 11.2 Model 命名规则\n\n```text\nuser_crypto_address => UserCryptoAddress\ncrypto_deposit_tx => CryptoDepositTx\ncrypto_collect_tx => CryptoCollectTx\ncrypto_api_provider => CryptoApiProvider\ncrypto_scan_cursor => CryptoScanCursor\n```\n\n### 11.3 业务逻辑放置规则\n\n```text\n1. 复杂业务逻辑不放 Model\n2. Model 只做数据表映射和基础查询\n3. Logic 负责完整业务用例编排与事务边界\n4. Service 只承载公共能力，不做单业务用例编排\n5. Controller 不直接写复杂业务逻辑\n6. Command 只负责调度 Logic\n7. api 和 admin 可以共用 Logic / Service\n8. api 和 admin 不重复写业务逻辑\n```"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now update section 17 (commands) to call Logic and add concurrency locks + confirm formula fix."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 17. Webman 常驻进程\n\n## 17.1 TronDepositScanCommand\n\n职责：\n\n```text\n扫描 TRC20-USDT Transfer 事件。\n```\n\n流程：\n\n```text\n1. 读取 CryptoScanCursor.last_block_number\n2. 获取当前最新区块高度\n3. 按区块范围扫描 Transfer 事件\n4. 只处理 USDT 合约\n5. 判断 to_address 是否存在于 UserCryptoAddress\n6. 判断 tx_hash 是否已存在于 CryptoDepositTx\n7. 不存在则写入 crypto_deposit_tx\n8. 更新扫描游标\n```\n\n要求：\n\n```text\n1. 每批扫描 20 ~ 100 个区块\n2. 扫描失败不能推进游标\n3. 需要 Redis 锁，避免多个扫描进程同时运行\n4. tx_hash 必须唯一\n```\n\n---\n\n## 17.2 TronDepositConfirmCommand\n\n职责：\n\n```text\n更新确认数，并在达到确认数后通知 pay 服务。\n```\n\n流程：\n\n```text\n1. 查询 status = 1 确认中 的 CryptoDepositTx\n2. 获取当前最新区块高度\n3. 计算 confirm_count = current_block - block_number\n4. 更新 confirm_count\n5. 如果 confirm_count >= min_confirm_count，状态改为待通知\n6. 调 pay 服务确认通知接口\n7. 通知成功，状态改为已通知\n8. 通知失败，记录失败次数，等待重试\n```\n\n要求：\n\n```text\n1. 钱包入账不在 crypto-pay 做\n2. crypto-pay 只负责通知 pay\n3. 通知 pay 必须支持失败重试\n```","new_string":"## 17. Webman 常驻进程\n\nCommand 只做调度，业务流程在对应 Logic 内实现：\n\n```text\nTronDepositScanCommand -> TronDepositScanLogic\nTronDepositConfirmCommand -> TronDepositConfirmLogic + CryptoDepositNotifyLogic\nTronCollectCommand -> TronCollectLogic\n```\n\n### 17.1 TronDepositScanCommand\n\n职责：\n\n```text\n按系统用户地址轮询 TRC20-USDT 到账交易。\n```\n\n第一期不扫描全链 USDT Transfer 事件（USDT 是全链最活跃合约，全量事件量级与限流压力过大）。改为**按系统用户地址轮询**：只查询 `UserCryptoAddress` 中的地址在指定区块区间内的 TRC20 到账交易。\n\n流程：\n\n```text\n1. 读取 CryptoScanCursor.last_block_number\n2. 获取当前最新区块高度 latest_block\n3. 计算安全扫描上界 safe_to = latest_block - SCAN_SAFE_BLOCK_GAP\n4. 计算本批区块区间 [last_block_number + 1, min(safe_to, last_block_number + batch)]\n5. 遍历 status = 1 正常 的用户地址，查询该地址在区块区间内的 USDT 到账交易\n6. 只处理 USDT 合约（contract_address = TRON_USDT_CONTRACT）\n7. 判断 to_address 是否存在于 UserCryptoAddress\n8. 判断 tx_hash 是否已存在于 CryptoDepositTx\n9. 不存在则写入 crypto_deposit_tx，初始 status = 1 确认中\n10. 扫描区间全部成功后，推进 last_block_number = 区间上界\n```\n\n要求：\n\n```text\n1. 每批扫描 20 ~ 100 个区块\n2. 引入 SCAN_SAFE_BLOCK_GAP（默认 3），不扫描链顶最新区块，规避 reorg\n3. 扫描失败不能推进游标\n4. 需要 Redis 锁，避免多个扫描进程同时运行\n5. tx_hash 必须唯一；写入捕获唯一键冲突视为已存在，跳过\n6. 地址数量较多时按 priority/qps_limit 控制对链 API 的请求速率\n```\n\n注意（reorg）：\n\n```text\n1. 扫描只处理 latest_block - SCAN_SAFE_BLOCK_GAP 以内的区块\n2. 确认期内（status = 1）应校验 tx 仍在主链，否则置异常并告警\n```\n\n---\n\n### 17.2 TronDepositConfirmCommand\n\n职责：\n\n```text\n更新确认数，并在达到确认数后通知 pay 服务。\n```\n\n流程：\n\n```text\n1. 查询 status = 1 确认中 的 CryptoDepositTx\n2. 获取当前最新区块高度 current_block\n3. 计算 confirm_count = current_block - block_number + 1\n4. 更新 confirm_count\n5. 校验该 tx 仍在主链（防 reorg），失效则置 status = 4 异常并告警\n6. 如果 confirm_count >= min_confirm_count，状态改为 2 待通知\n7. 调 CryptoDepositNotifyLogic 通知 pay\n8. 通知成功，状态改为 3 已通知\n9. 通知失败，记录失败次数，按退避策略等待重试（见 14.1）\n```\n\n要求：\n\n```text\n1. 钱包入账不在 crypto-pay 做\n2. crypto-pay 只负责通知 pay\n3. 通知 pay 必须支持失败重试\n4. 确认+通知进程同样需要 Redis 锁，避免同一 tx 被重复通知\n```"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" I need to adjust the heading level for section 17.3 from a level-2 to level-3 heading, and I should also update its content to incorporate Logic into the workflow description."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 17.3 TronCollectCommand","new_string":"### 17.3 TronCollectCommand"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now section 25 (final conclusion) layering text."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"代码结构保持简洁：\n\n```text\nwebman 多应用模式\napi + admin\nService + Model + Command + Support\n```\n\n不引入 Repository 层。\nModel 使用 ThinkORM Model 模式，只负责数据表映射和基础查询，复杂业务逻辑统一放在 Service。","new_string":"代码结构遵循团队统一分层：\n\n```text\nwebman 多应用模式\napi + admin\nController + Validate + DTO + Logic + Service + Model + Command + Support\n```\n\n不引入 Repository 层。\nModel 使用 ThinkORM Model 模式，只负责数据表映射和基础查询。\n业务用例编排与事务边界统一放在 Logic；Service 只承载链上网关、跨服务调用、公共计算等公共能力。"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" The layering is complete, so I'm marking that section done and moving forward to handle the amount and confirmation steps. Let me update my task list and tackle section 7 next."},{"type":"tool_use","name":"TodoWrite","input":{"merge":true,"todos":[{"id":"layering","content":"重构分层为 Controller/Validate/DTO/Logic/Service/Model（第11、17、25节）","status":"completed"},{"id":"amount","content":"金额取整规则与确认数公式修正（第7、8节）","status":"in_progress"}]}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Section 7 — amount rounding rule."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"换算规则：\n\n```text\nsystem_amount = raw_amount / 1000\n```\n\n示例：\n\n```text\n链上 raw_amount = 100000000\n实际 USDT = 100\n系统金额 system_amount = 100000\n前端展示金额 = $100.00\n```\n\n注意：\n\n```text\n第一期不做动态汇率。\n后续如果引入汇率，需要改为：\nsystem_amount = USDT数量 * 汇率 * 1000\n```","new_string":"换算规则（整数除法，向下取整）：\n\n```text\nsystem_amount = floor(raw_amount / 1000)\n```\n\nUSDT 为 6 位小数、系统金额为 3 位小数，低于 0.001 USDT 的尾数会被截断（向下取整）。\n\n```text\nraw_amount = 1000500 (1.0005 USDT)\nsystem_amount = floor(1000500 / 1000) = 1000 ($1.000)\n被截断 0.0005 USDT\n```\n\n取整策略：\n\n```text\n1. 第一期统一向下取整（floor），不四舍五入，避免给用户多记账\n2. 该规则同样用于 pay 的订单金额匹配（见第 16 节金额唯一尾数）\n3. AmountConverter 统一封装换算，禁止业务代码各自拼算\n```\n\n示例：\n\n```text\n链上 raw_amount = 100000000\n实际 USDT = 100\n系统金额 system_amount = 100000\n前端展示金额 = $100.00\n```\n\n注意：\n\n```text\n第一期不做动态汇率。\n后续如果引入汇率，需要改为：\nsystem_amount = floor(USDT数量 * 汇率 * 1000)\n```"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Section 8 — confirm count source + formula + safe gap."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"第一期默认：\n\n```text\nUSDT-TRC20 最小确认数 = 6\n```\n\n配置项：\n\n```text\nchain = TRC20\ntoken = USDT\nmin_confirm_count = 6\n```\n\n不允许 0 确认直接入账。","new_string":"第一期默认：\n\n```text\nUSDT-TRC20 最小确认数 = 6\n```\n\n配置来源（第一期为环境变量，非数据库表）：\n\n```text\nTRON_MIN_CONFIRM_COUNT = 6 最小确认数\nSCAN_SAFE_BLOCK_GAP = 3 扫描安全间隔，规避 reorg\n```\n\n确认数计算公式：\n\n```text\nconfirm_count = current_block - block_number + 1\n```\n\n即交易所在区块本身记为第 1 个确认。\n\n不允许 0 确认直接入账。\n\n后续若需按链/币种差异化配置确认数，再下沉到配置表或 `crypto_api_provider`，第一期不引入。"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" I've marked the scan sections as complete—17.1 is updated and section 8 has the safe gap added—so now I'm moving on to working with the tables."},{"type":"tool_use","name":"TodoWrite","input":{"merge":true,"todos":[{"id":"amount","content":"金额取整规则与确认数公式修正（第7、8节）","status":"completed"},{"id":"scan","content":"扫描改为按地址轮询 + 安全确认间隔/reorg（第8、17.1节）","status":"completed"},{"id":"tables","content":"表结构调整：tx_hash 唯一键预留多链、cursor/通知阈值说明（第12节）","status":"in_progress"}]}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now table changes. First the heading levels and the deposit_tx table (unique key for multi-chain, retry scheduling field, block_time UTC).\n\n Looking at the crypto_deposit_tx table updates: I need to rename uk_tx_hash to uk_chain_tx_hash, document the max_notify retry behavior and block_time as UTC, and consider adding a next_notify_at column to handle backoff retry logic instead of computing it on the fly from last_notify_at.\n\nNow I'm going through the section headings — converting all the ## 12.x headings to ### format and updating the SQL definitions with the necessary column changes and documentation notes."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 12.1 用户虚拟币充值地址表","new_string":"### 12.1 用户虚拟币充值地址表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 12.2 链上充值交易表","new_string":"### 12.2 链上充值交易表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":" `block_number` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '区块高度',\n `block_time` DATETIME NULL COMMENT '区块时间',","new_string":" `block_number` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '区块高度',\n `block_time` DATETIME NULL COMMENT '区块时间（UTC）',"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":" `notify_status` TINYINT NOT NULL DEFAULT 0 COMMENT '通知pay状态：0未通知 1通知成功 2通知失败',\n `notify_count` INT NOT NULL DEFAULT 0 COMMENT '通知次数',\n `last_notify_at` DATETIME NULL COMMENT '最近通知时间',\n\n `status` TINYINT NOT NULL DEFAULT 1 COMMENT '状态：1确认中 2待通知 3已通知 4异常 5忽略',\n\n `error_msg` VARCHAR(512) NOT NULL DEFAULT '' COMMENT '异常原因',\n\n `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',\n `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',\n\n PRIMARY KEY (`id`),\n UNIQUE KEY `uk_tx_hash` (`tx_hash`),\n KEY `idx_to_address` (`to_address`),\n KEY `idx_uid_status` (`uid`, `status`),\n KEY `idx_status_confirm` (`status`, `confirm_count`),\n KEY `idx_pay_order_no` (`pay_order_no`)\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='虚拟币充值链上交易表';","new_string":" `notify_status` TINYINT NOT NULL DEFAULT 0 COMMENT '通知pay状态：0未通知 1通知成功 2通知失败',\n `notify_count` INT NOT NULL DEFAULT 0 COMMENT '已通知次数',\n `last_notify_at` DATETIME NULL COMMENT '最近通知时间',\n `next_notify_at` DATETIME NULL COMMENT '下次允许通知时间，用于失败退避重试',\n\n `status` TINYINT NOT NULL DEFAULT 1 COMMENT '状态：1确认中 2待通知 3已通知 4异常 5忽略',\n\n `error_msg` VARCHAR(512) NOT NULL DEFAULT '' COMMENT '异常原因',\n\n `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',\n `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',\n\n PRIMARY KEY (`id`),\n UNIQUE KEY `uk_chain_tx_hash` (`chain`, `tx_hash`),\n KEY `idx_to_address` (`to_address`),\n KEY `idx_uid_status` (`uid`, `status`),\n KEY `idx_status_confirm` (`status`, `confirm_count`),\n KEY `idx_notify_retry` (`notify_status`, `next_notify_at`),\n KEY `idx_pay_order_no` (`pay_order_no`)\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='虚拟币充值链上交易表';"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" I need to add a note under section 12.2 about uk_chain_tx_hash, placing it after the 通知状态说明 block that's around lines 611-617."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"通知状态说明：\n\n```text\n0 未通知\n1 通知成功\n2 通知失败\n```\n\n---\n\n## 12.3 链扫描游标表","new_string":"通知状态说明：\n\n```text\n0 未通知\n1 通知成功\n2 通知失败\n```\n\n唯一键说明：\n\n```text\n1. 唯一键为 (chain, tx_hash)，第一期单链等价于 tx_hash 唯一\n2. 预留 chain 维度，避免未来多链 tx_hash 跨链碰撞\n```\n\n---\n\n### 12.3 链扫描游标表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" I need to add a note to section 12.3 about the safe block gap and per-address scanning after the SQL block, then fix the heading formatting for sections 12.4 and 12.5."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":" PRIMARY KEY (`id`),\n UNIQUE KEY `uk_chain_token_type` (`chain`, `token`, `scan_type`)\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='虚拟币链扫描游标表';\n```\n\n---\n\n## 12.4 归集交易表","new_string":" PRIMARY KEY (`id`),\n UNIQUE KEY `uk_chain_token_type` (`chain`, `token`, `scan_type`)\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='虚拟币链扫描游标表';\n```\n\n说明：\n\n```text\n1. last_block_number 为全局扫描进度，每批推进到 [区间上界]\n2. 实际扫描按系统用户地址轮询（见 17.1），游标只记区块进度\n3. 推进上界受 SCAN_SAFE_BLOCK_GAP 约束，不推进到链顶最新区块\n```\n\n---\n\n### 12.4 归集交易表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now collect_tx unique key (multi-chain) and heading 12.5."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":" PRIMARY KEY (`id`),\n UNIQUE KEY `uk_tx_hash` (`tx_hash`),\n KEY `idx_from_address` (`from_address`),\n KEY `idx_status` (`status`)\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='虚拟币归集交易表';","new_string":" PRIMARY KEY (`id`),\n UNIQUE KEY `uk_chain_tx_hash` (`chain`, `tx_hash`),\n KEY `idx_from_address` (`from_address`),\n KEY `idx_status` (`status`)\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='虚拟币归集交易表';"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" The NULL value in tx_hash works fine with the composite unique constraint since NULL entries don't violate uniqueness rules, so I'll keep that note and update the section heading to 12.5."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 12.5 链 API Provider 配置表","new_string":"### 12.5 链 API Provider 配置表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" Moving on to the authentication and codes sections now. I need to add the auth subsection to section 13, fix the heading structure for 13.1 and 13.2, and incorporate concurrency handling into the logic. Then for section 14, I'll add a payment return codes table and outline the retry strategy."},{"type":"tool_use","name":"TodoWrite","input":{"merge":true,"todos":[{"id":"tables","content":"表结构调整：tx_hash 唯一键预留多链、cursor/通知阈值说明（第12节）","status":"completed"},{"id":"auth-codes","content":"补内部接口鉴权、pay 返回码表、通知重试策略（第13、14节）","status":"in_progress"}]}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 13. api 应用接口\n\n## 13.1 获取或创建用户充值地址","new_string":"## 13. api 应用接口\n\n### 13.0 接口鉴权与调用约定\n\n`api` 应用只对内部服务开放，不对 C 端开放。所有内部接口必须鉴权：\n\n```text\n1. 跨服务调用统一走 slot_sdk，禁止业务代码手写 Guzzle/curl 拼 host\n2. 请求头必须带 server-name（调用方服务名），服务端校验来源白名单\n3. 关键内部接口增加签名校验：sign = HMAC(body + timestamp, internal_secret)\n4. timestamp 超时窗口（如 ±300s）防重放\n5. 部署层限制 api 应用仅内网可达\n```\n\n统一响应结构：\n\n```text\ncode = 0 成功，其余为业务/系统错误码\ndata 为业务数据，失败时带 message\n```\n\n---\n\n### 13.1 获取或创建用户充值地址"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now update 13.1 处理逻辑 to add concurrency lock + unique-key catch, and fix 13.2 heading."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"处理逻辑：\n\n```text\n1. 根据 uid + chain + token 查询 UserCryptoAddress\n2. 如果存在，直接返回地址\n3. 如果不存在，生成 TRON 地址\n4. 加密保存私钥\n5. 写入 user_crypto_address\n6. 返回充值地址\n```\n\n幂等规则：\n\n```text\nuid + chain + token 唯一。\n重复请求返回同一个地址。\n```","new_string":"处理逻辑（TronAddressLogic）：\n\n```text\n1. 根据 uid + chain + token 查询 UserCryptoAddress\n2. 如果存在，直接返回地址\n3. 如果不存在，获取 Redis 锁 lock:crypto_addr:{uid}:{chain}:{token}\n4. 锁内二次查询，存在则直接返回（双检）\n5. 生成 TRON 地址，AES-256-GCM 加密私钥\n6. 写入 user_crypto_address\n7. 释放锁，返回充值地址\n```\n\n幂等规则：\n\n```text\n1. uid + chain + token 唯一，重复请求返回同一个地址\n2. 并发未命中锁时，依赖 uk_uid_chain_token 兜底\n3. 写入命中唯一键冲突时，捕获异常后回查并返回已存在地址，不报错\n```"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 13.2 查询链上充值交易","new_string":"### 13.2 查询链上充值交易"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now section 14 — pay return codes + retry strategy. Fix heading 14.1 and expand the rules."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 14. crypto-pay 通知 pay 服务接口\n\n## 14.1 链上充值确认通知","new_string":"## 14. crypto-pay 通知 pay 服务接口\n\n### 14.1 链上充值确认通知"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"pay 服务无法匹配订单返回：\n\n```json\n{\n \"code\": 1001,\n \"message\": \"No matched deposit order\"\n}\n```\n\ncrypto-pay 处理规则：\n\n```text\n1. pay 返回 code = 0：\n - crypto_deposit_tx.status = 3 已通知\n - notify_status = 1 通知成功\n\n2. pay 返回失败：\n - notify_status = 2 通知失败\n - notify_count + 1\n - 记录 error_msg\n - 可进入重试或异常状态\n\n3. 通知多次失败：\n - crypto_deposit_tx.status = 4 异常\n - 后台人工处理\n```","new_string":"pay 服务失败返回（按场景区分错误码）：\n\n```json\n{\n \"code\": 1001,\n \"message\": \"No matched deposit order\"\n}\n```\n\npay 返回码约定：\n\n```text\n0 处理成功\n1001 无匹配的待支付订单\n1002 到账金额与订单金额不一致\n1003 订单已过期\n1004 订单状态非待支付（已处理/已取消）\n5000 pay 内部错误（可重试）\n```\n\n错误码分类与 crypto-pay 行为：\n\n```text\n1. 可重试类（5000、超时、网络错误）：进入退避重试\n2. 不可重试类（1001~1004）：不重试，直接转异常，等后台处理\n```\n\ncrypto-pay 处理规则：\n\n```text\n1. pay 返回 code = 0：\n - crypto_deposit_tx.status = 3 已通知\n - notify_status = 1 通知成功\n - 记录 pay_order_no\n\n2. pay 返回可重试错误：\n - notify_status = 2 通知失败\n - notify_count + 1\n - last_notify_at = now\n - next_notify_at = now + backoff(notify_count)\n - 记录 error_msg\n\n3. pay 返回不可重试错误：\n - notify_status = 2 通知失败\n - 记录 error_msg\n - crypto_deposit_tx.status = 4 异常\n\n4. 重试次数达到上限（notify_count >= NOTIFY_MAX_RETRY，默认 5）：\n - crypto_deposit_tx.status = 4 异常\n - 触发告警，后台人工处理\n```\n\n重试退避策略：\n\n```text\n1. 退避间隔（秒）：30, 60, 300, 900, 1800（指数/阶梯）\n2. 确认进程按 next_notify_at <= now 拉取 notify_status = 2 的记录重试\n3. 重试必须带 tx_hash，pay 侧按 tx_hash 幂等（见 20.2）\n```"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" Finishing up the auth codes section, then moving through the matching work in section 16 and admin headings in 15.x since 17 is already complete. I need to fix the headings in sections 15 and 20 before tackling the matching phase. After that, I'll handle the miscellaneous items including the master_key section 19 and the new risk/decision section. I'm also marking idempotency as complete since the lock implementations in 13.1 and 17.2 are done."},{"type":"tool_use","name":"TodoWrite","input":{"merge":true,"todos":[{"id":"auth-codes","content":"补内部接口鉴权、pay 返回码表、通知重试策略（第13、14节）","status":"completed"},{"id":"idempotency","content":"地址并发与确认/通知进程加锁（第13.1、17节）","status":"completed"},{"id":"matching","content":"修正固定地址按金额匹配风险（第16节）","status":"in_progress"}]}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now section 16 — matching strategy (unique amount tail + no-order policy)."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"### 16.1 创建订单时\n\n```text\n1. 用户选择 USDT-TRC20 充值\n2. pay 创建 deposit_order\n3. pay 调 crypto-pay 的 api 应用获取充值地址\n4. pay 将地址写入 deposit_order.pay_address\n5. pay 返回充值信息给前端\n```","new_string":"### 16.1 创建订单时\n\n```text\n1. 用户选择 USDT-TRC20 充值\n2. pay 创建 deposit_order\n3. pay 调 crypto-pay 的 api 应用获取充值地址\n4. pay 将地址写入 deposit_order.pay_address\n5. pay 生成订单唯一金额（见 16.4），写入 deposit_order\n6. pay 返回充值信息给前端（展示唯一金额）\n```"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"### 16.3 pay 匹配订单规则\n\n优先级：\n\n```text\n1. uid 一致\n2. pay_address 一致\n3. amount 与 system_amount 一致\n4. status = 待支付\n5. 未过期\n6. 创建时间最早\n```\n\n如果无法匹配：\n\n```text\npay 返回失败，由 crypto-pay 记录异常。\n```","new_string":"### 16.3 pay 匹配订单规则\n\n匹配条件（全部满足）：\n\n```text\n1. uid 一致\n2. pay_address 一致\n3. amount 与 system_amount 一致（唯一金额，见 16.4）\n4. status = 待支付\n5. 未过期\n6. 若仍命中多条，取创建时间最早\n```\n\n匹配失败返回对应错误码（见 14.1），由 crypto-pay 按可重试/不可重试分类处理：\n\n```text\n1. 无待支付订单 -> 1001\n2. 金额不一致 -> 1002\n3. 订单已过期 -> 1003\n4. 订单状态非待支付 -> 1004\n```\n\n### 16.4 订单金额唯一化（解决固定地址撞单）\n\n固定地址被用户所有充值复用，仅靠固定金额无法区分并发的同额订单。第一期采用**唯一金额尾数**保证匹配可判定：\n\n```text\n1. pay 创建订单时，在基础金额上叠加随机尾数（如 0.001 ~ 0.999 USDT 区间内的 system_amount 尾数）\n2. 同一 uid + pay_address 下，待支付订单的 amount 必须唯一\n3. 用户须按展示的精确金额转账，crypto-pay 上报 system_amount 用于精确匹配\n4. 金额换算统一向下取整（见第 7 节），尾数粒度不低于 system_amount 最小单位\n```\n\n### 16.5 无待支付订单的链上到账\n\n地址长期固定，用户可能不下单直接向旧地址转账：\n\n```text\n1. 第一期：无匹配待支付订单时 pay 返回 1001，crypto-pay 记为异常（status = 4），后台人工处理\n2. 因地址已绑定 uid，链上到账事实可信，可由后台确认后走标准资金流程补单\n3. 待决策：后续是否支持「认地址即认人」自动入账，见第 26 节\n```"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now section 19 — add master_key rotation guidance.\n\n I need to fix the section headings for 15.1 through 15.10 and 20.1 through 20.3, then add the new sections on master key rotation and risk assessment. I'll batch these heading replacements together in multiple calls since they're all distinct strings."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"环境变量建议：\n\n```env\nCRYPTO_MASTER_KEY=base64_xxxxxxxxx\nTRONGRID_API_KEY=xxxxxxxxx\nTRON_USDT_CONTRACT=TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj\nTRON_MIN_CONFIRM_COUNT=6\nTRON_HOT_WALLET_ADDRESS=Txxxxxxxxx\n```","new_string":"环境变量建议：\n\n```env\nCRYPTO_MASTER_KEY=base64_xxxxxxxxx\nCRYPTO_MASTER_KEY_VERSION=1\nTRONGRID_API_KEY=xxxxxxxxx\nTRON_USDT_CONTRACT=TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj\nTRON_MIN_CONFIRM_COUNT=6\nSCAN_SAFE_BLOCK_GAP=3\nNOTIFY_MAX_RETRY=5\nTRON_HOT_WALLET_ADDRESS=Txxxxxxxxx\n```\n\nmaster_key 轮转预案：\n\n```text\n1. 密文随记 key_version（密文前缀或独立字段），支持多版本并存\n2. 轮转时新私钥用新版本 key 加密，存量私钥后台异步重加密迁移\n3. 解密按密文携带的 key_version 选取对应 master_key\n4. 第一期可只落 key_version 字段与解密兼容逻辑，实际轮转流程延后\n```"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now append the risks & decisions section at the end.\n\n I need to locate where section 25 ends and then insert the new risk and decision section after it, so I'm reviewing the file structure to find the right insertion point."},{"type":"tool_use","name":"Read","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","offset":-12}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"不引入 Repository 层。\nModel 使用 ThinkORM Model 模式，只负责数据表映射和基础查询。\n业务用例编排与事务边界统一放在 Logic；Service 只承载链上网关、跨服务调用、公共计算等公共能力。","new_string":"不引入 Repository 层。\nModel 使用 ThinkORM Model 模式，只负责数据表映射和基础查询。\n业务用例编排与事务边界统一放在 Logic；Service 只承载链上网关、跨服务调用、公共计算等公共能力。\n\n---\n\n## 26. 风险与待决策（第一期需确认）\n\n以下为评审中已按建议落入文档、但仍需产品/技术拍板的关键决策点：\n\n### 26.1 已采用的方案（默认）\n\n```text\n1. 分层改为 Controller/Validate/DTO/Logic/Service/Model（对齐团队规范）\n2. 订单金额唯一化（随机尾数）解决固定地址撞单（16.4）\n3. 链上监听改为按用户地址轮询，不扫全链 Transfer 事件（17.1）\n4. 引入 SCAN_SAFE_BLOCK_GAP 与确认期主链校验规避 reorg（8、17）\n5. 金额换算统一向下取整 floor（第 7 节）\n6. 通知 pay 退避重试 + 上限转异常（14.1）\n7. 内部接口走 slot_sdk + server-name + 签名校验（13.0）\n8. tx_hash 唯一键预留 chain 维度（12.2、12.4）\n```\n\n### 26.2 待决策项\n\n```text\n1. 无待支付订单的链上到账：第一期记异常人工处理；是否后续支持「认地址即认人」自动入账（16.5）\n2. 唯一金额尾数粒度与上限：避免与正常金额冲突，需结合业务金额范围确定\n3. 归集触发方式：第一期半自动/人工；自动归集闭环与 gas（TRX 能量）供给方案延后\n4. 按地址轮询的 QPS 与地址规模：地址量增大后是否引入 webhook/事件订阅替代轮询\n5. 差异化确认数：是否需要按币种/金额分级确认数（大额更高确认）\n6. master_key 实际轮转流程上线时间\n```\n\n### 26.3 归集 gas 供给（延后）\n\n```text\n1. USDT-TRC20 转账需要地址具备 TRX 能量/带宽\n2. 归集前需由热钱包向用户地址补 TRX（gas 归集模式）\n3. 第一期只做归集记录与余额查询，自动补 gas 与自动归集延后\n```"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Now fixing the remaining heading levels in sections 15 and 20.\n\n I need to fix the remaining headings in sections 15.1-15.10 and 20.1-20.3 using sequential string replacements. Since these are non-overlapping unique strings in the same file, I can issue multiple tool calls in parallel rather than waiting for each one to complete."},{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.1 用户充值地址列表","new_string":"### 15.1 用户充值地址列表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.2 链上充值记录列表","new_string":"### 15.2 链上充值记录列表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.3 异常充值列表","new_string":"### 15.3 异常充值列表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.4 重新通知 pay","new_string":"### 15.4 重新通知 pay"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.5 标记忽略","new_string":"### 15.5 标记忽略"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.6 地址余额查询","new_string":"### 15.6 地址余额查询"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.7 归集记录列表","new_string":"### 15.7 归集记录列表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.8 手动发起归集，第一期可选","new_string":"### 15.8 手动发起归集，第一期可选"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.9 API Provider 配置列表","new_string":"### 15.9 API Provider 配置列表"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 15.10 API Provider 保存","new_string":"### 15.10 API Provider 保存"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 20.1 链上交易幂等","new_string":"### 20.1 链上交易幂等"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 20.2 通知 pay 幂等","new_string":"### 20.2 通知 pay 幂等"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"tool_use","name":"StrReplace","input":{"path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","old_string":"## 20.3 wallet 入账幂等","new_string":"### 20.3 wallet 入账幂等"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"Let me verify no leftover references to the old Service-orchestration model or removed class names.\n\n Checking sections 4.2 and 4.3 for API and admin responsibilities — they look clean without any layering violations. Section 6.1's payment matching logic is also fine. Now I need to search through the document for any lingering \"Service\" references that might indicate old orchestration patterns or service class names that could conflict with the current architecture."},{"type":"tool_use","name":"Grep","input":{"pattern":"TronAddressService|TronDepositScanService|TronDepositConfirmService|TronCollectService|CryptoNotifyService|CryptoProviderService|Service 负责|调度 Service|共用 Service","path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","output_mode":"content","-n":true}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" I'm checking the document for consistency in heading formatting, specifically looking for any remaining subsections marked with double hashes followed by a number pattern like \"## 1.2\"."},{"type":"tool_use","name":"Grep","input":{"pattern":"^## \\d+\\.\\d+","path":"/Users/ray/Documents/project/www/ray/docs/requirements/USTD.md","output_mode":"content","-n":true}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":" All the subsection headings are fixed now, and I can mark matching and miscellaneous as complete. Since this is just a documentation change with no PHP files modified, the slot-backend completion gate doesn't apply and I don't need to run a verify script. Let me wrap up the remaining todos and provide a final summary."},{"type":"tool_use","name":"TodoWrite","input":{"merge":true,"todos":[{"id":"matching","content":"修正固定地址按金额匹配风险（第16节）","status":"completed"},{"id":"misc","content":"master_key 轮转、风险与待决策、标题层级修正","status":"completed"}]}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"已按团队分层规范并采纳全部评审建议更新 `docs/requirements/USTD.md`。本次仅改动需求文档（无 PHP 改动，后端门禁不触发）。\n\n## 主要改动\n\n**分层重构（第 11、17、25 节）**\n- 改为 `Controller / Validate / DTO / Logic / Service / Model / Command / Support`，与 `backend-layering` 对齐。\n- 业务用例编排与事务边界移入 **Logic**（`TronAddressLogic`、`TronDepositScanLogic`、`TronDepositConfirmLogic`、`CryptoDepositNotifyLogic` 等）。\n- **Service 收敛为公共能力**：`TronGatewayService`（TronGrid 封装）、`PayNotifyGatewayService`（走 slot_sdk 调 pay），删除原 6 个「Logic 型 Service」。\n- 新增 Validate / DTO 目录与职责说明；Command 改为只调度 Logic。\n\n**核心业务风险**\n- 固定地址撞单：新增 16.4「订单金额唯一化（随机尾数）」+ 16.5「无待支付订单到账」策略，匹配条件细化。\n- 扫描方式：17.1 改为**按用户地址轮询**（不扫全链 USDT Transfer），并加 `SCAN_SAFE_BLOCK_GAP` + 确认期主链校验规避 reorg。\n- 金额：第 7 节明确 `floor` 向下取整；第 8 节确认数公式修正为 `current - block + 1`，确认数/安全间隔配置归 env。\n\n**接口与安全**\n- 新增 13.0 内部接口鉴权（slot_sdk + `server-name` + 签名防重放 + 内网限制）。\n- 14.1 增加 pay 返回码表（1001/1002/1003/1004/5000）、可重试/不可重试分类、退避重试策略；新增 `next_notify_at` 字段与 `idx_notify_retry` 索引。\n- 13.1 地址 get-or-create 增加 Redis 锁 + 双检 + 唯一键冲突回查；17.2 确认/通知进程加锁。\n\n**表结构**\n- `crypto_deposit_tx` / `crypto_collect_tx` 唯一键预留 `(chain, tx_hash)`；`block_time` 标注 UTC；游标表补全局进度说明。\n\n**其他**\n- 第 19 节补 master_key 轮转预案（key_version）。\n- 新增第 26 节「风险与待决策」，区分已采用方案与待拍板项（无订单自动入账、尾数粒度、归集 gas、轮询规模等）。\n- 修正全部 `## x.y` 子标题为 `###`。\n\n待你拍板的关键决策已集中在第 26 节，尤其是 **16.5 无订单到账是否自动入账** 和 **16.4 唯一金额尾数粒度**，需结合 pay 侧实现确认。"}]}} |