银行对账单：Upload → Poll → Apply

概述

用户上传银行对账单后，Liquia 将文件上传到 DTMS、触发 statements/convert，由后台 Poller 轮询 job；用户确认后 statements/apply，并同步 bank-flow id（必要时 bulk 补建）。

触发入口

动作	HTTP
上传转换	POST /api/bank/statements/upload
Job 状态	GET /api/bank/statements/jobs/:jobId
忽略冲突	POST /api/bank/statements/jobs/ignore-conflicts
应用入账	POST /api/bank/statements/jobs/:jobId/apply

后台：DocumentParsePollerService（约 5s interval，Redis lock poll:document-parse）。

参与方

• Client、api-gateway、StatementBankingUseCase
• DtmsBankingService、DocumentParsePollerService
• DtmsAuthService、DtmsClient、Redis、DTMS、本地 DB

业务流程图

加载图表…

业务流程图

时序图（主路径）

加载图表…

时序图（主路径）

时序图：Ignore conflicts（摘要）

加载图表…

时序图：Ignore conflicts（摘要）

DTMS API 对照

步骤	Liquia	HTTP	Path	Bearer
上传	uploadFiles	POST	/files?type=STATEMENT	是
转换	convertStatement	POST	/statements/convert	是
查 job	getStatementJob	GET	/statements/jobs/{jobId}	是
列表 job	listStatementJobs	GET	/statements/jobs?...	是
忽略	ignoreStatementJob	POST	/statements/jobs/{jobId}/ignore	是
应用	applyStatement	POST	/statements/apply	是
搜 flows	searchBankFlows	POST	/bank-flows-v2/search?...	是
批量 flows	bulkCreateBankFlows	POST	/bank-flows-v2/bulk	是

本地数据影响

• Document：dtmsFileId、dtmsStatementJobId、parse/apply 状态
• ParsedBankStatement、BankStatementLine.dtmsBankFlowId
• BankTransaction、BankAccount.balance；可挂 FlowRun

异常与补偿

• skip sync：假 jobId local-*
• job 未 DONE → apply 400；already applied → 可继续本地
• conflict → details.conflictJobId；job not found → 清理本地冲突
• Poll 超时约 30min

源码索引

• apps/api/src/integrations/dtms/dtms-banking.service.ts
• apps/api/src/orchestration/documents/document-parse-poller.service.ts
• Bank controller / statement-banking use-case