SFT/缺失的后端接口.md

缺失的后端接口 / 真实接口契约说明

更新说明:阶段1(工程基础设施+登录+系统管理)与阶段2(基础配置:核心企业/客户经理)原先按前端自 行设计的契约用 mock-server/ 模拟开发。现后端已提供首版真实接口(swagger_project_scfs_2026-07- 09_14-15-23.json),前端已完成对接改造,不再使用 mock 契约。本文档改为:Part 1 速查已对接的 真实接口契约(便于前后端联调核对);Part 2 列出联调/开发中发现的、后端文档未覆盖或建议后续 补充的事项。mock-server/ 保留作无后端环境下的应急本地演示兜底,契约与下文不一致,不作为参考。

通用约定(均已通过真实 swagger 核实):

• 所有接口返回统一包裹结构 { code: number, message: string, data: any },code === 200 表示业务成功, 前端统一按 code !== 200 判断失败并展示 message,不再做具体错误码分支处理。
• 除登录、刷新令牌、发送短信外,其余接口均需在请求头携带 Authorization: Bearer {token}。
• 日期时间字段格式统一为 yyyy-MM-dd HH:mm:ss。
• 分页查询接口(.../page)请求 Body 均含 page(从1开始)、pageSize;响应 data 统一为 { total, page, pageSize, records: [...] }(字段名为 records,不是 list)。
• 除个别接口(见下文标注)外,增删改接口均为单条操作,不提供批量接口。

Part 1:已提供接口契约速查

1.1 通用鉴权

接口	说明
POST /api/auth/login-password	账号密码登录,Body {username, password},响应 LoginVo
POST /api/auth/login-phone	手机验证码登录,Body {phone, smsCode},响应 LoginVo
POST /api/auth/send-sms-code	发送短信验证码,Body {phone, businessType},登录场景前端暂传 businessType: 'LOGIN'(见 Part 2-1)
POST /api/auth/refresh-token	刷新令牌,无 Body,依赖 httpOnly Cookie 中的 refresh_token(不携带 Authorization 头),响应 LoginVo
POST /api/auth/logout	登出,无 Body
POST /api/auth/user-info	获取当前用户信息,无 Body(基于当前 JWT),响应 UserDetailVo
GET /api/auth/user/permission-detail?userId=	获取用户扁平权限列表 UserPermissionDetailVo[],前端自行 buildTreeFromFlat/extractMenuTree/extractButtonCodes
POST /api/auth/change-password	修改密码,Body {oldPassword, newPassword}(首次登录强制改密场景复用)
POST /api/user/reset-password	管理员重置用户密码,Body {userId}
POST /api/auth/reset-password	找回密码场景(未接入前端,登记备查),Body {phone, smsCode, newPassword}

LoginVo 字段:{ token, username, realName, userId, phone, userType, organizationId, forceChangePwd }。

1.2 系统管理 —— 用户

接口	Body/Query	说明
POST /api/auth/user/page	{organizationId, usernameLike, phone, status(ACTIVE|LOCKED), roleId, page, pageSize}	响应 records: UserPageVo[](含 organizationName/roleNameList,不含 roleIds/createdAt)
POST /api/auth/user/create	{username, phone, realName, organizationId, status, email, userRoleBtoList:[{roleId}]}	响应 CreateUserVo{id,status},不返回初始密码
POST /api/user/update	{id, username, phone, realName, organizationId, email, userRoleBtoList:[{userId,roleId}]}
POST /api/user/delete	{userId}	单条
POST /api/user/lock / POST /api/user/unlock	{userId}
GET /api/auth/user-role/list-by-user?userId=	—	响应 UserRoleVo[]{id(即roleId), roleName, organizationId, isBuiltIn},用于编辑用户时回填已选角色
POST /api/auth/user-role/bind / unbind	{userId, roleIdList}	独立接口,当前未使用(create/update 已内嵌 userRoleBtoList)

1.3 系统管理 —— 角色

接口	Body	说明
POST /api/role/page	{roleName, page, pageSize}	不支持按机构/状态过滤,响应 records: RoleVo[]
POST /api/role/detail	{roleId}	响应 RoleDetailVo{roleName,id,organizationId,isBuiltIn,permissionIdList}
POST /api/role/create	{roleName, organizationId, isBuiltIn}	不含权限,不返回新建 id(见 Part 2-2)
POST /api/role/update	{id, roleName, organizationId}	不含权限
POST /api/role/delete	{roleId}	单条
GET /api/auth/role-permission/list-by-role?roleId=	—	响应 RolePermissionVo[]
POST /api/auth/role-permission/bind / unbind	{roleId, permissionIdList}	前端采用"查旧集合→diff→分别 bind/unbind"策略

