# HANDOFF – TDK Finance Manager

Cập nhật: 2026-11-15. Dự án: `C:\xampp\htdocs` (Laravel 11 + Inertia + Vue 3 + PrimeVue 4 + Tailwind, MySQL database `tdk`). Thư mục này **không phải git repo**.
Người dùng nói tiếng Việt, thích màu sắc tiết chế, giao diện giống artifact "TDK Finance Manager" (GitHub-dark).

> Ghi chú nguồn: phiên trước bị lỗi API ở các lượt cuối. Phần việc ngày 15/11 được suy ra từ danh sách file đã sửa, rồi kiểm tra lại bằng `migrate:status`, `route:list` và `php artisan test`.

## 1. Yêu cầu của người dùng

### Đã xong ở các phiên trước
- Vẽ lại giao diện theo artifact, giữ 100% tính năng (cả tool và bot Telegram). Lớp theme: `resources/css/tdk-theme.css`, `tdk-pages.css`, `tdk-icons.css`.
- Chuẩn hoá logic tính toán trong `app/Support/ExpenseFormula.php`.
- 9 tính năng bổ sung (ProfitReport, WalletReconciliation, DebtAging, ...) và tiếng Trung.

### Tab Thành viên
- Chấm công, tính lương theo tháng, có ngày off.
- Phụ cấp.
- Hoa hồng cho nhân viên tìm ra khách, % thay đổi theo thời điểm hoặc theo khách.
- Nhân viên có login riêng, chỉ quản lý khách hàng và đề xuất chi tiêu, **không xem báo cáo tài chính**.

### Quyết định người dùng đã chốt
- Cơ sở hoa hồng = **Thực thanh toán của khách** (`ExpenseFormula::finalPaymentSql`, tức `price_cid`).
- Đổi % **không áp dụng** cho hoa hồng đã chốt.
- Nạp/rút: **nhân viên đề xuất → admin xác nhận → mới cộng/trừ ví**.
- Hoa hồng **trả qua bảng lương**, ghi cụ thể từng khoản.
- Người tìm ra khách hưởng `own_percent`, người phụ trách (nếu khác) hưởng `other_percent`. Ngày công T2–T7, Chủ nhật nghỉ.

## 2. Đã hoàn thành

- **Giai đoạn 1 – Vai trò `staff`**: `StaffAccess`, `StaffCustomerScope`, `RestrictStaffAccess`, cột `users.found_by_admin_id`.
- **Giai đoạn 2 – Hoa hồng v2**: bảng `commission_rates`, `commission_lines`, `CommissionService`, `CommissionController`, trang `Commission.vue` và `MyCommission.vue`.
- **Giai đoạn 3 – Loại chấm công**: `YYYY-MM-DD` = vắng; hậu tố `:h` nửa ngày, `:u` không lương, `:l` lễ có lương.
- **Đề xuất / duyệt / phiếu lương**:
  - `MemberRequestController` (xin nghỉ, nạp/rút, chi tiêu; có thêm `partner_id`), `PayslipController`, `PayrollItemizer`.
  - Trang `MyRequests.vue`, `Approvals.vue`, `MyPayslip.vue`.
  - `PayrollEntry::netSalaryVnd()` đã cộng `commission_vnd`.
- **Phân quyền theo vai trò**: `app/Support/AdminPermissions.php`. `me.*` và `requests.*` mở cho mọi người, `approvals` cho super_user và manager. Đã sửa thêm `EnsureAdminPermission` và các controller admin liên quan.
- **Cổng khách hàng/đối tác**: Dashboard, Wallet, `PortalShell.vue`, `PortalLedgerService`, các component trong `resources/js/Components/Portal/`. Đăng nhập: `routes/auth.php`, `LoginRequest`.
- **i18n**: chuyển sang `resources/js/i18n/messages/{vi,en,zh}.js`.
- **Migration**: cả 8 migration ngày 13–15/11 đã chạy (gồm `member_requests`, bảng phụ cấp, trường duyệt `other_expenses`, `member_requests.partner_id`).
- **Build**: `public/build` build lúc 22:23 ngày 15/11. `public/hot` vẫn còn, tức web đang chạy qua dev server.

## 3. Kết quả test (chạy cuối ngày 15/11)
`php artisan test`: **200 pass, 0 lỗi**. `npx vite build` thành công.

