App 4 – Ghi giờ theo dự án & Timesheet

Hướng: Xây mới bằng builder · Đợt: Đợt 2 · Phụ thuộc: hrm (đợt 0), App 6
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: nhân viên ghi giờ làm theo dự án/task bằng đồng hồ trên web hoặc nhập tay, gộp theo kỳ thành timesheet để quản lý duyệt; giờ đã duyệt là đầu vào cho lương và hóa đơn. Chụp màn hình và đo bàn phím/chuột của Desktop Timer nằm ngoài phạm vi (xem mục cuối). Nguồn: Time Tracking, Timesheets, Timesheet Management, Daily Plans.

Hướng: xây mới. hrm có chấm công theo ca (check-in/out, ca làm, tăng ca); app này ghi giờ theo dự án/task để tính chi phí và xuất hóa đơn, không thay chấm công ca. Nhân viên và phòng ban lấy từ hrm qua sự kiện.

Vai trò & quyền

Vai trò	Được làm
Quản trị	Cấu hình kỳ timesheet và các quy tắc; xem mọi timesheet
Quản lý	Xem giờ và timesheet của phòng ban; duyệt hoặc từ chối kèm bình luận; xem kế hoạch ngày của team
Nhân viên	Bấm giờ, nhập tay, sửa/xóa giờ của mình khi timesheet chưa nộp; nộp timesheet; lập kế hoạch ngày

Dữ liệu

Thực thể	Trường	Ghi chú
Giờ làm (time log)	nhân viên, dự án, task, bắt đầu, kết thúc, thời lượng (giây, tự tính), loại (Đồng hồ, Nhập tay), mô tả, tính phí khách (đúng/sai), đang chạy (đúng/sai), lý do (khi nhập tay)	Dự án và task tham chiếu App 6
Timesheet	nhân viên, từ ngày, đến ngày, tổng giờ (tự tính), giờ tính phí (tự tính), trạng thái, người duyệt, thời điểm duyệt, bình luận	Một timesheet mỗi nhân viên mỗi kỳ
Cấu hình	kỳ (Tuần thứ Hai–Chủ nhật, 2 tuần, Tháng), cho phép nhập tay, bắt buộc chọn dự án, bắt buộc chọn task, bắt buộc ghi lý do khi nhập tay, số giờ tối thiểu/tối đa mỗi ngày, tự nộp cuối kỳ	Một bản ghi cho cả tổ chức
Kế hoạch ngày	nhân viên, ngày, trạng thái (Mở, Đang làm, Hoàn thành), danh sách task kèm giờ ước lượng và thứ tự

Trạng thái timesheet

Trạng thái	Ai chuyển sang
Nháp	Tự tạo khi có giờ đầu tiên trong kỳ
Chờ duyệt	Nhân viên nộp (hoặc tự nộp cuối kỳ)
Đã duyệt	Quản lý
Từ chối	Quản lý, bắt buộc bình luận; nhân viên sửa rồi nộp lại (về Chờ duyệt)

Quy tắc nghiệp vụ

1. Mỗi nhân viên chỉ có tối đa một đồng hồ đang chạy; bấm bắt đầu khi đã có đồng hồ chạy thì từ chối.
2. Hai khoảng giờ của cùng một nhân viên không được chồng nhau.
3. Kết thúc phải sau bắt đầu; không nhập giờ ở tương lai.
4. Tôn trọng cấu hình: bắt buộc dự án/task, chặn nhập tay nếu tắt, bắt buộc lý do khi nhập tay.
5. Tổng giờ một ngày không vượt số giờ tối đa/ngày.
6. Timesheet đã nộp hoặc đã duyệt thì không sửa, xóa, thêm giờ vào kỳ đó.
7. Quản lý không duyệt timesheet của chính mình; chỉ duyệt nhân viên trong phòng ban.
8. Hoàn thành một task trong kế hoạch ngày không tự đổi trạng thái task bên App 6 (bản đầu); task chưa xong có thể chuyển sang ngày sau.

Màn hình