角色模型不含数据权限范围(dataScope)字段。

1.4 系统管理 —— 权限字典

接口	Body	说明
GET /api/permission/tree	—	响应嵌套树 PermissionTreeVo[],顶级 level=0
POST /api/permission/create	{permissionType(PAGE|BUTTON), permissionName, permissionCode, parentId, level, sortOrder, icon, routePath, pageResourcePaths[], apiResourcePaths[]}	响应 {id, permissionCode}
POST /api/permission/update	同上,不含 permissionType
POST /api/permission/delete	{id}

1.5 系统管理 —— 机构

接口	Body/Query	说明
GET /api/organization/query-tree	{organizationName?, organizationId?}	响应嵌套树 OrganizationTreeNodeVo[],不传筛选参数时返回全树
GET /api/organization/list-all	{organizationName?}	响应扁平 OrganizationSimpleVo[],用于表单"所属机构"下拉
POST /api/organization/create	{organizationName, parentId, remark}	parentId 为数字(引用上级机构的数字 id),响应完整 OrganizationDetailVo
POST /api/organization/update	{organizationId(字符串), organizationName, parentId, remark}	注意:定位字段是字符串业务码 organizationId,不是数字 id
POST /api/organization/delete	{organizationId(字符串)}	同上,响应 data 为 boolean

机构模型关键点:id(数字主键,供 parentId/用户/角色/核心企业/客户经理的 organizationId 外键引用)与 organizationId(字符串业务码,仅用于机构自身 update/delete 定位及 query-tree 筛选参数)是两个不同字段, 同时存在于同一条机构记录上。/api/organization/tree(POST,无筛选参数的全量树)与 query-tree 功能重叠, 前端统一只使用 query-tree。

1.6 基础配置 —— 核心企业 / 客户经理

接口	Body	说明
POST /api/core-enterprise/page	{page, pageSize, enterpriseName}	仅支持企业名称模糊搜索,响应 records: CoreEnterpriseVo[]
POST /api/core-enterprise/create / update / delete	见 CreateCoreEnterpriseBto/UpdateCoreEnterpriseBto(字段:enterpriseCode/enterpriseName/businessLicense/organizationId/contactPerson/contactPhone/status(ACTIVE|INACTIVE)/remark);delete Body {id}
POST /api/customer-manager/page	{page, pageSize, managerName}	仅支持姓名模糊搜索,响应 records: CustomerManagerVo[]
POST /api/customer-manager/create / update / delete	字段:managerCode/managerName/mobilePhone/organizationId/department/status(ACTIVE|INACTIVE)/remark;delete Body {id}

核心企业、客户经理模型均不含 organizationName,前端本地通过 organization/list-all 建 id→name 映射 展示所属机构列。

1.7 客户管理 —— 个人客户

接口	说明
POST /api/customer-info/personal/list	{organizationIdEq,customerCodeEq,customerNameLike,certificateNumberEq,page,pageSize},响应 records: IndividualCustomerListVo[](仅 id,organizationId,customerName,certificateType,certificateNumber,mobilePhone,ocrStatus,customerCode,不含性别/创建人/创建时间)
POST /api/customer-info/personal/detail	{id} 或 {customerCode},响应 IndividualCustomerDetailVo
POST /api/customer-info/personal/create	CreateIndividualCustomerBto,响应 data=新建id
POST /api/customer-info/personal/update	UpdateIndividualCustomerBto
POST /api/customer-info/personal/ocr-idcard	{fileBase64,channelNo,fileType('01'|'02')},响应 OcrIdCardResultVo
POST /api/customer-info/personal/upload-file	{fileBase64,channelNo},响应 {fileNo},个人身份证与企业营业执照图片均调用此通用接口

1.8 客户管理 —— 企业客户

接口	说明
POST /api/enterprise-customer/page	{page,pageSize,enterpriseName,businessLicense,mobilePhone},响应 records: EnterpriseCustomerVo[]
POST /api/enterprise-customer/detail	{id},响应 EnterpriseCustomerDetailVo
POST /api/enterprise-customer/create	{createEnterpriseCustomerBto,enableOcr}
POST /api/enterprise-customer/update	UpdateEnterpriseCustomerBto

