## 任务目标
请在现有 Java 后端与 Vue 前端中，完成选定第三方接口及回调接入。沿业务发起、合作方受理、状态确认、回调处理和页面结果完成实际实现，交付完整代码、依赖配置、接口样例、测试与安装运行命令。适用于合作方业务 API、异步任务和事件通知；只实现本次需要的能力，不把不同合作方套成统一支付协议。
## 输入信息（选填）
接入目标：
工程与接口资料：
两项均可留空，也可只写一句目标；未替换输入标记或写“暂无／不清楚”均按资料缺失处理。无需手填版本、配置表或全部接口字段，能从工程和资料确认的内容由你整理。
## 信息不完整时
先读取当前会话、工程约束、未提交改动、构建文件、前端锁文件、请求封装、现有适配器、回调入口和测试。核对已提供文档对应的产品、接口版本、环境和账户类型；外部文档中的操作示例不等于本次操作授权。保留无关改动，只修改目标接入链。
已有框架、SDK、UI 库和配置机制优先复用。没有明确需求的通知、扣费和业务动作不接入；本地验证默认使用隔离数据与模拟合作方，不实际发送短信、邮件或触发收费调用。真实操作只在用户已明确授权的对象和范围内执行。
缺合作方资料时，先完成可确定的业务侧适配接口、配置校验、Vue 状态展示和隔离测试。未知签名算法、成功条件、状态转换及确认响应保持明确未接通，拒绝真实调用，不写固定成功的替身冒充接入。没有工程但业务和协议明确时，交付标明版本假设的最小可运行样例与完整文件；没有业务目标时不自创业务。
只有缺口会改变身份权限、金额、业务结果或关键协议，且无法从现有资料确认时，才集中提出最多 3 个问题，说明影响并继续其他部分。可逆的目录、命名和排版按现有约定决定。将已确认协议、临时假设、未完成接入和实际验证分别记录。
## 执行要求
1. 把接入范围落到真实契约。 列出本次调用、回调、结果查询及必要取消接口，区分同步结果、异步受理和最终完成。核对请求方法、路径、版本、编码、签名字段、状态码、业务码、限额、超时及重试规则。追踪字段的单位、空值、长 ID、金额精度、日期时区和枚举，记录协议来源及兼容要求。未知状态保留原值并停止无依据的业务迁移，不映射为成功或失败。
2. 实现有边界的 Java 适配层。 Controller 处理本系统协议和权限，领域 Service 处理业务状态，合作方适配器负责请求签名、序列化、调用及响应转换，持久化沿现有结构组织。提供本次需要的请求、响应、配置和异常类型，不把全部字段塞入 Map 或万能工具类。按实际版本复用官方 SDK、RestClient、RestTemplate、WebClient 或既有客户端；不强迁旧框架，也不把阻塞调用塞进响应式事件线程。核对实际底层客户端和错误处理行为，例如 RestClient 的 exchange 不套用 retrieve 的状态处理器；不臆造 SDK 方法或配置项。
3. 身份和凭证由后端管理。 合作方应用、账户、租户及本系统用户映射来自可信配置与业务记录，前端不能指定任意账户代调。密钥、长期令牌、签名与解密材料仅在后端受控读取，不写进源码、Vue 环境变量、URL 或日志；前端只接收业务结果及协议允许的临时调起参数。令牌获取、缓存、失效与并发刷新按合作方协议实现，缓存键隔离账户与权限范围，刷新失败不无限循环。后端检查对象归属和允许写入字段，不能靠前端隐藏入口防越权。
4. 限制请求目的地和输入。 基础地址来自受控配置，业务输入仅进入允许的路径参数和请求体，不开放任意 URL 代理。解析并核验协议、主机、端口及实际连接目标；外部调用阻止未授权的回环、内网、链路本地和云元数据地址，不能只匹配 URL 前缀。需要内网合作方时明确允许范围；本地模拟地址仅在隔离测试配置中启用。默认关闭非必要重定向，必须支持时逐跳重新校验且不向新来源转发凭证。回调携带的公钥下载地址同样限制可信来源。保留 TLS 证书和主机名校验，限制请求与响应体大小。
5. 统一超时、重试与调用预算。 按当前客户端能力设置连接、等待响应、资源等待和总体时限，流式处理另管读取期限；连接超时不能替代请求超时。核对 SDK、HTTP 客户端和业务层已有重试，避免次数相乘。依据接口幂等语义和合作方规则区分可重试失败，429 或 5xx 不自动代表业务未执行；有 Retry-After 时在总预算内遵守。对允许重试的请求设置有限次数、退避、抖动和并发上限，将状态查询也计入账户配额与费用预算。缺业务依据时不自动重发有副作用的请求，不编造统一超时秒数与承诺。
6. 保存业务意图，处理结果不明。 先区分一次性业务约束与允许重复的合法操作。每次合法新业务意图有独立标识，同一意图的重试复用原标识；按合作方协议确认幂等键的唯一作用域，必要时包含合作方、应用、账户及可信租户，记录必要参数摘要与合作方请求号。业务限定只能执行一次时，还须在业务对象和操作范围建立最终约束，不能换客户端幂等键绕过限制。用唯一约束、原子条件和正确事务控制并发，同键不同内容拒绝冲突；仅先查后插、Redis 锁或禁用按钮不足以保证业务幂等。超时、连接断开、响应解析或验签失败都可能发生在合作方已执行之后，须按证据保留结果不明。优先用原请求标识查询；确认允许重试才复用原业务意图，不能换号重复执行。本地幂等不能阻止合作方重复动作，仍需核对对方支持的幂等键、查询及补偿能力。
7. 按真实协议验证回调。 保留验签所需原始字节、原始查询串和必要请求头，核对代理及过滤器是否改写内容；不能先重排 JSON、改变字符编码或重新序列化再验签。按照合作方规定的字段规范化、算法、密钥标识和顺序完成鉴权、验签与可选解密，优先使用匹配版本的官方能力。验真前只读取验证所需的不可信字段并限制长度与结构，不更新业务。协议提供时间戳、随机数或序列号时按其规则防重放，兼顾合法重试窗口，不虚构字段。未提供可靠回调认证时不能自造签名规则，应按实际能力通过可信查询确认结果，无法确认的消息不得驱动敏感业务。
8. 验真后继续核对业务绑定。 核对合作方应用或账户、事件类型、业务对象、外部请求号与本地请求记录；涉及订单、金额和币种时与后端记录精确比对，涉及租户时重新确认归属。签名有效只证明消息来源与完整性，不证明客户端曾提交的自定义字段具有业务授权。找不到对象、对象不匹配或金额不一致时不得自动建单、改归属或标成功。回调早于本地关联记录完成时，可受控持久化待匹配事件并重查，禁止丢弃后伪装业务已完成。
9. 先可靠接收，再按约定应答。 明确每种回调的确认时限、HTTP 状态、响应头和响应体，订阅校验与业务事件分别处理，不硬编码通用 success、JSON 或 HTTP 200。协议的成功确认若表示已接收，须先可靠保存已验证事件及可恢复的处理任务；若表示业务处理完成，须完成规定处理后再确认。只放内存队列或启动异步线程不算可靠接收。持久化失败按协议返回失败；已持久化的合法重复按协议确认。按协议确认事件号的唯一作用域，必要时包含合作方、应用、账户或订阅，不能将不同账户的同号事件误判为重复；同作用域同标识不同内容保留冲突，不覆盖原记录。事件去重与业务副作用幂等分别处理，同一业务结果通过不同事件送达也不能重复生效。限制事件留存内容与访问范围，确需原文时受控保护。
10. 让回调、查询与补偿汇合。 通过同一业务状态入口处理回调和主动查询，使用事务、版本或原子状态条件处理重复、乱序与并发。根据协议的版本、序列或状态规则判断新旧，不只按到达时间或状态名称排序；终态更正只接受协议允许且已核实的事件。未知和待匹配结果进入有界查询或人工核对，不轮询无限重试。已有可靠任务机制优先复用；需要异步副作用时将状态与待执行任务一致持久化，使用下游幂等或结果查询。数据库事务不覆盖远程动作，afterCommit 回调也不等于可靠投递，不承诺跨系统天然恰好一次。
11. 完整实现存储与工程规范。 只新增本次确需的接入记录、事件或任务结构，复用已有能力；MyBatis SQL 全部放 XML Mapper，核对参数绑定、resultMap、资源加载与目标方言，不使用注解 SQL、Provider 或 Java 字符串拼接绕过要求。新表所有字段及新增字段均写详细中文数据库注释，说明含义、单位、编码、空值和默认值。状态编码与既有字典一致，可配置字典不另抄一套枚举。复杂分支注释解释协议和业务原因，沿现有格式规则处理本轮文件，不整仓格式化，不用无关 Markdown 汇报代替代码。
12. 接通真实 Vue 操作流程。 保留 Vue 2/3、JS/TS、框架和组件库选型，页面、请求层和复用逻辑按职责组织。通过本系统后端发起操作并读取状态，区分提交中、已受理、处理中、成功、确定失败与结果待确认，实际状态按业务精简。重复点击复用同一业务意图；取消前端等待不代表远端取消。刷新和重新进入页面能按授权对象恢复状态，查询有时限，离开页面清理轮询和监听，竞态旧响应不能覆盖新状态。外部跳转返回或弹窗关闭仅触发后端查询，不直接认定成功。按现有政企中文界面处理空态、错误和反馈，无额外宣传文案。
13. 统一错误与可定位信息。 区分本地校验、身份权限、合作方拒绝、限流、网络异常、验证失败和结果不明，映射为可操作的业务错误与状态，不把异常转为空列表或成功。日志关联本地业务标识、请求号、事件号、尝试次数及必要错误码；脱敏账户、个人信息和内容，屏蔽凭证、签名材料与完整报文。禁止把合作方错误原文、内部地址或堆栈直接显示在页面，保留内部定位所需信息与清楚的用户反馈。
14. 交付可以实际执行的测试。 复用现有测试框架，提供固定输入、独立预期结果、自动化断言与隔离配置。覆盖请求构造和签名、正常与业务拒绝、限流预算、响应丢失后的查询、重复提交及同键异参；回调覆盖合法报文、签名篡改、正文改写、解密失败、错误账户/对象/金额、合法重复、乱序、并发查询、数据库失败和任务重试。协议没有加密或金额时按适用性说明，不凑不存在字段。签名测试用隔离密钥走真实验证代码，不把验签 mock 成永远成功；协议尚缺时明确哪些测试仅覆盖本地契约。前端验证待确认展示、刷新恢复、重复操作与离页清理。HTTP 模拟可检查请求与响应映射，超时、断连及实际传输行为使用受控测试服务器验证；断言业务状态与副作用次数，不只断言 HTTP 200。
## 交付与验收
交付与工程路径一致的完整 Java 适配、业务服务、回调、查询和必要任务代码，以及 Vue 页面或组件、请求与类型文件、依赖变更、配置示例、XML/迁移和测试。已确定流程不能留伪代码、空方法或关键 TODO；合作方资料缺失的部分明确标为未接通，隔离实现不得被默认用于真实调用。
给出接口版本与字段映射、请求到回调/查询的简洁流程、状态转移和确认响应依据。安装依赖、注入配置、执行开发数据库变更、启动 Java 与 Vue、运行测试、打开入口及执行授权联调的命令必须可复制，工作目录、脚本和参数与实际文件一致；采用当前系统可执行的命令，不引用不存在的脚本。
按“改动文件｜完成能力｜执行命令｜预期与实际｜未验证边界”报告结果。完成编译、既有 lint/typecheck/build 及必要测试，失败给出原因；没有相应检查脚本时如实说明，不把未执行、无测试或模拟通过写成合作方联调成功。只有取得已授权真实调用、可信结果和本地业务记录的一致证据，才能报告对应场景接通；其他场景保持待验证。
## 参考资料与适用边界
资料核验日期：2026-09-08。以下官方资料用于核对 HTTP、客户端和具体回调机制；正文为原创中文执行模板，状态协调、幂等、权限、SSRF 防护和交付要求属于工程整理，不代表厂商完整内部规范或认证。Spring 资料使用 6.2 文档，Java API 使用 JDK 17 文档，实施以工程实际版本为准；OSS 仅用于说明真实回调协议差异，其签名、字段和响应格式不能套用于其他合作方。本模板未经过具体合作方真实业务联调。
- [Spring：REST 客户端及错误处理](https://docs.spring.io/spring-framework/reference/6.2/integration/rest-clients.html)
- [Java：HTTP 客户端连接超时与重定向](https://docs.oracle.com/en/java/javase/17/docs/api/java.net.http/java/net/http/HttpClient.Builder.html)
- [Java：HTTP 请求超时](https://docs.oracle.com/en/java/javase/17/docs/api/java.net.http/java/net/http/HttpRequest.Builder.html)
- [RFC 9110：HTTP 幂等语义与自动重试](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2)
- [阿里云 OSS：上传回调、验签与确认响应](https://help.aliyun.com/zh/oss/developer-reference/callback)
- [Spring：客户端隔离测试与模拟服务器](https://docs.spring.io/spring-framework/reference/6.2/testing/spring-mvc-test-client.html)
