URD: Tài chính

Module	CORE-12	Phiên bản	v0.6
Trạng thái	In-progress	Ngày	2026-06-15

Tài liệu nghiệp vụ. URD này là danh sách tính năng của Tài chính - mỗi tính năng dưới đây là một Khu vực chức năng (<AREA>). Cùng <AREA> đó làm khóa cho các PRD (PRD-<AREA>-NNN) và test (TC-<AREA>-NNN) của tính năng, và mỗi tính năng được liệt kê trong danh mục tính năng Delivery. Xem quy ước Feature Spine.

1. Mục đích

Định nghĩa các yêu cầu hướng người dùng cho Tài chính - sổ sách của merchant. Module phải theo dõi tiền trên các tài khoản (tiền mặt, ngân hàng, QR, mobile-POS), ghi nhận mọi dòng tiền dưới dạng một phiếu ghi sổ kép cân bằng, phân loại thu và chi theo danh mục, và tạo phần lớn hạch toán tự động để phản ứng với bán hàng, mua hàng, và biến động kho, nhờ đó chủ không phải ghi các dòng tiền thường nhật bằng tay.

2. Phạm vi

Bao gồm	Loại trừ
Tài khoản tiền / ví (Tiền mặt, Ngân hàng, QR, Mobile-POS)	Xử lý cổng thanh toán (module Payment)
Tài khoản kiểm soát nội bộ (Tồn kho, Giá vốn hàng bán)	Phát hành hóa đơn thuế (module Invoice)
Phiếu: thu, chi, chuyển khoản, điều chỉnh	Tính số lượng & định giá kho (module Tồn kho)
Dòng sổ cái (nợ / có) cho mỗi phiếu	Theo dõi ngân sách, P&L, dự báo dòng tiền (tương lai)
Danh mục thu / chi (dựng sẵn + tùy chỉnh)	Chi phí định kỳ / theo lịch (tương lai)
Tự hạch toán từ thanh toán bán hàng, nhận PO, biến động kho	Chụp ảnh biên lai / OCR (tương lai)
Hủy phiếu bằng bút toán đảo cân bằng	Quy đổi đa tiền tệ (mỗi phiếu một loại tiền tệ)

3. Định nghĩa

Thuật ngữ	Định nghĩa
Tài khoản (ví)	Nơi tiền nằm - một ngăn kéo tiền mặt, tài khoản ngân hàng, tài khoản chấp nhận QR, hoặc thiết bị mobile-POS. Giữ một số dư lũy kế.
Tài khoản kiểm soát nội bộ	Một tài khoản kế toán không phải tiền mặt (Tồn kho, Giá vốn hàng bán) do hệ thống tự động duy trì; không phải tiền của người dùng.
Phiếu	Một chứng từ kế toán ghi nhận một sự kiện tiền: phiếu thu (tiền vào), phiếu chi (tiền ra), chuyển khoản (giữa các tài khoản), hoặc điều chỉnh.
Dòng sổ cái	Một dòng nợ hoặc có bên trong một phiếu. Một phiếu luôn cân bằng: tổng nợ bằng tổng có khi cả hai bên cùng áp dụng.
Danh mục	Cách phân loại thu/chi cho một dòng tiền (ví dụ Sale, Purchase, Rent).
Tài khoản mặc định	Tài khoản mà một loại hạch toán tự động sẽ định tuyến tới theo mặc định - mỗi loại một tài khoản cho mỗi merchant.
Hủy	Hủy bỏ một phiếu đã phát hành bằng cách hạch toán một bút toán đảo bằng và ngược dấu, giữ lại bản gốc để kiểm toán.

4. Mô hình khái niệm

Chỉ mang tính khái niệm - schema đầy đủ, các enum, và bất biến nằm trong mô hình miền finance dành cho nhà phát triển.

5. Danh mục tính năng

Danh sách tính năng của module này. Mỗi hàng là một tính năng (một Khu vực chức năng). Chi tiết ở §6. Được phản chiếu trong danh mục tính năng Delivery.

Feature ID	Tính năng	Phase	Trạng thái	Ưu tiên
WAL	Tài khoản	P1	In-progress	High
VCH	Phiếu & Hạch toán	P1	In-progress	High
EVT	Hạch toán theo sự kiện	P1	Built	High
TXN	Dòng sổ cái	P1	Built	High
CAT	Danh mục	P1	Built	High
LDG	Sổ đối tác & P&L	P2	Planned	High