Màn hình	Nội dung
Đồng hồ	Chọn dự án, task, mô tả; Bắt đầu/Dừng; tổng giờ hôm nay
Giờ của tôi	Danh sách theo ngày; Thêm giờ tay; sửa/xóa
Timesheet tuần	Lưới ngày × dự án với tổng hàng/cột; nút Nộp
Duyệt timesheet	Danh sách chờ duyệt của phòng; xem chi tiết; Duyệt/Từ chối (hàng loạt được)
Kế hoạch ngày	Kéo task vào ngày, giờ ước lượng, so với giờ thực tế; xem kế hoạch team
Báo cáo giờ	Lọc theo nhân viên, dự án, khoảng ngày; tổng giờ, giờ tính phí; xuất CSV

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: giờ làm, timesheet, duyệt

Tôi cần app ghi giờ làm theo dự án và timesheet, 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 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.
Dự án và task tạm lưu bảng tham chiếu chỉ đọc (mã, tên), có dữ liệu mẫu.
Dữ liệu: giờ làm (nhân viên, dự án, task, bắt đầu, kết thúc, thời lượng tự tính,
loại đồng hồ hoặc nhập tay, mô tả, tính phí khách, lý do khi nhập tay), timesheet
theo tuần (nhân viên, từ ngày, đến ngày, tổng giờ, giờ tính phí, trạng thái
Nháp/Chờ duyệt/Đã duyệt/Từ chối, người duyệt, bình luận), cấu hình (cho phép nhập
tay, bắt buộc dự án, bắt buộc task, bắt buộc lý do khi nhập tay, giờ tối đa mỗi ngày).
Phân quyền: nhân viên ghi và xem giờ của mình, nộp timesheet; quản lý xem và duyệt
timesheet của phòng mình, không tự duyệt của mình; quản trị sửa cấu hình.
Quy tắc (kiểm tra ở API): mỗi người chỉ một đồng hồ đang chạy; các khoảng giờ của
một người không chồng nhau; kết thúc sau bắt đầu, không nhập giờ tương lai; không
vượt giờ tối đa mỗi ngày; tôn trọng cấu hình; timesheet đã nộp hoặc đã duyệt thì
không thêm, sửa, xóa giờ trong kỳ; từ chối phải có bình luận, nhân viên sửa rồi
nộp lại.
Màn hình: đồng hồ bấm giờ, giờ của tôi, timesheet tuần dạng lưới ngày × dự án có
nút Nộp, màn duyệt timesheet của phòng.

Lượt 2 – Kế hoạch ngày

Thêm kế hoạch ngày: nhân viên, ngày, trạng thái Mở/Đang làm/Hoàn thành, danh sách
task kèm giờ ước lượng và thứ tự. Nhân viên lập kế hoạch của mình; quản lý xem kế
hoạch của phòng. So sánh giờ ước lượng với giờ thực tế đã ghi; task chưa xong có
nút chuyển sang ngày sau.

Lượt 3 – Báo cáo

Thêm màn báo cáo giờ: lọc theo nhân viên, dự án, khoảng ngày; tổng giờ và giờ tính
phí; quản lý chỉ thấy nhân viên phòng mình; xuất CSV. Tổng tính ở API.

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

Phát sự kiện qua Redis Streams khi giờ làm được tạo, sửa, xóa và khi timesheet
được duyệt (mã giờ làm, nhân viên, dự án, task, bắt đầu, kết thúc, thời lượng, tính
phí khách, đã duyệt), để app hóa đơn và app dự án đồng bộ.

Lượt 5 (sau khi App 6 xong) – Nối dự án thật

Thay bảng tham chiếu dự án và task bằng dữ liệu đồng bộ từ sự kiện của app dự án
(dự án và task) vào bảng chỉ đọc; giữ nguyên các giờ đã ghi và liên kết của chúng.

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:

• [ ] Bấm Bắt đầu khi đồng hồ khác đang chạy thì bị từ chối.
• [ ] Nhập hai khoảng giờ chồng nhau thì bị từ chối ở API.
• [ ] Timesheet đã nộp: thêm, sửa, xóa giờ trong kỳ đều bị từ chối.
• [ ] Quản lý phòng A không thấy và không duyệt được timesheet của phòng B, không tự duyệt của mình.
• [ ] Checklist chung trong 00-tong-quan.md (mục Checklist chung trước khi Publish).