App 9 – Chi phí, nhà cung cấp & thu nhập

Hướng: Xây mới bằng builder · Đợt: Đợt 2 · Phụ thuộc: hrm (đợt 0), App 7
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: ghi nhận chi phí công ty và chi phí nhân viên ứng trước (có duyệt hoàn tiền), chi phí định kỳ, nhà cung cấp, thu nhập và tính thưởng; cho bức tranh thu – chi theo tháng. Nguồn: Expenses, Expense Categories, Recurring Expenses, Vendors, Income.

Hướng: xây mới bằng builder. Phụ thuộc: nhân viên và phòng ban từ hrm (đợt 0); khách hàng và dự án từ App 7, App 6 (tạm dùng bảng tham chiếu có dữ liệu mẫu, lượt 5 nối thật).

Vai trò & quyền

Vai trò	Được làm
Kế toán	Toàn quyền chi phí, thu nhập, nhà cung cấp, danh mục; duyệt lần cuối và đánh dấu đã hoàn tiền
Quản lý	Duyệt chi phí nhân viên trong phòng ban (bước 1)
Nhân viên	Tạo, sửa, xóa chi phí của mình khi còn Nháp; gửi duyệt; đính kèm chứng từ

Dữ liệu

Thực thể	Trường	Ghi chú
Danh mục chi phí	tên, mô tả	Mẫu: Đi lại, Ăn uống, Văn phòng phẩm, Phần mềm, Phần cứng, Đào tạo, Marketing, Tiện ích, Bảo hiểm, Khác
Nhà cung cấp	tên, email, điện thoại, website, mã số thuế, tag
Chi phí	phạm vi (Công ty, Nhân viên), nhân viên, ngày, danh mục, nhà cung cấp, số tiền, tiền tệ, loại (Tính lại cho khách, Nội bộ, Được khấu trừ thuế), khách hàng, dự án, chứng từ (tệp), ghi chú, trạng thái, người duyệt, lý do từ chối, đã đưa vào hóa đơn (đúng/sai)	Khách hàng bắt buộc nếu Tính lại cho khách
Chi phí định kỳ	phạm vi, nhân viên, danh mục, nhà cung cấp, số tiền, tiền tệ, chu kỳ (Hàng tháng, Hàng quý, Hàng năm), ngày bắt đầu, ngày kết thúc (tùy chọn), lần sinh gần nhất	Mẫu: tiền thuê, thuê bao phần mềm, phụ cấp
Thu nhập	ngày ghi nhận, số tiền, tiền tệ, nguồn (Khách thanh toán, Hoa hồng, Khác), khách hàng, nhân viên, ghi chú, tag
Cấu hình thưởng	kiểu (Theo lợi nhuận, Theo doanh thu), tỉ lệ %

Trạng thái chi phí nhân viên

Nháp → Chờ quản lý duyệt → Chờ kế toán duyệt → Đã duyệt → Đã hoàn tiền. Ở hai bước duyệt có thể Từ chối (bắt buộc lý do); nhân viên sửa rồi gửi lại. Chi phí công ty do kế toán nhập thì Đã duyệt ngay.

Quy tắc nghiệp vụ

1. Số tiền phải lớn hơn 0; ngày chi không ở tương lai.
2. Chi phí nhân viên phải có chứng từ khi số tiền vượt ngưỡng cấu hình (ví dụ 200.000 đ).
3. Chi phí loại Tính lại cho khách bắt buộc có khách hàng; chỉ chi phí Đã duyệt mới được đưa vào hóa đơn (App 8), mỗi chi phí một lần.
4. Quản lý và kế toán không tự duyệt chi phí của mình.
5. Chi phí đã duyệt không sửa hoặc xóa.
6. Mỗi ngày một tác vụ nền tạo chi phí từ chi phí định kỳ đến hạn; không tạo trùng kỳ và dừng sau ngày kết thúc.
7. Thưởng: theo lợi nhuận = (thu nhập − chi phí) × %; theo doanh thu = thu nhập × %; tính theo tháng.
8. Không xóa danh mục hoặc nhà cung cấp đã có chi phí.

Màn hình

Màn hình	Nội dung
Chi phí của tôi	Tạo, đính kèm chứng từ, gửi duyệt, theo dõi trạng thái
Duyệt chi phí	Hàng chờ theo vai trò (quản lý / kế toán), xem chứng từ, duyệt hoặc từ chối
Sổ chi phí	Mọi chi phí, lọc theo danh mục, nhà cung cấp, dự án, tháng
Chi phí định kỳ	Danh sách, lần sinh tiếp theo
Thu nhập	Danh sách thu nhập, lọc theo khách hàng, tháng
Nhà cung cấp	Danh sách và tổng chi theo từng nhà cung cấp
Báo cáo thu – chi	Thu, chi, lợi nhuận theo tháng; chi theo danh mục; thưởng ước tính

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: chi phí và quy trình duyệt

