integrate-1bill

集成 1BILL

构建可靠的 1LINK 1BILL 集成，避免将 1BILL 与 1GO/Raast P2M、1IBFT、银行卡网关或名为 OneBill 的无关产品混淆。

首先：检查并分类

始终先检查代码库，再进行规划或编写代码。搜索 1LINK 或 1BILL SDK、客户端、URL、凭据、账单机构前缀、PSID 或用户编号生成逻辑、查询／支付／撤销／状态处理程序、架构、数据库记录、消息签名、结算文件、对账任务、测试和认证材料。

• 如果已有集成，明确其对应的 1LINK 产品、API／目录版本、组织角色、环境、端点、身份验证／签名方案和已实现的流程。以最小改动修复现有设计。
• 如果没有集成，按照项目的语言、框架、数据模型、安全、日志、任务和测试惯例进行设计。
• 切勿臆造请求字段、响应码、签名、加密方式、URL、凭据、前缀规则、PSID 长度或超时行为。请从商户当前的 1LINK 沙盒／认证文档中获取这些信息。

选择流程前，先确定集成角色：

1. 调用 1BILL API 的 1LINK 成员银行或非银行发起方；
2. 为收款提供或连接账单数据的账单实体；
3. 通过获批合作方进行政府或机构收款；
4. 商户实际需要的是 1GO/Raast P2M 或银行卡结账，而非 1BILL。

确认产品

1BILL 是统一的账单支付通道，支持固定金额发票／凭证支付、可变金额／充值支付、信用卡账单支付以及套餐／捆绑服务流程。客户通常会在参与服务的银行、钱包、ATM 或柜台渠道中输入带账单机构前缀的用户、账单或 PSID 编号；该渠道会获取账单详情并提交付款。

不要将 1BILL 描述为嵌入式银行卡表单、订阅引擎、钱包推送 API 或 Stripe 的即时替代方案。如果需求是 QR、别名、IBAN 或付款请求商户受理，请考虑 1GO/Raast P2M。如果需求是银行卡结账，请考虑获批的支付网关。

工作流程

1. 获取最新的 1LINK 开发者门户产品选项、私有 API 规范／OpenAPI 文件、接入资料包、凭据、速率限制、测试数据、认证用例和生产切换说明。
2. 记录准确的目录／API 版本，并在修改代码前与任何现有实现进行比较。
3. 定义账单类别、账单机构前缀／编号规则、金额规则、有效期、重复付款策略、付款人可见字段和内部发票生命周期。
4. 将查询、支付、合同约定的撤销／冲正、支付状态查询、对账和异常处理建模为独立的幂等操作。
5. 由服务端权威管理账单编号、金额、有效期、已付款状态和结算。切勿信任客户端截图或客户端报告的结果。
6. 保存必要的关联标识，以便追踪应用记录、1LINK 请求、渠道交易、状态查询、结算和支持工单。
7. 严格按照当前认证资料包中的规定保护凭据和消息完整性。安全地拒绝无效、重放、未经授权或格式错误的请求。
8. 测试重复、延迟、缺失、冲正、超时和状态不明的交易，而不只测试成功支付。
9. 在投入生产前完成 1LINK 沙盒测试和正式认证。切换期间仅更改获批的环境配置。

可靠性规则

• 在状态查询或对账确认结果之前，将超时和传输故障视为结果未知；切勿盲目重试付款。
• 账单查询必须只读，付款提交则必须基于合同约定的唯一交易标识实现幂等。
• 对外部交易 ID 以及内部账单／付款引用实施唯一性约束。
• 使用事务性状态变更，并为财务事件保留只追加的审计跟踪。
• 切勿仅凭用户返回页面、屏幕截图、短信或前端请求将账单标记为已付款。
• 将交易记录与 1LINK／结算报告对账，并向操作人员提示差异。
• 保留便于人工查阅的支持信息，例如渠道、引用、金额、日期／时间以及跟踪／交易标识；不要记录机密信息或完整的敏感负载。

参考资料路由

• 阅读 references/product-and-api-surface.md，选择正确的 1LINK 产品，并了解公开确认的 1BILL 操作。
• 阅读 references/implementation-workflow.md，了解状态建模、查询／付款／状态／撤销流程、PSID／引用 UX 以及认证。
• 在实现身份验证、财务状态、重试、日志记录、对账或生产部署之前，阅读 references/security-and-reliability.md。
• 阅读 references/research-notes.md，了解注明日期的官方来源、公开文档的局限、近期社区报告以及必须重新核实的内容。

验证与输出

运行相关的格式化、Lint、类型检查和测试。报告是否找到 1BILL 或从头添加、选定的角色和产品、检查过的版本和私有规范、已实现的操作、幂等策略、对账计划、认证状态，以及仍需配置的 1LINK 或合作伙伴设置。明确标注假设，切勿将沙盒成功描述为生产批准。