> ## 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.

# Tính công nợ

> Cách tạo bảng kê nháp và dòng phí cho một kỳ đang mở.

Bạn tạo bảng kê nháp tại **Công nợ - thanh toán** → **Chỉ số điện nước**, trong phần **Tính công nợ theo kỳ**.

| Tóm tắt | Nội dung |
| - | - |
| Trạng thái | `Implemented` |
| Người thực hiện | Tài khoản có quyền tính công nợ và đã chọn tòa nhà |
| Kết quả | Tạo bảng kê `draft`, dòng phí `open` và audit log |

## Trước khi thực hiện

* Kỳ tính công nợ đang mở.
* Có ít nhất một căn hộ `active` trong phạm vi được chọn.
* Chưa có bảng kê còn hiệu lực cho cùng căn hộ và kỳ.
* Dữ liệu dịch vụ hoặc chỉ số tạo được ít nhất một dòng phí.

## Các bước

![Form tính công nợ theo kỳ](https://mintcdn.com/taho-a5b7eb2b/EvnCrV7SdQSoqqYy/images/finance/calculate-billing-form.png?fit=max\&auto=format\&n=EvnCrV7SdQSoqqYy\&q=85\&s=ed670ed357bc122978d75e3b3ce5ad02)

Form tính công nợ theo kỳ trên màn hình Chỉ số điện nước

**1. Mở màn hình tính công nợ**

Chọn tòa nhà cần làm việc. Mở **Công nợ - thanh toán** → **Chỉ số điện nước** và tìm phần **Tính công nợ theo kỳ** ở cuối trang. Phần này chỉ hiển thị khi tài khoản có quyền tính phí.

**2. Nhập kỳ và hạn thanh toán**

Chọn **Kỳ tính phí** (ví dụ tháng 7/2026) và **Hạn thanh toán** (ví dụ 15/08/2026). Để trống **Mã căn hộ** nếu muốn tính cho toàn bộ tòa nhà, hoặc nhập danh sách mã căn hộ cần tính (phân cách bằng dấu phẩy).

**3. Bấm Tính công nợ**

Bấm nút **Tính công nợ**. Hệ thống sẽ đọc dịch vụ đang áp dụng cùng chỉ số điện nước đã chốt của kỳ để tạo bảng kê nháp.

**4. Kiểm tra thông báo kết quả**

Khi hoàn tất, hệ thống hiện thông báo xác nhận: **Đã tính công nợ và tạo bảng kê nháp kèm các dòng phí.**

![Thông báo tính công nợ thành công](https://mintcdn.com/taho-a5b7eb2b/EvnCrV7SdQSoqqYy/images/finance/calculate-billing-result.png?fit=max\&auto=format\&n=EvnCrV7SdQSoqqYy\&q=85\&s=4cb17b1580ca2f19af407ded3daed630)

Thông báo thành công sau khi hoàn tất tính công nợ nháp

Bảng kê mới tạo ở trạng thái **Chờ duyệt**; tiếp tục mở [Duyệt bảng kê](https://docs.taho.com.vn/finance/approve-bill.md) để kiểm tra số liệu trước khi thu tiền.

## Tình huống thực tế

> **Ví dụ:** Ban quản lý tính phí tháng `07/2026` cho tòa nhà:
>
> * **Căn hộ A0101**: Có chỉ số Nước tiêu thụ 15 m³ (225.000 đ) và Điện tiêu thụ 132 kWh (462.000 đ). Hệ thống tạo bảng kê nháp tổng phát sinh `687.000 đ`.
> * **Căn hộ A0102**: Có chỉ số Nước tiêu thụ 12 m³ (180.000 đ). Hệ thống tạo bảng kê nháp tổng phát sinh `180.000 đ`.
> * Cả 2 bảng kê được đưa vào danh sách **Duyệt số liệu** để người phụ trách kiểm tra lại.

> [!NOTE]
>
> Để trống **Mã căn hộ (không bắt buộc)** nghĩa là tính cho tất cả căn hộ đang hoạt động trong tòa nhà. Nếu bất kỳ căn hộ nào trong phạm vi đã có bảng kê còn hiệu lực cùng kỳ, toàn bộ yêu cầu bị từ chối.

## Khi hệ thống không tạo bảng kê

| Điều kiện | Kết quả |
| - | - |
| Kỳ đã khóa | Không tạo dữ liệu |
| Không có căn hộ active phù hợp | Trả lỗi |
| Đã có bảng kê còn hiệu lực cho cùng căn hộ và kỳ | Trả lỗi |
| Không tạo được dòng phí | Không tạo bảng kê |

Nếu chỉ một số căn hộ không có dòng phí hợp lệ, hệ thống bỏ qua các căn hộ đó và tạo bảng kê cho những căn hộ còn lại. Nếu không căn hộ nào tạo được dòng phí, yêu cầu trả lỗi.

Xem sơ đồ, User Story và Acceptance Criteria tại [Use case và workflow](https://docs.taho.com.vn/product-specs/workflow-specifications.md).

> [accordion] Dành cho BA, QA và kỹ thuật
>
> ### User story
>
> Với tài khoản có quyền `action:calculate_billing`, người dùng có thể tạo bảng kê nháp và dòng phí cho một kỳ đang mở trong `activeTowerId`.
>
> ### Acceptance criteria
>
> * **Given** kỳ đang mở và dữ liệu nguồn hợp lệ, **when** gửi intent `calculate-billing`, **then** hệ thống tạo `Bills`, `BillLines` và `AuditLogs` trong một transaction.
> * **Given** kỳ đã khóa, **when** gửi yêu cầu, **then** hệ thống không tạo dữ liệu.
> * **Given** đã có bảng kê còn hiệu lực cho cùng căn hộ và kỳ, **when** gửi yêu cầu, **then** hệ thống trả lỗi.
>
> ### Call path và kiểm thử
>
> `POST /admin/workflow` → intent `calculate-billing` → `calculateBillingPeriod()` → Prisma transaction.
>
> Các trường hợp dòng phí cố định, theo chỉ số, dịch vụ phương tiện và kỳ khóa nằm trong `test/financial-workflows.test.ts`.


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