Tôi cần app quản lý chi phí có phân quyền, lưu trong database, có đính kèm tệp chứng từ.
Mọi dữ liệu tách theo tổ chức của người đăng nhập.
Nhân viên và phòng ban không tự quản lý mà lấy từ sự kiện của app hrm
(hrm:stream:employees và sự kiện phòng ban) vào bảng chỉ đọc; người đăng nhập
khớp với nhân viên qua mã user Shell.
Có dữ liệu mẫu cho bảng nhân viên và phòng ban (khoảng 3 phòng ban, 10 nhân viên,
có quản lý và nhân viên) để thử phân quyền trong bản xem trước.
Khách hàng và dự án tạm lưu bảng tham chiếu chỉ đọc (mã, tên), có dữ liệu mẫu.
Dữ liệu: danh mục chi phí (mẫu: Đi lại, Ăn uống, Văn phòng phẩm, Phần mềm, Phần
cứng, Đào tạo, Marketing, Tiện ích, Bảo hiểm, Khác), nhà cung cấp (tên, email, điện
thoại, website, mã số thuế), chi phí (phạm vi công ty hoặc nhân viên, nhân viên,
ngày, danh mục, nhà cung cấp, số tiền, tiền tệ, loại Tính lại cho khách/Nội bộ/Được
khấu trừ thuế, khách hàng, dự án, chứng từ, ghi chú, trạng thái Nháp/Chờ quản lý
duyệt/Chờ kế toán duyệt/Đã duyệt/Đã hoàn tiền/Từ chối, người duyệt, lý do từ chối).
Phân quyền: nhân viên tạo, sửa, xóa chi phí của mình khi còn Nháp và gửi duyệt;
quản lý duyệt bước 1 cho phòng mình; kế toán duyệt bước 2, đánh dấu đã hoàn tiền và
nhập chi phí công ty (duyệt ngay); không ai tự duyệt chi phí của mình.
Quy tắc (kiểm tra ở API): số tiền lớn hơn 0, ngày không ở tương lai; trên 200.000 đ
phải có chứng từ; Tính lại cho khách thì bắt buộc khách hàng; từ chối phải có lý do,
nhân viên sửa rồi gửi lại; chi phí đã duyệt không sửa, xóa; không xóa danh mục hoặc
nhà cung cấp đã có chi phí.
Màn hình: chi phí của tôi, hàng chờ duyệt theo vai trò có xem chứng từ, sổ chi phí
có lọc theo danh mục, nhà cung cấp, dự án, tháng; danh sách nhà cung cấp.

Lượt 2 – Chi phí định kỳ

Thêm chi phí định kỳ (phạm vi, nhân viên, danh mục, nhà cung cấp, số tiền, chu kỳ
Hàng tháng/Hàng quý/Hàng năm, ngày bắt đầu, ngày kết thúc tùy chọn). Mỗi ngày một
tác vụ nền tạo chi phí từ khoản đến hạn, không tạo trùng kỳ, dừng sau ngày kết thúc.
Màn danh sách có lần sinh tiếp theo.

Lượt 3 – Thu nhập, thưởng và báo cáo

Thêm thu nhập (ngày, số tiền, tiền tệ, nguồn Khách thanh toán/Hoa hồng/Khác, khách
hàng, nhân viên, ghi chú) chỉ kế toán quản lý. Thêm cấu hình thưởng (theo lợi nhuận
hoặc theo doanh thu, tỉ lệ %). Báo cáo thu – chi theo tháng: thu, chi, lợi nhuận,
chi theo danh mục, thưởng ước tính; tính ở API.

Lượt 4 – Phát sự kiện cho app khác

Phát sự kiện qua Redis Streams khi chi phí được duyệt hoặc hủy duyệt (mã, ngày,
số tiền, tiền tệ, loại, khách hàng, dự án, mô tả), để app hóa đơn lấy chi phí tính
lại cho khách.

Lượt 5 (sau khi App 7 và 6 xong) – Nối dữ liệu thật

Thay bảng tham chiếu khách hàng và dự án bằng dữ liệu đồng bộ từ sự kiện của app
CRM và app dự án vào bảng chỉ đọc; giữ nguyên liên kết của các chi phí đã có.

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:

• [ ] Nhân viên không tự duyệt được chi phí của mình, kể cả khi là quản lý.
• [ ] Chi phí trên 200.000 đ không có chứng từ thì không gửi được.
• [ ] Quản lý phòng A không thấy chi phí của phòng B.
• [ ] Chạy tác vụ chi phí định kỳ hai lần trong ngày không tạo trùng.
• [ ] Checklist chung trong 00-tong-quan.md (mục Checklist chung trước khi Publish).