Trạng thái: live từ Plane nếu có map, còn lại do registry khai báo. Vocabulary đồng nhất với Plane (state-group / phase).

6. Tính năng

Một mục con cho mỗi tính năng, theo thứ tự danh mục. Mỗi tính năng giữ mô tả, yêu cầu, và tiêu chí chấp nhận của nó cùng nhau. Ưu tiên = MoSCoW (Must / Should / Could / Won't).

WAL - Tài khoản In-progress

Feature ID: expenses/WAL · Phase: P1 · PRDs: - · Dev: @nx/finance

Tính năng dành cho người dùng: merchant giữ tiền trên các tài khoản tiền mặt, ngân hàng, QR, và mobile-POS - mỗi tài khoản có số dư lũy kế, và mỗi loại có một tài khoản mặc định - trong khi hệ thống tự tạo tài khoản mặc định và tài khoản kiểm soát nội bộ cho mỗi merchant mới.

Yêu cầu

ID	P	Yêu cầu
URD-WAL-001	M	Giữ các tài khoản loại Tiền mặt, Ngân hàng, QR, và Mobile-POS, mỗi tài khoản thuộc một merchant
URD-WAL-002	M	Duy trì một tài khoản mặc định cho mỗi loại của mỗi merchant để định tuyến hạch toán tự động
URD-WAL-003	M	Tự tạo tài khoản mặc định và tài khoản kiểm soát nội bộ của mỗi merchant khi merchant được tạo
URD-WAL-004	M	Theo dõi số dư hiện tại lũy kế của mỗi tài khoản mỗi khi có phiếu hạch toán
URD-WAL-005	S	Cho phép đặt loại tiền tệ cho tài khoản (mặc định VND)
URD-WAL-006	S	Giới hạn quyền xem tài khoản theo các merchant mà người dùng được cấp (admin thấy tất cả)

Tiêu chí chấp nhận

AC-WAL-01: Tài khoản mặc định & kiểm soát khi có merchant mới

Cho	Khi	Thì
Một merchant được tạo	Sự kiện merchant được đối soát	Các tài khoản mặc định của merchant được dựng sẵn
		Tài khoản kiểm soát nội bộ Tồn kho và Giá vốn hàng bán tồn tại

VCH - Phiếu & Hạch toán In-progress

Feature ID: expenses/VCH · Phase: P1 · PRDs: - · Dev: @nx/finance

Tính năng dành cho người dùng: mọi sự kiện tiền được ghi nhận dưới dạng một phiếu cân bằng - phiếu thu tự phát hành khi đơn được thanh toán, phiếu chi khi nhận đơn mua hàng, và hạch toán giá vốn khi kho biến động - cùng với chuyển khoản thủ công, vòng đời nháp, và hủy bằng bút toán đảo cho chủ.

Yêu cầu

ID	P	Yêu cầu
URD-VCH-001	M	Ghi nhận sự kiện tiền dưới dạng phiếu loại thu, chi, chuyển khoản, hoặc điều chỉnh
URD-VCH-002	M	Mọi phiếu đều cân bằng - nợ bằng có khi cả hai bên cùng áp dụng
URD-VCH-003	M	Tự phát hành một phiếu thu khi một thanh toán bán hàng thành công, phân loại là Sale
URD-VCH-004	M	Tự phát hành một phiếu chi cho nhà cung cấp khi một đơn mua hàng được nhận
URD-VCH-005	M	Tự hạch toán giá vốn hàng bán và điều chỉnh kho vào tài khoản kiểm soát nội bộ khi kho biến động
URD-VCH-006	M	Hạch toán tự động phải idempotent - một sự kiện lặp lại không bao giờ hạch toán hai lần
URD-VCH-007	M	Liên kết mỗi phiếu tới chứng từ nguồn của nó (đơn bán, đơn mua hàng, biến động kho, thủ công)
URD-VCH-008	S	Đánh số mỗi phiếu đã phát hành theo merchant, theo loại, theo tháng
URD-VCH-009	S	Hỗ trợ vòng đời thủ công: nháp → phát hành, và xóa một bản nháp trước khi phát hành
URD-VCH-010	S	Chuyển tiền giữa hai tài khoản dưới dạng một phiếu chuyển khoản cân bằng duy nhất
URD-VCH-011	S	Hủy một phiếu đã phát hành bằng một bút toán đảo cân bằng; bản gốc được giữ lại
URD-VCH-012	C	Gán một phiếu vào một phiên ca POS cho biến động tiền mặt theo ca

Tiêu chí chấp nhận

AC-VCH-01: Tự thu khi đơn được thanh toán

Cho	Khi	Thì
Một đơn bán được thanh toán	Sự kiện thanh toán thành công đến	Một phiếu thu được phát hành, phân loại là Sale, liên kết tới đơn bán
		Số dư tài khoản nhận tăng đúng số tiền
Cùng sự kiện đó đến lại	Được xử lý lần thứ hai	Không phiếu thứ hai nào được tạo (idempotent)

AC-VCH-02: Tự chi khi nhận đơn mua hàng

Cho	Khi	Thì
Một đơn mua hàng được nhận	Sự kiện nhận PO đến	Một phiếu chi được phát hành cho nhà cung cấp, liên kết tới đơn mua hàng
Giá trị tồn kho dương		Phiếu cân bằng vế tài sản kho với (các) vế tiền mặt

AC-VCH-03: Chuyển khoản giữa tài khoản

Cho	Khi	Thì
Hai tài khoản của merchant	Chủ chuyển một số tiền A → B	Một phiếu chuyển khoản hạch toán một bút toán nợ và một bút toán có bằng nhau
		Tài khoản A giảm và Tài khoản B tăng cùng một lượng

AC-VCH-04: Hủy bằng bút toán đảo

Cho	Khi	Thì
Một phiếu đã phát hành	Chủ hủy nó	Một phiếu đảo cân bằng được hạch toán; bản gốc được giữ lại
		Số dư các tài khoản bị ảnh hưởng trở về trạng thái trước khi có phiếu

EVT - Hạch toán theo sự kiện Built

Feature ID: finance/EVT · Phase: P1 · PRDs: PRD-EVT-001 · Dev: @nx/finance

Tính năng dành cho người dùng: Tài chính giữ sổ sách đầy đủ mà không cần nhập tay bằng cách phản ứng với những gì đã xảy ra - một đơn được thanh toán, một đơn mua hàng được nhận, hàng xuất kho cho một đơn bán, một biến động giá trị tồn kho, một merchant mới - và hạch toán phiếu tương ứng qua luồng sự kiện, một cách bất đồng bộ. Việc thu tiền không bao giờ phải chờ sổ sách; một gián đoạn Tài chính nhất thời sẽ bắt kịp về sau thay vì làm mất bút toán; và một sự kiện phát lại không bao giờ hạch toán hai lần.

Yêu cầu

ID	P	Yêu cầu
URD-EVT-001	M	Tài chính tiêu thụ sự kiện vận hành một cách bất đồng bộ; hành động bán / mua / kho gốc không bao giờ bị chặn để chờ hạch toán
URD-EVT-002	M	Đăng ký nhận các sự kiện thanh toán bán hàng thành công, nhận đơn mua hàng, xuất kho cho đơn bán, điều chỉnh tồn kho, và tạo merchant
URD-EVT-003	M	Một thanh toán bán hàng thành công hạch toán một phiếu thu, kèm một phiếu chi trả lại tiền thừa khi tiền khách đưa vượt tổng đơn
URD-EVT-004	M	Một đơn mua hàng được nhận hạch toán một phiếu chi cho nhà cung cấp, kèm vế tài sản tồn kho khi giá trị nhận dương
URD-EVT-005	M	Hàng xuất kho cho một đơn bán hạch toán một phiếu giá vốn hàng bán khi cơ sở giá vốn dương
URD-EVT-006	M	Một biến động giá trị tồn kho do người vận hành hạch toán một phiếu điều chỉnh tồn kho một dòng
URD-EVT-007	M	Một merchant mới dựng sẵn tài khoản mặc định và tài khoản kiểm soát nội bộ từ sự kiện vòng đời merchant
URD-EVT-008	M	Mọi hạch toán tự động đều idempotent - một sự kiện phát lại phát lại phiếu sẵn có, không bao giờ tạo phiếu thứ hai
URD-EVT-009	M	Một sự kiện chỉ được xác nhận sau khi hạch toán của nó commit; một handler thất bại để lại sự kiện cho phát lại (at-least-once)
URD-EVT-010	S	Sự kiện chỉ mang định danh; worker phân giải đầy đủ danh tính nguồn và đối tác (NCC, mã PO, tài khoản) trước khi hạch toán
URD-EVT-011	S	Hạch toán ngắt sạch không tạo phiếu khi không có gì để ghi (không định tuyến tài chính, cơ sở giá vốn bằng 0, chênh lệch giá trị bằng 0, không có tiền thừa)
URD-EVT-012	S	Consumer rút cạn công việc đang xử lý và đóng sạch khi nhận tín hiệu tắt

Tiêu chí chấp nhận

AC-EVT-01: Hạch toán bất đồng bộ không chặn đơn bán

Cho	Khi	Thì
Một đơn bán được thanh toán	Sự kiện thanh toán thành công được phát	Đơn bán hoàn tất ngay mà không chờ Tài chính
	Consumer Tài chính đọc sự kiện	Một phiếu thu cân bằng được hạch toán, liên kết tới đơn bán

AC-EVT-02: Idempotent khi phát lại

Cho	Khi	Thì
Một sự kiện đã tạo phiếu của nó	Cùng sự kiện đó được giao lại	Phiếu sẵn có được phát lại - không phiếu thứ hai nào được tạo

AC-EVT-03: At-least-once khi handler thất bại

Cho	Khi	Thì
Một sự kiện liên quan tiền được giao	Handler thất bại trước khi hạch toán commit	Sự kiện không được xác nhận và được phát lại
Sự kiện được phát lại	Handler thành công	Phiếu được hạch toán đúng một lần

AC-EVT-04: Giá vốn khi xuất kho

Cho	Khi	Thì
Hàng xuất kho cho một đơn bán với cơ sở giá vốn dương	Sự kiện xuất kho đến	Một phiếu giá vốn hạch toán vào tài khoản kiểm soát tồn kho
Cơ sở giá vốn bằng 0	Sự kiện đến	Không phiếu nào được hạch toán; việc bỏ qua được ghi log

AC-EVT-05: Ngắt sạch khi không có gì để ghi

Cho	Khi	Thì
Một thanh toán không mang định tuyến tài chính, hoặc tiền thừa bằng 0	Sự kiện đến	Không phiếu nào được hạch toán và không lỗi nào phát sinh
Một biến động kho có chênh lệch giá trị bằng 0	Sự kiện đến	Không phiếu nào được hạch toán; việc bỏ qua được ghi log

TXN - Dòng sổ cái Built

Feature ID: expenses/TXN · Phase: P1 · PRDs: - · Dev: @nx/finance

Tính năng dành cho người dùng: mỗi phiếu hạch toán các dòng sổ cái nợ và có lên các tài khoản, mang theo tài khoản bị tác động, một danh mục tùy chọn, một số tiền, snapshot số dư trước/sau, và một liên kết truy vết tới chứng từ nguồn.

Yêu cầu

ID	P	Yêu cầu
URD-TXN-001	M	Mỗi phiếu hạch toán các dòng sổ cái nợ/có lên các tài khoản
URD-TXN-002	M	Một dòng mang theo tài khoản nó tác động, một danh mục tùy chọn, một số tiền, và snapshot số dư trước/sau
URD-TXN-003	M	Các dòng dùng chung loại tiền tệ của phiếu
URD-TXN-004	S	Một dòng có thể tham chiếu chứng từ nguồn của nó để truy vết

Tiêu chí chấp nhận

AC-TXN-01: Dòng sổ cái cân bằng

Cho	Khi	Thì
Một phiếu được hạch toán	Các dòng sổ cái được ghi	Mỗi dòng mang theo tài khoản, số tiền, và snapshot số dư trước/sau của nó
		Các dòng dùng chung loại tiền tệ của phiếu

CAT - Danh mục Built

Feature ID: expenses/CAT · Phase: P1 · PRDs: - · Dev: @nx/finance

Tính năng dành cho người dùng: dòng tiền được phân loại thu hoặc chi bằng 14 danh mục hệ thống dựng sẵn, áp tự động cho các phiếu tự sinh, và merchant được tự do thêm danh mục tùy chỉnh lồng dưới một danh mục cha.

Yêu cầu

ID	P	Yêu cầu
URD-CAT-001	M	Cung cấp 14 danh mục hệ thống dựng sẵn, trải đều thu và chi
URD-CAT-002	M	Danh mục được gán loại thu hoặc chi
URD-CAT-003	M	Áp một danh mục hệ thống tự động cho phiếu tự sinh (ví dụ Sale, Purchase)
URD-CAT-004	S	Merchant có thể thêm danh mục tùy chỉnh, lồng dưới một danh mục cha

Tiêu chí chấp nhận

AC-CAT-01: Danh mục hệ thống trên phiếu tự động

Cho	Khi	Thì
Một phiếu tự sinh (ví dụ Sale, Purchase)	Được phát hành	Một danh mục hệ thống phù hợp được áp tự động
Một merchant thêm một danh mục tùy chỉnh dưới một danh mục cha	Lưu lại	Nó sẵn sàng để phân loại dòng tiền

LDG - Sổ Đối tác & P&L Planned

Mã tính năng: finance/LDG · Phase: P2 (T7-T8) · PRDs: PRD-LDG-001 · Dev: @nx/finance

Mang lại gì cho người dùng: merchant thấy ai nợ mình và mình nợ ai - một sổ đối tác, phải thu (khách) và phải trả (NCC) - và có thật sự lãi không, qua P&L theo kỳ.

Yêu cầu

ID	P	Yêu cầu
URD-LDG-001	M	Phải thu khách được theo dõi (bán chịu sinh nợ; phiếu thu tất toán)
URD-LDG-002	M	Phải trả NCC chạy end-to-end (sinh khi nhận PO; tất toán bằng phiếu chi)
URD-LDG-003	M	Một view sổ đối tác: theo đối tác, hai chiều, số dư lũy kế
URD-LDG-004	M	Báo cáo P&L theo kỳ (doanh thu − giá vốn − chi phí)
URD-LDG-005	S	Phải thu/phải trả tất toán qua phiếu thu/chi
URD-LDG-006	S	Sổ lọc theo loại đối tác và kỳ

Nghiệm thu

AC-LDG-01: Sổ hai chiều + P&L

Given	When	Then
Một đơn B2B bán chịu và một PO đã nhận	Chủ mở sổ đối tác	Nợ khách và nợ NCC cùng hiển thị với số dư đúng
Một tháng kinh doanh	Chủ mở P&L	Doanh thu, giá vốn, chi phí khớp với tài khoản

7. Ràng buộc & Phi mục tiêu

Ràng buộc

ID	Ràng buộc
C-01	Mọi phiếu phải cân bằng (nợ bằng có khi cả hai bên cùng áp dụng)
C-02	Đúng một tài khoản mặc định cho mỗi loại của mỗi merchant
C-03	Hạch toán tự động phải idempotent khi sự kiện lặp lại
C-04	Mọi dòng sổ cái trong một phiếu dùng chung loại tiền tệ của phiếu (một loại tiền tệ; mặc định VND)
C-05	14 danh mục hệ thống dựng sẵn không thuộc về merchant
C-06	Bản ghi dùng xóa mềm; phiếu đã phát hành không bao giờ bị xóa cứng - chúng được hủy
C-07	Tài khoản kiểm soát nội bộ phải tồn tại trước khi hạch toán giá vốn hàng bán

Phi mục tiêu

• Theo dõi ngân sách và chênh lệch
• Tự động hóa chi phí định kỳ / theo lịch
• Báo cáo lãi lỗ và dự báo dòng tiền
• Chụp ảnh biên lai / OCR
• Quy đổi đa tiền tệ trong cùng một phiếu

8. Lịch sử phiên bản

Ngày	Tác giả	Mô tả	Ver
2026-02-26	P. Do - Product Owner	User story ban đầu	v0.1
2026-04-16	P. Do - Product Owner	Phạm vi ví, giao dịch, danh mục	v0.3
2026-05-30	Chuyển đổi tài liệu	Tái cấu trúc theo mô hình phiếu ghi sổ kép đã xác minh (tài khoản / phiếu / dòng sổ cái / danh mục); sửa loại tài khoản và mô hình giao dịch	v0.4
2026-06-04	Claude (AI pair)	Tổ chức lại theo tính năng (Feature Spine)	v0.5
2026-06-15	Finance squad	Thêm tính năng EVT Hạch toán theo sự kiện (seam bán hàng → sổ cái)	v0.6