Liquia ↔ DTMS 集成总览

业务目的

Liquia 作为企业财资前端与编排层，将租户、实体、银行、对账单、发票/合同、流动性与 FX 暴露等能力同步或委托给 DTMS（UNI 财资中台）。Gateway（apps/api）通过 DtmsClient 以 HTTP 调用 DTMS；租户会话 JWT 由 DtmsAuthService 管理并缓存于 Redis。

架构参与方

加载图表…

架构参与方

组件	路径	职责
DtmsClient	apps/api/src/integrations/dtms/dtms.client.ts	HTTP；统一 X-API-Key
DtmsAuthService	dtms-auth.service.ts	登录 + Redis token
DtmsSyncService	dtms-sync.service.ts	Corporate / Entity
DtmsBankingService	dtms-banking.service.ts	银行机构、账户、对账单
Ledger	ledger-service via TCP	org/entity DTMS 链接字段

鉴权时序

所有 DTMS 请求带 X-API-Key。POST /corporates 与 POST /auth/users/_login 不需要 Bearer；其余业务 API 需要 Authorization: Bearer {loginJwt}。

加载图表…

鉴权时序

• Cache key：dtms:token:{organizationId}
• TTL：JWT exp - now - 60（下限 60s；解析失败默认 3600s）
• Signup 开通成功后可直接 cacheToken（凭据尚未经 Ledger 读取路径）

环境变量

变量	用途
DTMS_BASE_URL	DTMS API（非 OAuth UI）
DTMS_API_KEY	X-API-Key
DTMS_CREDENTIALS_KEY	加密 org 根密码（及银行账号加密回退）
DTMS_ENABLED	dev/test 控制是否 skip sync；production 下 Sync 忽略 false；FX 强制 true
DTMS_DEBUG	production 下打请求日志
DTMS_DM2_CURRENCIES	FX 推荐币种列表
REDIS_URL	token 缓存

shouldSkipSync（Sync / Banking / Documents 等）

1. 未配置 BASE_URL+API_KEY：仅在 development && DTMS_ENABLED!==true 时 skip，否则后续断言失败
2. development/test：DTMS_ENABLED!=='true' → skip
3. production：已配置则永不 skip

本地 DTMS 链接字段（摘要）

模型	关键字段
Organization	dtmsCorporateId, dtmsRootEntityId, dtmsRootEmail, dtmsRootPasswordEnc, …
Entity	dtmsEntityId
Bank	dtmsCounterpartyId（DTMS classification=BANK）
Counterparty	dtmsCounterpartyId
BankAccount	dtmsBankAccountId
Document	dtmsFileId, dtmsStatementJobId（statement 或 DPJ id 复用）
BankStatementLine	dtmsBankFlowId, dtmsCashFlowId
ApArItem	dtmsInvoiceId, dtmsContractId
CashFlow	dtmsCashFlowId

错误码（摘要）

Code	含义
DTMS_NOT_CONFIGURED / DTMS_API_KEY_MISSING	配置缺失
DTMS_AUTH_GATEWAY / DTMS_LOGIN_FAILED	鉴权/网关
DTMS_VALIDATION_FAILED	400/422
DTMS_UNAVAILABLE / DTMS_REQUEST_FAILED	上游不可用或请求失败
DTMS_PROVISION_FAILED / DTMS_ENTITY_SYNC_FAILED	开通/实体同步
DTMS_NOT_LINKED / DTMS_PARENT_MISSING / DTMS_CREDENTIALS_*	链接或凭据

详见 apps/api/src/integrations/dtms/dtms-errors.ts。

重要边界

集成边界

以下约定影响时序图与 API 对照，写文档时勿混淆。

1. Production DTMS_ENABLED：Sync / Banking / Documents 在 production 忽略 DTMS_ENABLED=false（已配置 BASE_URL+API_KEY 则必 sync）；FX 暴露 强制 DTMS_ENABLED=true；Liquidity 不检查 skip 开关。
2. Onboarding 中经 banking microservice 创建的银行账户 不走 DtmsBankingService（无 DTMS 链接）。
3. DTMS 侧「银行」= Counterparty(classification=BANK)，账户的 bankId 传的是该 counterparty id。
4. Document.dtmsStatementJobId 字段复用 statement job 与 document-processing job。
5. 未挂接 Client 方法：searchBankAccounts、searchCashFlows、searchCashFlowInstruments；cash-flow bulk 入队路径未接线，见 flows/08 与 API 目录。

源码入口

• 模块：apps/api/src/integrations/dtms/dtms.module.ts
• Redis 说明：docs/cloud-redis.md