App 8 – Hóa đơn, báo giá & thanh toán

Hướng: Xây mới bằng builder · Đợt: Đợt 2 (cuối) · Phụ thuộc: App 7, 11, 4, 9
Quy ước chung, nguồn dữ liệu nhân viên và cách chạy builder: 00-tong-quan.md

Mục đích: lập báo giá và hóa đơn cho khách (từ sản phẩm, giờ làm hoặc chi phí tính lại), gửi cho khách xem qua link, ghi nhận thanh toán từng phần và theo dõi công nợ. Nguồn: Invoicing, Payments, Client Portal, Accounting Templates.

Hướng: xây mới bằng builder. Phụ thuộc: khách hàng (App 7), sản phẩm (App 11), giờ làm (App 4), chi phí (App 9). Lượt 1–4 xây được ngay với bảng tham chiếu có dữ liệu mẫu; lượt 5 nối dữ liệu thật khi các app kia xong.

Vai trò & quyền

Vai trò	Được làm
Kế toán	Toàn quyền: tạo, gửi, hủy hóa đơn và báo giá; ghi thanh toán; cấu hình thuế và đánh số
Nhân viên bán hàng	Tạo và gửi báo giá, xem hóa đơn của khách hàng mình phụ trách
Khách hàng (không đăng nhập)	Mở link bí mật để xem, tải PDF, chấp nhận hoặc từ chối báo giá/hóa đơn

Dữ liệu

Thực thể	Trường	Ghi chú
Hóa đơn / báo giá	loại (Hóa đơn, Báo giá), số (tự tăng theo loại, ví dụ INV-2026-0001), khách hàng, ngày lập, hạn thanh toán, tiền tệ, thuế 1 (%), thuế 2 (%), chiết khấu (giá trị + kiểu % hoặc số tiền), tạm tính, tiền thuế, tổng cộng, đã trả, còn nợ (tự tính), ghi chú, điều khoản, trạng thái, mã link chia sẻ, hạn link, tạo từ báo giá nào	Khách hàng tham chiếu App 7
Dòng hàng	hóa đơn, nguồn (Sản phẩm, Task, Nhân viên theo giờ, Dự án, Chi phí, Nhập tay), mô tả, số lượng, đơn giá, thành tiền (tự tính), áp thuế (đúng/sai), áp chiết khấu (đúng/sai)	Sản phẩm từ App 11, giờ từ App 4, chi phí từ App 9
Thanh toán	hóa đơn, ngày, số tiền, tiền tệ, phương thức (Chuyển khoản, Tiền mặt, Séc, Thẻ tín dụng, Thẻ ghi nợ, Trực tuyến), ghi chú, người ghi
Cấu hình	thuế mặc định (tên và %), tiền tố số hóa đơn và báo giá, số ngày hạn thanh toán mặc định, thông tin ngân hàng in trên hóa đơn, logo

Trạng thái hóa đơn

Nháp → Đã gửi → Khách đã xem → Chấp nhận → Đã thanh toán. Quá hạn mà còn nợ thì sang Quá hạn; trả đủ thì vẫn về Đã thanh toán. Trả một phần thì hiển Thanh toán một phần. Từ Nháp hoặc Đã gửi có thể Hủy (void).

Báo giá: Nháp → Đã gửi → Chấp nhận hoặc Từ chối; báo giá Chấp nhận chuyển được thành hóa đơn.

Quy tắc nghiệp vụ

1. Số hóa đơn tự tăng, duy nhất, không sửa; hóa đơn hủy vẫn giữ số.
2. Thành tiền dòng = số lượng × đơn giá; tạm tính = tổng thành tiền; chiết khấu tính trên các dòng áp chiết khấu; thuế tính trên phần sau chiết khấu của các dòng áp thuế; tổng = tạm tính − chiết khấu + thuế. Tính ở server.
3. Chỉ sửa nội dung khi hóa đơn là Nháp; đã gửi thì chỉ được hủy và lập hóa đơn mới.
4. Không ghi thanh toán cho hóa đơn Nháp hoặc Đã hủy; tổng thanh toán không vượt tổng hóa đơn.
5. Đã trả = tổng thanh toán; còn nợ = 0 thì tự chuyển Đã thanh toán; quá hạn thanh toán mà còn nợ thì tự chuyển Quá hạn.
6. Một giờ làm hoặc một chi phí chỉ được đưa vào một hóa đơn chưa hủy (chống tính tiền hai lần).
7. Link chia sẻ dùng mã ngẫu nhiên, có hạn; khách mở link lần đầu thì chuyển Khách đã xem; trang công khai chỉ trả về đúng hóa đơn đó.

Màn hình

Màn hình	Nội dung
Danh sách hóa đơn	Lọc theo trạng thái, khách hàng, khoảng ngày; tổng còn nợ, quá hạn
Danh sách báo giá	Tương tự; nút Chuyển thành hóa đơn
Soạn hóa đơn	Thông tin chung, bảng dòng hàng; thêm dòng từ sản phẩm, giờ làm chưa tính tiền, chi phí tính lại; tổng tự cập nhật
Chi tiết hóa đơn	Xem trước bản in, tải PDF, Gửi (tạo link), ghi thanh toán, lịch sử thanh toán
Trang khách hàng	Trang công khai theo link: xem, tải PDF, Chấp nhận / Từ chối
Báo cáo công nợ	Công nợ theo khách hàng và tuổi nợ (0–30, 31–60, trên 60 ngày)

Prompt cho builder – chia lượt

