实体同步：Onboarding 子实体 + Entity CRUD

概述

Onboarding 完成时，将组织架构中尚未链接 DTMS 的子实体按层级同步到 DTMS。运行时通过 Entities API 创建/更新实体时，同步调用 DTMS POST|PATCH /entites。

触发入口

动作	HTTP
完成 Onboarding	POST /api/auth/onboarding
创建实体	POST /api/entities
更新实体	PATCH /api/entities/:id
批量创建实体	POST /api/entities/bulk（仅 Ledger，不调 DTMS）

参与方

• Client、api-gateway
• CompleteOnboardingUseCase / EntitiesUseCase
• DtmsSyncService、DtmsAuthService、DtmsClient
• Ledger、Redis、DTMS

业务流程图

加载图表…

业务流程图

时序图：Onboarding 子实体同步

加载图表…

时序图：Onboarding 子实体同步

时序图：运行时 Create Entity

加载图表…

时序图：运行时 Create Entity

DTMS API 对照

步骤	Liquia	HTTP	Path	Bearer
鉴权	login via Auth	POST	/auth/users/_login	否
创建	createEntity	POST	/entites	是
更新	updateEntity	PATCH	/entites/{id}	是
补偿删除	deleteEntity	DELETE	/entites/{id}	是

本地数据影响

• Entity.dtmsEntityId
• 名称截断：name≤25、externalName≤60；holding_company/layer0 → isGroup=true

异常与补偿

• DTMS_NOT_LINKED、DTMS_PARENT_MISSING、DTMS_ENTITY_SYNC_FAILED
• Create 遇 DTMS_REQUEST_FAILED 可 forceRefresh 后重试
• Onboarding 银行账户若走 banking microservice：不同步 DTMS（见 banking 流程边界）

源码索引

• apps/api/src/orchestration/onboarding/complete-onboarding.use-case.ts
• apps/api/src/orchestration/entities/entities.use-case.ts
• apps/api/src/integrations/dtms/dtms-sync.service.ts