diff --git a/docs/superpowers/specs/2026-07-14-cib-bank-integration-config-form-design.md b/docs/superpowers/specs/2026-07-14-cib-bank-integration-config-form-design.md new file mode 100644 index 0000000..8a79e85 --- /dev/null +++ b/docs/superpowers/specs/2026-07-14-cib-bank-integration-config-form-design.md @@ -0,0 +1,110 @@ +# 兴业银行联调基础配置确认表设计 + +## 目标 + +生成一份可由福建水务营收系统项目组与兴业银行共同填写、确认和回传的 Markdown 配置表,用于联调前的信息交换、网络开通、安全参数确认和责任边界核对。 + +## 文档定位 + +- 文档类型:兴业银行专项联调配置确认表。 +- 使用阶段:联调准备、网络申请、配置交换和联调准入检查。 +- 对接双方:兴业银行与福建水务营收系统项目组。 +- 目标文件:`docs/evidence/bank-integration/兴业银行联调基础配置确认表.md`。 + +## 状态规则 + +每一项配置使用以下状态之一: + +| 状态 | 含义 | +|---|---| +| 已确认 | 可由当前项目代码、正式文档或已验证环境直接确认 | +| 可预填 | 可根据当前实现预填,但仍需部署、运维或银行书面确认 | +| 待兴业银行提供 | 当前项目无法确定,需兴业银行提供 | +| 待我方提供 | 需我方运维、安全、业务或项目负责人提供 | +| 双方待确认 | 涉及双方共同选择或约定,不能由单方确定 | +| 不适用 | 经双方确认后不适用于本次联调范围 | + +不得把本地 Docker 测试账号、密码、端口或样本目录标记为正式联调配置。 + +## 表格结构 + +### 1. 文档基本信息 + +记录银行名称、分支机构、项目名称、环境、文档版本、双方负责人和更新时间。银行名称与项目名称可预填,分支机构及联系人待补充。 + +### 2. 兴业银行提供给我方 + +包括: + +- 银行测试环境接口地址、机构号、渠道号和商户号; +- 银行出口 IP、端口、访问方向和网络要求; +- SFTP/FTP 地址、端口、认证方式及送盘、回盘、对账目录; +- 数据格式、字符集、金额单位、日期格式和文件命名规则; +- 加密、签名、证书、时间戳、防重放和密钥交换规则; +- 正常与异常请求报文、送盘、回盘和对账样本; +- 错误码、超时、重试、对账和结算规则; +- 银行技术、业务及网络联系人。 + +### 3. 我方提供给兴业银行 + +包括: + +- 福建水务营收系统联调环境域名、入口 IP、端口和 HTTPS 证书信息; +- 兴业银行需要访问的接口相对路径; +- 我方访问银行的固定出口 IP; +- 我方机构编码、租户/机构映射和测试客户数据; +- 我方支持的数据格式、加密能力和文件传输协议; +- 我方技术、业务、运维和安全联系人; +- 联调时间窗口、故障通知方式和日志查询信息。 + +接口路径只预填当前代码可确认的相对路径,不虚构正式域名、外网 IP 或端口。 + +### 4. 双方共同确认 + +包括联调范围、接口版本、环境用途、网络访问矩阵、幂等键、超时时间、重试次数、文件处理时点、对账日切、异常补偿、验收标准和上线切换方式。 + +### 5. 当前填写完成度 + +汇总: + +- 已能从项目确认的内容; +- 可预填但需要复核的内容; +- 兴业银行必须提供的内容; +- 我方运维、安全和业务必须补充的内容; +- 阻止正式联调启动的关键缺口。 + +## 预填原则 + +当前可预填: + +- 对接银行为兴业银行; +- 项目名称为福建水务营收系统; +- 当前实现支持 XML/JSON 报文转换; +- 当前文件传输解析支持 SFTP/FTP,正式联调推荐 SFTP; +- 当前接口类别包括欠费查询、实时缴费、缴费红冲、代扣/托收签解约、客户校验、送盘、回盘及状态查询; +- 当前网关存在 `/app-api/bankbusiness/**` 银行侧路由。 + +必须保持待确认: + +- 兴业银行具体分支机构; +- 双方测试环境域名、IP、端口及白名单; +- 银行机构号、渠道号、商户号; +- 正式接口是否统一经网关访问; +- 兴业银行采用的加密、签名和证书规则; +- SFTP 地址、账号、目录及认证方式; +- 兴业银行私有报文和文件格式; +- 生产或联调密钥、密码、私钥。 + +## 安全约束 + +- 表内不记录密码、私钥、完整对称密钥或可直接使用的生产凭据。 +- 敏感项只记录密钥编号、证书指纹、有效期、交换方式和责任人。 +- IP、域名和证书信息在对外发送前由我方运维或安全人员复核。 +- 所有本地 Docker smoke 参数只作为内部验证证据,不进入对外配置值。 + +## 完成标准 + +- 表格明确区分双方提供项和共同确认项。 +- 所有预填值都有当前项目证据,不确定内容明确留空并标注责任方。 +- 表格可以直接发送给兴业银行填写,不要求对方阅读项目源码或内部设计文档。 +- 文档末尾明确给出当前是否具备接口预联调、网络联调和端到端业务联调条件。