Skip to content

feat: add routeId to transaction for FK-backed route identification #1930

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ClaraTersi merged 6 commits into from
Mar 20, 2026
Merged

feat: add routeId to transaction for FK-backed route identification #1930

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
39ce659
feat: add routeId field to transaction for referential integrity with…
ClaraTersi Mar 19, 2026
6b8340e
fix: resolve route cache from routeId in Redis consumer and index rou…
ClaraTersi Mar 19, 2026
fd996b1
fix: use NOT VALID + VALIDATE CONSTRAINT for route_id FK to avoid tab…
ClaraTersi Mar 19, 2026
69e7bf9
docs: add route id to transaction :books:
ClaraTersi Mar 19, 2026
ff3cd55
docs: fix route description and add routeId to create request schemas…
ClaraTersi Mar 20, 2026
a91a127
refactor: split index creation into separate migration for CONCURRENT…
ClaraTersi Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion components/ledger/api/docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9929,6 +9929,12 @@ const docTemplate = `
"maxLength": 100,
"example": "ROUTE-001"
},
"routeDescription": {
"description": "Human-readable description of the operation route for accounting traceability\nexample: Settlement route for service charges\nmaxLength: 250",
"type": "string",
"maxLength": 250,
"example": "Settlement route for service charges"
},
"routeId": {
"description": "UUID of the operation route that generated this operation. Primary field for route identification, validation, and accounting.\nexample: 00000000-0000-0000-0000-000000000000\nformat: uuid",
"type": "string",
Expand Down Expand Up @@ -10148,11 +10154,17 @@ const docTemplate = `
"example": "00000000-0000-0000-0000-000000000000"
},
"route": {
"description": "Deprecated: legacy route identifier, use routeId on individual operations instead. Contains the operation route UUID as a free-form string for backwards compatibility.\nexample: 00000000-0000-0000-0000-000000000000\nmaxLength: 250\ndeprecated: true",
"description": "Deprecated: legacy route identifier, use routeId instead. Contains the transaction route UUID as a free-form string for backwards compatibility.\nexample: 00000000-0000-0000-0000-000000000000\nmaxLength: 250\ndeprecated: true",
"type": "string",
"maxLength": 250,
"example": "00000000-0000-0000-0000-000000000000"
},
"routeId": {
"description": "UUID of the transaction route. Primary field for route identification, validation, and accounting.\nexample: 00000000-0000-0000-0000-000000000000\nformat: uuid",
"type": "string",
"format": "uuid",
"example": "00000000-0000-0000-0000-000000000000"
},
"source": {
"description": "List of source account aliases or identifiers\nexample: [\"@person1\"]",
"type": "array",
Expand Down
14 changes: 13 additions & 1 deletion components/ledger/api/swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9905,6 +9905,12 @@
"maxLength": 100,
"example": "ROUTE-001"
},
"routeDescription": {
"description": "Human-readable description of the operation route for accounting traceability\nexample: Settlement route for service charges\nmaxLength: 250",
"type": "string",
"maxLength": 250,
"example": "Settlement route for service charges"
},
"routeId": {
"description": "UUID of the operation route that generated this operation. Primary field for route identification, validation, and accounting.\nexample: 00000000-0000-0000-0000-000000000000\nformat: uuid",
"type": "string",
Expand Down Expand Up @@ -10124,11 +10130,17 @@
"example": "00000000-0000-0000-0000-000000000000"
},
"route": {
"description": "Deprecated: legacy route identifier, use routeId on individual operations instead. Contains the operation route UUID as a free-form string for backwards compatibility.\nexample: 00000000-0000-0000-0000-000000000000\nmaxLength: 250\ndeprecated: true",
"description": "Deprecated: legacy route identifier, use routeId instead. Contains the transaction route UUID as a free-form string for backwards compatibility.\nexample: 00000000-0000-0000-0000-000000000000\nmaxLength: 250\ndeprecated: true",
"type": "string",
"maxLength": 250,
"example": "00000000-0000-0000-0000-000000000000"
},
"routeId": {
"description": "UUID of the transaction route. Primary field for route identification, validation, and accounting.\nexample: 00000000-0000-0000-0000-000000000000\nformat: uuid",
"type": "string",
"format": "uuid",
"example": "00000000-0000-0000-0000-000000000000"
},
"source": {
"description": "List of source account aliases or identifiers\nexample: [\"@person1\"]",
"type": "array",
Expand Down
25 changes: 22 additions & 3 deletions components/ledger/api/swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7694,6 +7694,16 @@ definitions:
type: string
maxLength: 100
example: ROUTE-001
routeDescription:
description: 'Human-readable description of the operation route for accounting
traceability

example: Settlement route for service charges

maxLength: 250'
type: string
maxLength: 250
example: Settlement route for service charges
routeId:
description: 'UUID of the operation route that generated this operation. Primary
field for route identification, validation, and accounting.
Expand Down Expand Up @@ -7933,9 +7943,8 @@ definitions:
format: uuid
example: 00000000-0000-0000-0000-000000000000
route:
description: 'Deprecated: legacy route identifier, use routeId on individual
operations instead. Contains the operation route UUID as a free-form string
for backwards compatibility.
description: 'Deprecated: legacy route identifier, use routeId instead. Contains
the transaction route UUID as a free-form string for backwards compatibility.

example: 00000000-0000-0000-0000-000000000000

Expand All @@ -7945,6 +7954,16 @@ definitions:
type: string
maxLength: 250
example: 00000000-0000-0000-0000-000000000000
routeId:
description: 'UUID of the transaction route. Primary field for route identification,
validation, and accounting.

example: 00000000-0000-0000-0000-000000000000

format: uuid'
type: string
format: uuid
example: 00000000-0000-0000-0000-000000000000
source:
description: 'List of source account aliases or identifiers

Expand Down
30 changes: 29 additions & 1 deletion components/transaction/api/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3744,6 +3744,7 @@ components:
accountId: 00000000-0000-0000-0000-000000000000
deletedAt: 2021-01-01T00:00:00Z
route: 00000000-0000-0000-0000-000000000000
routeDescription: Settlement route for service charges
balanceKey: asset-freeze
balanceId: 00000000-0000-0000-0000-000000000000
status: '{}'
Expand Down Expand Up @@ -3903,6 +3904,14 @@ components:
example: ROUTE-001
maxLength: 100
type: string
routeDescription:
description: |-
Human-readable description of the operation route for accounting traceability
example: Settlement route for service charges
maxLength: 250
example: Settlement route for service charges
maxLength: 250
type: string
routeId:
description: |-
UUID of the operation route that generated this operation. Primary field for route identification, validation, and accounting.
Expand Down Expand Up @@ -4104,6 +4113,7 @@ components:
accountId: 00000000-0000-0000-0000-000000000000
deletedAt: 2021-01-01T00:00:00Z
route: 00000000-0000-0000-0000-000000000000
routeDescription: Settlement route for service charges
balanceKey: asset-freeze
balanceId: 00000000-0000-0000-0000-000000000000
status: '{}'
Expand All @@ -4130,10 +4140,12 @@ components:
accountId: 00000000-0000-0000-0000-000000000000
deletedAt: 2021-01-01T00:00:00Z
route: 00000000-0000-0000-0000-000000000000
routeDescription: Settlement route for service charges
balanceKey: asset-freeze
balanceId: 00000000-0000-0000-0000-000000000000
status: '{}'
route: 00000000-0000-0000-0000-000000000000
routeId: 00000000-0000-0000-0000-000000000000
id: 00000000-0000-0000-0000-000000000000
status: '{}'
updatedAt: 2021-01-01T00:00:00Z
Expand Down Expand Up @@ -4243,13 +4255,21 @@ components:
type: string
route:
description: |-
Deprecated: legacy route identifier, use routeId on individual operations instead. Contains the operation route UUID as a free-form string for backwards compatibility.
Deprecated: legacy route identifier, use routeId instead. Contains the transaction route UUID as a free-form string for backwards compatibility.
example: 00000000-0000-0000-0000-000000000000
maxLength: 250
deprecated: true
example: 00000000-0000-0000-0000-000000000000
maxLength: 250
type: string
routeId:
description: |-
UUID of the transaction route. Primary field for route identification, validation, and accounting.
example: 00000000-0000-0000-0000-000000000000
format: uuid
example: 00000000-0000-0000-0000-000000000000
format: uuid
type: string
source:
description: |-
List of source account aliases or identifiers
Expand Down Expand Up @@ -4830,6 +4850,7 @@ components:
accountId: 00000000-0000-0000-0000-000000000000
deletedAt: 2021-01-01T00:00:00Z
route: 00000000-0000-0000-0000-000000000000
routeDescription: Settlement route for service charges
balanceKey: asset-freeze
balanceId: 00000000-0000-0000-0000-000000000000
status: '{}'
Expand All @@ -4856,6 +4877,7 @@ components:
accountId: 00000000-0000-0000-0000-000000000000
deletedAt: 2021-01-01T00:00:00Z
route: 00000000-0000-0000-0000-000000000000
routeDescription: Settlement route for service charges
balanceKey: asset-freeze
balanceId: 00000000-0000-0000-0000-000000000000
status: '{}'
Expand Down Expand Up @@ -5112,6 +5134,7 @@ components:
accountId: 00000000-0000-0000-0000-000000000000
deletedAt: 2021-01-01T00:00:00Z
route: 00000000-0000-0000-0000-000000000000
routeDescription: Settlement route for service charges
balanceKey: asset-freeze
balanceId: 00000000-0000-0000-0000-000000000000
status: '{}'
Expand All @@ -5138,10 +5161,12 @@ components:
accountId: 00000000-0000-0000-0000-000000000000
deletedAt: 2021-01-01T00:00:00Z
route: 00000000-0000-0000-0000-000000000000
routeDescription: Settlement route for service charges
balanceKey: asset-freeze
balanceId: 00000000-0000-0000-0000-000000000000
status: '{}'
route: 00000000-0000-0000-0000-000000000000
routeId: 00000000-0000-0000-0000-000000000000
id: 00000000-0000-0000-0000-000000000000
status: '{}'
updatedAt: 2021-01-01T00:00:00Z
Expand Down Expand Up @@ -5184,6 +5209,7 @@ components:
accountId: 00000000-0000-0000-0000-000000000000
deletedAt: 2021-01-01T00:00:00Z
route: 00000000-0000-0000-0000-000000000000
routeDescription: Settlement route for service charges
balanceKey: asset-freeze
balanceId: 00000000-0000-0000-0000-000000000000
status: '{}'
Expand All @@ -5210,10 +5236,12 @@ components:
accountId: 00000000-0000-0000-0000-000000000000
deletedAt: 2021-01-01T00:00:00Z
route: 00000000-0000-0000-0000-000000000000
routeDescription: Settlement route for service charges
balanceKey: asset-freeze
balanceId: 00000000-0000-0000-0000-000000000000
status: '{}'
route: 00000000-0000-0000-0000-000000000000
routeId: 00000000-0000-0000-0000-000000000000
id: 00000000-0000-0000-0000-000000000000
status: '{}'
updatedAt: 2021-01-01T00:00:00Z
Expand Down
14 changes: 13 additions & 1 deletion components/transaction/api/transaction_docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4493,6 +4493,12 @@ const docTemplatetransaction = `{
"maxLength": 100,
"example": "ROUTE-001"
},
"routeDescription": {
"description": "Human-readable description of the operation route for accounting traceability\nexample: Settlement route for service charges\nmaxLength: 250",
"type": "string",
"maxLength": 250,
"example": "Settlement route for service charges"
},
"routeId": {
"description": "UUID of the operation route that generated this operation. Primary field for route identification, validation, and accounting.\nexample: 00000000-0000-0000-0000-000000000000\nformat: uuid",
"type": "string",
Expand Down Expand Up @@ -4730,11 +4736,17 @@ const docTemplatetransaction = `{
"example": "00000000-0000-0000-0000-000000000000"
},
"route": {
"description": "Deprecated: legacy route identifier, use routeId on individual operations instead. Contains the operation route UUID as a free-form string for backwards compatibility.\nexample: 00000000-0000-0000-0000-000000000000\nmaxLength: 250\ndeprecated: true",
"description": "Deprecated: legacy route identifier, use routeId instead. Contains the transaction route UUID as a free-form string for backwards compatibility.\nexample: 00000000-0000-0000-0000-000000000000\nmaxLength: 250\ndeprecated: true",
"type": "string",
"maxLength": 250,
"example": "00000000-0000-0000-0000-000000000000"
},
"routeId": {
"description": "UUID of the transaction route. Primary field for route identification, validation, and accounting.\nexample: 00000000-0000-0000-0000-000000000000\nformat: uuid",
"type": "string",
"format": "uuid",
"example": "00000000-0000-0000-0000-000000000000"
},
"source": {
"description": "List of source account aliases or identifiers\nexample: [\"@person1\"]",
"type": "array",
Expand Down
14 changes: 13 additions & 1 deletion components/transaction/api/transaction_swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4487,6 +4487,12 @@
"maxLength": 100,
"example": "ROUTE-001"
},
"routeDescription": {
"description": "Human-readable description of the operation route for accounting traceability\nexample: Settlement route for service charges\nmaxLength: 250",
"type": "string",
"maxLength": 250,
"example": "Settlement route for service charges"
},
"routeId": {
"description": "UUID of the operation route that generated this operation. Primary field for route identification, validation, and accounting.\nexample: 00000000-0000-0000-0000-000000000000\nformat: uuid",
"type": "string",
Expand Down Expand Up @@ -4724,11 +4730,17 @@
"example": "00000000-0000-0000-0000-000000000000"
},
"route": {
"description": "Deprecated: legacy route identifier, use routeId on individual operations instead. Contains the operation route UUID as a free-form string for backwards compatibility.\nexample: 00000000-0000-0000-0000-000000000000\nmaxLength: 250\ndeprecated: true",
"description": "Deprecated: legacy route identifier, use routeId instead. Contains the transaction route UUID as a free-form string for backwards compatibility.\nexample: 00000000-0000-0000-0000-000000000000\nmaxLength: 250\ndeprecated: true",
"type": "string",
"maxLength": 250,
"example": "00000000-0000-0000-0000-000000000000"
},
"routeId": {
"description": "UUID of the transaction route. Primary field for route identification, validation, and accounting.\nexample: 00000000-0000-0000-0000-000000000000\nformat: uuid",
"type": "string",
"format": "uuid",
"example": "00000000-0000-0000-0000-000000000000"
},
"source": {
"description": "List of source account aliases or identifiers\nexample: [\"@person1\"]",
"type": "array",
Expand Down
18 changes: 17 additions & 1 deletion components/transaction/api/transaction_swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -943,6 +943,14 @@ definitions:
example: ROUTE-001
maxLength: 100
type: string
routeDescription:
description: |-
Human-readable description of the operation route for accounting traceability
example: Settlement route for service charges
maxLength: 250
example: Settlement route for service charges
maxLength: 250
type: string
routeId:
description: |-
UUID of the operation route that generated this operation. Primary field for route identification, validation, and accounting.
Expand Down Expand Up @@ -1188,13 +1196,21 @@ definitions:
type: string
route:
description: |-
Deprecated: legacy route identifier, use routeId on individual operations instead. Contains the operation route UUID as a free-form string for backwards compatibility.
Deprecated: legacy route identifier, use routeId instead. Contains the transaction route UUID as a free-form string for backwards compatibility.
example: 00000000-0000-0000-0000-000000000000
maxLength: 250
deprecated: true
example: 00000000-0000-0000-0000-000000000000
maxLength: 250
type: string
routeId:
description: |-
UUID of the transaction route. Primary field for route identification, validation, and accounting.
example: 00000000-0000-0000-0000-000000000000
format: uuid
example: 00000000-0000-0000-0000-000000000000
format: uuid
type: string
source:
description: |-
List of source account aliases or identifiers
Expand Down
1 change: 1 addition & 0 deletions components/transaction/internal/adapters/http/in/transaction-creation-helpers.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@
return transactionDate, nil
}

func (handler *TransactionHandler) BuildOperations(

Check failure on line 148 in components/transaction/internal/adapters/http/in/transaction-creation-helpers.go

View workflow job for this annotation

GitHub Actions / Go Analysis / Lint (midaz-transaction) 

cognitive complexity 35 of func `(*TransactionHandler).BuildOperations` is high (> 30) (gocognit)
ctx context.Context,
balances []*mmodel.Balance,
fromTo []pkgTransaction.FromTo,
Expand Down Expand Up @@ -423,7 +423,7 @@
LedgerID: blc.LedgerID,
CreatedAt: transactionDate,
UpdatedAt: time.Now(),
Route: ft.Route,

Check failure on line 426 in components/transaction/internal/adapters/http/in/transaction-creation-helpers.go

View workflow job for this annotation

GitHub Actions / Go Analysis / Lint (midaz-transaction) 

SA1019: ft.Route is deprecated: passive field kept for backward compatibility. Accepted from client and persisted, but not used in any validation or business logic. Use routeId instead. (staticcheck)
RouteID: ft.RouteID,
Metadata: ft.Metadata,
BalanceAffected: !isAnnotation,
Expand Down Expand Up @@ -475,7 +475,7 @@
LedgerID: blc.LedgerID,
CreatedAt: transactionDate,
UpdatedAt: time.Now(),
Route: ft.Route,

Check failure on line 478 in components/transaction/internal/adapters/http/in/transaction-creation-helpers.go

View workflow job for this annotation

GitHub Actions / Go Analysis / Lint (midaz-transaction) 

SA1019: ft.Route is deprecated: passive field kept for backward compatibility. Accepted from client and persisted, but not used in any validation or business logic. Use routeId instead. (staticcheck)
RouteID: ft.RouteID,
Metadata: ft.Metadata,
BalanceAffected: !isAnnotation,
Expand Down Expand Up @@ -558,7 +558,7 @@
LedgerID: blc.LedgerID,
CreatedAt: transactionDate,
UpdatedAt: time.Now(),
Route: ft.Route,

Check failure on line 561 in components/transaction/internal/adapters/http/in/transaction-creation-helpers.go

View workflow job for this annotation

GitHub Actions / Go Analysis / Lint (midaz-transaction) 

SA1019: ft.Route is deprecated: passive field kept for backward compatibility. Accepted from client and persisted, but not used in any validation or business logic. Use routeId instead. (staticcheck)
RouteID: ft.RouteID,
Metadata: ft.Metadata,
BalanceAffected: !isAnnotation,
Expand Down Expand Up @@ -610,7 +610,7 @@
LedgerID: blc.LedgerID,
CreatedAt: transactionDate,
UpdatedAt: time.Now(),
Route: ft.Route,

Check failure on line 613 in components/transaction/internal/adapters/http/in/transaction-creation-helpers.go

View workflow job for this annotation

GitHub Actions / Go Analysis / Lint (midaz-transaction) 

SA1019: ft.Route is deprecated: passive field kept for backward compatibility. Accepted from client and persisted, but not used in any validation or business logic. Use routeId instead. (staticcheck)
RouteID: ft.RouteID,
Metadata: ft.Metadata,
BalanceAffected: !isAnnotation,
Expand Down Expand Up @@ -733,7 +733,7 @@
LedgerID: blc.LedgerID,
CreatedAt: transactionDate,
UpdatedAt: time.Now(),
Route: ft.Route,

Check failure on line 736 in components/transaction/internal/adapters/http/in/transaction-creation-helpers.go

View workflow job for this annotation

GitHub Actions / Go Analysis / Lint (midaz-transaction) 

SA1019: ft.Route is deprecated: passive field kept for backward compatibility. Accepted from client and persisted, but not used in any validation or business logic. Use routeId instead. (staticcheck)
RouteID: ft.RouteID,
Metadata: ft.Metadata,
BalanceAffected: !isAnnotation,
Expand Down Expand Up @@ -866,7 +866,8 @@
ChartOfAccountsGroupName: transactionInput.ChartOfAccountsGroupName,
CreatedAt: transactionDate,
UpdatedAt: time.Now(),
Route: transactionInput.Route,

Check failure on line 869 in components/transaction/internal/adapters/http/in/transaction-creation-helpers.go

View workflow job for this annotation

GitHub Actions / Go Analysis / Lint (midaz-transaction) 

SA1019: transactionInput.Route is deprecated: legacy route identifier, contains the transaction route UUID as a string. Use routeId instead. (staticcheck)
RouteID: transactionInput.RouteID,
Metadata: transactionInput.Metadata,
Status: transaction.Status{
Code: transactionStatus,
Expand Down
Loading
Loading