> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taho.com.vn/llms.txt
> Use this file to discover all available pages before exploring further.

# Database

> PostgreSQL, Prisma client, migrations và repository boundaries hiện tại.

PostgreSQL lưu application state. Prisma cung cấp generated client; `@prisma/adapter-pg` nối Prisma với connection pool của `pg`.

## Kết nối database

```text theme={null}
DATABASE_URL
→ src/core/db/prisma.ts
→ pg Pool
→ Prisma adapter
→ generated Prisma Client
```

Đường tạo Prisma adapter hiện truyền URL kết nối và timeout kết nối cố định 5.000 ms. Consumer cho nhóm `TAHO_DB_*` trong đường này: Not confirmed by current source code. Xem [Biến môi trường](https://docs.taho.com.vn/reference/environment-variables.md).

## Ba cách source truy cập dữ liệu

| Cách truy cập | Dùng cho | Đặc điểm |
| - | - | - |
| Generic repository | Danh mục và CRUD quản trị | Module allowlist, tower scope, codec và validation chung |
| Specialized service | Membership, vehicle, RBAC, reminder | Validation và transaction theo workflow |
| Financial transaction | Billing, receipt, adjustment, excess | Lock/version/dependency checks và audit side effects |

`src/core/db/database-store.ts` đăng ký các table delegate cho generic repository. Schema hiện có 69 models; một số relation và workflow model chỉ được service hoặc Prisma transaction truy cập.

## Tenant boundary trong schema

Tenant vận hành hiện tại là tòa nhà được nhận diện bằng `Towers.tower_code` và các field `tower_id` trên dữ liệu nghiệp vụ.

| Nhóm model | Tenant shape hiện tại |
| - | - |
| Dữ liệu nghiệp vụ | Phần lớn có `tower_id` và relation tới `Towers.tower_code` |
| User-to-tower assignment | `UserBuildings` nối `Users.id` với `Towers.id` |
| Permission groups | `PermissionGroups`, `Permissions` và các bảng nối không có `tower_id` |
| Authentication account | `AuthUsers` liên kết 1-1 với `Users`; không trực tiếp liên kết tower |

Nhiều relation nghiệp vụ dùng khóa kết hợp chứa `tower_id`, ví dụ cư dân–căn hộ, phương tiện–căn hộ/dịch vụ, bảng kê–dòng phí và đối soát cư dân.

`Bills` tham chiếu căn hộ bằng cặp `tower_id` và `apartment`, trỏ tới `Apartments.tower_id` và `Apartments.code`. Schema hiện tại không có `Bills.apartment_id`. Migration kiểm tra mã căn hộ trùng trong cùng tòa nhà và bảng kê tham chiếu sai trước khi tạo khóa ngoại; dữ liệu không hợp lệ làm migration dừng. Việc migration đã chạy trên database vận hành: Not confirmed by current source code.

Generic repository xác định table có tenant scope bằng việc kiểm tra table có column `tower_id`. List thêm tower filter; create sở hữu giá trị `tower_id`; get/update/delete kiểm tra tower của record.

> [!WARNING]
>
> PostgreSQL Row-Level Security policy: `Not Found`. Tenant isolation hiện phụ thuộc vào handler, repository/service query và schema relations. Raw Prisma query mới không tự nhận tower filter.

## Thêm hoặc đổi dữ liệu

**1. Sửa schema**

Cập nhật `prisma/schema.prisma`, gồm relation, index và database mapping cần thiết.

**2. Tạo migration**

Migration được lưu dưới `prisma/migrations`. Kiểm tra trạng thái migration trên database đích; việc file migration tồn tại không chứng minh đã triển khai.

**3. Cập nhật access path**

Thêm delegate/repository validation hoặc specialized transaction tùy workflow. Không đưa financial tables vào generic write path.

**4. Cập nhật tests và docs**

Kiểm tra codec, constraint, tower scope và affected workflow trước khi cập nhật Data dictionary.

`prisma.config.ts` trỏ migration path tới `prisma/migrations` và seed command tới `prisma/seed.ts`. Existing README chỉ là bằng chứng phụ nếu khác executable config.

Xem danh sách models tại [Data dictionary](https://docs.taho.com.vn/reference/data-dictionary.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.