Finance Schema
The finance schema contains 3 models that manage financial operations including wallet management, categorized income/expense tracking, and inter-wallet transfers.
Source: packages/core/src/models/schemas/finance/
Models Overview
| Model | Table Name | Description |
|---|---|---|
| FinanceWallet | finance.FinanceWallet | Financial accounts (cash, bank, e-wallet, credit card) |
| FinanceCategory | finance.FinanceCategory | Income and expense categorization |
| FinanceTransaction | finance.FinanceTransaction | Individual financial transactions |
FinanceWallet
Financial accounts for tracking money flow per merchant.
Wallet Types
| Type | Value | Description |
|---|---|---|
| CASH | 100_CASH | Physical cash |
| BANK | 200_BANK | Bank account |
| EWALLET | 300_EWALLET | Electronic wallet (Momo, ZaloPay, etc.) |
| CREDIT_CARD | 400_CREDIT_CARD | Credit card |
Columns
| Column | Type | Constraints | Description |
|---|---|---|---|
status | text | NOT NULL, DEFAULT ACTIVATED | Wallet status (ACTIVATED, ARCHIVED) |
name | jsonb (i18n) | NOT NULL | Internationalized name |
type | text | NOT NULL | Wallet type (CASH, BANK, EWALLET, CREDIT_CARD) |
account_number | text | Bank account or card number | |
bank_name | text | Bank/institution name | |
currency | text | NOT NULL, DEFAULT 'VND' | Currency code |
initial_balance | decimal(15,4) | NOT NULL, DEFAULT '0' | Starting balance |
current_balance | decimal(15,4) | NOT NULL, DEFAULT '0' | Current balance |
is_default | boolean | NOT NULL, DEFAULT false | Default wallet for the merchant |
is_excluded | boolean | NOT NULL, DEFAULT false | Excluded from reports |
merchant_id | text | NOT NULL | FK to Merchant |
created_by | text | Creator user ID | |
modified_by | text | Last modifier user ID | |
| + common columns | id, createdAt, modifiedAt, deletedAt, metadata |
FinanceCategory
Income and expense categorization with hierarchical support and predefined categories.
Category Types
| Type | Value | Description |
|---|---|---|
| INCOME | 100_INCOME | Income category |
| EXPENSE | 200_EXPENSE | Expense category |
Columns
| Column | Type | Constraints | Description |
|---|---|---|---|
status | text | NOT NULL, DEFAULT ACTIVATED | Category status (ACTIVATED, ARCHIVED) |
name | jsonb (i18n) | NOT NULL | Internationalized name |
description | jsonb (i18n) | Internationalized description | |
type | text | NOT NULL | Category type (INCOME or EXPENSE) |
identifier | text | NOT NULL, UNIQUE | Auto-generated unique identifier |
merchant_id | text | FK to Merchant (null for global categories) | |
parent_id | text | FK to parent FinanceCategory | |
| + common columns |
Fixed Finance Categories
Income categories:
| Code | Value | Description |
|---|---|---|
| SALE | 000_SALE | Revenue from sales |
| OTHER_INCOME | 001_OTHER_INCOME | Other income sources |
| REFUND_INCOME | 002_REFUND_INCOME | Refund received |
Expense categories:
| Code | Value | Description |
|---|---|---|
| PURCHASE | 100_PURCHASE | Inventory purchases |
| OTHER_EXPENSE | 101_OTHER_EXPENSE | Miscellaneous expenses |
| REFUND_EXPENSE | 102_REFUND_EXPENSE | Refunds issued |
Operating expense categories:
| Code | Value | Description |
|---|---|---|
| OPERATING | 200_OPERATING | General operating expenses |
| SALARY | 201_SALARY | Staff salaries |
| RENT_UTILITIES | 202_RENT_UTILITIES | Rent and utilities |
| MARKETING | 203_MARKETING | Marketing and advertising |
| SHIPPING | 204_SHIPPING | Shipping and logistics |
| MAINTENANCE | 205_MAINTENANCE | Equipment/facility maintenance |
Interest categories:
| Code | Value | Description |
|---|---|---|
| COLLECT_INTEREST | 300_COLLECT_INTEREST | Interest income |
| PAY_INTEREST | 301_PAY_INTEREST | Interest expense |
FinanceTransaction
Individual financial transactions with wallet-to-wallet transfer support.
Transaction Types
| Type | Value | Description |
|---|---|---|
| INCOME | 100_INCOME | Money coming in |
| EXPENSE | 200_EXPENSE | Money going out |
| TRANSFER | 300_TRANSFER | Money moving between wallets |
Transaction Statuses
| Status | Value | Terminal | Description |
|---|---|---|---|
| PENDING | 200_PENDING | No | Awaiting completion |
| COMPLETED | 303_COMPLETED | Yes | Successfully completed |
| CANCELLED | 505_CANCELLED | Yes | Cancelled |
Columns
| Column | Type | Constraints | Description |
|---|---|---|---|
status | text | NOT NULL, DEFAULT COMPLETED | Transaction status |
type | text | NOT NULL | Transaction type (INCOME, EXPENSE, TRANSFER) |
amount | decimal(15,4) | NOT NULL | Transaction amount |
currency | text | NOT NULL, DEFAULT 'VND' | Currency code |
exchange_rate | decimal(19,6) | Exchange rate (for multi-currency) | |
transaction_date | isoTimestamp | NOT NULL | Transaction date (ISO 8601 string) |
finance_wallet_id | text | NOT NULL | FK to source FinanceWallet |
to_finance_wallet_id | text | FK to destination FinanceWallet (for TRANSFER type) | |
finance_category_id | text | FK to FinanceCategory | |
reference_type | text | Reference entity type (e.g., SaleOrder, PurchaseOrder) | |
reference_id | text | Reference entity ID | |
merchant_id | text | NOT NULL | FK to Merchant |
metadata | jsonb | TFinanceTransactionMetadata (sale order payment details) | |
created_by | text | Creator user ID | |
modified_by | text | Last modifier user ID | |
| + common columns |
Entity Relationships
Event-Driven Integration
The finance package automatically creates transactions based on events from other services:
| Event | Action | Category | Type |
|---|---|---|---|
| Commerce initialized (merchant onboarding) | Create default Cash wallet | -- | -- |
| Payment success (sale order) | Create INCOME transaction | SALE | INCOME |
| Purchase order received | Create EXPENSE transaction | PURCHASE | EXPENSE |
Related Documentation
- Database Overview -- Schema summary, common columns, shared types
- Entity Relationship Diagram -- Comprehensive ERD for all 55 models
- Public Schema -- 30 models in the public schema
- Pricing Schema -- 7 pricing models
- Allocation Schema -- 4 allocation models
- Sale Schema -- 2 sale order models
- Inventory Schema -- 8 inventory models
- Payment Schema -- 1 webhook config model
- Migrations -- DDL migrations and seed data framework