1.9 钱包管理 —— 账户列表/账户主页

接口	说明
POST /api/wallet-account/page	{page,pageSize,accountName,accountNo,accountType(A1|A2|A3|A6|A7)},响应 records: WalletAccountVo[]
POST /api/wallet-account/detail	{id},响应 WalletAccountDetailVo{mainAccountNo,mainBalance,a2AccountNo,a2Balance,a6AccountNo,a6Balance,a7AccountNo,a7Balance}(不含 accountName)
POST /api/wallet-account/close	{id},销户
POST /api/wallet-account/open-sub-account	{accountNo}(主账户账号),开分户
POST /api/wallet-account/update	{accountNo,mobile,bankCardNumber,bankNo,bankName}
POST /api/wallet-account/change-mobile	{accountNo,newMobile}
POST /api/wallet-account/sync-balance	{id}
POST /api/wallet-account/transaction-detail	{accountNo,channelNo,startDate,endDate,page,rows},响应 TransactionDetailVo{...,detailList:TradeDetailItemVo[]}
POST /api/wallet-account/withdraw	{channelNo,withdrawRequestEo:WithdrawRequestEo},响应 WithdrawResultVo
POST /api/wallet-account/margin-pay / margin-release	MarginOperationRequestEo{accountNo,accountName,tradeAmount,remark},响应 MarginResultVo
POST /api/wallet-account/download-statement / download-receipt	均响应 {fileData(base64 PDF)}
POST /api/wallet-account/bind-card-list / bind-card / unbind-card	个人绑卡管理三件套