Việc làm thêm cuối ngày 15/11:
- Test Telegram: thêm `usdtToVndRate` vào dữ liệu nạp (controller trả 422 khi thiếu tỷ giá).
- **Phụ cấp**: `AllowanceController`, route `admin.allowances*` (chỉ super_user, quyền `allowances.manage`), trang `Admin/Allowances.vue` (bảng mức theo thành viên + danh mục), menu "Phụ cấp" trong nhóm Thành viên. Test: `tests/Feature/Admin/AllowanceTest.php`.
- **CustomerList**: cột + ô chọn "Người tìm ra khách" (chỉ khi `canAssignOwners`; bỏ trống khi tạo = người phụ trách, bỏ trống khi sửa = giữ nguyên). Test trong `StaffAccessTest`.
- Test mới `tests/Feature/Admin/PayrollLeaveCommissionTest.php`: đơn nghỉ đã duyệt ghép vào chấm công (bỏ CN, giữ ngày chấm tay); hoa hồng đã chốt gắn vào lương, `netSalaryVnd` có cộng; lương đã trả thì không gắn.
- Đã xem trên trình duyệt ở 1600 và 1900px: trang Phụ cấp, cột và hộp sửa "Người tìm ra khách". Không có lỗi console.
- Backup: `C:\xampp\backups\tdk-source-20261115-2356.zip` (656 file, không có vendor/node_modules/.env/public/hot/Claude outputs).

## 4. Còn tồn tại
1. Tab Thành viên hiện có các sub-tab: Nhân sự / Lương thưởng / Phụ cấp / Hoa hồng / Tổng HH theo thành viên / Chi tiết hoa hồng / Thanh toán tiền HH. Đề xuất–Duyệt nằm ở trang `approvals` riêng, chưa gộp vào tab.
2. DB local chưa có loại phụ cấp nào nên bảng "Mức theo thành viên" mới được kiểm bằng test, chưa xem trên trình duyệt với dữ liệu thật.
3. Tỷ giá hoa hồng trong bảng lương lấy **đúng ngày cuối kỳ** (`UsdtVndRate::getEffectiveUsdtToVnd`), không có thì dùng tỷ giá mặc định. Thiếu cả hai thì `commission_vnd` = 0.
4. `DEPLOY-TDK.md` chưa liệt kê migration ngày 14–15/11 (hoa hồng, phụ cấp, member_requests).

## 5. Bước tiếp theo
1. Hỏi người dùng có muốn gộp Đề xuất–Duyệt vào tab Thành viên không.
2. Bổ sung danh sách migration mới vào `DEPLOY-TDK.md` trước khi deploy.
3. Deploy: dùng bản backup mới nhất, trên server **không** để `public/hot`.

## 6. Ghi chú kỹ thuật
- Sao lưu: `C:\xampp\backups\tdk-source-20261114-0016.zip` (mới nhất), `tdk-htdocs-20261113-2102.zip`. Chưa có bản nào sau 14/11.
- Dev server dùng `public/hot` (`http://primevue-breeze-inertia.localhost:5173`). Chạy `npx vite build` để cập nhật `public/build`.
- Test dùng database `testing` (phpunit).
- Tiền tính bằng bcmath. `App\Support\Money::round` là half-up.
- Công cụ kiểm tra (chỉ đọc): `scripts/tdk-audit/{audit-finance,snapshot,diff}.php`. Chụp snapshot trước và sau mọi thay đổi về tiền.
- PowerShell 5.1:
  - Ghi file PHP bằng Write tool, hoặc `[IO.File]::WriteAllText` với UTF-8 không BOM.
  - **Không đặt tên hàm `R`** vì trùng alias Invoke-History.
  - Backtick trong chuỗi `"..."` bị hiểu là escape.
- Thông tin đăng nhập test local nằm trong `Claude outputs/tdk-local-login.txt`. Không lặp lại nội dung và không đưa vào gói deploy.
- Gói deploy không kèm `.env`, `public/hot`, `node_modules`, `vendor`, `Claude outputs`.
- Phải hỏi người dùng trước khi sửa dữ liệu tiền đang lưu trong DB.

## 7. Cập nhật 16/11/2026
- Chuông thông báo cho admin/NV, khách, đối tác: bảng `notifications`, `App\Support\AppNotifier`, `Components/NotificationBell.vue`. Link lưu dạng path tương đối, ghép `url()` khi trả về.
- Rút tiền chuyển khoản cần chứng từ khi duyệt (`payment_proof_path`), chặn đề xuất rút vượt số dư.
- Rà soát nhập liệu: tỷ giá phải > 0 (tỷ giá ≤ 0 bị coi như chưa có); % hoa hồng thành viên ≤ 100; sửa NV mà để trống ví thì giữ nguyên ví; khấu trừ lương ≤ lương + phụ cấp + thưởng; ngày chi tiêu khách/đối tác và ngày đề xuất chi tiêu không được ở tương lai; link cũ admin/partner-wallet chuyển đúng sang công nợ đối tác.
- Deploy: 4 migration mới 2026_11_16_100000..130000, `npm run build`, max_allowed_packet=64M. Test: 216 pass.