# debt-management-screen Specification

## Purpose
Admin-facing surfaces for working with customer debt: the "Danh sách công nợ" list with its name/phone search, the per-customer "Công nợ" tab that holds a customer's debt-related order history, and the shared "Ghi nợ tay" / "Thu nợ" actions for recording debt and repayments outside the POS flow.
## Requirements
### Requirement: Danh sách công nợ screen lists customers with debt information
The system SHALL provide a "Danh sách công nợ" screen listing every customer with an outstanding balance, showing only their name, phone number, and current `debt_total` — no per-row action controls. Each row SHALL link to that customer's "Công nợ" tab on their own customer detail page (there is no separate standalone debt detail page).

#### Scenario: Viewing the debt list
- **WHEN** an admin opens the Danh sách công nợ screen
- **THEN** the screen shows a row per customer with an outstanding balance, displaying their name, phone number, and current `debt_total`, with no "Thao tác" column

#### Scenario: Opening a customer's debt detail from the list
- **WHEN** an admin clicks a customer's row on the Danh sách công nợ screen
- **THEN** the system navigates to that customer's detail page with its "Công nợ" tab already active

### Requirement: Danh sách công nợ screen can be filtered by customer name or phone
The system SHALL provide a search input on the Danh sách công nợ screen that filters the visible rows to those whose name or phone number matches the entered text, without requiring a page reload.

#### Scenario: Searching narrows the list
- **WHEN** an admin types text into the search input that matches part of a customer's name or phone number
- **THEN** only rows matching that text remain visible, immediately, without a page reload

#### Scenario: Search matches nothing
- **WHEN** an admin types text into the search input that matches no customer's name or phone number
- **THEN** no rows are shown and a "not found" message is displayed instead

#### Scenario: Clearing the search shows the full list again
- **WHEN** an admin clears the search input
- **THEN** all customers with outstanding debt are shown again

### Requirement: A "Công nợ" tab on the customer detail page shows that customer's related orders
The customer detail page SHALL include a "Công nợ" tab, alongside its existing "Thông tin cơ bản" / "Thống kê nhanh" / "Đơn hàng đã mua" tabs, showing that customer's current `debt_total` and the list of orders linked to their `pos_debt` ledger entries (i.e. orders that contributed to their current or past debt). This tab is the single place a customer's debt-related order history is shown — it is not duplicated on a separate screen.

#### Scenario: Viewing a customer's related orders
- **WHEN** an admin opens the "Công nợ" tab on a customer's detail page
- **THEN** the tab shows that customer's current `debt_total` and the orders linked to their `pos_debt` ledger entries

#### Scenario: The "Thống kê nhanh" tab does not duplicate the related-orders list
- **WHEN** an admin views a customer's "Thống kê nhanh" tab
- **THEN** that tab does not show the list of orders related to that customer's debt — that list lives only in the "Công nợ" tab

### Requirement: Manual debt entry for a customer, from a shared action reachable without leaving the debt list
The system SHALL allow recording a debt amount directly for a customer, independent of any POS order, via a single "Ghi nợ tay" action available at the top of the Danh sách công nợ screen (not per row) — using it opens a form to search for and select the target customer, then enter the amount and an optional note. The same action, already scoped to the customer, SHALL also be available on that customer's "Công nợ" tab.

#### Scenario: Recording a manual debt from the debt list screen
- **WHEN** an admin uses the shared "Ghi nợ tay" action on the Danh sách công nợ screen, selects a customer, and submits a valid amount
- **THEN** a `manual_debt` ledger entry is created for the selected customer and their `debt_total` increases by that amount

#### Scenario: Recording a manual debt from the customer's own "Công nợ" tab
- **WHEN** an admin uses the "Ghi nợ tay" action on a customer's "Công nợ" tab and submits a valid amount
- **THEN** a `manual_debt` ledger entry is created for that customer (no customer selection needed, since it is already scoped) and their `debt_total` increases by that amount

### Requirement: Repayment can be recorded from the debt list or from the customer's own "Công nợ" tab
The system SHALL provide a "Thu nợ" action: as a single shared action at the top of the Danh sách công nợ screen (not per row) that opens a form to search for and select the target customer before entering the amount; and, already scoped to the customer, on that customer's "Công nợ" tab.

#### Scenario: Recording a repayment from the debt list screen
- **WHEN** an admin uses the shared "Thu nợ" action on the Danh sách công nợ screen, selects a customer, and submits a valid amount
- **THEN** a `repayment` ledger entry is created for the selected customer and their `debt_total` decreases by that amount

#### Scenario: Recording a repayment from the customer's own "Công nợ" tab
- **WHEN** an admin uses the "Thu nợ" action on a customer's "Công nợ" tab with a valid amount
- **THEN** a `repayment` ledger entry is created for that customer (no customer selection needed) and their `debt_total` decreases by that amount

#### Scenario: Repayment amount exceeds the customer's current debt
- **WHEN** an admin attempts to record a repayment greater than the customer's current `debt_total`, from either location
- **THEN** the repayment is rejected with a validation error and the customer's `debt_total` is unchanged