{
  "openapi": "3.0.3",
  "info": {
    "title": "IDACHF-3 邮储收款账户增量接口",
    "version": "2026-07-21",
    "description": "PC 管理端邮储收款账户列表、详情和保存接口。写入 Apifox 项目 5737553 的 PC 端目录 48690332。"
  },
  "tags": [
    {
      "name": "邮储收款账户",
      "description": "账单管理下的邮储支付配置维护接口，与账单记录模块同级。"
    }
  ],
  "paths": {
    "/p/psbcaccount/list": {
      "post": {
        "tags": [
          "邮储收款账户"
        ],
        "x-apifox-folder": "邮储收款账户",
        "summary": "邮储收款账户列表",
        "description": "分页查询当前登录人学校数据权限范围内的邮储收款账户。商户号只返回脱敏值，列表不返回支付标识和任何密钥明文。需要登录并拥有 /billmanage/bankaccount 菜单权限。",
        "operationId": "psbcAccountList",
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PsbcAccountListRequest"
              },
              "example": {
                "page": 1,
                "page_size": 10,
                "name": "荣海小学",
                "status": 3,
                "school_uuid": "school-a-uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "业务结果，以 code=0 表示成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PsbcAccountListResponse"
                },
                "examples": {
                  "success": {
                    "summary": "查询成功",
                    "value": {
                      "code": 0,
                      "message": "查询成功",
                      "data": {
                        "total": 1,
                        "per_page": 10,
                        "current_page": 1,
                        "last_page": 1,
                        "storage_ready": true,
                        "data": [
                          {
                            "id": 1,
                            "uuid": "cc819d52-14c3-4bd1-a81b-c08ae3ce1cad",
                            "name": "荣海小学餐费账户",
                            "status": 3,
                            "status_label": "可用",
                            "settlement_desc": "学生餐费统一结算",
                            "merchant_no_masked": "********2386",
                            "school_uuid": "school-a-uuid",
                            "school_name": "荣海小学",
                            "school_uuids": [
                              "school-a-uuid"
                            ],
                            "school_names": [
                              "荣海小学"
                            ],
                            "version_no": 1,
                            "remark": "测试账户",
                            "is_legacy": false,
                            "editable": true,
                            "update_time": "2026-07-21 14:30:00"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/p/psbcaccount/detail": {
      "post": {
        "tags": [
          "邮储收款账户"
        ],
        "x-apifox-folder": "邮储收款账户",
        "summary": "邮储收款账户详情",
        "description": "按 ID 查询账户详情。平台管理员得到三个密钥的脱敏值，格式为开头 8 位 + ******** + 结尾 8 位，用于查看和比对；浏览器不会收到完整密钥。其他有页面权限的账号只得到已配置标记，不返回密钥字段。响应禁止缓存。",
        "operationId": "psbcAccountDetail",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PsbcAccountDetailRequest"
              },
              "example": {
                "id": 1
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "业务结果，以 code=0 表示成功",
            "headers": {
              "Cache-Control": {
                "description": "固定包含 no-store、no-cache",
                "schema": {
                  "type": "string",
                  "example": "no-store, no-cache, must-revalidate"
                }
              },
              "Pragma": {
                "description": "禁止缓存",
                "schema": {
                  "type": "string",
                  "example": "no-cache"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PsbcAccountMaskedDetailResponse"
                },
                "examples": {
                  "platformManager": {
                    "summary": "平台管理员查询成功",
                    "value": {
                      "code": 0,
                      "message": "查询成功",
                      "data": {
                        "id": 1,
                        "uuid": "cc819d52-14c3-4bd1-a81b-c08ae3ce1cad",
                        "name": "荣海小学餐费账户",
                        "status": 3,
                        "status_label": "可用",
                        "settlement_desc": "学生餐费统一结算",
                        "school_uuid": "school-a-uuid",
                        "school_name": "荣海小学",
                        "merchant_no": "100610100002386",
                        "merchant_no_masked": "********2386",
                        "payment_id": "shop-payment-001",
                        "merchant_public_key": "MERCHANT********BLIC-KEY",
                        "merchant_private_key": "MERCHANT********VATE-KEY",
                        "psbc_public_key": "PSBC-SM2********BLIC-KEY",
                        "merchant_public_key_configured": true,
                        "merchant_private_key_configured": true,
                        "psbc_public_key_configured": true,
                        "config_complete": true,
                        "version_no": 1,
                        "remark": "测试账户",
                        "is_legacy": false,
                        "editable": true,
                        "update_time": "2026-07-21 14:30:00"
                      }
                    }
                  },
                  "notFoundOrForbidden": {
                    "summary": "不存在或无学校权限",
                    "value": {
                      "code": 1,
                      "message": "邮储收款账户不存在或无权查看",
                      "data": []
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/p/psbcaccount/save": {
      "post": {
        "tags": [
          "邮储收款账户"
        ],
        "x-apifox-folder": "邮储收款账户",
        "summary": "新增或编辑邮储收款账户",
        "description": "仅平台管理员可调用。id 为空时新增，传 id 时编辑。账户状态只允许 3=可用、4=停用；可用必须绑定一所顶级学校，停用不得绑定学校。新增时三个密钥必填；编辑时密钥不传或传空会保留原密文，不能把详情接口返回的带 ******** 脱敏值作为新密钥提交。若学校已有账户，首次返回确认提示，再传 confirm_replace_binding=1 后停用旧账户并完成替换。",
        "operationId": "psbcAccountSave",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PsbcAccountMaskedAwareSaveRequest"
              },
              "examples": {
                "create": {
                  "summary": "新增可用账户",
                  "value": {
                    "name": "荣海小学餐费账户",
                    "status": 3,
                    "settlement_desc": "学生餐费统一结算",
                    "school_uuid": "school-a-uuid",
                    "merchant_no": "100610100002386",
                    "payment_id": "shop-payment-001",
                    "merchant_public_key": "MERCHANT-SM2-PUBLIC-KEY",
                    "merchant_private_key": "MERCHANT-SM2-PRIVATE-KEY",
                    "psbc_public_key": "PSBC-SM2-PUBLIC-KEY",
                    "remark": "开户、联调或使用说明"
                  }
                },
                "editWithoutChangingKeys": {
                  "summary": "编辑基础资料并保留原密钥",
                  "value": {
                    "id": 1,
                    "name": "荣海小学餐费账户",
                    "status": 3,
                    "settlement_desc": "学生餐费统一结算",
                    "school_uuid": "school-a-uuid",
                    "merchant_no": "100610100002386",
                    "payment_id": "shop-payment-001",
                    "remark": "修改说明"
                  }
                },
                "disable": {
                  "summary": "停用账户",
                  "value": {
                    "id": 1,
                    "name": "荣海小学餐费账户",
                    "status": 4,
                    "school_uuid": "",
                    "merchant_no": "100610100002386",
                    "payment_id": "shop-payment-001"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "业务结果，以 code=0 表示成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PsbcAccountMaskedAwareSaveResponse"
                },
                "examples": {
                  "success": {
                    "summary": "保存成功",
                    "value": {
                      "code": 0,
                      "message": "保存成功",
                      "data": {
                        "id": 1,
                        "uuid": "cc819d52-14c3-4bd1-a81b-c08ae3ce1cad",
                        "name": "荣海小学餐费账户",
                        "status": 3,
                        "status_label": "可用",
                        "school_uuid": "school-a-uuid",
                        "school_name": "荣海小学",
                        "merchant_no": "100610100002386",
                        "merchant_no_masked": "********2386",
                        "payment_id": "shop-payment-001",
                        "merchant_public_key_configured": true,
                        "merchant_private_key_configured": true,
                        "psbc_public_key_configured": true,
                        "version_no": 1,
                        "editable": true
                      }
                    }
                  },
                  "schoolConflict": {
                    "summary": "学校已有当前账户，需要二次确认",
                    "value": {
                      "code": 1,
                      "message": "所选学校已有当前收款账户，请确认后再更换",
                      "data": []
                    }
                  },
                  "permissionDenied": {
                    "summary": "非平台管理员",
                    "value": {
                      "code": 1,
                      "message": "仅平台管理员可维护邮储收款账户",
                      "data": []
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PsbcAccountListRequest": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "description": "页码"
          },
          "page_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 10,
            "description": "每页数量"
          },
          "name": {
            "type": "string",
            "description": "账户名称模糊查询",
            "example": "荣海小学"
          },
          "status": {
            "type": "integer",
            "enum": [
              3,
              4
            ],
            "description": "账户状态：3可用，4停用"
          },
          "school_uuid": {
            "type": "string",
            "description": "顶级学校 UUID；学校候选项来自 POST /p/staff/tree 的 data.department",
            "example": "school-a-uuid"
          }
        }
      },
      "PsbcAccountDetailRequest": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 1
              },
              {
                "type": "string",
                "enum": [
                  "legacy_psbc_config"
                ]
              }
            ],
            "description": "配置主键；legacy_psbc_config 仅用于配置表未初始化时的历史只读记录",
            "example": 1
          }
        }
      },
      "PsbcAccountMaskedAwareSaveRequest": {
        "type": "object",
        "required": [
          "name",
          "status",
          "merchant_no",
          "payment_id"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1,
            "description": "编辑时传配置主键；新增时不传"
          },
          "name": {
            "type": "string",
            "maxLength": 100,
            "description": "账户名称，同一商城内不能重复",
            "example": "荣海小学餐费账户"
          },
          "status": {
            "type": "integer",
            "enum": [
              3,
              4
            ],
            "default": 3,
            "description": "账户状态：3可用，4停用"
          },
          "settlement_desc": {
            "type": "string",
            "maxLength": 500,
            "description": "结算说明"
          },
          "school_uuid": {
            "type": "string",
            "description": "顶级学校 UUID。状态为3时必填，状态为4时必须为空",
            "example": "school-a-uuid"
          },
          "merchant_no": {
            "type": "string",
            "maxLength": 128,
            "description": "B2C 商户号",
            "example": "100610100002386"
          },
          "payment_id": {
            "type": "string",
            "maxLength": 128,
            "description": "统一收单门店号或支付标识",
            "example": "shop-payment-001"
          },
          "merchant_public_key": {
            "type": "string",
            "writeOnly": true,
            "description": "商户 SM2 公钥完整值。新增必填；编辑时不传或传空表示保持原值，不接受带 ******** 的详情脱敏值"
          },
          "merchant_private_key": {
            "type": "string",
            "writeOnly": true,
            "format": "password",
            "description": "商户 SM2 私钥完整值。新增必填；编辑时不传或传空表示保持原值，不接受带 ******** 的详情脱敏值"
          },
          "psbc_public_key": {
            "type": "string",
            "writeOnly": true,
            "description": "邮储支付 SM2 公钥完整值。新增必填；编辑时不传或传空表示保持原值，不接受带 ******** 的详情脱敏值"
          },
          "remark": {
            "type": "string",
            "maxLength": 500,
            "description": "备注"
          },
          "confirm_replace_binding": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "default": 0,
            "description": "学校已有账户时，二次确认传1；保存成功后旧账户会被停用并解除学校绑定"
          }
        }
      },
      "PsbcAccountListItem": {
        "type": "object",
        "properties": {
          "id": {
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ],
            "description": "配置主键；历史只读兼容记录为 legacy_psbc_config"
          },
          "uuid": {
            "type": "string",
            "description": "配置 UUID"
          },
          "name": {
            "type": "string",
            "description": "账户名称"
          },
          "status": {
            "type": "integer",
            "enum": [
              3,
              4
            ],
            "description": "账户状态：3可用，4停用"
          },
          "status_label": {
            "type": "string",
            "enum": [
              "可用",
              "停用"
            ]
          },
          "settlement_desc": {
            "type": "string"
          },
          "school_uuid": {
            "type": "string",
            "description": "绑定学校 UUID；未绑定时为空字符串"
          },
          "school_name": {
            "type": "string",
            "description": "绑定学校名称"
          },
          "school_uuids": {
            "type": "array",
            "deprecated": true,
            "description": "旧前端兼容字段，当前最多一个学校",
            "items": {
              "type": "string"
            }
          },
          "school_names": {
            "type": "array",
            "deprecated": true,
            "description": "旧前端兼容字段，当前最多一个学校",
            "items": {
              "type": "string"
            }
          },
          "merchant_no_masked": {
            "type": "string",
            "description": "脱敏商户号，仅显示最后4位",
            "example": "********2386"
          },
          "version_no": {
            "type": "integer",
            "description": "支付参数版本号"
          },
          "remark": {
            "type": "string"
          },
          "is_legacy": {
            "type": "boolean",
            "description": "是否为缺表场景下的历史只读兼容记录"
          },
          "editable": {
            "type": "boolean",
            "description": "当前记录是否允许编辑"
          },
          "create_time": {
            "type": "string",
            "description": "创建时间"
          },
          "update_time": {
            "type": "string",
            "description": "最近更新时间"
          }
        }
      },
      "PsbcAccountMaskedDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PsbcAccountListItem"
          },
          {
            "type": "object",
            "properties": {
              "merchant_no": {
                "type": "string",
                "description": "完整 B2C 商户号"
              },
              "payment_id": {
                "type": "string",
                "description": "统一收单门店号或支付标识"
              },
              "merchant_public_key": {
                "type": "string",
                "readOnly": true,
                "description": "商户 SM2 公钥脱敏值，仅平台管理员详情返回；格式为开头 8 位 + ******** + 结尾 8 位"
              },
              "merchant_private_key": {
                "type": "string",
                "format": "password",
                "readOnly": true,
                "description": "商户 SM2 私钥脱敏值，仅平台管理员详情返回；格式为开头 8 位 + ******** + 结尾 8 位"
              },
              "psbc_public_key": {
                "type": "string",
                "readOnly": true,
                "description": "邮储支付 SM2 公钥脱敏值，仅平台管理员详情返回；格式为开头 8 位 + ******** + 结尾 8 位"
              },
              "merchant_public_key_configured": {
                "type": "boolean"
              },
              "merchant_private_key_configured": {
                "type": "boolean"
              },
              "psbc_public_key_configured": {
                "type": "boolean"
              },
              "config_complete": {
                "type": "boolean",
                "description": "支付参数是否完整"
              }
            }
          }
        ]
      },
      "PsbcAccountListPage": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          },
          "current_page": {
            "type": "integer"
          },
          "last_page": {
            "type": "integer",
            "description": "无数据时为0"
          },
          "storage_ready": {
            "type": "boolean",
            "description": "支付配置表和环境加密密钥是否均已就绪；false 时页面只读"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PsbcAccountListItem"
            }
          }
        },
        "required": [
          "total",
          "per_page",
          "current_page",
          "last_page",
          "storage_ready",
          "data"
        ]
      },
      "PsbcAccountListResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": 0
          },
          "message": {
            "type": "string",
            "example": "查询成功"
          },
          "data": {
            "$ref": "#/components/schemas/PsbcAccountListPage"
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      },
      "PsbcAccountMaskedDetailResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "0成功，1失败"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PsbcAccountMaskedDetail"
              },
              {
                "type": "array",
                "maxItems": 0,
                "description": "失败时返回空数组"
              }
            ]
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      },
      "PsbcAccountMaskedAwareSaveResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "0成功，1失败"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PsbcAccountMaskedDetail"
              },
              {
                "type": "array",
                "maxItems": 0,
                "description": "失败时返回空数组"
              }
            ]
          }
        },
        "required": [
          "code",
          "message",
          "data"
        ]
      }
    }
  }
}