Dán từng lượt theo thứ tự, mỗi lượt là một tin nhắn. Duyệt kế hoạch trước khi builder chạy; chỉ sang lượt sau khi lượt trước đã kiểm tra xong trong bản xem trước.

Lượt 1 – Lõi: hóa đơn, dòng hàng, thanh toán

Tôi cần app hóa đơn và thanh toán có phân quyền, lưu trong database.
Mọi dữ liệu tách theo tổ chức của người đăng nhập.
Nhân viên lấy từ sự kiện của app hrm (hrm:stream:employees) vào bảng chỉ đọc,
khớp người đăng nhập qua mã user Shell; khi hrm chưa phát đủ sự kiện thì tạm dùng
sự kiện người dùng của Shell (shell:stream:users).
Có dữ liệu mẫu cho bảng nhân viên (khoảng 10 người) để thử trong bản xem trước.
Khách hàng tạm lưu bảng tham chiếu chỉ đọc (mã, tên, email, người phụ trách), có dữ
liệu mẫu.
Dữ liệu: hóa đơn (số tự tăng dạng INV-2026-0001, khách hàng, ngày lập, hạn thanh
toán, tiền tệ, thuế 1 %, thuế 2 %, chiết khấu % hoặc số tiền, tạm tính, tiền thuế,
tổng, đã trả, còn nợ, ghi chú, điều khoản, trạng thái Nháp/Đã gửi/Khách đã xem/Chấp
nhận/Thanh toán một phần/Đã thanh toán/Quá hạn/Đã hủy), dòng hàng (mô tả, số lượng,
đơn giá, thành tiền, áp thuế, áp chiết khấu), thanh toán (hóa đơn, ngày, số tiền,
phương thức chuyển khoản/tiền mặt/séc/thẻ/trực tuyến, ghi chú), cấu hình (thuế mặc
định, tiền tố số, số ngày hạn mặc định, thông tin ngân hàng).
Phân quyền: kế toán toàn quyền; nhân viên bán hàng chỉ xem hóa đơn của khách mình
phụ trách.
Quy tắc (kiểm tra ở API): mọi số tiền tính ở API – thành tiền = số lượng × đơn giá,
chiết khấu trên các dòng áp chiết khấu, thuế trên phần sau chiết khấu của dòng áp
thuế, tổng = tạm tính − chiết khấu + thuế; số hóa đơn không trùng, không sửa, hóa đơn
hủy vẫn giữ số; chỉ sửa khi còn Nháp; không ghi thanh toán cho hóa đơn Nháp hoặc Đã
hủy; tổng thanh toán không vượt tổng hóa đơn; trả đủ thì tự Đã thanh toán, trả một
phần thì Thanh toán một phần; quá hạn còn nợ thì tự Quá hạn.
Màn hình: danh sách hóa đơn có lọc theo trạng thái, khách hàng, khoảng ngày và tổng
còn nợ; soạn hóa đơn có bảng dòng hàng, tổng tự cập nhật; chi tiết hóa đơn có xem
trước bản in, ghi thanh toán, lịch sử thanh toán.

Lượt 2 – Báo giá

Thêm báo giá dùng chung cấu trúc hóa đơn với loại Báo giá và số riêng (EST-...):
Nháp → Đã gửi → Chấp nhận hoặc Từ chối. Báo giá Chấp nhận có nút Chuyển thành hóa
đơn (sao chép dòng hàng, ghi hóa đơn được tạo từ báo giá nào).

Lượt 3 – Trang công khai cho khách

Thêm link chia sẻ cho hóa đơn và báo giá: mã ngẫu nhiên, có hạn. Trang công khai
không cần đăng nhập, chỉ trả về đúng chứng từ đó, cho xem, tải PDF, Chấp nhận hoặc
Từ chối. Khách mở link lần đầu thì chuyển Khách đã xem.

Lượt 4 – Nguồn dòng hàng và báo cáo

Thêm nguồn dòng hàng: chọn sản phẩm (giá tự điền), giờ làm chưa tính tiền, chi phí
tính lại cho khách đã duyệt. Tạm lưu sản phẩm, giờ làm, chi phí ở bảng tham chiếu
chỉ đọc có dữ liệu mẫu. Mỗi giờ làm hoặc chi phí chỉ vào một hóa đơn chưa hủy; hủy
hóa đơn thì giải phóng lại. Thêm báo cáo công nợ theo khách hàng và tuổi nợ 0–30,
31–60, trên 60 ngày.

Lượt 5 (sau khi App 7, 11, 4, 9 xong) – Nối dữ liệu thật

Thay các bảng tham chiếu bằng dữ liệu đồng bộ từ sự kiện của các app khác vào bảng
chỉ đọc: khách hàng từ app CRM, sản phẩm và giá bán từ app kho, giờ làm đã duyệt
có tính phí khách từ app ghi giờ, chi phí tính lại cho khách đã duyệt từ app chi phí.
Giữ nguyên các hóa đơn đã lập và quy tắc mỗi giờ làm hoặc chi phí chỉ vào một hóa đơn.

Kiểm tra trước khi Publish

Đăng nhập lần lượt bằng từng vai trò trong bản xem trước:

• [ ] Tổng hóa đơn tính ở API: sửa tổng từ trình duyệt không có tác dụng.
• [ ] Ghi thanh toán vượt số còn nợ thì bị từ chối; trả đủ thì tự Đã thanh toán.
• [ ] Hóa đơn đã gửi không sửa được nội dung; số hóa đơn không trùng.
• [ ] Link công khai chỉ mở đúng một hóa đơn, hết hạn thì không mở được.
• [ ] Checklist chung trong 00-tong-quan.md (mục Checklist chung trước khi Publish).