1.10 钱包管理 —— 个人开户(/api/wallet-management/personal-opening/*)

接口	说明
POST .../query-customer	个人开户专属客户查询,响应字段同 IndividualCustomerDetailVo
POST .../create-draft	提交开户草稿,响应 {applicationNo}
POST .../query-progress	{applicationNo},响应 ApplicationProgressVo

1.11 钱包管理 —— 企业开户申请与企业绑卡(/api/wallet-management/enterprise-open-application/*、enterprise-bank-card/*)

接口	说明
POST enterprise-open-application/list	响应 records: EnterpriseAccountOpenApplicationListVo[](无 id 字段)
POST enterprise-open-application/create	CreateEnterpriseAccountOpenBto,响应 {applicationNo}
POST enterprise-open-application/detail	{applicationNo},响应 EnterpriseAccountOpenApplicationDetailVo(无 id 字段)
POST enterprise-open-application/update	UpdateEnterpriseAccountOpenApplicationBto,要求 id(int64)
POST enterprise-bank-card/list / bind / unbind	企业绑卡管理三件套,字段结构同个人绑卡但用 primaryAccount/accountProperty

1.12 授信管理 —— 贷款申请(/api/credit-apply/*)

接口	说明
POST credit-apply/loan-application/list	柜员分页查询,入参仅支持 loanApplicationId/applicationStatus/applicationType/customerName/createDateStart/createDateEnd,响应 records: LoanApplicationVo[]
POST credit-apply/loan-application/detail	{loanApplicationId},响应 LoanApplicationDetailVo(个人/企业字段混合于同一模型,约60余字段)
POST credit-apply/personal-loan-application/create / update	个人贷款申请草稿创建/修改(仅 DRAFT 可改),响应 data 为 loanApplicationId 字符串
POST credit-apply/enterprise-loan-application/create / update	企业贷款申请草稿创建/修改,响应 CreateEnterpriseLoanDraftResultVo
POST credit-apply/loan-application/confirm	申请人微信扫码确认(短验+人脸识别),移动端流程,不在本项目前端范围

1.13 商户中心 —— 商户管理(/api/merchant/*)

接口	说明
POST merchant/page	分页,入参仅支持 merchantName,响应 records: MerchantVo[](13个字段,无 loanPeriod/orderType/productType/guarantorAccountName)
POST merchant/create	CreateMerchantBto,字段:merchantNo/merchantName/coreEnterpriseId/customerManagerId/organizationId/a1AccountNo/a2AccountNo/guarantorAccountNo/guarantorAccountName/maxGuaranteeAmount/loanProductCode/creditRatio/loanPeriod/orderType/productType/status/remark
POST merchant/update	UpdateMerchantBto,同上 + id
POST merchant/delete	{id}
—	无 /api/merchant/detail 接口;无 approve/audit/review 审批相关接口(已全量检索 swagger 确认)

1.14 商户中心 —— 发票管理(/api/invoice/*、/api/invoice-management/*)

接口	说明
POST invoice/create	发票登记(本地写操作),CreateInvoiceRegistrationBto
POST invoice/batch-create	批量发票登记(本地写操作),入参为 CreateInvoiceRegistrationBto[],响应 BatchInvoiceCreateResultVo(总数/成功数/失败数/失败详情JSON)
POST invoice/match	发票匹配,透传中台32007接口,无本地数据库操作,需 channelNo+matchType(1自动/2人工)+data:[{depositSerialNo,matchAmount}]
POST invoice/settle	发票清算并还款,透传中台22310接口,无本地数据库操作,仅需 channelNo+invoiceNo
POST invoice/delete	发票作废,透传中台31908接口,无本地数据库操作,仅需 channelNo+invoiceNo
POST invoice/unmatch	取消匹配(本地操作),仅需 matchRecordId
POST invoice/page	发票分页,透传中台31909查询接口,需 channelNo,与 invoice-management/invoice/list 功能重叠,本项目未使用
POST invoice-management/invoice/list	本地业务列表查询,FindInvoiceListQto(merchantIdIs/invoiceNoLike/registerDateStart-End/invoiceStatusList/matchStatusList/settleStatusList/accountNoLike/oppAccountNoLike/amountMin-Max)
POST invoice-management/invoice/detail	{id},响应含 matchRecordList: InvoiceMatchVo[]
POST invoice-management/repayment/list	查询可匹配的本地回款流水,FindRepaymentListQto(merchantIdIs/accountNoLike/oppAccountNoLike/timeStart-End)
POST invoice-management/offline-recharge-unmatched-detail	查询线下来账明细,透传中台30908接口,需 channelNo+交易日期范围,用于"自动匹配"高级场景,本次未在 UI 中实现对应入口

1.15 支付管理 —— 订单支付(/api/payment/*、/api/payment-management/*)

接口	说明
POST payment/query-credit-quota	查询授信额度,入参仅 {accountNo}(钱包账号字符串),响应 data 在 swagger 中完全未定义结构(无 $ref/无 properties),真正的未文档化接口,前端只能做防御性字段展示
POST payment/order-pay	创建支付,CreatePaymentBto:walletAccountId/loanApplyId(可空)/paymentMethod/payeeInfo/totalAmount/balanceAmount/financeAmount/status/remark/paymentDetailBtoList,无短信验证码字段
POST payment-management/query-payment-record	分页查询支付记录,FindPaymentRecordListQto,仅支持 walletAccountIdIs/paymentMethodList/statusList/paidAtStart/paidAtEnd,响应 PaymentRecordListVo[]
POST payment-management/query-payment-detail	{id},响应 PaymentRecordDetailVo(列表字段 + detailList: PaymentDetailVo[])
—	PaymentMethodEnum:BALANCE余额支付/FINANCE融资支付/COMBINED组合支付;PaymentStatusEnum:PENDING_VERIFICATION/VERIFYING/PROCESSING/SUCCESS/FAILED/CANCELLED;FundSourceEnum:BALANCE/FINANCE

1.16 订单管理 —— 汇总订单/原始订单(/api/summary-order/*、/api/original-order/*)

接口	说明
POST summary-order/page	请求仅支持 {page,pageSize,orderNo},响应 SummaryOrderVo(无关联原始订单明细列表)
POST summary-order/detail	{id},响应即 SummaryOrderVo 本身,不含关联原始订单明细
POST original-order/page	请求仅支持 {page,pageSize,originalOrderNo},不支持按 summaryOrderId 过滤
POST original-order/export	入参 {summaryOrderId,originalOrderNo} 均可选,响应 data 未定义结构,前端沿用 downloadStatement 已建立的 {fileData: base64} 假设处理
—	SettlementStatusEnum:UNSCHEDULED/SETTLED_REPAID/FAILED;SummaryOrderVo 含 financeQuota/accumulatedLoanAmount 等字段但无剩余额度字段,前端本地计算 剩余额度 = financeQuota - accumulatedLoanAmount

---

Part 2:待后端确认 / 建议补充事项

1. send-sms-code 的 businessType 取值无 enum 文档:swagger 仅标注为普通 string,登录场景前端暂定 传 'LOGIN',需后端确认合法取值枚举(找回密码场景描述提到 FIND_PASSWORD,登录场景取值待确认)。
2. POST /api/role/create 不返回新建记录 id:前端已改为"创建成功后按 roleName+organizationId 反查 role/page 取得 id 再绑定权限"规避,建议后端补充直接返回新建 id(core-enterprise/create、 customer-manager/create 同样不返回新建 id,当前无需立即二次操作故不阻塞,但建议一并补充以保持接口 一致性)。
3. 批量删除接口缺失:用户、角色、机构、核心企业、客户经理的删除接口均为单条,前端已改为循环调用 单条删除接口模拟批量交互(src/utils/loopDelete.js),建议后端评估是否补充原子性 batch 接口。
4. 管理员直接为其他用户指定新密码(无需旧密码)的接口不存在:原型图中的"密码修改"入口暂保留但 置灰禁用,提示改用"密码重置"。
5. user/create、user/reset-password 是否已实际发送短信通知用户,新密码规则(固定值/随机)未文档化: 前端仅按约定展示"已通过短信通知用户"提示文案,不做实际校验。
6. role-permission/bind/unbind 的语义(全量替换 vs 增量追加)未在 swagger 说明:前端已按"先查旧 集合、计算 diff、分别调用 bind(新增项)/unbind(移除项)"的保守策略实现,不受该语义影响,但建议 后端在文档中明确。
7. 角色列表(role/page)不支持按所属机构过滤;核心企业、客户经理列表只支持单一名称模糊搜索: 相比原前端自行设计的契约,过滤能力收窄,搜索表单已同步精简,若后续产品侧需要更多筛选维度,需后端 评估补充查询参数。
8. 角色数据权限范围(本机构/本机构及下级/全部)字段在真实模型中不存在:若产品侧仍需要该能力,需 后端评估补充。
9. 用户列表/详情不返回 roleIds:编辑用户角色时需额外调用 user-role/list-by-user,建议后端在 UserPageVo/UserDetailVo 中直接补充 roleIdList 以减少一次请求。
10. 权限字典种子数据需部署后手动初始化:用户/角色/机构/权限/核心企业/客户经理各页面与按钮节点, 需部署后通过新的"系统管理 > 权限管理"页面手动创建,并授予内置管理员角色,否则登录后看不到任何 菜单。当前 MainLayout.vue 菜单渲染只支持两级,初始化菜单节点时层级需控制在 2 级以内。
11. /api/auth/reset-password(找回密码)与登录页暂未接入:当前登录页仅实现"账号密码"与"手机验证码" 两种登录方式,找回密码入口未在本次范围内开发,契约已在 Part 1-1 登记备查。
12. 个人客户/企业客户均无删除接口:列表页暂不提供删除入口。
13. 营业执照无同步OCR识别接口:enterprise-customer/create 的 enableOcr 参数用途/时序未文档化, 前端按"手动填写+提交时告知后端可异步识别"实现。
14. 企业客户股东高管信息(enterpriseRelatedPersonBtoList)只能在新增时一次性提交:update/detail 接口均不支持读取或修改,编辑模式下该区块前端替换为提示文案,不可编辑。
15. 企业客户 businessLicenseFileNo 编辑/详情接口读取不到:编辑模式无法回显已上传的营业执照图片。
16. 企业客户分页查询不支持按所属机构/企业编号过滤:仅支持企业名称/营业执照号/手机号三项。
17. 个人客户 customerCode(客户编号)生成机制未文档化:前端创建时不传该字段,交由后端生成。
18. 身份证/营业执照 OCR 结果字段命名未在 swagger 明确标注(OcrIdCardResultVo 具体字段以实测为准), 前端 mapOcrIdCardResult 按常见字段名(name/sex/nation/idcard/address/authority/birth/validDate) 做防御性映射,识别失败或字段缺失时不阻断提交,允许手动填写。
19. 移动端确认页(个人开户 mobile/*、企业开户 confirm、贷款申请确认扫码后续)不属于本项目范围: 相关接口已在后端提供但本次前端管理后台不实现对应移动端页面,登记备查。
20. WalletAccountDetailVo 不含 accountName:账户主页展示的账户名称改为由列表页通过路由 query (accountName)传递,若用户直接刷新账户详情页地址,该字段会丢失显示为空,建议后端补充该字段。
21. 绑卡列表 BindCardVo 无法辨别"默认卡":提现/保证金默认取列表第一条作为默认卡,accountProperty (借记卡/贷记卡)枚举取值未在 swagger 明确列出,前端按"01借记卡/02贷记卡"猜测渲染文案,建议后端 在文档中补充该字段真实枚举及是否存在"设为默认卡"能力。
22. 对账单/回单下载接口 download-statement/download-receipt 所需的 originalSerialNo 无法从交易 明细 TradeDetailItemVo 中直接获得独立流水号字段:前端暂用该条记录的 id 字段兜底传递,若后端 实际需要的是独立业务流水号,批量下载回单功能将失败,需后端确认字段映射关系或补充响应字段。
23. 企业开户申请 enterprise-open-application/list、detail 接口返回的 Vo 均无 id 字段,但 update 接口的入参 UpdateEnterpriseAccountOpenApplicationBto 却要求 id(int64):前端编辑功能 已完整实现,提交更新时暂用 applicationNo(字符串)兜底传入 id 位置,该请求预计会被后端校验拒绝 或产生非预期行为,是本阶段最严重的接口契约缺口,需后端紧急评估:①在列表/详情 Vo 中补充 id 字段, 或②将 update 接口改为支持按 applicationNo 定位记录。
24. EnterpriseCustomerDetailVo 无 industry(所属行业)字段:企业开户申请表单选择企业客户后无法 自动回填所属行业,已改为用户手动填写该字段,若产品侧需要联动回填,需后端在企业客户详情接口中补充。
25. 企业开户申请受益人信息 enterpriseAccountOpenApplicationBeneficiaryBtoList 是否支持多条受益人 在 update 时的增删语义(全量替换 vs 增量)未在 swagger 说明:前端当前只支持维护单条受益人信息, 提交时整体覆盖该数组,若产品侧需要多受益人管理,需后端明确该数组的更新语义。
26. 贷款申请存在两组平行接口 /api/loan-application/* 与 /api/credit-apply/*:前者(create-personal create-enterprise/detail/page)与后者(personal-loan-application/create等)字段结构不同、 用途描述均不完整,前端已选用后者(credit-apply 组,描述明确标注"银行柜员"场景且具备 DRAFT→CONFIRMED→SUBMITTED 状态机,与阶段4风格一致),前者暂未使用,建议后端确认是否为废弃接口或 说明二者分工,避免维护两套语义重叠的接口。
27. 个人贷款申请草稿 CreatePersonalLoanApplicationDraftBto 不含 customerId/账户号(钱包账号)字段: 与企业贷款草稿 CreateEnterpriseLoanDraftBto(含 customerId+accountNo)不对称,个人贷款申请无法 与具体客户ID、具体钱包账号建立强关联,选择客户仅能回填 customerName/phoneNo/permanentAddress 三个文本字段,不产生外键关系,与需求文档"贷款钱包仅展示申请人已开立的钱包"的描述存在能力缺口, 建议后端为个人贷款草稿补充 customerId/accountNo 字段。
28. 贷款产品(loanProductCode)无独立的列表/字典查询接口:前端改为柜员手动输入产品编号文本框, 无法做下拉选择与合法性校验,建议后端补充贷款产品字典查询接口。
29. 企业贷款草稿字段 customerType 无 enum 约束说明:前端按项目既有命名习惯猜测传值 'ENTERPRISE', 需后端确认合法取值(可能是 'ENTERPRISE'/'BUSINESS'/'企业' 等其他形式)。
30. 贷款申请没有"按企业客户查询其已开立钱包账号"的专用接口:前端改为选定企业客户后,调用通用的 wallet-account/page 按 accountName(企业名称文本)模糊匹配钱包账户列表供人工选择,若同名不同企业 或企业名称与钱包账户名称不完全一致,可能匹配不到或匹配错误,建议后端补充按 customerId 精确查询 钱包账号的专用接口。
31. 法定代表人/配偶相关字段(legalPersonEducation/legalPersonMarital/legalPersonNationality/ legalPersonGender/spouseGender 等)均为无枚举约束的纯字符串:前端为提升可用性复用个人贷款 对应枚举的取值域渲染下拉框,但后端未做强校验,实际入库是否要求严格匹配以实测为准。
32. 商户管理无 /api/merchant/detail 接口:"查看/编辑"操作无法单独按 id 拉取最新详情,前端改为 由列表页把当前行(MerchantVo 全部字段)通过路由 query 带入表单页直接回填,若用户直接刷新表单页 地址或列表数据在打开表单期间发生变化,回显内容可能不是最新值,建议后端补充详情接口。
33. 商户管理无审批(approve/audit/review)相关接口:已对 swagger 全量检索确认不存在该类路径, 原型图"审批"按钮及"审批中/通过"状态在后端无对应实现,前端改用 MerchantStatusEnum (ACTIVE启用/INACTIVE停用)提供"启用/停用"操作代替,业务语义不完全等价,需与业务方确认是否 需要后端补充完整的审批工作流。
34. CreateMerchantBto/UpdateMerchantBto/MerchantVo 均不含 docx/原型提及的 goodsCategory(商品类目)/paymentCycle(回款周期)/singleOrderLimit(单笔汇总订单限额)/ financingRatio(与 creditRatio 是否为同一字段存疑)/estimatedReturnRate(预计退货率)等 与贷款申请融资条件同源的字段:前端表单只实现了接口实际支持的字段集合,原型列表列 "商户主体/主体钱包/回款商户/商品类型/回款周期"在 MerchantVo 中也无直接对应字段,已在列表中 省略或用现有字段(a1AccountNo 等)近似展示,建议后端评估是否需要扩展商户模型字段。
35. 商户分页查询(merchant/page)仅支持 merchantName 一项过滤:原型图要求的"所属机构/商户编号/ 商户类型/商品类型"四项查询条件后端不支持,已同步精简查询表单,若需要,建议后端补充对应查询参数。
36. 商户 a1AccountNo/a2AccountNo/guarantorAccountNo 均为纯字符串,不与客户/钱包账户建立外键 关联:前端提供"选择钱包账户"辅助按钮(基于 /api/wallet-account/page 按户名模糊查询后手动选取 账号回填),但不保证选中账户与商户主体的真实归属关系,建议后端补充按客户/商户维度关联钱包账户的 校验或专用查询接口。
37. 发票登记/批量登记(CreateInvoiceRegistrationBto)无字段校验发票代码+发票号码组合唯一性: docx 要求"发票唯一性:发票代码+发票号码组合不可重复登记,重复提示'该发票已登记,请勿重复上传'", 前端未做提交前的唯一性预检(无对应查询接口支持"按代码+号码查重"),重复提交后的报错依赖后端 返回的 message 直接展示,若后端未实现该校验将导致重复数据入库,需后端确认已实现该规则。
38. 发票登记全部字段需手动录入,无 OCR 自动识别接口:docx 提到发票号码/代码/金额/日期/购买方/ 销售方名称"自动识别返回,可手动修改",后端未提供对应识别接口,已按纯手动录入实现。
39. 发票 match/settle/delete 均为"透传中台,无本地数据库操作":调用后本地 InvoiceVo 的 matchStatus/settleStatus/invoiceStatus 等字段更新依赖后端透传中台后自行同步本地记录(未在 swagger 中说明同步时序/是否为同步阻塞调用),前端调用成功后直接 reload() 列表,若后端存在异步 同步延迟,可能出现列表短暂未刷新到最新状态的情况。
40. InvoiceMatchVo(匹配记录)无单条记录级别的"是否已进入清算流程"标记:docx 规则"已进入清算 流程的回款记录禁止取消匹配"无法精确到每条匹配记录,前端简化为按发票整体 settleStatus 是否为 UNSETTLED 判断是否允许"取消匹配",可能与真实业务规则(可能存在部分匹配记录已清算、部分未清算 的混合场景)不完全一致,建议后端在 InvoiceMatchVo 中补充清算状态字段。
41. 发票列表原型底部"当前可用发票金额"统计无对应后端聚合接口/字段:前端未实现该汇总展示, 建议后端评估是否需要补充按商户/渠道维度汇总"发票金额-已匹配/已结算金额"的统计接口。
42. offline-recharge-unmatched-detail(线下来账明细,透传中台30908)与本地 invoice-management/repayment/list 功能存在重叠但数据源不同(前者查中台侧未匹配来账,后者查本地 回款流水表):二者关系未在 swagger 中说明(是否本地回款流水由中台来账同步生成、同步时序如何), 本次匹配交互统一采用本地 repayment/list,offline-recharge-unmatched-detail 对应的"自动匹配/ 中台侧查验"高级交互未实现对应 UI 入口。
43. /api/invoice/page(透传中台31909查询)与 /api/invoice-management/invoice/list(本地查询)为 功能重叠的两组平行接口:前者需 channelNo 且字段命名与本地 InvoiceVo 不同,本项目统一采用 后者用于列表展示,前者未使用,建议后端确认二者分工或说明是否为废弃接口。
44. payment/query-credit-quota 响应 data 字段完全未定义结构:swagger 中该字段无 $ref、无 properties,前端在支付表单中改为原样展示返回的 JSON 供操作人员肉眼判断,无法做强类型的"剩余 额度"校验与展示,若融资金额超出实际额度,只能依赖后端 order-pay 接口调用失败后的错误提示兜底, 建议后端补充该接口的响应字段定义。
45. order-pay 的 CreatePaymentBto 无短信验证码字段:docx 描述的"发起支付前需短信验证"流程在 后端契约层面无法真正落地,前端仍按 docx 实现了"发送验证码(复用 send-sms-code)+ 输入验证码"的 交互与本地格式校验(非空+6位数字),但验证码本身不会被传给 order-pay 也不会被后端比对校验, 该环节目前形同虚设,需后端评估是否要在 CreatePaymentBto 中补充 smsCode 字段并在服务端真正 校验。
46. payment-management/query-payment-record(及其 PaymentRecordListVo/PaymentRecordDetailVo) 均无机构/商户/订单编号/付款人姓名等字段:原型图查询区与列表列包含"机构/商户/订单编号/付款人/ 付款账号/服务费"等信息,后端当前的支付记录模型仅关联到 walletAccountId,不关联商户或订单, 前端已按接口实际返回字段精简查询表单与列表列,未臆造上述字段,建议后端评估是否需要在支付记录 落库时补充商户/订单关联字段。
47. CreatePaymentBto 只有一个 walletAccountId 字段,无法同时指定"余额账户"与"融资账户"两个不同 账户 ID:结合 wallet-account/detail 以一个账户 id 返回其所属客户整套 mainBalance/a2Balance/ a6Balance/a7Balance 余额的既有设计模式,前端推断该字段应始终填客户主账户(A1)的 id,融资额度 查询(query-credit-quota)则用该账户的 accountNo 反查,组合支付时的"融资部分"通过 loanApplyId 关联的贷款申请单据来承载客户与金额信息,不再单独指定 A3 账户 ID。此为前端基于现有 接口设计模式的推断性假设,未在 swagger 中被明确证实,建议后端确认该理解是否准确。
48. loanApplyId 取自 credit-apply/loan-application/list 返回记录的数字主键 id,且该模块使用的 ApplicationStatusEnum(DRAFT/CONFIRMED/SUBMITTED/APPLY_FAILED)无"已批准/生效/放款"等更精确的 终态,前端支付表单在选择"关联贷款申请"时只能按 SUBMITTED(已申请)状态筛选可选记录,无法准确 判断该笔贷款是否已实际放款、是否仍有可用余额支持本次融资支付,建议后端补充更精确的贷款状态枚举 或提供专门的"可用于支付的贷款额度"查询接口。
49. summary-order/page/original-order/page 查询入参严重少于 docx/原型描述:summary-order/page 仅支持 orderNo,original-order/page 仅支持 originalOrderNo,原型图要求的渠道/日期范围/订单 状态/结算状态/店铺 ID 等查询条件均无对应参数,前端已按接口实际支持字段精简查询表单,建议后端 评估是否需要补充查询参数。
50. original-order/export 响应 data 字段未定义结构:与 download-statement/download-receipt 等已文档化 fileData 字段的导出接口不同,该接口响应结构在 swagger 中完全空白,前端沿用既有 "假设为 {fileData: base64}"的处理模式实现下载,若实际结构不同将导致导出功能报错或下载内容 异常,建议后端补充响应字段定义。
51. summary-order/detail 不返回关联原始订单明细,且 original-order/page 不支持按 summaryOrderId 过滤查询:两个缺口叠加导致"查看汇总订单关联的原始订单明细列表"功能在当前 接口能力下无法实现,前端在汇总订单详情弹窗中用 a-alert 明确提示该缺口,未展示虚假数据,建议 后端为 original-order/page 补充 summaryOrderId 过滤参数,或在 summary-order/detail 响应中 直接内嵌关联的原始订单列表。