Ladaer.BackEnd

Tài khoản quảng cáo đồng bộ từ nền tảng về. Không có endpoint tạo tay: tài khoản luôn kéo từ nền tảng để ExternalId chắc chắn đúng.

Danh sách tài khoản quảng cáo

Chi tiết một tài khoản quảng cáo

Danh sách tài khoản của một kết nối — dùng cho dropdown chọn tài khoản

Kéo danh sách tài khoản từ nền tảng về (upsert theo ExternalId)

Bật/tắt việc đưa tài khoản vào các job đồng bộ định kỳ

Đổi giá thầu hàng loạt cho nhóm quảng cáo và từ khoá. Cả hai endpoint đều đòi Ads.Publish, kể cả preview: bản xem trước gọi thật ra nền tảng bằng validate_only nên vẫn tốn quota và vẫn để lại dấu vết trên tài khoản quảng cáo. Quyền không gộp theo "đọc/ghi" mà theo "có chạm nền tảng hay không" (plan §1.2, bài học set-bid-modifier). Luồng bắt buộc ba bước: chọn dòng → preview (nền tảng chỉ kiểm tra, LADA không ghi gì) → gõ chữ xác nhận rồi apply. apply ghi lên nền tảng trước, thành công mới ghi giá mới vào LADA.

Xem trước lô đổi giá thầu: bảng cũ → mới từng dòng, dòng bỏ qua kèm lý do. Không ghi gì vào LADA, không sửa gì trên nền tảng.

Ghi thật lô đổi giá thầu lên nền tảng. Ghi nền tảng trước, thành công mới ghi vào LADA.

Chiến dịch quảng cáo: soạn nháp trong LADA và đẩy lên nền tảng. Quyền được tách theo mức rủi ro: Ads.Search để xem, Ads.Create/Ads.Update để soạn nháp, còn Ads.Publish cho mọi thao tác làm phát sinh chi phí thật trên nền tảng.

Danh sách chiến dịch

Chi tiết chiến dịch kèm nhóm quảng cáo và số liệu tổng hợp. Không truyền khoảng ngày thì lấy 30 ngày gần nhất.

Lưu cả cây chiến dịch nháp (chiến dịch → nhóm → mẫu quảng cáo → targeting). Chỉ ghi vào LADA, không gọi ra nền tảng nên không phát sinh chi phí.

Xoá mềm chiến dịch trong LADA (chiến dịch đã lên nền tảng phải xoá bên đó trước)

Kéo chiến dịch của một tài khoản từ nền tảng về

Kéo cả chiến dịch và nhóm quảng cáo của một tài khoản

Kéo nhóm quảng cáo của một chiến dịch

Thông tin cho hộp thoại xác nhận trước khi đẩy: tài khoản bị trừ tiền, ngân sách, thời gian chạy, ước tính chi phí tối đa, danh sách lỗi/cảnh báo. Chỉ đọc dữ liệu nên không cần quyền publish.

Kiểm tra trước khi đẩy (dry-run): nền tảng validate toàn bộ nhưng không tạo gì thật.

Đẩy chiến dịch lên nền tảng. Luôn tạo ở trạng thái tạm dừng — người dùng tự bật sau khi đã tự kiểm tra trên nền tảng.

Đẩy thay đổi của chiến dịch nháp lên nền tảng

Tạm dừng chiến dịch trên nền tảng

Bật chạy chiến dịch trên nền tảng — từ đây quảng cáo bắt đầu tiêu tiền

Bật / tạm dừng nhiều chiến dịch trong một lượt. Gọi tuần tự đúng logic của bản lẻ (nguyên tắc §1.6 — không song song), trả kết quả từng dòng. Chiến dịch đã ở trạng thái đích hoặc chưa đẩy lên nền tảng thì bỏ qua, không tính là lỗi. Lô bị từ chối trước khi chạy (Id lạ, quá trần) là 400; lô đã chạy — kể cả có dòng thất bại — là 200 kèm bảng kết quả.

Đổi trạng thái một nhóm quảng cáo trên nền tảng

Đổi trạng thái một quảng cáo trên nền tảng

Đổi ngân sách theo ngày của chiến dịch đã có trên nền tảng. Đây là thao tác đổi trực tiếp số tiền tiêu mỗi ngày nên cần quyền publish.

Cấu hình kết nối tới nền tảng quảng cáo (credentials, OAuth, kiểm tra kết nối). Toàn bộ endpoint đụng tới credential yêu cầu quyền Ads.Connection — đây là chỗ nắm chìa khoá tiêu tiền nên tách riêng khỏi quyền xem báo cáo.

Danh sách kết nối

Chi tiết một kết nối (credential đã được che)

Năng lực của một nền tảng — UI render form credential động từ đây

Năng lực của mọi nền tảng đã khai báo adapter

Tạo mới hoặc cập nhật kết nối

Xoá mềm kết nối

Lấy liên kết cấp quyền OAuth để người dùng bấm vào

Callback OAuth do nền tảng gọi tới. Không yêu cầu đăng nhập vì trình duyệt được nền tảng chuyển hướng sang, không mang theo JWT — chống CSRF bằng tham số state đã ký.

Kiểm tra kết nối bằng một lệnh gọi nhẹ tới nền tảng

Mẫu quảng cáo (creative) và cầu nối từ nội dung website sang quảng cáo. Toàn bộ endpoint ở đây chỉ ghi vào LADA — không có endpoint nào gọi ra nền tảng, nên không cần quyền Ads.Publish.

Danh sách mẫu quảng cáo

Chi tiết một mẫu quảng cáo

Tạo mới hoặc cập nhật mẫu quảng cáo

Xoá mềm mẫu quảng cáo (mẫu đang được dùng thì không xoá được)

Giới hạn mẫu quảng cáo của một nền tảng — form dùng để đếm ký tự realtime.

Kiểm tra mẫu theo giới hạn nền tảng mà không cần lưu — dùng cho nút "Kiểm tra" trên form.

Gợi ý mẫu quảng cáo từ một nội dung AI Marketing đã duyệt. SaveAsCreative = false thì chỉ trả gợi ý cho wizard, chưa lưu gì.

Gợi ý mẫu quảng cáo từ một bài viết CMS đã xuất bản. URL bài viết thành Final URL.

Đọc nhóm quảng cáo và các quảng cáo bên trong nó. Toàn bộ controller này chỉ đọc, nên mọi endpoint chỉ cần Ads.Search. Bật/tắt một quảng cáo hay một nhóm là thao tác tiêu tiền và đã có sẵn ở api/ads/campaign/ad/{adId}/status và api/ads/campaign/group/{groupId}/status (quyền Ads.Publish) — cố ý không làm lại ở đây để chỉ có một đường ghi trạng thái. Đồng bộ quảng cáo từ nền tảng về cũng chỉ đọc: nó ghi vào bảng của LADA, không thay đổi gì trên tài khoản quảng cáo thật.

Danh sách nhóm quảng cáo có phân trang, kèm số đếm quảng cáo / từ khoá.

Chi tiết một nhóm: thông tin nhóm, bối cảnh chiến dịch / tài khoản, và năng lực nền tảng. UI dùng các cờ năng lực để ẩn hẳn tab không dùng được, không hiện tab rỗng — tab rỗng đọc thành "chưa cấu hình gì", trong khi thật ra nền tảng không có khái niệm đó.

Danh sách quảng cáo trong nhóm kèm số liệu gộp trong khoảng ngày (mặc định 30 ngày gần nhất). Quảng cáo có IsManagedByLada = false là quảng cáo đồng bộ về từ nền tảng — LADA không quản mẫu của nó nên chỉ đọc được, đó không phải bản ghi lỗi. Metrics = null nghĩa là chưa đồng bộ số liệu cấp quảng cáo, khác hẳn với "đã đồng bộ và mọi số bằng 0" — UI phải hiển thị hai trạng thái này khác nhau.

Số liệu tổng hợp của nhóm trong khoảng ngày (mặc định 30 ngày gần nhất).

Kéo quảng cáo của cả chiến dịch chứa nhóm này từ nền tảng về LADA. Chỉ đọc — không thay đổi gì trên tài khoản quảng cáo, nên quyền chỉ cần Ads.Search. Đồng bộ theo chiến dịch chứ không theo từng nhóm: nền tảng trả quảng cáo của cả chiến dịch trong một lượt gọi, tách ra từng nhóm chỉ tốn quota gấp số nhóm lần mà không thu thêm thông tin nào.

"Việc cần xử lý" của phân hệ quảng cáo — panel gộp theo loại trên trang Chiến dịch (plan §3.4). Quyền: Ads.Search để xem; Ads.Update để bỏ qua (dismiss) / hiện lại (undismiss) — bỏ qua chỉ ghi AdsIssueDismissal, không chạm dữ liệu đồng bộ. Hành động chính của từng loại (kéo lịch về, đồng bộ tài khoản, đồng bộ số liệu) nằm ở controller của nghiệp vụ đó với đúng bó quyền của nó. Lỗi ngoài dự kiến trả thông điệp trung tính, chi tiết vào log — không lặp nếp BadRequest(ex.Message) (sổ nợ N-22).

Danh sách việc đã gộp theo loại, mỗi loại kèm số đếm đã trừ bỏ qua và tối đa 200 mục chi tiết. Bỏ trống bộ lọc = toàn hệ thống.

Bỏ qua một lô mục cùng loại trong N ngày (mặc định 30). Có Id không tồn tại hoặc không còn thuộc loại đó là 400 cả lô, không âm thầm bỏ phần lạ. Tối đa 500 Id.

Hiện lại các mục đã bỏ qua của một loại. Bỏ trống EntityIds = hiện lại tất cả. POST chứ không DELETE-có-thân: thân của DELETE bị một số proxy/WAF bỏ, và repo chưa có tiền lệ nào chạy thật qua production với kiểu đó.

Từ khoá và từ khoá phủ định của chiến dịch / nhóm quảng cáo. Sửa từ khoá là đổi cấu hình đang tiêu tiền, nên luồng ghi chia ba bước tách biệt giống lịch chạy: (1) sửa nháp trong LADA (create-or-update, create-bulk, DELETE) — không gọi ra nền tảng, không tốn đồng nào; (2) xem trước (preview-apply) — nền tảng kiểm tra cả lô bằng validate_only, không ghi gì; (3) đẩy thật (apply) — ghi lên nền tảng rồi đọc lại để xác nhận. Quyền: Ads.Search để xem và để đồng bộ về (chỉ đọc); Ads.Update / Ads.Delete cho việc sửa nháp trong LADA; Ads.Publish cho mọi thứ gọi ra nền tảng — kể cả preview-apply, vì nó tốn quota API thật. Xoá từ khoá phủ định là thao tác nguy hiểm nhất ở đây: nó mở cửa cho truy vấn rác tiêu tiền ngay khi được đẩy lên, mà không có gì báo. UI phải bắt gõ từ khoá xác nhận trước khi gọi apply nếu lô có dòng xoá phủ định — số dòng đó nằm ở NegativeRemoveCount trong kết quả preview-apply. Danh sách phủ định rỗng nghĩa là không loại trừ truy vấn nào, không phải "chưa cấu hình". Ngoài ra LADA chưa đọc danh sách phủ định dùng chung (shared set) của nền tảng — xem SharedSetNote trong kết quả đọc.

Danh sách từ khoá có phân trang, lọc theo chiến dịch / nhóm / nền tảng / kiểu khớp. Không gửi isNegative = lấy cả hai loại. Gửi true/false mới lọc.

Bối cảnh của một phạm vi từ khoá — không kèm danh sách: năng lực nền tảng, trạng thái publish, có thay đổi chưa đẩy hay không, và số lượng từng loại. Đây là thứ màn hình danh sách gọi, cặp với search phân trang. Bỏ trống groupId = phạm vi cấp chiến dịch (phủ định cấp chiến dịch).

Từ khoá của một chiến dịch: từ khoá phủ định cấp chiến dịch cùng từ khoá của mọi nhóm, kèm bối cảnh hiển thị (nền tảng có khái niệm từ khoá không, có dry-run không, giới hạn số từ khoá mỗi nhóm). Không phân trang — trả về mọi dòng của chiến dịch. Màn hình danh sách phải dùng search + context thay cho endpoint này.

Từ khoá của riêng một nhóm quảng cáo. Từ khoá phủ định cấp chiến dịch cố ý không trộn vào đây: trộn vào thì người dùng tưởng xoá ở đây là hết ảnh hưởng, trong khi nó áp cho mọi nhóm khác của chiến dịch. Không phân trang — xem ghi chú ở by-campaign.

Kéo từ khoá từ nền tảng về LADA. Chỉ đọc — dữ liệu trên tài khoản quảng cáo thật không bị thay đổi, nên quyền chỉ cần Ads.Search. Từ khoá thuộc nhóm chưa đồng bộ về LADA bị bỏ qua và đếm riêng (SkippedCount) — nếu số đó khác 0 thì danh sách đang xem CHƯA đủ.

Thêm / sửa một từ khoá trong LADA (bản nháp). Không gọi ra nền tảng, không phát sinh chi phí — thay đổi chỉ có hiệu lực sau khi đẩy lên. Bỏ trống AdsGroupId = từ khoá phủ định cấp chiến dịch. Bỏ trống mà IsNegative = false sẽ bị từ chối chứ không tự đổi cấp.

Thêm nhiều từ khoá một lượt bằng danh sách dán vào — mỗi dòng một từ khoá. Không gọi ra nền tảng. Cả lô cùng vào hoặc cùng đứng: có lỗi thì không thêm dòng nào, để không để lại danh sách nửa vời. Dòng trắng, dòng trùng trong lô và dòng đã có sẵn được báo rõ số lượng trong thông báo, không âm thầm bỏ.

Xoá một từ khoá trong LADA (soft-delete). Không gọi ra nền tảng. Từ khoá đã có trên nền tảng vẫn đang chạy tới khi người dùng đẩy lên — với từ khoá phủ định thì nghĩa là truy vấn vẫn đang bị loại trừ. Thông báo trả về nói rõ điều này; UI phải hiện nguyên văn, đừng rút gọn thành "đã xoá".

Xem trước những gì sẽ ghi lên nền tảng: so từ khoá trong LADA với từ khoá trên nền tảng rồi nhờ nền tảng kiểm tra cả lô bằng validate_only. Không ghi gì lên tài khoản quảng cáo. Bỏ trống groupId = lô từ khoá phủ định cấp chiến dịch. Một lần gọi chỉ xử lý một phạm vi — nhóm hoặc cấp chiến dịch, không trộn. Quyền Ads.Publish vì nó gọi ra nền tảng thật (tốn quota API). Nền tảng không có dry-run thì endpoint này báo lỗi, tuyệt đối không âm thầm ghi thật.

Đẩy từ khoá lên nền tảng thật. Việc này tiêu tiền: từ khoá mới bắt đầu chạy ngay, và từ khoá phủ định bị xoá thì truy vấn tương ứng lập tức tiêu tiền trở lại. UI phải hiện hộp xác nhận nêu rõ từng thay đổi trước khi gọi endpoint này, và bắt gõ từ khoá xác nhận khi lô có dòng xoá phủ định (NegativeRemoveCount > 0 ở bước xem trước). Sau khi ghi, service đọc lại từ khoá từ nền tảng và trả về danh sách đã đọc lại — UI hiển thị danh sách đó, không hiển thị thứ vừa gửi lên.

Cờ hiển thị cho giao diện của phân hệ Quảng cáo — "tôi được thấy nút nào".

Endpoint này cố ý không đòi role nào (chỉ cần đăng nhập): người không có quyền gì vẫn phải hỏi được và nhận về toàn false để giao diện ẩn nút. Gác nó bằng một role là dựng lại đúng lỗi nó sinh ra để chữa (rule quyen-hien-thi mục 4). Luật nằm ở hàm thuần , controller chỉ hỏi role rồi chuyển tiếp.

Cờ hiển thị nút của phân hệ quảng cáo cho người đang đăng nhập

Số liệu quảng cáo và log gọi nền tảng. Chi phí luôn kèm mã tiền tệ của tài khoản — frontend hiển thị theo mã đó, không quy đổi.

Kéo số liệu theo ngày của một tài khoản trong khoảng ngày

Số liệu tổng hợp của một chiến dịch / nhóm / quảng cáo

Số liệu tổng hợp của cả một tài khoản quảng cáo

Log gọi nền tảng — màn hình debug của module

Số liệu tổng quan toàn hệ thống kèm kỳ liền trước để so sánh tăng/giảm.

Số liệu đã về tới ngày nào và đồng bộ lần cuối lúc nào — thanh ngữ cảnh của phân hệ hiện "Số liệu đến …" và tô cảnh báo khi số đã cũ. Không nhận khoảng ngày.

Chuỗi số liệu theo thời gian để vẽ biểu đồ.

Số liệu gộp theo từng nền tảng quảng cáo.

Xếp hạng chiến dịch theo chi phí (mặc định) hoặc chỉ số khác.

Đồng bộ số liệu ngay cho mọi tài khoản đang bật đồng bộ định kỳ. Yêu cầu quyền Ads.Publish vì có gọi ra nền tảng bên ngoài.

Dựng bộ lọc chung và chặn khoảng ngày không hợp lệ ngay tại cửa ngõ.

Lịch chạy quảng cáo (ad schedule) của chiến dịch. Luồng sửa lịch chia làm ba bước tách biệt vì sửa lịch là đổi giá thầu — tiêu tiền thật: (1) sửa bản nháp trong LADA (create-or-update, DELETE, set-bid-modifier) — không gọi ra nền tảng; (2) xem trước (preview-apply) — nền tảng kiểm tra bằng validate_only, không ghi gì; (3) đẩy thật (apply). Quyền: Ads.Search để xem; Ads.Update / Ads.Delete cho việc sửa nháp trong LADA; Ads.Publish cho mọi thứ liên quan tới tiền và tới nền tảng — bao gồm cả set-bid-modifier (đổi giá thầu là chuyện tiền) và preview-apply (gọi ra nền tảng thật). Danh sách khung giờ rỗng nghĩa là chiến dịch chạy cả tuần 24/7, không phải "không chạy".

Lịch của một chiến dịch kèm bối cảnh hiển thị (múi giờ tài khoản, đã publish chưa, nền tảng có cho sửa lịch không, chiến lược đặt giá có áp dụng % giá thầu không). Danh sách rỗng nghĩa là chiến dịch chạy cả tuần 24/7, không phải "không chạy".

Kéo lịch từ nền tảng về LADA. Chỉ đọc từ nền tảng — dữ liệu trên tài khoản quảng cáo thật không bị thay đổi.

Kéo lịch từ nền tảng về cho nhiều chiến dịch — chỉ đọc, không đổi gì trên tài khoản quảng cáo; xong mỗi chiến dịch thì dò lệch lại để cờ "lệch với nền tảng" tắt. Tuần tự, một chiến dịch lỗi không giết lô, kết quả từng dòng. Tối đa 500 Id; có Id không tồn tại là 400 cả lô (plan §3.9).

Dò lệch lịch của một chiến dịch ngay lập tức, không chờ job chạy đêm. Chỉ đọc từ nền tảng rồi đánh dấu nếu lệch — không sửa lịch ở bất kỳ phía nào.

Chạy tay lượt dò lệch lịch trên toàn bộ chiến dịch đã đẩy lên nền tảng — đúng việc mà job ads-schedule-reconcile làm mỗi đêm. Gọi ra nền tảng một lần cho mỗi chiến dịch nên tốn quota API. Chỉ dùng khi cần kiểm tra ngay, còn lại để job tự chạy. Quyền Ads.Publish vì đây là thao tác nặng, dù nó không ghi gì lên nền tảng.

Tạo / sửa một khung giờ trong LADA (bản nháp). Không gọi ra nền tảng, không phát sinh chi phí — thay đổi chỉ có hiệu lực sau khi bấm đẩy lên.

Xoá một khung giờ trong LADA (soft-delete). Không gọi ra nền tảng: khung giờ đã có trên nền tảng vẫn còn chạy tới khi người dùng đẩy lịch lên.

Đặt / xoá % điều chỉnh giá thầu của một khung giờ trong LADA. Quyền Ads.Publish dù chỉ ghi vào DB LADA: đổi giá thầu là chuyện tiền, không nên để quyền sửa dữ liệu thường mở được cánh cửa này.

Hệ số theo dạng nền tảng (1.2 = +20%, 0.5 = -50%). Bỏ trống / null = xoá điều chỉnh, khác hẳn 0. Frontend chịu trách nhiệm đổi từ "+20" mà người dùng gõ sang 1.2.

Xem trước những gì sẽ ghi lên nền tảng: so lịch LADA với lịch nền tảng rồi nhờ nền tảng kiểm tra cả lô bằng validate_only. Không ghi gì lên tài khoản quảng cáo. Quyền Ads.Publish vì nó gọi ra nền tảng thật (tốn quota API).

Đẩy lịch lên nền tảng thật. Việc này tiêu tiền: giá thầu theo khung giờ đổi ngay sau khi ghi. UI phải hiện hộp xác nhận nêu rõ từng thay đổi trước khi gọi endpoint này. Sau khi ghi, service đọc lại lịch từ nền tảng và trả về danh sách đã đọc lại — UI hiển thị danh sách đó, không hiển thị thứ vừa gửi lên.

Danh sách mẫu lịch áp nhanh (giờ hành chính, cuối tuần, 24/7…) kèm giới hạn số chiến dịch một lô. Định nghĩa mẫu nằm ở backend nên thêm/sửa mẫu không phải build lại frontend. Giới hạn lô trả kèm ở đây thay vì để frontend tự ghi hằng số — hai bản số lệch nhau thì UI sẽ cho chọn nhiều hơn mức backend nhận, người dùng chọn xong mới biết là quá.

Áp một mẫu lịch cho một chiến dịch — chỉ ghi nháp trong LADA, không gọi ra nền tảng. Thay toàn bộ lịch hiện tại. Quyền Ads.Publish (không phải Ads.Update) vì mẫu mang theo % giá thầu — cùng lý do với set-bid-modifier: đổi giá thầu là chuyện tiền.

% chung theo dạng hệ số Google (1.2 = +20%). Bỏ trống để dùng % của mẫu.

Áp một mẫu lịch cho nhiều chiến dịch một lượt. Một chiến dịch lỗi không làm chết cả lô — kết quả trả về nói rõ từng chiến dịch thành công / thất bại / bỏ qua kèm lý do. Chiến dịch chưa publish và tài khoản MCC được tính là bỏ qua, không phải thất bại. Luồng nên dùng trên UI: gọi với validateOnly = true để dry-run cả lô, người dùng đọc bảng kết quả, rồi mới gọi lại với validateOnly = false. Áp sai lịch cho hàng chục chiến dịch cùng lúc là sự cố tốn tiền.

REST quản trị của miền MCP số liệu (docs/plan-mcp-tra-cuu-so-lieu.md) — tool số liệu nằm ở endpoint MCP /analytics, không ở đây.

Ảnh chụp trạng thái triển khai MCP số liệu: phiên bản schema, cấu hình (cờ, không khoá), login chỉ đọc (đọc được analytics, bị lỗi 229 ở dbo), số dòng bảng analytics, lượt nạp từng chủ đề + mốc phủ, role Analytics.Read, client OAuth, số đo Việc 0.

Gác Founder như api/ContentStore/DeployCheck — thay cho mọi câu SQL tay trên production (ràng buộc 2026-08-27). Chỉ đọc, không tham số. Luật nằm ở ; controller trả thẳng kết quả.

Controller xử lý các hoạt động liên quan đến danh mục.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý danh mục.

Tìm kiếm các danh mục dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Lấy danh sách danh mục dưới dạng cây.

Từ khóa tìm kiếm. Danh sách danh mục dưới dạng cây.

Tạo hoặc cập nhật thông tin danh mục.

Model chứa thông tin danh mục. Kết quả của hoạt động tạo hoặc cập nhật.

Lấy thông tin chi tiết của một danh mục dựa trên ID.

ID của danh mục. Thông tin chi tiết của danh mục.

Xóa một danh mục dựa trên ID.

ID của danh mục. Kết quả của hoạt động xóa.

Controller cấu hình tính giá cho danh mục hàng hóa động

Tìm kiếm cấu hình danh mục hàng hóa

Lấy cấu hình theo Id (kèm thuộc tính và lựa chọn)

Tạo mới hoặc cập nhật cấu hình (kèm thuộc tính và lựa chọn)

Xóa cấu hình (xóa mềm kèm thuộc tính và lựa chọn)

Lấy cấu hình theo danh mục hàng hóa (nhân viên lên đơn cần đọc)

Lấy toàn bộ cấu hình đang bật

Controller xử lý các hoạt động liên quan đến bài viết.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý bài viết.

Tìm kiếm các bài viết dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tạo hoặc cập nhật bài viết.

Model chứa thông tin bài viết. Kết quả của hoạt động tạo hoặc cập nhật.

Lấy thông tin chi tiết của bài viết dựa trên ID.

ID của bài viết. Thông tin chi tiết của bài viết.

Nguồn cho ô "Bưu cục liên quan" của form Bài viết: chi nhánh LADA/nhượng quyền chưa xoá, kèm tên hiển thị và trạng thái công bố của hồ sơ bưu cục nếu có.

Gác đúng bó role của form Bài viết (Post.GetById để mở form sửa, Post.CreateOrUpdate để lưu) chứ không mượn nguồn bưu cục sẵn có: AgencyProfile/Lookups đòi AgencyProfile.*, Agency/GetTree đòi Agency.GetTree — người viết bài không có các role đó, ô chọn sẽ 403 và interceptor đá cả trang (rule quyen-hien-thi). Tập dòng trùng đúng tập mà bước lưu bài chấp nhận. Danh sách sắp theo tên.

Xóa một bài viết dựa trên ID.

ID của bài viết. Kết quả của hoạt động xóa.

Đăng bài viết.

Model chứa thông tin trạng thái bài viết. Kết quả của hoạt động đăng bài viết.

Từ chối bài viết.

Model chứa thông tin trạng thái bài viết. Kết quả của hoạt động từ chối bài viết.

Gửi bài viết chờ duyệt.

Model chứa thông tin trạng thái bài viết. Kết quả của hoạt động gửi bài viết chờ duyệt.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý sản phẩm.

Tìm kiếm các sản phẩm dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Lấy thông tin chi tiết của sản phẩm dựa trên ID.

ID của sản phẩm. Thông tin chi tiết của sản phẩm.

Bộ khối của trang dịch vụ — editor FE lấy loại khối được thêm và bộ icon cố định từ đây (không chép danh sách). Quyền như mở form dịch vụ.

.

Nguồn cho hai ô "Tỉnh đi / Tỉnh đến" của form Dịch vụ: tỉnh bộ 2 cấp + gợi ý đoán từ tên trang.

Gác đúng bó role của form Dịch vụ (Product.GetById để mở form sửa, Product.CreateOrUpdate để lưu) chứ không mượn nguồn tỉnh sẵn có: LoSug đòi Location.LocationSuggestion, AgencyProfile/Lookups đòi AgencyProfile.* — người soạn trang dịch vụ không có các role đó, ô chọn sẽ 403 và interceptor đá cả trang (rule quyen-hien-thi). Ai mở được form thì nạp được ô chọn, không hơn. Tên trang đang soạn; rỗng thì chỉ trả danh sách tỉnh, không đoán. .

Tạo hoặc cập nhật sản phẩm.

Model chứa thông tin sản phẩm. Kết quả của hoạt động tạo hoặc cập nhật.

Xóa một sản phẩm dựa trên ID.

ID của sản phẩm. Kết quả của hoạt động xóa.

Tìm kiếm cấu hình script

Lấy thông tin cấu hình script theo Id

Thêm hoặc cập nhật cấu hình script

Xóa cấu hình script

Tự động hoàn thành từ khóa tìm kiếm thẻ.

Từ khóa tìm kiếm. Danh sách các thẻ gợi ý.

Tìm kiếm các thẻ dựa trên tham số SmartTableParam.

Tham số tìm kiếm. Danh sách các thẻ phù hợp. Topic là nội dung một mục Cổng nhượng quyền (FranchisePortal.<Code>, hoặc đang được một mục trỏ tới) KHÔNG đi qua controller này với bất kỳ ai, kể cả Founder và người có role cổng: Search không liệt kê, đọc / lưu / xuất bản / xem trước trả như topic không tồn tại, xoá bị từ chối — cửa nằm trong . Nội dung cổng sửa ở FranchisePortalSectionController (role FranchisePortal.Content / Manage, đóng nợ CNQ-12 ở GĐ E).

Cờ hiển thị của màn sửa topic: CanSave (nút "Lưu lại"), CanUploadPicture (nút tải ảnh của khối), CanPublish (nút "Xuất bản"), CanPreview (nút "Xem trước"); và của danh sách topic: CanCreate (nút "Tạo topic"), CanDelete (mục "Xóa"). KHÔNG đòi role (rule quyen-hien-thi) — người không có quyền nhận cờ false.

Tìm kiếm các chủ đề dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Lấy thông tin chi tiết của chủ đề dựa trên ID.

ID của chủ đề. Thông tin chi tiết của chủ đề.

Id của topic theo tên hệ thống — menu tắt "Nội dung trang nhượng quyền" mở thẳng topic FranchiseLanding mà không ghi cứng Id (khác nhau giữa các DB). Không có → 0. Quyền như đọc topic.

Tên hệ thống, vd. FranchiseLanding.

Bộ khối của topic theo tên hệ thống — editor FE biết có hiện tab "Khối nội dung" không, được thêm loại khối nào, luật số lượng và bộ icon cố định (FE không chép danh sách). Không có bộ khối → Enabled = false. Quyền như đọc topic.

Tên hệ thống của topic, vd. FranchiseLanding.

Tạo hoặc cập nhật chủ đề.

Model chứa thông tin chủ đề. Kết quả của hoạt động tạo hoặc cập nhật.

Xuất bản khối nội dung đang sửa của topic: kiểm lại toàn bộ rồi chụp thành bản website in ra. Lưu topic (CreateOrUpdate) không đổi trang công khai — chỉ thao tác này mới đổi (plan nhượng quyền website §6.3).

Id của topic. Dấu DraftVersion của bản đang sửa người bấm đã thấy (từ GetById) — bắt buộc. Có người lưu khối sau đó thì không xuất bản (DraftChanged = true). TopicPublishResult; Failed kèm câu lỗi khi bản đang sửa chưa đạt luật xuất bản.

Cấp link xem trước bản ĐANG SỬA của topic trên website (hạn 30 phút; link cấp trước vẫn sống). Role như đọc topic: link chỉ cho xem đúng bản đang sửa mà người gọi đã đọc được qua GetById, để gửi người duyệt/chủ trang xem mà không cần tài khoản (plan nhượng quyền website §6.3).

Id của topic. TopicPreviewResult — Path trên website kèm token, ExpiresAt.

Xóa một chủ đề dựa trên ID.

ID của chủ đề. Kết quả của hoạt động xóa.

Lấy thông tin chi tiết của UrlRecord dựa trên ID.

ID của UrlRecord. Thông tin chi tiết của UrlRecord.

Tìm kiếm các UrlRecord dựa trên tham số SmartTableParam.

Tham số tìm kiếm. Danh sách các UrlRecord phù hợp.

Cập nhật thông tin cơ bản của UrlRecord.

Model chứa thông tin cập nhật. Kết quả cập nhật.

Màn hình "Chuyển hướng URL": khai luật 301/302 cho website công khai mà không phải deploy. Quyền tách làm hai mức theo hậu quả, không theo động từ HTTP. UrlRedirect.View cho hai lời gọi chỉ đọc — kể cả POST search, vốn là POST chỉ vì SmartTable gửi bộ lọc trong thân request. UrlRedirect.Manage cho hai lời gọi ghi: chúng đổi điều hướng của trang công khai trong vòng 5 phút (thời hạn cache của middleware bên website), không qua bước duyệt nào.

Danh sách luật chuyển hướng, có lọc và phân trang

Một luật để mở form sửa

Thêm hoặc sửa một luật chuyển hướng.

Danh tính người thực hiện lấy từ token, không lấy từ thân request. Hai trường UpdatedBy/UpdatedByUserName của model bị ghi đè ngay đầu hàm: chúng có trong model vì tầng service dùng chung khuôn với các màn CRUD khác, nhưng nhận giá trị do client gửi lên là để bất kỳ ai cũng ký tên người khác vào một thay đổi điều hướng công khai.

Xoá mềm một luật chuyển hướng

Xoá luật không bật lại cờ IncludeInSiteMap của bản ghi UrlRecord tương ứng — lý do đầy đủ nằm ở .

Cờ hiển thị cho màn hình "Chuyển hướng URL" — "tôi được thấy nút nào".

Endpoint này cố ý không đòi role nào (chỉ cần đăng nhập): người không có quyền gì vẫn phải hỏi được và nhận về toàn false để giao diện ẩn nút. Gác nó bằng một role là dựng lại đúng lỗi nó sinh ra để chữa — trang sẽ hiện nút cho người không bấm được, hoặc gãy vì lời gọi hỏi quyền lại bị 403. Luật nằm ở hàm thuần , controller chỉ hỏi role rồi chuyển tiếp (mẫu: SearchConsoleNavController).

Cờ hiển thị nút của màn hình chuyển hướng URL cho người đang đăng nhập

Luật "ai thấy gì" của màn hình Chuyển hướng URL.

Hàm thuần — không chạm database, không đọc HttpContext: nhận danh sách role đã phân giải qua IUserRoleResolver, trả các cờ. Controller thì không test được sạch vì User.GetCurrentUser() nuốt mọi ngoại lệ rồi trả UserId = 0. CanManage không kéo theo CanView. Hàng rào thật là các thuộc tính [Authorize(Roles = …)] trên UrlRedirectController: hai lời gọi đọc đòi đúng UrlRedirect.View. Một người chỉ được cấp UrlRedirect.Manage mà thấy trang mở ra sẽ ăn 403 ngay ở lời gọi nạp bảng, nên cờ phải soi đúng bó quyền nó gác chứ không mượn bó khác. Ở miền này khả năng lệch còn cao hơn miền đồng bộ tìm kiếm: hai quyền cố ý không được nối vào nhóm Permission nào (chủ dự án chốt 2026-09-15 "chỉ Founder"), nên mọi lần cấp về sau đều là gán tay — và gán tay thì lệch được.

Vai bỏ qua mọi kiểm tra role của hệ thống — ẩn nút của Founder là dựng hàng rào không có thật.

Role của hai lời gọi chỉ đọc: search, get-by-id.

Role của hai lời gọi đổi điều hướng công khai: create-or-update, delete.

Role đã phân giải qua IUserRoleResolver; null hoặc rỗng = không có role nào

Cờ hiển thị của màn hình Chuyển hướng URL — mỗi cờ gác đúng một bó quyền (xem )

Cờ hiển thị của màn hình Chuyển hướng URL — mỗi cờ gác đúng một bó quyền (xem )

Trang đăng nhập + đồng ý của authorization server OAuth 2.1 cho MCP (plan §3.4, §7.2): người dùng đăng nhập bằng tài khoản LADA, xem client nào xin quyền gì, bấm đồng ý → OpenIddict cấp mã uỷ quyền. Endpoint token / revocation / metadata do OpenIddict tự phục vụ (không passthrough). Không nằm dưới /api nên không qua FrontendOriginMiddleware.

Hai luật không có đường vòng: tài khoản Founder không được cấp quyền cho trợ lý AI (plan §7.4d) và tài khoản phải có role MCP — lúc đăng nhập: ≥ 1 role ContentStore.* hoặc Analytics.*; lúc đồng ý: role của ĐÚNG mặt MCP mà resource xin (). Một issuer phục vụ hai mặt (/mcp kho nội dung, /analytics số liệu), nên token chỉ mang scope thuộc resource đã xin — scope không lọt chéo. là nửa dành cho người của hợp đồng MCP: nó nói bằng tiếng Việt thứ mà token sắp cấp cho phép làm. Nửa dành cho máy là + mô tả từng tool. Mở rộng quyền của một scope thì sửa nhãn ở đây trong cùng commit, không thì người bấm "Đồng ý" đang đồng ý với một câu đã cũ.

Tham số OAuth được chép lại thành input ẩn của form đồng ý — danh sách cố định, để tham số lạ trong URL (ví dụ kẻ xấu chèn decision=accept vào link authorize gửi nạn nhân) không lọt vào form.

Trang từ chối theo MÃ lý do (không phản chiếu chuỗi tự do từ URL lên trang mang thương hiệu LADA).

Mọi trang /connect không được nhúng trong khung (chống clickjacking trang đồng ý).

Chỉ nhận đường dẫn cục bộ trỏ về /connect/authorize; còn lại về trang từ chối.

Lý do không cho ĐĂNG NHẬP trang OAuth; null nếu được. Lúc này chưa đọc resource của yêu cầu nên chỉ đòi "có role MCP nào đó" — role đúng mặt kiểm ở bước đồng ý ().

Resource + scope sẽ cấp cho yêu cầu này, hoặc lý do từ chối ().

Đăng ký client động (RFC 7591) POST /connect/register — Claude.ai / Cowork / ChatGPT gọi khi người dùng thêm connector. Ẩn danh theo RFC nhưng bị giới hạn 10 lần/phút/IP và redirect URI phải thuộc allowlist.

Endpoint này chỉ cấp danh tính cho client, không mang một luật nội dung nào. Thứ trợ lý AI đọc để biết viết bài thế nào là + mô tả từng tool, trả ở initialize và tools/list sau khi đã có token.

Quản lý token truy cập cá nhân (PAT) cho MCP — quản trị tạo hộ user, thu hồi, xem danh sách. Chuỗi token chỉ trả về một lần ở Create. Toàn bộ cần role ContentStore.ManageToken.

Tạo token cho một user — 201 kèm Data.PlainToken (chỉ lần này); 400 khi user là Founder / thiếu role / scope sai.

Danh sách token (không có chuỗi/hash); mặc định ẩn token đã thu hồi.

Thu hồi token — 200 (gọi lại token đã thu hồi cũng 200 kèm cảnh báo); 404 khi không có.

Bài viết trong kho nội dung AI (GĐ A: tạo nháp, đọc, tìm, render). Body trả về luôn là nguyên vẹn — kể cả khi thành công — để client luôn có Warnings; HTTP status suy từ mã lỗi qua .

Số liệu trong bài (hợp đồng 0.2, từ 2026-09-12): thân bài viết trọn, không còn ô chờ [[CẦN …]]; khoản nào chưa có số thì nằm ở Brief.DataNeeded, còn cả bài chờ số thì để trạng thái needs_data kèm lý do. Bài cũ còn sót chuỗi đó vẫn lưu và vẫn đăng được, chỉ kèm cảnh báo LEGACY_PLACEHOLDER và bị dọn khỏi bản gửi sang CMS. Câu chữ mà trợ lý AI đọc nằm ở Infrastructures/Mcp/McpServerContract.cs — sửa hành vi thì sửa cả hai trong một commit.

Tạo bản nháp bài 4 phần — 201 khi thành công; 400/404/409/413/422 theo mã lỗi.

Bài đầy đủ theo Id — 404 nếu không có.

Bài đầy đủ theo mã đề — 404 nếu đề chưa có bài.

Danh sách bài rút gọn theo SmartTableParam.

Render thân bài + FAQ: format = html (mặc định) | markdown.

Sửa nội dung bài — 200 khi thành công; 409 VERSION_CONFLICT kèm bản hiện tại trong Extra.Current khi ExpectedVersion lệch; 400/404/413/422 theo mã lỗi.

Đổi trạng thái bài — 422 INVALID_TRANSITION kèm danh sách đích hợp lệ trong Extra.AllowedTargets.

Duyệt đăng — chạy đủ 8 điều kiện §3.3d rồi mới chuyển Approved. Thiếu điều kiện → 422 PUBLISH_PRECONDITION_FAILED kèm Extra.Missing / Extra.Checks và không ghi gì. Gác riêng bằng ContentStore.Approve, không dùng chung ContentStore.Edit của SetStatus.

Rút lại bài đã duyệt (Approved → Chờ duyệt), lý do bắt buộc — cùng quyền với duyệt.

Gán tác giả / người kiểm tra cho bài; trả lại bài đầy đủ sau khi gán.

Slug còn trống không (nhìn cả UrlRecord đã xoá mềm của CMS), kèm gợi ý thay thế.

Lịch sử phiên bản của bài, mới nhất trước — 404 nếu không có bài.

Ghi kết quả một dòng ảnh sau khi nộp file (set_image_status): URL ảnh, URL bản OG, trạng thái, ghi chú kiểm. Không đụng thông số ảnh — thứ đó sửa qua Update.

Bỏ một ảnh khỏi bộ ảnh của bài (xoá mềm) — dùng khi bài không cần tấm đó.

Tám điều kiện đăng §3.3d ở chế độ chỉ đọc — màn duyệt hiện danh sách còn thiếu. Không đổi gì; chuyển sang Approved là việc của GĐ E. 404 nếu không có bài.

Tác giả / người kiểm tra của kho nội dung AI (list_people đặc tả §5.3 + CRUD cho màn quản trị). Đọc thì chỉ cần quyền tìm kiếm; ghi thì cần ContentStore.ManageAuthor.

Danh sách gọn cho trợ lý AI và ô chọn tác giả: ?RoleTitle=&IsActive=true&Limit=50.

Tạo mới (Id = 0) hoặc sửa — 201 khi tạo, 200 khi sửa.

Xoá mềm — từ chối nếu người này còn đứng tên bài nào.

Bộ công cụ ảnh: khối STYLE BASE/DO NOT, từ điển khuôn ảnh, ảnh tham chiếu thương hiệu.

Đọc gác bằng ContentStore.GetById — người tạo ảnh cần xem khuôn và ảnh tham chiếu ngay trên màn chi tiết bài. Ghi gác bằng ContentStore.ManageAssets, role RIÊNG cho cấu hình thương hiệu: không mượn role của dữ liệu bài viết, vì cấu hình thương hiệu là miền khác hẳn.

Toàn bộ bộ công cụ cho màn cấu hình (kể cả bản đã tắt).

Bản dùng cho màn chi tiết bài: khuôn + ảnh tham chiếu đang bật.

Nhập bài từ file Markdown 4 phần — đường vào cho trợ lý không có MCP (ChatGPT, Gemini) và cho các file nháp viết trước khi kho nội dung tồn tại. File không lưu xuống đĩa: đọc thẳng từ luồng vào bộ nhớ, xử lý xong là hết. Đây là chủ ý — một thư mục upload trên máy chủ là bề mặt tấn công mới mà nghiệp vụ này không cần tới.

Nộp một hoặc nhiều file .md (multipart). dryRun=true chỉ soát và báo cáo, không ghi gì. 200 kèm bảng kết quả từng file — file hỏng không chặn file lành.

Nhập cả một thư mục trên máy chạy API — đường dẫn truyền qua payload, không hard-code trong code. Dùng cho lượt nhập đầu tiên (30 file nháp) khi file nằm sẵn trên máy chủ nội bộ.

Xuất bản bài từ kho nội dung sang CMS Post — đường duy nhất dữ liệu kho nội dung ra được website.

Hai action, cùng một hàm service. Preview và Publish gọi đúng , chỉ khác cờ DryRun — và Preview ép cờ đó về true ở đây, không tin giá trị người gọi gửi lên. Hai đường code song song cho "xem trước" và "làm thật" là cách chắc chắn để một hôm nào đó chúng lệch nhau, và chỗ lệch sẽ nằm đúng trên đường ghi ra trang công khai. Cả hai gác ContentStore.Publish. Xem trước cũng là quyền: nó trả nguyên HTML sẽ đăng. Riêng chế độ "Đăng ngay" đòi thêm role Post.Publish, kiểm ở tầng service chứ không phải ở đây (§7.11) — MCP và PAT cũng đi qua đúng hàm đó.

Soát thử: trả HTML, mục lục, số H2 / ảnh / FAQ và danh sách việc sẽ ghi. Không ghi một dòng nào, và chạy được cả khi công tắc ContentStore.PublishEnabled đang tắt — đây chính là cách kiểm bài trước khi xin bật công tắc.

Xuất bản thật. Đòi công tắc ContentStore.PublishEnabled = true (503 PUBLISH_DISABLED nếu tắt), bài đang Approved, và đủ 8 điều kiện đăng kiểm lại tại thời điểm này (422 PUBLISH_PRECONDITION_FAILED) — Approved là kết luận của thời điểm duyệt, không phải giấy phép vĩnh viễn.

Soát thử đồng bộ lại ảnh sang bài viết CMS của một bài đã xuất bản: cho biết ảnh đại diện và thân bài sẽ đổi những gì. Không ghi một dòng nào, và chạy được cả khi công tắc đang tắt.

Ghi thật ảnh của bài sang Post đã đăng — ảnh đại diện / OG, và thân bài nếu nó còn đúng bản do kho dựng ra. Đòi công tắc ContentStore.PublishEnabled = true như đường xuất bản.

Danh mục CMS chọn được, kèm cờ danh mục mặc định. Mảng thẳng, không bọc ContentStoreResult (đúng bảng vỏ trả về của miền). Gác ContentStore.Publish chứ không phải Category.GetTree — màn đăng phải chạy được với đúng bó quyền của chính nó.

Chạy tay job đồng bộ trạng thái đăng — thứ Hangfire vẫn chạy mỗi 15 phút. Có ở đây để người vận hành không phải chờ một chu kỳ khi vừa bấm đăng trong CMS cũ.

Nhật ký lượt chạy nháp bài (append_run_log đặc tả §5.1) và danh sách trang dịch vụ (list_service_pages đặc tả §5.3) — hai tra cứu nhỏ của cùng một nhóm người dùng.

Ghi một lượt chạy — 201 kèm dòng vừa ghi.

Các lượt gần nhất, mới trước (mặc định 20, tối đa 100).

Toàn bộ trang dịch vụ đang chạy trên website, để trợ lý AI đặt link nội bộ theo URL thật thay vì bịa đường dẫn.

Những thứ chung của cả miền kho nội dung AI, không thuộc riêng bài / đề / tác giả / token.

Cờ ẩn/hiện cho giao diện: người này bấm được nút nào trong kho nội dung.

Cố ý KHÔNG gác bằng role nào. Câu hỏi "tôi được thấy gì" phải trả lời được cho cả người không có quyền nào — họ nhận đủ cờ false. Gác nó bằng một role là dựng lại đúng cái lỗi nó sinh ra để chữa (rule quyen-hien-thi §4). Luật nằm ở hàm thuần , không nằm ở đây — controller chỉ hỏi role rồi chuyển tiếp.

Ảnh chụp trạng thái triển khai: phiên bản schema, số dòng từng bảng Content*, role đã seed và số người có, ba công tắc, cấu hình MCP đang chạy, và thứ API nhìn thấy về chính request này.

Đây là thứ thay cho việc mở SQL client vào production (quyết định Q7, plan §7.12). Trình tự deploy §4.4 bước 1 đòi xác nhận migration và seed bằng query; ràng buộc 2026-08-27 cấm chạy SQL tay vào Ladaer2 production. Endpoint chỉ đọc, không tham số, và dùng lại được ở mọi lần deploy sau. Vì sao gác Founder chứ không phải một role ContentStore.*. Việc của nó là chứng minh seed role đã chạy — gác nó bằng chính role mà seed tạo ra là vòng tròn: seed hỏng thì endpoint báo 403 và không ai biết vì sao. Founder có sẵn từ trước mọi migration của đợt này. Luật nằm ở ; controller trả thẳng kết quả, không chép tay từng trường — đúng bài học NavPermissions 2026-09-07.

Phần dùng chung của các controller kho nội dung AI: dựng từ người dùng hiện tại và đổi thành HTTP response. Không đặt [Authorize] ở đây — từng controller tự khai để role hiện rõ ngay tại chỗ.

REST và MCP là hai lớp vận chuyển của cùng một luật — luật nằm ở tầng service, còn thứ trợ lý AI đọc để biết phải viết bài thế nào nằm ở Infrastructures/Mcp/McpServerContract.cs cùng mô tả từng tool. Đổi hành vi ở đây mà không sửa hợp đồng bên đó là dựng lại đúng cái lệch pha 2026-09-12: code bỏ ô chờ [[CẦN …]] nhưng chỉ dẫn MCP vẫn dạy trợ lý để ô lại, nên nó vừa làm theo vừa bị cảnh báo.

Người thực hiện thao tác: UserId/UserName từ JWT, RequestId là TraceIdentifier; Client giữ mặc định "admin".

Trả nguyên làm body (kể cả khi thành công, để client luôn có Warnings); status = khi Success, ngược lại suy từ mã lỗi qua .

Hàng đợi đề bài của kho nội dung AI (list_topics / create_topics, đặc tả §5.1).

Danh sách đề cho màn quản trị theo SmartTableParam.

Danh sách đề cho trợ lý AI: ?Status=&WeekNo=&ExcludeL2=F2&Limit=20, theo SortOrder tăng dần.

Tạo nhiều đề một lần — 201 kèm Created/Rejected từng dòng; 400 khi payload rỗng.

Đổi trạng thái một đề — 404 nếu không có mã đề; 400 khi "Đã nháp" mà thiếu ArticleId.

CallLog Controller - Quản lý cuộc gọi tổng đài

Tìm kiếm call log

Các tham số tìm kiếm Kết quả tìm kiếm

Lấy thông tin chi tiết call log theo ID

ID của call log Thông tin chi tiết call log

Tạo hoặc cập nhật call log

Model chứa thông tin call log cần tạo/cập nhật Kết quả của hoạt động tạo/cập nhật call log

Tạo call log mới

Model chứa thông tin call log cần tạo Kết quả của hoạt động tạo call log

Xóa call log

ID của call log cần xóa Kết quả của hoạt động xóa

Cập nhật trạng thái Lead cho call log

ID của call log Model chứa thông tin trạng thái mới Kết quả của hoạt động cập nhật

Lấy danh sách call log theo số điện thoại

Số điện thoại Danh sách call log

Thống kê call log theo khoảng thời gian

Ngày bắt đầu Ngày kết thúc Thống kê call log

Controller xử lý các hoạt động liên quan đến địa chỉ khách hàng.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý địa chỉ khách hàng.

Tìm kiếm các địa chỉ khách hàng dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tìm kiếm các địa chỉ nguồn dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tìm kiếm các địa chỉ đích dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tạo địa chỉ đích cho khách hàng.

Model chứa thông tin địa chỉ khách hàng. Kết quả của hoạt động tạo địa chỉ đích.

Tạo hoặc cập nhật địa chỉ khách hàng.

Model chứa thông tin địa chỉ khách hàng. Kết quả của hoạt động tạo hoặc cập nhật.

Cập nhật riêng định vị (Lat/Long) của một địa chỉ khách hàng. Gửi Lat = Long = null để xoá định vị đang có.

Toạ độ cần ghi. Kết quả của hoạt động cập nhật. Dùng chung role với CreateOrUpdate: ghim toạ độ bản chất là sửa địa chỉ, nên ai sửa được địa chỉ thì ghim được. Đặt role mới sẽ khiến toàn bộ nhân viên đang dùng bị 403 cho tới khi role đó được thêm vào DB.

Lấy thông tin chi tiết của một địa chỉ khách hàng dựa trên ID.

ID của địa chỉ khách hàng. Thông tin chi tiết của địa chỉ khách hàng.

Xóa một địa chỉ khách hàng dựa trên ID.

ID của địa chỉ khách hàng. Kết quả của hoạt động xóa.

Gợi ý địa chỉ khách hàng dựa trên từ khóa, ID khách hàng và loại địa chỉ.

Từ khóa tìm kiếm. ID của khách hàng. Loại địa chỉ. Danh sách địa chỉ phù hợp.

Controller quản lý tài khoản ngân hàng khách hàng

Khởi tạo controller

Service quản lý tài khoản ngân hàng

Lấy danh sách tài khoản ngân hàng của khách hàng

ID khách hàng Danh sách tài khoản ngân hàng

Lấy tài khoản ngân hàng mặc định của khách hàng

ID khách hàng Tài khoản ngân hàng mặc định

Lấy thông tin tài khoản ngân hàng theo ID

ID tài khoản Thông tin tài khoản ngân hàng

Tạo hoặc cập nhật tài khoản ngân hàng

Thông tin tài khoản ngân hàng Kết quả thao tác

Xóa tài khoản ngân hàng

ID tài khoản Kết quả thao tác

Đặt tài khoản làm mặc định

ID tài khoản Kết quả thao tác

Tìm kiếm tài khoản ngân hàng

Từ khóa tìm kiếm (số TK, tên chủ TK, tên ngân hàng) ID khách hàng (tùy chọn) Mã ngân hàng (tùy chọn) Danh sách tài khoản ngân hàng

Gợi ý tài khoản ngân hàng cho khách hàng

ID khách hàng Từ khóa tìm kiếm Danh sách gợi ý

Controller xử lý ticket khiếu nại của khách hàng phía nhân viên (khiếu nại do khách tạo từ app qua Lada.AppBackEnd, khách xem phản hồi qua api/complaints).

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý ticket khiếu nại.

Tìm kiếm khiếu nại của khách hàng.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Lấy chi tiết khiếu nại kèm ảnh đính kèm.

Id khiếu nại. Chi tiết khiếu nại.

Tiếp nhận khiếu nại (chuyển sang trạng thái đang xử lý).

Thông tin thao tác. Kết quả của thao tác.

Phản hồi khiếu nại cho khách.

Thông tin phản hồi. Kết quả của thao tác.

Đóng khiếu nại (chuyển sang trạng thái đã giải quyết).

Thông tin thao tác. Kết quả của thao tác.

Controller dịch vụ xử lý các hoạt động liên quan đến khách hàng.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý khách hàng.

Tìm kiếm các khách hàng dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Gọi đến khách hàng dựa trên từ khóa.

Từ khóa tìm kiếm. Danh sách khách hàng phù hợp.

Gợi ý danh sách sale quản lý dùng cho bộ lọc danh sách khách hàng. Founder thấy toàn bộ nhân viên; người dùng thường chỉ thấy bản thân và cấp dưới trực tiếp.

Từ khóa tìm kiếm. Danh sách nhân viên phù hợp.

Tạo hoặc cập nhật thông tin khách hàng.

Model chứa thông tin khách hàng. Kết quả của hoạt động tạo hoặc cập nhật.

Cập nhật thông tin thuộc tính của khách hàng.

Model chứa thông tin thuộc tính của khách hàng. Kết quả của hoạt động cập nhật thuộc tính.

Lấy thông tin thuộc tính của khách hàng dựa trên ID và loại thuộc tính.

ID của khách hàng. Loại thuộc tính. Thông tin thuộc tính của khách hàng.

Lấy thông tin chi tiết của một khách hàng dựa trên ID.

ID của khách hàng. Thông tin chi tiết của khách hàng.

Xóa một khách hàng dựa trên ID.

ID của khách hàng. Kết quả của hoạt động xóa.

Khóa một khách hàng.

Model chứa thông tin khách hàng cần khóa. Kết quả của hoạt động khóa.

Mở khóa một khách hàng.

Model chứa thông tin khách hàng cần mở khóa. Kết quả của hoạt động mở khóa.

Đặt lại mật khẩu cho tài khoản đăng nhập của một khách hàng.

Model chứa Id khách hàng và mật khẩu mới. Kết quả của hoạt động đặt lại mật khẩu.

Tạo tài khoản đăng nhập cho một khách hàng đã có hồ sơ.

Model chứa Id khách hàng, tên đăng nhập và mật khẩu. Kết quả của hoạt động tạo tài khoản.

Lấy thông tin người quản lý của một khách hàng dựa trên ID.

ID của khách hàng. Thông tin người quản lý của khách hàng.

Gán người quản lý cho một khách hàng.

Model chứa thông tin người quản lý cần gán. Kết quả của hoạt động gán người quản lý.

Gán người quản lý hàng loạt cho nhiều khách hàng.

Model chứa danh sách khách hàng và người quản lý. Kết quả của hoạt động gán hàng loạt.

Xuất danh sách khách hàng ra file Excel.

Tham số tìm kiếm (dùng chung filter với Search). Kết quả xuất Excel (chứa URL download trong Message).

Lấy danh sách đồng quản lý của khách hàng.

Xóa đồng quản lý khỏi khách hàng.

Các role được xem toàn bộ lead (không bị giới hạn theo người phụ trách).

Tìm kiếm lead

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tạo hoặc cập nhật lead

Model chứa thông tin lead cần tạo/cập nhật. Kết quả của hoạt động tạo/cập nhật lead.

Gán người quản lý cho một lead.

Model chứa thông tin người quản lý cần gán. Kết quả của hoạt động gán người quản lý.

Lấy thông tin định giá của một lead dựa trên ID.

ID của lead. Thông tin định giá của lead.

Cập nhật thông tin định giá của một lead.

Model chứa thông tin định giá của lead. Kết quả của hoạt động cập nhật định giá.

Controller duyệt/từ chối yêu cầu đổi nhân viên phụ trách do khách gửi từ app. Duyệt sẽ cập nhật Customer.ManagerId qua luồng AssignManager sẵn có.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý ticket khiếu nại và yêu cầu đổi nhân viên.

Tìm kiếm yêu cầu đổi nhân viên phụ trách.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Duyệt yêu cầu: gán nhân viên phụ trách mới cho khách hàng.

Thông tin duyệt (NewManagerId bắt buộc). Kết quả của thao tác.

Từ chối yêu cầu đổi nhân viên phụ trách.

Thông tin từ chối (ProcessedNote bắt buộc). Kết quả của thao tác.

Controller quản lý thông tin xuất hóa đơn VAT của khách hàng

Lấy danh sách thông tin xuất hóa đơn VAT

Model tìm kiếm Danh sách thông tin xuất hóa đơn VAT

Lấy thông tin chi tiết xuất hóa đơn VAT theo ID

ID thông tin xuất hóa đơn VAT Thông tin chi tiết xuất hóa đơn VAT

Lấy thông tin xuất hóa đơn VAT mặc định của khách hàng

ID khách hàng Thông tin xuất hóa đơn VAT mặc định

Tạo mới hoặc cập nhật thông tin xuất hóa đơn VAT

Model tạo mới hoặc cập nhật Kết quả tạo mới hoặc cập nhật

Xóa thông tin xuất hóa đơn VAT

ID thông tin xuất hóa đơn VAT Kết quả xóa

Đặt thông tin xuất hóa đơn VAT làm mặc định

ID thông tin xuất hóa đơn VAT Kết quả cập nhật

Dashboard cá nhân theo vai trò — mọi endpoint chỉ cần đăng nhập: dashboard là bề mặt cá nhân, phân quyền thật nằm ở mapping widget ↔ nhóm quyền và được DashboardService kiểm tra server-side ở từng thao tác.

Quản trị danh mục widget dashboard: bật/tắt, gán nhóm quyền, sửa cấu hình mặc định, khoá tuỳ chọn (UserEditable trong SettingsSchema)

Lấy thông tin dashboard cho ứng dụng tài xế

Lấy thông tin tài chính của lái xe

Tìm kiếm danh sách đơn hàng tài chính của lái xe có phân trang

Tìm kiếm danh sách đơn hàng của lái xe có phân trang

Lấy thông tin chi tiết đơn hàng theo ID

Lấy chi tiết đơn hàng, id truyền qua query (GetOrder?id=) — dạng app tài xế gửi cho khoá CallPath ORDER_GETBYID (order_service.dart fetchOrderById). Tách action riêng vì [ApiController] suy ra id là [FromRoute] khi mọi route của action có {id}: chỉ chồng thêm [HttpGet("GetOrder")] lên action trên thì ?id= bị bỏ qua, id = 0 và app nhận đơn rỗng.

Cập nhật trạng thái lấy hàng thành công

Cập nhật trạng thái lấy hàng thất bại

Cập nhật trạng thái giao hàng thành công

Cập nhật trạng thái giao hàng thất bại

Controller quản lý các hoạt động liên quan đến triển khai đơn hàng.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý triển khai đơn hàng. Dịch vụ quản lý người dùng. Dịch vụ quản lý chi nhánh.

Lấy danh sách các địa điểm triển khai.

Danh sách các địa điểm triển khai.

Lấy danh sách các địa điểm giao hàng.

Danh sách các địa điểm giao hàng.

Lấy danh sách các đơn hàng cần nhận hàng dựa trên các tham số tìm kiếm.

Các tham số tìm kiếm. Danh sách các đơn hàng cần nhận hàng.

Gán giao hàng

Model gán

Lấy danh sách các địa điểm nhận hàng.

Danh sách các địa điểm nhận hàng.

Lấy danh sách các đơn hàng cần nhận hàng dựa trên các tham số tìm kiếm.

Các tham số tìm kiếm. Danh sách các đơn hàng cần nhận hàng.

Gán nhiệm vụ nhận hàng cho người dùng.

Model chứa thông tin gán nhiệm vụ. Kết quả của hoạt động gán nhiệm vụ.

Hủy gán nhiệm vụ nhận hàng cho người dùng.

Model chứa thông tin hủy gán nhiệm vụ. Kết quả của hoạt động hủy gán nhiệm vụ.

Lấy danh sách các địa điểm trung chuyển.

Danh sách các địa điểm trung chuyển.

Lấy danh sách các đơn hàng cần trung chuyển dựa trên các tham số tìm kiếm.

Các tham số tìm kiếm. Danh sách các đơn hàng cần trung chuyển.

Gán trung chuyển

Model gán

Lấy thông tin giám sát đơn hàng.

Số trang. Kích thước trang. Thông tin giám sát đơn hàng.

Lấy chi tiết đơn hàng dựa trên các tham số tìm kiếm.

Các tham số tìm kiếm. Chi tiết đơn hàng.

Lấy toạ độ cho các địa chỉ đơn hàng chưa được ghim, bằng cách gọi Google Geocoding rồi lưu lại vào CSDL. Bản đồ triển khai gọi endpoint này sau khi đã hiện các điểm gần đúng, nên độ trễ của Google không chặn việc hiển thị.

Danh sách Id của OrderAddress Danh sách toạ độ lấy được (bỏ qua địa chỉ geocode thất bại)

Sắp xếp thứ tự hiển thị đơn hàng

Lấy danh sách vị trí triển khai theo loại triển khai

Loại triển khai: 1=Pickup, 2=Delivery, 3=Transit, 4=Return

Lấy danh sách đơn hàng triển khai theo loại triển khai

Loại triển khai: 1=Pickup, 2=Delivery, 3=Transit, 4=Return Tham số bảng thông minh

Gán đơn hàng cho nhân viên theo loại triển khai

Loại triển khai: 1=Pickup, 2=Delivery, 3=Transit, 4=Return Mô hình gán đơn hàng

Cập nhật đơn hàng sang chiều trả về

Danh sách ID đơn hàng

Lựa chọn "Bên phát hoàn" của hộp Trả về: chi nhánh LADA đang hoạt động (cùng role với Trả về — điều phối không có role màn chi nhánh).

Controller để xử lý các hoạt động liên quan tới quy trình kinh doanh Các chức năng Pickup, Delivery đã được di chuyển sang DriverAppController

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý các hoạt động. Dịch vụ xử lý người dùng.

Tìm kiếm các hoạt động dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Lấy thông tin chi tiết của một hoạt động dựa trên ID.

ID của hoạt động. Thông tin chi tiết của hoạt động.

Xử lý yêu cầu nhận hàng cho một hoạt động.

Model chứa thông tin chi tiết của yêu cầu nhận hàng. Kết quả của hoạt động nhận hàng.

Xử lý yêu cầu nhận hàng cho một hoạt động.

Model chứa thông tin chi tiết của yêu cầu nhận hàng. Kết quả của hoạt động nhận hàng.

T�m ki?m c�c tuy?n d?a tr�n tham s? SmartTableParam

Tham s? t�m ki?m Danh s�ch c�c tuy?n ph� h?p

L?y th�ng tin tuy?n theo ID

ID c?a tuy?n Th�ng tin c?a tuy?n

X�a tuy?n theo ID

ID c?a tuy?n K?t qu? x�a

T?o ho?c c?p nh?t th�ng tin tuy?n

Th�ng tin c?a tuy?n K?t qu? t?o ho?c c?p nh?t

Lấy danh sách agencyIds thuộc chi nhánh hiện tại và con cháu.

Lấy danh sách xe có thể nhận (chưa có người phụ trách)

Danh sách xe có thể nhận

Nhận xe (Check-in) với upload hình ảnh

Thông tin nhận xe Kết quả nhận xe

Trả xe (Check-out) với upload hình ảnh

Thông tin trả xe Kết quả trả xe

Tạo hoặc cập nhật thông tin xe tải

Thông tin xe tải Kết quả tạo hoặc cập nhật

Lấy thông tin xe tải theo danh sách ID

Danh sách ID xe tải Danh sách thông tin xe tải

Lấy thông tin chi tiết của một xe tải dựa trên ID.

ID của xe tải. Thông tin chi tiết của xe tải.

Lấy danh sách media (ảnh đăng ký, đăng kiểm) của xe tải

ID xe tải Danh sách media items

Lấy thông tin xe tải theo ID đơn vị

ID đơn vị Danh sách thông tin xe tải

Tìm kiếm xe tải dựa trên tham số SmartTableParam

Tham số tìm kiếm Danh sách xe tải phù hợp

Xóa xe tải

ID xe tải cần xóa Kết quả xóa

Lấy lịch sử giao nhận xe tải theo ID xe

ID xe tải Danh sách lịch sử giao nhận xe với thông tin ODO, ghi chú và ảnh

Lấy tất cả thông số kỹ thuật của xe tải

ID xe tải Danh sách thông số kỹ thuật

Tạo hoặc cập nhật thông số kỹ thuật của xe tải

Thông tin thông số kỹ thuật Kết quả tạo hoặc cập nhật

Xóa thông số kỹ thuật của xe tải

Thông tin thông số kỹ thuật Kết quả xóa

Tìm kiếm thuộc tính thông số kỹ thuật của xe tải

Tham số tìm kiếm Danh sách thuộc tính thông số kỹ thuật

Lấy tất cả thuộc tính thông số kỹ thuật của xe tải

Danh sách thuộc tính thông số kỹ thuật

Tạo hoặc cập nhật thuộc tính thông số kỹ thuật của xe tải

Thông tin thuộc tính thông số kỹ thuật Kết quả tạo hoặc cập nhật

Xóa thuộc tính thông số kỹ thuật của xe tải

Thông tin thuộc tính thông số kỹ thuật Kết quả xóa

Tìm kiếm thuộc tính bảo trì của xe tải

Tham số tìm kiếm Danh sách thuộc tính bảo trì

Lấy tất cả thuộc tính bảo trì của xe tải

Danh sách thuộc tính bảo trì

Tạo hoặc cập nhật thuộc tính bảo trì của xe tải

Thông tin thuộc tính bảo trì Kết quả tạo hoặc cập nhật

Xóa thuộc tính bảo trì của xe tải

Thông tin thuộc tính bảo trì Kết quả xóa

Lấy tất cả liên kết bảo trì của xe tải

ID bảo trì xe tải Danh sách liên kết bảo trì

Tìm kiếm bảo trì xe tải

Tham số tìm kiếm Danh sách bảo trì xe tải

Lấy thông tin bảo trì xe tải theo danh sách ID

Danh sách ID bảo trì xe tải Danh sách thông tin bảo trì xe tải

Tạo hoặc cập nhật thông tin bảo trì xe tải

Thông tin bảo trì xe tải Kết quả tạo hoặc cập nhật

Xóa thông tin bảo trì xe tải

Id của lần bảo dưỡng cần xoá Kết quả xóa

Lấy danh sách tất cả xe tải thuộc chi nhánh của người dùng hiện tại

Danh sách tất cả xe tải thuộc chi nhánh

Nạp dầu cho xe với upload hình ảnh và thông tin ODO

Thông tin nạp dầu Kết quả nạp dầu

Lấy hoạt động xe tải theo danh sách ID

Danh sách ID hoạt động xe tải Thông tin hoạt động xe tải

Cập nhật giá trị ODO đổ dầu gần nhất của xe tải

ID xe tải Giá trị ODO Kết quả cập nhật

Lấy giá trị ODO đổ dầu gần nhất của xe tải

ID xe tải Giá trị ODO đổ dầu gần nhất

API phân hệ bảo dưỡng xe tải: danh mục garage, danh mục loại bộ phận, bộ phận lắp trên xe. Vì sao là controller riêng chứ không thêm vào TruckController: file đó đã 620 dòng và ôm cả xe, hoạt động, thông số kỹ thuật, bảo trì, đổ dầu. Phân hệ này còn thêm engine cảnh báo và API tình trạng đội xe ở GĐ B nên tách từ đầu. Tên role cố ý giữ tiền tố Truck.* thay vì TruckMaintenance.* theo tên controller: plan §3.4 đã chốt danh sách role và migration đã seed đúng danh sách đó. Role gom theo nhóm việc (ComponentTypeManage, ComponentManage) chứ không một-role-một-action, vì đây là danh mục quản trị dùng chung — ai sửa được thì cũng xem được.

Khởi tạo controller bảo dưỡng xe tải.

Dựng phạm vi chi nhánh của người dùng hiện tại.

Luật nằm trong vì TruckController cũng cần đúng luật này cho luồng lưu/xoá bảo dưỡng — hai bản sao của một luật phân quyền là hai chỗ để quên sửa một chỗ.

Tìm kiếm garage.

Lấy danh sách garage đang hoạt động (đổ vào ô chọn).

Lấy chi tiết một garage.

Tạo mới hoặc cập nhật garage.

Xoá garage.

Tìm kiếm loại bộ phận xe.

Lấy danh sách loại bộ phận (đổ vào ô chọn).

Lấy chi tiết một loại bộ phận.

Tạo mới hoặc cập nhật loại bộ phận.

Xoá loại bộ phận.

Tìm kiếm bộ phận trên xe, trong phạm vi chi nhánh của người dùng.

Lấy toàn bộ bộ phận của một xe.

Mở thêm cho người ghi bảo dưỡng vì form bảo dưỡng gọi nó khi chọn xe để gắn dòng phụ tùng vào bộ phận (QĐ3-11) — chỉ nới ĐỌC, gắn/sửa/xoá bộ phận vẫn chỉ Truck.ComponentManage; phạm vi chi nhánh giữ nguyên.

Lấy chi tiết một bộ phận.

Gắn mới hoặc sửa bộ phận trên xe.

Khởi tạo bộ bộ phận hàng loạt cho một xe từ danh mục đang bật.

Xoá bộ phận trên xe.

Lấy chỉ số ODO hiện tại của một xe kèm thời điểm ghi nhận và nguồn dữ liệu. Chỉ trả về khi xe nằm trong phạm vi chi nhánh của người dùng.

Mở thêm cho người ghi bảo dưỡng vì form bảo dưỡng gọi nó khi chọn xe để điền sẵn ODO (QĐ3-11).

Danh sách xe kèm ODO hiện tại và số bộ phận sắp/đã đến hạn — màn tình trạng đội xe.

Số cảnh báo tính trực tiếp bằng engine tại thời điểm gọi, không đọc bảng TruckComponentAlert: bảng đó do job nền ghi nên trước lượt quét đầu tiên còn rỗng, mà màn tình trạng phải đúng ngay khi vừa gắn bộ phận xong.

Hồ sơ tình trạng một xe: ODO, lưới bộ phận kèm tỷ lệ tiêu hao và mức cảnh báo.

Lịch sử các lần bảo dưỡng đã chạm tới một bộ phận: thay ở đâu, giá bao nhiêu, có hoá đơn không.

Tra cứu cảnh báo do job nền sinh, lọc theo phạm vi chi nhánh của người dùng.

Danh sách tệp đính kèm của một lần bảo dưỡng.

Role dùng lại nhóm Truck.TruckMaint* có sẵn của luồng bảo dưỡng vì tệp là một phần của bản ghi bảo dưỡng — ai xem/sửa được bản ghi thì xem/sửa được tệp. Phạm vi chi nhánh vẫn ép server-side theo xe đang gắn với bản ghi.

Tải tệp (multipart) lên và gắn vào lần bảo dưỡng.

Gỡ một tệp đính kèm khỏi lần bảo dưỡng.

Đọc một hoá đơn đã đính kèm (PDF hoặc ảnh) và trả gợi ý số tiền / ngày / biển số cho form.

Người dùng chủ động bấm "Đọc từ hoá đơn"; kết quả chỉ là gợi ý "máy đọc — kiểm lại", không tự điền, không ghi gì vào DB. Tệp đọc lại từ đĩa theo bản ghi đính kèm — không nhận tệp tải lên ở đây, nên không có endpoint "OCR chung" cho file tuỳ ý (plan trích-xuất-văn-bản §3.5). Role: người sửa được bản ghi bảo dưỡng mới cần gợi ý để điền form. Phạm vi chi nhánh ép server-side theo xe gắn với bản ghi. POST vì là thao tác tốn CPU (OCR 1–2,5 giây), không để proxy/trình duyệt cache. Id dòng đính kèm (TruckMaintenanceMediaItem.Id), loại hoá đơn.

Cờ hiển thị phần "Đọc phiếu bằng AI" của form bảo dưỡng (rule quyen-hien-thi).

KHÔNG đòi role: câu "tôi được thấy gì" phải trả lời được cho cả người không có quyền nào (họ nhận toàn false). Mỗi cờ đọc đúng bó role trên [Authorize] của endpoint nó gác — test reflection khoá.

Đọc một hoá đơn / phiếu đã đính kèm bằng AI và trả gợi ý tiêu đề + từng dòng khớp danh mục.

Gợi ý, không ghi gì ngoài nhật ký đọc. Phạm vi chi nhánh theo xe của bản ghi; ngoài phạm vi trả cùng câu "không tìm thấy". AI lỗi thì máy chủ tự chuyển sang OCR cũ (Mode = Offline). Id dòng đính kèm loại hoá đơn.

Đọc tệp phiếu tải thẳng lúc TẠO MỚI bản ghi (QĐ3-3). Tệp chỉ được đọc rồi bỏ — lưu bản ghi xong giao diện mới tải nó lên làm media và gọi SlipReading/{id}/Attach.

Trần 15 MB kiểm TRƯỚC khi đọc vào bộ nhớ (§3.11); xe phải thuộc phạm vi chi nhánh của người gọi.

Chạy lại so khớp (không gửi lại ảnh) sau khi danh mục / alias vừa đổi. Có trần số lần.

Mở lại gợi ý của một lượt đọc trong phạm vi chi nhánh.

Gắn lượt đọc lúc tạo mới vào bản ghi vừa lưu (và dòng media vừa tải lên).

Danh sách tên gọi khác của loại bộ phận K200.

Ghi nhớ "tên trên phiếu = loại bộ phận" — danh mục dùng chung nên đòi role quản lý danh mục.

Gỡ một tên gọi khác.

API chấm công dành cho ứng dụng lái xe (DriverApp).

Tra cứu lịch sử chấm công của chính lái xe đang đăng nhập (có phân trang). UserId được lấy từ token và ép ở tầng service, không đọc từ client.

Tham số SmartTableParam (Pagination bắt buộc; lọc khoảng ngày qua Search.PredicateObject.CheckInStart/CheckInEnd). Danh sách ca chấm công của lái xe hiện tại.

Lấy thông tin dashboard cho ứng dụng tài xế

Lấy thông tin tài chính của lái xe

Tìm kiếm danh sách đơn hàng tài chính của lái xe có phân trang

Lái xe tạo phiếu chuyển tiền (upload ảnh chuyển khoản)

Lái xe xem phiếu đang chờ duyệt

Lái xe hủy phiếu chuyển tiền

Lấy thông tin tài khoản ngân hàng để nộp tiền (QR code VietQR)

Tìm kiếm danh sách đơn hàng của lái xe có phân trang

Tìm kiếm đơn hàng đang hoạt động (đang lấy, lấy thất bại, đang giao, giao thất bại)

Lấy thông tin chi tiết đơn hàng theo ID

Sắp xếp thứ tự hiển thị đơn hàng

Cập nhật trạng thái lấy hàng thành công

Cập nhật trạng thái lấy hàng thất bại

Cập nhật trạng thái giao hàng thành công

Cập nhật trạng thái giao hàng thất bại

Cập nhật trạng thái trả hàng thành công

Cập nhật trạng thái trả hàng thất bại

Lấy danh sách lý do thất bại theo loại (Pickup/Delivery)

Đăng nhập dành cho tài xế

Đổi mật khẩu

Gia hạn đăng nhập (Refresh Token)

Cập nhật thông tin profile

Chấm công (Check-in/Check-out)

Lấy bảng lương (Dựa trên báo cáo năng suất)

Lấy danh sách tất cả xe tải thuộc chi nhánh của người dùng hiện tại

Danh sách tất cả xe tải thuộc chi nhánh

Lấy danh sách xe tải có thể nhận (chưa có người phụ trách) thuộc chi nhánh

Danh sách xe tải có thể nhận

Nhận xe (Check-in) với upload hình ảnh

Thông tin nhận xe Kết quả nhận xe

Trả xe (Check-out) với upload hình ảnh

Thông tin trả xe Kết quả trả xe

Đổ dầu cho lái xe trên app mobile. Lái xe là người đang đăng nhập, xe là xe đang phụ trách (tự động xác định). Có thể chọn thẻ dầu hoặc đổ bằng tiền mặt, không cần chọn giao dịch.

Thông tin đổ dầu Kết quả đổ dầu

Lái xe chỉnh sửa và gửi lại phiếu đổ dầu bị từ chối

Lái xe xóa phiếu đổ dầu (chỉ khi Pending hoặc Rejected)

Lịch sử đổ dầu của lái xe (phân trang, lọc theo ngày và từ khóa)

Kiểm tra xe hiện tại của người dùng

Thông tin xe hiện tại

Lấy thẻ xăng dầu mà lái xe đang được gán (bao gồm PendingAccept và Received)

Lấy thông tin thẻ xăng dầu theo QR Code

Lái xe xác nhận nhận thẻ xăng dầu (kèm ảnh minh chứng)

Lái xe trả thẻ xăng dầu (kèm ảnh minh chứng)

Tình trạng bảo dưỡng của xe lái xe đang nhận: ODO hiện tại và danh sách bộ phận kèm tỷ lệ tiêu hao, cái nào sắp đến hạn.

Không nhận truckId từ client. Xe xác định từ token qua Truck.CurrentDriverId — cho phép truyền id là cho tài xế xem xe của người khác. Chưa nhận xe thì trả 404 kèm thông báo, không trả rỗng lặng lẽ.

Giọng đọc dẫn đường cho app lái xe (đợt dẫn đường DriverApp, GĐ D2 — plan §3.5.6, §3.11; đợt tự host 2026-09-28 — memory project-tts-tu-host).

Gác bằng role SẴN CÓ DriverApp.SearchActiveOrders (danh sách đơn đang trên đường của app lái xe): mọi lối vào màn dẫn đường đều đi qua danh sách đó, nên ai tới được nút loa đều có role này — không cần cờ ẩn nút (rule quyen-hien-thi). Role riêng Tts.Batch cần migration seed cho nhóm lái xe — ngoài phạm vi D2 (DD-42). Chỉ [Authorize] trơn thì bất kỳ tài khoản nhân viên nào (kể cả bị lộ) cũng tiêu được trần ký tự toàn server (/code-review D2). Chặn tiếp bằng trần ký tự câu mới theo người + toàn server trong .

Role gác endpoint — mượn của danh sách đơn đang trên đường (xem remarks).

Role gác endpoint trạng thái — người vận hành cấu hình hệ thống (cùng role với ReloadCache của AppConfig).

Bảo đảm các câu chỉ dẫn có âm thanh; trả bytes (base64) của câu app chưa có.

400 khi số câu ngoài 1…60 (ErrorCode = "Invalid"; câu sai LẺ chỉ hỏng dòng của nó); 503 khi máy chủ chưa có khoá nguồn giọng ("NotConfigured"); còn lại 200 — kể cả khi nguồn lỗi hay hết token: lúc đó Result = Failed kèm ErrorCode, những câu đã có vẫn trả về dùng được. Câu chưa có ở nguồn tự host mang "Pending" riêng dòng, lượt vẫn Success.

Trạng thái gateway cho người vận hành: nguồn đang chọn, năm khoá AppConfig đã nạp (khoá che), thăm dò sidecar, và một lượt tổng hợp thử qua đúng đường app đi.

Có vì backend production chỉ ghi log ra console (IIS không giữ): "app không tải được giọng" mà không có cách nào biết hỏng ở AppConfig, khoá, mạng tới sidecar hay nguồn. Lượt thử tính vào trần ký tự của người gọi (50 ký tự) — gọi tay vài lần không đáng kể.

Controller quản lý tài khoản gửi email (SMTP/SES) — cấu hình động, có mã hóa secret.

Lấy danh sách tài khoản gửi email.

Lấy chi tiết tài khoản gửi email theo ID (không trả secret thật).

Tạo mới hoặc cập nhật tài khoản gửi email.

Xóa (mềm) tài khoản gửi email.

Đặt tài khoản gửi làm mặc định (chỉ 1 mặc định toàn hệ thống).

Gửi email thử để kiểm tra cấu hình tài khoản.

Controller nhật ký + báo cáo gửi email (chỉ đọc).

Danh sách nhật ký gửi email (lọc theo trạng thái/người nhận/khoảng ngày).

Chi tiết 1 dòng nhật ký gửi email.

Báo cáo tổng hợp gửi email (tổng/thành công/thất bại) theo khoảng ngày.

Controller quản lý tài khoản ngân hàng

Tìm kiếm tài khoản ngân hàng

Tham số tìm kiếm Danh sách tài khoản ngân hàng

Lấy chi tiết tài khoản ngân hàng

ID tài khoản ngân hàng Chi tiết tài khoản ngân hàng

Tạo hoặc cập nhật tài khoản ngân hàng

Thông tin tài khoản ngân hàng Kết quả thao tác

Xóa tài khoản ngân hàng

ID tài khoản ngân hàng Kết quả thao tác

Import sao kê ngân hàng từ file Excel

Thông tin import Kết quả import

Tìm kiếm giao dịch ngân hàng

Tham số tìm kiếm Danh sách giao dịch

Lấy danh sách tài khoản ngân hàng đang hoạt động

Danh sách tài khoản đang hoạt động

Tìm kiếm lịch sử import sao kê

Tham số tìm kiếm Danh sách lịch sử import

Cập nhật số dư tài khoản

ID tài khoản Số dư mới Kết quả thao tác

Model cập nhật số dư

ID tài khoản

Số dư mới

Controller quản lý thông tin ngân hàng

Tìm kiếm ngân hàng với phân trang

Lấy danh sách tất cả ngân hàng đang hoạt động

Khởi tạo dữ liệu ngân hàng mẫu

Lấy thông tin ngân hàng theo ID (trả về model để edit)

Tạo hoặc cập nhật thông tin ngân hàng

Tạo ngân hàng mới

Cập nhật thông tin ngân hàng

Xóa ngân hàng

Gợi ý ngân hàng theo từ khóa (cho select option)

Tìm kiếm quỹ

Các tham số tìm kiếm. Kết quả tìm kiếm.

Thu tiền

Model chứa thông tin thu tiền. Kết quả của hoạt động thu tiền.

Lấy danh sách hóa đơn

ID của người dùng. Danh sách hóa đơn.

Tìm kiếm tài khoản

Các tham số tìm kiếm. Kết quả tìm kiếm.

Lấy tài khoản theo ID

ID của tài khoản. Thông tin tài khoản.

Tạo hoặc cập nhật tài khoản

Model chứa thông tin tài khoản cần tạo/cập nhật. Kết quả của hoạt động tạo/cập nhật tài khoản.

Xóa tài khoản

ID của tài khoản cần xóa. Kết quả của hoạt động xóa tài khoản.

Seed dữ liệu tài khoản

Kết quả của hoạt động seed dữ liệu tài khoản.

Lấy danh sách khách hàng cần đối soát

Lấy danh sách đơn hàng có thể đối soát của khách hàng

Tìm kiếm phiếu đối soát

Lấy chi tiết phiếu

Duyệt phiếu (Kế toán)

Từ chối phiếu (Kế toán)

Hoàn thành phiếu (Xác nhận thanh toán)

Lấy lịch sử thao tác

Upload ảnh chứng từ cho phiếu đối soát

ID phiếu đối soát Danh sách ảnh chứng từ (1-3 ảnh) Kết quả upload

Xuất Excel danh sách phiếu đối soát khách hàng

Model xuất Excel Kết quả xuất file

Xuất Excel chi tiết phiếu đối soát khách hàng

ID phiếu đối soát Model xuất Excel Kết quả xuất file

Xuất Excel danh sách đơn hàng cần đối soát của khách hàng

ID khách hàng Model xuất Excel Kết quả xuất file

Tìm kiếm phiếu chuyển tiền lái xe

Chi tiết phiếu chuyển tiền

Duyệt phiếu chuyển tiền

Từ chối phiếu chuyển tiền

Controller quản lý danh mục chi phí

Tìm kiếm danh mục chi phí với phân trang

Tham số tìm kiếm và phân trang Danh sách danh mục chi phí

Lấy danh mục chi phí theo ID

ID danh mục chi phí Thông tin danh mục chi phí

Tạo hoặc cập nhật danh mục chi phí

Thông tin danh mục chi phí Kết quả tạo hoặc cập nhật

Xóa danh mục chi phí

ID danh mục chi phí Kết quả xóa

Lấy danh sách tất cả danh mục chi phí (cho dropdown)

Danh sách danh mục chi phí

Kiểm tra tên danh mục có trùng không

Tên danh mục ID loại trừ (khi update) True nếu tên đã tồn tại

Lấy danh sách danh mục chi phí theo cây phân cấp

Danh sách danh mục chi phí theo cây phân cấp

Lấy danh sách danh mục gốc (không có ParentId)

Danh sách danh mục gốc

Lấy danh sách danh mục con theo ParentId

ID danh mục cha Danh sách danh mục con

Kiểm tra có thể xóa danh mục không (không có danh mục con)

ID danh mục True nếu có thể xóa

Controller quản lý chi phí

Tìm kiếm chi phí với phân trang

Tham số tìm kiếm và phân trang Danh sách chi phí

Lấy chi phí theo ID

ID chi phí Thông tin chi phí

Tạo hoặc cập nhật chi phí

Thông tin chi phí Kết quả tạo hoặc cập nhật

Duyệt chi phí

ID chi phí Kết quả duyệt

Bỏ duyệt chi phí (chuyển về trạng thái chờ duyệt)

ID chi phí Kết quả bỏ duyệt

Từ chối chi phí

ID chi phí Thông tin từ chối Kết quả từ chối

Đánh dấu chi phí đã chuyển tiền

ID chi phí Thông tin chuyển tiền Kết quả đánh dấu chuyển tiền

Xóa chi phí

ID chi phí Kết quả xóa

Duyệt hàng loạt chi phí (chỉ dành cho Founder)

Danh sách ID chi phí cần duyệt Kết quả duyệt hàng loạt

Request model cho việc từ chối chi phí

Lý do từ chối (bắt buộc)

Request model cho việc đánh dấu chi phí đã chuyển tiền

Ghi chú cho giao dịch chuyển tiền

Request model cho việc duyệt hàng loạt chi phí

Danh sách ID chi phí cần duyệt

Controller cho việc xuất Excel thông tin đơn hàng

Xuất Excel thông tin đơn hàng theo danh sách OrderId hoặc OrderCode

Thông tin đầu vào Kết quả xuất file

Xuất Excel thông tin đơn hàng theo danh sách OrderId

Danh sách ID đơn hàng Kết quả xuất file

Xuất Excel thông tin đơn hàng theo danh sách OrderCode

Danh sách mã đơn hàng Kết quả xuất file

Download file Excel đã xuất

Tên file File Excel

Lấy danh sách file Excel đã xuất

Danh sách file

Lấy dữ liệu tổng quan tài chính

Tổng quan tình hình tài chính — Financial Health Overview Tổng hợp 12 KPIs: Profitability (5) + Liquidity (5) + Franchise (2) Bám theo Section 4 - LADA_Franchise_Finance_Plan.md

Dự báo dòng tiền 13 tuần tới

Controller tổng hợp cho việc xuất Excel các phiếu tài chính

Xuất Excel danh sách phiếu đối soát

Model xuất Excel Kết quả xuất file

Xuất Excel chi tiết phiếu đối soát

ID phiếu đối soát Model xuất Excel Kết quả xuất file

Xuất Excel danh sách phiếu chuyển khoản

Model xuất Excel Kết quả xuất file

Xuất Excel chi tiết phiếu chuyển khoản

ID phiếu chuyển khoản Model xuất Excel Kết quả xuất file

Xuất Excel danh sách đơn hàng nợ cước của khách hàng

Model xuất Excel Kết quả xuất file

Download file Excel đã xuất

Tên file File Excel

Lấy danh sách file Excel đã xuất

Danh sách file

Xóa file Excel đã xuất

Tên file Kết quả xóa

Xác định loại file dựa trên thư mục

Controller quản lý thẻ xăng dầu (thẻ tín dụng), đổ dầu và thanh toán tiền dầu khoán

Tìm kiếm thẻ xăng dầu với phân trang

Lấy thông tin thẻ xăng dầu theo ID

Lấy lịch sử thẻ xăng dầu

Tạo hoặc cập nhật thẻ xăng dầu

Xóa thẻ xăng dầu

Lấy danh sách thẻ đang hoạt động

Lấy tổng nợ thẻ tín dụng (cho báo cáo)

Import sao kê thẻ tín dụng từ Excel

Import lịch sử giao dịch thẻ xăng dầu từ file Excel. File Excel phải có cột "Tài khoản thẻ/ Số thẻ" để hệ thống ánh xạ với thẻ tương ứng. Hệ thống sẽ tự động tìm thẻ dựa vào số thẻ trong file và tạo giao dịch tương ứng.

Các cột được hỗ trợ trong file Excel: - Tài khoản thẻ / Số thẻ (bắt buộc): Số thẻ tín dụng để mapping - Ngày giao dịch: Định dạng dd/MM/yyyy hoặc dd/MM/yyyy HH:mm - Số tiền: Số tiền giao dịch (hỗ trợ định dạng 1.234.567 hoặc 1,234,567) - Loại tiền: VND, USD... - Loại giao dịch: Retail, Refund... - Địa điểm: Nơi giao dịch - Tình trạng: Thành công, Chờ xử lý...

Tìm kiếm giao dịch thẻ

Lấy chi tiết giao dịch thẻ

Đối soát giao dịch thẻ với lần đổ dầu

Đánh dấu giao dịch đã thanh toán cho ngân hàng

Lấy danh sách giao dịch chưa đối soát theo thẻ và ngày

Xóa nhiều giao dịch thẻ cùng lúc

Tạo hoặc cập nhật thông tin đổ dầu

Tìm kiếm lịch sử đổ dầu

Lấy chi tiết lần đổ dầu

Lấy lịch sử đổ dầu theo xe

Lấy lịch sử đổ dầu theo lái xe

Xóa bản ghi đổ dầu

Duyệt phiếu đổ dầu (nếu đổ bằng thẻ, bắt buộc chọn giao dịch thẻ xăng)

Từ chối phiếu đổ dầu

Bỏ duyệt phiếu đổ dầu đã duyệt (chưa chốt lương): đưa về chờ duyệt, gỡ đối soát giao dịch thẻ

Cờ hiển thị nút Duyệt / Từ chối / Bỏ duyệt / Cập nhật / Xóa / Xuất Excel của màn Lịch sử đổ dầu cho người đang đăng nhập

Cố ý không đòi role nào (chỉ cần đăng nhập): người không có quyền vẫn phải hỏi được và nhận toàn false để giao diện ẩn nút. Luật nằm ở hàm thuần .

Xuất Excel lịch sử đổ dầu

Controller quản lý danh mục doanh thu

Tìm kiếm danh mục doanh thu với phân trang

Tham số tìm kiếm và phân trang Danh sách danh mục doanh thu

Lấy danh mục doanh thu theo ID

ID danh mục doanh thu Thông tin danh mục doanh thu

Tạo hoặc cập nhật danh mục doanh thu

Thông tin danh mục doanh thu Kết quả tạo hoặc cập nhật

Xóa danh mục doanh thu

ID danh mục doanh thu Kết quả xóa

Lấy danh sách tất cả danh mục doanh thu (cho dropdown)

Danh sách danh mục doanh thu

Kiểm tra tên danh mục có trùng không

Tên danh mục ID loại trừ (khi update) True nếu tên đã tồn tại

Lấy danh sách danh mục doanh thu theo cây phân cấp

Danh sách danh mục doanh thu theo cây phân cấp

Lấy danh sách danh mục gốc (không có ParentId)

Danh sách danh mục gốc

Lấy danh sách danh mục con theo ParentId

ID danh mục cha Danh sách danh mục con

Kiểm tra có thể xóa danh mục không (không có danh mục con)

ID danh mục True nếu có thể xóa

Controller quản lý doanh thu

Tìm kiếm doanh thu với phân trang

Tham số tìm kiếm và phân trang Danh sách doanh thu

Lấy doanh thu theo ID

ID doanh thu Thông tin doanh thu

Tạo hoặc cập nhật doanh thu

Thông tin doanh thu Kết quả tạo hoặc cập nhật

Duyệt doanh thu

ID doanh thu Kết quả duyệt

Từ chối doanh thu

ID doanh thu Thông tin từ chối Kết quả từ chối

Đánh dấu doanh thu đã nhận tiền

ID doanh thu Thông tin nhận tiền Kết quả đánh dấu nhận tiền

Xóa doanh thu

ID doanh thu Kết quả xóa

Nộp cọc trách nhiệm — tạo giao dịch thu nhập cọc lái xe

Request model cho việc từ chối doanh thu

Lý do từ chối (bắt buộc)

Request model cho việc đánh dấu doanh thu đã nhận tiền

Ghi chú cho giao dịch nhận tiền

Request model cho việc nộp cọc trách nhiệm

ID lái xe nộp cọc

Số tiền cọc

Ngày chuyển khoản

Ảnh chuyển khoản (tùy chọn)

Ghi chú

Controller cho báo cáo thu chi

Khởi tạo một thể hiện của .

Service báo cáo thu chi.

Lấy báo cáo thu chi theo khoảng thời gian

Thông tin khoảng thời gian báo cáo Báo cáo thu chi theo ngày

Controller quản lý tài khoản ngân hàng cá nhân của người dùng đang đăng nhập

Lấy danh sách tài khoản ngân hàng của tôi

Danh sách tài khoản ngân hàng

Tìm kiếm tài khoản ngân hàng của tôi với phân trang

Tham số tìm kiếm và phân trang Danh sách tài khoản ngân hàng với phân trang

Lấy thông tin chi tiết tài khoản ngân hàng của tôi theo ID

ID tài khoản ngân hàng Thông tin chi tiết tài khoản ngân hàng

Tạo mới hoặc cập nhật tài khoản ngân hàng của tôi

Thông tin tài khoản ngân hàng Kết quả tạo hoặc cập nhật

Xóa tài khoản ngân hàng của tôi

ID tài khoản ngân hàng Kết quả xóa

Controller xử lý các hoạt động liên quan đến giá cước.

Khởi tạo một instance mới của lớp .

Tùy chọn cấu hình ứng dụng. Dịch vụ xử lý giá cước. Dịch vụ quản trị ma trận giá theo loại hàng. Engine báo giá theo dòng phí. Môi trường lưu trữ web. Truy cập ngữ cảnh HTTP. GĐ 2 — bỏ IBackFeeService và IGoodsCategoryPricingService khỏi controller: cả hai nay nằm bên trong engine. IBackFeeService mất nơi gọi cuối cùng và đã được xoá.

Id loại hàng mặc định của hệ thống (QĐ-1).

GoodsCategoryId, bằng 0 khi chưa cấu hình. Form lên đơn cần biết loại mặc định ngay khi mở để đặt sẵn dòng hàng đầu tiên, tức trước khi có đủ hai đầu địa chỉ để gọi CheckFee. Không có endpoint này thì frontend buộc phải hardcode Id "Hàng đóng kiện" — đúng thứ mà GoodsCategoryResolver đã cố tránh bằng cách đưa Id vào cấu hình. Chỉ trả Id, không trả tên: danh mục loại hàng frontend đã tải sẵn để đổ dropdown, tra tên ở đó. Dùng chung quyền với CheckFee vì cùng phục vụ một màn hình.

Lấy danh sách giá mặc định.

Loại giá. Danh sách giá mặc định.

Cập nhật danh sách giá mặc định.

Model chứa thông tin danh sách giá. Kết quả của hoạt động cập nhật danh sách giá.

Đọc bảng giá của MỘT PHẠM VI bất kỳ — bộ ba (khách, loại hàng, loại giá).

Khách sở hữu bảng giá. 0 = khách mặc định. Loại giá. Loại hàng. Bỏ trống = bảng giá CHUNG theo khoảng trọng lượng. Bảng giá của phạm vi được hỏi. Đây là dạng tổng quát của — endpoint cũ nay chỉ là lời gọi endpoint này với phạm vi (khách mặc định, bảng chung). Giữ endpoint cũ để client hiện tại không phải đổi. Dùng lại quyền Price.GetDefaultPriceList: cùng một việc "xem bảng giá", chỉ khác phạm vi. Đẻ quyền mới nghĩa là mọi vai trò đang xem bảng giá phải được gán lại tay.

Cập nhật bảng giá của một phạm vi bất kỳ.

Bảng giá kèm phạm vi (CustomerId, GoodsCategoryId, PriceType). Kết quả cập nhật. ⚠️ Đường lưu này suy ra "dòng cần xoá" bằng đang có trong phạm vi − có trong payload. Gửi sai phạm vi là xoá mềm dữ liệu của phạm vi khác — đúng hình dạng của nợ PSVC. Payload phải chứa đủ mọi dòng người dùng đang nhìn thấy của ĐÚNG phạm vi đó.

Liệt kê các PHẠM VI bảng giá của một khách hàng.

Khách cần xem. 0 = khách mặc định. Danh sách phạm vi kèm số dòng và cờ đang đi mượn bảng mặc định. Danh sách cố tình gồm cả phạm vi khách chưa khai dòng nào và đang ăn theo bảng mặc định (cờ IsInherited). Người quản trị cần thấy "khách này đang tính tiền bằng bảng của ai" ngay trên màn hình, thay vì phải suy ra bằng cách không thấy dòng nào.

Sao chép bảng giá từ phạm vi nguồn sang phạm vi đích.

Nguồn, đích, loại giá và các tuỳ chọn copy. Số ô đã tạo, bỏ qua, đè — và cảnh báo nếu có. ⚠️ Mặc định OverwriteExisting = false — không đè ô đã tồn tại ở đích. UI phải hiện đủ , , cho người dùng biết.

Xuất danh sách giá mặc định.

Loại giá của bảng đang mở — cùng tham số với GetDefaultPriceList. Kết quả của hoạt động xuất danh sách giá. là tham số THÊM VÀO khi vá nợ N4. Không có nó, service phải tự đoán phạm vi nên nạp mọi dòng giá của khách mặc định: file Excel trộn cả ba loại giá và kéo theo cả ô giá theo loại hàng, tức là không khớp với bảng người dùng đang nhìn lúc bấm Xuất.

Kiểm tra phí.

Model chứa thông tin kiểm tra phí. Kết quả của hoạt động kiểm tra phí. GĐ 2 — đường này nay chạy bằng , cùng khung dòng phí với đường tạo đơn. Trước đó khung dòng phí không có nơi gọi nào trên đường tiền: viết xong, có test, mà không ai chạy qua nó. Không đổi một đồng nào — và đây là các lý do từng ô ra đúng số cũ: ResolveAreaSurcharge = true để engine TỰ tra phụ phí khu vực từ hai phường, đúng việc BackFeeService làm trước đây. Đường tạo đơn để false — xem , bật nhầm ở đó là cộng thêm một khoản chưa từng có vào mọi đơn mới. Bốn khoản CollectAmount / InsuranceFee / ReturnFee / Discount để nguyên 0 vì không có chúng. Bộ tính tương ứng trả null ⇒ không sinh dòng ⇒ không cộng đồng nào. Ngày nào form báo giá nhận thêm mấy số đó thì chỉ cần gán vào request, engine tự lo. Giá cố định theo loại hàng: RouteFeeCalculator sinh dòng cước tuyến IsSkipped với Amount = 0, nên Fee tự về 0 — thay cho câu if (pricing.IsFixedPrice) Fee = 0 viết tay trước đây. Số lời gọi IGoodsCategoryPricingService.ResolveAsync giữ NGUYÊN, không tăng. Bản cũ gọi hai lần: một lần trong FeeService (chỉ khi danh mục có bảng giá riêng) và một lần ngay tại controller (mọi lần tra cước thành công). Bản mới cũng hai: lần trong FeeService giữ nguyên, còn lần của controller dời vào RouteFeeCalculator. Điều kiện chạy khác nhau về hình thức (GoodsCategoryId.HasValue thay vì "tra cước thành công") nhưng ra cùng kết quả: bộ tính chỉ chạy tới đó khi tra cước đã thành công, và ResolveAsync không có danh mục thì trả kết quả rỗng.

Dựng danh sách dòng hàng cho engine: quy đổi Kg → gram rồi gộp các món giống nhau về giá.

Dòng hàng form gửi, trọng lượng tính cước theo Kg. null khi form không khai theo món — engine đi nhánh một loại hàng. ⚠️ Bước gộp là thứ giữ cho báo giá bằng đúng số tiền đơn được lưu. Form lên đơn gửi mỗi kiện một dòng (packageEditor.getFeeModel), còn đường ghi đơn OrderService.Create gộp kiện cùng loại + cùng thuộc tính trước khi tra (). Bảng giá theo cân là bậc thang, nên tra ba dòng 10kg rồi cộng lại ra số khác với tra thẳng 30kg: trước bản vá này, đơn 3 kiện × 10kg cùng loại báo 360.000 nhưng lưu 220.000 — người lên đơn báo khách một giá, hệ thống thu một giá khác. Gộp sau khi đã đổi kg → gram, đúng thứ tự của OrderService.Create (gộp trên SubTotalWeight đã là gram) và của FeeRules.BuildGoodsLines bên Lada.AppBackEnd. ⚠️ Đừng chuyển phép gộp xuống RouteFeeCalculator: engine cố ý để việc gộp cho nơi gọi, và OrderService / OrderFinService đã gộp trước khi gọi — gộp thêm lần nữa trong engine không sai số nhưng biến một quyết định tường minh thành hành vi ẩn ở hai tầng.

Đọc ma trận giá của một danh mục hàng hóa: tuyến (hàng) × lựa chọn thuộc tính trục (cột).

Danh mục hàng hóa. Loại giá của các ô. Ô ma trận bình thường là FixPrice. Khách sở hữu bảng giá. 0 = khách mặc định. Lưới ĐẦY ĐỦ, phân biệt được ô đã khai giá và ô trống. Trả lưới đầy đủ chứ không phải danh sách dòng giá đang có: ô trống là thứ người quản trị phải nhìn thấy — đơn đi tuyến đó với lựa chọn đó sẽ báo "chưa có giá". Trả dòng thô thì ô trống đơn giản là không xuất hiện, và một tuyến bị bỏ quên trông y hệt một tuyến không tồn tại. Dùng lại quyền Price.GetDefaultPriceList: cùng một việc "xem bảng giá", chỉ khác hình dạng bảng. Đẻ thêm quyền mới nghĩa là mọi vai trò đang xem bảng giá phải được gán lại tay.

Liệt kê các danh mục hàng hóa ĐÃ có bảng giá riêng.

Lọc theo khách sở hữu ô giá. 0 = mọi khách, không phải khách mặc định. Danh sách danh mục kèm số ô giá và số tuyến đã khai. Danh sách này trả lời theo dữ liệu (có ô giá hay không), đúng câu hỏi mà engine đặt ra khi chọn trục. Một danh mục khai PricingMode = RoutePriceList mà chưa có ô nào không nằm trong danh sách này — và đơn của nó vẫn tính theo trọng lượng.

Ghi một lô ô giá của ma trận (tạo / sửa / xoá mềm).

Lô ô giá cần lưu. Kết quả lưu. Message mang cảnh báo khi lần lưu này xoá ô cuối cùng. ⚠️ Ô vắng mặt trong payload là ô KHÔNG ĐỤNG TỚI, không phải ô bị xoá. Muốn xoá thì phải gửi kèm cờ Xoa = true. Đường bảng giá chung suy ra "dòng cần xoá" bằng phép trừ và đó chính là cơ chế đã xoá oan 13 ô giá mỗi lần bấm Lưu (nợ PSVC) — không lặp lại ở đây. ⚠️ Lô rỗng là "không có gì để lưu", KHÔNG phải "xoá sạch bảng giá". Xoá cả bảng đi qua để hậu quả nhìn thấy được trên URL.

Khởi tạo ma trận giá cho một danh mục: sinh đủ ô theo tuyến × lựa chọn của thuộc tính trục.

Danh mục, giá gốc và hệ số theo từng lựa chọn. Kết quả khởi tạo kèm số ô đã sinh. ⚠️ Đây là thao tác đổi cách tính tiền của cả danh mục: ô giá đầu tiên xuất hiện là danh mục chuyển ngay từ nhánh trọng lượng sang nhánh bảng giá riêng, mọi đơn sau đó tra bảng mới. UI phải hỏi lại trước khi bấm. Không phải "sao chép bảng mặc định": bảng chung là tuyến × khoảng trọng lượng, bảng riêng là tuyến × lựa chọn trục — khác hình dạng, không nhân bản được. Ô đã có giá không bị đè.

Xoá bảng giá riêng của một danh mục ⇒ danh mục quay về tính cước theo TRỌNG LƯỢNG.

Danh mục cần xoá bảng giá riêng. Khách sở hữu bảng giá cần xoá. 0 = mọi khách, không phải khách mặc định. Kết quả xoá kèm số ô đã xoá. ⚠️ Sau thao tác này đơn của danh mục vẫn ra tiền, chỉ là tính theo trọng lượng thay vì tra bảng riêng — không lỗi nào bay lên. Đây là đường lùi hợp lệ về nghiệp vụ, nhưng người bấm phải biết hậu quả tiền, nên nó là một endpoint riêng chứ không phải hệ quả phụ của một lần lưu.

Khởi tạo đường dẫn tệp.

Đường dẫn tệp.

Chuyển đổi đường dẫn cục bộ thành URL.

Đường dẫn cục bộ. URL.

Controller quản lý đối soát đơn hàng

Khởi tạo controller

Service quản lý đối soát

Tìm kiếm khách hàng cần đối soát với phân trang

Tham số tìm kiếm Kết quả tìm kiếm khách hàng cần đối soát

Tìm kiếm đơn hàng có thể đối soát với phân trang

Tham số tìm kiếm Loại đối soát (tùy chọn) Kết quả tìm kiếm đơn hàng có thể đối soát

Tìm kiếm đối soát

Tham số tìm kiếm Kết quả tìm kiếm đối soát

Lấy chi tiết đối soát

ID đối soát Chi tiết đối soát

Tạo đối soát mới

Thông tin đối soát Kết quả thao tác

Xác nhận đối soát

ID đối soát Kết quả thao tác

Cập nhật đã chuyển khoản

Thông tin chuyển khoản Kết quả thao tác

Hủy đối soát với thông tin chi tiết

Thông tin hủy đối soát Kết quả thao tác

Hủy đối soát (phương thức cũ - deprecated)

ID đối soát Kết quả thao tác

Upload ảnh chứng từ chuyển khoản

ID đối soát Danh sách file ảnh Kết quả upload

Lấy danh sách ảnh chứng từ chuyển khoản

ID đối soát Danh sách ảnh chứng từ

Xuất Excel danh sách phiếu đối soát

Model xuất Excel Kết quả xuất file

Xuất Excel chi tiết phiếu đối soát

ID phiếu đối soát Model xuất Excel Kết quả xuất file

Tạo hóa đơn thuế mới

Thông tin tạo hóa đơn (CustomerReconciliationSlipId, VatInfoId, Note) Kết quả tạo hóa đơn

Cập nhật trạng thái hóa đơn thuế (Draft hoặc Issued)

Thông tin cập nhật (TaxInvoiceId, Status, InvoiceNumber, InvoiceDate, Files) Kết quả cập nhật

Lấy thông tin hóa đơn thuế theo ID

ID hóa đơn thuế Thông tin hóa đơn thuế

Lấy thông tin hóa đơn thuế theo ID phiếu đối soát

ID phiếu đối soát Thông tin hóa đơn thuế

Xóa hóa đơn thuế (chỉ cho phép xóa khi ở trạng thái NotIssued)

ID hóa đơn thuế Kết quả xóa

Tìm kiếm giao dịch của ví. Service sẽ tự động kiểm tra quyền: chỉ Founder và Accountant mới xem tất cả, user khác chỉ xem ví của mình.

Tham số tìm kiếm Danh sách giao dịch với tổng thu và tổng chi

Lấy chi tiết giao dịch (chỉ cho TransactionType = 4)

ID của giao dịch Chi tiết giao dịch

Lấy thống kê giao dịch theo loại

ID ví Ngày bắt đầu (optional) Ngày kết thúc (optional) Thống kê giao dịch

Lấy lịch sử số dư ví

ID ví Ngày bắt đầu (optional) Ngày kết thúc (optional) Lịch sử số dư ví

Controller quản lý hóa đơn thanh toán chuyển khoản

Tìm kiếm khách hàng có đơn hàng cần tạo hóa đơn thanh toán chuyển khoản

Tham số tìm kiếm Danh sách khách hàng

Lấy danh sách đơn hàng có thể tạo hóa đơn thanh toán của khách hàng

ID khách hàng Danh sách đơn hàng

Tìm kiếm danh sách hóa đơn thanh toán chuyển khoản

Tham số tìm kiếm Danh sách hóa đơn

Lấy chi tiết hóa đơn thanh toán theo ID

ID hóa đơn Chi tiết hóa đơn

Tạo hóa đơn thanh toán chuyển khoản

Thông tin hóa đơn Kết quả tạo hóa đơn

Hủy hóa đơn thanh toán chuyển khoản với thông tin chi tiết

Thông tin hủy hóa đơn Kết quả hủy hóa đơn

Hủy hóa đơn thanh toán chuyển khoản (phương thức cũ - deprecated)

ID hóa đơn Kết quả hủy hóa đơn

Duyệt hóa đơn thanh toán chuyển khoản

Thông tin duyệt hóa đơn Kết quả duyệt hóa đơn

Xuất Excel danh sách phiếu chuyển khoản

Model xuất Excel Kết quả xuất file

Xuất Excel chi tiết phiếu chuyển khoản

ID phiếu chuyển khoản Model xuất Excel Kết quả xuất file

Controller quản lý tài khoản ngân hàng người dùng

Tìm kiếm tài khoản ngân hàng người dùng với phân trang

Tham số tìm kiếm và phân trang Danh sách tài khoản ngân hàng người dùng

Lấy thông tin chi tiết tài khoản ngân hàng theo ID

ID tài khoản ngân hàng Thông tin chi tiết tài khoản ngân hàng

Tạo mới hoặc cập nhật tài khoản ngân hàng

Thông tin tài khoản ngân hàng Kết quả tạo hoặc cập nhật

Xóa tài khoản ngân hàng

Thông tin tài khoản ngân hàng cần xóa Kết quả xóa

Lấy danh sách tài khoản ngân hàng của người dùng hiện tại

Danh sách tài khoản ngân hàng

Controller quản lý hóa đơn VAT từ Tổng cục Thuế

Tìm kiếm hóa đơn VAT

Tham số tìm kiếm Danh sách hóa đơn VAT

Đồng bộ thủ công hóa đơn bán ra từ API Tổng cục Thuế

Khoảng thời gian cần đồng bộ Kết quả đồng bộ

Lấy thông tin đồng bộ gần nhất

Thông tin đồng bộ gần nhất

Model cho request đồng bộ thủ công

Chiều hóa đơn: 1 = Bán ra (Sold), 2 = Mua vào (Purchase). Mặc định là 1.

Controller xử lý các yêu cầu liên quan đến ví điện tử.

Tìm kiếm danh sách các ví điện tử dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tìm kiếm danh sách các giao dịch của ví điện tử dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Lấy danh sách ví cho suggestion (select control).

Từ khóa tìm kiếm (tên, số điện thoại, username). Danh sách tối đa 20 ví.

Lấy thông tin chi tiết của ví điện tử dựa trên ID.

ID ví. Thông tin chi tiết của ví.

Lấy thông tin chi tiết của ví điện tử của người dùng đang đăng nhập.

Thông tin chi tiết của ví.

Chuyển tiền từ ví của người dùng đang đăng nhập sang ví đích. Ví nguồn sẽ được lấy tự động từ người dùng hiện tại.

Thông tin chuyển tiền Kết quả chuyển tiền

Điều chỉnh số dư ví (cân ví) - chỉ dành cho Founder và Accountant. Tạo giao dịch để khớp số dư ví với số dư mong muốn.

ID ví cần điều chỉnh Thông tin điều chỉnh Kết quả điều chỉnh

Tạo mới hoặc cập nhật bản ghi chấm công thủ công (bổ sung khi quên chấm vào/ra).

Thông tin chấm công thủ công. Kết quả xử lý.

Gợi ý giờ chấm ra cho một ca dựa trên thời điểm lấy/giao hàng muộn nhất của lái xe kể từ khi ca bắt đầu. Dùng cho nút "Lấy giờ ra từ đơn hàng" trong dialog chấm bù công.

ID lái xe. Thời điểm ca bắt đầu (giờ vào). Kết quả gợi ý giờ ra kèm cờ có dữ liệu hay không.

Kiểm tra trước xem ca định chấm có bị trùng (chồng lấp thời gian) với ca đã có của cùng nhân viên hay không. Dùng cho FE cảnh báo sớm trong dialog chấm công thủ công và chấm ra bù. Hàng rào chặn thật vẫn nằm ở các API ghi dữ liệu.

ID nhân viên. Giờ vào của ca định ghi (tùy chọn). Giờ ra của ca định ghi (tùy chọn). Id bản ghi đang sửa cần loại trừ (tùy chọn). Kết quả kiểm tra trùng ca.

Chấm ra thủ công cho một bản ghi chưa có giờ ra (admin bổ sung hộ khi lái xe quên chấm ra), cho phép upload ảnh ODO bù. Dùng multipart/form-data.

Thông tin chấm ra thủ công (giờ ra, ODO, ảnh). Kết quả xử lý.

Xoá mềm một bản ghi chấm công. Chỉ Founder — không mở role riêng Attendance.Delete theo yêu cầu chủ dự án (2026-08-19), vì xoá chấm công đổi thẳng số công/kíp của kỳ lương chưa chốt. Frontend cũng chỉ hiện menu xoá cho Founder (userStore.user.IsFounder), nhưng hàng rào thật là attribute này.

Id bản ghi chấm công. Kết quả xử lý.

Import bảng chấm công từ file Excel (máy chấm công vân tay).

File Excel (.xlsx, .xls). Kết quả import kèm thống kê.

Xu?t danh s�ch ch?m c�ng ra file Excel.

Tham s? t�m ki?m. K?t qu? xu?t file Excel.

Lấy tổng hợp số công của tất cả nhân viên theo tháng.

Tháng (1-12). Năm (ví dụ: 2025). Danh sách tổng hợp số công của nhân viên.

Lấy chi tiết công từng ngày của một nhân viên theo tháng.

Tháng (1-12). Năm (ví dụ: 2025). ID nhân viên. Danh sách chi tiết công từng ngày của nhân viên.

Kh?i t?o du?ng d?n t?p.

�u?ng d?n t?p.

Chuy?n d?i du?ng d?n file th�nh URL.

�u?ng d?n file. URL.

Controller d? x? lý các ho?t d?ng liên quan d?n ?ng viên.

Kh?i t?o m?t instance m?i c?a l?p .

D?ch v? x? lý ?ng viên.

Tìm ki?m các ?ng viên d?a trên các tham s? du?c cung c?p.

Các tham s? tìm ki?m. K?t qu? tìm ki?m.

Xóa m?t ?ng viên d?a trên ID.

ID c?a ?ng viên. K?t qu? c?a ho?t d?ng xóa.

L?y thông tin dánh giá c?a m?t ?ng viên d?a trên ID.

ID c?a ?ng viên. Thông tin dánh giá c?a ?ng viên.

C?p nh?t thông tin dánh giá c?a m?t ?ng viên.

Model ch?a thông tin dánh giá c?a ?ng viên. K?t qu? c?a ho?t d?ng c?p nh?t dánh giá.

T?o ?ng viên m?i.

Thông tin ?ng viên. K?t qu? c?a ho?t d?ng t?o ?ng viên.

L?y thông tin ?ng viên theo ID.

ID c?a ?ng viên. Thông tin ?ng viên.

C?p nh?t thông tin ?ng viên.

Thông tin ?ng viên. K?t qu? c?a ho?t d?ng c?p nh?t.

Download CV c?a ?ng viên

ID c?a ?ng viên File CV

L?y content type d?a trên extension file

Extension file Content type

Quản lý cọc trách nhiệm + Tạm ứng lương — Lịch sử giao dịch

Tạo phiếu tạm ứng lương (Expense Pending — chờ duyệt và chi)

Hoàn cọc trách nhiệm (Expense Pending — chờ duyệt và chi)

Lấy lịch sử giao dịch cọc/tạm ứng của NV

Lấy thông tin số dư cọc trách nhiệm của NV

Search giao dịch cọc/tạm ứng (trang quản trị)

Theo dõi cọc trách nhiệm lái xe — danh sách + tổng hợp

Danh sách lái xe kèm trạng thái cọc (Hạn mức / Đã đóng / Đang chờ / Còn thiếu)

Số liệu tổng hợp cọc toàn công ty (theo scope agency của người xem)

Founder xem tất cả (agencyIds = null); còn lại chỉ thấy agency của mình + con cháu

Quản lý đánh giá lái xe (Test Lái / Thử Việc)

Quản lý bảng tra mức lương lái xe

Quản lý cấu hình lương nhân viên

NLĐ tự xem cấu hình lương của mình. Lấy userId từ JWT.

Lấy tất cả cấu hình lương có hiệu lực trong kỳ lương (month/year). Dùng cho form lập phiếu lương khi cần hiển thị nhiều config pro-rata.

Quản lý tiêu chí đánh giá lái xe

Quản lý ngày lễ

Controller d? x? l� c�c ho?t d?ng li�n quan d?n c�ng vi?c.

Kh?i t?o m?t instance m?i c?a l?p .

D?ch v? x? l� c�ng vi?c.

T�m ki?m c�c c�ng vi?c d?a tr�n c�c tham s? du?c cung c?p.

C�c tham s? t�m ki?m. K?t qu? t�m ki?m.

T?o ho?c c?p nh?t th�ng tin c�ng vi?c.

Model ch?a th�ng tin c�ng vi?c. K?t qu? c?a ho?t d?ng t?o ho?c c?p nh?t.

L?y th�ng tin chi ti?t c?a m?t c�ng vi?c d?a tr�n ID.

ID c?a c�ng vi?c. Th�ng tin chi ti?t c?a c�ng vi?c.

X�a m?t c�ng vi?c d?a tr�n ID.

ID c?a c�ng vi?c. K?t qu? c?a ho?t d?ng x�a.

Cấu hình loại nghỉ phép + Quỹ phép nhân viên

Quản lý phiếu nghỉ phép — NV, Manager, HR

Tạo phiếu nghỉ phép

Hủy phiếu nghỉ phép (chỉ khi đang chờ duyệt)

Lấy danh sách đơn nghỉ phép của tôi

Lấy quỹ phép của tôi

Danh sách đơn chờ Manager duyệt

Manager duyệt đơn

Manager từ chối đơn

Danh sách đơn chờ HR duyệt

HR duyệt đơn

HR từ chối đơn

Tìm kiếm tất cả đơn nghỉ phép (admin/HR)

Quản lý Thưởng/Phạt nhân viên

Quản lý Phiếu lương (Payroll)

Lập phiếu lương cho kỳ

Lấy danh sách phiếu lương theo kỳ

Lấy phiếu lương theo ID

Lấy lịch sử phiếu lương theo nhân viên

NLĐ tự xem phiếu lương của mình theo kỳ (month/year). Lấy userId từ JWT, không yêu cầu quyền đặc biệt.

Kỳ + trạng thái phiếu lương gần nhất (khác Bản nháp) của chính người gọi — thẻ "Phiếu lương tháng M" trên đầu Bảng tin. Không số tiền, không tham số: userId lấy từ JWT nên không xem được phiếu của người khác.

Lái xe xem phiếu lương đang chờ xác nhận (nếu có). Không cần tham số — tự tìm phiếu pending mới nhất theo userId từ JWT. Dùng cho Driver App.

KT gửi phiếu lương cho NLĐ xác nhận

NLĐ xác nhận hoặc từ chối phiếu lương

Preview lương ước tính cho 1 nhân viên — không lưu DB. Dùng cho nút "Tính trước" trên form lập phiếu.

Xóa phiếu lương — chỉ cho phép xóa khi ở trạng thái Bản nháp (Draft)

Filter phiếu lương theo SalaryMode trong Search — được xử lý ở Search action

Xuất danh sách phiếu lương ra Excel

NLĐ (trưởng nhóm/QLBC) tự xem doanh số team. Lấy userId từ JWT.

Đ?i m?t kh?u cho ngu?i důng

Thông tin d?i m?t kh?u K?t qu? d?i m?t kh?u

Controller để quản lý Permission Groups (tập hợp các Role)

Xóa Permission Group

Gán Permission cho User

Xóa Permission khỏi User

Lấy danh sách Role trong Permission

Tìm kiếm Permission với phân trang

Lấy tất cả Roles có thể gán cho Permission

Tạo hoặc cập nhật Permission (theo pattern AgencyController)

Lấy thông tin Permission theo ID (trả về PermissionModel)

Cập nhật danh sách Role của Permission (hàm riêng biệt)

PermissionId

Danh sách Role

Controller để quản lý migration từ old role system sang new Permission system

Kiểm tra trạng thái migration

Lấy danh sách Role mới sẽ được tạo

Lấy mapping từ old roles sang Permission Groups

Tạo các Role mới

Tạo Permission Groups mặc định

Migration Users từ old roles sang Permission Groups

Chạy full migration process

Gợi ý tất cả lái xe trong hệ thống, không giới hạn bưu cục. Dùng cho xuất kho và nhập kho.

Đổi mật khẩu cho người dùng

Thông tin đổi mật khẩu Kết quả đổi mật khẩu

API lịch sử thao tác người dùng

Lấy lịch sử thao tác của người dùng

ID người dùng Số lượng bản ghi tối đa (mặc định 50)

Bảng tin nội bộ — màn NGƯỜI SOẠN (docs/plan-bang-tin-noi-bo.md §3.4, §3.8). Mọi action gác bằng InternalNews.Manage | InternalNews.PublishAll (Founder qua tất); role chưa đủ — service kiểm phạm vi từng dòng đối tượng lúc lưu và lúc đăng: vượt phạm vi → 403, bài ngoài phạm vi sửa → 404.

403 ở đây là lời từ chối theo DỮ LIỆU (người có role nhưng chọn đối tượng ngoài cây mình), nên giao diện gọi các action lưu / đăng / ước tính phải khai boQuaChuyenHuong403 để không bị đá khỏi trang đang soạn.

Danh sách bài tôi quản lý: status, kind, keyword trong Search.PredicateObject.

Tạo (Id = 0) / sửa thông tin bài + đối tượng. Ghi đè toàn bộ thông tin; Audiences = null giữ nguyên đối tượng.

Lưu bộ khối của bản đang sửa (thay cả bộ). Trả DraftVersion để gửi lại khi Đăng.

Đăng ngay / hẹn giờ (PublishAt tương lai) / Đăng lại (bài đang đăng; chuông chỉ gửi khi NotifyAgain).

Thu hồi về nháp (bài đã đăng / đã lưu trữ) hoặc huỷ hẹn giờ.

"≈ N người" cho đối tượng đang chọn — đúng tập sẽ nhận chuông.

Dữ liệu ô chọn đối tượng đã lọc theo phạm vi người đăng — màn soạn KHÔNG gọi Permission/*, Agency/* (đòi role miền khác mà trưởng bưu cục không có).

Tìm người để chọn đích danh (≥ 2 ký tự, tối đa 20 người, trong phạm vi người đăng).

Xem trước bản đang sửa (đã lọc HTML) cùng hình chi tiết người đọc.

Bộ khối của bài bảng tin cho BlockEditor — máy chủ quyết loại khối, giao diện không chép.

Thống kê đọc (GĐ D): người nhắm / đã đọc / đã xác nhận + theo đơn vị. Role InternalNews.ViewStats (Founder qua) — KHÔNG phải bó : trưởng đơn vị chỉ có Manage nhận 403.

Danh sách người nhắm: status unread (mặc định) | unacknowledged | all; agencyId 0 = không đơn vị.

Tệp .xlsx trả thẳng (không lưu vào kho media công khai) — 2 trang tính: tổng hợp theo đơn vị, danh sách người nhắm.

Bảng tin nội bộ — đường của NGƯỜI ĐỌC (docs/plan-bang-tin-noi-bo.md §3.3, §3.4): mọi người đăng nhập, không đòi role. Hàng rào là luật đối tượng ở service — bài không được xem trả 404 (không lộ tồn tại). API này cũng là API của app sau này (nợ BT-5), nên chỉ dựa vào JWT.

Bảng tin của tôi (POST vì nhận ): Search.PredicateObject nhận kind, unread, archived, keyword. Ghim lên đầu, rồi mới đăng trước; tối đa 50 bài một trang.

Chi tiết bài (ảnh chụp lúc đăng + tệp mà khối tham chiếu). Không được xem → 404.

Đánh dấu đã đọc — mở bài thì giao diện gọi. Lần sau chỉ đổi lần đọc gần nhất.

"Tôi đã đọc và hiểu" — chỉ với bài bật yêu cầu xác nhận.

Số bài đang đăng tôi được xem mà chưa mở.

Cờ cho giao diện — KHÔNG đòi role (rule quyen-hien-thi mục 4): người không có quyền nhận false.

Tài liệu (pdf/xlsx/docx, 30 MB) và video tệp (mp4/webm, 300 MB) của bài Bảng tin nội bộ — ghi vào kho media chung Media.RootPath\Files\InternalNews\…, URL trên Media.Domain (docs/plan-bang-tin-noi-bo.md §3.5, §6.5). Không có đường đọc nội dung ở đây: người đọc mở thẳng URL kho media (cổng media lo "đăng nhập mới xem", nợ BT-7).

Trần request = trần tệp + 1 MB cho phần còn lại của multipart.

Tải lên một tài liệu của bài (multipart, khoá file, tuỳ chọn title). Kiểm bằng nội dung tệp.

Tải lên một video tệp của bài (multipart, khoá file): mp4, webm — tối đa 300 MB.

Xoá tệp: xoá file trên đĩa rồi xoá dòng. Từ chối khi khối nội dung (nháp hoặc bản đã đăng) còn dùng tệp.

Giao và quản lý chỉ tiêu KPI. Role chỉ mở cửa API — phạm vi giao cho ai theo cây quản lý trực tiếp (§7.3) và phạm vi xem (§3.6) đều ép server-side trong service, không tin FE.

Danh sách chủ thể người gọi giao được chỉ tiêu — nguồn cho ô chọn chủ thể ở màn giao chỉ tiêu.

Có endpoint riêng thay vì để FE gọi User/Search hay Agency/Search: hai đường đó thuộc miền khác và không bó theo §7.3, dùng chúng ở màn KPI là lặp lại đúng lỗi GĐ C (mượn lớp phân quyền của miền này để gác dữ liệu của miền kia). Trả về **chỉ Id và tên**. Nhân viên hay đơn vị Lọc theo tên, bỏ trống thì lấy từ đầu danh sách Số dòng tối đa (mặc định 50, trần 200) Mở cho **mọi role của phân hệ KPI** chứ không riêng role giao chỉ tiêu, vì thứ trả về luôn bị bó bởi phạm vi §7.3 của **chính người gọi**: ai không quản lý ai thì nhận danh sách rỗng, không có gì để lộ. Siết hẹp hơn thì lợi bất cập hại — người chỉ có quyền xem mở đúng màn hình của mình là ăn 403, và interceptor của SPA đá họ ra trang "không có quyền" giữa chừng thay vì hiện một danh sách rỗng có giải thích. Ba đường thao tác dùng chung luật §7.3 (giao chỉ tiêu, chốt lại kỳ, đánh giá quý/năm) đều cần danh sách này — xem .

Tìm kiếm chỉ tiêu — không có Kpi.ViewAll thì chỉ thấy của mình + cấp dưới trực tiếp + đơn vị mình quản lý

Lấy chỉ tiêu theo Id (null nếu ngoài phạm vi xem)

Giao/sửa một dòng chỉ tiêu (Draft lưu lẻ dòng được, response kèm cảnh báo tổng trọng số §7.8)

Xoá chỉ tiêu (xoá mềm — chặn khi kỳ đã chốt)

Chuyển cả bộ chỉ tiêu của một chủ thể trong một kỳ sang Đã giao — chặn cứng khi tổng trọng số ≠ 100% (§7.8)

Copy bộ chỉ tiêu của một chủ thể từ kỳ trước sang kỳ mới (Draft)

Cấu hình thưởng KPI và luồng sinh tiền (§7.5, §7.14).

Một role duy nhất cho cả mẫu bậc thang lẫn dòng cấu hình nhân viên–tháng (KpiBonusPolicy.*, §7.14): cả hai đều là "chuỗi cấu hình đổi được tiền" của §3.10, và tách role ra chỉ tạo ảo giác phân quyền — ai sửa được mẫu thì cũng đổi được số tiền của mọi dòng đang trỏ tới mẫu đó.

Bảng tính thử — hiện tiền sẽ sinh, không ghi gì. Chạy được cả khi công tắc còn tắt (§5.1 bước 4).

Sinh/cập nhật thưởng thật cho một kỳ — idempotent. Đường thủ công; chốt kỳ cũng tự gọi.

Khách hàng không hoạt động theo sale — dữ liệu "đánh dấu để dễ quản lý" mà plan §7.4 yêu cầu.

Đặt cùng họ với KpiProgressController và dùng chung role KpiAssignment.Search: cùng một đối tượng người dùng (người quản lý theo dõi chỉ tiêu sale), cùng một luật phạm vi (IKpiVisibilityResolver), và số ở đây phải khớp thẻ sales.active-customers trên màn theo dõi. Tách role riêng chỉ tạo thêm chỗ để cấu hình sai. Phạm vi ép trong service, role chỉ mở cửa API. ⚠️ Dữ liệu trả về là **danh bạ CRM** (tên + số điện thoại khách), nên service còn đòi thêm một điều kiện nữa mới cho xem ngoài đội của mình: Founder hoặc role Customer.Search. Người chỉ có Kpi.ViewAll xem được KPI của mọi người nhưng **không** vì thế mà đọc được cả tệp khách hàng — xem chú thích trong CustomerActivityService.GetInactiveInScopeAsync. ⚠️ Endpoint này **chỉ đọc**. Việc giải phóng khách khỏi sale không chăm ("nhả quản lý") là nợ `KPI-1`, làm ở đợt riêng — đừng thêm hành động ghi vào đây.

Danh sách khách hàng **không hoạt động** trong phạm vi người đang đăng nhập được xem.

Thời điểm chốt; bỏ trống lấy hiện tại Lọc thêm về một sale; chỉ thu hẹp kết quả, không mở thêm quyền

Quản trị danh mục chỉ số KPI

Tìm kiếm danh mục chỉ số

Lấy chỉ số theo Id

Tạo hoặc cập nhật chỉ số

Xoá chỉ số (xoá mềm — chặn khi đã có chỉ tiêu tham chiếu)

Chốt kỳ KPI thủ công và nhập tay giá trị thực (plan §3.4).

Đường tự động là Hangfire job KpiPeriodCloseJob chạy mùng 1; controller này là đường thủ công cho hai ca: chốt sớm/chốt bù một chủ thể, và chốt lại trong cửa sổ Kpi.RecloseWindowDays khi dữ liệu đơn hàng còn điều chỉnh. Role KpiAssignment.Close chỉ **mở cửa API**; ai chốt được cho ai vẫn do luật phạm vi §7.3 quyết trong service. Job không đi qua đây và không mở endpoint nào mới (§3.10).

Chốt (hoặc chốt lại) kỳ của một chủ thể.

Chủ thể và kỳ cần chốt

Nhập tay giá trị thực cho một chỉ tiêu trước khi chốt kỳ; job chốt không ghi đè giá trị này.

Chỉ tiêu, giá trị và lý do nhập tay (lý do bắt buộc)

Tình trạng cửa sổ chốt lại của một kỳ — màn chốt kỳ dùng để nói "còn N ngày" trước khi bấm.

Chỉ đọc. Truyền và thì trả thêm chủ thể đó đã chốt kỳ chưa, và chỉ khi chủ thể nằm trong phạm vi §7.3 của người gọi. Năm của kỳ Tháng của kỳ (1-12) Loại chủ thể, bỏ trống nếu chỉ cần thông tin mức kỳ Id chủ thể, bỏ trống nếu chỉ cần thông tin mức kỳ

Đánh giá KPI định kỳ quý/năm (plan §7.1) — tầng đọc + kết luận của con người, không sinh tiền.

Phạm vi XEM (§3.6) và phạm vi THAO TÁC (§7.3) tách hẳn nhau ở đây: người có Kpi.ViewAll đọc được bản đánh giá của cả công ty, nhưng chỉ quản lý trực tiếp (hoặc Founder) mới viết và chốt được. Role dưới đây chỉ mở cửa API, luật phạm vi nằm trong service.

Danh sách bản đánh giá định kỳ.

Một bản đánh giá kèm bảng tổng hợp điểm sống của kỳ.

Bảng tổng hợp điểm KPI quý/năm của một chủ thể — số sống, chưa gắn với bản đánh giá nào.

1 nhân viên, 2 đơn vị User.Id hoặc Agency.Id 1 quý, 2 năm Năm của kỳ Quý 1-4; bỏ qua khi kỳ năm

Tạo hoặc sửa bản đánh giá (chỉ khi còn Draft).

Chốt bản đánh giá — snapshot điểm tổng hợp tại thời điểm chốt, sau đó không sửa được nữa.

Xoá bản đánh giá còn Draft.

Theo dõi KPI trong kỳ — giá trị thực tính tại thời điểm gọi, chưa chốt kỳ (plan §3.4).

Dùng chung role KpiAssignment.Search với màn danh sách chỉ tiêu: cùng một tập dữ liệu, chỉ khác cách trình bày, nên tách role riêng chỉ tạo thêm chỗ để cấu hình sai. Phạm vi xem ép trong service theo §3.6 — role chỉ mở cửa API.

Tiến độ KPI của một kỳ, gộp theo chủ thể.

Năm của kỳ; bỏ trống lấy năm hiện tại Tháng của kỳ 1-12; bỏ trống lấy tháng hiện tại Lọc thêm theo loại chủ thể: 1 nhân viên, 2 đơn vị Lọc thêm theo một chủ thể; chỉ thu hẹp kết quả, không mở thêm quyền

Controller demo cho New Media Services

Upload ảnh đơn giản (không lưu database)

File ảnh Loại ảnh (avatar, product, general, etc.) URL ảnh đã xử lý

Upload nhiều ảnh cùng lúc

Danh sách file ảnh Loại ảnh Danh sách kết quả

Upload video đơn giản

File video Loại video URL video đã xử lý

Upload media tự động detect loại (ảnh hoặc video)

File media Kết quả xử lý

Upload ảnh cho attendance (có lưu database)

File ảnh ID chấm công Kết quả xử lý

Upload ảnh cho truck activity

File ảnh ID hoạt động xe Kết quả xử lý

Validate file có phải ảnh hợp lệ không

File cần kiểm tra True nếu hợp lệ

Convert SystemPath thành URL hiển thị

Đường dẫn hệ thống URL hiển thị

API batch migration: Tạo ảnh JPEG (og:image) từ thumbnails WebP cũ Dùng 1 lần để cập nhật dữ liệu cũ, sau đó có thể xóa controller này

Batch tạo ảnh JPEG cho tất cả Posts có thumbnail WebP nhưng chưa có OgImage

Batch tạo ảnh JPEG cho tất cả Products có thumbnail WebP nhưng chưa có OgImage

Batch tạo ảnh JPEG cho tất cả JobPosts có thumbnail WebP nhưng chưa có OgImage

Chạy migration cho tất cả (Posts + Products + JobPosts)

Chuyển URL thumbnail WebP thành đường dẫn file hệ thống, tạo bản JPEG, trả về URL mới

Chuyển URL (Domain + relative path) → System path (RootPath + relative path) VD: https://ladaexpress.vn/Images/PostThumb/2005/5/26/optimized/image.webp → C:\uploads\Images\PostThumb\2005\5\26\optimized\image.webp

Controller to handle operations related to pictures. Updated to use UnifiedMediaService from Framework.

Initializes a new instance of the class.

Unified media service from Framework.

Uploads a picture for post content.

The picture file to upload. The result of the upload operation.

Ảnh bìa + ảnh khối Hình ảnh / Bộ ảnh của bài Bảng tin nội bộ — thư mục Images\InternalNews\… trong kho media chung (docs/plan-bang-tin-noi-bo.md §3.5, §6.5). Cùng bó role với màn quản trị bảng tin.

Uploads a picture for training lesson content.

The picture file to upload. The result of the upload operation.

Tải lên ảnh dùng chung cho các trang cấu hình hệ thống (ví dụ ảnh QR tải app khách hàng).

Tệp ảnh cần tải lên. Kết quả tải lên kèm URL tuyệt đối của ảnh.

Lấy danh sách đơn hàng thu người gửi nhưng không có SourceCashierId

Từ ngày (optional) Đến ngày (optional) Trang (default: 1) Số bản ghi/trang (default: 50)

Lấy tổng quan các rủi ro đơn hàng (số đơn, tổng tiền)

Từ ngày (optional) Đến ngày (optional)

Lấy danh sách đơn hàng thu người nhận nhưng không có DestCashierId

Từ ngày (optional) Đến ngày (optional) Trang (default: 1) Số bản ghi/trang (default: 50)

Lấy tổng quan các đơn hàng thu người nhận thiếu DestCashier (số đơn, tổng tiền)

Từ ngày (optional) Đến ngày (optional)

Lấy danh sách đơn hàng thu cả 2 đầu nhưng thiếu SourceCashierId hoặc DestCashierId

Từ ngày (optional) Đến ngày (optional) Trang (default: 1) Số bản ghi/trang (default: 50)

Lấy tổng quan các đơn hàng thu cả 2 đầu thiếu Cashier (số đơn, tổng tiền)

Từ ngày (optional) Đến ngày (optional)

Hồ sơ công khai của bưu cục (docs/plan-buu-cuc.md §3.5, GĐ A1).

Role chỉ mở cửa API. Phạm vi bưu cục (Branch.Manager chỉ bưu cục của mình) và quyền theo nhóm trường đều ép trong — không tin FE. Lỗi trả đúng HTTP status theo (403/404/409/422), body vẫn là AgencyProfileResult (Result, Message, ErrorCode…). apiClient của SPA chỉ nhận 2xx — service FE phải bắt riêng.

Danh sách hồ sơ — 200 trả thẳng SmartTableResult như mọi màn danh sách; 403 khi không có phạm vi.

Chi tiết hồ sơ + điều kiện đăng + cờ quyền. 403 ngoài phạm vi, 404 chưa có hồ sơ.

Tạo hồ sơ nháp. 409 PROFILE_ALREADY_EXISTS, 422 AGENCY_NOT_BRANCH / INVALID_DISPLAY_NAME.

Sửa theo nhóm trường. 403 FORBIDDEN_FIELD kèm tên nhóm; 409 VERSION_CONFLICT kèm Current; 422 lỗi dữ liệu.

Công bố / tạm ngưng (SetStatus) hoặc đóng (Close). 422 INVALID_TRANSITION / PUBLISH_PRECONDITION_FAILED kèm Missing.

Mở lại hồ sơ đã đóng về nháp.

Giờ làm việc đủ 7 ngày — Branch.Manager sửa trực tiếp bưu cục của mình.

Ngoại lệ giờ một ngày (thêm/sửa/gỡ).

Ngoại lệ giờ cho nhiều bưu cục một lần (GĐ D — nghỉ lễ). Một ngày hoặc khoảng ≤ 31 ngày; mỗi bưu cục có thay đổi được một phiên bản + nhật ký, tất cả một transaction. Một bưu cục ngoài phạm vi → 403 cả lần gọi, không ghi gì.

Branch.Manager gửi đề xuất sửa một nhóm trường chỉ-đề-xuất (Toạ độ, Giới thiệu/hỏi đáp, Tuyến, Ghi chú vùng, Nhân sự — GĐ D). Dữ liệu kiểm ngay bằng luật của đường ghi; 422 NO_CHANGES khi giống hồ sơ hiện tại.

Hàng đợi đề xuất kèm bảng so sánh hiện tại ↔ đề xuất. Người duyệt thấy mọi bưu cục; Branch.Manager chỉ thấy bưu cục mình (ép ở truy vấn). status: 1 chờ, 2 đã duyệt, 3 từ chối, 4 bị thay; trống = mọi trạng thái.

Duyệt: áp vào hồ sơ qua đúng đường ghi sẵn có (luật nội dung chạy lại), sinh một phiên bản. Chỉ người phạm vi toàn mạng lưới. 409 CHANGE_REQUEST_CLOSED khi đề xuất đã xử lý; 409 VERSION_CONFLICT khi hồ sơ đổi.

Từ chối kèm lý do bắt buộc — hồ sơ không đổi.

Báo cáo bưu cục một tháng (GĐ D): lượt + phiên theo bưu cục × loại sự kiện (nguồn AgencyWebEventDaily), nguồn truy cập / trang (sự kiện thô). Branch.Manager chỉ thấy bưu cục mình.

Xuất CSV (UTF-8 BOM, ô chữ chống công thức) một bảng của báo cáo: view = agencies | daily | sources | pages. Thành công trả file; lỗi trả vỏ JSON đúng HTTP status như mọi endpoint của miền.

Thay toàn bộ tuyến. 422 INVALID_ROUTE_PAGE nếu Product không phải trang dich-vu/.

Thêm/sửa nhân sự hiển thị.

Gỡ nhân sự hiển thị.

Sắp lại thứ tự mọi nhân sự hiển thị trong một phiên bản — gửi đủ đúng tập nhân sự hiện có.

Tải MỘT ảnh (multipart/form-data: File + các trường của ). Loại ảnh xét theo nội dung (JPEG/PNG/WebP), ≤ 10 MB, bỏ EXIF/GPS, tên file server sinh. Branch.Manager tải lên → ảnh chờ duyệt. 422 INVALID_MEDIA khi file giả/quá lớn; 403 FORBIDDEN_FIELD Media khi không có quyền.

Sửa vai / alt / chú thích / cờ ảnh thật / thứ tự của một ảnh. 404 MEDIA_NOT_FOUND nếu ảnh không thuộc bưu cục.

Gỡ một ảnh (xoá mềm) + gỡ tham chiếu ảnh Open Graph / chân dung nhân sự trong cùng transaction.

Sắp lại thứ tự mọi ảnh của một vai. Branch.Manager chỉ sắp được thư viện ảnh (Gallery).

Duyệt / bỏ duyệt ảnh — chỉ ảnh đã duyệt lên trang công khai và được tính điều kiện công bố #5.

Xem ảnh CHỜ DUYỆT (nợ BC-14): file không nằm trong thư mục media công khai; Get cấp cho người đã qua phạm vi bưu cục một URL tới đây kèm vé ký HMAC hết hạn sau 1 giờ. Không đăng nhập vì thẻ <img> không gửi được header Authorization — vé chính là quyền. Sai vé/hết hạn/ảnh đã gỡ → 404 như nhau.

Đổi slug. 409 SLUG_TAKEN nếu trùng hồ sơ khác hoặc lịch sử slug của bưu cục khác; 422 INVALID_SLUG.

Lịch sử phiên bản (không kèm ảnh chụp), mới nhất trước; start/pageSize phân trang (mặc định 50, tối đa 200).

Một phiên bản kèm ảnh chụp — để xem trước khi khôi phục. 404 VERSION_NOT_FOUND.

Khôi phục nội dung một phiên bản thành phiên bản MỚI. Không đổi trạng thái công bố, slug, ảnh. Phần dữ liệu cũ vi phạm luật hiện hành giữ nguyên hiện tại, liệt kê ở Notices.

Trần một request tải ảnh: ảnh 10 MB + các trường form + vỏ multipart.

Danh mục chọn: tỉnh bộ 2 cấp, trang tuyến, loại hàng, chi nhánh chưa có hồ sơ (chỉ trả cho người có Update). Mở cho mọi role của các trang dùng nó — danh sách (Search), chi tiết (Get/ManageOwn), hộp thoại tạo hồ sơ (Update); dữ liệu không nhạy cảm.

Cờ mức trang. CỐ Ý không gác role (rule quyen-hien-thi): câu "tôi được thấy gì" phải trả lời được cho cả người không có quyền nào — họ nhận toàn false.

Trang "Quản trị nhượng quyền" — gộp Bảng giá nhượng quyền, Quản trị bảng giá, Nội dung cổng và Cấu hình trợ lý thành bốn tab, chỉ Founder và nhóm "Quản lý mạng lưới" xem được ().

Không có endpoint dữ liệu riêng: mỗi tab gọi đúng controller của màn cũ (FranchisePrice, FranchisePortalSection, FranchisePortalFile, FranchisePortalAssistant). Menu mang-luoi/quan-tri-nhuong-quyen khai đúng role của cờ trang (GopMenuQuanTriNhuongQuyen.sql) — đổi role ở thì sửa cả menu.

Cờ trang và cờ từng tab trong MỘT lời gọi. CỐ Ý không gác role (rule quyen-hien-thi): người không có quyền vẫn hỏi được và nhận toàn false.

Tham số mục "Kế hoạch kinh doanh" của cổng nhượng quyền (GĐ M, plan cổng §3.13, §6.24) — màn /mang-luoi/bang-gia-nhuong-quyen/ke-hoach: năm dòng sản lượng theo bậc phường + bộ tham số chung + ô tính thử. Dữ liệu nội bộ, chỉ phục vụ SPA quản trị.

Cùng hai bó quyền với bảng giá phường (§6.24 mục 5 — không role mới): FranchisePrice.Export — xem + tính thử; FranchisePrice.Manage — xem, tính thử và sửa. Menu mang-luoi/bang-gia-nhuong-quyen/ke-hoach khai đúng hợp hai role này (SeedMenuKeHoachKinhDoanh.sql). Service kiểm lại role — attribute ở đây là lớp đầu, không phải lớp duy nhất. Tính thử không nhận Id mã truy cập nào.

Cờ hiển thị cho giao diện. CỐ Ý không gác role (rule quyen-hien-thi): người không có quyền nào vẫn hỏi được và nhận toàn false để giao diện ẩn nút.

Cả bộ tham số kèm dấu phiên bản cho form sửa.

Sửa cả bộ (năm bậc + tham số) trong một lần; dấu Stamp lệch → từ chối.

Tính thử với số phường mỗi bậc + tham số đang sửa — không ghi gì, không đọc mã nào.

Đăng ký tư vấn nhượng quyền bưu cục — từ website (/nhuong-quyen) hoặc nhân viên nhập tay cho người nhắn tin, gọi tổng đài — tách khỏi lead khách gửi hàng (docs/plan-nhuong-quyen-website.md §3.1, §6.2).

Hai bó quyền (seed SeedRoleLeadNhuongQuyen.sql): FranchiseLead.Search — xem, sửa thông tin, đổi trạng thái đăng ký MÌNH phụ trách; nhập tay đăng ký mới (tự phụ trách). FranchiseLead.Manage — thấy tất cả, giao người phụ trách, xuất Excel. Phạm vi ép trong service (), không dựa vào giao diện: đăng ký ngoài phạm vi trả 404 như không tồn tại. Đổi role ở đây thì sửa cả .

Cờ hiển thị cho giao diện. CỐ Ý không gác role (rule quyen-hien-thi): người không có quyền nào vẫn hỏi được và nhận toàn false để giao diện ẩn nút.

Danh sách đăng ký trong phạm vi người gọi. Search.PredicateObject: globalSearch, status, provinceCode, picId (0 = chưa giao), channel, fromDate, toDate (ngày gửi), updatedFromDate, updatedToDate (ngày cập nhật gần nhất), portalSeenFromDate, portalSeenToDate (ngày khách vào xem Cổng nhượng quyền gần nhất, §6.28) — đều yyyy-MM-dd; idleMinDays, idleMaxDays, openOnly (khoá của ô báo cáo tồn đọng, ). Sort.Predicate: CreatedTime (mặc định, mới trước), UpdatedTime, PortalLastSeenAt, Id, FullName, Status, ProvinceName, PicUserName.

Báo cáo tồn đọng (tab "Tồn đọng" của màn /dang-ky-nhuong-quyen): trạng thái × thời gian chờ theo tỉnh đăng ký, và tỉnh × trạng thái — trong phạm vi người gọi, cùng bộ lọc với search (thường là channel, picId, fromDate/toDate). Bấm vào ô thì giao diện gọi search thêm khoá status, provinceCode, idleMinDays/idleMaxDays, openOnly của ô đó.

Các đoạn trạng thái theo thời gian của nhiều đăng ký ({ Ids: [...] }, tối đa 600) — thanh của biểu đồ Gantt trang lịch hẹn (plan cổng §6.30). Id ngoài phạm vi người gọi bị bỏ qua: kết quả chỉ có đăng ký người gọi xem được.

Danh mục cho ô lọc và form nhập tay: trạng thái, tỉnh (kèm khac), tình trạng doanh nghiệp, kênh tiếp nhận — giao diện đọc ở đây, không chép danh sách sang JS. Cùng bó role với search vì chỉ có nghĩa khi danh sách đọc được.

Chi tiết một đăng ký (kèm câu đồng ý, UTM, trang gửi); 404 khi không có hoặc ngoài phạm vi.

Lịch sử cập nhật của một đăng ký, mới nhất trước: tạo, sửa thông tin, đổi trạng thái, giao người phụ trách, ghi chú. Cùng phạm vi với {id} — 404 khi không có hoặc ngoài phạm vi.

Nhập tay một đăng ký cho người nhắn tin hoặc gọi tổng đài; trả Id của bản ghi mới. Người chỉ có FranchiseLead.Search tự phụ trách đăng ký mình nhập (PicId gửi lên bị bỏ qua).

Sửa thông tin người đăng ký (không đổi trạng thái, người phụ trách).

Đổi trạng thái kèm ghi chú.

Giao người phụ trách (PicId rỗng/0 = bỏ giao).

Giao cùng một người phụ trách cho nhiều đăng ký ({ Ids: [...], PicId }, tối đa ) — các dòng đang chọn trên danh sách. Id ngoài phạm vi bị bỏ qua và đếm riêng; người được giao không hợp lệ thì không đăng ký nào đổi.

Người có thể được giao: giữ Search hoặc Manage, còn làm việc.

Xuất Excel theo cùng bộ lọc với danh sách (bỏ qua phân trang).

Tham số bốn bậc gói vùng phủ POINT / HUB / ZONE / REGION (GĐ K, plan cổng §6.16, §6.17) — màn /mang-luoi/bang-gia-nhuong-quyen/goi. Dữ liệu nội bộ, chỉ phục vụ SPA quản trị.

Cùng hai bó quyền với bảng giá phường (): FranchisePrice.Export — xem; FranchisePrice.Manage — xem và sửa. Menu mang-luoi/bang-gia-nhuong-quyen/goi khai đúng hợp hai role này (SeedMenuGoiGiaNhuongQuyen.sql, đổi nhãn ở M202610151520). Service kiểm lại role — attribute ở đây là lớp đầu, không phải lớp duy nhất.

Cờ hiển thị cho giao diện. CỐ Ý không gác role (rule quyen-hien-thi): người không có quyền nào vẫn hỏi được và nhận toàn false để giao diện ẩn nút.

Mọi bậc theo thứ tự ngưỡng kèm dấu phiên bản cho form sửa.

Sửa cả bộ bậc trong một lần — dải phường các bậc phải liền nhau.

Mã truy cập Cổng nhượng quyền: người phụ trách một đăng ký nhượng quyền tạo mã cho khách đó, mở/khoá từng mục, gia hạn, thu hồi, xem dấu vết (docs/plan-cong-nhuong-quyen.md §3.2, GĐ A; mã gắn vào đăng ký từ GĐ L, §6.23 — giao diện là khối "Mã truy cập" của màn Đăng ký nhượng quyền).

Hai bó quyền (seed SeedCongNhuongQuyen.sql; nhóm quyền "Quản lý mạng lưới" / "Mạng lưới 2" — §6.23): FranchisePortal.Sale — mọi thao tác trên mã của đăng ký MÌNH phụ trách. FranchisePortal.Manage — thấy mọi mã. Phạm vi ép trong service (), không dựa vào giao diện: mã ngoài phạm vi trả 404 như không tồn tại. Mã rõ chỉ có ở create và {id} — luôn kèm no-store. Đổi role ở đây thì sửa cả và AllowRoles của menu.

Cờ hiển thị cho giao diện. CỐ Ý không gác role (rule quyen-hien-thi): người không có quyền nào vẫn hỏi được và nhận toàn false để giao diện ẩn nút.

Danh sách mã trong phạm vi người gọi — ô chọn mã "Hỏi thử" của màn Cấu hình trợ lý. Search.PredicateObject: globalSearch, status (active / expiring / expired / revoked), provinceCode, priceScope (none / below), fromDate, toDate (yyyy-MM-dd). Sort.Predicate: CreatedTime (mặc định, mới trước), ExpiresAt, CustomerName, LastAccessAt. Mỗi dòng kèm tóm tắt phạm vi giá (PriceScopeState, PriceScopeLabel, PriceScopeProvinceName).

Chi tiết một mã kèm MÃ RÕ, trạng thái mở/khoá từng mục, lịch sử gần nhất; 404 khi không có hoặc ngoài phạm vi.

Tạo mã cho khách của một đăng ký nhượng quyền; trả mã rõ NQ-XXXX-XXXX và Id. Chỉ người phụ trách đăng ký tạo được, và đăng ký chưa có mã chưa thu hồi (§6.23 mục 3).

Mở các mục cho mã (chỉ mục đang bật).

Khoá lại các mục của mã.

Gắn phạm vi giá: các phường/xã (được nhiều tỉnh); gửi danh sách trống = gỡ. Gói vùng phủ tự xếp theo số phường (GĐ K). Khách chỉ xem lại đúng thứ đã gắn ở mục bảng giá của cổng. CỐ Ý dùng role của cổng, không đòi thêm FranchisePrice.*: sale là người báo giá cho khách của mình (plan cổng §6.10, CNQ-45).

Tỉnh/thành phố có giá ở phiên bản giá hiện hành (không đòi vùng phủ — plan cổng §6.26) cho ô chọn của khối "Phạm vi giá". Ba nguồn price-options/* gác bằng role của cổng như price-scope — sale không có FranchisePrice.* vẫn chọn được phường (CNQ-39).

Bốn bậc gói vùng phủ — drawer báo gói theo số phường đang chọn (GĐ K).

Phường/xã của một tỉnh CÓ GIÁ ở phiên bản giá hiện hành; lọc theo tên (không dấu).

Mở mọi mục đang bật cho mã.

Gia hạn thêm 7 ngày, tính từ mốc muộn hơn giữa bây giờ và hạn hiện tại.

Thu hồi mã ngay lập tức — mọi phiên đang mở của khách bị đóng.

Lịch sử thao tác của một mã, mới nhất trước; 404 khi không có hoặc ngoài phạm vi.

Dấu vết của khách dùng mã này: một trang sự kiện (mới trước) + tổng thời gian xem theo mục; 404 khi không có hoặc ngoài phạm vi.

Transcript hỏi-đáp của khách với trợ lý AI (tab Hỏi đáp, GĐ G): một trang tin nhắn (mới trước) + số câu đã hỏi; 404 khi không có hoặc ngoài phạm vi — sale chỉ đọc được transcript của mã thuộc đăng ký mình phụ trách.

Màn "Cấu hình trợ lý" của Cổng nhượng quyền (docs/plan-cong-nhuong-quyen.md §3.6, GĐ G): nhà cung cấp / model, hạn mức câu hỏi, trần ngữ cảnh, văn bản nền, thông báo sale, và "Hỏi thử". Chỉ FranchisePortal.Manage (Founder vượt mọi kiểm tra) — kiểm lần hai trong service bằng cờ CanConfigure. Không endpoint nào trả API key.

Cờ hiển thị cho giao diện. CỐ Ý không gác role (rule quyen-hien-thi): người không có quyền vẫn hỏi được và nhận false.

Hỏi trợ lý một câu với ngữ cảnh của một mã — mã ngoài phạm vi trả 404. Gọi nhà cung cấp trả phí: câu hỏi tối đa 1.000 ký tự, trần thời gian 60 giây; không lưu transcript, không trừ lượt của khách.

Tệp riêng tư của Cổng nhượng quyền — tài liệu (pdf/xlsx/docx) và video tệp (mp4/webm) — lưu trên ổ đĩa dưới AppConfig FranchisePortal.PrivateRootPath, ngoài web root của media (docs/plan-cong-nhuong-quyen.md §6.5).

Controller này chỉ tải lên / liệt kê / xoá cho biên tập viên; KHÔNG có đường đọc nội dung tệp — khách đọc qua /thong-tin-nhuong-quyen/tep/{id} của website sau khi kiểm mã truy cập (GĐ C). Mọi action đòi FranchisePortal.Content hoặc FranchisePortal.Manage.

Trần request = trần tệp + 1 MB cho phần còn lại của multipart.

Tải lên một tài liệu (multipart, khoá file): pdf, xlsx, docx — tối đa 30 MB. Kiểm bằng nội dung tệp, không tin phần mở rộng. PDF được trích văn bản cho trợ lý AI.

Tải lên một video tệp (multipart, khoá file): mp4, webm — tối đa 300 MB.

Tệp của một mục; bỏ sectionId = mọi tệp.

Xoá một tệp (bản ghi và tệp trên đĩa). Từ chối khi tệp đang là audio thuyết minh của một mục.

Mục của Cổng nhượng quyền riêng tư /thong-tin-nhuong-quyen (docs/plan-cong-nhuong-quyen.md §3.4, GĐ A): danh sách, siêu dữ liệu, thứ tự, bật/tắt; và từ GĐ E khối nội dung của mục — đọc / lưu bản đang sửa, xuất bản, cấp link xem trước (§3.9, §6.8). Khối vẫn nằm ở topic vật chủ nhưng KHÔNG đi qua api/Topic nữa (CNQ-12).

Mọi action dữ liệu đòi FranchisePortal.Content hoặc FranchisePortal.Manage (seed SeedCongNhuongQuyen.sql). Đổi role ở đây thì sửa cả và AllowRoles của menu cong-nhuong-quyen/noi-dung.

Câu từ chối cấp link xem trước khi công tắc cổng đang tắt (website trả 404 cho mọi đường của cổng).

Cờ hiển thị cho giao diện. CỐ Ý không gác role (rule quyen-hien-thi): người không có quyền nào vẫn hỏi được và nhận toàn false để giao diện ẩn nút.

Mọi mục cổng theo thứ tự hiển thị, kèm trạng thái xuất bản và thuyết minh.

Bộ icon và các đoạn đường dẫn dành riêng cho form mục — giao diện đọc ở đây, không chép sang JS.

Chi tiết một mục; 404 khi không có.

Tạo một mục nội dung (kèm topic vật chủ của nó); trả Id của mục mới.

Sửa tiêu đề, đường dẫn, tóm tắt, icon của mục — không chạm khối nội dung.

Sắp lại thứ tự: gửi Id của TOÀN BỘ mục theo thứ tự mới.

Tắt mục: ẩn với mọi mã truy cập, kể cả mã đã được mở mục này.

Bật lại mục — mã nào đã được mở mục này thì xem lại được ngay.

Bản ĐANG SỬA của khối nội dung một mục, kèm bộ khối của mục, dấu phiên bản, trạng thái xuất bản và cảnh báo khối trỏ tới tệp không còn dùng được. Mục bảng giá trả HasBlocks = false. 404 khi không có mục.

Lưu bản đang sửa: thay TOÀN BỘ khối của mục. Không đổi gì trên trang khách đang thấy. Khối sai, hoặc khối trỏ tới tệp không thuộc đúng mục này, trả 400 kèm câu chỉ rõ khối thứ mấy. Version là dấu DraftVersion lấy từ GET {id}/blocks — có người lưu khối sau đó thì không ghi (DraftChanged = true) thay vì đè mất bản của họ.

Xuất bản bản đang sửa thành bản khách thấy trên cổng (cần ít nhất 1 khối). Version là dấu DraftVersion lấy từ GET {id}/blocks — có người lưu khối sau đó thì không xuất bản (DraftChanged = true).

Cấp link xem trước bản ĐANG SỬA của đúng mục này trên website (hạn 30 phút; link cấp trước vẫn sống). Link không cần mã truy cập và không ghi dấu vết; chỉ mở được khi cổng đang bật — công tắc tắt thì từ chối kèm câu giải thích, thay vì đưa biên tập viên tới trang 404 chung của website (bấm thật GĐ I+J).

Tải một ảnh cho khối nội dung của mục (slide, bộ ảnh, ảnh bìa video…) — multipart, khoá file. Ảnh đi media công khai như ảnh của topic (plan §3.4, nợ CNQ-3); role của cổng là đủ, không cần Picture.UploadTopicContentPicture.

Bảng giá nhượng quyền bưu cục — dữ liệu nội bộ, chỉ phục vụ SPA quản trị.

Hai bó quyền, không mượn miền khác (seed SeedRoleBangGiaNhuongQuyen.sql): FranchisePrice.Manage — tải mẫu, kiểm/lưu file giá, lịch sử phiên bản, thêm/sửa tay từng dòng (chỉ quản trị). FranchisePrice.Export — chọn tỉnh, phường/xã, xuất bảng giá (sale nhượng quyền, quản lý khu vực); Manage cũng xuất được. Menu mang-luoi/bang-gia-nhuong-quyen và .../quan-tri khai đúng hợp của các role này (SeedMenuBangGiaNhuongQuyen.sql) — đổi role ở đây thì sửa cả script menu và . File trả thẳng qua File() với no-store, không lưu ra wwwroot: giá nhượng quyền không được nằm ở URL công khai.

Cờ hiển thị cho giao diện. CỐ Ý không gác role (rule quyen-hien-thi): người không có quyền nào vẫn hỏi được và nhận toàn false để giao diện ẩn nút.

Mọi tỉnh/thành phố 2 cấp để chọn khi tải mẫu; IsDefault = thuộc vùng phủ hiện tại.

Tải file mẫu gồm toàn bộ phường/xã của các tỉnh được chọn.

Kiểm toàn bộ file. Có lỗi → danh sách lỗi theo dòng; không lỗi → bản xem trước. Không ghi gì.

Xác nhận: kiểm lại toàn bộ file rồi lưu thành phiên bản mới, đặt làm hiện hành.

Lịch sử phiên bản, mới nhất trước — phiên bản cũ giữ lại để tra.

Phiên bản hiện hành (mã, ngày hiệu lực, tham số) — đầu trang xuất; 204 khi chưa upload lần nào.

Các tỉnh có phường/xã có giá trong phiên bản hiện hành.

Phường/xã có giá của một tỉnh. Search.PredicateObject: ProvinceId (bắt buộc), Keyword (tìm theo tên, có dấu hay không dấu đều ra).

Xuất bảng giá Excel. Không tích phường/xã nào → cả tỉnh, không có phần tổng.

Chi tiết một dòng giá của phiên bản hiện hành để nạp form sửa; 404 khi phường/xã không có giá.

Phường/xã 2 cấp của một tỉnh chưa có giá trong phiên bản hiện hành — ô chọn của form thêm dòng.

Thêm tay một dòng giá vào phiên bản hiện hành. Ô sai → 400 kèm Errors[] theo tên trường.

Sửa tay một dòng giá của phiên bản hiện hành; Stamp lệch (người khác vừa sửa) → 400.

Phiếu đối soát tháng bưu cục nhượng quyền (docs/bang-gia-noi-bo/SPEC.md §3.6, §3.8 api/FranchiseSettlement).

Bưu cục chỉ thấy / xác nhận / tải bảng kê phiếu của chính mình — service ép phạm vi phía máy chủ, kể cả đường xuất Excel.

Cờ hiển thị — không đòi role.

Danh sách phiếu. Khoá lọc: agencyId (bưu cục bị ép về mình), period (yyyyMM), status.

Chi tiết phiếu (tổng theo loại, bảng kê hai chiều, phụ lục K1).

Bưu cục nhượng quyền cho ô lọc / hộp lập phiếu của kế toán LADA.

Lập / làm mới nháp cho một kỳ đã qua.

Phát hành (Nháp → Chờ xác nhận).

Bưu cục xác nhận.

Khoá (dòng Ví → đã đối soát).

Đánh dấu đã lập hoá đơn (ghi số hoá đơn hai chiều, không tích hợp hoá đơn điện tử).

Tải bảng kê: 0 = đủ 4 sheet, 1 = LADA → bưu cục, 2 = bưu cục → LADA, 3 = phụ lục K1, 4 = chi tiết.

Ví bưu cục nhượng quyền (docs/bang-gia-noi-bo/SPEC.md §3.8 api/FranchiseWallet).

Bưu cục (role View) chỉ thấy ví của chính mình — service ép bộ lọc bưu cục về bưu cục của người gọi ở phía máy chủ, mọi yêu cầu ví khác trả 403. Kế toán LADA (Manage) thấy mọi ví, tạo điều chỉnh, duyệt lần 1; Approve duyệt lần 2.

Cờ hiển thị — không đòi role (rule quyen-hien-thi).

Dòng Ví (SmartTable). Khoá lọc: agencyId (bưu cục bị ép về ví mình), orderCode, orderId, entryType, status, eventAtStart, eventAtEnd.

Một dòng Ví kèm cách tính.

Tổng tạm tính / đã chốt theo loại dòng.

Danh sách ví của mọi bưu cục nhượng quyền (LADA).

Bật ví cho một chi nhánh (Ví v2 §1.1): tạo FranchiseWallet Active + EnabledAt, tham số mặc định; chi nhánh LADA không chặn xuất kho (§6 mục 15). Chỉ role Config (kế toán trưởng) / Founder. Từ đây planner mới sinh dòng cho chi nhánh đó.

Tạo điều chỉnh tay (chờ duyệt).

Duyệt điều chỉnh tay (lần 1: Manage / Approve; lần 2 từ ngưỡng: Approve, khác người tạo và người duyệt lần 1).

Từ chối điều chỉnh tay.

Vấn đề ghi Ví đang mở (cần soát).

Dự kiến phí nếu đơn giao thành công (Ví v2 plan §3.8.1, không ghi sổ); bưu cục chỉ đơn mình tham gia, chỉ dòng của mình.

Sửa tham số + tài khoản nhận / ảo của một ví (Ví v2 plan §3.8.1) — role Config.

Lịch sử đổi cấu hình của một ví — role Config.

Đối chiếu lại Ví của một đơn ngay (không chờ job đêm).

Bưu cục sở hữu khách (màn khách hàng).

Gán / bỏ bưu cục sở hữu khách (role sửa khách hàng) — SPEC §3.7, M14.

Chủ bưu cục tạo lệnh rút (Ví v2 §3.5): ví = bưu cục của người gọi, tài khoản nhận chụp từ ví — request không mang bưu cục hay tài khoản. Ví trừ ngay; không đủ điều kiện → từ chối nêu số tối đa được rút.

Chủ bưu cục huỷ lệnh rút còn chờ của bưu cục mình — ví hoàn ngay.

Kế toán quỹ xác nhận đã chuyển tiền lệnh rút.

Kế toán quỹ từ chối lệnh rút — hoàn ví (từ ngưỡng duyệt hai người: chờ người duyệt thứ hai).

Lệnh rút — bưu cục bị ép về ví mình; LADA (Manage / Approve / Treasury) lọc theo bưu cục.

Kế toán quỹ ghi nhận tiền bưu cục nạp vào tài khoản LADA — ví cộng ngay (không có đường cho bưu cục tự nạp).

Khoản nạp — bưu cục bị ép về ví mình; LADA lọc theo bưu cục.

Đơn nợ cước đơn hoàn theo bưu cục sale / khách (mặc định: còn nợ + đang cấn trong phiếu) — bưu cục bị ép về ví mình.

Kế toán ghi nhận bưu cục sale đã tự thu khoản nợ cước đơn hoàn ngoài ví — đóng nợ, không có E13.

Bảng giá nội bộ cho bưu cục nhượng quyền: giá mua đơn / phí lấy / phí giao (docs/bang-gia-noi-bo/SPEC.md §3.8).

Attribute là lớp đầu, service kiểm lại role và phạm vi bưu cục (fail-closed) — bưu cục chỉ có role View thì chỉ xem được bản đang / sắp áp cho bưu cục của chính mình, mọi yêu cầu khác trả 403.

Cờ hiển thị — không đòi role (rule quyen-hien-thi).

Danh sách phiên bản. Khoá lọc trong Search.PredicateObject: kind, status, agencyId, effectiveAt, keyword.

Chi tiết một phiên bản (bưu cục: chỉ bản đang / sắp áp cho mình).

Tải Excel một phiên bản — cùng luật xem như chi tiết (bưu cục: chỉ bản đang / sắp áp cho mình, không có giá niêm yết).

Tạo nháp từ khung niêm yết hoặc sao chép bản khác.

Sửa nháp.

Sinh theo hệ số.

Duyệt.

Huỷ — chỉ người duyệt (SPEC §3.8 "approve/cancel: Approve", §3.10).

Đặt / bỏ ngày ngừng áp dụng của bản đã duyệt.

Kiểm tra cân đối tại một ngày; thay một bảng bằng bản nháp đang xem.

Ba bảng đang áp + sắp áp cho một bưu cục (bưu cục: chỉ bưu cục của mình).

Gợi ý mã phiên bản.

Bưu cục nhượng quyền để chọn phạm vi (endpoint riêng, không mượn Agency/* để người soạn khỏi cần role Agency.*).

Controller quản lý lý do thất bại lấy/giao hàng (Admin)

Tìm kiếm lý do thất bại

Lấy thông tin lý do thất bại theo ID

Tạo mới hoặc cập nhật lý do thất bại

Xóa lý do thất bại (soft delete)

Controller xử lý các hoạt động liên quan đến địa chỉ đơn hàng.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý địa chỉ đơn hàng.

Lấy thông tin chi tiết của một địa chỉ đơn hàng dựa trên ID.

ID của địa chỉ đơn hàng. Thông tin chi tiết của địa chỉ đơn hàng.

Cập nhật thông tin địa chỉ đơn hàng.

Model chứa thông tin địa chỉ đơn hàng. Kết quả của hoạt động cập nhật.

Cập nhật riêng định vị (toạ độ) của địa chỉ đơn hàng. Không đụng tới tỉnh/phường nên không kéo theo tính lại cước hay đổi bưu cục dự kiến.

Toạ độ mới (để null cả Lat và Long để xoá định vị). Kết quả của hoạt động cập nhật.

Bóc toạ độ từ một link Google Maps. Dành cho link RÚT GỌN (maps.app.goo.gl): browser không đọc được Location header của redirect nên phải nhờ server.

Link người dùng dán vào. Toạ độ bóc được hoặc thông báo lỗi. Nhận thêm role của sổ địa chỉ khách hàng: màn tạo đơn cũng ghim toạ độ cho CustomerAddress bằng chính ô dán link này, mà nhân viên ở đó chưa chắc có quyền sửa địa chỉ đơn hàng. Endpoint chỉ bóc toạ độ từ URL, không đọc/ghi dữ liệu nghiệp vụ nào nên mở thêm là an toàn.

Controller để xử lý các hoạt động liên quan tới đơn hàng

Khởi tạo một instance mới của lớp .

Tùy chọn cấu hình ứng dụng. Dịch vụ xử lý đơn hàng.

Tìm kiếm đơn hàng theo các tham số cung cấp

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tìm đơn của bưu cục người đang đăng nhập — màn "Đơn hàng bưu cục" của chủ bưu cục.

Khoá Scope trong Search.PredicateObject chọn nhóm: 1 dự kiến lấy · 2 đã lấy · 3 dự kiến giao · 4 đã nhận từ kho tổng · 5 nhân sự bưu cục tạo. Các khoá lọc còn lại giống Search. Bưu cục lấy từ tài khoản (User.AgencyId), không nhận từ tham số; tài khoản chưa gắn bưu cục nhận danh sách rỗng. Các tham số tìm kiếm.

Cờ hiển thị của màn "Đơn hàng bưu cục": xem được không, của bưu cục nào, kèm option bộ lọc trạng thái.

Cố ý chỉ cần đăng nhập, không đòi role (rule quyen-hien-thi): người không có quyền vẫn hỏi được và nhận CanView = false. Luật nằm ở hàm thuần .

Tạo mới một đơn hàng.

Model chứa thông tin đơn hàng. Kết quả của hoạt động tạo đơn hàng.

Lấy thông tin chi tiết của đơn hàng dựa trên mã đơn hàng.

Mã đơn hàng. Thông tin chi tiết của đơn hàng.

Lấy thông tin chi tiết của đơn hàng theo mã đơn hàng với thông tin đơn vị do.

Mã đơn hàng. Thông tin chi tiết của đơn hàng với đơn vị do.

Hủy một đơn hàng.

Model chứa thông tin đơn hàng cần hủy. Kết quả của hoạt động hủy đơn hàng.

Gỡ bỏ trạng thái hủy của một đơn hàng.

Model chứa thông tin đơn hàng cần gỡ bỏ trạng thái hủy. Kết quả của hoạt động gỡ bỏ trạng thái hủy.

Lấy danh sách các phương thức thanh toán có sẵn

Danh sách phương thức thanh toán

Lấy danh sách các loại thời gian có sẵn cho bộ lọc

Danh sách các loại thời gian

Xuất Excel danh sách đơn hàng

Model xuất Excel Kết quả xuất file

Download file Excel đã xuất

Tên file File Excel

Chuẩn bị dữ liệu bộ lọc danh sách đơn hàng

Các danh sách option cho bộ lọc

Controller cho việc xuất Excel đơn hàng (Generic)

Xuất Excel đơn hàng với template được chỉ định

Model xuất Excel Kết quả xuất file

Xuất Excel đơn hàng với filter nâng cao

Model xuất Excel với filter Kết quả xuất file

Xuất Excel đơn hàng theo template Finance (backward compatibility)

Danh sách ID đơn hàng Kết quả xuất file

Xuất Excel đơn hàng theo template Basic

Danh sách mã đơn hàng Kết quả xuất file

Lấy danh sách template có sẵn

Danh sách template

Download file Excel đã xuất

Tên file File Excel

Lấy danh sách file Excel đã xuất

Danh sách file

Controller để xử lý các hoạt động liên quan đến tài chính đơn hàng.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý tài chính đơn hàng.

Lấy thông tin chi tiết của tài chính đơn hàng dựa trên ID.

ID của tài chính đơn hàng. Thông tin chi tiết của tài chính đơn hàng.

Cập nhật thông tin tài chính đơn hàng.

Model chứa thông tin tài chính đơn hàng. Kết quả của hoạt động cập nhật. Ai được sửa: người quản lý khách hàng, sale phụ trách đơn, hoặc Founder (chủ dự án chốt 2026-08-05). Chốt này nằm trong OrderFinService.Update chứ không ở attribute [Authorize], vì nó phụ thuộc DỮ LIỆU của từng đơn (ai quản lý khách, ai là sale) — attribute chỉ chặn được theo role. Muốn đổi luật thì sửa ở service. ⚠️ Hàm này nay TỰ ĐỘNG TÍNH LẠI CƯỚC khi client gửi GoodsAttributes (chủ dự án chốt 2026-08-05). Nghĩa là số tiền sau khi sửa có thể khác trước nếu bảng giá đã thay đổi kể từ lúc lên đơn — đó là hành vi mong muốn, không phải lỗi.

Thu tiền

Model chứa thông tin tài chính đơn hàng. Kết quả của hoạt động cập nhật.

Controller để xử lý các hoạt động liên quan đến kiện hàng đơn hàng.

Initializes a new instance of the class.

Dịch vụ xử lý kiện hàng đơn hàng.

Lấy thông tin chi tiết của kiện hàng đơn hàng dựa trên ID.

ID của đơn hàng. Thông tin chi tiết của kiện hàng đơn hàng.

Lấy thông tin chi tiết của kiện hàng đơn hàng dựa trên ID với thông tin đơn vị.

ID của đơn hàng. Thông tin chi tiết của kiện hàng đơn hàng với thông tin đơn vị.

Cập nhật thông tin kiện hàng đơn hàng.

Model chứa thông tin kiện hàng đơn hàng. Kết quả của hoạt động cập nhật.

Tìm kiếm danh sách mặt bằng

Lấy chi tiết mặt bằng theo ID

Tạo mới hoặc cập nhật mặt bằng

Xóa mặt bằng (soft delete)

Chuyển trạng thái mặt bằng

Cập nhật thông tin tài chính mặt bằng

Xóa ảnh/media của mặt bằng

Tìm kiếm tiêu chí chấm điểm

Lấy tiêu chí theo ID

Tạo mới hoặc cập nhật tiêu chí (kèm options)

Xóa tiêu chí (soft delete kèm options)

Lấy tất cả tiêu chí đang active (cho NV khi chấm điểm)

Quản lý mã khuyến mãi

Tìm kiếm mã khuyến mãi

Lấy chi tiết mã khuyến mãi

Tạo hoặc cập nhật mã khuyến mãi

Xóa mã khuyến mãi

Sinh mã khuyến mãi hàng loạt

Thay đổi trạng thái mã khuyến mãi

Model thay đổi trạng thái mã

Quản lý chương trình khuyến mãi

Tìm kiếm chương trình khuyến mãi

Lấy chi tiết chương trình khuyến mãi

Tạo hoặc cập nhật chương trình khuyến mãi

Xóa chương trình khuyến mãi

Thay đổi trạng thái chương trình khuyến mãi

Lấy log sử dụng khuyến mãi

Model thay đổi trạng thái

Lấy danh sách quy tắc hoàn thưởng theo chương trình

Tạo hoặc cập nhật quy tắc

Xóa quy tắc

Tìm kiếm ví khuyến mãi

Lấy ví theo customerId

Tìm kiếm log giao dịch ví

Nạp tiền thủ công vào ví khuyến mãi

Lấy báo cáo kiểm soát chi phí (Bảng kiểm soát chi phí)

Xuất Excel báo cáo kiểm soát chi phí

Backfill PaymentsDate từ lịch sử cho các expense đã Paid (chạy 1 lần)

Lấy báo cáo dòng tiền tổng hợp (Cash Flow Dashboard)

Xuất Excel báo cáo dòng tiền

Drill-down: danh sách đơn Thu cước vận chuyển theo khoảng thời gian

Drill-down: danh sách đơn Thu COD từ Shipper theo khoảng thời gian

Lấy báo cáo nợ ngắn hạn (Short-term Liability)

SmartTable search: Công nợ phải thu theo khách hàng

Xuất Excel danh sách đơn nợ cước theo khách hàng

SmartTable search: Nợ COD theo khách hàng

Request model cho báo cáo kiểm soát chi phí

Request model cho báo cáo dòng tiền

"daily" hoặc "weekly"

Controller để xử lý các báo cáo đổ dầu

Khởi tạo một thể hiện của .

Dịch vụ báo cáo đổ dầu. Dịch vụ xuất Excel báo cáo đổ dầu.

Lấy báo cáo đổ dầu theo lái xe

Tham số bảng thông minh Danh sách báo cáo đổ dầu theo lái xe Filters có thể truyền trong PredicateObject: - StartDate, EndDate: Khoảng thời gian đổ dầu - DriverIds: Mảng ID lái xe - TruckIds: Mảng ID xe - Statuses: Mảng trạng thái phiếu (0: Pending, 1: Approved, 2: Rejected). Mặc định [1]

Lấy báo cáo đổ dầu theo ngày

Tham số bảng thông minh Danh sách báo cáo đổ dầu theo ngày (nhóm theo ngày, chi tiết lái xe + xe bên trong) Filters có thể truyền trong PredicateObject: - StartDate, EndDate: Khoảng thời gian đổ dầu - DriverIds: Mảng ID lái xe - TruckIds: Mảng ID xe - Statuses: Mảng trạng thái phiếu (0: Pending, 1: Approved, 2: Rejected). Mặc định [1]

Xuất Excel báo cáo đổ dầu theo lái xe

Tham số bảng thông minh (cùng điều kiện lọc với GetByDriver) Kết quả xuất file Excel

Xuất Excel báo cáo đổ dầu theo ngày

Tham số bảng thông minh (cùng điều kiện lọc với GetByDate) Kết quả xuất file Excel

Lấy báo cáo đổ dầu theo xe

Tham số bảng thông minh Danh sách báo cáo đổ dầu theo xe (nhóm theo xe, chi tiết lái xe bên trong) Filters có thể truyền trong PredicateObject: - StartDate, EndDate: Khoảng thời gian đổ dầu - DriverIds: Mảng ID lái xe - TruckIds: Mảng ID xe - Statuses: Mảng trạng thái phiếu (0: Pending, 1: Approved, 2: Rejected). Mặc định [1]

Xuất Excel báo cáo đổ dầu theo xe

Tham số bảng thông minh (cùng điều kiện lọc với GetByTruck) Kết quả xuất file Excel

Controller để xử lý các báo cáo hoạt động lái xe

Khởi tạo một thể hiện của .

Dịch vụ báo cáo lái xe.

Lấy báo cáo năng suất lái xe theo từng ngày

Tham số bảng thông minh Danh sách báo cáo năng suất lái xe theo ngày

Controller thống kê tồn đọng đơn hàng (Backlog)

Lấy danh sách AgencyIds mà user hiện tại có quyền truy cập. Founder: null (không giới hạn). Khác: bưu cục mình + con cháu.

Lấy thống kê tồn đọng đơn hàng theo trạng thái và thời gian (D0-D7+)

Lấy thống kê tồn đọng đơn hàng phân nhóm theo Agency

Lấy danh sách chi tiết đơn hàng drill-down (có phân trang)

Đảm bảo AgencyIds trong SearchParam bị giới hạn bởi allowedIds. Nếu user truyền AgencyIds: lấy giao (intersection). Nếu user không truyền: dùng toàn bộ allowedIds.

Controller để xử lý các báo cáo tài chính đơn hàng

Khởi tạo một thể hiện của .

Dịch vụ báo cáo tài chính đơn hàng.

Chuẩn bị dữ liệu bộ lọc: trạng thái và trạng thái vật lý

Model chứa danh sách option trạng thái và trạng thái vật lý

Lấy thống kê chuyển khoản ngân hàng theo sale

Tham số bảng thông minh Danh sách thống kê chuyển khoản theo sale

Lấy dòng Tổng toàn cục (summary cards) cho báo cáo CK theo sale.

Tham số bảng thông minh (dùng cùng bộ lọc với search) Dòng tổng toàn cục

Lấy thống kê chuyển khoản ngân hàng theo khách hàng

Tham số bảng thông minh Danh sách thống kê chuyển khoản theo khách hàng

Lấy dòng Tổng toàn cục (summary cards) cho báo cáo CK theo khách hàng — tính trên toàn bộ khách hàng khớp bộ lọc, không phụ thuộc trang đang xem của SmartTable.

Tham số bảng thông minh (dùng cùng bộ lọc với search) Dòng tổng toàn cục

Lấy danh sách đơn CK kế toán chi tiết theo từng ô số liệu (metric), có phân trang server-side. Metric: "total"/null (tất cả), "notcollected" (chưa thu), "createdbill" (đã tạo phiếu), "collected" (đã thu). Truyền SaleId/CustomerId trong Search.PredicateObject để lọc theo sale/khách hàng (SaleId chỉ áp dụng khi là Founder/Accountant).

Tham số lọc giống báo cáo tổng hợp, bổ sung Metric; phân trang qua Pagination/Sort Trang dữ liệu danh sách đơn chi tiết (SmartTableResult)

Lấy báo cáo số lượng đơn và doanh số theo tuyến

Tham số bảng thông minh chứa các điều kiện lọc: - StartDate/EndDate: Khoảng thời gian - SaleId: Lọc theo sale (chỉ Founder) - SourceCityId: Lọc theo tỉnh/thành phố gửi - DestCityId: Lọc theo tỉnh/thành phố nhận Danh sách báo cáo theo tuyến và trạng thái

Role của ô lọc dùng chung cho ba trang doanh số theo chiều — người vào được trang nào cũng nạp được ô lọc.

Thống kê doanh thu bán hàng

Tham số tìm kiếm Kết quả thống kê doanh thu

Thống kê đơn hàng và doanh thu theo ngày

Tham số tìm kiếm Kết quả thống kê đơn hàng và doanh thu theo ngày

Thống kê doanh thu theo ngày công ty nhận tiền (Collection Date) Chỉ bao gồm thống kê tài chính, không có thống kê trạng thái triển khai

Tham số tìm kiếm Kết quả thống kê doanh thu theo ngày nhận tiền

Thống kê doanh thu theo Sale (chỉ thống kê tài chính)

Tham số tìm kiếm Kết quả thống kê doanh thu theo Sale

Thống kê doanh thu theo khách hàng

Tham số tìm kiếm Kết quả thống kê doanh thu theo khách hàng

Lấy thông tin quyền của user cho báo cáo doanh thu theo khách hàng

Thông tin quyền (có thể chọn sale hay không)

Cờ hiển thị của ba báo cáo doanh số theo chiều + nút Xuất Excel + link mã đơn. CỐ Ý không gác role (rule quyen-hien-thi): người không có quyền nào vẫn hỏi được và nhận toàn false.

Doanh số theo bưu cục bán × 4 nhóm trạng thái. Phạm vi: Founder/kế toán mọi bưu cục (kể cả đã ngừng), người đứng tên bưu cục thì bưu cục đó + con cháu, còn lại rỗng.

Search.PredicateObject: FromDate, ToDate, AgencyId (chỉ thu hẹp).

Doanh số theo nhóm (quản lý trực tiếp của sale) × 4 nhóm trạng thái. Phạm vi: bản thân + cấp dưới + nhân sự bưu cục mình đứng tên; Founder/kế toán không giới hạn.

Search.PredicateObject: FromDate, ToDate, ManagerId (0 = chưa có quản lý; chỉ thu hẹp).

Doanh số theo phường/xã (bộ 2 cấp) của điểm lấy hoặc điểm giao × 4 nhóm trạng thái. Phạm vi như báo cáo bưu cục.

Search.PredicateObject: FromDate, ToDate, AddressType (1/2), CityId, Keyword, AgencyId.

Danh sách đơn của một ô (drill-down). Action chỉ đòi đăng nhập vì role phụ thuộc Dimension trong body — service kiểm role của chiều qua IUserRoleResolver rồi ép CÙNG phạm vi với báo cáo của chiều đó.

Search.PredicateObject: FromDate, ToDate, Dimension, Key, StatusGroup, AddressType, AgencyId; Pagination.

Bưu cục và nhóm trong phạm vi người xem cho ô lọc — không gọi danh mục toàn cục.

Xuất Excel báo cáo bưu cục — đòi role của chiều VÀ RevenueReport.Export (hai [Authorize] là phép AND).

Xuất Excel báo cáo nhóm — đòi role của chiều VÀ RevenueReport.Export.

Xuất Excel báo cáo phường/xã — đòi role của chiều VÀ RevenueReport.Export.

Trả thẳng byte với no-store, không lưu ra wwwroot — doanh số theo bưu cục/nhóm không được nằm ở một URL tải công khai (khuôn FranchisePriceController).

Controller quản lý cấu hình phạt tự động

Lấy cấu hình đang hiệu lực

Cập nhật cấu hình (tạo version mới)

Tạm dừng / Mở lại job tự động

Tìm kiếm danh sách cấu hình

Lấy chi tiết cấu hình theo ID

Tạo mới hoặc cập nhật cấu hình

Xóa cấu hình

Controller quản lý phiếu thưởng/phạt

Tìm kiếm phiếu thưởng/phạt

Lấy phiếu thưởng/phạt theo ID

Tạo phiếu thưởng/phạt thủ công

Duyệt phiếu

Từ chối phiếu

Gỡ/hủy phiếu (có giới hạn amnesty nếu Auto)

Tạo biên bản vi phạm nộp tiền trễ từ trang Cashier

Tha thứ / bỏ qua biên bản (Forgive)

Xóa biên bản vi phạm

Lý do gỡ biên bản (bắt buộc)

Lý do tha thứ (bắt buộc)

Màn hình "Đồng bộ tìm kiếm": xem trạng thái index của từng URL và ba nút bấm tay. Quyền tách làm hai mức theo hậu quả, không theo động từ HTTP. SearchConsole.View cho mọi lời gọi chỉ đọc lại 5 bảng đã có — kể cả POST search, vốn là POST chỉ vì SmartTable gửi bộ lọc trong thân request. SearchConsole.Manage cho ba nút thật sự làm phát sinh lời gọi ra Google và tiêu hạn mức chung với job chạy nền.

Trần số dòng nhật ký trả về một lượt.

Bảng nhật ký giữ tới Search.ApiLogRetentionDays ngày nên nó lớn dần; không kẹp thì một lời gọi ?take=999999 kéo cả bảng về trình duyệt. Màn hình chỉ hiện vài chục dòng gần nhất.

Số dòng nhật ký mặc định — đủ nhìn được một ngày chạy job mà không phải bấm thêm.

Số ngày mặc định của tab hiệu suất — bằng cửa sổ giao diện Search Console hay dùng.

Số ngày mặc định của tab lượt bot. Ngắn hơn tab hiệu suất vì câu hỏi ở đây luôn là về hiện tại ("bot nào đang ghé"), và vì dữ liệu chỉ được giữ 90 ngày.

Bảng chính: hàng tồn kho URL kèm trạng thái index gần nhất

Các con số tổng hợp đầu trang, kèm trạng thái công tắc và hạn mức còn lại

Trạng thái tệp sitemap dưới mắt công cụ tìm kiếm

Số liệu hiệu suất tìm kiếm của một khoảng ngày: lượt bấm, lượt hiển thị, CTR, vị trí, và đường xu hướng theo ngày.

Chỉ đọc bảng SearchMetricDaily — không gọi ra Google, nên không tiêu hạn mức và chạy được cả khi mọi công tắc còn tắt. Vì thế nó nằm ở mức quyền View.

Xếp hạng trang theo lượt bấm

Xếp hạng truy vấn theo lượt bấm

Các truy vấn đưa người dùng tới đúng một trang

Tham số url chỉ được dùng làm giá trị so sánh trong một truy vấn tham số hoá, không ghép vào chuỗi nào và không đi ra ngoài — nên không có đường để một địa chỉ lạ trở thành một lời gọi. URL không có trong bảng thì trả về danh sách rỗng.

Tổng hợp lượt bot ghé website — theo User-Agent tự khai

Số ở đây do middleware của ladaexpress.vn ghi, API chỉ đọc lại. Không có lời gọi ra ngoài nào, nên chỉ đòi quyền xem.

Xếp hạng đường dẫn theo số lượt bot

Tham số bot chỉ được dùng làm giá trị so sánh trong một truy vấn tham số hoá, không ghép vào chuỗi nào và không đi ra ngoài. Tên bot lạ thì trả về danh sách rỗng.

Nhật ký lời gọi ra công cụ tìm kiếm — cũng chính là sổ đếm hạn mức đã dùng

Kiểm ngay trạng thái index của một URL trong hàng tồn kho.

Chỉ nhận URL đã có trong bảng SearchUrl — service từ chối mọi địa chỉ khác trước khi có lời gọi nào đi ra. Đó vừa là hàng rào SSRF (không ai mượn được máy chủ để gọi hộ một địa chỉ tự chọn) vừa là hàng rào hạn mức. Lượt kiểm này trừ vào cùng sổ hạn mức ngày với job chạy nền. Cố ý không truyền HttpContext.RequestAborted xuống service. Người bấm đóng tab giữa chừng sẽ huỷ token, mà điểm huỷ nguy hiểm nhất nằm đúng giữa "đã gọi ra Google" và "đã ghi dòng nhật ký": huỷ ở đó là mất dấu một lượt đã tiêu hạn mức, và lượt sau sẽ tiêu thêm đúng ngần ấy nữa. Lời gọi chỉ vài trăm mili-giây nên chạy nốt là lựa chọn rẻ hơn.

Nộp lại tệp sitemap đang cấu hình.

Cố ý không nhận tham số: địa chỉ tệp luôn lấy từ khoá Search.Google.SitemapUrl. Cho người bấm chọn tệp là cho phép nộp một địa chỉ bất kỳ dưới danh nghĩa property của LADA. Bị từ chối kèm lý do khi công tắc Search.Google.SubmitEnabled còn tắt.

Thử kết nối tới công cụ tìm kiếm để biết khoá và quyền đã đúng chưa.

Câu trả lời cố ý chỉ nói được/không được kèm cách sửa — không kèm địa chỉ service account hay mẩu khoá nào, vì nó hiện thẳng lên giao diện quản trị.

Cờ hiển thị cho màn hình "Đồng bộ tìm kiếm" — "tôi được thấy nút nào".

Endpoint này cố ý không đòi role nào (chỉ cần đăng nhập): người không có quyền gì vẫn phải hỏi được và nhận về toàn false để giao diện ẩn nút. Gác nó bằng một role là dựng lại đúng lỗi nó sinh ra để chữa — trang sẽ hiện nút cho người không bấm được, hoặc gãy vì lời gọi hỏi quyền lại bị 403. Luật nằm ở hàm thuần , controller chỉ hỏi role rồi chuyển tiếp (mẫu: AdsNavController).

Cờ hiển thị nút của màn hình đồng bộ tìm kiếm cho người đang đăng nhập

Luật "ai thấy gì" của màn hình Đồng bộ tìm kiếm.

Hàm thuần — không chạm database, không đọc HttpContext: nhận danh sách role đã phân giải qua IUserRoleResolver, trả các cờ. Cùng khuôn với AdsNavPermissions, và vì cùng một lý do: luật này phải có ca test gọi thẳng vào nó, mà controller thì không test được sạch (User.GetCurrentUser() nuốt mọi ngoại lệ rồi trả UserId = 0). CanManage không kéo theo CanView. Cám dỗ ở đây là coi "quản lý" như một mức cao hơn "xem" rồi cho nó bao luôn. Nhưng hàng rào thật là các thuộc tính [Authorize(Roles = …)] trên SearchConsoleController: mọi endpoint đọc đòi đúng SearchConsole.View. Một người chỉ được cấp SearchConsole.Manage mà thấy trang mở ra sẽ ăn 403 ngay ở lời gọi nạp bảng. Cờ phải soi đúng bó quyền mà nó gác, không mượn bó khác. Hai quyền này luôn được cấp cùng nhau qua nhóm Permission "Marketing", nên trường hợp lệch chỉ xảy ra khi có người gán tay — và khi đó giao diện phải nói đúng sự thật.

Vai bỏ qua mọi kiểm tra role của hệ thống — ẩn nút của Founder là dựng hàng rào không có thật.

Role của mọi lời gọi chỉ đọc: search, summary, sitemap-status, api-logs.

Role của ba nút làm phát sinh lời gọi ra Google: inspect-now, submit-sitemap-now, test-connection.

Role đã phân giải qua IUserRoleResolver; null hoặc rỗng = không có role nào

Cờ hiển thị của màn hình Đồng bộ tìm kiếm — mỗi cờ gác đúng một bó quyền (xem )

Cờ hiển thị của màn hình Đồng bộ tìm kiếm — mỗi cờ gác đúng một bó quyền (xem )

Quản lý kênh chat: kết nối Zalo Official Account qua OAuth, bật/tắt, xoá. Toàn bộ endpoint đòi quyền ChatChannel.Manage — đây là chỗ nắm token của OA, tách hẳn khỏi quyền trả lời tin nhắn. Ngoại lệ duy nhất là endpoint nhận callback, vì trình duyệt được Zalo chuyển hướng sang nên không mang theo JWT; nó tự bảo vệ bằng tham số state đã ký HMAC.

Tiền tố đường dẫn công khai của endpoint nhận callback OAuth. Khai đúng một chỗ rồi cho FrontendOriginMiddleware.BypassPaths dùng lại — chép chuỗi ra hai nơi là sớm muộn có nơi quên đổi, và nơi quên đó thành lỗ hổng.

Danh sách kênh đã kết nối. Phản hồi không chứa token dưới bất kỳ dạng nào — chỉ có hai cờ HasAccessToken / HasRefreshToken. Ba role chứ không phải một, và đó là bản vá cho lần thứ BA của cùng một hình dạng lỗi (finding FB-2 giai đoạn B, rồi L7 và L12 của phiên bấm thật P1b): route mở cho vai A nhưng API mà trang đó gọi lại đòi vai B. Trang /dieu-phoi-chat mở cho ChatDistribution.Manage và ChatConversation.ViewChannel, mà ô lọc kênh của nó gọi đúng endpoint này — trước bản vá nó trả 403 cho cả hai vai, và apiClient dịch mọi 403 thành một cú chuyển hướng cả SPA sang trang "không có quyền". Tức trang điều phối hỏng với ĐÚNG những vai nó được mở cho; chỉ Founder dùng được, và chỉ vì Founder bỏ qua mọi kiểm tra role. Nới ở đây không mở thêm dữ liệu nào: hai vai được thêm vốn đã đọc được hội thoại của những kênh ấy, và mỗi hội thoại đã mang sẵn tên kênh trong danh sách.

Chi tiết một kênh

Lấy đường dẫn cấp quyền để admin của Zalo OA bấm vào. Phản hồi kèm code challenge cần khai trên cổng nhà phát triển (nếu có dùng PKCE).

Zalo chuyển hướng trình duyệt của admin OA về đây kèm code và oa_id sau khi cấp quyền xong. Không yêu cầu đăng nhập vì request đến từ một lần chuyển hướng của Zalo. Chống việc người ngoài tự gắn Official Account của họ vào hệ thống bằng tham số state đã ký HMAC kèm dấu thời gian; state sai hoặc hết hạn là từ chối ngay ở tầng service. Giới hạn tốc độ theo policy ẩn danh: luồng thật chỉ gọi đúng một lần cho mỗi lần cấp quyền.

Lấy đường dẫn hộp thoại Facebook Login for Business để quản trị viên bấm vào và tự cấp quyền — thay cho việc dán tay user access token lấy ở Graph API Explorer. Phản hồi kèm chuỗi state; giao diện phải giữ lại chuỗi đó để hỏi danh sách Page sau khi cửa sổ cấp quyền đóng. Token không bao giờ đi qua trình duyệt.

Facebook chuyển hướng trình duyệt của quản trị viên về đây kèm code và state sau khi cấp quyền xong. Không yêu cầu đăng nhập vì request đến từ một lần chuyển hướng của Facebook — cửa sổ bật lên không mang theo phiên của SPA. Chống người ngoài tự gắn Page của họ vào hệ thống bằng tham số state đã ký HMAC kèm dấu thời gian và mã người dùng; state sai hoặc hết hạn là từ chối ngay ở tầng service. Trả về một trang HTML tối giản tự đóng cửa sổ. Đây là chỗ DUY NHẤT trong repo trả HTML từ controller, và có lý do: người dùng đang nhìn thẳng vào cửa sổ này, mà JSON trần thì họ phải tự hiểu rồi tự đóng.

Danh sách Facebook Page mà quản trị viên đang quản lý. Dùng POST dù đây là thao tác đọc: state và token dự phòng phải đi trong thân request. Trên query string chúng sẽ nằm lại trong nhật ký truy cập của mọi proxy trên đường, mà Page access token dẫn xuất từ token đó thì không có hạn dùng. Phản hồi không chứa token của Page nào.

Kết nối một Facebook Page thành kênh chat. Bước chọn Page luôn nằm sau đăng nhập kèm quyền ChatChannel.Manage, kể cả khi đi bằng luồng Facebook Login: callback ẩn danh chỉ giữ token vào bộ nhớ máy chủ chứ không tạo kênh, nên không có đường nào gắn được Page mà không qua cửa này.

Đăng ký lại webhook (subscribed_apps) cho một kênh Facebook đã lưu (SC-20). Dành cho kênh kết nối trước khi bước đăng ký được tự động hoá, hoặc khi bước đó thất bại.

Bật hoặc tắt một kênh

Xoá mềm một kênh

Danh sách nhân viên phụ trách một kênh. Quyền riêng ChatChannel.StaffAssign chứ không dùng chung ChatChannel.Manage: quyền kia nắm token OA — thứ mà trưởng bưu cục xếp lịch trực cho đội sale của mình không có lý do gì phải chạm tới. Role mới trả lời được "có được cấu hình sale phụ trách không", chưa trả lời "kênh nào". Câu thứ hai hỏi tầng dịch vụ — không hỏi thì một trưởng nhóm đọc được danh sách sale của mọi bưu cục khác, kèm họ tên (finding F-1).

Thêm hoặc sửa một nhân viên phụ trách kênh

Gỡ một nhân viên khỏi danh sách phụ trách kênh (xoá mềm, giữ lịch sử)

Đổi bưu cục sở hữu và chế độ phân phối của kênh. Chuyển kênh khỏi chế độ "Dùng chung" là bật hàng rào quyền xem — từ đó chỉ người trong phạm vi mới đọc được hội thoại của kênh. Giao diện phải hỏi lại trước khi gọi; tầng dịch vụ còn chặn thêm hai ca hỏng người ("chưa ai phụ trách" và "kênh một chủ mà không có đúng một chủ").

Trang kết thúc luồng cấp quyền Facebook: báo kết quả rồi tự đóng cửa sổ. Thông điệp luôn đi qua — một phần trong đó là nguyên văn lời Facebook nói (error_description trên query string), tức là chuỗi do bên ngoài điều khiển. Nhúng thẳng vào HTML là mở đường chèn mã ngay trên tên miền của API. Trang không nhận tham số nào khác từ query và không tự chuyển hướng đi đâu: cửa sổ này do SPA mở ra, đóng lại là xong, phần còn lại của luồng do SPA làm bằng chuỗi state nó đang giữ.

Máy phân phối khách chat — nhật ký quyết định và bản phát lại đối chiếu (giai đoạn D).

Route chữ thường tường minh api/socialchat/distribution, đúng nếp của SocialChatController và ChatPresenceController. Hàng chờ vẫn nằm ở POST api/socialchat/distribution/queue của SocialChatController — không dời sang đây vì dời là đổi đường một trang đang chạy, mà nguyên tắc số 1 nói đừng. Đối chiếu role với trang gọi nó. Route /dieu-phoi-chat mở cho ChatDistribution.Manage và ChatConversation.ViewChannel, nên hai đường ĐỌC ở đây gác đúng bằng hai vai ấy — mở hẹp hơn là tái lập FB-2 / L7 / L12, ba lần cùng một hình dạng "trang mở được nhưng lời gọi của nó trả 403". Đường phát lại thì hẹp hơn hẳn: nó ghi hàng loạt dòng nhật ký và là công cụ của người vận hành máy phân phối, không phải của người đọc hàng chờ. Chỉ ChatDistribution.Manage.

Nhật ký quyết định của máy phân phối, đã thu hẹp theo phạm vi kênh của người đọc.

Trạng thái máy phân phối — để giao diện nói rõ "đang chạy thử" thay vì để người đọc tưởng khách đã được chia thật.

Phát lại tin inbound lịch sử qua máy phân phối và trả về bảng đối chiếu — bằng chứng của cổng D2.

Không bao giờ ghi AssignedStaffId: mọi dòng nó sinh ra mang Source = Replay và IsDryRun = true, và chạy lại thì dọn đúng những dòng phát lại cũ trong cùng cửa sổ chứ không đụng dòng của máy chạy thật.

Trạng thái sẵn sàng của sale (giai đoạn C đợt phân phối khách chat).

Route chữ thường tường minh api/socialchat/presence, đúng nếp của SocialChatController (api/socialchat) và ChatChannelController (api/socialchat/channel) chứ không theo quy ước Pascal của phần còn lại repo. Đường "của tôi" và đường "của người khác" là HAI endpoint riêng, không phải một endpoint phân nhánh theo StaffId trong thân yêu cầu. Gộp lại nghĩa là quyền cần có phụ thuộc vào nội dung thân — loại hàng rào dễ quên nhất, và không đọc ra được bằng cách nhìn [Authorize]. Đối chiếu role với trang gọi nó (bài học FB-2 → L7 → L12, ba lần cùng một hình dạng): chip trạng thái nằm trên thanh điều hướng của mọi trang, nên hai endpoint me gác bằng ChatConversation.Search — quyền hẹp nhất mà một người làm chat chắc chắn có. Phía trình duyệt vẫn phải đọc 403 thành "ẩn chip" thay vì để apiClient đá cả SPA sang trang không có quyền.

Ba đường GHI của hộp thoại quản lý có mở cho người đang đăng nhập hay không.

Sổ nợ PP-36 chỗ (b). Hộp thoại quản lý ở /trang-thai-sale mở cho người chỉ có ChatConversation.ViewChannel — đường ĐỌC nhận vai ấy, nhưng cả ba tab bên trong gọi ba đường GHI mà vai ấy chắc chắn ăn 403. Máy chủ trả cờ, giao diện ẩn hẳn tab; cùng khuôn CanViewTeam đã chạy đúng ở trang điểm. Không đòi role nào: câu "tôi được làm gì" phải trả lời được cho cả người không có quyền nào — họ nhận ba cờ false. Luật nằm ở hàm thuần để có ca test gọi thẳng vào.

Trạng thái sẵn sàng của chính người đăng nhập

Đặt trạng thái sẵn sàng cho chính mình

Trạng thái sẵn sàng của một nhân viên khác

Role chỉ mở cửa vào tính năng; phạm vi "được xem của ai" nằm ở tầng service. Không chấm phạm vi ở đây thì endpoint này thành máy tra tên và ghi chú theo mã tuỳ ý — đúng hình dạng finding F-4 của giai đoạn A, và đúng bài học IDOR của docs/security-audit-2026-07-11.md: chặn ở giao diện không phải là chặn.

Đặt trạng thái sẵn sàng hộ một nhân viên khác

Đặt, sửa hoặc xoá giờ làm việc riêng của chính mình (KC-18). Gửi giờ bắt đầu và giờ kết thúc cùng trống là xoá, về "chưa đặt".

Cùng role với POST me: đặt giờ làm là việc của chính người làm chat, và chip trạng thái mở hộp này ở mọi trang. Service không đọc StaffId trong thân.

Đặt, sửa hoặc xoá giờ làm việc riêng hộ một nhân viên khác (KC-18)

Chủ dự án chốt (§8.7 câu 4): cùng quyền với đặt trạng thái hộ, không tạo quyền mới. Phạm vi "được đặt cho ai" chấm ở tầng service như POST staff.

Tạm ngưng chia khách cho một nhân viên, hoặc gỡ lệnh tạm ngưng

Uỷ quyền tạm hội thoại của một người đang không sẵn sàng cho người khác cùng kênh.

Bảng thời lượng theo trạng thái — mỗi nhân viên một dòng.

Nhận , nên client bắt buộc gửi đủ cả Pagination, Search và Sort. Ba trường ấy là kiểu tham chiếu non-nullable trong một assembly bật <Nullable>enable, nên ASP.NET Core suy ra [Required] ngầm và [ApiController] biến thiếu trường thành 400 trước khi dòng code đầu tiên của action chạy. Đó là lỗi L13 đã làm hàng chờ /dieu-phoi-chat chưa từng nạp được kể từ khi trang ra đời, và không ca test nào bắt được vì test gọi thẳng service. Phạm vi "được nhìn thấy ai" nằm ở tầng service, không ở đây: ba vai mở được trang có phạm vi rất khác nhau.

Điểm chất lượng chat (giai đoạn F) — điểm của chính mình và bảng điểm đội.

Hai đường, hai mức quyền khác hẳn nhau, và đó là chốt CH-8: xem điểm của mình thì ai cũng xem được, không đòi quyền gì; xem điểm người khác đòi ChatQuality.ViewTeam. Đặt cả hai sau cùng một role là hoặc chặn sale xem điểm của chính họ (làm bộ điểm thành bảng phạt bí mật), hoặc mở điểm của mọi người cho tất cả. Trả cờ CanViewTeam để giao diện ẩn hẳn tab thay vì đặt ở đó một cái nút chắc chắn trả 403. Khuôn CanReplay của giai đoạn D, và nó tồn tại vì hình dạng "route mở cho vai A nhưng API đòi vai B" đã cắn bốn lần trong đợt này. ChatQuality.ViewTeam là quyền hẹp hơn quyền vào trang — trang /diem-chat-cua-toi mở cho mọi người.

Điểm của chính người đang đăng nhập, kèm điểm từng tiêu chí, cỡ mẫu và việc cần làm.

Cố ý không nhận tham số staffId. Một đường "xem điểm của người X" nhận mã người từ client là một lỗ IDOR sẵn sàng — bài học của docs/security-audit-2026-07-11.md và của chính đợt này ở 13 endpoint giai đoạn A. Muốn xem người khác thì đi đường team, và đường ấy có role riêng cộng một phép thu hẹp phạm vi.

Điểm của những người trong phạm vi xem của mình.

Role mở cửa, IChatVisibilityResolver quyết phạm vi. Hai lớp, không một — Founder bypass chỉ vượt kiểm tra ROLE, không vượt DataAccessScope.

API mẫu tin nhắn nhanh — danh sách chọn ở ô soạn tin và trang quản lý /tin-nhan-nhanh (docs/plan-tin-nhan-nhanh-chat.md §3.3). Gửi tin từ mẫu nằm ở api/socialchat/send-quick-reply.

Mỗi phạm vi một cặp endpoint ghi, gác bằng một role khác nhau — save-personal/ personal/{id} đòi ChatConversation.Send, save-shared/shared/{id} đòi ChatQuickReply.ManageShared. Role không nằm trong JWT (rule backend-contracts), nên chấm "được sửa mẫu dùng chung không" trong service là phải kéo lớp phân giải role vào; đặt trên attribute thì /security-review đọc được ngay. Phạm vi và chủ nhân của bản ghi thì chấm ở service. Ba lời gọi ĐỌC mở cho cả ba role ChatConversation.Search, ChatConversation.Send, ChatQuickReply.ManageShared — rộng hơn plan §3.3 (chỉ Search) một cách có chủ ý: dòng menu /tin-nhan-nhanh mở cho Send và ManageShared, nên gác trang bằng Search là để người chỉ có ManageShared vào được trang rồi ăn 403 và bị đá khỏi SPA — đúng họ lỗi rule quyen-hien-thi chặn. Không mở thêm dữ liệu nào: ai đọc được gì vẫn do hàng rào của service quyết định.

Danh sách gọn cho ô chọn ở ô soạn tin: mẫu dùng chung đang bật + mẫu cá nhân đang bật của tôi

Bảng ở trang quản lý, theo một phạm vi

Phân trang, sắp xếp; Search.PredicateObject nhận globalSearch, IsActive 1 = của tôi, 2 = dùng chung

Một mẫu để mở form sửa; ngoài phạm vi thấy được thì 404

Tạo hoặc sửa mẫu cá nhân của chính mình (multipart, kèm ảnh tuỳ chọn)

Tạo hoặc sửa mẫu dùng chung cho cả công ty (multipart, kèm ảnh tuỳ chọn)

Xoá mềm mẫu cá nhân của chính mình; tệp ảnh giữ nguyên

Xoá mềm mẫu dùng chung; tệp ảnh giữ nguyên

Cùng nguồn với cờ CanManageSharedQuickReplies của nav-permissions: giao diện ẩn nút ghi theo cờ ấy, và bảng dùng chung hiện mẫu đã tắt theo đúng luật ấy — hai nơi không được đọc hai luật.

API khung chat cho SPA quản trị. Mọi hành động chấm quyền server-side bằng [Authorize(Roles = …)] — role tra từ database qua ServerRoleAuthorizationHandler, không nằm trong JWT. Không có endpoint nào ở đây tin vào việc giao diện đã ẩn nút. Phạm vi dữ liệu chấm ở tầng service, không phải ở đây. Mọi action truyền User.GetCurrentUser().UserId xuống service, và service hỏi IChatVisibilityResolver — một luật, một chỗ. Rải if phạm vi lên controller là đúng hình dạng lỗi IDOR của docs/security-audit-2026-07-11.md: đường thứ hai vào cùng dữ liệu sẽ quên mất cái if ấy. Kênh còn ở chế độ Shared thì hàng rào không đổi gì — ai có quyền vẫn xem được mọi hội thoại của kênh đó, đúng hành vi trước đợt phân phối (§6.3).

Danh sách hội thoại cho cột trái của khung chat

Chi tiết một hội thoại kèm các tin gần nhất

Hội thoại cần mở Số tin nạp sẵn; bỏ trống là 50, trần 200

Nạp thêm tin CŨ HƠN một tin đã có trên màn hình — nút "xem thêm tin cũ".

Hội thoại Mã tin cũ nhất đang hiện; chỉ lấy tin có mã nhỏ hơn nó Số tin lấy thêm; bỏ trống là 50, trần 200

Đánh dấu một hội thoại là đã đọc hết

Kéo lại các tin gần nhất của hội thoại từ nền tảng và chèn tin LADA còn thiếu — nút "Đồng bộ lại" trên khung chat.

Ca gốc là tin Page tự trả lời riêng từ bình luận Facebook: webhook không chở tới, nên khung chat chỉ có câu trả lời của khách mà mất câu hỏi đứng trước. Job chat-history-sync tự kéo cho hội thoại mới; nút này cho hội thoại có từ trước. Gác bằng ChatConversation.GetById — role mở hội thoại, cùng role với mark-read — và phạm vi ĐỌC ở tầng service: thao tác chỉ chép lại thứ đã có trên nền tảng, không gửi gì cho khách.

Những phần tử điều hướng của miền chat mà người đang đăng nhập được phép thấy.

Khuôn CanReplay / CanViewTeam, áp cho hai liên kết trên thanh công cụ khung chat (sổ nợ PP-39). Máy chủ trả cờ, giao diện ẩn hẳn liên kết — không để giao diện đoán theo role tự chép sang JavaScript, cũng không để liên kết hiện rồi người dùng bấm vào và ăn 403. Đây là lần thứ bảy và tám của họ lỗi "route mở cho vai A nhưng API đòi vai B" trong cùng một đợt, và khuôn chống nó đã chạy đúng ngay cạnh: P7 đo được tab "Điểm đội" không tồn tại trong DOM của một sale. Endpoint riêng thay vì ký sinh vào unread-count, vì có ba màn cần hai cờ này — khung chat, /trang-thai-sale, và /kenh-chat — mà chỉ khung chat gọi unread-count. Ký sinh thì hai màn kia phải tự chép lại luật. Không đòi role nào: câu "tôi được thấy gì" phải trả lời được cho cả người không có quyền chat nào — họ nhận hai cờ false. Gác nó bằng role là dựng đúng cái lỗi nó sinh ra để chữa. Bốn cờ đọc bốn bó quyền KHÁC NHAU, và cố ý không dùng quyền của lời gọi dữ liệu. Riêng trang /kenh-chat cần ba cờ vì nó có ba nhóm thao tác gác bằng ba bó quyền khác nhau: CanOpenChannelPage (vào được trang — ChatChannel.Manage hoặc ChatChannel.StaffAssign), CanManageChannels (cấp quyền OAuth — chỉ ChatChannel.Manage) và CanUpdateAssignmentSettings (khối cấu hình kênh — StaffAssign và ChatDistribution.Manage, đúng phép AND hai lớp gác của channel/assignment-settings; PP-46). Gộp cờ theo chiều nào cũng sai: gộp về Manage thì trưởng nhóm mất đường vào trang duy nhất của họ, gộp về bó của channel/all thì người chỉ ĐỌC thấy nút cấp quyền OAuth và ăn 403.

Tổng số tin chưa đọc trên mọi hội thoại

Trả lời một hội thoại bằng tin nhắn văn bản

Thả hoặc gỡ một biểu tượng cảm xúc trên một tin nhắn. Dùng chung quyền ChatConversation.Send với việc gửi tin, không tạo quyền thứ hai: đây vẫn là một hành động ra ngoài, khách nhìn thấy được, và ai được trả lời khách thì đương nhiên được thả một biểu tượng cảm xúc. Một quyền riêng chỉ thêm một dòng phải seed và một chỗ nữa để quên cấp.

Trả lời một hội thoại bằng hình ảnh. Nhận CHÍNH TỆP chứ không nhận đường dẫn: SendChatMessageParam.LocalImagePath là đường dẫn trên đĩa máy chủ, để client đặt được giá trị đó là mở đường đọc tệp bất kỳ của máy chủ rồi gửi ra ngoài cho khách. Ở đây máy chủ lưu tệp rồi tự điền đường dẫn.

Trả lời một hội thoại, xuất phát từ một mẫu tin nhắn nhanh (docs/plan-tin-nhan-nhanh-chat.md §3.2, §3.3). Ảnh lấy từ mẫu, không nhận từ client. Client chỉ gửi mã mẫu và cờ WithImage; đường dẫn tệp trên đĩa máy chủ do máy chủ tra theo mã mẫu — cùng lý do send-image nhận chính tệp chứ không nhận đường dẫn. Mẫu phải thấy được với người gửi (mẫu dùng chung, hoặc mẫu cá nhân của chính họ) và đang bật. Nội dung gửi đi là chữ trong ô soạn mà nhân viên đã sửa, không phải nội dung gốc của mẫu. Bên trong gọi đúng SendMessageAsync mà send và send-image dùng — cùng hàng rào phạm vi ghi, cùng kiểm kênh, cùng luật trích dẫn. Zalo/Facebook không biết có "mẫu". Không hỏi EnsureCanSendAsync trước như send-image: ở đó câu hỏi trước tồn tại để khỏi ghi một tệp mồ côi xuống đĩa, còn ở đây ảnh đã nằm sẵn trên đĩa — SendMessageAsync tự chặn đúng những trường hợp ấy trước khi lưu tin.

Gợi ý khách hàng để gắn vào hội thoại. Đi qua đúng của phân hệ khách hàng, không tự truy vấn bảng Customer. Phân hệ đó có sẵn một luật phạm vi mà cả hệ thống đang dựa vào: ngoài Founder, không ai được duyệt danh sách khách của người khác — người dùng thường chỉ tìm trong khách mình phụ trách, và chỉ khi gõ ĐỦ số điện thoại mới tìm được toàn hệ thống (kết quả khi đó là duy nhất nên không lộ tệp khách của ai). Role ChatConversation.LinkCustomer mở CỬA vào tính năng gắn khách; nó không, và không được, mở rộng phạm vi dữ liệu khách hàng mà tài khoản đó vốn được xem. Tự viết một câu truy vấn mới ở đây là dựng một cửa sau vào tệp khách hàng của công ty.

Gắn hội thoại với một khách hàng trong hệ thống. Trước khi gắn, mã khách hàng được đối chiếu lại bằng CHÍNH đường gợi ý có phạm vi ở trên. Nếu không, endpoint này thành một máy tra tên khách hàng theo mã: gọi lần lượt CustomerId = 1, 2, 3… là đọc được tên của cả tệp khách hàng, không cần từ khoá. Đối chiếu lại bằng cùng một luật thì không có luật thứ hai để lệch.

Gỡ liên kết khách hàng khỏi hội thoại (gắn nhầm người)

Danh sách nhân viên có thể nhận phân công. Endpoint riêng của phân hệ chứ không dùng chung User/SugStaff: đường kia đòi role User.SugStaff mà nhân viên chăm sóc khách hàng không có lý do gì phải có. Nhưng nó phải chấm ĐÚNG phạm vi dữ liệu mà User/SugStaff chấm — mặc định của DataAccessScope là SelfOnly, nên bỏ bước này là một tài khoản vốn chỉ thấy chính mình lại đọc được danh bạ nhân sự của cả công ty. Role mở cửa vào tính năng, không mở rộng phạm vi dữ liệu.

Từ khoá theo tên hoặc tên đăng nhập Kênh của hội thoại sắp phân công. Truyền vào thì kết quả bị thu hẹp thêm một lần nữa — chỉ còn người có tên trong danh sách phụ trách của kênh, nếu kênh đó đã bật hàng rào. Không truyền thì giữ nguyên hành vi cũ; kênh Shared cũng vậy.

Phân công hội thoại cho nhân viên, hoặc gỡ phân công khi không truyền mã nhân viên. Trên kênh Shared đây vẫn CHỈ là nhãn. Trên kênh đã bật hàng rào, phân công là hành động đổi phạm vi dữ liệu — nên có ba lớp chặn: hội thoại phải nằm trong phạm vi mình thấy (tầng service), người được gán phải trong phạm vi nhân sự của mình (ngay dưới đây), và phải có tên trong danh sách phụ trách kênh (tầng service).

Nhả hội thoại về hàng chờ.

Không chấm gì thêm ở đây, và đó là chủ ý: câu hỏi "tôi có được nhả hội thoại này không" chính là câu hỏi "hội thoại này có nằm trong phạm vi ghi của tôi không", mà phạm vi thì tầng service hỏi IChatVisibilityResolver. Một sale mức Self vì thế chỉ nhả được hội thoại mình đang cầm; trưởng nhóm nhả được hội thoại của kênh mình.

Chuyển hội thoại sang nhân viên khác.

Đường này không được thành đường đọc trộm (§3.11). "Chuyển về cho mình rồi đọc" bị chặn ở tầng service, bằng chính hàng rào: hội thoại phải nằm trong phạm vi ghi của người thực hiện trước đã, nên một sale không chuyển được hội thoại của người khác về mình — họ không nạp nổi nó. Ở đây chỉ còn vế thứ hai, giống hệt assign: người nhận phải nằm trong phạm vi nhân sự của người chuyển. Vế thứ ba — người nhận phải có tên trong danh sách phụ trách kênh — nằm ở tầng service, dùng lại đúng một hàm với assign.

Thu hồi quyền xem một hội thoại của nhân viên đã thôi giữ nó.

Đường này tồn tại vì §6.2 có một khe hở mà chính người sắp bị cắt điều khiển được: cờ KeepReadAccess chỉ ghi lúc đóng một lượt đang mở, nên sale tự nhả trước với lý do hành chính là lượt của họ đóng lại với cờ giữ quyền — và từ đó quản lý không còn lượt nào để đóng, dù khách đã phàn nàn. Role là quyền định đoạt người phụ trách (Transfer) hoặc quản trị phân phối; phạm vi dữ liệu vẫn do tầng service chấm, nên một sale không thu hồi được quyền xem của ai trên hội thoại ngoài phạm vi ghi của mình.

Lịch sử phân công của một hội thoại — "ai từng cầm hội thoại này, vì sao thôi cầm". Hội thoại ngoài phạm vi đọc trả về danh sách rỗng, không phải lỗi.

Hàng chờ — hội thoại chưa giao cho ai (sổ nợ PP-14).

Hai quyền cùng vào được, vì có hai vai làm cùng một việc: người điều phối toàn hệ thống (ChatDistribution.Manage) và trưởng nhóm của một kênh (ChatConversation.ViewChannel). Phạm vi dữ liệu của hai vai vẫn khác nhau — trưởng nhóm chỉ thấy hàng chờ của kênh mình, và điều đó do IChatVisibilityResolver quyết, không do role.

Một nhân viên có nằm trong phạm vi nhân sự mà người đang đăng nhập được phép chọn không.

Đúng luật của staff/suggest ở trên, viết một lần cho cả assign lẫn transfer. Không có bước này thì gọi lần lượt mã 1, 2, 3… là đọc được tên của toàn bộ bảng người dùng, kể cả tài khoản khách hàng, và giao được việc cho tài khoản đã khoá. Hai đường ghi cùng hình dạng mà chép luật ra hai chỗ là để chúng lệch nhau ở lần sửa sau — đúng hình dạng lỗi IDOR của docs/security-audit-2026-07-11.md. Ba mức, và mức SelfOnly lấy phạm vi từ một nguồn KHÁC hai mức kia (sổ nợ PP-38, kế hoạch §6.6, chốt 2026-08-30). All và ManagedTeam đọc phạm vi nhân sự từ UserPreference; SelfOnly thì không có phạm vi nhân sự nào cả, nên nó lấy danh sách phụ trách của chính kênh chứa hội thoại này. Lý do là một con số: 40/40 sale nhóm "Kinh doanh" đều SelfOnly (đo trên dev 2026-08-30, chưa đối chiếu production), nên trước bản vá này nút "Chuyển khách" là ngõ cụt với toàn đội: họ chỉ chọn được chính mình, mà chọn chính mình thì transfer trả "Người này đang phụ trách hội thoại." Phạm vi mới HẸP hơn ManagedTeam, và hẹp theo hai chiều cùng lúc: người nhận phải có tên trong danh sách phụ trách kênh, và chính người chuyển cũng phải có tên trong đó. Vế thứ hai là chữ "cùng" của §6.6, và nó không phải trang trí: thiếu nó thì trong suốt cửa sổ dry-run — mọi kênh còn Shared, nên BuildWritableConversationFilter trả _ => true và mọi sale có phạm vi GHI trên mọi hội thoại — một sale bất kỳ sẽ chuyển được hội thoại bất kỳ cho bất kỳ ai trong danh sách phụ trách của kênh đó, rộng hơn hẳn điều §6.6 mở ra. Có vế thứ hai thì hành vi trước bước 3 gần như không đổi, đúng nguyên tắc số 1. Trên kênh đã bật hàng rào, bản vá này chỉ làm ô chọn khớp với luật máy chủ vốn đã áp: người nhận vốn đã phải qua IsAssignableToChannelAsync ở tầng service. Trên kênh Shared thì máy chủ không áp hàng rào kênh nào cả (hàm kia trả true vô điều kiện), nên ở đó luật này chặt hơn máy chủ — sai về phía an toàn, chiều duy nhất được phép sai. Ba điều bản vá KHÔNG làm (§6.6): không nới phạm vi ĐỌC — ChatVisibilityResolver không đổi một dòng, nên sale vẫn không thấy hội thoại của người mình vừa chọn; không nâng DataAccessScope — lối ra (c) bị loại có chủ ý vì nó nới cả phạm vi đọc của CRM và nhân sự, đúng bẫy "mượn phân quyền miền khác" đã cắn ba lần ở đợt KPI; không để staff/suggest lệch khỏi hàm này — hai chỗ cùng đọc một danh sách qua IChatChannelStaffService, và lệch nhau là tự tay dựng lại một PP-36 mới. Vì sao nới cả assign chứ không tách hai luật. Nhóm quyền 2 giữ ChatConversation.Assign từ đợt chat đa nền tảng, nên hàm này phục vụ cả hai đường của cùng một người, và staff/suggest cũng phục vụ cả hai ô chọn. Tách hai luật là để ô "Phân công" gợi ý ra những người mà assign sẽ từ chối — tự tay dựng lại PP-36, đúng điều ràng buộc thứ hai của §6.6 cấm. Hệ quả phải nói ra chứ không giấu: assign ghi nhật ký với lý do cố định và ghi chú rỗng, còn transfer bắt buộc lý do + ghi chú, và chính lý do đó quyết định người cũ còn quyền xem hay không (§6.2). Nghĩa là sale nay có một đường đổi người không ghi lý do. Vẫn có vết — một dòng ChatConversationAssignment — nên nguyên tắc số 1 mục 4 không bị vi phạm, nhưng giao diện phải tiếp tục dẫn người dùng vào nút "Chuyển". "Nhận về tôi" luôn nằm trong phạm vi: chọn chính mình không mở rộng phạm vi đọc của ai. Nhân viên được chọn làm người nhận Người đang thực hiện Hội thoại đang thao tác — nguồn của "cùng kênh" ở mức SelfOnly. Máy chủ tự tra kênh từ mã hội thoại; tuyệt đối không nhận mã kênh từ client, vì khi đó người gọi gửi mã kênh mình CÓ phụ trách kèm mã hội thoại của kênh KHÁC là chấm người nhận trên sai kênh.

Hai người có cùng nằm trong danh sách phụ trách kênh của một hội thoại không — phạm vi của mức SelfOnly (sổ nợ PP-38).

Bước cuối vẫn đi qua IChatStaffDirectory, không tự truy vấn bảng người dùng: sàn "tài khoản kiểu nhân viên, chưa khoá" phải giữ nguyên. Một dòng ChatChannelStaff trỏ tới tài khoản đã khoá hay tài khoản khách hàng vẫn phải bị chặn — restrictToStaffIds là phép THU HẸP thêm, không phải đường đi vòng.

Đổi trạng thái vòng đời của hội thoại: đang xử lý / chờ khách / đóng / mở lại. Cả bốn chuyển dịch dùng chung role ChatConversation.Close — đó là quyền "định đoạt vòng đời hội thoại". Role này seed từ giai đoạn B, mô tả của nó được migration giai đoạn D chỉnh lại cho khớp phạm vi thật.

Điểm nhận webhook của các nền tảng chat. Đây là bề mặt công khai duy nhất của phân hệ chat. Ba nguyên tắc của mọi endpoint trong lớp này: (1) tự bảo vệ bằng chữ ký chứ không bằng đăng nhập — nền tảng gọi tới không mang JWT; (2) LUÔN trả 200 khi lỗi nội bộ, nếu không nền tảng sẽ gửi lại vô hạn; (3) không bao giờ ghi nhật ký nội dung khoá bí mật hay chữ ký.

Tiền tố đường dẫn của toàn bộ endpoint webhook. Dùng chung cho FrontendOriginMiddleware.BypassPaths và phần miễn giới hạn tốc độ toàn cục — giữ một chỗ khai báo để ba nơi không bao giờ lệch nhau.

Giới hạn kích thước thân request: 1 MB, đủ rộng cho payload webhook lớn nhất của Zalo/Facebook

Nhận sự kiện webhook của Zalo Official Account.

Bước bắt tay Facebook gọi đúng một lần lúc khai báo webhook trên cổng nhà phát triển (và mỗi lần đổi URL). Khớp verify token thì phải trả về nguyên văn hub.challenge. Zalo không có bước này — đây là lý do endpoint Facebook cần thêm một động từ GET. Trả text/plain chứ không phải JSON: Facebook so sánh nguyên văn thân phản hồi với giá trị nó gửi đi, thêm dấu nháy của JSON là hỏng.

Nhận sự kiện webhook của Facebook Messenger (Page).

Bật thì chữ ký sai bị từ chối bằng 401; tắt thì chỉ ghi cảnh báo rồi vẫn xử lý. Mặc định BẬT khi khoá cấu hình vắng mặt. Trước đây mặc định là tắt, nghĩa là một appsettings.json cũ chưa có khối SocialChat sẽ nhận mọi webhook không cần chữ ký — lớp bù duy nhất lúc đó là đối chiếu app_id, mà app_id không phải bí mật: nó nằm ngay trong đường dẫn cấp quyền được gửi cho admin OA bên ngoài. Muốn tắt thì phải khai tường minh false, tức là một quyết định có người ký tên.

Đọc thân request nguyên văn cùng toàn bộ header. Chữ ký được tính trên chuỗi thô nên tuyệt đối không đọc qua model binding.

Chạy luồng xử lý chung. Mọi lỗi nội bộ đều bị nuốt và trả 200 kèm nhật ký mức Error — trả mã lỗi ra ngoài chỉ khiến nền tảng gửi lại mãi mà không sửa được gì.

Kiểm app_id trong payload có đúng ứng dụng Zalo của LADA không. Đây là lớp bảo vệ duy nhất còn lại khi chữ ký chưa xác minh được (sổ nợ SC-7), nên nó **đóng khi thiếu cấu hình**: chưa khai App ID thì không có cách nào biết payload là của ai, và một webhook công khai không danh tính thì phải từ chối chứ không phải cho qua.

Controller để xử lý các hoạt động liên quan đến đại lý.

Controller để xử lý các hoạt động liên quan đến đại lý.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý đại lý. Dịch vụ xử lý người dùng. Dịch vụ phân giải role của user. Dịch vụ xuất Excel vùng phủ.

Lấy danh sách agencyIds thuộc chi nhánh hiện tại và con cháu. Trả về null nếu user không bị giới hạn phạm vi (Founder hoặc không có agency).

Kiểm tra agencyId có nằm trong phạm vi chi nhánh cho phép không.

Tìm kiếm các đại lý dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tạo hoặc cập nhật thông tin đại lý.

Model chứa thông tin đại lý. Kết quả của hoạt động tạo hoặc cập nhật.

Lấy thông tin chi tiết của một đại lý dựa trên ID.

ID của đại lý. Thông tin chi tiết của đại lý.

Tìm kiếm đại lý dựa trên từ khóa.

Từ khóa tìm kiếm. Danh sách đại lý phù hợp.

Xóa một đại lý dựa trên ID.

ID của đại lý. Kết quả của hoạt động xóa.

Cập nhật trạng thái của một đại lý.

Model chứa thông tin trạng thái của đại lý. Kết quả của hoạt động cập nhật trạng thái.

Lấy danh sách đại lý dưới dạng cây.

Từ khóa tìm kiếm. Danh sách đại lý dưới dạng cây.

Xuất Excel vùng phủ của tất cả chi nhánh trong phạm vi quyền

Kết quả xuất file Excel

Controller để xử lý các hoạt động liên quan đến vùng phủ của đại lý

Khởi tạo một instance mới của lớp .

Service xử lý vùng phủ của đại lý

Lấy thông tin vùng phủ của đại lý

ID của đại lý Thông tin vùng phủ bao gồm danh sách location

Thêm location vào đại lý

Model chứa AgencyId và danh sách LocationIds cần thêm Kết quả của hoạt động thêm

Xóa location khỏi đại lý

Model chứa AgencyId và danh sách LocationIds cần xóa Kết quả của hoạt động xóa

Lấy danh sách location chưa được gán cho đại lý dưới dạng cây (lazy loading)

ID của đại lý ID của location cha (0 = lấy tỉnh/thành phố, >0 = lấy con của location đó) Danh sách location dưới dạng cây hierarchical, chỉ lấy location có type Urban hoặc SubUrban

Tìm kiếm nội dung marketing với SmartTableParam (search, filter, sort, pagination)

Tạo bài blog từ brief

Tạo bài social media từ brief

Duyệt nội dung marketing

Lấy danh sách nội dung chờ duyệt

Lấy chi tiết nội dung theo ID

Mainline model cho Responses API (orchestrator)

Tự động gắn brand context (developer instructions + file_ids + vector store)

Chọn brand assets cụ thể theo key (null = tất cả active)

Tự động viết lại prompt thành prompt tiếng Anh chi tiết trước khi tạo ảnh

Tạo ảnh bằng AI, tải về và lưu vào media storage

Cập nhật nội dung HTML của bài viết (sau khi chèn ảnh)

Lấy brand registry hiện tại

Cập nhật developer instructions

Upload brand asset lên OpenAI Files API

Lấy danh sách brand assets đang active

Xóa brand asset

Sync knowledge base lên OpenAI Vector Store

Trạng thái hiện tại: VectorStoreId đang dùng + danh sách OpenAiFileId của Brand Assets Dùng cho trang Kho tài nguyên để highlight tài nguyên đang active

Đăng ký file đã có trên OpenAI làm Brand Asset (không upload lại)

Gắn Vector Store đã có làm Knowledge Base cho Brand Registry

Helper: Lấy provider entity by Id và tạo HttpClient có auth

Lấy danh sách Vector Stores của 1 provider

Tạo Vector Store mới cho 1 provider POST /v1/vector_stores

Lấy chi tiết 1 Vector Store + files

Lấy danh sách Files đã upload của 1 provider

Upload file lên OpenAI cho 1 provider POST /v1/files (multipart/form-data: file + purpose)

Xóa file trên OpenAI cho 1 provider DELETE /v1/files/{fileId}

Controller quản lý cấu hình ứng dụng (AppConfig)

Tìm kiếm AppConfig với SmartTable

Tham số tìm kiếm Kết quả tìm kiếm

Lấy AppConfig theo Id

Id của AppConfig AppConfig

Tạo hoặc cập nhật AppConfig

Model AppConfig Kết quả thao tác

Xóa AppConfig

Id của AppConfig Kết quả xóa

Reload cache cho tất cả applications

Kết quả reload

API quản lý cache — chỉ Founder mới được phép truy cập.

Lấy thống kê cache: tổng entries, danh sách groups theo prefix, provider đang dùng.

Lấy danh sách cache entries, có thể lọc theo prefix.

Lấy giá trị đầy đủ của 1 cache entry theo key.

Xóa 1 cache entry theo key chính xác.

Xóa tất cả cache entries có key bắt đầu bằng prefix.

Xóa toàn bộ cache.

Phải gọi hai lớp. chỉ xoá được khoá do chính nó ghi (tiền tố "AppConfig:" và các nhóm khác), còn Lada.Framework.AppConfigService ghi thẳng vào IMemoryCache với tiền tố "AppConfig_" — chính là nhóm khoá mà mọi công tắc ContentStore.* đi qua. Thiếu vế thứ hai thì nút này báo "đã xoá" trong khi giá trị cũ vẫn sống, và người vận hành kết luận sai là cấu hình không có tác dụng (nợ CS-20).

Controller để xử lý các hoạt động liên quan đến call path.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý call path.

Lấy danh sách call path theo version/build. Nếu không truyền, lấy danh sách từ phiên bản mặc định.

Số phiên bản (optional, ví dụ: 1.0.0) Số build (optional, ví dụ: 101) Danh sách call path.

Tìm kiếm các call path dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tạo hoặc cập nhật thông tin call path.

Model chứa thông tin call path. Kết quả của hoạt động tạo hoặc cập nhật.

Lấy thông tin chi tiết của một call path dựa trên ID.

ID của call path. Thông tin chi tiết của call path.

Copy tất cả CallPath từ một version sang một version khác.

Thông tin version nguồn và version đích. Kết quả của hoạt động copy.

Controller để quản lý các phiên bản đường dẫn (CallPathVersion).

Lấy tất cả phiên bản (dùng cho dropdown).

Tìm kiếm phiên bản theo các tham số.

Tạo hoặc cập nhật phiên bản.

Lấy thông tin chi tiết phiên bản theo ID.

Xóa phiên bản theo ID.

Controller đọc và duyệt tài liệu API từ thư mục Docs/

Lấy danh sách tài liệu API trong thư mục Docs

Lấy nội dung chi tiết của một tài liệu API

Đường dẫn tương đối của file

Controller để xử lý các hoạt động liên quan tới điểm đầu cuối.

Khởi tạo môt instance mới của lớp .

Dịch vụ xử lý điểm đầu cuối.

Tìm kiếm các điểm đầu cuối dựa trên các tham số tìm kiếm.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tạo hoặc cập nhật thông tin điểm đầu cuối.

Model chứa thông tin điểm đầu cuối. Kết quả của hoạt động tạo hoặc cập nhật.

Lấy thông tin chi tiết của một điểm đầu cuối dựa trên ID.

ID của điểm đầu cuối. Thông tin chi tiết của điểm đầu cuối.

Xóa một điểm đầu cuối dựa trên ID.

ID của điểm đầu cuối. Kết quả của hoạt động xóa.

Tạo các điểm đầu cuối tự động.

Kết quả của hoạt động tạo.

Tạo mới báo lỗi (yêu cầu đăng nhập)

Thông tin báo lỗi Kết quả tạo báo lỗi

Tìm kiếm báo lỗi (dành cho admin)

Tham số tìm kiếm Danh sách báo lỗi

Tìm kiếm báo lỗi do chính người đang đăng nhập gửi. Cố ý KHÔNG đòi role: ai gửi được góp ý thì phải theo dõi được góp ý của mình. Phạm vi dữ liệu bị chặn ở service bằng UserId lấy từ token, không nhận từ tham số.

Tham số tìm kiếm Danh sách báo lỗi của chính người dùng

Lấy chi tiết một báo lỗi do chính người đang đăng nhập gửi.

ID báo lỗi Chi tiết báo lỗi

Lấy chi tiết báo lỗi (dành cho admin)

ID báo lỗi Chi tiết báo lỗi

Cập nhật trạng thái báo lỗi (dành cho admin)

Thông tin cập nhật Kết quả cập nhật

Xóa báo lỗi (dành cho admin)

ID báo lỗi Kết quả xóa

Lấy danh sách báo lỗi theo trạng thái (dành cho admin)

Trạng thái Trang hiện tại Kích thước trang Danh sách báo lỗi

Lấy danh sách báo lỗi mới (dành cho admin)

Trang hiện tại Kích thước trang Danh sách báo lỗi mới

Lấy danh sách báo lỗi đang xử lý (dành cho admin)

Trang hiện tại Kích thước trang Danh sách báo lỗi đang xử lý

Đánh dấu báo lỗi là đang xử lý

ID báo lỗi Kết quả cập nhật

Đánh dấu báo lỗi là đã xử lý

ID báo lỗi Ghi chú từ admin Kết quả cập nhật

Đóng báo lỗi

ID báo lỗi Ghi chú từ admin Kết quả cập nhật

Controller để xử lý các hoạt động liên quan tới Google Maps.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý Google Maps. Dịch vụ xử lý địa điểm.

Kích hoạt công việc lấy tọa độ (lat, long) của phường/xã.

Thông báo kết quả kích hoạt công việc.

Kích hoạt công việc lấy khoảng cách của EndPoints.

Thông báo kết quả kích hoạt công việc.

API xem và thao tác tác vụ nền Hangfire từ SPA quản trị — chỉ Founder, cùng mức với CacheController vì đây là công cụ vận hành hệ thống.

Số liệu tổng quan: đếm theo trạng thái, server đang chạy, queue.

Danh sách tác vụ định kỳ đã đăng ký.

Chạy ngay một tác vụ định kỳ, không đợi tới lịch.

Id tác vụ định kỳ, ví dụ notification-cleanup.

Tạm dừng tác vụ định kỳ trong danh mục: gỡ khỏi lịch, không tự đăng ký lại khi API khởi động.

Đăng ký (lại) tác vụ định kỳ trong danh mục với lịch mặc định.

Xoá hẳn tác vụ định kỳ KHÔNG nằm trong danh mục khỏi lịch Hangfire.

Liệt kê job theo trạng thái (Processing / Scheduled / Enqueued / Succeeded / Failed / Deleted).

Chi tiết một job kèm lịch sử chuyển trạng thái.

Đưa job (thường là job thất bại) trở lại hàng đợi để chạy lại.

Xoá một job khỏi hàng đợi.

Controller để xử lý các hoạt động liên quan tới địa điểm.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý địa điểm.

Tìm kiếm các địa điểm dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Tạo hoặc cập nhật thông tin địa điểm.

Model chứa thông tin địa điểm. Kết quả của hoạt động tạo hoặc cập nhật.

Lấy thông tin chi tiết của một địa điểm dựa trên ID.

ID của địa điểm. Thông tin chi tiết của địa điểm.

Lấy địa chỉ đầy đủ của một phường/xã dựa trên ID.

ID của phường/xã. Địa chỉ đầy đủ của phường/xã.

Xóa một địa điểm dựa trên ID.

ID của địa điểm. Kết quả của hoạt động xóa.

Gọi API tìm kiếm địa điểm dựa trên từ khóa, loại và ID cha.

Từ khóa tìm kiếm. Loại địa điểm. ID cha. Danh sách địa điểm phù hợp.

Tìm kiếm địa chỉ hoàn thành dựa trên từ khóa.

Từ khóa tìm kiếm. Danh sách địa chỉ phù hợp.

Lấy chi tiết địa điểm dựa trên ID địa điểm.

ID của địa điểm. Chi tiết địa điểm.

Kích hoạt công việc cập nhật tên kết hợp (CombinedName).

Thông báo kết quả kích hoạt công việc.

Import dữ liệu Location ĐVHC mới từ database Antin. Import Tỉnh/TP và Phường/Xã 2 cấp, cập nhật MappedWardId cho Location 3 cấp.

Kết quả import

Import dữ liệu Location 2 cấp từ file Excel. File Excel cần có 3 cột: Tỉnh/TP (Mã) | Tên Xã mới | Mã Xã mới

File Excel upload Kết quả import

Cập nhật tọa độ lat/long hàng loạt cho các location chưa có tọa độ. Sử dụng Google Geocoding API để tự động xác định tọa độ.

Danh sách ID location cần cập nhật Kết quả cập nhật

Cấu hình chiến lược mapping địa chỉ → LocationId (dùng cho app khách). Đọc/ghi một key duy nhất Location.MappingStrategy trong bảng AppConfig.

Key cấu hình trong bảng AppConfig (khớp với Lada.AppBackEnd).

Lấy cấu hình chiến lược mapping hiện tại.

Lưu cấu hình chiến lược mapping.

DTO cấu hình chiến lược mapping địa chỉ.

Thứ tự chạy các option (1=nearest ward, 2=name-match, 3=Google).

Cờ bật/tắt từng option (key = số option).

Trang Bản đồ tô phường/xã (/ban-do-phuong-xa): danh sách phường/xã tô màu, dùng chung giữa mọi người. Đọc đòi MapWardList.View, ghi đòi MapWardList.Manage.

Cờ hiển thị nút của trang cho người đang đăng nhập. Cố ý không đòi role nào: người không có quyền vẫn phải hỏi được và nhận toàn false (rule quyen-hien-thi).

Tất cả danh sách tô

Một danh sách tô kèm phường/xã

Tỉnh/thành bộ 2 cấp kèm số phường/xã — bước chọn tỉnh đầu trang

Toàn bộ phường/xã bộ 2 cấp của một tỉnh — 404 khi Id không phải tỉnh bộ 2 cấp

Tạo / sửa danh sách tô — LocationIds thay toàn bộ phường/xã của danh sách

Xoá mềm danh sách tô

Controller xử lý các hoạt động liên quan đến menu.

Khởi tạo một instance mới của lớp .

Dịch vụ xử lý menu.

Tìm kiếm các menu dựa trên các tham số được cung cấp.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Lấy danh sách menu cho ứng dụng và vai trò.

Loại ứng dụng. Danh sách menu.

Lấy cây menu cho quản trị viên.

Cây menu.

Lấy cây menu dựa trên loại ứng dụng và từ khóa tìm kiếm.

Loại ứng dụng. Từ khóa tìm kiếm. Cây menu.

Khóa một menu.

Model chứa thông tin menu cần khóa. Kết quả của hoạt động khóa.

Mở khóa một menu.

Model chứa thông tin menu cần mở khóa. Kết quả của hoạt động mở khóa.

Tạo hoặc cập nhật thông tin menu.

Model chứa thông tin menu. Kết quả của hoạt động tạo hoặc cập nhật.

Lấy thông tin chi tiết của một menu dựa trên ID.

ID của menu. Thông tin chi tiết của menu.

Xóa một menu dựa trên ID.

ID của menu. Kết quả của hoạt động xóa.

Lấy danh sách các ứng dụng.

Danh sách các ứng dụng.

Cấu hình màn hình chặn truy cập bằng điện thoại của app khách hàng (Lada.App): link tải app, ảnh QR và nội dung thông báo. Lưu ở các khoá MobileApp.* trong AppConfig.

Lấy cấu hình hiện tại.

Lưu cấu hình.

Controller quản trị thông báo (Admin). Quản lý categories, gửi broadcast, xem lịch sử.

Lấy danh sách loại thông báo

Tìm kiếm loại thông báo (phân trang, lọc) cho SmartTable

Tạo loại thông báo mới

Cập nhật loại thông báo

Xóa (mềm) loại thông báo. Không xóa cứng vì Notification.CategoryId là FK non-null tham chiếu category.

Gửi thông báo (Admin manual send)

Xem lịch sử thông báo đã gửi

Controller quản lý thông báo cho người dùng. Xem, đánh dấu đã đọc, xóa, cấu hình preferences.

Lấy danh sách thông báo của user hiện tại (phân trang)

Lấy số thông báo chưa đọc

Đánh dấu 1 thông báo đã đọc

Đánh dấu tất cả thông báo đã đọc

Xóa (archive) 1 thông báo

Lấy cấu hình thông báo của user

Cập nhật cấu hình thông báo

Đăng ký device token cho push notification

Xóa device token

Controller xử lý các yêu cầu liên quan đến kho hàng.

Khởi tạo một thể hiện mới của lớp .

Dịch vụ người dùng. Dịch vụ kho hàng.

Xử lý yêu cầu nhập kho cho một đơn hàng.

Mô hình chứa thông tin đơn hàng. Kết quả của quá trình nhập kho.

Tìm kiếm danh sách tài xế theo từ khóa và phân trang.

Từ khóa tìm kiếm tài xế. Số trang cho phân trang. Kích thước trang cho phân trang. Danh sách các tài xế phù hợp với từ khóa tìm kiếm.

Lấy danh sách đơn hàng cần inbound của một tài xế.

Id của tài xế. Số trang. Số bản ghi / trang. Danh sách các đơn hàng cần inbound.

Khởi tạo CourseController.

Tìm kiếm khóa học.

Lấy tất cả khóa học đang hoạt động (cho Learner View). Kết quả được filter theo Permission của user hiện tại. Founder thấy tất cả.

Lấy chi tiết khóa học.

Tạo hoặc cập nhật khóa học.

Xóa khóa học.

Lấy toàn bộ curriculum (sections + standalone lessons) theo GlobalOrder.

Lưu thứ tự curriculum sau khi kéo thả.

Lấy danh sách PermissionIds được gán cho khóa học.

Cập nhật danh sách Permission cho khóa học.

Request model cho cập nhật Permission của khóa học.

Khởi tạo LessonController.

Lấy danh sách bài giảng của section.

Lấy tất cả bài giảng của khóa học (theo GlobalOrder).

Lấy bài giảng độc lập (không thuộc chương nào) của khóa học.

Lấy chi tiết bài giảng (admin).

Lấy chi tiết bài giảng kèm media (learner view).

Tạo hoặc cập nhật bài giảng.

Xóa bài giảng.

Sắp xếp lại thứ tự bài giảng.

Sắp xếp lại thứ tự toàn bộ bài giảng (GlobalOrder) trong khóa học.

Upload media cho bài giảng.

Lấy danh sách media của bài giảng.

Xóa media.

Sắp xếp lại thứ tự media.

Khởi tạo SectionController.

Lấy danh sách sections của khóa học.

Lấy chi tiết section.

Tạo hoặc cập nhật section.

Xóa section.

Sắp xếp lại thứ tự sections.

Section Analytics trong appsettings — MCP tra cứu số liệu vận hành (docs/plan-mcp-tra-cuu-so-lieu.md §1, §3.1). Endpoint /analytics dùng chung host, issuer OAuth, trang đăng nhập/đồng ý và DCR với MCP kho nội dung (); khác PRM, chỉ dẫn server, bộ tool và role.

Fail-fast có điều kiện (quyết định kỹ thuật GĐ A, plan §7): Production + = true mà thiếu ConnectionStrings:AnalyticsConnection hoặc → dừng khởi động. Production mà công tắc còn TẮT thì chỉ cảnh báo: không tool nào chạy, không job nào nạp, không mã nào được băm — dừng cả API vì một tính năng đang tắt chỉ biến một lần deploy vá lỗi khác thành sự cố. Bật công tắc cần khởi động lại, nên lúc đó fail-fast vẫn bắt. Môi trường khác thiếu khoá thì dùng giá trị tạm + cảnh báo (như khoá OpenIddict) để máy dev không vỡ.

Công tắc tổng. TẮT (mặc định): tool trả UNAVAILABLE, job nạp đêm không chạy.

Khoá HMAC của mã băm KH-/NV-/LX-/XE- — base64 của ≥ 32 byte (openssl rand -base64 32).

Đường dẫn endpoint MCP số liệu trên API — nơi DUY NHẤT khai chuỗi này (gate, rate limit, PRM, resource OAuth đều đọc từ đây qua McpSurfaceRegistry). Phải là đường dẫn ngang hàng với /mcp, không lồng dưới nó.

Đường dẫn đã chuẩn hoá: một dấu / đầu, không dấu / cuối.

Connection string đọc schema analytics: AnalyticsConnection, hoặc LadaConnection khi dev thiếu.

Connection string chính (ghi AnalyticsCallLog, job nạp đọc dbo).

true khi đang đọc bằng LadaConnection (không có login chỉ đọc) — chỉ chấp nhận ở dev.

Khoá HMAC đã giải mã.

true khi dùng khoá tạm sinh lúc khởi động — mã băm đổi sau mỗi lần khởi động lại.

Cảnh báo lúc đăng ký service — log khi pipeline dựng.

Đọc section, giải khoá, chọn connection và áp luật fail-fast.

Tách khỏi để test luật fail-fast không cần IConfiguration thật.

Section ContentStore trong appsettings — cấu hình mức triển khai của MCP + OAuth (GĐ C). Những thứ đổi được lúc vận hành (công tắc, whitelist IP, ngưỡng rate limit, allowlist redirect) nằm ở AppConfig trong DB, không ở đây.

McpPublicUrl phải ở appsettings chứ không phải AppConfig vì OpenIddict cần issuer lúc khởi động (trước khi có DB) và PRM resource phải bằng đúng URL người dùng nhập vào connector (plan §7.3). Dev thử qua tunnel thì đổi giá trị này trong appsettings.json cục bộ (gitignore) rồi khởi động lại.

URL MCP công khai — mặc định theo quyết định §7.3: https://mcp.ladaexpress.com/mcp.

Cảnh báo phát hiện lúc đăng ký service (khoá tạm…) — log khi pipeline dựng, vì lúc đăng ký chưa có ILogger.

URI MCP đã chuẩn hoá (tuyệt đối, không dấu / cuối).

Chuỗi resource đúng nguyên văn để so với URL người dùng nhập (bỏ dấu / cuối).

Issuer OAuth = origin của URL MCP (https://mcp.ladaexpress.com).

Đường dẫn endpoint MCP trên API (thường "/mcp").

Khoá và tuỳ chọn của authorization server OpenIddict.

Khoá RSA riêng (PEM, PKCS#8 hoặc PKCS#1) để ký access token. OpenIddict bắt buộc khoá ký bất đối xứng. Thiếu → dùng khoá tạm sinh lúc khởi động (token mất hiệu lực khi khởi động lại) và log cảnh báo. Tạo: openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048.

Khoá đối xứng (base64, ≥ 32 byte) mã hoá access token / mã uỷ quyền / refresh token. Thiếu → khoá tạm + cảnh báo. Tạo: openssl rand -base64 32.

Cho phép endpoint OAuth chạy qua HTTP thường — CHỈ dev/loopback. Production phải false.

Thời hạn access token (phút). Mặc định 60.

Thời hạn refresh token (ngày). Mặc định 14.

Ngưỡng rate limit đọc từ mục RateLimiting của appsettings. Thiếu mục nào thì dùng mặc định ở đây.

Vì sao tách theo user và theo IP (2026-10-16): bản cũ chỉ có một ngưỡng toàn cục 100 request/phút/IP. Cả văn phòng đi ra Internet bằng một IP công cộng (NAT), nên vài chục nhân viên dùng SPA cùng lúc chia nhau đúng 100 request đó — mỗi lần mở trang SPA đã bắn 10–30 lời gọi, cộng thêm header thăm dò chat và hiện diện mỗi 60 giây trên mọi tab — và cứ vài phút lại có người nhận 429 "Quá nhiều yêu cầu" như bị khoá. Nay request đã đăng nhập tính hạn mức theo từng user (), chỉ request chưa đăng nhập mới tính theo IP (). Login theo IP vẫn giữ vì lúc đó chưa biết user là ai, nhưng nới từ 5 lên : token SPA sống 16 ngày nên cả văn phòng thường hết hạn cùng một đợt và đăng nhập lại dồn vào vài phút. Chống dò mật khẩu một tài khoản vẫn do Identity lockout lo (5 lần sai → khoá 5 phút, theo tài khoản, không phụ thuộc IP); ngưỡng IP ở đây chỉ chặn rải mật khẩu qua nhiều tài khoản.

Tên mục cấu hình trong appsettings.

Giới hạn toàn cục cho request đã đăng nhập: số request / phút / user (mọi IP cộng lại). Mặc định 600 — một người dùng thật không giữ 10 request/giây suốt một phút; vượt ngưỡng này gần như chắc chắn là tab lặp vô hạn hoặc script.

Giới hạn toàn cục cho request chưa đăng nhập (hoặc token hỏng/hết hạn): số request / phút / IP. Mặc định 100 — giữ nguyên ngưỡng cũ vì lưu lượng chưa đăng nhập từ một IP vốn rất ít (đăng nhập, báo lỗi).

Endpoint đăng nhập (SPA, app lái xe, trang đăng nhập OAuth): số request / phút / IP. Mặc định 30.

Policy anonymous cho endpoint công khai ít dùng (báo lỗi, đăng ký client MCP, callback OAuth kênh chat): số request / phút / IP. Mặc định 10.

Chỉ cho phép truy cập Hangfire Dashboard khi đã đăng nhập và có role Founder hoặc Admin.

Custom Authorization Handler: xác thực role từ DB thay vì JWT token. Gộp luôn logic Founder bypass.

Constants cho cache keys. Dùng prefix để nhóm và hỗ trợ invalidation theo nhóm. Format: "Group:SubKey" — ví dụ "UserRoles:123"

Danh sách roles của user. Format: UserRoles:{userId}

Giá trị cấu hình hệ thống. Format: AppConfig:{key}

Roles: 15 phút — cân bằng giữa giảm tải DB và đảm bảo quyền cập nhật kịp thời

AppConfig: 1 giờ — cấu hình hệ thống, invalidate khi thay đổi

Cấu hình cache provider. Đọc từ appsettings section "CacheSettings".

Provider: "Memory" (default) hoặc "Redis"

Connection string cho Redis (chỉ cần khi Provider = "Redis"). Ví dụ: "localhost:6379" hoặc "redis-server:6379,password=xxx,ssl=true"

Prefix cho tất cả Redis keys, giúp phân biệt giữa các ứng dụng dùng chung Redis.

Abstraction layer cho cache operations. Cho phép swap implementation (MemoryCache → Redis) mà không ảnh hưởng business logic.

Lấy giá trị từ cache, trả về default nếu không tìm thấy

Lấy từ cache hoặc tạo mới nếu chưa có (cache-aside pattern)

Đặt giá trị vào cache

Xóa một cache entry theo key

Xóa tất cả cache entries có key bắt đầu bằng prefix

Lấy giá trị raw (object) từ cache theo key, dùng cho admin inspection

Lấy tất cả cache keys đang được track

Xóa toàn bộ cache

Implementation dùng IMemoryCache, wrap thêm key tracking để hỗ trợ RemoveByPrefix.

Redis implementation của ICacheService. Dùng StackExchange.Redis, serialize/deserialize qua System.Text.Json. Hỗ trợ key tracking bằng SCAN (không dùng KEYS * để tránh block).

Factory để tạo LadaDbContext cho design-time operations (migrations, scaffolding, etc.)

Mapper

Mapper configuration

Init

Dòng danh sách tô ở panel trái trang Bản đồ tô phường/xã

Danh sách tô kèm phường/xã. Lưu: gửi ; đọc: trả .

Id phường/xã bộ 2 cấp — chỉ dùng khi lưu. Lưu là thay TOÀN BỘ danh sách phường bằng tập này.

Phường/xã trong danh sách — chỉ dùng khi đọc

Một tỉnh/thành bộ 2 cấp ở bước chọn tỉnh. (2 số) = provinceCode trong file ranh giới.

Một phường/xã bộ 2 cấp. là mã hành chính 5 số — khoá ghép với ranh giới trên bản đồ.

"Phường" / "Xã"; rỗng với đặc khu (chữ "Đặc khu" nằm sẵn trong Name)

Toàn bộ bố cục dashboard của user: các zone theo thứ tự, mỗi zone chứa widget instance

Một widget đã nằm trên dashboard — Settings là JSON đã merge DefaultSettings + cài đặt riêng của user

Zone đích; null = zone đầu tiên (tự tạo "Tổng quan" nếu user chưa có zone nào)

Id của UserDashboardWidget

JSON settings — server chỉ giữ các khoá có UserEditable=true trong SettingsSchema

Id của UserDashboardWidget vừa tạo

Kết quả data của một widget — Data đúng envelope theo Type (kpi/chart/list/...)

Lưu toàn bộ bố cục dashboard của user — zone/widget không có mặt trong model sẽ bị xoá mềm. Id = 0 nghĩa là zone/widget mới tạo.

Dòng danh sách catalog trên trang quản trị widget

Form tạo/sửa widget catalog — Code chỉ đặt lúc tạo, sửa sẽ bị bỏ qua

Nhóm quyền cho multi-select trên form admin

Một widget trong thư viện mà user hiện tại được dùng (server đã lọc theo nhóm quyền)

Trả lời của GET api/Order/agency-scope: người đang đăng nhập xem được màn "Đơn hàng bưu cục" không, của bưu cục nào, kèm option cho bộ lọc trạng thái.

Endpoint không đòi role (rule quyen-hien-thi) nên option trạng thái đi kèm ở đây — mượn PrepareOrderListFilter (role Order.Search) là để chủ bưu cục ăn 403 ngay khi mở trang.

Có role và đã gắn bưu cục — chỉ khi này màn mới nạp bảng.

Có role xem đơn bưu cục (hoặc Founder).

Bưu cục của người xem, 0 = chưa gắn.

Tên bưu cục của người xem.

Danh sách trạng thái đơn hàng.

Danh sách trạng thái vật lý.

Dữ liệu bộ lọc danh sách đơn hàng

Danh sách trạng thái đơn hàng

Danh sách trạng thái vật lý

Danh sách phương thức thanh toán phí

Danh sách khách hàng tương ứng filter (nếu truyền CustomerId)

DTO trả về cho danh sách tài khoản quảng cáo đã đồng bộ từ nền tảng.

Kết nối đã lấy tài khoản này về

Tên kết nối để hiển thị

ID tài khoản bên nền tảng

Mã tiền tệ của tài khoản — hiển thị chi phí theo mã này, không giả định VND

Là tài khoản quản lý (MCC) — không tạo chiến dịch trực tiếp trên tài khoản này

Là tài khoản test của nền tảng

Một quảng cáo cụ thể trong nhóm quảng cáo.

Id quảng cáo bên nền tảng — null nghĩa là chưa đẩy lên

Loại quảng cáo của nền tảng (Google AdType: RESPONSIVE_SEARCH_AD…)

Trạng thái duyệt thô của nền tảng (APPROVED, DISAPPROVED…)

Trạng thái duyệt bằng tiếng Việt, tính ở backend để mọi nơi hiển thị giống nhau. Giá trị nền tảng chưa biết thì giữ nguyên chuỗi gốc — không đoán thành "Đã duyệt".

Mẫu quảng cáo trong LADA. null nghĩa là quảng cáo này được đồng bộ về từ nền tảng chứ không do LADA soạn — dữ liệu chỉ đọc, không phải lỗi thiếu dữ liệu.

Đúng khi quảng cáo do LADA soạn và đẩy lên (có mẫu quảng cáo)

Số liệu gộp trong kỳ, null khi chưa đồng bộ số liệu cấp quảng cáo. Để null thay vì các số 0: "chưa có dữ liệu" khác hẳn "có dữ liệu và bằng 0".

Chi tiết một nhóm quảng cáo — dữ liệu đầu trang cho trang nhóm quảng cáo.

Tài khoản quản lý (MCC) — không chứa dữ liệu quảng cáo

Nhóm đã có mặt trên nền tảng chưa

Chiến dịch đã có mặt trên nền tảng chưa

DTO chiến dịch cho danh sách. Chi phí / ngân sách luôn đi kèm — không giả định VND khi hiển thị.

Tên tài khoản quảng cáo

ID bên nền tảng — null nghĩa là chưa đẩy lên

Chi tiết các trường đang lệch với nền tảng (khi SyncStatus = OutOfSync)

Số nhóm quảng cáo

Số liệu gộp trong khoảng ngày đang lọc (FromDate/ToDate của search) — cột số liệu của bảng chiến dịch (plan cải tổ giao diện quảng cáo §3.6). null khi không truyền khoảng ngày, hoặc chiến dịch chưa có dòng số liệu nào trong khoảng đó — giao diện hiện "—", không hiện 0.

Số liệu gộp của một chiến dịch cho bảng danh sách. Cố ý là bản rút gọn của : không mang Daily (25 dòng × 30 ngày là 750 bản ghi thừa cho mỗi trang) và không mang các chỉ số bảng không hiện.

Tỷ lệ nhấp (%) = Clicks / Impressions, tính từ tổng của khoảng ngày

Chi phí mỗi lần nhấp = Cost / Clicks

Chi phí mỗi chuyển đổi = Cost / Conversions; 0 khi chưa có chuyển đổi

Mã tiền tệ của dòng — mỗi dòng hiện theo mã riêng, không giả định cả trang cùng mã

Một chiến dịch có số liệu ở nhiều mã tiền tệ (không nên xảy ra, nhưng phải nói thật nếu có)

Rút gọn từ bản tổng hợp của AdsMetricAggregator — cùng một phép tính với thẻ KPI

Chi tiết chiến dịch: thông tin chiến dịch + nhóm + số liệu tổng hợp.

Thông tin chiến dịch

Danh sách nhóm quảng cáo

Số liệu tổng hợp trong khoảng ngày đang xem (null nếu chưa có dữ liệu)

Nền tảng đọc được từ khoá hay không. UI ẩn hẳn tab "Từ khoá" khi false: tab rỗng đọc thành "chưa cấu hình gì", trong khi thật ra nền tảng không có khái niệm từ khoá (VD Facebook / TikTok nhắm theo đối tượng, không theo từ khoá).

Sửa được từ khoá trên nền tảng hay không (thao tác tiêu tiền)

Nền tảng có khái niệm từ khoá phủ định

Có từ khoá phủ định cấp chiến dịch hay không. Tách khỏi vì đây chính là thứ quyết định tab trên trang chiến dịch — nền tảng chỉ có phủ định cấp nhóm thì tab này vô nghĩa.

DTO trả về cho danh sách và chi tiết kết nối nền tảng quảng cáo. Mọi thông tin mật đều đã được che (abcd***wxyz) — tuyệt đối không trả giá trị gốc ra API.

Tên hiển thị của kết nối

Nền tảng

Tên nền tảng để hiển thị

Trạng thái kết nối

Tên trạng thái để hiển thị

OAuth Client ID — không phải secret, trả nguyên

Client Secret đã che

Developer token đã che

ID tài khoản quản lý (MCC)

Đã có refresh token hay chưa — UI dùng để biết có cần bấm "Cấp quyền" không

Thời điểm access token hết hạn

Số tài khoản quảng cáo đã đồng bộ về

Mẫu quảng cáo trả về cho danh sách và form. Headline / description trả về dạng mảng đã parse — frontend không phải tự đọc JSON.

Danh sách tiêu đề

Danh sách mô tả

Nội dung AI Marketing đã dùng làm nguồn

Bài viết CMS đã dùng làm nguồn

Số quảng cáo đang dùng mẫu này — mẫu đã dùng thì không cho xoá

Kết quả kiểm tra mẫu quảng cáo theo giới hạn của nền tảng. Frontend dùng để hiện cảnh báo ngay trên form, không đợi Google trả lỗi.

Mẫu đã đủ điều kiện đẩy lên nền tảng chưa

Danh sách lỗi phải sửa mới publish được

Danh sách cảnh báo — vẫn publish được nhưng nên xem lại

Gợi ý mẫu quảng cáo sinh ra từ một nội dung nguồn (AI Marketing / bài CMS). Text vượt giới hạn ký tự được trả kèm bản rút gọn đề xuất — người dùng tự quyết, hệ thống không cắt cụt âm thầm.

Tên mẫu gợi ý

Các tiêu đề gợi ý

Các mô tả gợi ý

Giới hạn của nền tảng đích — form đếm ký tự theo object này

Ghi chú cho người dùng (tiếng Việt)

Một đoạn text gợi ý kèm thông tin về giới hạn ký tự.

Text gốc lấy từ nội dung nguồn

Bản đề xuất đã rút gọn cho vừa giới hạn (bằng text gốc nếu đã vừa)

Độ dài text gốc

Giới hạn ký tự của nền tảng cho loại text này

Text gốc vượt giới hạn — người dùng cần xem lại bản rút gọn

Nhóm quảng cáo trả về cho danh sách và chi tiết chiến dịch.

Tên chiến dịch cha. Do service điền cho trang hiện tại (AutoMapper không map được), nên null ở các đường không điền. Trang "Nhóm quảng cáo" toàn tài khoản không có ngữ cảnh chiến dịch nào cả — không có cột này thì 149 dòng nhóm không biết thuộc về đâu.

Chiến lược đặt giá của chiến dịch cha — quyết định giá thầu nhóm có tác dụng hay không (plan §3.5). Điền cùng lúc với .

Tên tài khoản quảng cáo. Điền cùng lúc với .

Id nhóm bên nền tảng — null nghĩa là chưa đẩy lên

Giá thầu CPC tối đa theo đơn vị tiền tệ của tài khoản

Loại nhóm của nền tảng (Google AdGroupType)

Số quảng cáo trong nhóm. Do service đếm và gán, AutoMapper không map được (entity không có sẵn số này) nên mặc định 0 khi gọi qua đường không đếm.

Số từ khoá nhắm mục tiêu trong nhóm

Số từ khoá phủ định của riêng nhóm (không tính phủ định cấp chiến dịch)

Một loại việc cần xử lý đã gộp — một dòng của panel "Việc cần xử lý" (plan §3.4). Phân loại và đặt tiêu đề làm ở backend: giao diện chỉ hiện và đổi nút theo , không parse JSON lệch. đã trừ các mục bị bỏ qua còn hạn; là phần bị ẩn, để hiện "đã bỏ qua N · Hiện lại".

Loại bản ghi của mọi mục trong nhóm — cần khi gọi bỏ qua

Nhãn nút hành động chính

Tiêu đề dòng, đã kèm số đếm — ví dụ "80 chiến dịch có khung giờ chạy trên Google mà LADA chưa nhập"

Một câu nói hành động chính làm gì / có tốn quota không, để người bấm không phải đoán

Số mục đang hiện (sau khi trừ bỏ qua)

Số mục đang bị bỏ qua còn hạn

Id của mọi mục đang hiện (tối đa 500) — giao diện dùng cho hành động hàng loạt và bỏ qua cả nhóm mà không cần tải đủ . Vượt trần thì .

Chi tiết từng mục, tối đa 200 — quá thì giao diện mở bộ lọc bảng thay vì cuộn

Một mục trong nhóm — gắn với đúng một bản ghi

Id bản ghi dạng chuỗi (Guid chiến dịch, int tài khoản / kết nối, mã cố định mức hệ thống)

Tóm tắt nội dung việc, đủ để quyết mà không cần mở chi tiết

Việc có từ lúc nào (lần đánh dấu / đồng bộ gần nhất)

Id bản ghi cha khi hành động cần tới nó — tài khoản chậm đồng bộ mang Id kết nối

Một từ khoá (thường hoặc phủ định) trả về cho danh sách và chi tiết.

Nhóm chứa từ khoá — null với từ khoá phủ định cấp chiến dịch

Id criterion bên nền tảng — null nghĩa là chưa đẩy lên

"Phủ định" hoặc "Nhắm mục tiêu" — tính ở backend để mọi nơi hiển thị giống nhau

Nội dung kèm ký hiệu kiểu khớp theo đúng cách Google Ads hiển thị: [chính xác], "cụm từ", còn khớp rộng thì để trần.

Giá thầu CPC riêng — null nghĩa là dùng giá thầu của nhóm

"theo nhóm" khi không đặt giá thầu riêng, để bảng không có ô trống mơ hồ

Trạng thái duyệt thô của nền tảng (APPROVED, DISAPPROVED…)

Điểm chất lượng 1–10; null nghĩa là nền tảng chưa đủ dữ liệu để tính

Số liệu gộp trong kỳ, null khi chưa đồng bộ số liệu cho từ khoá này. Cố ý để null thay vì trả về các số 0: "chưa có dữ liệu" khác hẳn "có dữ liệu và bằng 0".

Bối cảnh của một phạm vi từ khoá (một chiến dịch hoặc một nhóm) — không kèm danh sách. Đây là thứ UI cần để quyết định hiện/ẩn nút và hiện cảnh báo: năng lực nền tảng, trạng thái publish, có thay đổi chưa đẩy hay không, và số lượng từng loại. Tách khỏi danh sách vì danh sách phải phân trang (một nhóm có thể tới hàng nghìn từ khoá) trong khi mấy con số này tính bằng một câu đếm gộp, không cần đọc dòng nào về bộ nhớ.

Nhóm đang xem — null khi đang xem ở cấp chiến dịch

Chiến dịch đã có mặt trên nền tảng chưa — chưa thì không đẩy được từ khoá

Nhóm đã có mặt trên nền tảng chưa (chỉ có nghĩa khi xem ở cấp nhóm)

Tài khoản quản lý (MCC) không chứa từ khoá

Nền tảng có dry-run hay không — không có thì nút "Xem trước" phải ẩn

Giới hạn số từ khoá mỗi nhóm của nền tảng; 0 = không rõ giới hạn

Có dòng nào chưa khớp nền tảng (nháp hoặc đã sửa trong LADA)

Ghi chú cố định về danh sách phủ định dùng chung (shared set) mà LADA không đọc. Phải hiện lên UI: người dùng không được tưởng danh sách ở đây là đầy đủ.

Số từ khoá nhắm mục tiêu trong phạm vi

Số từ khoá phủ định của chính phạm vi đang xem: phủ định cấp chiến dịch khi xem theo chiến dịch, phủ định của riêng nhóm khi xem theo nhóm.

Số từ khoá phủ định thuộc các nhóm bên trong, chỉ có nghĩa khi xem ở cấp chiến dịch. Đếm riêng vì phạm vi ảnh hưởng khác hẳn: phủ định cấp chiến dịch áp cho mọi nhóm, phủ định của nhóm thì không — gộp một số sẽ khiến người dùng hiểu sai sức ảnh hưởng.

Bối cảnh kèm toàn bộ danh sách từ khoá của một phạm vi. Chỉ dùng cho luồng đẩy lên nền tảng (apply), nơi bắt buộc phải có đủ mọi dòng để tính diff. Màn hình danh sách không dùng cái này — nó gọi search phân trang cộng với context, vì một nhóm có thể có hàng nghìn từ khoá.

Từ khoá thường (nhắm mục tiêu) — luôn cấp nhóm

Từ khoá phủ định trong phạm vi đang xem

Một dòng số liệu theo ngày.

Id bản ghi canonical tương ứng

Mã tiền tệ của chi phí — hiển thị theo mã này, không quy đổi

Số liệu tổng hợp trong một khoảng ngày. CTR / CPC / CPA được tính lại từ tổng, không lấy trung bình của trung bình (trung bình của CTR từng ngày cho ra số sai khi lượng hiển thị các ngày lệch nhau).

Tỷ lệ nhấp (%) = Clicks / Impressions

Chi phí mỗi lần nhấp = Cost / Clicks

Chi phí mỗi chuyển đổi = Cost / Conversions

Tỷ lệ doanh thu trên chi phí = ConversionValue / Cost

Đúng khi số liệu được gộp từ nhiều tài khoản dùng mã tiền tệ khác nhau. Lúc đó là tổng của các đơn vị tiền khác nhau nên KHÔNG có nghĩa về mặt tiền tệ — UI phải cảnh báo thay vì hiển thị như một số tiền bình thường. Hệ thống cố tình không quy đổi vì không có nguồn tỷ giá đáng tin tại thời điểm chi.

Số liệu từng ngày để vẽ biểu đồ

Số liệu tổng quan toàn hệ thống kèm kỳ trước để so sánh. Kỳ trước dài đúng bằng kỳ hiện tại và nằm liền sát phía trước, nên hai kỳ so được với nhau.

Số liệu kỳ đang xem. Null khi kỳ này chưa có dữ liệu nào.

Số liệu kỳ liền trước. Null khi kỳ trước chưa có dữ liệu.

Số tài khoản quảng cáo có phát sinh số liệu trong kỳ

Số chiến dịch có phát sinh số liệu trong kỳ

Lần đồng bộ số liệu gần nhất — để người dùng biết số đang xem mới hay cũ

Số liệu quảng cáo đã về tới đâu — mốc cho thanh ngữ cảnh của phân hệ (plan cải tổ giao diện quảng cáo §3.1-M1). Không phụ thuộc khoảng ngày đang xem: người dùng chọn "Tháng này" khi số liệu dừng từ tháng trước vẫn phải thấy "số liệu đến 18/08".

Ngày mới nhất có dòng số liệu cấp chiến dịch. Null = chưa đồng bộ số liệu lần nào.

Lần đồng bộ số liệu gần nhất (theo dòng số liệu, không theo log)

Một mốc thời gian trong chuỗi số liệu (ngày / tuần / tháng).

Ngày đầu của mốc — dùng để sắp thứ tự

Nhãn hiển thị trên trục hoành (VD "05/08", "Tuần 32", "08/2026")

Tỷ lệ nhấp (%) tính lại từ tổng của mốc

Chi phí mỗi lần nhấp tính lại từ tổng của mốc

Số liệu gộp theo một nền tảng quảng cáo.

Đúng khi nền tảng này có nhiều tài khoản khác mã tiền tệ

Tỷ trọng chi phí trên tổng toàn kỳ (%) — để vẽ donut không phải tự tính ở frontend

Một dòng trong bảng xếp hạng chiến dịch theo số liệu.

Id canonical của chiến dịch — dùng để link sang trang chi tiết

Trạng thái chiến dịch tại thời điểm xem (không phải trạng thái trong kỳ)

Thông tin hiển thị trong hộp thoại xác nhận trước khi đẩy chiến dịch lên nền tảng. Mục đích là bắt người dùng đọc đúng những con số sẽ làm phát sinh chi phí — không phải hộp thoại "Bạn có chắc không?" chung chung.

Tên tài khoản quảng cáo sẽ bị trừ tiền

ID tài khoản bên nền tảng — để người dùng đối chiếu với Google Ads

Tài khoản test của nền tảng thì không tiêu tiền thật

Ngân sách/ngày theo đơn vị tiền tệ của tài khoản

Mã tiền tệ của tài khoản — không quy đổi sang VND

Số ngày chạy dự kiến; null nghĩa là chạy vô thời hạn

Ước tính chi phí tối đa = ngân sách/ngày × số ngày chạy. Null khi chưa có ngày kết thúc — chạy vô thời hạn thì không có trần chi phí.

Số nhóm quảng cáo sẽ được tạo

Số quảng cáo sẽ được tạo

Số từ khoá sẽ được tạo

Trạng thái chiến dịch sau khi tạo (luôn là Tạm dừng)

Lỗi phải sửa mới đẩy lên được

Cảnh báo — vẫn đẩy lên được nhưng nên xem lại

Đủ điều kiện đẩy lên nền tảng chưa

Nền tảng có hỗ trợ kiểm tra trước khi đẩy (dry-run) không

Một khung giờ chạy quảng cáo trả về cho UI. Các chuỗi hiển thị (, , ) được tính ở backend để mọi nơi hiển thị giống nhau — frontend không phải tự suy ra, nhất là phần đổi hệ số sang phần trăm (chỗ rất dễ nhầm).

Id criterion bên nền tảng — null nghĩa là chưa đẩy lên

Thứ trong tuần bằng tiếng Việt (Thứ Hai … Chủ Nhật)

Khoảng giờ đã format sẵn, ví dụ "08:00 – 17:00"

Hệ số điều chỉnh giá thầu theo đúng dạng của Google (1.2 = +20%). null = không điều chỉnh.

Hệ số giá thầu đã đổi sang phần trăm để hiển thị: "+20%", "-50%", "—" khi null, "-100%" khi hệ số = 0.

Một dòng log gọi nền tảng quảng cáo — màn hình debug chính của module. Nội dung request/response đã được scrub credential ở tầng service trước khi lưu.

Mã lỗi gốc của nền tảng — giữ nguyên để tra tài liệu Google

DTO trả về cho danh sách và chi tiết của AI Provider.

DTO trả về cho danh sách và chi tiết nội dung marketing AI.

Tiêu đề nội dung

Loại nội dung: blog, social_post

Brief gốc từ user

Trạng thái workflow (enum)

Trạng thái dưới dạng chuỗi

Platform đăng: facebook, zalo, instagram

Nội dung đầy đủ (HTML hoặc plain text)

Mô tả SEO (chỉ có ở blog)

URL ảnh AI tạo (nếu có)

Ghi chú khi duyệt / từ chối

Thời gian duyệt

Thời gian publish

Thời gian tạo

DTO trả về cho danh sách và chi tiết của Prompt Template.

Item cho AppConfig list/search

Key của AppConfig

Value của AppConfig

Description của AppConfig

Toạ độ của một địa chỉ đơn hàng, trả về sau khi geocode.

Id của OrderAddress

Vĩ độ

Kinh độ

Nguồn toạ độ: 0 = chưa có, 1 = chính xác, 2 = gần đúng (tâm đơn vị hành chính)

Cấu hình cho từng loại triển khai (Strategy Pattern)

Các trạng thái đơn hàng hợp lệ cho loại triển khai

Các trạng thái vật lý hợp lệ cho loại triển khai

Loại địa chỉ hiển thị trên location tree

Trạng thái vật lý sau khi gán nhân viên

Loại hành động ghi lịch sử

Template lời nhắn track: "{updater} {message} {user}"

Nếu true, filter đơn hàng theo ops.AgencyId (đơn đang ở kho nào) Nếu false, filter theo ExpectAgencyPickupId hoặc ward.AgencyId

Nếu true, loại trừ đơn có ExpectAgencyDeliveryId = currentAgencyId Dùng cho Transit: chỉ lấy đơn chuyển sang bưu cục khác

Filter theo OrderDirection nếu có giá trị Dùng cho Return (ToReturn) và Delivery (ToDelivery)

Nếu true, chỉ lấy đơn có ExpectAgencyReturnId = currentAgencyId Dùng cho Return: chỉ trả về đơn thuộc bưu cục hoàn dự kiến

Nếu true, chỉ lấy đơn có ExpectAgencyDeliveryId = currentAgencyId Dùng cho Delivery: chỉ lấy đơn thuộc bưu cục phát dự kiến

Factory cung cấp cấu hình cho từng loại triển khai

Lấy cấu hình theo loại triển khai

Dữ liệu về vị trí và số lượng đơn triển khai

Id của lái xe

Tên đăng nhập của lái xe

Họ và tên của lái xe

SĐT của lái xe

Số lượng đơn hàng đã gán pickup

Số lượng đơn hàng đang lấy

Số lượng đơn hàng đã lấy

Số lượng đơn hàng đã gán giao

Số lượng đơn hàng đang giao

Số lượng đơn hàng đã giao

Một lựa chọn "Bên phát hoàn" ở hộp Trả về (Ví v2 plan §3.8.1) — chỉ chi nhánh LADA đang hoạt động; bưu cục đã lấy hàng là lựa chọn mặc định (không nằm trong danh sách).

Mã vận đơn

Ghi chú đơn hàng

Đơn hàng của sale nào

Tuyến

Toàn bộ ảnh đã chụp cho đơn (lấy / giao / trả / kho), bất kể ai chụp. Điền ở DriverAppOrderService.GetById và SearchActiveOrders (thẻ đơn hiện ảnh để lái xe phân biệt hàng); các danh sách khác để rỗng.

App lái xe phải hiện ô "Số tiền đã thu" và gửi CollectedAmount khi lấy đơn này (lái xe bưu cục nhượng quyền bật ví, đơn Ví ghi GỬI-TRẢ). Máy chủ quyết bằng OrderPaymentRules.DecidePickupCollect; chỉ điền cho đơn đang đi lấy ở DriverAppOrderService, các danh sách khác để mặc định.

Số điền sẵn trong ô (số đã ghi trên đơn → cước thu người gửi → cước tạm tính).

Số tối đa máy chủ nhận (150 % cước tạm tính).

Câu hiện dưới số tiền: gợi ý / tối đa, hoặc vì sao không thu cước khi lấy; null = không hiện.

Đối tượng đại diện cho một mục đơn hàng nhập kho.

Mã đơn hàng.

Mã code của đơn hàng.

Ghi chú của đơn hàng.

Trạng thái của đơn hàng.

Tên trạng thái

Trạng thái vật lý của đơn hàng.

Tên trạng thái vật lý

Nội dung trạng thái của đơn hàng.

Hướng của đơn hàng.

ID của người phụ trách.

Tên người phụ trách.

Ghi chú khi lấy hàng.

Ghi chú khi giao hàng.

Trọng lượng tính phí.

Σ cân kiện (gram, Σ OrderPackage.SubTotalWeight) — cân máy chủ dùng chốt cước khi không có cân bàn. Hộp nhập kho hiện làm "Cân khai" (V-49: = 0 ở 100 % đơn nên dòng cân khai từng trống).

Số tiền thu hộ.

Phí bao gồm COD.

Loại phí thanh toán.

Phí.

Giảm giá.

Phí COD.

Tổng phí.

Phí nguồn.

Phí đích.

Phí trả lại.

Phí bảo hiểm.

Đơn hàng của sale nào

Danh sách tệp phương tiện.

Danh sách sản phẩm

Đối tượng đại diện cho một mục phương tiện trong kho.

Id đơn hàng

Đường dẫn hệ thống của mục phương tiện.

Văn bản thay thế cho mục phương tiện.

Chú thích cho mục phương tiện.

Lớp đại diện cho thông tin địa chỉ trong đơn hàng.

ID của đơn hàng.

Tên của người nhận.

Số điện thoại 1 của người nhận.

Địa chỉ 1 của người nhận.

Tên thành phố.

Tên quận/huyện.

Tên phường/xã.

Loại địa chỉ

Loại địa chỉ

Địa chỉ đầy đủ

Lớp đại diện cho thông tin gói hàng trong đơn hàng.

ID của đơn hàng.

Tên của gói hàng.

Số lượng của gói hàng.

Mã đại lý

Tên chi nhánh

Mô tả chi nhánh

Đại lý cha

Người đại diện pháp lý (người của đại lý) Nếu là phòng ban của LADA thì giá trị là 0

Tên cán bộ quản lý

Ngày tạo

Ngày cập nhật

Trạng thái Agency

Tên hiển thị dạng cây: có tiền tố |--- theo cấp — dùng cho dropdown phẳng cũ

Tên chi nhánh thuần (không tiền tố) — AgencyTreeSelect đọc trường này

Chi nhánh cha (0 = gốc) — để client dựng lại cây từ danh sách phẳng

Đối tượng đại diện cho điểm đầu và điểm cuối.

Id của phường/xã gửi.

Id của phường/xã giao.

Tên phường/xã gửi.

Tên quận/huyện gửi.

Tên thành phố gửi.

Tên phường/xã giao.

Tên quận/huyện giao.

Tên thành phố giao.

Khoảng cách đầu cuối (tính bằng mét).

Văn bản hiển thị khoảng cách.

Loại cấp hành chính (2 cấp / 3 cấp).

Danh mục cha

1: Tỉnh / thành phố, 2: Quận / huyện, 3: Phường / xã

Vùng phủ: Nội thành, ngoại thành, không cung cấp

Phụ phí khu vực (VND). Hiện trên danh sách để soát được phường nào đã đặt phụ phí.

Phân loại: 2 cấp (mới) hoặc 3 cấp (cũ)

Item hiển thị location dưới dạng cây (hierarchical)

ID của location

Tên location

Tên đầy đủ (bao gồm cả tên cha)

Cấp độ (1: Tỉnh/Thành phố, 2: Quận/Huyện, 3: Phường/Xã)

ID của location cha

Loại vùng phủ

Tiền tố (Thành phố, Tỉnh, Quận, Huyện, Phường, Xã)

Thứ tự hiển thị

Danh sách location con (Quận/Huyện hoặc Phường/Xã)

Có location con hay không

Số lượng location con (dựa trên Children đã load)

Số lượng location con có thể load (chưa được assign)

Đối tượng đại diện cho mục menu.

Nhãn của mục menu.

Loại của mục menu.

URL của mục menu.

Lớp biểu tượng của mục menu.

Id của mục menu cha.

Tên của mục menu cha.

Trạng thái của mục menu.

Chuỗi trạng thái của mục menu.

Các vai trò được phép truy cập mục menu.

Tên ứng dụng của mục menu.

Thứ tự hiển thị của mục menu.

Cấp độ của mục menu.

Thời gian tạo mục menu.

Thời gian cập nhật mục menu.

Người tạo mục menu.

Người cập nhật mục menu.

Suggestion Location Item

Bộ khối của một vật chủ — GET api/Topic/BlockProfile (topic theo tên hệ thống) và GET api/Product/BlockProfile (trang dịch vụ). Editor FE đọc từ đây, KHÔNG chép danh sách loại khối/icon (plan nhượng quyền website §3.3). = false thì không hiện tab "Khối nội dung" và không gửi khối.

Khoá vật chủ (Product, FranchiseLanding…); rỗng khi không có bộ khối.

Tên đọc được của vật chủ, vd. "trang nhượng quyền".

Luật số lượng lúc lưu (editor kiểm trước khi gửi).

Luật số lượng lúc xuất bản — có thể chặt hơn lúc lưu (trang nhượng quyền: đúng 1 khối Mở đầu). FE dùng để báo trước khi bấm Xuất bản; máy chủ vẫn kiểm lại.

Bộ icon cố định skin của vật chủ vẽ được. Payload lưu .

Hồ sơ máy chủ → bản FE đọc; null = vật chủ không có bộ khối.

Giá trị int của ProductBlockType.

Tên enum (Hero, LeadForm…).

Chuỗi ghi vào items[].icon của payload — dạng vật chủ này lưu (khoá hoặc class FA).

Thân SVG viewBox 0 0 24 24 — hằng trong code server, FE in xem trước được.

Danh mục cha

Là danh mục nổi bật hay không

Loại danh mục

Mã icon Material (chỉ dùng cho ContentType = GoodsType)

Mã nhánh nội dung cấp 2 (A1, B3, F2...) của kho nội dung AI.

Item hiển thị cấu hình tính giá của danh mục hàng hóa (dùng cho trang quản trị, form lên đơn và app khách)

Tên danh mục hàng hóa

Mô tả tiếng Việt của cách áp giá

Số thuộc tính đang dùng

Danh sách thuộc tính động kèm lựa chọn

Item hiển thị thuộc tính động của danh mục hàng hóa

Mô tả tiếng Việt của kiểu thuộc tính

Thuộc tính này có phải trục cột của bảng giá riêng theo tuyến không

Trước GĐ 2 field này không có trong Item, nên trang quản trị không đọc được cờ đã bật — mở form ra rồi bấm Lưu là cờ tắt trở lại, im lặng đưa cả danh mục về nhánh tính theo trọng lượng. Đây là một nửa của nợ N4; nửa còn lại là chiều ghi ở GoodsCategoryAttributeModel.

Item hiển thị lựa chọn kèm giá

Trọng lượng quy ước khi chọn lựa chọn này (kg), 0 = không khai. Form lên đơn cộng số này của các lựa chọn để ra cân của kiện.

Một dòng của ô "Bưu cục liên quan" trên form Bài viết (GET api/Post/AgencyOptions). Tập dòng trùng đúng tập chi nhánh mà bước lưu bài chấp nhận (CmsOptionalLink.IsLinkableAgency).

Id bưu cục (Agency.Id) — giá trị gửi lên ở PostModel.AgencyId.

Mã bưu cục.

Tên bưu cục trong cây tổ chức (Agency.Name).

Tên hiển thị công khai (AgencyProfile.DisplayName); null nếu bưu cục chưa có hồ sơ hoặc hồ sơ đã xoá.

Trạng thái công bố của hồ sơ (AgencyPublishStatus: 1 Nháp, 2 Đang công bố, 3 Tạm ngưng, 4 Đã đóng); null nếu chưa có hồ sơ.

Tiêu đề bài viết

Mô tả ngắn

Trạng thái bài viết

Thời gian tạo

Thời gian cập nhật

Ảnh đại diện

Tên dịch vụ

Mô tả ngắn

Là sản phẩm nổi bật hay không?

Thời gian tạo

Thời gian cập nhật

Nguồn cho hai ô "Tỉnh đi / Tỉnh đến" của form Dịch vụ (GET api/Product/RouteCityOptions): danh sách tỉnh bộ 2 cấp kèm gợi ý đoán từ tên trang.

Tỉnh bộ 2 cấp (Level 1, LevelType = TwoLevel) chưa xoá, sắp theo tên — đúng tập mà bước lưu chấp nhận.

Id tỉnh đi gợi ý (bộ 2 cấp); null nếu không đoán được hoặc tỉnh đoán được là tỉnh cũ đã sáp nhập.

Id tỉnh đến gợi ý (bộ 2 cấp); null như .

Tên tỉnh đi đoán thô từ tên trang, có thể thuộc bộ 3 cấp cũ ("Hải Dương") — còn đó cả khi không map được sang bộ 2 cấp, để giao diện nói được "đoán ra Hải Dương nhưng đó là tỉnh cũ, hãy chọn tay".

Tên tỉnh đến đoán thô, như .

Một tỉnh bộ 2 cấp trong ô chọn tỉnh đi/đến.

Id tỉnh bộ 2 cấp (Location.Id) — giá trị gửi lên ProductModel.RouteFromCityId/RouteToCityId.

Tên đầy đủ kèm tiền tố hành chính, ví dụ "Thành phố Hà Nội".

Tên hệ thống

Gets or sets the title

Gets or sets the body

Table of Content Từ thẻ H3 => H6 Tự sinh trong khi thêm mới / cập nhật bài viết

Thời gian tạo

Thời gian cập nhật

Gets or sets the slug

Tên thực thể và cũng là tên controller luôn

Id của thực thể

Một dòng trên bảng danh sách luật chuyển hướng URL.

Số lượt request đã đi qua luật. Đọc kèm , xem ghi chú ở đó.

Là số xấp xỉ, nghiêng về THIẾU. Website cộng dồn trong bộ nhớ rồi mới ghi xuống, nhiều nhất một lần mỗi phút cho mỗi luật — nên phần chưa kịp ghi sẽ mất khi tiến trình khởi động lại, và ngưỡng "một lần mỗi phút" là theo từng tiến trình web, không phải theo cả website. Ghi ở đây chứ không chỉ ở entity, vì DTO là hợp đồng mà mọi client đọc.

Lần gần nhất có request đi qua; null = chưa ghi nhận lượt nào.

Số ngày trọn vẹn luật đã tồn tại, tính từ .

Có mặt để giao diện không in ra một con số nói dối. Một luật vừa tạo xong và một luật đã nằm đó ba tháng mà không ai gọi tới đều hiện HitCount = 0 — hai tình trạng khác nhau hoàn toàn: cái đầu là chưa biết gì, cái sau là đã đo và không ai vào. Tính ở máy chủ thay vì để giao diện tự trừ ngày, để hai bên không bao giờ nói lệch nhau vì lệch múi giờ hay lệch đồng hồ máy khách. null khi rỗng (dữ liệu cũ chưa có mốc tạo) — lúc đó cũng không kết luận được gì về .

Đường dẫn cũ này có còn đang được khai trong sitemap hay không — ba trạng thái.

true là một mâu thuẫn cần sửa, không phải thông tin phụ: sitemap nói "hãy vào đọc trang này" trong khi máy chủ trả 301 "trang này đã chuyển đi", và công cụ tìm kiếm ghi nhận nó thành lỗi chứ không tự chọn giúp bên nào (bài học GEO-12). false = đã kiểm và không còn. null = chưa kết luận được — chỉ kiểm được một trong hai nguồn, vì hàng tồn kho sitemap (SearchUrl) còn rỗng. Sitemap sinh từ bảy nguồn, mà hơn mười đường dẫn tĩnh (/, /gioi-thieu, /lien-he, /bang-gia…) và toàn bộ trang bưu cục /mang-luoi/{slug} không đi qua UrlRecord, nên soi mỗi UrlRecord rồi trả false là nói về một nhóm chưa kiểm. true KHÔNG có nghĩa "có người bật lại cờ". Có ít nhất bốn đường dẫn tới nó: luật được lưu ở trạng thái tắt (khi đó tầng lưu cố ý không chạm cờ sitemap), một UrlRecord cùng slug được tạo sau, bước tắt cờ hỏng mà luật vẫn vào bảng, hoặc URL vào sitemap từ một nguồn khác UrlRecord. Luật đang tắt luôn cho false vì nó không trả 301 nên không có mâu thuẫn nào.

Một phiên bản khối STYLE BASE / DO NOT dùng chung.

Số ảnh đang trỏ tới phiên bản này — để người sửa biết mình đang đụng vào bao nhiêu ảnh.

Một khuôn ảnh trong từ điển khuôn.

Một ảnh tham chiếu thương hiệu.

Ảnh chụp toàn bộ bộ công cụ ảnh dùng để ghép prompt và hiện hướng dẫn. Nạp một lần cho mỗi lời gọi chi tiết bài — ba bảng này đều là danh mục nhỏ (dưới trăm dòng), không phân trang.

Dòng danh sách bài (list_articles / Search) — rút gọn, không có thân bài.

Một dòng bộ ảnh đã lưu.

Prompt đã ghép sẵn khối STYLE BASE + phần riêng + DO NOT — thứ người tạo ảnh dán thẳng vào công cụ AI. Null khi ảnh không có prompt (dựng tay / chụp thật / không ảnh) hoặc khi chưa cấu hình khối chung; service điền, không map từ entity.

Có prompt riêng nhưng không tìm được khối STYLE BASE nào áp dụng — giao diện phải nói ra.

Mã phiên bản khối thương hiệu ĐÃ dùng để ghép — để người đọc đối chiếu được bản nào đang chạy.

Tên tiếng Việt của khuôn (từ ContentImageFrame), ví dụ "Bảng số".

Mô tả khuôn đủ để người chưa từng làm vẫn dựng được.

Link mẫu dựng sẵn của khuôn (Canva…), nếu có.

Khuôn này dựng tay, không có prompt AI.

Một tác giả / người kiểm tra.

Số bài đang đứng tên tác giả — để không xoá nhầm người còn bài.

Một lượt chạy nháp bài.

Một trang dịch vụ đang chạy trên website (list_service_pages) — trợ lý AI đặt link nội bộ theo danh sách này thay vì bịa URL.

Đường dẫn công khai, đã có dấu "/" đầu: /dich-vu/xe-tai-ghep-ha-noi-thanh-hoa.

Tên trang hiển thị (Product.Name).

Tỉnh đầu suy được từ tên trang; null nếu không suy được.

Giá trị thô cột Product.ProductType (dữ liệu có cả giá trị 0 không nằm trong enum).

Loại trang đọc được: "Hàng hóa chung", "Xe đạp, xe máy", hoặc "Chưa phân loại".

Một đề bài trong hàng đợi.

Một dòng lịch sử phiên bản bài — thanh bên màn chi tiết. Cố ý KHÔNG mang theo BodyMarkdown/BriefJson/SelfScoreJson: bài dài vài chục KB, mà danh sách chỉ cần "ai đổi, lúc nào, ghi chú gì". Xem lại nội dung một bản cũ là việc của giai đoạn sau.

Tên người/trợ lý tạo bản này (ContentArticleVersion.ChangedBy).

CallLog Item - DTO cho hiển thị danh sách cuộc gọi

Identity

Call number - mỗi cuộc gọi có một số, nội bộ của 3CX

Call ID - định danh duy nhất của cuộc gọi

Thời gian cuộc gọi

Thời gian bắt đầu cuộc gọi

Thời gian trả lời

Thời gian kết thúc cuộc gọi

Lý do cuộc gọi bị chấm dứt

Số điện thoại nguồn

Số điện thoại đích

Số được quay

Số cuối cùng

Chi phí của cuộc gọi

Tên tỷ lệ của biến thể thanh toán

Loại nguồn

Loại đích

Tên hiển thị nguồn

Tên hiển thị đích

Distinguished name cuối cùng

Tên hiển thị cuối cùng

Cuộc gọi nhỡ (FinalDN = GRP0000)

Loại cuộc gọi

Trạng thái Lead

Trạng thái Lead dạng string

Nội dung trạng thái

Thời gian tạo

Thời gian cập nhật

Người tạo

Người cập nhật

ID của user được mapping từ FinalDN

Tên user được mapping từ FinalDN

Một khách hàng kèm trạng thái hoạt động tại một thời điểm — kết quả sp_GetActiveCustomersBySale.

"Hoạt động" theo định nghĩa plan §7.4: có ít nhất một đơn tạo trong cửa sổ trượt 3 tháng và đơn đó đã giao thành công.

ID khách hàng

Sale đang phụ trách (Customer.ManagerId)

Tên khách hàng

Số điện thoại

Tên đăng nhập của tài khoản khách (rỗng nếu chưa có tài khoản)

Số đơn đã giao thành công trong cửa sổ 3 tháng

Lần giao thành công gần nhất trong cửa sổ; null nếu không có đơn nào

Có đang hoạt động tại thời điểm chốt không

Vĩ độ điểm đã ghim. 0 nghĩa là địa chỉ chưa được định vị.

Kinh độ điểm đã ghim. 0 nghĩa là địa chỉ chưa được định vị.

Item hiển thị thông tin tài khoản ngân hàng của khách hàng

ID khách hàng

Tên khách hàng

Số tài khoản

Số tài khoản đã che (****1234)

Tên chủ tài khoản

Mã ngân hàng

Tên ngân hàng

Tên chi nhánh

Địa chỉ chi nhánh

Có phải tài khoản mặc định

Ghi chú

Thông tin hiển thị đầy đủ

Có thể sử dụng để chuyển tiền không

Có thể chỉnh sửa không

Có thể xóa không

Thông tin một sale đồng quản lý khách hàng

Dòng khiếu nại của khách hàng trên danh sách xử lý phía nhân viên.

Mã khiếu nại hiển thị cho khách (KN + Id)

Đơn hàng liên quan (không bắt buộc)

Nội dung khiếu nại của khách

Trạng thái: Draft → Processing → Resolved / Cancelled

Phản hồi của nhân viên xử lý (khách xem được qua app)

Chi tiết khiếu nại kèm ảnh đính kèm.

URL ảnh đính kèm (đã là URL tuyệt đối, lưu sẵn khi khách upload)

Dòng yêu cầu đổi nhân viên phụ trách trên danh sách duyệt phía nhân viên.

Nhân viên phụ trách tại thời điểm khách gửi yêu cầu

Lý do khách muốn đổi

Trạng thái: Pending → Approved / Rejected

Họ và tên

Số điện thoại

Địa chỉ

Địa chỉ email

Liên hệ zalo

Liên hệ zalo

Khách có bảng giá riêng hay không — xem CustomerModel.UseCustomPriceList.

Identity

Họ và tên

Số điện thoại

Thông tin cần hỗ trợ

Đường dẫn gửi

Ngày tạo

Ngày tạo hiển thị (dd/MM/yyyy HH:mm)

Ngày cập nhật

Ngày cập nhật hiển thị (dd/MM/yyyy HH:mm)

Người phụ trách

Tên đăng nhập người phụ trách

Trạng thái Lead

Nội dung trạng thái

Item thông tin xuất hóa đơn VAT của khách hàng

ID khách hàng

Tên khách hàng

Mã số thuế

Tên công ty/cá nhân

Địa chỉ

Email nhận hóa đơn

Người liên hệ

Điện thoại

Ghi chú

Mặc định (chỉ có 1 record mặc định cho mỗi khách hàng)

Ngày cập nhật

Người cập nhật

Item chứa thông tin đơn hàng tài chính của lái xe cho search có phân trang

ID của đơn hàng

Mã đơn hàng

Mã đối tác

Số tiền cước lấy hàng (SourceFee) của đơn này

Số tiền cước giao hàng (DestFee) của đơn này

Số tiền thu hộ (COD) của đơn này

Tổng số tiền của đơn này mà driver đang cầm

Trạng thái đơn hàng

Trạng thái đơn hàng dạng string

Trạng thái vật lý đơn hàng

Trạng thái vật lý dạng string

Loại thanh toán cước

Loại thanh toán cước dạng string

Ngày tạo đơn hàng

Ngày tạo đơn hàng dạng string

Ghi chú đơn hàng

Tên khách hàng

Tên người phụ trách (PIC)

Tên tuyến đường

Địa chỉ lấy hàng

Địa chỉ giao hàng

Loại tiền mà driver đang cầm cho đơn này

Driver có phải là người thu tiền ban đầu không

Thời gian thu tiền lần đầu (nếu driver là người thu ban đầu)

Thời gian thu tiền lần đầu dạng string

WardId của địa chỉ lấy hàng (dùng nội bộ để enrich)

WardId của địa chỉ giao hàng (dùng nội bộ để enrich)

Tên người liên hệ (tùy theo loại phí thu) - Thu phí nguồn: Tên người gửi - Thu phí đích/COD: Tên người nhận

Số điện thoại liên hệ (tùy theo loại phí thu)

Địa chỉ liên hệ (tùy theo loại phí thu) - Thu phí nguồn: Địa chỉ gửi hàng - Thu phí đích/COD: Địa chỉ giao hàng

Loại địa chỉ hiển thị (Source/Dest)

Trạng thái nộp tiền của lái xe cho đơn này "Chưa nộp" - Lái xe đang cầm tiền "Đã nộp" - Lái xe đã nộp tiền về

Item tài khoản gửi email (trả về UI). KHÔNG bao giờ trả về giá trị secret thật — chỉ cờ /.

Nhãn hiển thị của loại nhà cung cấp (SMTP/SES/Mock).

Đã cấu hình mật khẩu SMTP hay chưa (không lộ giá trị).

Đã cấu hình secret key SES hay chưa (không lộ giá trị).

Item nhật ký gửi email (chỉ đọc, hiển thị trên trang giám sát). KHÔNG chứa nội dung mã OTP / body — chỉ metadata.

Tài khoản gửi đã dùng (nếu có).

Tên tài khoản gửi (join từ EmailAccount).

Kênh thực tế đã gửi: smtp / ses / mock.

Email người nhận.

Tiêu đề email.

Loại email (đăng ký OTP / khác).

Mô tả loại email.

Trạng thái gửi (1=thành công, 2=thất bại).

Mô tả trạng thái.

Thông báo lỗi (khi thất bại).

Thời gian gửi (ms).

Thời điểm gửi.

Hiển thị thời điểm gửi.

Báo cáo tổng hợp gửi email trong một khoảng thời gian (cho SummaryCard).

Tổng số email đã gửi (mọi trạng thái).

Số gửi thành công.

Số gửi thất bại.

Tỷ lệ thành công (%), làm tròn 1 chữ số.

Item hiển thị thông tin báo lỗi

URL trang web xảy ra lỗi

Nội dung mô tả lỗi

Trạng thái xử lý báo lỗi

Tên trạng thái hiển thị

Ghi chú từ admin khi xử lý

ID người dùng báo lỗi (nếu có)

Tên người báo lỗi

Email người báo lỗi

Số điện thoại người báo lỗi

Thông tin trình duyệt

Thông tin thiết bị

Danh sách hình ảnh lỗi

Item hiển thị thông tin media báo lỗi

ID báo lỗi

URL hiển thị hình ảnh

Tên file gốc

Kích thước file (bytes)

Kích thước file hiển thị

Loại file

Mô tả hình ảnh

Thứ tự hiển thị

DTO Item cho tài khoản ngân hàng

Tên tài khoản ngân hàng

Số tài khoản

Số dư hiện tại

Số lượng giao dịch

Ngày giao dịch cuối cùng

Tên người quản lý

Họ tên người quản lý

Ngày cập nhật số dư cuối cùng

Tài khoản có thể thu hộ COD (tài khoản nhận cước)

DTO Item cho import sao kê ngân hàng

ID tài khoản ngân hàng

Tên tài khoản ngân hàng

Số tài khoản ngân hàng

Tên ngân hàng

Mã ngân hàng

Tên file gốc

Kích thước file (formatted)

Tổng số dòng trong file

Số dòng xử lý thành công

Số dòng lỗi

Số dòng bỏ qua

Số dòng trùng lặp

Trạng thái import

Thông báo lỗi

Ngày bắt đầu của dữ liệu

Ngày kết thúc của dữ liệu

Có ghi đè dữ liệu trùng lặp không

Thời gian bắt đầu xử lý

Thời gian kết thúc xử lý

Thời gian xử lý (formatted)

Tên người thực hiện import

Tỷ lệ thành công (%)

DTO Item cho giao dịch ngân hàng

ID tài khoản ngân hàng

Mã giao dịch từ ngân hàng

Ngày giao dịch

Số tiền ghi có (formatted)

Số tiền ghi nợ (formatted)

Số dư sau giao dịch (formatted)

Nội dung giao dịch

Thời gian giao dịch chi tiết

Trạng thái xử lý

Loại giao dịch

Mã tham chiếu

Tên người gửi/nhận

Số tài khoản người gửi/nhận

Ngân hàng của người gửi/nhận

Tên tài khoản ngân hàng

Số tài khoản ngân hàng

ID import (nếu có)

Số dòng trong file import

Ghi chú xử lý

Thứ tự hiển thị

Một dòng dữ liệu trong báo cáo Cash Flow (VD: "Thu cước", "Đối soát COD")

Nhãn hiển thị (VD: "Thu cước vận chuyển")

Phân loại (Fee, COD, OPEX, Loan, FuelCard, Other)

Số tiền theo từng kỳ (key = ngày hoặc tuần)

Tổng số tiền

Phần trăm trên tổng Inflow hoặc Outflow

Kết quả báo cáo Cash Flow Dashboard

Danh sách cột kỳ (ngày: "2026-04-01" hoặc tuần: "W14")

Các dòng tiền vào

Các dòng tiền ra

Tổng Inflow theo từng kỳ

Tổng Outflow theo từng kỳ

Dòng tiền ròng theo từng kỳ

Tổng dòng tiền vào

Tổng dòng tiền ra

Dòng tiền ròng = Inflow - Outflow

Một dòng chi tiết đơn hàng trong drill-down Thu cước / Thu COD

Mã phiếu đối soát (nếu có)

Kết quả drill-down danh sách đơn theo kỳ / loại

Thời gian thu tiền sớm nhất trong các đơn đang cầm (từ SP) Dùng để tính deadline nộp tiền thay cho LastPaymentTime

Thời gian nộp tiền gần nhất (từ UserPreference, giữ lại để tham khảo)

Số lần vi phạm nộp tiền trong tháng hiện tại

Đang quá hạn nộp tiền (quá 10h sáng hôm sau)

Mức phạt hiện tại theo cấu hình AutoPenaltyLevel (VND)

Mô tả hình thức xử lý (Nhắc nhở / Phạt 100k / ...)

Model cho một dòng trong báo cáo kiểm soát chi phí (dạng cây danh mục)

ID danh mục chi phí

Tên danh mục chi phí

Mã số thứ tự hiển thị (ví dụ: "1", "1.1", "1.1.1")

ID danh mục cha (null nếu là danh mục gốc)

Tổng tiền theo từng ngày: Key = "yyyy-MM-dd", Value = số tiền

Tổng cộng toàn bộ các ngày

Trung bình tiền/ngày (TotalSum / số ngày trong khoảng lọc)

Tỷ lệ phần trăm trên tổng toàn bộ chi phí

Danh sách danh mục con

Kết quả trả về của báo cáo kiểm soát chi phí

Danh sách các ngày trong khoảng báo cáo (yyyy-MM-dd)

Danh sách dòng dữ liệu dạng cây

Tổng tiền theo từng ngày (dòng tổng cuối cùng)

Tổng tiền toàn bộ

Trung bình/ngày toàn bộ

Item tóm tắt đối soát theo khách hàng

ID khách hàng

Tên khách hàng

Số điện thoại khách hàng

Email khách hàng

Số lượng đơn hàng cần đối soát

Tổng tiền COD cần đối soát

Tổng phí dự kiến trừ

Tổng tiền đối soát dự kiến (tính theo logic PayFeeType)

Số tiền dự kiến chuyển (sử dụng logic mới)

Ngày đơn hàng cũ nhất chưa đối soát

Ngày đơn hàng mới nhất chưa đối soát

Số lượng đối soát đã tạo

Tổng tiền đã đối soát

Có tài khoản ngân hàng mặc định không

Thông tin tài khoản ngân hàng mặc định

Có thể tạo đối soát không

Có quyền duyệt đối soát không (Reconciliation.Confirm hoặc Founder)

Có quyền cập nhật chuyển tiền đối soát không (Reconciliation.Transfer hoặc Founder)

Mức độ ưu tiên (dựa trên số tiền và thời gian)

Mức độ ưu tiên dạng string

Màu sắc hiển thị theo mức độ ưu tiên

Mức độ ưu tiên đối soát

Item cho danh sách phiếu chuyển tiền (Search result)

Chi tiết phiếu chuyển tiền

Danh sách đơn hàng trong phiếu

Đơn hàng trong phiếu chuyển tiền

Tóm tắt phiếu đang chờ duyệt (embed trong DriverFinModel cho mobile)

Kết quả tạo/duyệt/từ chối phiếu

ID của chi phí

Trạng thái trước khi thay đổi (null nếu là tạo mới)

Tên trạng thái cũ (hiển thị)

Trạng thái sau khi thay đổi

Tên trạng thái mới (hiển thị)

Tên người thực hiện hành động

Lý do từ chối (nếu có)

Ghi chú

Mô tả chi phí

Ghi chú cho chi phí

Số tiền chi phí

Danh mục chi phí

Trạng thái chi phí

Phương thức thanh toán

UserId của người duyệt

Tên người duyệt

Lý do từ chối (nếu có)

Có được phép duyệt chi phí này không

Có được phép từ chối chi phí này không

Có được phép đánh dấu đã thanh toán không

ID tài khoản ngân hàng nhận tiền (chỉ để reference)

Thông tin tài khoản ngân hàng nhận tiền (formatted)

Số tài khoản ngân hàng

Tên chủ tài khoản

Mã ngân hàng

Tên ngân hàng

Tên chi nhánh ngân hàng

Danh sách lịch sử thay đổi trạng thái

DTO hiển thị kỳ sao kê thẻ xăng

DTO hiển thị hợp đồng vay xe

Mô tả tóm tắt giai đoạn lãi suất, VD: "8.5% (T1-12), 12.5% (T13-15)"

Có tất toán hay không

Trạng thái tất toán (0=Processing, 1=Completed, 2=Cancelled)

Tổng tiền tất toán

Tổng tiền đã thanh toán (Expense status = Paid)

Tổng tiền chờ duyệt/chờ thanh toán

Số phí đã duyệt / tổng phí

DTO hiển thị lịch trả nợ kỳ

DTO hiển thị thông tin tất toán khoản vay

DTO hiển thị khoản phí tất toán

Trạng thái Expense liên kết (0=Pending, 1=Approved, 2=Rejected, 3=Paid)

MA TRẬN giá theo loại hàng để hiển thị: tuyến (hàng) × lựa chọn thuộc tính trục (cột).

Vì sao trả lưới đầy đủ chứ không chỉ các dòng giá đang có. Người quản trị cần thấy ô nào CHƯA khai giá thì mới biết phải khai — trả về danh sách dòng Price thô thì ô trống đơn giản là không xuất hiện, và một tuyến bị bỏ quên trông y hệt một tuyến không tồn tại. Ô trống chính là thứ phải nhìn thấy: đơn đi tuyến đó với option đó sẽ báo "chưa có giá". và là HAI thứ khác nhau, đừng gộp. Engine chọn trục bằng DỮ LIỆU (EXISTS(Price WHERE GoodsCategoryId = C AND IsDeleted = 0)), không bằng mode. Danh mục khai mode RoutePriceList mà chưa có ô giá nào vẫn tính theo trọng lượng. Trả cả hai để UI nói được đúng sự thật đó thay vì tin vào mode.

Danh mục hàng hóa của bảng giá này.

Tên danh mục — để dựng tiêu đề và câu cảnh báo.

Cách áp giá đang khai trong cấu hình danh mục.

⚠️ triệt tiêu cước tuyến; chỉ đổi cách tra, cước tuyến VẪN thu. Đây là hai công tắc riêng, UI không được gộp làm một.

Danh mục có thật sự đang đi theo nhánh bảng giá riêng hay không — trả lời theo DỮ LIỆU.

false trong khi là RoutePriceList nghĩa là mode đã khai nhưng chưa có ô giá nào ⇒ đơn vẫn tính theo trọng lượng. UI phải nói rõ điều này.

Thuộc tính trục giá (IsPriceAxis = 1) của danh mục. null = chưa khai trục.

Chưa khai trục thì không dựng được cột nào — ma trận trả về rỗng kèm giải thích, chứ không trả lưới trống không lý do.

Tên thuộc tính trục — nhãn của trục cột trên lưới.

Loại giá của các ô đang có. Ô ma trận bình thường là .

Số ô đã khai giá — dùng cảnh báo trước khi xoá ô cuối cùng.

Cột của ma trận: các lựa chọn của thuộc tính trục.

Hàng của ma trận: các tuyến.

Lời giải thích khi ma trận rỗng (chưa khai trục, trục không có lựa chọn nào...). Chuỗi rỗng khi bình thường.

Một CỘT của ma trận — một lựa chọn của thuộc tính trục.

GoodsAttributeOption.Id.

Nhãn hiển thị của lựa chọn.

Một HÀNG của ma trận — một tuyến kèm đủ ô theo mọi cột.

Khoảng cách của tuyến, hiển thị dạng "0 - 30 km".

⚠️ DB lưu khoảng cách bằng MÉT, chuỗi này đã quy sang km. Đừng đọc số trong chuỗi rồi tính tiếp.

Ô giá theo đúng thứ tự cột của . Luôn đủ số ô — ô chưa khai giá vẫn có mặt với = false.

Một Ô của ma trận.

Ba trạng thái, đừng gộp còn hai. = false là chưa có dòng giá ⇒ đơn đi ô này sẽ báo "chưa có giá cho tuyến". = true với = 0 là đã khởi tạo, khai giá 0 ⇒ đơn ra cước 0 đồng, hoàn toàn khác. Nhìn mỗi Value thì hai trạng thái này trông giống hệt nhau, và đó chính là chỗ người quản trị tưởng đã khai xong.

Id dòng Price. 0 = ô trống, chưa có dòng nào trong DB.

Giá của ô. Chỉ có nghĩa khi = true.

Ô đã có dòng giá trong DB hay chưa.

Một danh mục hàng hóa ĐÃ có bảng giá riêng — để trang danh sách đánh dấu.

Số ô giá đang có (đã lọc IsDeleted). Luôn > 0 vì danh mục 0 ô không nằm trong danh sách này.

Số tuyến đã có ít nhất một ô giá — để thấy bảng còn thiếu tuyến nào.

Cách áp giá đang khai trong cấu hình. Lệch với thực tế (có ô giá) là chuyện đáng hiện lên UI.

ID của doanh thu

Trạng thái doanh thu

Lý do từ chối (nếu có)

Ghi chú

Tên người thực hiện hành động

Mô tả doanh thu

Ghi chú cho doanh thu

Số tiền doanh thu

Danh mục doanh thu

Trạng thái doanh thu

UserId của người duyệt

Tên người duyệt

Lý do từ chối (nếu có)

Có được phép duyệt doanh thu này không

Có được phép từ chối doanh thu này không

Có được phép đánh dấu đã nhận tiền không

Một PHẠM VI bảng giá của khách hàng — bộ ba (CustomerId, GoodsCategoryId, PriceType).

Đây là đơn vị định danh bảng giá của v2. GoodsCategoryId = null là bảng giá CHUNG theo khoảng trọng lượng; có giá trị là bảng giá riêng của một loại hàng. Cờ là thứ đáng đọc nhất ở đây. Nó nói phạm vi này khách chưa khai dòng nào và đang ăn theo bảng giá mặc định (QĐ-2). Danh sách cố tình liệt kê cả phạm vi đi mượn chứ không chỉ phạm vi khách sở hữu: người quản trị cần thấy "khách này đang tính tiền bằng bảng của ai" ngay trên màn hình, thay vì phải suy ra bằng cách không thấy dòng nào. ⚠️ của phạm vi đi mượn là số dòng của bảng mặc định, không phải của khách. Hiện nó như số dòng của khách sẽ khiến người dùng tưởng mình đã khai giá riêng rồi.

Khách sở hữu phạm vi đang xét — luôn là khách được hỏi, kể cả khi đi mượn.

Loại hàng của bảng giá. null = bảng giá chung theo khoảng trọng lượng.

Tên loại hàng để hiện lên UI. Rỗng khi là bảng giá chung.

Loại giá của bảng.

Số dòng giá đang có trong phạm vi. Xem cảnh báo ở phần chú thích của lớp.

true = khách trống hẳn phạm vi này và đang dùng bảng giá mặc định.

Đơn hàng có thể đối soát

Mã đơn hàng

Mã đối tác

ID khách hàng

Tên khách hàng

Tiền COD

Phí dịch vụ (có thể trừ vào COD)

Tiền đối soát dựa trên PayFeeType

Tiền thực tế = ReconciliationAmount (đã tính theo logic PayFeeType)

Trạng thái COD

Trạng thái COD dạng string

Trạng thái đơn hàng

Trạng thái đơn hàng dạng string

Ngày giao hàng thành công

Ngày thu COD

Trọng lượng tính cước

Cước vận chuyển

Địa chỉ giao hàng

Tên người nhận

Số điện thoại người nhận

Ghi chú đơn hàng

Có được chọn để đối soát không

Có thể đối soát không (CodStage = Head)

Item hiển thị trong danh sách đối soát

Mã đối soát

ID khách hàng

Tên khách hàng

Số điện thoại khách hàng

Từ ngày

Đến ngày

Ngày chuyển tiền

Tổng tiền COD

Tổng phí trừ

Số tiền thực chuyển

Số lượng đơn hàng

Trạng thái

Trạng thái dạng string

Loại phiếu đối soát

Loại phiếu đối soát dạng string

ID thông tin xuất hóa đơn VAT

Tên công ty xuất hóa đơn VAT

Người tạo

Người phê duyệt

Người chuyển tiền

Ghi chú

Có thể chỉnh sửa không

Có thể xác nhận không (chỉ check status)

Có thể chuyển tiền không (chỉ check status)

Có thể hủy không

User có quyền duyệt đối soát không (Reconciliation.Confirm hoặc Founder)

User có quyền cập nhật chuyển tiền đối soát không (Reconciliation.Transfer hoặc Founder)

Có thể xác nhận không (kết hợp cả status và quyền)

Có thể chuyển tiền không (kết hợp cả status và quyền)

Item đơn hàng trong đối soát

ID đối soát

ID đơn hàng

Mã đơn hàng

Mã đối tác

Tiền COD

Phí trừ

Tiền thực tế

Ngày giao hàng

Ngày thu COD

Trọng lượng tính cước

Cước vận chuyển

Địa chỉ giao hàng

Tên người nhận

Số điện thoại người nhận

Ghi chú

Đối tượng đại diện cho tuyến đường.

Tên tuyến.

Mô tả tuyến.

Khoảng cách tối thiểu.

Khoảng cách tối đa.

Thứ tự hiển thị.

ID giao dịch

Mô tả giao dịch

Ghi chú cho giao dịch

Số tiền giao dịch

Số tiền mặt

Số tiền chuyển khoản

Loại giao dịch

Tên loại giao dịch

Hướng giao dịch

Tên hướng giao dịch

Ngày giao dịch

ID ví nguồn

Tên chủ ví nguồn

ID ví đích (nullable)

Tên chủ ví đích

Số lượng đơn hàng liên kết

Danh sách mã đơn hàng (để hiển thị preview)

Tổng tiền COD từ các đơn hàng

Tổng cước nguồn từ các đơn hàng

Tổng cước đích từ các đơn hàng

Trạng thái giao dịch

Tên trạng thái giao dịch

Số tiền hiển thị với dấu (+/-) để phân biệt thu/chi

Số tiền hiển thị với định dạng tiền tệ

Màu sắc để hiển thị (xanh cho thu, đỏ cho chi)

Icon để hiển thị loại giao dịch

Tên người gửi/nhận tiền

Số điện thoại người gửi/nhận tiền

Tên đầy đủ người gửi/nhận tiền

Số dư ví sau giao dịch

Số dư ví hiển thị với định dạng tiền tệ

Có phải giao dịch thu tiền không

Có phải giao dịch chi tiền không

Mô tả ngắn gọn cho giao dịch

ID giao dịch

ID đơn hàng

Mã đơn hàng

Mã đối tác

Ghi chú đơn hàng

Số tiền COD trong giao dịch này

Cước nguồn trong giao dịch này

Cước đích trong giao dịch này

Tổng tiền từ đơn hàng này trong giao dịch

ID khách hàng

Tên khách hàng

Tên người gửi

Địa chỉ người gửi

Số điện thoại người gửi

Tên người nhận

Địa chỉ người nhận

Số điện thoại người nhận

Trọng lượng tính cước

Tổng tiền COD của đơn hàng

Cước chính của đơn hàng

Tổng cước của đơn hàng

Loại thanh toán cước

Tên loại thanh toán cước

Trạng thái đơn hàng

Tên trạng thái đơn hàng

Ngày tạo đơn hàng

Ngày cập nhật đơn hàng

Số dư hiện tại

Item cho hiển thị danh sách ngân hàng

Tên đầy đủ ngân hàng

Tên thương hiệu

Mã ngân hàng

Thứ tự hiển thị

Người tạo

Người cập nhật

Thời gian tạo

Thời gian cập nhật

Model cho option select ngân hàng

ID ngân hàng

Tên thương hiệu ngân hàng

Tên đầy đủ ngân hàng

DTO hiển thị danh sách phiếu đối soát khách hàng

Mã phiếu

ID khách hàng

Tên khách hàng

Số điện thoại khách hàng

Loại phiếu

Tên loại phiếu

Trạng thái

Tên trạng thái

Tổng tiền thu hộ COD

Tổng phí vận chuyển

Số tiền cuối cùng

Tổng nợ cước đơn hoàn đã cấn vào phiếu (Ví v2 E13 — V-37).

Số lượng đơn hàng

Người tạo

Thời gian tạo

Người duyệt

Thời gian duyệt

Người hoàn thành

Thời gian hoàn thành

Ghi chú nội bộ

Phương thức thanh toán

Mã giao dịch

Link ảnh chứng từ

ID tài khoản ngân hàng khách hàng

Số tài khoản ngân hàng

Tên chủ tài khoản

Mã ngân hàng (VCB, TCB, VTB, etc.)

Tên ngân hàng

Tên chi nhánh ngân hàng

Địa chỉ chi nhánh ngân hàng

Thông tin hiển thị đầy đủ của tài khoản nhận tiền

Phiếu có hóa đơn hay không

Trạng thái hóa đơn (nếu có)

Tên trạng thái hóa đơn

DTO chi tiết đơn hàng trong phiếu

Nợ cước đơn hoàn cấn vào đơn này (Ví v2 E13 — V-37); 0 = không cấn.

Danh sách đơn có thể đối soát (V-35): đơn do bưu cục nhượng quyền bán mà không phải COD giao thành công — cước khách trả thẳng bưu cục, không đối soát với LADA; lập phiếu sẽ bị từ chối nên màn không cho chọn.

DTO lịch sử thao tác

DTO item cho tổng hợp khách hàng cần tạo hóa đơn thanh toán chuyển khoản

ID khách hàng

Tên khách hàng

Số điện thoại khách hàng

Mã khách hàng

Email khách hàng

Địa chỉ khách hàng

Số đơn hàng chưa thanh toán

Số đơn COD chưa đối soát

Số đơn chuyển khoản chưa thanh toán

Tổng tiền COD chưa đối soát (VNĐ)

Tổng cước của các đơn COD (VNĐ)

Tổng tiền chuyển khoản chưa thanh toán (VNĐ)

Số tiền ước tính cần trả khách = TotalCodAmount - TotalCodFee - TotalTransferFee (VNĐ)

Số tiền ước tính đã format (VD: "25,500,000 ₫")

Ngày đơn hàng cũ nhất chưa thanh toán

Ngày đơn hàng mới nhất chưa thanh toán

Số ngày từ đơn hàng cũ nhất

Mức độ ưu tiên dựa trên số ngày

ID người quản lý khách hàng

Tên người quản lý khách hàng

Thông tin ngân hàng khách hàng

Tên chủ tài khoản

Tên ngân hàng

Có thể tạo hóa đơn không (dựa trên quyền và số đơn hàng)

Item hiển thị thông tin danh mục chi phí

Tên danh mục chi phí

Mã danh mục chi phí chuẩn hóa theo TT133

Mô tả danh mục chi phí

Thứ tự hiển thị

ID của danh mục cha (null nếu là danh mục gốc)

Tên danh mục cha

ID người duyệt

Tên người duyệt

Mã tài khoản

Danh sách danh mục con

Cấp độ trong cây phân cấp (0 = gốc, 1 = con, 2 = cháu, ...)

Trạng thái xóa

Item hiển thị thông tin danh mục doanh thu

Tên danh mục doanh thu

Mô tả danh mục doanh thu

Thứ tự hiển thị

ID của danh mục cha (null nếu là danh mục gốc)

Tên danh mục cha

ID người duyệt

Tên người duyệt

Danh sách danh mục con

Cấp độ trong cây phân cấp (0 = gốc, 1 = con, 2 = cháu, ...)

Trạng thái xóa

Item hóa đơn thuế

ID phiếu đối soát

Mã phiếu đối soát

ID thông tin VAT

Mã số thuế

Tên công ty

Địa chỉ

Email nhận hóa đơn

Số hóa đơn

Ngày xuất hóa đơn

Trạng thái

Tên trạng thái

Tổng tiền trước thuế

Tiền thuế VAT

Tổng tiền sau thuế

Thuế suất (%)

URL file PDF hóa đơn

Ghi chú

User có quyền cập nhật trạng thái không (Founder hoặc TaxInvoice.Update)

Có thể xóa không (chỉ khi NotIssued hoặc Draft)

DTO item cho việc xuất Excel thông tin đơn hàng

ID đơn hàng

Mã đơn hàng

Mã đối tác

Ghi chú đơn hàng

ID khách hàng

Tên khách hàng

ID Sale

Tên Sale

Tên người gửi

Địa chỉ người gửi

Số điện thoại người gửi

Tên người nhận

Địa chỉ người nhận

Số điện thoại người nhận

Trạng thái đơn hàng

Trạng thái vật lý đơn hàng

Khối lượng tính cước (gram)

Khối lượng tính cước (kg) - hiển thị

Cước phí vận chuyển

Cước phí vận chuyển (formatted)

Phí COD

Phí COD (formatted)

Phí lấy hàng

Phí lấy hàng (formatted)

Phí giao hàng

Phí giao hàng (formatted)

Giảm giá

Giảm giá (formatted)

Tổng cước phí

Tổng cước phí (formatted)

Loại thanh toán cước phí

Số tiền thu hộ

Số tiền thu hộ (formatted)

COD có bao gồm cước phí không

Trạng thái thu COD

Số tiền TransferFee

Số tiền TransferFee (formatted)

Trạng thái TransferFee

Cước phí nguồn

Cước phí nguồn (formatted)

Trạng thái cước phí nguồn

Cước phí đích

Cước phí đích (formatted)

Trạng thái cước phí đích

Số tiền đối soát

Số tiền đối soát (formatted)

Thời gian tạo đơn hàng

Thời gian tạo đơn hàng (formatted)

Thời gian lấy hàng thành công

Thời gian lấy hàng thành công (formatted)

Thời gian giao hàng thành công

Thời gian giao hàng thành công (formatted)

Tổng số kiện

Tổng khối lượng (gram)

Tổng khối lượng (kg) - hiển thị

Nội dung hàng hóa

DTO item cho hiển thị danh sách hóa đơn thanh toán chuyển khoản

Mã hóa đơn

ID khách hàng

Tên khách hàng

Số điện thoại khách hàng

Từ ngày

Đến ngày

Tổng tiền TransferFee

Tổng tiền TransferFee (formatted)

Số đơn hàng

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

Tên trạng thái hóa đơn

Mức độ ưu tiên

Tên mức độ ưu tiên

Người tạo

Thời gian tạo

ID người duyệt

Người duyệt

Ngày duyệt

Ghi chú

Thông tin chuyển khoản

Số tài khoản ngân hàng công ty/đại lý

Tên chủ tài khoản công ty/đại lý

Tên ngân hàng công ty/đại lý

Có thể chỉnh sửa không (chỉ người tạo và trạng thái Draft)

Có thể hủy không (chỉ người tạo và trạng thái Draft)

Có thể duyệt không (role Accountant và trạng thái Draft)

DTO item cho đơn hàng trong hóa đơn thanh toán chuyển khoản

ID hóa đơn thanh toán

ID đơn hàng

Mã đơn hàng

Số tiền TransferFee của đơn hàng này

Số tiền TransferFee (formatted)

Ghi chú riêng cho đơn hàng này

Tên người gửi

Địa chỉ người gửi

Số điện thoại người gửi

Tên người nhận

Địa chỉ người nhận

Số điện thoại người nhận

Ngày tạo đơn hàng

Trạng thái đơn hàng

Trạng thái vật lý đơn hàng

Trạng thái đơn hàng

Trạng thái vật lý đơn hàng

Thông tin sản phẩm (gộp các package thành chuỗi)

Item cho tài khoản ngân hàng người dùng

ID người dùng

Tên người dùng

Số tài khoản

Tên chủ tài khoản

ID ngân hàng

Mã ngân hàng (VCB, TCB, VTB, etc.)

Tên ngân hàng

Có phải tài khoản mặc định không

Ghi chú

Số lượng chi phí sử dụng tài khoản này

Item hiển thị thông tin hóa đơn VAT trong danh sách

Ký hiệu mẫu số (khmshdon)

Ký hiệu hóa đơn (khhdon)

Số hóa đơn (shdon)

Ngày lập (tdlap)

MST người bán (nmmst)

Tên người bán (nmten)

MST người mua (nbmst)

Tên người mua (nbten)

Tổng tiền hàng (tgtcthue)

Tổng tiền thuế (tgtthue)

Tổng thanh toán (tgtttbso)

Đơn vị tiền (dvtte)

Tình trạng (tthai)

Ghi chú (gchu)

Thời gian đồng bộ

Chiều hóa đơn: 1 = Bán ra, 2 = Mua vào

Tên chiều hóa đơn

Kết quả kiểm tra hóa đơn (ttxly)

Tên kết quả kiểm tra (ttxly)

Tên trạng thái hóa đơn (tthai)

DTO trả về thông tin thẻ xăng dầu cho Driver App

ID của bản ghi bàn giao hiện tại

Trạng thái bàn giao (PendingAccept / Received / Returned)

Giao dịch đã được đổ dầu hay chưa (có FuelRefillId)

Đơn giá khoán đã được clamp trong khoảng [MinQuotaUnitPrice, MaxQuotaUnitPrice]

Thu nhập dầu = DifferenceLiters × ClampedQuotaUnitPrice

Chi tiết công từng ngày của nhân viên

ID nhân viên

Tên đăng nhập

Họ và tên

Ngày làm việc

Thời gian check-in (sớm nhất trong ngày)

Thời gian check-out (muộn nhất trong ngày)

Số giờ làm việc trong ngày (có 1 số sau dấu phẩy)

Số công trong ngày

Số kíp trong ngày — tổng kíp của TỪNG CA tính trên giờ thô, cùng công thức với bảng lương (AttendanceFormulas.CalculateOvertimeKips). Không suy được từ vì cột đó đã gộp theo ngày và làm tròn 0,1h.

Số ODO đầu ngày

Số ODO cuối ngày

Tổng ODO chạy trong ngày

Tháng

Năm

Số ODO khi check-in

Số ODO khi check-out

Danh sách ảnh check-in

Danh sách ảnh check-out

Đối tượng đại diện cho media của attendance

Tổng hợp số công của nhân viên theo tháng

ID nhân viên

Tên đăng nhập

Họ và tên

Tổng số ngày đi làm

Tổng số giờ làm việc (có 1 số sau dấu phẩy)

Tổng số công

Tháng

Năm

Họ và tên

Số điện thoại

Địa chỉ hiện tại

Giới thiệu về bản thân

Trạng thái hồ sơ

Nội dung đánh dấu trạng thái

Thời gian hẹn phỏng vấn

Thời gian tạo

ID người phụ trách tuyển hồ sơ này (trống nếu chưa ai nhận)

Tên người phụ trách tuyển — service tra theo cho từng trang kết quả

Thời điểm hồ sơ chuyển sang nhận việc

Tên file CV

URL để truy cập CV

Kích thước file CV (bytes)

Loại file CV

Thời gian upload CV

Có CV hay không

Item hiển thị dòng theo dõi cọc trách nhiệm của 1 lái xe

ID lái xe

Tên đăng nhập

Họ và tên

Số điện thoại

ID chi nhánh quản lý

Tên chi nhánh quản lý

Hạn mức cọc yêu cầu

Cọc đã đóng lũy kế (đã được kế toán xác nhận nhận tiền)

Mức trừ cọc qua lương mỗi tháng

Cọc đang chờ xác nhận (Income Pending, chưa cộng vào Đã đóng)

Số tiền còn thiếu = max(0, Hạn mức - Đã đóng)

Trạng thái: "Đủ" | "Thiếu" | "Chưa nộp"

Thời điểm nộp gần nhất

Item hiển thị Bảng đánh giá lái xe

Item chi tiết điểm đánh giá

Item hiển thị Bảng tra mức lương

Item hiển thị Phiếu lương (Snapshot)

Mức khai đóng BHXH bắt buộc (snapshot)

Khấu trừ thực tế = InsuranceBase × 10.5%

Tiền tạm ứng lương cấn trừ trong kỳ (snapshot)

Tiền cọc trách nhiệm cấn trừ trong kỳ (snapshot)

Expense liên kết đã thanh toán (Paid) → không cho sửa phiếu lương

Item hiển thị Cấu hình lương nhân viên

Item hiển thị Nhóm tiêu chí đánh giá

Item hiển thị Tiêu chí đánh giá

Tiêu đề bài viết

Thời gian tạo

Thời gian cập nhật

Mô tả công việc

Yêu cầu kinh nghiệm (ví dụ: 2 năm c++)

Địa chỉ làm việc

Loại hình công việc

Ngày bắt đầu

Ngày kết thúc

Email tiếp nhận CV

Phòng ban

Phòng ban

Vị trí ứng tuyển

Mức lương tối thiểu

Mức lương tối đa

Trạng thái tin tuyển dụng: mở / đóng

Trạng thái tin tuyển dụng: mở / đóng

Item hiển thị phiếu nghỉ phép

Item hiển thị quỹ phép nhân viên

Item hiển thị loại nghỉ phép

Item hiển thị ngày lễ

Trạng thái phiếu lương gần nhất của người đang đăng nhập — cho thẻ "Phiếu lương tháng M" trên đầu Bảng tin (docs/plan-bang-tin-noi-bo.md §3.8). CỐ Ý không có số tiền: thẻ nằm trên trang tin, chỉ cần kỳ + trạng thái.

Có ít nhất một phiếu đã gửi cho người này (khác Bản nháp). false → các trường còn lại trống, thẻ ẩn.

Trạng thái hiệu lực: "NLĐ đã xác nhận" mà phiếu chi đã chi thì là "Đã thanh toán" — như trang phiếu lương.

Item hiển thị Thưởng/Phạt

0 = Fixed, 1 = Percentage

Số tiền hoặc % nhập vào

Số tiền đã tính (snapshot)

Chi tiết doanh số từng thành viên trong team (dùng cho TeamLeader/BranchManager)

Lớp đại diện cho thông tin nhân viên.

ID của nhân viên.

Tên đăng nhập của nhân viên.

Họ và tên của nhân viên.

Số điện thoại của nhân viên.

ID của đại lý mà nhân viên thuộc về.

Trạng thái khóa của nhân viên.

Loại người dùng

Ngày tạo

Ngày cập nhật

Mã chấm công (khớp với mã máy chấm công vân tay khi import)

ID người quản lý trực tiếp

Tên người quản lý trực tiếp

Số tiền tạm ứng lương hiện tại trong tháng

Tổng hạn mức cọc trách nhiệm yêu cầu của lái xe

Số tiền cọc trách nhiệm đã đóng lũy kế

Số tiền cọc trách nhiệm cấn trừ hàng tháng qua lương

DTO trả về lịch sử thao tác người dùng

Kết quả thao tác bảng tin. → HTTP 404 (cả khi bài có thật nhưng người gọi không được xem/sửa — không lộ tồn tại), → HTTP 403 (vượt phạm vi đăng).

Dấu bản đang sửa sau thao tác (lưu khối) — gửi lại khi bấm Đăng.

Bản đang sửa đã khác bản người đăng xem lúc mở màn.

Số người được gửi chuông lúc đăng (0 khi không gửi).

Cờ cho giao diện (rule quyen-hien-thi) — GET api/InternalNews/nav, không đòi role.

Đơn vị người chỉ có quyền mức đơn vị được chọn làm đối tượng (gồm con cháu).

Tên đích để hiển thị (tên nhóm / đơn vị / người); trống khi Tất cả.

Đích chỉ có ở phía nhượng quyền (bưu cục NQ, người của bưu cục NQ, "Mọi bưu cục nhượng quyền") — giao diện gỡ dòng này khi người soạn chuyển sang "Chỉ nhân viên LADA" (plan §6.6).

Tài liệu / video của bài — KHÔNG có đường dẫn trên đĩa.

URL tuyệt đối trên Media.Domain.

Một dòng của màn quản trị bảng tin.

Chỉ nhân viên LADA / Gồm cả bưu cục nhượng quyền (plan §6.6).

Số người đã mở bài.

Lịch đăng bị job huỷ tự động — bài tới giờ mà không đăng được nên về nháp (plan bảng tin §3.13 mục 4, nợ BT-9). Tắt khi có người lưu bài lại.

Chi tiết bài cho người soạn: thông tin + đối tượng + bản đang sửa + tệp.

Dấu bản đang sửa — gửi lại ở ExpectedDraftVersion khi bấm Đăng.

Bài đang đăng và bản đang sửa khác ảnh chụp người đọc đang thấy (cần "Đăng lại").

Một khối để hiển thị (ảnh chụp đã đăng, hoặc bản xem trước đã lọc).

Một bài trên bảng tin của người đọc.

Đang ghim (đã tính PinnedUntil).

Chi tiết bài cho người đọc: thông tin + ảnh chụp khối + tệp mà khối tham chiếu.

Được tick "gồm đơn vị con" cho đơn vị này (mức đơn vị: chỉ cây mình đứng tên quản lý).

Bưu cục nhượng quyền — ẩn khi bài đang để "Chỉ nhân viên LADA" (plan §6.6).

Một loại đơn vị chọn được ("Mọi bưu cục nhượng quyền", "Mọi chi nhánh của LADA"…) — Id = giá trị AgencyType.

Chỉ gồm người phía nhượng quyền — ẩn khi bài đang để "Chỉ nhân viên LADA".

Người của bưu cục nhượng quyền (theo đơn vị hoặc tài khoản NQ) — ẩn khi "Chỉ nhân viên LADA".

Dữ liệu cho ô chọn đối tượng — ĐÃ lọc theo phạm vi người đăng, để màn soạn không phải mượn API tra cứu của miền khác (Permission.Search, Agency.GetTree — trưởng bưu cục không có các role đó, plan §7).

Được chọn "Tất cả", nhóm quyền, loại đơn vị (mức công ty).

Thấy lựa chọn phạm vi Chỉ nhân viên LADA / Gồm cả bưu cục nhượng quyền (plan §6.6, §5 câu 12c): mức công ty, và mức đơn vị có cả đơn vị LADA lẫn bưu cục NQ trong phạm vi.

Phạm vi máy chủ tự đặt cho mọi bài của người này; null khi .

Nhóm quyền đang hoạt động — rỗng với người chỉ có mức đơn vị.

Đơn vị chọn được: mọi đơn vị (mức công ty) hoặc cây đơn vị mình quản lý (mức đơn vị).

Loại đơn vị chọn được (mức công ty) — Id = giá trị AgencyType.

Ước tính người nhận chuông cho đối tượng đang chọn — đúng tập ResolveRecipientsAsync sẽ gửi.

Thống kê đọc của một bài (plan §3.17, GĐ D). "Người nhắm" = đúng tập ResolveRecipientsAsync trả cho đối tượng HIỆN TẠI của bài (bỏ tài khoản xoá / đang khoá); đã đọc / đã xác nhận chỉ đếm trong tập đó.

Người đã đọc nhưng KHÔNG thuộc tập người nhắm hiện tại (đổi đối tượng, khoá / xoá tài khoản) — không vào tử số.

Theo đơn vị làm việc còn sống; nhiều người chưa đọc lên trước, "Không thuộc đơn vị" cuối.

null = không đơn vị / đơn vị đã xoá (dòng "Không thuộc đơn vị").

Một người nhắm trong danh sách thống kê.

Một dòng tổng hợp quý/năm của một chỉ số (§7.1).

Mục tiêu kỳ tổng hợp trên đúng tập tháng ĐÃ CHỐT (§7.13): Σ mục tiêu với chỉ số cộng dồn; mục tiêu tháng cuối đã chốt với chỉ số ảnh chụp; bình quân gia quyền theo mẫu số với chỉ số tỷ lệ

Giá trị thực của kỳ, cộng từ snapshot KpiResult các tháng đã chốt — KHÔNG chạy lại provider (§7.13). Null khi chưa tính được: chưa tháng nào chốt, thiếu tử/mẫu, hoặc chỉ số nhập tay thiếu số.

Σ tử số các tháng đã chốt — chỉ có với chỉ số dạng tỷ lệ

Σ mẫu số các tháng đã chốt — chỉ có với chỉ số dạng tỷ lệ

Chỉ số dạng tỷ lệ/bình quân — giá trị kỳ = Σtử ÷ Σmẫu, không phải Σ%

Số tháng có giao chỉ số này ĐÃ CHỐT — chỉ những tháng này góp vào con số

Số tháng có giao chỉ số này CHƯA CHỐT — không góp số, chỉ ghi nhãn

Trọng số bình quân các tháng ĐÃ CHỐT có giao chỉ số này

Số tháng trong khoảng có giao chỉ số này — khác số tháng của kỳ là bộ chỉ tiêu không đều

Chỉ số này là ảnh chụp tại một thời điểm (chỉ tiêu không cộng dồn) hay số cộng dồn cả kỳ

Đầu khoảng các tháng ĐÃ CHỐT thật sự góp vào con số của riêng chỉ số này (tháng đầu đã chốt; với ảnh chụp là tháng cuối đã chốt)

Cuối khoảng các tháng đã chốt thật sự góp vào con số (tháng cuối đã chốt)

Lý do dòng chưa có số, hoặc ghi chú về cách con số được tạo ra; null nghĩa là tính thẳng

Bảng tổng hợp KPI quý/năm của một chủ thể — cộng từ snapshot KpiResult các tháng ĐÃ CHỐT (§7.13), nên bất biến khi dữ liệu gốc đổi sau khi tháng đã chốt.

Snapshot điểm kỳ chỉ xảy ra một lần duy nhất: lúc bản đánh giá KpiPeriodicReview chuyển Final thì TotalScore được ghi vào AggregatedScore (§7.1) — và chỉ khi = 0 và kỳ đã kết thúc.

Quý 1-4; bằng 0 khi kỳ năm

Đầu kỳ tổng hợp (giờ Việt Nam)

Cuối kỳ tổng hợp (giờ Việt Nam)

Số tháng trong kỳ có chỉ tiêu và ĐÃ CHỐT (đủ mọi chỉ tiêu của tháng)

Số tháng trong kỳ có chỉ tiêu nhưng CÒN dòng chưa chốt — khác 0 thì bảng này chưa trọn kỳ, và Finalize bị chặn (§7.13, đóng KPI-11)

Nhãn kiểu "còn N tháng chưa chốt: 08, 09" cho người đọc; null khi trọn kỳ

Tổng trọng số bình quân — khác 100% là bộ chỉ tiêu các tháng không đồng nhất

Điểm KPI tổng hợp của kỳ = Σ điểm trọng số các dòng

Số dòng chưa tính được số

Item hiển thị chỉ tiêu KPI trong danh sách. SubjectName / AssignedByName do service gán tay sau khi map (SubjectId đa hình, không có navigation).

Mẫu bậc thang thưởng KPI kèm các bậc

Một bậc: điểm trong [MinScore, MaxScore) ⇒ tiền

Dòng cấu hình thưởng của một nhân viên trong một tháng

Tên chủ thể nguồn điểm — chính nhân viên, hoặc tên bưu cục/khu vực

Một dòng của bảng tính thử thưởng KPI — hiện tiền sẽ sinh, hoặc lý do không sinh.

Σ điểm trọng số các chỉ tiêu đã chốt của chủ thể nguồn điểm trong tháng

Số chỉ tiêu đã chốt góp vào điểm

Bậc trúng: nhãn "[50 – 80)" để đối soát

Tiền sẽ sinh; 0 khi không đủ điều kiện

Có sinh PayrollAdjustment hay không

Lý do không sinh (kỳ thử nghiệm, công tắc tắt, mẫu tắt, chưa chốt kỳ, không trúng bậc…)

Kỳ thử nghiệm — không bao giờ sinh tiền kể cả khi công tắc bật (§7.9)

Bảng tính thử thưởng KPI của một kỳ tháng

Công tắc Kpi.EnableBonus đang bật hay tắt

Kỳ này là kỳ thử nghiệm (chốt trước Kpi.EffectiveFrom)

Số dòng cấu hình xét tới

Số dòng thực sự sẽ sinh tiền

Tổng tiền sẽ sinh

Kết quả một lần chạy sinh thưởng thật

Số adjustment tạo mới

Số adjustment cập nhật (chốt lại kỳ)

Số adjustment gỡ đi vì dòng cấu hình không còn đủ điều kiện sinh tiền

Số dòng cấu hình không sinh tiền

Lý do không sinh của từng dòng bị bỏ qua — để nghiệp vụ biết vì sao không có tiền

Item hiển thị chỉ số KPI trong danh sách

Một dòng danh sách đánh giá KPI định kỳ quý/năm.

Mô tả loại chủ thể để hiển thị thẳng

Tên nhân viên hoặc tên đơn vị được đánh giá

Quý 1-4; 0 khi kỳ năm

Nhãn kỳ để hiển thị: "Quý 3/2026" hoặc "Năm 2026"

Điểm snapshot lúc chuyển Final; null khi còn Draft (màn hình hiện số sống)

Một dòng theo dõi chỉ tiêu trong kỳ — giá trị thực tính tại thời điểm gọi, chưa chốt kỳ.

Id chỉ tiêu đang theo dõi

Mã chỉ số, vd "driver.delivery-count"

Đơn vị đo (đơn, đồng, %, KH, người...)

Chiều đánh giá — quyết định cách đọc % hoàn thành

Tên nhân viên hoặc tên đơn vị được giao chỉ tiêu

Giá trị thực tính tại thời điểm gọi; null khi chưa tính được (chỉ số nhập tay hoặc lỗi nguồn)

% hoàn thành thô, chưa áp trần

% hoàn thành sau khi áp trần — số dùng để tính điểm

Điểm đã nhân trọng số

Chỉ số lấy giá trị tự động hay nhập tay

Lý do dòng này chưa có số: nguồn dữ liệu lỗi, chỉ số nhập tay chưa nhập, chỉ tiêu không hợp lệ. Null nghĩa là dòng tính bình thường.

Không gộp lỗi thành giá trị 0: 0 đọc ra là "không đạt chỉ tiêu", còn lỗi nguồn là "chưa biết" — hai thứ khác nhau, và nhầm chúng ở GĐ E là mất tiền thưởng của người ta (§3.9d).

Kết quả màn theo dõi KPI trong kỳ, gộp theo từng chủ thể.

Tổng trọng số các chỉ tiêu của chủ thể trong kỳ — khác 100% là bộ chỉ tiêu chưa đủ

Tổng điểm KPI tạm tính của kỳ = Σ điểm trọng số các dòng

Số dòng chưa tính được số (lỗi nguồn hoặc chờ nhập tay)

Tình trạng cửa sổ chốt lại của một kỳ (plan §3.4) — thứ màn chốt kỳ cần để nói rõ với người dùng "còn mấy ngày" thay vì để họ bấm rồi mới biết đã hết hạn.

Số ngày nằm ở AppConfig: Kpi.RecloseWindowDays và trước GĐ F chỉ KpiPeriodCloseService đọc được. Phơi ra ở đây thay vì để FE gọi AppConfig/Search vì đọc thẳng AppConfig từ màn KPI là mượn role của miền khác — đúng bẫy §8 mà GĐ C đã cắn.

Thời điểm hết kỳ (theo mốc kỳ giờ Việt Nam của KpiPeriod)

Kỳ đã kết thúc chưa — chưa hết kỳ thì không chốt được, kể cả lần đầu

Số ngày cửa sổ chốt lại đang cấu hình

Hạn cuối còn chốt lại được = hết kỳ + số ngày cửa sổ

Cửa sổ chốt lại còn mở không

Số ngày còn lại của cửa sổ, làm tròn lên; 0 khi đã hết hạn hoặc kỳ chưa kết thúc.

Chủ thể đã có chỉ tiêu nào ở trạng thái đã chốt chưa — chỉ có giá trị khi lời gọi truyền chủ thể và chủ thể đó nằm trong phạm vi thao tác của người gọi; ngoài ra là null.

Câu giải thích tiếng Việt để hiển thị thẳng lên băng thông báo

Một dòng kết quả kỳ ĐÃ CHỐT — đọc thẳng từ KpiResult, không tính lại.

Kỳ đã chốt là snapshot bất biến (§3.4). Đây chính là thứ chặn phơi nhiễm của nợ KPI-8: nhân sự chuyển bưu cục sau khi chốt không làm số của kỳ cũ trôi, vì không ai chạy lại provider.

Mã chỉ số, vd "sales.revenue"

Đơn vị đo

Tên nhân viên hoặc tên đơn vị

Giá trị thực đã chốt

Giá trị nhập tay nếu dòng này do người nhập, null nếu engine tính

Lý do nhập tay

Kỳ thử nghiệm (§7.9) — xem và đối chiếu được, KHÔNG BAO GIỜ sinh thưởng

Tên người chốt; job tự động ghi tài khoản hệ thống

Breakdown đối soát, ghi nguyên văn từ provider lúc chốt

Kết quả một lần chạy chốt kỳ — số dòng chốt được, số dòng lỗi, lý do từng dòng lỗi.

Job ghi nguyên khối này vào log. Đọc kỹ : dòng lỗi là dòng chưa chốt, không phải dòng chốt với giá trị 0 (§3.9d).

Kỳ này là kỳ thử nghiệm hay chính thức (§7.9)

Số chỉ tiêu đã ghi được KpiResult và chuyển sang Đã chốt kỳ

Số chỉ tiêu cập nhật lại kết quả cũ (chốt lại) thay vì tạo mới

Số chỉ tiêu KHÔNG chốt được vì nguồn dữ liệu lỗi hoặc chỉ số nhập tay chưa có giá trị — những dòng này giữ nguyên trạng thái cũ, chờ sửa nguồn rồi chốt lại

Lý do từng dòng lỗi, dạng "chỉ tiêu #id (mã chỉ số): lý do"

Số khoản thưởng KPI sinh mới sau lần chốt này (GĐ E) — 0 khi chưa đủ 4 chốt chặn

Số khoản thưởng KPI được cập nhật (chốt lại kỳ)

Tổng tiền thưởng KPI của lần chạy này

Một lựa chọn cho ô chọn chủ thể của màn giao chỉ tiêu — chỉ định danh, không mang gì thêm.

Cố ý **chỉ có Id và tên**. Đây là đường đọc mới, và §8 của plan chốt rằng đường đọc mới không bao giờ được rộng hơn đường đọc sẵn có của chính miền dữ liệu đó: người có KpiAssignment.CreateOrUpdate không vì thế mà được đọc số điện thoại, email hay bưu cục của nhân sự — đó là dữ liệu miền HR, phải hỏi role của miền HR.

Id của nhân viên hoặc đơn vị

Tên hiển thị

Nhân viên hay đơn vị — để FE khỏi phải suy lại từ tham số đã gửi

Caption của media

Thứ tự hiển thị của media

Một dòng danh sách hồ sơ bưu cục.

Chi nhánh đã bị xoá mềm ở Quản lý chi nhánh — hồ sơ cần đóng/chuyển hướng.

Khu vực = node AgencyType.Region gần nhất phía trên chi nhánh trong cây ParentId (cột "khu vực" đặc tả §6.1); null khi chi nhánh không nằm dưới khu vực nào.

Người sửa hồ sơ lần cuối (cột "người cập nhật" đặc tả §6.1).

Mã điều kiện công bố cứng còn thiếu (chỉ điều kiện đã làm ở GĐ hiện tại).

Lượt bấm gọi 30 ngày gần nhất (tới hết hôm qua — nguồn AgencyWebEventDaily do job đêm gộp). 0 khi chưa có sự kiện nào.

Chi tiết hồ sơ bưu cục cho màn 7 tab.

Thông tin lõi của Agency — CHỈ ĐỌC, sửa ở Quản lý chi nhánh.

Rỗng tới GĐ A2.

Số xã bộ 2 cấp trong vùng phủ.

Đề xuất còn chờ duyệt của bưu cục (GĐ D) — chỉ trả cho người đọc được hàng đợi (người duyệt, Branch.Manager); người khác nhận mảng rỗng.

Giá trị cột thô — KHÔNG đáng tin (Việc 0 Đ2); dùng .

Địa chỉ thật sự ở bộ 2 cấp (tính từ Location).

Họ tên người quản lý chi nhánh (User.FullName) — null khi chưa gán.

false = chờ duyệt — portal vẫn thấy, trang công khai không lấy.

Người tải lên — màn duyệt ảnh cần biết ảnh của ai.

Một dòng lịch sử phiên bản — không kèm SnapshotJson (nặng); xem chi tiết qua Versions/{agencyId}/{versionNo}.

Phiên bản hồ sơ đang ở.

Trang lịch sử phiên bản, mới nhất trước.

Một phiên bản kèm ảnh chụp đã đọc (thuộc tính thiếu trong JSON cũ mang giá trị mặc định).

Danh mục chọn cho màn hồ sơ bưu cục.

Tỉnh bộ 2 cấp (Level 1, LevelType 2).

Trang tuyến dich-vu/….

Loại hàng (Category.ContentType = GoodsType).

Chi nhánh LadaBranch/Franchise chưa có hồ sơ — chỉ trả cho người được tạo hồ sơ.

Khu vực (Agency loại Region) cho bộ lọc "khu vực" của danh sách — rỗng thì portal ẩn bộ lọc đó.

Loại sở hữu một bưu cục có thể mang (Chi nhánh LADA / Nhượng quyền) — bộ lọc "loại" của danh sách.

Trang công khai /buu-cuc/<slug> đã bật chưa (AppConfig Network.BuuCucPublicEnabled). Tắt thì portal không hiện link "Xem trang công khai" — link đó là 404 tới khi marketing công bố đủ hồ sơ và bật cờ (plan §4.1).

Một đề xuất sửa hồ sơ (GĐ D) kèm bảng so sánh hiện tại ↔ đề xuất.

Một dòng tóm tắt: "Đổi toạ độ", "Thêm nhân sự Nguyễn Văn A"…

Người duyệt / từ chối (null khi còn chờ hoặc bị thay bằng đề xuất mới).

Phiên bản hồ sơ lúc gửi.

Phiên bản hồ sơ hiện tại — gửi lại làm ExpectedVersion khi duyệt.

Phiên bản sinh ra khi duyệt.

Bảng so sánh — "hiện tại" là giá trị ĐANG lưu lúc đọc (không phải lúc gửi), "đề xuất" là giá trị sẽ ghi. Chữ thuần (Intro đã bỏ thẻ) — FE hiện bằng nội suy văn bản, không bao giờ v-html.

Một dòng của bảng so sánh.

Hàng đợi đề xuất.

Số đề xuất còn chờ trong phạm vi người gọi (không theo bộ lọc trạng thái) — dải "N đề xuất chờ duyệt".

Đề xuất đang chờ của một bưu cục — hiện trên thẻ nhóm ở trang chi tiết.

Kết quả áp ngoại lệ giờ hàng loạt.

Các ngày áp dụng, yyyy-MM-dd.

Kết quả một bưu cục.

Phiên bản mới (khi có thay đổi) hoặc phiên bản hiện tại.

Bộ đếm một nhóm sự kiện: lượt (Count) và phiên (SessionHash distinct theo ngày) cho từng loại. Lượt bơm được trong trần 120/phút/IP — hiện cả phiên cạnh lượt.

Tổng lượt mọi loại.

Đặt (không cộng) số phiên của một loại — số phiên khác nhau trên cả phạm vi tính từ sự kiện thô.

Báo cáo bưu cục một tháng (GĐ D) — nguồn AgencyWebEventDaily; nguồn truy cập/trang từ sự kiện thô.

Tháng báo cáo yyyy-MM.

Ngày đầu tháng.

Ngày cuối tính số — cuối tháng, hoặc ngày gộp gần nhất nếu tháng đang chạy.

Ngày gần nhất job gộp đã chạy (toàn hệ thống); null = job chưa từng gộp.

Sự kiện thô của tháng còn (giữ 13 tháng) — false thì bảng nguồn/trang rỗng vì đã dọn.

Số phiên ở và là khách khác nhau trên CẢ phạm vi (tính từ sự kiện thô — một khách xem 2 bưu cục là 1 phiên). False (tháng đã quá 13 tháng, không còn sự kiện thô) thì hai chỗ đó là TỔNG số phiên từng bưu cục (một khách xem 2 bưu cục tính 2). Dòng từng bưu cục luôn là số phiên của riêng bưu cục.

Top nguồn truy cập (utm_source, hoặc host referrer, hoặc "(trực tiếp)") — chữ do trình duyệt khách gửi.

Top trang phát sinh sự kiện — chữ do trình duyệt khách gửi.

Bưu cục trong phạm vi người xem — nguồn ô lọc.

Khu vực (node Region) cho ô lọc — trả kèm báo cáo vì người chỉ có role Report không gọi được Lookups. Phạm vi Own (Branch.Manager) nhận mảng rỗng: một bưu cục thì không có gì để lọc.

Một bưu cục trong báo cáo.

Một ngày (cộng mọi bưu cục trong bộ lọc) — biểu đồ.

Một dòng nguồn / trang.

Cả bộ tham số mục "Kế hoạch kinh doanh" của cổng nhượng quyền (GET api/FranchiseBusinessPlan/get, plan cổng §3.13, §6.24): năm dòng sản lượng theo bậc phường + một dòng tham số + dấu phiên bản cho form sửa.

Dấu phiên bản của cả bộ — gửi lại khi lưu; khác dấu hiện tại = người khác vừa sửa.

Năm bậc phường 1–5 theo thứ tự bậc.

null = chưa chạy migration seed.

Số phường mỗi bậc tối đa ở ô xem thử (trần số phường một mã).

Lần lưu gần nhất của cả bộ (dòng nào mới nhất).

Một bậc phường — ba số là đơn MỖI PHƯỜNG MỖI NGÀY.

Tổng ba số — để đối chiếu với sản lượng nội bộ của bậc trong bảng giá.

Tham số chung. Tiền: đồng (đơn giá đ/đơn, chi phí đ/tháng).

Kết quả lưu. = MỌI lỗi kiểm dữ liệu trong một lần.

Kết quả tính thử (POST api/FranchiseBusinessPlan/preview) — không ghi gì, không chạm mã nào.

Kế hoạch tính thử — cùng luật với trang của khách. Tiền: đồng (đã làm tròn 10.000 đ).

Ready · NoWards · NoTieredWards · NotConfigured.

Gói vùng phủ theo số phường (POINT…); null = chưa đủ gói.

Số bưu cục nhân chi phí cố định.

Sản lượng vùng khi chạy đủ (trước tỷ lệ khởi động), đơn/ngày.

Tháng 1 / 3 / 6 / 12.

24 tháng.

Một dòng của danh sách "Đăng ký nhượng quyền".

Mã đăng ký người gửi nhận được trên website, dạng NQ000123.

Location.Code của tỉnh, hoặc khac.

Mã da-co / se-thanh-lap / chua-dinh; là nhãn.

Lịch hẹn gặp / khảo sát gần nhất (plan cổng §6.29) — còn giữ sau khi đăng ký rời "Đã hẹn gặp/khảo sát"; null = chưa từng ghi lịch.

Kênh tiếp nhận; là nhãn.

Nhân viên nhập tay; rỗng với đăng ký từ form website.

Lần khách vào xem Cổng nhượng quyền gần nhất (plan cổng §6.28): LastSeenAt lớn nhất của mọi phiên trên mọi mã gắn đăng ký này — cổng chạm mốc này khi khách còn đang xem, không chỉ lúc nhập mã. null = khách chưa từng vào cổng (kể cả khi sale đã chọn tay "Đã xem thông tin nhượng quyền"). Không gác theo role cổng.

Mã truy cập Cổng nhượng quyền gần nhất của đăng ký (plan cổng §6.23): mã chưa thu hồi nếu có, không thì mã thu hồi gần nhất; null khi chưa từng cấp mã HOẶC người gọi không có role cổng (FranchisePortal.Sale / Manage) — role cổng là hàng rào của mã.

Người gọi xem được mã truy cập của đăng ký này — cùng phạm vi FranchisePortalNavPermissions.ApplyScope: role cổng ∧ (quản lý mọi mã ∨ là người phụ trách). false thì rỗng vì KHÔNG ĐƯỢC XEM, không phải vì chưa cấp mã — giao diện không được nói "chưa cấp mã" (rule quyen-hien-thi).

Người gọi tạo được mã truy cập cho đăng ký này: có role tạo mã ∧ là người phụ trách ∧ đăng ký chưa có mã chưa thu hồi — cùng luật máy chủ kiểm ở POST api/FranchisePortalAccessCode/create.

Các đoạn trạng thái theo thời gian của một đăng ký (POST api/FranchiseLead/status-timeline) — thanh của biểu đồ Gantt trang lịch hẹn (plan cổng §6.30).

Liền nhau, cũ trước; đoạn cuối To = null là trạng thái hiện tại.

Một khoảng thời gian đăng ký ở một trạng thái.

null = còn đang ở trạng thái này.

Tóm tắt mã truy cập trên dòng đăng ký — KHÔNG có mã rõ (mã rõ chỉ ở GET api/FranchisePortalAccessCode/{id}).

4 ký tự đầu phần thân mã (NQ-ABCD-••••).

active · expiring · expired · revoked (tính tại lúc đọc).

Số mã CHƯA thu hồi của đăng ký — lớn hơn 1 chỉ có ở dữ liệu trước luật "một mã" (§6.23).

Chi tiết một đăng ký — thêm bằng chứng đồng ý, nguồn chiến dịch, trang gửi.

Nguyên văn câu đồng ý người gửi đã đánh dấu; rỗng với đăng ký nhập tay.

null với đăng ký nhập tay.

Dòng Lead gốc nếu bản ghi được chuyển từ bảng cũ.

Một dòng lịch sử cập nhật của đăng ký (GET {id}/history), mới nhất trước. Dòng "Tạo đăng ký" của đăng ký từ website (và của đăng ký có trước khi bật ghi lịch sử) dựng từ chính bản ghi — bằng 0.

Mỗi phần tử một trường đổi, dạng Nhãn: cũ → mới.

Người thao tác; rỗng khi người đăng ký tự gửi form website.

Một người có thể được giao phụ trách đăng ký (giữ role Search hoặc Manage, còn làm việc).

Danh mục cho ô lọc của màn "Đăng ký nhượng quyền" — máy chủ là nguồn duy nhất, giao diện không chép danh sách sang JS (nợ NQW-1: GĐ E đổi nguồn tỉnh ở máy chủ, giao diện tự theo).

Trạng thái xử lý, theo số của .

Tỉnh, thành nhận đăng ký (Location.Code) + lựa chọn khac ở cuối.

Tình trạng doanh nghiệp người đăng ký khai trên form.

Mọi kênh tiếp nhận, theo số của — cho ô lọc.

Kênh nhân viên chọn được khi nhập tay — trừ Website.

Kết quả thao tác trên một đăng ký; = không có hoặc ngoài phạm vi (trả 404).

Id của đăng ký vừa tạo/sửa — giao diện mở thẳng chi tiết sau khi nhập tay.

Số mã truy cập cổng vừa thu hồi theo đăng ký (lưu "Không phù hợp") — giao diện báo trong câu đã lưu.

Kết quả giao hàng loạt (POST api/FranchiseLead/assign-many): ba con số cộng lại bằng số id đã gửi (sau khi bỏ trùng) — giao diện báo đúng bao nhiêu đăng ký thật sự đổi người.

Đăng ký đổi người phụ trách (mỗi cái một dòng lịch sử).

Đăng ký vốn đã do đúng người đó phụ trách (hoặc vốn chưa giao khi bỏ giao) — không ghi gì.

Id không có hoặc ngoài phạm vi người gọi (đã bị xoá sau khi trang nạp) — bỏ qua.

Tên người vừa được giao; null khi bỏ giao.

File Excel của nút Xuất.

Báo cáo tồn đọng đăng ký nhượng quyền (POST api/FranchiseLead/backlog) — hai bảng cùng một lần đọc, cùng phạm vi với danh sách. Mảng Counts xếp đúng thứ tự (bảng thời gian chờ) hoặc (bảng theo tỉnh) — giao diện không chép danh sách cột sang JS.

Cột thời gian chờ: số ngày kể từ lần cập nhật gần nhất (D0, D1, … D30+).

Mọi trạng thái theo thứ tự tiến trình; IsOpen = false là trạng thái đã đóng (đã ký, không phù hợp).

Bảng thời gian chờ gộp mọi tỉnh — đủ các trạng thái đang xử lý, kể cả dòng bằng 0.

Bảng thời gian chờ của từng tỉnh có đăng ký đang xử lý — chỉ các dòng khác 0.

Mỗi tỉnh một dòng, đếm theo MỌI trạng thái (cả đã đóng).

Mốc tính "hôm nay" của cột thời gian chờ.

Gửi lại nguyên văn làm khoá lọc idleMinDays / idleMaxDays của search khi bấm vào ô.

null = không chặn trên (cột cuối).

Một bảng trạng thái × thời gian chờ; rỗng = gộp mọi tỉnh.

Gửi lại nguyên văn làm khoá lọc provinceCode (kể cả chua-ro).

Dòng tổng theo từng cột.

null ở dòng tổng.

Theo thứ tự .

Số đăng ký đang xử lý (trừ trạng thái đã đóng).

Một bậc gói vùng phủ POINT / HUB / ZONE / REGION (GĐ K, plan cổng §6.16) — cho màn tham số /goi và ô "Phạm vi giá" của sale. Dữ liệu nội bộ: KHÔNG đưa nguyên danh sách ra cổng (khách chỉ thấy bậc của mình).

Bậc cuối — mã có nhiều phường hơn vẫn thuộc bậc này.

"6–15 phường, xã" / bậc cuối "từ 31 phường, xã".

"Giá bảng" / "Giảm 15 %".

"75 % bảng chuẩn".

Hỗ trợ riêng — mỗi dòng một ý.

Bốn bậc theo thứ tự ngưỡng kèm dấu phiên bản — form sửa gửi lại dấu này (người khác vừa sửa thì từ chối).

Trần số phường/xã của một mã — dải của mọi bậc phải nằm trong 1 … số này.

Kết quả một thao tác ghi của Cổng nhượng quyền. = không có hoặc ngoài phạm vi → HTTP 404.

Id của bản ghi vừa tạo/sửa.

Một dòng của danh sách "Nội dung cổng".

Topic vật chủ của bộ khối; null với mục bảng giá.

Mục đã có bản xuất bản khách xem được. Mục bảng giá không có khối nên luôn true.

Chi tiết một mục cho form sửa.

Tên hệ thống của topic vật chủ (FranchisePortal.<Code>) — editor khối hỏi bộ khối theo tên này.

Đường dẫn của mục trên website.

Danh mục cho form mục cổng (GET form-options) — giao diện không chép danh sách sang JS.

Đoạn đường dẫn không đặt được làm slug mục.

Bản ĐANG SỬA của khối nội dung một mục (GET {id}/blocks) kèm thứ editor cần: bộ khối của vật chủ, dấu phiên bản để xuất bản đúng bản đã thấy, trạng thái xuất bản, và cảnh báo khối trỏ tới tệp không còn dùng được.

False với mục không có khối (mục bảng giá) — màn chỉ hiện tab Thông tin.

Lý do mục LẼ RA có khối mà không sửa được (nội dung lệch); null = bình thường.

Bộ khối của mục: loại khối được thêm, luật số lượng, bộ icon. Enabled = false khi false.

Dấu bản đang sửa — gửi lại khi bấm Xuất bản (POST {id}/publish).

Bản đang sửa khác bản khách đang thấy (hoặc chưa xuất bản lần nào mà đã có khối).

Khối của bản ĐANG SỬA trỏ tới tệp không còn dùng được — lưu / xuất bản sẽ bị từ chối cho tới khi gỡ.

Khối của bản ĐÃ XUẤT BẢN trỏ tới tệp không còn — cổng đang tự ẩn phần đó với khách.

Một khối trỏ tới một tệp riêng tư không còn dùng được.

Thứ tự khối trong bộ khối, tính từ 1.

Câu nói rõ lý do (đã xoá, sai loại, thuộc mục khác…).

Kết quả lưu (POST {id}/blocks) hoặc xuất bản (POST {id}/publish) khối của một mục.

True = có người lưu khối sau khi người bấm mở màn (dấu phiên bản gửi lên đã cũ) — chưa ghi / chưa xuất bản gì. Giao diện báo để người dùng tải lại bản mới nhất; không tự tải lại vì sẽ mất phần họ đang soạn.

Link xem trước bản đang sửa của một mục (POST {id}/preview-token). là đường dẫn trên website kèm token (/thong-tin-nhuong-quyen/xem-truoc/…) — giao diện ghép với địa chỉ website của môi trường.

Một dòng của danh sách "Mã truy cập". Không mang mã rõ — chỉ 4 ký tự đầu.

4 ký tự đầu phần thân mã (NQ-ABCD-••••).

Mã đăng ký nhượng quyền của khách, dạng NQ000123.

Trạng thái tính tại lúc đọc: active · expiring (còn ≤ 2 ngày) · expired · revoked.

Mã tỉnh sale ghi cho mã — nhãn lọc, không gác gì trên cổng (thứ khách thấy là PriceScope ở chi tiết mã).

Số mục đang bật đã mở cho mã này / tổng số mục đang bật.

Tóm tắt phạm vi giá đã gắn (): none · below (có phường nhưng chưa đủ gói — khách thấy câu "cần từ 3 phường…") · wards (đã vào một gói vùng phủ).

Nhãn in ở danh sách: "7 phường, xã · HUB" / "2 phường, xã · chưa đủ gói"; null khi chưa gắn.

Tỉnh/thành phố của các phường đã gắn, cách nhau dấu phẩy (được nhiều tỉnh); null khi chưa gắn.

Giá trị của .

Tỉnh/thành phố có giá ở phiên bản giá hiện hành trong ô chọn của khối "Phạm vi giá".

Một phường/xã CÓ GIÁ ở phiên bản giá hiện hành trong ô chọn của khối "Phạm vi giá".

Tên kèm loại (vd "Phường Hà Đông") — đúng chuỗi được chụp vào phạm vi giá khi gắn.

Chi tiết một mã — có mã rõ, chỉ trả cho người trong phạm vi của mã.

Mã rõ dạng NQ-XXXX-XXXX; rỗng khi máy chủ không giải mã được (đổi khoá bí mật).

Mọi mục cổng kèm trạng thái mở/khoá của mã này, theo thứ tự hiển thị.

Các thao tác gần nhất, mới trước.

Thứ sale đã gắn cho khách ở mục bảng giá; null = chưa gắn gì (khách thấy lời nhắn liên hệ tư vấn viên).

Phạm vi giá của một mã: các phường/xã đã gắn + gói vùng phủ tự xếp theo số phường (GĐ K).

Tỉnh/thành phố của các phường, cách nhau dấu phẩy theo thứ tự gắn — được nhiều tỉnh (§6.17).

Tên gói vùng phủ của mã ("HUB"); null khi chưa đủ gói hoặc bảng bậc trống.

Nhãn của gói ("Phát triển").

Câu nhắc khi chưa đủ gói ("Cần từ 3 phường, xã để vào gói POINT.") — đúng câu khách thấy trên cổng.

Tên kèm loại chụp lúc gắn ("Phường Hà Đông").

false = mục đang ẩn với mọi mã; không mở thêm được, khách không thấy dù đã mở.

Mục dữ liệu ("Bảng giá vùng phủ", "Kế hoạch kinh doanh" — GĐ M): dựng từ phường/xã đã gắn cho mã; mở mục này mà mã chưa gắn phường nào thì khách chỉ thấy "Chưa có khu vực nào được gắn cho bạn".

Kết quả tạo mã: mã rõ trả về đúng lần này để hiện cho sale (xem lại được ở chi tiết).

Tổng thời gian xem một mục của một mã = tổng DurationSec các lần rời mục.

Số lần mở mục.

Dấu vết của một mã: một trang sự kiện (mới trước) + tổng theo mục trên TOÀN BỘ sự kiện của mã.

Một tin nhắn hỏi-đáp với trợ lý AI của một mã (tab Hỏi đáp của drawer mã — GĐ G).

Transcript của một mã: một trang tin nhắn (MỚI trước — giao diện tự đảo để đọc) + bộ đếm câu hỏi.

Tổng số câu khách đã hỏi bằng mã này (cột QuestionCount).

Số câu đã hỏi hôm nay (giờ Việt Nam) và trần mỗi ngày — để biết khách sắp / đã hết lượt.

Một nhà cung cấp AI chọn được cho trợ lý — KHÔNG có key, chỉ có cờ có / chưa có key.

Loại mà trợ lý cổng gọi được (Anthropic / OpenAI) — loại khác không chọn được.

Gốc URL — chỉ có ý nghĩa với loại OpenAI (adapter Anthropic luôn gọi địa chỉ mặc định). Hiện cho người quản lý thấy dữ liệu khách sẽ đi đâu trước khi lưu.

Lần sửa cuối của dòng nhà cung cấp (màn nhà cung cấp AI, role Ai.Marketing).

Dấu hiện tại của dòng (FranchisePortalAiRules.ProviderPin) — form gửi lại lúc lưu (CNQ-65).

Cấu hình trợ lý AI cổng (màn "Cấu hình trợ lý", GĐ G) — đọc từ các khoá FranchisePortal.Ai.*.

Id nhà cung cấp đã chọn; null = trợ lý tắt (KHÔNG lùi về nhà cung cấp mặc định).

Model đã cấu hình; rỗng = .

Nhà cung cấp trợ lý dùng thật lúc này — đúng dòng đã chọn nếu còn dùng được; null = trợ lý không gọi được ai.

Dòng đã chọn bị sửa (loại / BaseUrl / key) SAU lần lưu cấu hình cuối, hoặc cấu hình lưu từ trước khi có dấu ghim — trợ lý đang tắt tới khi người quản lý kiểm tra rồi lưu lại (CNQ-65).

Phần đã đổi ("loại nhà cung cấp", "địa chỉ gọi", "API key"); rỗng khi không so từng phần được (dấu trống / dạng cũ).

Kết quả "Hỏi thử": câu trả lời + số đo + ngữ cảnh đã dùng (chỉ số đo từng mục, không lặp lại nội dung).

Mã đã hết hạn / thu hồi: khách không vào được cổng, mọi mục coi như khoá.

Một tệp riêng tư của cổng. Không mang đường dẫn trên đĩa và không mang văn bản đã trích.

Đã trích được văn bản cho trợ lý AI (chỉ PDF).

Kết quả tải tệp lên.

Một tỉnh/thành phố 2 cấp trong ô chọn tỉnh của trang tải mẫu.

Số phường/xã 2 cấp của tỉnh trong danh mục.

Tỉnh thuộc vùng phủ hiện tại (có phường/xã gắn bưu cục) — mặc định được tích sẵn khi tải mẫu. Đọc từ dữ liệu, không ghi cứng danh sách tỉnh.

Số phường/xã có giá trong phiên bản hiện hành (trang xuất).

Một phiên bản bảng giá — dòng lịch sử ở trang quản trị, đầu trang ở trang xuất.

Số dòng đã thêm hoặc sửa tay sau khi upload (dòng có UpdatedTime sau ). Khác 0 nghĩa là mã phiên bản in trên bảng giá xuất ra không còn chốt đúng giá của file đã upload.

Lần sửa tay gần nhất; null khi chưa sửa dòng nào.

Chi tiết một dòng giá của phiên bản hiện hành — nạp vào form sửa của quản trị.

Dấu phiên bản của dòng — gửi lại khi lưu; dòng đã bị người khác sửa thì máy chủ bác.

Một phường/xã 2 cấp CHƯA có giá trong phiên bản hiện hành — ô chọn của form thêm dòng.

Lỗi của một ô trong form thêm/sửa dòng giá — là tên thuộc tính của model.

Kết quả thêm/sửa một dòng giá: dòng sau khi lưu và phiên bản với số dòng, tổng giá đã tính lại.

Một phường/xã có giá trong phiên bản hiện hành — dòng của bảng tích chọn ở trang xuất.

Location.Id của phường/xã — khoá dòng, cũng là giá trị gửi lên khi xuất.

Lỗi của một dòng (hoặc của cả file khi = 0) lúc kiểm file upload.

Số dòng trong Excel (hàng 1 là tên cột); 0 = lỗi mức file.

Số dòng và tổng giá theo một nhóm (tỉnh hoặc bậc) ở bản xem trước.

Bản xem trước sau khi file qua kiểm — quản trị bấm xác nhận thì mới lưu.

Kết quả kiểm / lưu file upload. Có lỗi thì đầy và null — không ghi gì.

Phiên bản vừa lưu (chỉ có sau bước xác nhận).

File nhị phân trả về cho nút Tải mẫu / Xuất.

Phần tổng của bảng giá xuất ra khi có tích chọn — kết quả của FranchisePriceCalculator.

Số phường/xã đã chọn ít hơn mức tối thiểu — ghi cảnh báo đỏ, vẫn cho xuất.

Σ giá nhượng quyền (gồm VAT).

Làm tròn nửa lên (tổng ÷ (1 + thuế suất)).

Tổng − giá chưa VAT.

Σ cọc theo sản lượng, trước khi kẹp sàn/trần.

min(tối đa, max(tối thiểu, Σ cọc theo sản lượng)).

Số xe × bảo đảm mỗi xe thuê.

Tiền bảo đảm theo vùng + bảo đảm xe thuê.

Tổng phí nhượng quyền + tổng tiền bảo đảm.

Cờ hiển thị màn Đối soát bưu cục.

Kế toán LADA: lập nháp, phát hành, khoá, đánh dấu hoá đơn, xem mọi phiếu.

Bưu cục xác nhận phiếu của mình.

Bưu cục xem phiếu của mình (Confirm hoặc FranchiseWallet.View, thuộc bưu cục nhượng quyền).

Một phiếu đối soát tháng.

"11/2026".

Một dòng bảng kê hoá đơn.

Một đơn của phụ lục K1.

"Bưu cục tự thu" hoặc người đã thu CƯỚC hộ (không kể tiền thu hộ COD, không kể khoản đã đảo).

Quyền thao tác trên đúng phiếu này.

Thêm điều chỉnh tay "vào kỳ" của phiếu nháp này (cần cả quyền quản lý phiếu lẫn quyền điều chỉnh Ví).

Chi tiết phiếu.

Ví v2: biên bản đối chiếu tháng — đầu kỳ, phát sinh theo mã, nạp, rút, cuối kỳ (plan §3.6).

Ví v2: chiều 3 — cước bưu cục sale lập hoá đơn cho khách (E5, CK-THẲNG, đơn hoàn).

Tổng chiều 3.

V-65: đơn nội vùng của kỳ (cước chính thức = cước tạm tính) kèm cân khai — kế toán kiểm xác suất.

Tổng cước các đơn nội vùng.

Một đơn nội vùng của phiếu tháng (V-65).

Lúc chốt cước chính thức (= lúc đơn được nhận diện nội vùng).

Cân khai (gram) — Σ cân kiện lúc tạo đơn.

Cước tạm tính = cước chính thức.

Biên bản đối chiếu tháng (Ví v2): Đầu kỳ + Phát sinh + Nạp + Rút = Cuối kỳ.

Phát sinh nghiệp vụ (mã E, điều chỉnh tay) — không gồm nạp / rút.

Rút ròng (rút − hoàn lệnh rút bị huỷ / từ chối), số âm.

Một dòng chiều 3 của bảng kê.

Kết quả lập nháp hàng loạt.

Một bưu cục nhượng quyền trong ô lọc / hộp lập phiếu.

File tải về.

Cờ hiển thị của màn Ví bưu cục (nav-permissions).

Bưu cục xem ví của chính mình.

Kế toán LADA: xem mọi ví, tạo điều chỉnh, duyệt lần 1, đối chiếu lại đơn.

Duyệt lần 2 điều chỉnh từ ngưỡng.

Ngưỡng cần người duyệt thứ hai.

Bật ví cho chi nhánh / sửa tham số ví (Ví v2, role FranchiseWallet.Config hoặc Founder).

Tạo / huỷ lệnh rút của ví bưu cục mình (Ví v2 GĐ C, role FranchiseWallet.Withdraw + thuộc bưu cục nhượng quyền).

Kế toán quỹ: ghi nhận nạp, chuyển / từ chối lệnh rút (Ví v2 GĐ C, role FranchiseWallet.Treasury hoặc Founder).

Đọc dòng Ví / tóm tắt / đơn nợ cước / dự kiến phí (View thuộc bưu cục nhượng quyền, Manage, Approve) — plan §3.8.1.

Thấy mọi ví: sổ vấn đề, duyệt / từ chối điều chỉnh, ô chọn bưu cục (Manage, Approve).

Danh sách ví (Manage, Approve, Config, Treasury) — kế toán quỹ chọn bưu cục khi ghi nạp, kế toán trưởng mở cấu hình (V-47).

Xem lệnh rút / khoản nạp: bưu cục (ví mình — View hoặc Withdraw) và LADA (Manage, Approve, Treasury).

Bưu cục của người dùng.

Tên bưu cục của người dùng.

Một dòng Ví.

Dòng có vào số dư không.

Cách tính đọc được.

Tên bưu cục / chi nhánh của người thu tiền.

Dòng gốc mà điều chỉnh tay này điều chỉnh.

Mã phiếu đối soát (BB-…) — chỉ điền ở chi tiết một dòng.

Điều chỉnh tay đang chờ người duyệt thứ hai.

Vai của bưu cục trên đơn khi ghi dòng (Ví v2): 1 bán (S) · 2 lấy (L) · 3 phát (P) · 4 phát hoàn (PH).

Cước / COD dùng để tính dòng.

Cơ sở tính là cước chính thức (đã chốt khi nhập kho) hay tạm tính.

Cơ sở tính đọc được — "Cước chính thức 246.000 đ", "COD 2.500.000 đ".

Hình thức trả cước của đơn tại sự kiện ghi dòng.

Danh sách dòng Ví kèm tổng (khuôn TransactionSearchResult: tổng do máy chủ tính trên toàn phạm vi lọc, không theo trang).

Số dư hiện tại của ví (mọi thời gian, mọi dòng vào số dư).

Tổng tạm tính hiện tại (chưa vào số dư).

Tổng các dòng vào số dư trong phạm vi lọc.

Tổng tạm tính trong phạm vi lọc.

Tổng một loại dòng.

Tóm tắt ví của một bưu cục trong một khoảng.

Bưu cục nhượng quyền (chịu ngưỡng / rút); false = chi nhánh LADA bật ví chỉ để đo.

Ví đã bật (Active ∧ EnabledAt).

Số rút được ngay = số dư − tạm giữ − số dư tối thiểu (≥ 0); chỉ bưu cục nhượng quyền đã bật ví.

Số dư dưới ngưỡng cảnh báo (bằng ngưỡng không tính).

Tài khoản nhận tiền rút đã khai.

Một ví trong danh sách của LADA.

Kết quả bật ví cho một chi nhánh (Ví v2, POST api/FranchiseWallet/wallets/enable).

2 = bưu cục nhượng quyền, 3 = chi nhánh LADA.

Ví đã bật từ trước — lần gọi này không đổi gì.

Cờ chặn xuất kho theo ví (bưu cục nhượng quyền: bật; chi nhánh LADA: tắt — chỉ ghi để đo).

2 = bưu cục nhượng quyền, 3 = chi nhánh LADA.

Bưu cục nhượng quyền đã bật ví có số dư dưới ngưỡng cảnh báo.

Một lần đổi cấu hình ví (tham số / tài khoản) — plan §3.10 "Tham số: mỗi lần đổi ghi lịch sử".

Nội dung đổi đọc được: "Số dư tối thiểu: 20.000.000 → 15.000.000; Tài khoản nhận: … → …".

Dự kiến phí của một đơn nếu giao thành công từ trạng thái hiện tại (GET api/FranchiseWallet/orders/{id}/forecast).

Tổng các dòng trả về = ví thay đổi dự kiến (gồm cả dòng giữ tiền bưu cục đang cầm).

Lãi gộp dự kiến: tổng trừ các dòng giữ tiền E1 / E2 / E3 / E9 (tiền mặt cầm hộ, không phải lãi / lỗ).

Chưa chốt cước chính thức — số theo cước tạm tính.

Tổng + lãi gộp theo từng bưu cục có dòng (V-56) — LADA xem đơn nhiều bưu cục thì cộng lẫn phí của nhiều bên, không còn là "lãi gộp của bưu cục"; bưu cục chỉ thấy dòng mình nên luôn một phần tử.

Dự kiến phí của một bưu cục trên đơn.

Một dòng dự kiến.

Một vấn đề ghi Ví cần soát.

Loại vấn đề (V-24): 0 luật · 1 lỗi kỹ thuật · 2 chặn xuất kho · 3 bất biến T17 · 4 ghi chú chốt cước.

Bưu cục liên quan (chặn xuất kho: bưu cục phát).

Đã tự đóng (lượt đối chiếu / kiểm bất biến sau không còn gặp).

Bưu cục sở hữu một khách.

Người xem được sửa bưu cục sở hữu (role Customer.CreateOrUpdate / Founder) — giao diện ẩn ô chọn khi false.

Bưu cục nhượng quyền chọn được.

Kết quả đối chiếu lại một đơn.

Một lệnh rút tiền ví (Ví v2 §3.5).

Dòng RUT đã trừ ví.

Dòng RUT-HOAN hoàn ví (từ chối / huỷ).

Dòng RUT-HOAN đang chờ người duyệt thứ hai (từ chối từ ngưỡng duyệt hai người) — ví CHƯA được hoàn.

Danh sách lệnh rút kèm số rút tối đa hiện tại của ví (khi xem một ví).

Ví đang xem (null = nhiều ví).

Số dư hiện tại của ví đang xem.

Số tối đa rút được ngay lúc này = số dư − tạm giữ − số dư tối thiểu (≥ 0).

Tài khoản nhận tiền rút đã khai của ví đang xem.

Một khoản nạp ví (Ví v2 §3.5).

Dòng NAP đã cộng ví.

Số dư ví sau khi ghi nhận (chỉ có ở kết quả ghi nhận).

Một khoản khách nợ cước đơn hoàn (dòng NO-CUOC) — danh sách đơn nợ cước của bưu cục sale (mota L2-4).

Dòng NO-CUOC.

Cước đi + hoàn khách còn nợ.

Hoàn thành công lúc.

Phiếu đối soát khách đang giữ chỗ / đã cấn.

Đơn COD đã / sẽ bị cấn.

Vỏ kết quả chung của API bảng giá nội bộ: Result/Message như mọi API, kèm dữ liệu, cờ 403 và danh sách lỗi / cảnh báo để màn hình in từng dòng.

Dữ liệu (null khi thất bại).

Bị từ chối vì quyền / phạm vi (controller trả HTTP 403).

Không tìm thấy (controller trả HTTP 404).

Các lý do chặn (in từng dòng).

Cảnh báo không chặn.

Thành công.

Thất bại nghiệp vụ.

Bị từ chối quyền.

Không tìm thấy.

File Excel một phiên bản bảng giá (GĐ5).

Cờ hiển thị của trang bảng giá nội bộ (nav-permissions).

Soạn / sửa nháp.

Duyệt / huỷ / đặt ngày ngừng.

Xem bản áp cho bưu cục của mình (có role View và thuộc bưu cục nhượng quyền).

Bưu cục của người dùng (0 = không thuộc bưu cục nào).

Tên bưu cục của người dùng.

Có role xem bảng của bưu cục (để màn hình nói đúng lý do khi CanViewOwn = false).

Bưu cục của người dùng là bưu cục nhượng quyền.

Một bưu cục nhượng quyền để chọn phạm vi.

Id.

Mã.

Tên.

Trạng thái hoạt động (AgencyStatus).

Đang hoạt động.

Một dòng danh sách phiên bản.

gia_mua_don / phi_lay / phi_giao.

Trạng thái suy từ ngày (Nháp / Sắp / Đang / Hết hiệu lực / Huỷ).

Ngày ngừng áp dụng tường minh.

Ngày kết thúc thực (tường minh, hoặc ngày bản sau thay); null = chưa kết thúc.

"Toàn mạng" hoặc "3 bưu cục: A, B, C".

Một ô của phiên bản (kèm giá niêm yết hiện tại để soi lệch).

"1–3 kg".

Giá niêm yết lúc chụp.

Giá niêm yết hiện tại của nấc (null = nấc không còn trong niêm yết).

Một hàng của ma trận (một dải; phí lấy / giao chỉ có một hàng với RouteId null).

Khoảng cách từ (mét, không gồm) — null với hàng "mọi dải".

Khoảng cách đến (mét, gồm).

Một cột của ma trận (một nấc cân).

"đ/đơn" hoặc "đ/kg".

Một nấc lệch khung.

Quyền thao tác của người đang xem trên đúng bản này.

Chi tiết một phiên bản.

Khớp khung niêm yết hiện tại.

Lý do bấm Duyệt lúc này sẽ bị từ chối (xem trước, chỉ với bản nháp).

Cảnh báo khi duyệt (không chặn).

Tham chiếu ngắn tới một phiên bản.

Đang dùng bản nháp thay bản hiệu lực (chỉ trong cân đối).

Hai con số giữ lại của một cách bán.

Một dòng cân đối.

Bước cân (gram) — đơn vị "đ/bước" của ô cộng bước.

Kết quả kiểm tra cân đối.

Một ô trong màn xem của bưu cục.

Một bản trong màn xem của bưu cục (không có ghi chú nội bộ / người soạn).

Ngày bản này bắt đầu áp cho bưu cục (bản sắp áp có thể khác ).

Bản riêng của bưu cục (true) hay bản toàn mạng.

Bản đang và sắp áp của một bảng.

Bảng giá áp cho một bưu cục.

Bản áp dụng đã tra kèm ô — dùng lại cho Ví bưu cục (GĐ2).

Bản áp dụng đã tra kèm ô — dùng lại cho Ví bưu cục (GĐ2).

Item hiển thị lý do thất bại (Search/List)

Tên/tiêu đề lý do thất bại

Mô tả chi tiết

Loại thất bại: 1 = Pickup, 2 = Delivery, 3 = Both

Tên loại thất bại (hiển thị)

Có bắt buộc tải ảnh minh chứng không

Tiêu đề/hướng dẫn ảnh cần tải

Thứ tự hiển thị

Trạng thái hoạt động

Ngày tạo

Người tạo

Ngày cập nhật

Người cập nhật

DTO item cho xuất Excel đơn hàng cơ bản

ID đơn hàng

Mã đơn hàng

Mã đối tác

Tên khách hàng

Tên Sale

Tên người gửi

Địa chỉ người gửi

Số điện thoại người gửi

Tên người nhận

Địa chỉ người nhận

Số điện thoại người nhận

Trạng thái đơn hàng

Trạng thái vật lý đơn hàng

Khối lượng tính cước (gram)

Khối lượng tính cước (kg) - hiển thị

Tổng cước phí

Tổng cước phí (formatted)

Số tiền thu hộ

Số tiền thu hộ (formatted)

Loại thanh toán cước phí

Thời gian tạo đơn hàng

Thời gian tạo đơn hàng (formatted)

Thời gian lấy hàng thành công

Thời gian lấy hàng thành công (formatted)

Thời gian giao hàng thành công

Thời gian giao hàng thành công (formatted)

Tổng số kiện

Tổng khối lượng (gram)

Tổng khối lượng (kg) - hiển thị

Nội dung hàng hóa

Ghi chú đơn hàng

DTO item cho xuất Excel đơn hàng - mục đích vận hành

ID đơn hàng

Mã đơn hàng

Mã đối tác

Tên khách hàng

Số điện thoại khách hàng

Tên Sale

Số điện thoại Sale

Tên người gửi

Địa chỉ người gửi đầy đủ

Số điện thoại người gửi

Tên người nhận

Địa chỉ người nhận đầy đủ

Số điện thoại người nhận

Tỉnh/Thành phố gửi

Quận/Huyện gửi

Tỉnh/Thành phố nhận

Quận/Huyện nhận

Trạng thái đơn hàng

Trạng thái vật lý đơn hàng

Hướng đơn hàng (Nội tỉnh/Liên tỉnh)

Tuyến vận chuyển

Kho hiện tại

Nhân viên phụ trách lấy hàng

Nhân viên phụ trách giao hàng

Thời gian tạo đơn hàng

Thời gian tạo đơn hàng (formatted)

Thời gian lên kế hoạch lấy hàng

Thời gian lên kế hoạch lấy hàng (formatted)

Thời gian triển khai lấy hàng

Thời gian triển khai lấy hàng (formatted)

Thời gian lấy hàng thành công

Thời gian lấy hàng thành công (formatted)

Thời gian triển khai giao hàng

Thời gian triển khai giao hàng (formatted)

Thời gian giao hàng thành công

Thời gian giao hàng thành công (formatted)

Tổng số kiện

Tổng khối lượng (gram)

Tổng khối lượng (kg) - hiển thị

Khối lượng tính cước (gram)

Khối lượng tính cước (kg) - hiển thị

Nội dung hàng hóa

Giá trị hàng hóa

Giá trị hàng hóa (formatted)

Tổng cước phí

Tổng cước phí (formatted)

Số tiền thu hộ

Số tiền thu hộ (formatted)

Loại thanh toán cước phí

Trạng thái thu COD

Ghi chú đơn hàng

Ghi chú vận hành

Độ ưu tiên

Dịch vụ đặc biệt

Phân loại địa chỉ: 2 cấp hoặc 3 cấp

Tên thành phố (dùng cho hiển thị tuyến)

Vĩ độ điểm lấy/giao. Null nếu chưa xác định được vị trí.

Kinh độ điểm lấy/giao. Null nếu chưa xác định được vị trí.

Nguồn toạ độ: 0 = chưa có, 1 = ghim chính xác (địa chỉ đã có toạ độ hoặc đã geocode), 2 = tâm phường/xã (gần đúng, chỉ để định vị sơ bộ trên bản đồ).

Thời gian hẹn lấy / giao hàng

Cho phép sửa hay không

Phụ phí theo thuộc tính loại hàng (0 với đơn không chọn danh mục)

Số lái xe thực thu của người gửi khi lấy (Ví v2 E1 đã neo số này) — màn thu tiền người gửi hiện thay cước (V-27).

Tiền đối soát dựa trên PayFeeType

Thuộc tính loại hàng đã lưu trên đơn (snapshot tại thời điểm lên đơn / sửa đơn)

Kiện hàng mang thuộc tính này. null = thuộc tính khai ở cấp đơn (đơn cũ, hoặc kênh chưa khai loại hàng theo kiện).

Id thuộc tính gốc, dùng để dựng lại lựa chọn khi sửa đơn

Id lựa chọn gốc, null với kiểu nhập văn bản

Tên thuộc tính tại thời điểm lưu

Mô tả tiếng Việt của kiểu thuộc tính

Nhãn lựa chọn tại thời điểm lưu

Giá tại thời điểm lưu

Giá trị khách nhập với kiểu nhập văn bản

Giá trị khách nhập với kiểu khoảng số

Mã vận đơn

Mã đối tác

Ghi chú đơn hàng

Đơn hàng của khách hàng nào

Bưu cục bán (Ví v2 — vai S trên màn Đơn hàng bưu cục).

Đơn hàng của sale nào

Tuyến

Danh sách ảnh của đơn hàng

Danh mục hàng hóa khách chọn (Category có ContentType = GoodsType)

Thuộc tính loại hàng đã lưu trên đơn (snapshot). Rỗng với đơn cũ / đơn không phân loại.

Thông tin thời gian (tạm thời để lưu dữ liệu cho xuất Excel)

Mã đơn hàng

Ghi chú đơn hàng

Đơn hàng của khách hàng nào

Đơn hàng của sale nào

Một ảnh gắn với đơn hàng (bảng Media) kèm mốc sự kiện đã sinh ra nó (OrderTrack: lấy hàng, giao hàng, trả hàng, nhập/xuất kho...).

App tài xế nhóm ảnh theo và dùng làm tiêu đề nhóm — tên track do hệ thống sinh sẵn bằng tiếng Việt ("X lấy hàng thành công.") nên không cần app tự suy diễn từ , vốn có nhiều giá trị trùng mô tả.

Đường dẫn tải ảnh (đã đổi từ SystemPath sang URL).

Sự kiện sinh ra ảnh; Guid.Empty nếu ảnh không gắn với track nào.

Tên sự kiện (tiếng Việt, hệ thống sinh) — rỗng nếu không tìm thấy track.

Thời điểm sự kiện; null nếu không tìm thấy track.

Ảnh kiện hàng

Loại hàng của riêng kiện này, null = kiện không khai loại (đơn cũ dùng loại cấp đơn).

Tên loại hàng của kiện — điền ở tầng service, rỗng khi kiện không khai loại.

Thuộc tính loại hàng đã lưu cho riêng kiện này (snapshot lúc lên đơn).

Response item cho OrderPackage với thông tin đơn vị đo

Ảnh kiện hàng

Trọng lượng (đã chuyển đổi về đơn vị client)

Chiều dài (đã chuyển đổi về đơn vị client)

Chiều rộng (đã chuyển đổi về đơn vị client)

Chiều cao (đã chuyển đổi về đơn vị client)

Tổng trọng lượng (đã chuyển đổi về đơn vị client)

Ghi chú

Loại hàng của riêng kiện này, null = kiện không khai loại (đơn cũ dùng loại cấp đơn).

Đơn vị trọng lượng

Đơn vị kích thước

Mô tả đơn vị trọng lượng

Mô tả đơn vị kích thước

Item hiển thị danh sách mặt bằng

Item hiển thị thông tin liên hệ

Item hiển thị điểm chấm

Item hiển thị tiêu chí chấm điểm (cho admin và cho NV khi chấm điểm)

Danh sách options kèm điểm

Item hiển thị option

Item hiển thị trong danh sách chương trình khuyến mãi

Item hiển thị trong danh sách mã khuyến mãi

Item hiển thị trong log sử dụng khuyến mãi

Item DTO cho danh sách cấu hình phạt tự động (Search)

DTO đơn giản cho API GetAll CallPath (dùng cho mobile/client). Path = Domain + RelativePath (đã gộp sẵn).

Tên call path (ví dụ: ACCOUNT_REFRESH_TOKEN)

Đường dẫn đầy đủ = Domain + RelativePath (ví dụ: https://srv.v2.ladaexpress.vn/api/Account/RefreshToken)

Mô tả

Represents a CallPath data transfer object

Gets or sets the name

Gets or sets the relative path

Gets or sets the description

Item cho CallPathVersion - dùng cho Search/GetAll

Số phiên bản (ví dụ: 1.0.0)

Số build (ví dụ: 101)

Domain cơ sở (ví dụ: https://api.ladaexpress.vn)

Mô tả phiên bản

Đánh dấu phiên bản mặc định

Số lượng CallPath thuộc phiên bản này

Tổng quan hàng đợi Hangfire: số liệu theo trạng thái, server đang chạy, queue.

Số server Hangfire đang gửi heartbeat.

Số tác vụ định kỳ đã đăng ký.

Số job đang nằm trong queue chờ worker nhận.

Số queue.

Số job đã lên lịch (chạy sau).

Số job đang được worker xử lý.

Số job chạy thành công (còn trong cửa sổ lưu trữ).

Số job thất bại.

Số job đã xoá.

Danh sách server đang chạy.

Danh sách queue.

Một server Hangfire (một tiến trình API đang chạy worker).

Một queue Hangfire cùng số job đang chờ.

Tác vụ định kỳ đã đăng ký bằng RecurringJob.AddOrUpdate.

Id tác vụ, ví dụ notification-cleanup.

Biểu thức cron 5 trường.

Tên lớp.phương thức sẽ chạy, ví dụ NotificationCleanupJob.Execute.

Lỗi khi Hangfire không lên lịch được (cron sai, không nạp được kiểu...).

Đã bị gỡ khỏi lịch (RemoveIfExists) nhưng còn lưu vết.

Tên hiển thị tiếng Việt (từ danh mục; job ngoài danh mục dùng Id).

Job làm gì (từ danh mục).

Có trong RecurringJobCatalog — tức tạm dừng rồi đăng ký lại được.

Tự đăng ký khi API khởi động (trừ khi đã tạm dừng).

Cron mặc định trong danh mục (dùng khi bấm Đăng ký).

Đang nằm trong lịch Hangfire (có bản ghi và chưa bị gỡ).

Đã bị tạm dừng từ trang Tác vụ nền — không tự đăng ký lại khi khởi động.

Một job trong danh sách theo trạng thái.

Trạng thái đang liệt kê: Processing / Scheduled / Enqueued / Succeeded / Failed / Deleted.

Job có còn ở đúng trạng thái này không (false nghĩa là đã chuyển trạng thái khác sau khi liệt kê).

Thời điểm vào trạng thái (bắt đầu chạy / thành công / thất bại / xoá...).

Thời điểm dự kiến đưa vào queue (job Scheduled).

Tổng thời gian chạy tính bằng mili giây (job Succeeded).

Một trang job theo trạng thái.

Chi tiết một job kèm lịch sử chuyển trạng thái.

Một bước trong lịch sử trạng thái của job.

Một lượt giữ hội thoại, đọc được — dòng của màn "ai từng cầm hội thoại này". Danh sách trắng như : chỉ tên hiển thị, không tên đăng nhập, không thông tin liên hệ.

Người giữ lượt này (chính là User.Id)

Bỏ trống nghĩa là người này đang giữ hội thoại

Máy quyết hay người quyết

Người bấm nút; bỏ trống là máy quyết

Người này còn đọc được hội thoại sau khi thôi giữ không — hiển thị để quản lý thấy được hệ quả thật của lý do đã chọn, chứ không phải một ô để sửa.

DTO trả về cho danh sách và chi tiết kênh chat. Lớp này KHÔNG có trường nào chứa token, kể cả dạng đã che. Che chuỗi vẫn là lộ một phần chuỗi, mà câu hỏi duy nhất giao diện cần trả lời là "kênh đã có token chưa, còn hạn tới bao giờ" — hai giá trị bên dưới đủ. Danh sách trường ở đây là danh sách trắng: thứ gì không khai ở đây thì không có đường ra khỏi máy chủ.

Nền tảng của kênh

Tên nền tảng để hiển thị

Định danh kênh phía nền tảng (OA id với Zalo, Page id với Facebook)

Kênh đã có access token hay chưa — giao diện dùng để biết có cần bấm "Kết nối" không

Kênh đã có refresh token hay chưa — thiếu là không tự làm mới được, phải cấp quyền lại

Thời điểm access token hết hạn (Zalo: 25 giờ kể từ lúc cấp)

Token đã hết hạn tại thời điểm truy vấn

Lần cấp quyền gần nhất

Lần job làm mới token gần nhất

Kênh đang bật thì webhook mới nhận tin và mới gửi tin ra được

Bưu cục sở hữu kênh — nhãn tổ chức, không phải hàng rào quyền

Tên bưu cục sở hữu kênh, rỗng khi chưa gắn

Chế độ phân phối — cũng là công tắc bật hàng rào quyền xem của kênh

Tên chế độ phân phối để hiển thị

Số nhân viên đang phụ trách kênh này

Một dòng trong danh sách nhân viên phụ trách một kênh chat. Danh sách trắng: chỉ đủ để giao diện dựng bảng phụ trách. Không có tên đăng nhập, không có số điện thoại — cùng lý lẽ với .

Mã nhân viên (chính là User.Id)

Tên hiển thị của nhân viên

Tên vai trò để hiển thị

Trọng số ép cứng, bỏ trống là tính theo điểm chất lượng

Số hội thoại chưa đóng người này còn đang giữ trên chính kênh này. Yêu cầu tối thiểu của sổ nợ PP-18: nút Gỡ phải nói trước "người này còn giữ N hội thoại" rồi mới hỏi xác nhận, vì gỡ xong chúng về hàng chờ và không còn ai đang theo dõi chúng.

Chi tiết một hội thoại: phần đầu khung chat cộng với các tin nhắn đã nạp.

Thông tin hội thoại — cùng hình dạng với một dòng trong danh sách

Tin nhắn theo thứ tự thời gian tăng dần (tin cũ ở trên, tin mới ở dưới)

Tổng số tin của hội thoại. Lớn hơn số phần tử trong nghĩa là còn tin cũ chưa nạp — giao diện dùng để biết có nên hiện nút "xem thêm" không.

Một dòng trong danh sách hội thoại, và cũng là phần đầu của khung chat. Đây là danh sách trắng: entity ChatConversation có navigation sang ChatChannel và Customer, đẩy thẳng entity ra ngoài vừa lộ dữ liệu không cần thiết vừa làm bộ tuần tự của SignalR ném lỗi vòng tham chiếu (nó không kế thừa cấu hình ReferenceLoopHandling.Ignore của tầng MVC).

Nền tảng của hội thoại

Tên nền tảng để hiển thị

Tên kênh — một hệ thống có thể nối nhiều OA/Page nên phải phân biệt được

Định danh khách phía nền tảng. Cần cho việc đối soát, không hiển thị thẳng

Tên hiển thị của khách trên nền tảng. Rỗng khi chưa lấy được hồ sơ — giao diện phải tự lùi về một nhãn đọc được thay vì hiện ô trống.

Khách của hội thoại này là người ẩn danh — nền tảng không cấp định danh bền vững. Giao diện dựa vào cờ này để nói thẳng "khách ẩn danh" và để không mời gắn khách hàng. Không suy từ việc rỗng: khách thường mà lời gọi lấy hồ sơ hỏng cũng rỗng y như vậy.

Khách hàng trong hệ thống đã gắn với hội thoại này (giai đoạn D)

Tên khách hàng đã gắn, rỗng khi chưa gắn

Nhân viên được phân công (giai đoạn D). v1 chỉ dùng để lọc, không chặn quyền xem

Tên nhân viên được phân công, rỗng khi chưa phân công. Không đến từ navigation — cột AssignedStaffId không có khoá ngoại sang bảng người dùng. Giá trị do IChatStaffDirectory tra và ĐƯỢC TRUYỀN VÀO mapper, nên mọi đường ghi DTO đều phải cung cấp nó (tham số bắt buộc, trình biên dịch canh giúp).

Tên trạng thái để hiển thị

Tóm tắt tin nhắn cuối cùng, dựng sẵn ở tầng lõi

Lần cuối KHÁCH nhắn vào. Cửa sổ trả lời của mọi nền tảng đều tính từ mốc này (Zalo 48 giờ, Facebook 24 giờ).

Số giờ còn lại của cửa sổ trả lời; âm là đã hết, null là chưa có tin vào nào

Nền tảng của hội thoại này có báo "khách đã xem" hay không. Với Zalo là false — đã đo, nền tảng không gửi sự kiện đó (§6.9 kế hoạch). Giao diện dùng cờ này để nói thẳng rằng thang trạng thái dừng ở "Đã nhận", thay vì để nhân viên chờ một dấu hiệu không bao giờ sáng.

Hội thoại này có gửi được tin trả lời trích dẫn hay không. Là câu trả lời cho từng hội thoại chứ không cho từng nền tảng: Zalo trả lời được với khách thường nhưng không với khách ẩn danh (endpoint v2.0 của luồng ẩn danh không có trường trích dẫn). Giao diện dùng cờ này để ẩn hẳn nút "Trả lời", thay vì để nhân viên soạn xong một câu rồi mới nhận lỗi.

Hội thoại này có thả được biểu tượng cảm xúc lên tin nhắn hay không.

Bộ biểu tượng cảm xúc nền tảng chấp nhận, theo đúng thứ tự hiển thị. Mảng rỗng nghĩa là không giới hạn — giao diện được cho chọn biểu tượng bất kỳ (đó là trường hợp của Facebook; Zalo trả về đúng sáu mã của mình). Danh sách đi từ máy chủ ra chứ không để phía trình duyệt tự chép: hai bảng song song là hai bảng sẽ lệch, và cái lệch chỉ lộ ra khi nền tảng từ chối một biểu tượng đã bấm được.

Hội thoại này có nút "Đồng bộ lại tin từ nền tảng" hay không — cờ năng lực của nền tảng, không phải cờ quyền: endpoint conversation/{id}/sync-history gác bằng ChatConversation.GetById, đúng role người dùng đã phải có để mở được hội thoại này.

Người đang đăng nhập có được thay đổi hội thoại này không — trả lời, đánh dấu đã đọc, nhận về mình, phân công, nhả, chuyển, gắn khách. false = chỉ đọc.

Sổ nợ PP-36. Máy chủ vốn đã phân biệt đọc với ghi rất rõ — đo được ở §18.4 trên cùng một hội thoại, cùng một người, cách nhau vài giây: GET conversation/298 trả 200 còn mark-read / send / assign đều trả "Không tìm thấy hội thoại." Thiếu cờ này thì chỉ giao diện là không biết: ô soạn tin không khoá, nút Gửi bật ngay khi gõ, và một sale gõ xong câu trả lời cho khách thật là mất trắng, kèm một câu báo lỗi nói sai chuyện. Giá trị lấy nguyên từ ChatVisibility.AllowsWrite — cùng biểu thức mà 13 đường ghi đang dùng, không có bản thứ hai để lệch. Cờ này không phải hàng rào: hàng rào vẫn ở tầng service. Nó chỉ làm giao diện biết đúng điều máy chủ vốn đã biết.

Chế độ phân phối của kênh chứa hội thoại. null = không tra được kênh.

Ra tới giao diện vì hai trường dưới im lặng theo chế độ kênh (§6.5, PP-34), và không có trường này thì màn hàng chờ không phân biệt được hai chuyện rất khác nhau: "khách không đang chờ" và "kênh này hệ thống không chấm". Bản đầu của bản vá PP-34 để tooltip nói câu thứ nhất cho cả hai — tức dịch một phép không đo thành một lời khẳng định, đúng lớp lỗi FB-2 mà cả đợt này đã cắn tám lần.

Chữ hiển thị của ; rỗng khi không tra được kênh.

Số phút giờ làm khách đã chờ được trả lời. null = khách không đang chờ (đã có tin trả lời sau tin của họ, hoặc hội thoại đã đóng), hoặc kênh không ở chế độ tự phân phối nên hệ thống không chấm thời gian chờ ở đó (§6.5, PP-34) — phân biệt hai ca bằng .

Tính ở máy chủ, không để trình duyệt tự trừ hai mốc thời gian. Giờ làm việc là một cấu hình có nghỉ trưa, có ngày nghỉ và có múi giờ; chép phép tính ấy sang JavaScript là dựng nguồn sự thật thứ hai, và cái lệch sẽ hiện ra dưới dạng "màn hình nói khách chờ 620 phút" trong khi hệ thống mới đếm 10.

Khách đã chờ quá ngưỡng chưa. Hội thoại đã giao chấm theo Chat.Sla.RemindMinutes; hội thoại còn ở hàng chờ chấm theo Chat.Queue.AlertMinutes. Luôn false ngoài kênh AutoDistribute (§6.5, PP-34): nhãn "Quá hạn" hứa rằng hệ thống sẽ nhắc và sẽ thu hồi, mà không lượt quét nào chạy cho kênh khác — cả hai job đều lọc AssignmentMode == AutoDistribute.

Một dòng của màn nhật ký quyết định phân phối. Danh sách trắng như mọi DTO khác của miền: đủ để dựng bảng và trả lời "vì sao không phải tôi", không kèm nội dung tin nhắn của khách.

Tên hiển thị của khách trong hội thoại — để người đọc nhận ra dòng nào là dòng nào

Tên người được chọn; rỗng khi không ai nhận

Mã luật: sticky-customer / least-loaded / no-candidate / lost-race

Tên luật bằng tiếng Việt để hiển thị

Bảng ứng viên đã cân nhắc, kèm lý do bị loại của từng người

Một ứng viên trong bảng cân nhắc của một quyết định

Lý do bị loại bằng tiếng Việt; "đủ điều kiện" khi không bị loại

Một dòng của bảng đối chiếu dry-run: một sale trên một kênh nhận bao nhiêu lượt trong cửa sổ phát lại.

Số lượt được chọn trong cửa sổ

Tỉ lệ phần trăm trên tổng lượt có người nhận của kênh

Tỉ lệ phần trăm đáng lẽ nhận được nếu chia đúng theo trọng số — mẫu số là tổng trọng số của những người có mặt trong bảng.

Lệch tuyệt đối giữa và , tính bằng điểm phần trăm

Bảng đối chiếu dry-run của một kênh — đầu vào của cổng D2.

Tổng số quyết định trong cửa sổ, kể cả lượt không ai nhận

Số lượt có người nhận

Số lượt không ai đủ điều kiện

Số lượt luật khách quen quyết định

Số người có mặt trong bảng

Lệch lớn nhất giữa hai người cùng trọng số, tính bằng phần trăm trên người nhận nhiều hơn. Ngưỡng cổng D2: > 20 % là không bật.

Câu cảnh báo về độ tin cậy — cỡ mẫu quá nhỏ, hoặc kênh chỉ có một người. Rỗng nghĩa là bảng này đọc được như một bảng phân bố.

Kết quả một lượt phát lại lịch sử

Số tin inbound đã duyệt qua

Số hội thoại có ít nhất một quyết định

Số dòng nhật ký quyết định đã ghi

Số dòng nhật ký phát lại cũ đã dọn trước khi chạy

Chuyển entity chat sang DTO. Đây là ranh giới ra khỏi máy chủ — thứ gì không khai trong DTO thì không có đường đi ra. Để ở một chỗ dùng chung vì có HAI đường ra: REST (controller) và SignalR (ChatHub). Hai đường map khác nhau là hai nguồn dữ liệu cùng đổ vào một mảng phía trình duyệt mà lại khác hình dạng — đúng loại lỗi im lặng mà kế hoạch §6.8 đang tìm cách tránh. Phân hệ này KHÔNG dùng AutoMapper (theo tiền lệ ChatChannelService.ToItem): DTO có trường dẫn xuất cần tra cứu theo nền tảng (), diễn đạt bằng hàm thường rõ hơn bằng cấu hình.

Chuyển một hội thoại sang DTO.

Hội thoại; navigation ChatChannel/Customer có thì dùng, không có thì để rỗng Dùng để biết cửa sổ trả lời của nền tảng; bỏ trống thì không tính Mốc thời gian tính cửa sổ trả lời Tên nhân viên đang phân công, tra sẵn qua IChatStaffDirectory. Tham số bắt buộc, cố ý không có giá trị mặc định. Cột AssignedStaffId không có navigation nên mapper không tự tra được, mà quên điền thì dòng hội thoại đẩy qua SignalR sẽ mang tên rỗng và phía trình duyệt thay nguyên dòng bằng bản vừa nhận — tên người phụ trách biến mất khỏi màn hình ngay khi có tin mới. Đúng hình dạng của lỗi đã cắn ở giai đoạn C. Để trình biên dịch bắt người viết đường ghi mới phải quyết định. Chế độ phân phối của kênh chứa hội thoại — cổng của nhãn "Quá hạn" và cột "Chờ trả lời" (§6.5, sổ nợ PP-34). null nghĩa là không tra được kênh, và khi đó coi như kênh không tự phân phối: fail-closed, cùng chiều với . Tham số bắt buộc, cố ý không có giá trị mặc định — cùng lý do với và : đường đẩy realtime nạp hội thoại từ webhook và không phải lúc nào cũng Include kênh, nên một giá trị mặc định ở đây là nhãn "Quá hạn" tắt hoặc bật sai ở đúng cái đường đã cắn hai lần. Người đang xem có được thay đổi hội thoại này không — luôn là ChatVisibility.AllowsWrite(conversation) của chính người đó (sổ nợ PP-36). Tham số bắt buộc, cố ý không có giá trị mặc định, và ở đây lý do còn nặng hơn hai tham số trên: khai = false thì một đường gọi bị quên sẽ khoá ô soạn tin của người đang phụ trách khách thật — tệ hơn chính lỗi đang vá; khai = true thì bản vá lặng lẽ không có tác dụng ở đúng đường bị quên.

Khách đã chờ bao nhiêu phút giờ làm, và đã quá ngưỡng chưa.

Câu hỏi "khách có đang chờ không, và từ lúc nào" đi qua — đúng hàm mà lượt quét hạn phản hồi dùng. Viết lại ở đây là dựng định nghĩa thứ hai, và cái lệch chỉ lộ ra khi một sale hỏi vì sao màn hình nói 5 phút mà hệ thống vừa thu hồi hội thoại của họ. Hai ngưỡng khác nhau vì đó là hai việc khác nhau: hội thoại đã giao chấm theo hạn phản hồi của người đang giữ, hội thoại còn ở hàng chờ chấm theo ngưỡng báo trưởng nhóm. Dùng chung một ngưỡng là nói dối ở một trong hai màn. Và từ KC-18 cũng là hai cách đếm: dòng đã giao đếm trong giờ riêng của người đang giữ, dòng hàng chờ đếm những phút có ít nhất một ứng viên của kênh vào ca. Mốc bắt đầu thì vẫn chung một hàm cho cả hai. Cổng theo chế độ kênh (§6.5, PP-34). Chỉ kênh AutoDistribute được chấm. Cổng này không phải luật mới — nó là đúng cái cổng mà cả hai lượt quét đã có (ChatSlaSweepService và ChatQueueSweepService đều lọc AssignmentMode == AutoDistribute khi chọn kênh), chỉ là tầng hiển thị chưa có. Thiếu nó thì ngày deploy đầu tiên mọi hội thoại đang chờ nổi nhãn đỏ trên mọi kênh — migration đặt mọi kênh production về Shared — trong khi nguyên tắc số 1 hứa "deploy xong hệ thống không đổi hành vi một chút nào". Cổng áp cho cả hai nhánh ngưỡng, không riêng nhánh đã giao: nhánh hàng chờ đọc Chat.Queue.AlertMinutes, đúng ngưỡng mà lượt quét đọc nó cũng không chạy cho kênh Shared. Kênh FixedOwner cũng không được chấm, và vì cùng một lý do: không lượt quét nào chạy cho nó, nên một nhãn "Quá hạn" ở đó hứa một hành động sẽ không xảy ra. Đọc THẲNG chế độ kênh chứ không hỏi qua một hàm tiện dụng nào — bài học đắt nhất của cổng chất lượng giai đoạn D là IsAssignableToChannelAsync CỐ Ý trả true cho kênh Shared nên không phân biệt được hai chế độ. Cùng lý do và cùng cách viết với .

Chuyển một tin nhắn sang DTO.

Tin nhắn Khối trích dẫn đã tra sẵn qua IChatQuoteResolver, null với tin thường. Tham số bắt buộc, cố ý không có giá trị mặc định — cùng lý do với assignedStaffName ở trên: quên điền ở một đường ghi thì khối trích dẫn biến mất khỏi màn hình ngay khi tin nhận được một cập nhật giao nhận, mà không có lỗi nào báo.

Chữ hiển thị thay cho một tin không có nội dung văn bản. Ở một chỗ dùng chung vì có hai nơi cần đúng cùng một nhãn: cột xem trước của danh sách hội thoại (ChatConversation.LastMessage) và khối trích dẫn. Hai bảng nhãn song song là hai bảng sẽ lệch nhau.

Số giờ còn lại của cửa sổ trả lời tự do. Trả null khi khách chưa nhắn lần nào, hoặc khi chưa có bản gửi tin cho nền tảng đó — không biết luật thì không đoán một con số, vì con số bịa ra vẫn hiện lên màn hình y như con số đã kiểm chứng.

Một bong bóng tin nhắn trong khung chat. Danh sách trắng như , và vì lý do giống hệt: entity ChatMessage có navigation ngược về hội thoại.

Chiều tin: khách gửi vào hay nhân viên gửi ra

Nội dung văn bản, hoặc chú thích của ảnh

Đường dẫn tệp đính kèm để hiển thị

Định danh tin phía nền tảng — cần cho việc đối soát trạng thái giao nhận

Khối trích dẫn của tin gốc, khi tin này là một câu trả lời trích dẫn. null với tin thường. Nội dung được máy chủ tra sẵn () vì nền tảng chỉ gửi MÃ tin gốc. Cố ý KHÔNG trả mã đó ra ngoài: khung chat hiện nay không để lọt chuỗi định danh nền tảng nào của khách, và khối trích dẫn không được là chỗ phá lệ.

Tên người gửi hiển thị dưới bong bóng

Nhân viên đã bấm gửi, null với tin của khách

Định danh admin phía nền tảng đã gõ tin này ngoài LADA (SC-26). Chỉ Zalo có; đây là admin của CHÍNH OA LADA chứ không phải định danh của khách, nên hiện ra được.

Biểu tượng cảm xúc khách đã thả lên tin này, dạng ký tự emoji thật. null là chưa thả hoặc đã gỡ. Giao diện vẽ thẳng ký tự này, KHÔNG có bảng dịch nào ở phía trình duyệt.

Biểu tượng cảm xúc phía LADA đã thả lên tin này.

Nhân viên đã thả ; null mà emoji vẫn có nghĩa là cảm xúc được thả ngoài LADA, từ cửa sổ chat của chính nền tảng.

Lý do gửi hỏng, đã dịch sang tiếng Việt ở tầng ZaloErrorCatalog. Giao diện hiện thẳng chuỗi này dưới bong bóng, KHÔNG viết bảng dịch thứ hai ở phía trình duyệt.

Đoạn trích của tin gốc hiện phía trên một câu trả lời trích dẫn.

Mã tin gốc TRONG LADA, để khung chat cuộn tới khi nhân viên bấm vào khối trích dẫn. null nghĩa là không dựng lại được tin gốc (có trước khi nối kênh, hoặc đã xoá) — khối vẫn hiện, chỉ không bấm được và không có nội dung.

Chiều của tin gốc — khung chat dùng để nói "bạn" hay tên khách

Loại nội dung của tin gốc

Tên người gửi tin gốc

Đoạn trích đã cắt ngắn; rỗng khi không dựng lại được tin gốc

Một dòng gợi ý khách hàng khi nhân viên gắn hội thoại với hồ sơ trong hệ thống. Danh sách trắng rất hẹp, và hẹp có chủ ý: quyền gắn khách hàng (ChatConversation.LinkCustomer) được cấp cho nhân viên chăm sóc khách hàng, không phải cho người quản lý dữ liệu khách. Nó chỉ cần đủ để nhận ra đúng người — không kèm địa chỉ, email, công nợ hay bảng giá.

Một dòng gợi ý nhân viên khi phân công hội thoại. Cố ý chỉ có mã và tên hiển thị, hẹp hơn UserOptionItem dùng chung của repo (không số điện thoại, không tên đăng nhập): ô chọn này chỉ cần một chuỗi để bấm, mà mỗi trường mở thêm là thêm dữ liệu nội bộ đi ra cho một quyền vốn chỉ nói về chuyện phân công hội thoại. Tên đăng nhập đặc biệt không nên có mặt — nó là một nửa của cặp đăng nhập.

Tên hiển thị; tài khoản chưa điền họ tên thì đã được lùi về tên đăng nhập ở tầng dịch vụ

Trạng thái sẵn sàng của một người, dựng cho màn hình.

Trả cả trạng thái hiệu lực lẫn trạng thái tự khai, có chủ ý: menu đổi trạng thái phải hiện đúng thứ người dùng đã chọn (), còn cái chip cạnh nó phải nói sự thật lúc này (). Trộn hai thứ vào một trường là lúc 8 giờ tối, menu tự nhảy sang "Ngoài giờ làm việc" — một giá trị người dùng không chọn được và không gỡ được.

Mã nhân viên

Tên hiển thị

Trạng thái hiệu lực lúc này — kết quả sau khi gộp mọi nguồn

Nhãn tiếng Việt của

Trạng thái người này tự khai (thứ hiện trong menu)

Nhãn tiếng Việt của

Hạn của trạng thái tự khai

Ghi chú của chính người đó

Bị quản lý tạm ngưng đến khi nào

Lý do tạm ngưng do quản lý nhập

Có nhận khách mới lúc này không — bằng EffectiveStatus == Available

Câu mô tả giờ làm việc riêng của người này, ví dụ "08:00–17:30, Thứ Hai–Thứ Bảy, nghỉ trưa 12:00–13:00". Có mặt để màn hình giải thích được vì sao đang "Ngoài giờ làm việc" thay vì chỉ khẳng định là thế. Chuỗi rỗng khi chưa đặt (KC-18, §8.6: giờ làm mặc định ẩn) — trước KC-18 trường này luôn mô tả cấu hình chung, nên chip hiện một giờ làm không áp cho ai.

Đã có giờ làm riêng dùng được chưa (KC-18). false = chưa đặt — người này luôn trong ca, không bao giờ tự thành "Ngoài giờ", và tiêu chí tỉ lệ sẵn sàng coi là chưa có mẫu. Dữ liệu giờ riêng hỏng cũng là false (xem ChatStaffWorkingHours.HasOwnWorkingHours).

Giờ bắt đầu làm việc riêng, dạng HH:mm; null khi chưa đặt

Giờ kết thúc làm việc riêng, dạng HH:mm; null khi chưa đặt. Làm tới hết ngày thì là 23:59 — đúng giá trị người dùng chọn và gửi lại được nguyên văn.

Giờ bắt đầu nghỉ trưa, dạng HH:mm; null = không nghỉ trưa hoặc chưa đặt

Giờ kết thúc nghỉ trưa, dạng HH:mm; null = không nghỉ trưa hoặc chưa đặt

Ngày làm, mã 2 (Thứ Hai) … 7 (Thứ Bảy), 8 (Chủ Nhật), tăng dần — cùng cách đánh số với Chat.WorkingHours.WorkingDays. Mảng rỗng khi chưa đặt.

Giờ gợi ý lấy từ cấu hình chung Chat.WorkingHours.* — cùng dạng các trường giờ ở trên, để hộp "Đặt giờ làm việc" điền sẵn khi người này chưa đặt. Chủ dự án chốt (§8.7 câu 5): cấu hình chung chỉ còn là giờ gợi ý, không áp cho ai.

Trần thời hạn cho Bận / Ra ngoài, tính bằng phút — giao diện dùng để chặn tại chỗ

Trần thời hạn cho Nghỉ, tính bằng ngày

Nghỉ từ bấy nhiêu ngày trở lên thì hội thoại đang cầm được uỷ quyền tạm; 0 = tắt. Giao diện dùng để cảnh báo trước khi người dùng bấm xác nhận.

Một bộ giờ làm việc ở dạng giao diện đọc và gửi lại được (KC-18) — dùng cho giờ gợi ý .

Giờ bắt đầu làm việc, dạng HH:mm

Giờ kết thúc làm việc, dạng HH:mm; hết ngày là 23:59

Giờ bắt đầu nghỉ trưa, dạng HH:mm; null = không nghỉ trưa

Giờ kết thúc nghỉ trưa, dạng HH:mm; null = không nghỉ trưa

Ngày làm, mã 2 (Thứ Hai) … 8 (Chủ Nhật), tăng dần

Một dòng của bảng thời lượng theo trạng thái — mỗi nhân viên một dòng, các trạng thái là cột.

Mã nhân viên

Tên hiển thị

Trạng thái hiệu lực lúc xem báo cáo

Nhãn tiếng Việt của

Đã có giờ làm riêng dùng được chưa (KC-18). false = chưa đặt — người này luôn trong ca và nhận khách theo trạng thái đang đặt.

Câu mô tả giờ làm riêng, cùng dạng với ; chuỗi rỗng khi chưa đặt.

Có mặt vì KC-20 (§8.7 câu 6): sale tự đặt được một ca rất ngắn để gần như luôn "Ngoài giờ" — không nhận khách mới, không bị nhắc hay thu hồi. Chủ dự án chọn không chặn mà cho quản lý nhìn thấy để đặt hộ lại.

Số phút ở trạng thái Sẵn sàng trong cửa sổ báo cáo

Số phút ở trạng thái Bận

Số phút ở trạng thái Ra ngoài

Số phút ở trạng thái Nghỉ

Số phút bị tạm ngưng nhận khách

Tổng số phút có ghi nhật ký trong cửa sổ. Nhỏ hơn độ dài cửa sổ là bình thường: người chưa từng đổi trạng thái không có dòng nhật ký nào, và bịa ra thời lượng cho họ là bịa ra dữ liệu.

Số hội thoại người này đang giữ (chưa đóng) lúc xem báo cáo

Điểm một tiêu chí, kèm mọi thứ cần để người dùng hiểu con số — không chỉ con số.

Đơn vị của — phút, %

Số thô — trung vị phút, tỉ lệ phần trăm

Cỡ mẫu, luôn hiện ra. Trang phải nói được "trung vị này dựng từ 2 hội thoại" chứ không im lặng trình bày nó như một trung vị dựng từ 200 — đó là yêu cầu thẳng của prompt giai đoạn F và là hệ quả của sổ nợ PP-13.

Tiêu chí này có chấm được không. false khi cỡ mẫu bằng 0 — giao diện phải hiện "chưa có dữ liệu" chứ không hiện 0 điểm.

Việc cần làm để tăng điểm tiêu chí này

Điểm của chính người đang đăng nhập — dữ liệu của trang /diem-chat-cua-toi.

Đã có lượt tính nào cho người này chưa

Tổng số tiêu chí đang bật — mẫu số của

Thứ hạng trong nhóm người cùng phụ trách kênh — null khi chưa xếp hạng được.

Chốt CH-9: hiện thứ hạng của mình ("bạn đứng thứ 3/7") nhưng không hiện điểm người khác — đủ động lực, không đủ để so đo. Vì thế DTO này cố ý không có trường nào mang điểm của người khác, kể cả ẩn danh.

Tổng số người trong nhóm xếp hạng

Điểm có đang ảnh hưởng số lượng khách được chia không — cờ Chat.Quality.AffectsDistribution.

Phải nói ra trên giao diện. Trình bày một trọng số 1,18 mà không nói nó chưa có hiệu lực là để người dùng tin rằng họ đang được chia nhiều hơn đồng nghiệp trong khi thực tế máy vẫn chia đều.

Một dòng trong bảng điểm đội — chỉ cho người có quyền ChatQuality.ViewTeam.

Một mẫu tin nhắn nhanh trả cho giao diện — danh sách chọn ở ô soạn tin và bảng ở /tin-nhan-nhanh. Danh sách trắng. Không có ImageSystemPath — đường dẫn đĩa máy chủ không bao giờ ra client (nguyên tắc 1.5; ca test số 10 soi bằng reflection). Không có OwnerUserId — giao diện chỉ cần biết "của tôi hay không" (), không cần mã người dùng của ai.

Tên phạm vi để hiển thị: "Của tôi" / "Dùng chung"

Mẫu có ảnh gửi được hay không — tính theo đường dẫn tệp phía máy chủ, không theo : Zalo tải ảnh lên từ tệp, có URL mà không có tệp là gửi không được.

URL công khai để xem trước. Trên dev trả 404 vì Media.Domain trỏ production (TN-6).

Mẫu cá nhân của chính người đang xem

Một Facebook Page mà quản trị viên đang quản lý, trả về cho bước chọn Page khi kết nối kênh. Lớp này KHÔNG có trường token, và không bao giờ được có: GET /me/accounts trả về Page access token của từng Page, mà token ấy không hết hạn — để nó lọt ra khỏi máy chủ một lần là ai cầm được cũng nhắn tin thay Page mãi mãi. Danh sách trường ở đây là danh sách trắng.

Định danh Page phía Facebook

Tên Page hiển thị cho người chọn

Ảnh đại diện Page

Page này đã có kênh trong hệ thống chưa — chọn lại là cập nhật token, không tạo kênh thứ hai

Item hiển thị khóa học trong danh sách

Item trong curriculum của khóa học (section hoặc standalone lesson)

type: "section" | "standalone"

Id của section hoặc lesson

Thứ tự thống nhất trong curriculum

Request sắp xếp lại curriculum

Chi tiết bài giảng (kèm media, thông tin section/course) cho Learner View

Item hiển thị bài giảng

Item hiển thị media trong bài giảng

Item hiển thị section trong khóa học

Garage trong danh mục

Tên garage

Địa chỉ

Số điện thoại

Người liên hệ

Ghi chú

Còn sử dụng hay không

Số ODO hiện tại của xe (áp dụng cho tất cả hoạt động: nhận xe, trả xe, đổ dầu)

Danh sách hình ảnh kèm theo

Item hiển thị media trong hoạt động xe tải

ID hoạt động xe tải

ID media

URL của media

Alt text của media

Caption của media

Loại media (Ảnh nhận xe/Ảnh trả xe)

Mô tả loại media

Thứ tự hiển thị

Đơn giá

Một cảnh báo tuổi thọ bộ phận do job nền sinh ra.

Bộ phận bị cảnh báo

Xe

Biển số

Chi nhánh quản lý xe

Tên loại bộ phận

Vị trí bộ phận

Vị trí để hiển thị

Mức cảnh báo

Mức cảnh báo để hiển thị

Thời điểm phát hiện

Thời điểm phát hiện để hiển thị

Số km đã dùng tại thời điểm cảnh báo

Số ngày đã dùng tại thời điểm cảnh báo

Thời điểm đã gửi thông báo; null = chưa gửi (công tắc đang tắt hoặc chưa tới lượt)

Đã gửi thông báo hay chưa

Thời điểm cảnh báo được xử lý xong (bộ phận đã thay)

Cảnh báo còn đang mở hay đã xử lý

Bộ phận đang lắp trên xe

Xe

Biển số xe

Loại bộ phận

Tên loại bộ phận

Vị trí trên xe (giá trị enum ComponentPosition)

Tên vị trí hiển thị

Ngày lắp

ODO lúc lắp

Nguồn gốc (giá trị enum ComponentSource)

Tên nguồn gốc hiển thị

Tuổi thọ theo km riêng của bộ phận này

Tuổi thọ theo tháng riêng của bộ phận này

Tuổi thọ theo km đang áp dụng (riêng nếu có, không thì của loại)

Tuổi thọ theo tháng đang áp dụng (riêng nếu có, không thì của loại)

Ghi chú

Còn đang lắp trên xe hay không

Một tên gọi khác của loại bộ phận K200.

ComponentTypeAliasSource: 1 = dữ liệu nền, 2 = người dùng xác nhận.

Loại bộ phận xe trong danh mục

Mã loại bộ phận

Tên hiển thị

Tuổi thọ mặc định theo km

Tuổi thọ mặc định theo tháng

Có gắn với vị trí trên xe hay không

Ngưỡng cảnh báo trước theo km (null = dùng mặc định toàn cục)

Ngưỡng cảnh báo trước theo ngày (null = dùng mặc định toàn cục)

Nhóm phân loại (giá trị enum)

Tên hiển thị của nhóm phân loại

Số lượng trên mỗi xe, dạng chữ tham khảo

Chi phí tham khảo dạng chữ

Ghi chú

Còn dùng hay không

Thứ tự hiển thị

Một dòng của màn tình trạng đội xe: xe + ODO hiện tại + số bộ phận đang có vấn đề.

Xe

Biển số

Chi nhánh quản lý xe

Tên chi nhánh

Trạng thái vận hành

Trạng thái vận hành để hiển thị

ODO hiện tại; null khi xe chưa có dữ liệu ODO nào

Thời điểm ghi nhận ODO

Thời điểm ghi nhận ODO để hiển thị

Số ngày kể từ lần ghi nhận ODO gần nhất

Nguồn của số ODO: FuelRefill / TruckActivity / LastRefillOdo / None

Tổng số bộ phận đang lắp

Số bộ phận sắp đến hạn

Số bộ phận đã quá hạn

Số bộ phận không tính được vì chuỗi ODO quá cũ

Mức nặng nhất trong các bộ phận của xe; null khi xe không có vấn đề gì

Mức nặng nhất để hiển thị

Tình trạng một bộ phận trên xe — dùng cho lưới bộ phận của hồ sơ xe và cho DriverApp.

Bộ phận

Xe

Biển số

Loại bộ phận

Tên loại bộ phận

Vị trí trên xe

Vị trí để hiển thị

Ngày lắp hiện hành (mốc tính tuổi thọ)

Ngày lắp để hiển thị

ODO lúc lắp

Nguyên bản nhà máy hay đã thay

Nguồn gốc để hiển thị

Tuổi thọ hiệu lực theo km

Tuổi thọ hiệu lực theo tháng

Số km đã dùng; null khi không tính được

Số km còn lại

Số ngày đã dùng

Số ngày còn lại

Hạn theo thời gian

Hạn theo thời gian để hiển thị

Tỷ lệ tiêu hao theo km (%)

Tỷ lệ tiêu hao theo thời gian (%)

Tỷ lệ tiêu hao để hiển thị = lớn hơn trong hai tiêu chí

Mức cảnh báo; null khi bộ phận còn khoẻ

Mức cảnh báo để hiển thị

Ghi chú của engine khi một tiêu chí không tính được

Ngày thay gần nhất; null khi vẫn là nguyên bản nhà máy

Ngày thay gần nhất để hiển thị

Garage của lần thay gần nhất

Một dòng lịch sử của một bộ phận: lần bảo dưỡng nào đã chạm tới nó và làm gì.

Lần bảo dưỡng

Tiêu đề lần bảo dưỡng

Thời điểm bắt đầu

Thời điểm bắt đầu để hiển thị

ODO tại thời điểm bảo dưỡng

Hành động lên bộ phận

Hành động để hiển thị

Chi phí riêng của dòng công việc

Garage — ưu tiên tên trong danh mục, không có thì lấy chuỗi nhập tay của bản ghi cũ

Người thực hiện

Có hoá đơn hay không

Đường dẫn hoá đơn của bản ghi cũ (chỉ đọc, form mới không ghi vào đây)

Hồ sơ tình trạng một xe: thông tin xe + ODO + lưới bộ phận.

Thông tin xe và số liệu tổng hợp

Các bộ phận đang lắp kèm tình trạng

Giá trị ODO gần nhất khi đổ dầu

Danh sách media (ảnh đăng ký, đăng kiểm)

Item hiển thị media xe tải

Rỗng khi bản ghi không có thời điểm kết thúc — cột NOT NULL nên giá trị trống là 01/01/0001, đừng bày ra cho người dùng

Rỗng khi bản ghi chưa hẹn kỳ sau — xem ghi chú ở .

Cũng rỗng khi kỳ sau không muộn hơn lúc bắt đầu: màn ghi nhận gửi StartTime vào ô này khi người dùng bỏ trống (cột NOT NULL nên phải có giá trị), mà "kỳ bảo dưỡng sau đúng bằng lúc đang bảo dưỡng" thì không mang nghĩa gì — hiện ra chỉ làm người vận hành tưởng xe đã tới hạn.

Garage chọn từ danh mục; null với bản ghi cũ nhập garage bằng chuỗi

Chỉ số ODO của xe tại thời điểm bảo dưỡng

Một tệp đính kèm (hoá đơn / ảnh hiện trạng) của một lần bảo dưỡng — thay cho trường chuỗi TruckMaintenance.InvoiceUrl cũ (nợ BD-4). Trường cũ chỉ còn hiển thị, không ghi mới.

Lần bảo dưỡng chứa tệp

Khoá bảng Media dùng chung

URL công khai để hiển thị

Loại tệp: hoá đơn hay ảnh hiện trạng

Tên hiển thị loại tệp

Thứ tự hiển thị

Tệp là PDF (hoá đơn quét) — view dựng icon + tên tệp thay cho thẻ ảnh.

Tính từ tệp đã nằm trên đĩa, không phải từ content-type client khai lúc tải lên.

Tên tệp để hiển thị (chỉ có với PDF; tệp ảnh trả chuỗi rỗng)

Kết quả lưu một lần bảo dưỡng — thêm để màn mới tải hoá đơn lên ngay sau khi tạo. Kế thừa nên chữ ký service không đổi.

Id bản ghi vừa tạo/cập nhật; 0 khi thất bại

Hạng mục theo danh mục cũ; null với dòng chỉ gắn bộ phận

Bộ phận trên xe mà dòng công việc này chạm tới; null với dòng lịch sử

Hành động lên bộ phận

Tên hành động để hiển thị

Chi phí riêng của dòng công việc

Lớp mở rộng cho các phương thức ánh xạ giữa các đối tượng.

Ánh xạ từ đối tượng nguồn sang đối tượng đích.

Loại của đối tượng nguồn. Loại của đối tượng đích. Đối tượng nguồn. Đối tượng đích.

Ánh xạ từ đối tượng nguồn sang đối tượng đích đã tồn tại.

Loại của đối tượng nguồn. Loại của đối tượng đích. Đối tượng nguồn. Đối tượng đích đã tồn tại. Đối tượng đích đã được cập nhật.

Chuyển đổi đối tượng Expense sang ExpenseItem.

Chuyển đổi đối tượng Expense sang ExpenseModel.

Chuyển đổi đối tượng BankAccount sang BankAccountItem.

Chuyển đổi đối tượng BankTransaction sang BankTransactionItem.

Chuyển đổi đối tượng BankStatementImport sang BankStatementImportItem.

Chuyển đổi đối tượng VatInvoice sang VatInvoiceItem.

Chuyển đổi đối tượng VatInvoiceModel sang VatInvoice.

Chuyển đổi đối tượng Agency sang AgencyModel.

Chuyển đổi đối tượng Agency sang AgencyItem.

Chuyển đổi đối tượng AgencyModel sang Agency.

Chuyển đổi danh sách đối tượng Agency sang danh sách AgencyItem.

Chuyển đổi đối tượng Customer sang CustomerModel.

Chuyển đổi đối tượng Customer sang CustomerItem.

Chuyển đổi đối tượng Customer sang CustomerSugItem.

Chuyển đổi đối tượng CustomerModel sang Customer.

Chuyển đổi đối tượng CustomerAddress sang CustomerAddressModel.

Chuyển đổi đối tượng CustomerAddress sang CustomerAddressItem.

Chuyển đổi đối tượng CustomerAddressModel sang CustomerAddress.

Chuyển đổi đối tượng Lead sang LeadModel.

Chuyển đổi đối tượng User sang UserOptionItem.

Chuyển đổi đối tượng User sang StaffItem.

Chuyển đổi đối tượng User sang StaffModel.

Chuyển đổi đối tượng Role sang RoleItem.

Chuyển đổi đối tượng Role sang RoleModel.

Chuyển đổi đối tượng OrderAddressModel sang OrderAddress.

Chuyển đổi đối tượng OrderAddress sang OrderAddressModel.

Chuyển đổi đối tượng OrderAddress sang UpdateOrderAddressModel.

Chuyển đổi đối tượng OrderAddress sang OrderAddressItem.

Chuyển đổi danh sách đối tượng OrderAddress sang danh sách OrderAddressItem.

Chuyển đổi đối tượng OrderPackageModel sang OrderPackage.

Chuyển đổi đối tượng OrderPackage sang OrderPackageModel.

Chuyển đổi đối tượng OrderPackage sang OrderPackageItem.

Chuyển đổi đối tượng OrderPackage sang OrderPackageResponseItem (với chuyển đổi đơn vị).

Chuyển đổi danh sách đối tượng OrderPackage sang danh sách OrderPackageItem.

Chuyển đổi danh sách đối tượng OrderPackage sang danh sách OrderPackageResponseItem.

Chuyển đổi đối tượng OrderTrackModel sang OrderTrack.

Chuyển đổi đối tượng OrderTrack sang OrderTrackItem.

Chuyển đổi danh sách đối tượng OrderTrack sang danh sách OrderTrackItem.

Chuyển đổi đối tượng OrderTimeTrackModel sang OrderTimeTrack.

Chuyển đổi đối tượng OrderFinModel sang OrderFin.

Chuyển đổi đối tượng OrderFin sang OrderFinItem.

Chuyển đổi đối tượng OrderFin sang UpdateOrderFinModel.

Chuyển đổi đối tượng OrderOpsModel sang OrderOps.

Chuyển đổi đối tượng OrderOps sang OrderOpsItem.

Chuyển đổi đối tượng OrderOps sang OpsOrderItem.

Chuyển đổi đối tượng Order sang OrderModel.

Chuyển đổi đối tượng OrderModel sang Order.

Chuyển đổi đối tượng Order sang OrderItem.

Chuyển đổi đối tượng Order sang OpsOrderItem.

Chuyển đổi đối tượng Order sang OrderDetailModel.

Chuyển đổi đối tượng Price sang PriceDetailModel.

Chuyển đổi đối tượng Price sang PriceDetailModel.

Chuyển đổi đối tượng Wallet sang WalletDetailModel.

Chuyển đổi đối tượng TruckModel sang Truck.

Chuyển đổi đối tượng Truck sang TruckModel.

Chuyển đổi đối tượng Truck sang TruckItem.

Chuyển đổi danh sách đối tượng Truck sang danh sách TruckItem.

Chuyển đổi đối tượng TruckActivityModel sang TruckActivity.

Chuyển đổi đối tượng TruckActivity sang TruckActivityItem.

Chuyển đổi danh sách đối tượng TruckActivity sang danh sách TruckActivityItem.

Chuyển đổi đối tượng TruckAsset sang TruckAssetItem.

Chuyển đổi danh sách đối tượng TruckAsset sang danh sách TruckAssetItem.

Chuyển đổi đối tượng TruckAssetModel sang TruckAsset.

Chuyển đổi đối tượng TruckSpecAttributeModel sang TruckSpecAttribute.

Chuyển đổi đối tượng TruckSpecAttribute sang TruckSpecAttributeItem.

Chuyển đổi danh sách đối tượng TruckSpecAttribute sang danh sách TruckSpecAttributeItem.

Chuyển đổi đối tượng GarageModel sang Garage.

Chuyển đổi đối tượng Garage sang GarageItem.

Chuyển đổi danh sách Garage sang danh sách GarageItem.

Chuyển đổi đối tượng TruckComponentTypeModel sang TruckComponentType.

Chuyển đổi đối tượng TruckComponentType sang TruckComponentTypeItem.

Chuyển đổi danh sách TruckComponentType sang danh sách TruckComponentTypeItem.

Chuyển đổi đối tượng TruckMaintAttributeModel sang TruckMaintAttribute.

Chuyển đổi đối tượng TruckMaintAttribute sang TruckMaintAttributeItem.

Chuyển đổi danh sách đối tượng TruckMaintAttribute sang danh sách TruckMaintAttributeItem.

Chuyển đổi đối tượng TruckMaintLinkModel sang TruckMaintLink.

Chuyển đổi đối tượng TruckMaintLink sang TruckMaintLinkItem.

Chuyển đổi danh sách đối tượng TruckMaintLink sang danh sách TruckMaintLinkItem.

Chuyển đổi đối tượng TruckMaintenanceModel sang TruckMaintenance.

Chuyển đổi đối tượng TruckMaintenance sang TruckMaintenanceItem.

Chuyển đổi danh sách đối tượng TruckMaintenance sang danh sách TruckMaintenanceItem.

Chuyển đổi đối tượng TruckSpecificationModel sang TruckSpecification.

Chuyển đổi đối tượng TruckSpecification sang TruckSpecificationItem.

Chuyển đổi danh sách đối tượng TruckSpecification sang danh sách TruckSpecificationItem.

Chuyển đổi Order sang DriverFinOrderModel với logic tùy chỉnh cho userId

Chuyển đổi Order sang DriverFinOrderItem với logic tùy chỉnh cho userId (cho search có phân trang)

Model cập nhật phần cấu hình nội bộ của một tài khoản quảng cáo. Thông tin gốc (tên, tiền tệ, múi giờ) do nền tảng quyết định — chỉ đồng bộ về, không sửa từ LADA.

Có đưa tài khoản này vào các job đồng bộ định kỳ không

Cấp đối tượng được đổi giá thầu hàng loạt.

Nhóm quảng cáo (ad_group.cpc_bid_micros)

Từ khoá (ad_group_criterion.cpc_bid_micros)

Yêu cầu đổi giá thầu hàng loạt cho nhóm quảng cáo hoặc từ khoá. Dùng cho cả bulk-bid/preview và bulk-bid/apply: xem trước và ghi thật phải nhận đúng một hình dạng dữ liệu, nếu không bảng xem trước sẽ không nói về thứ sắp ghi.

Đổi giá thầu của nhóm quảng cáo hay của từ khoá

Id nhóm hoặc Id từ khoá (theo ). Tối đa 500; có Id không tồn tại, đã xoá, hoặc khác nền tảng là từ chối cả lô (plan §3.9).

Phép tính áp lên giá thầu cũ

Giá trị của phép tính: số tiền với Set/IncreaseAmount/DecreaseAmount, phần trăm với IncreasePercent/DecreasePercent. Luôn dương.

Sàn tuỳ chọn — kẹp sau khi tính

Trần tuỳ chọn — kẹp sau khi tính

Giá thầu cũ mà bảng xem trước đã hiện cho từng dòng — hàng rào chống lệch giữa hai bước (sổ nợ N-31). Vấn đề: apply tính lại giá từ giá đang có trong LADA. Người dùng gõ chữ xác nhận cho bảng "5.000 → 6.000 ₫", nhưng nếu giữa hai bước có ai đổi giá — hoặc chính lô đó vừa chạy một lần — thì apply tính từ giá mới và ghi ra con số khác con số đã xác nhận. Bảng xác nhận phải ràng buộc kết quả, không chỉ minh hoạ nó. Bỏ trống (hoặc thiếu dòng nào) = không kiểm dòng đó, giữ nguyên hành vi cũ: preview là nơi dựng ra bảng nên tự nó không có gì để đối chiếu. Giao diện luôn gửi đủ khi apply vì nút ghi chỉ mở sau khi đã xem trước.

Giá thầu cũ của một dòng tại thời điểm xem trước — dùng để phát hiện dữ liệu đã đổi giữa bước xem trước và bước ghi thật.

Id nhóm hoặc Id từ khoá, khớp một phần tử của

Giá thầu cũ đã hiện trên bảng xem trước. null là một giá trị có nghĩa ("đang kế thừa giá thầu nhóm"), không phải "không biết" — dòng đang kế thừa mà lúc ghi đã có giá riêng cũng là một thay đổi phải chặn.

Bảng xem trước có xếp dòng này vào nhóm sẽ đổi được không. Ràng buộc giá cũ thôi chưa đủ (finding review-giai-doan GĐ E). Ca lọt: một nhóm đang SyncStatus != Synced thì bước xem trước xếp là "bỏ qua — chưa đẩy lên nền tảng", nên ô xác nhận nói "muốn đổi giá thầu của 4 dòng" và người dùng gõ chữ cho đúng 4 dòng đó. Nếu giữa hai bước có ai bấm đồng bộ, nhóm thành Synced mà CpcBid không đổi → giá cũ vẫn khớp, hàng rào không thấy gì, và dòng thứ 5 được ghi tiền lên nền tảng mà không để lại dấu hiệu nào trong kết quả. null = client không khai, không kiểm — giữ đúng hợp đồng "không gửi thì không kiểm" của cả . Mặc định false sẽ biến mọi lời gọi cũ thành "bỏ qua sạch cả lô".

Yêu cầu bật / tạm dừng nhiều chiến dịch trong một lượt.

Tối đa 500 Id; có Id không tồn tại hoặc đã xoá là từ chối cả lô (plan §3.9)

Trạng thái đích — chỉ nhận hoặc . Xoá hàng loạt cố ý không đi đường này.

Model tạo / cập nhật chiến dịch nháp trong LADA (chưa đẩy lên nền tảng). Wizard gửi cả cây: chiến dịch → nhóm → mẫu quảng cáo → targeting trong một lần lưu, vì tách nhiều lần lưu sẽ để lại chiến dịch không có nhóm nếu người dùng bỏ giữa đường.

Tài khoản quảng cáo sẽ chạy chiến dịch

Ngân sách theo đơn vị tiền tệ của tài khoản (không phải micros)

Danh sách nhóm quảng cáo

Nhóm quảng cáo trong model chiến dịch.

Id nhóm — Guid.Empty nghĩa là nhóm mới

Giá thầu CPC tối đa theo đơn vị tiền tệ của tài khoản

Các mẫu quảng cáo dùng trong nhóm này

Targeting của nhóm

Targeting của một nhóm quảng cáo.

Từ khoá. Cú pháp giống Google Ads Editor: [chính xác], "khớp cụm", không dấu = khớp cụm (an toàn hơn khớp rộng về chi phí).

Mã vị trí của nền tảng (Google geo target constant id)

Mã ngôn ngữ của nền tảng (Google language constant id)

Model đổi ngân sách của một chiến dịch đã đẩy lên nền tảng.

Ngân sách/ngày mới theo đơn vị tiền tệ của tài khoản

Model tạo mới / cập nhật kết nối nền tảng quảng cáo. Các field mật (ClientSecret, DeveloperToken) nếu gửi lên còn chứa "***" thì service giữ nguyên giá trị đang lưu trong DB.

Tên hiển thị của kết nối

Nền tảng quảng cáo

OAuth Client ID

OAuth Client Secret — SECRET

Developer token (Google Ads, 22 ký tự) — SECRET

ID tài khoản quản lý (login-customer-id, không dấu gạch ngang)

Redirect URI đã đăng ký với nền tảng

Phiên bản API (Google: v25)

Các credential đặc thù nền tảng mà cột chung không cover. Key trùng AdsCredentialField.Key do Capabilities khai báo.

Model tạo mới / cập nhật mẫu quảng cáo. Headline / description nhận dạng mảng, service tự serialize sang JSON của entity.

Nền tảng đích — quyết định giới hạn ký tự khi validate

Nội dung AI Marketing nguồn (để truy vết ngược)

Bài viết CMS nguồn

Yêu cầu tạo mẫu quảng cáo từ một nội dung nguồn.

Nền tảng đích — mặc định Google

URL đích của quảng cáo. Với bài CMS, để trống thì service tự dựng từ slug.

true = lưu luôn thành mẫu trong LADA; false = chỉ trả gợi ý cho wizard hiển thị.

Bỏ qua một lô mục cùng loại việc. EntityType không nhận từ client — suy từ ở máy chủ, để client không thể ghi bản ghi lệch loại.

Id các mục (Guid chiến dịch, int tài khoản / kết nối, mã cố định) — tối đa 500, có Id lạ là từ chối cả lô

Số ngày bỏ qua, bỏ trống = 30 (Q1)

Hiện lại các mục đã bỏ qua. bỏ trống = hiện lại mọi mục còn hạn của loại đó — hành động này chỉ gỡ ẩn, không chạm dữ liệu đồng bộ nên không cần hàng rào Id.

Dữ liệu thêm/sửa một từ khoá trong LADA. Lưu bằng model này KHÔNG gọi ra nền tảng: dòng mới là bản nháp (), dòng đã có trên nền tảng bị sửa thì thành . Muốn nền tảng biết thì phải đi tiếp bước xem trước rồi đẩy — đó là chỗ duy nhất tiêu tiền.

Guid.Empty nghĩa là từ khoá mới

Chiến dịch chứa từ khoá — bắt buộc, kể cả với từ khoá cấp nhóm

Nhóm chứa từ khoá. Bỏ trống (null) nghĩa là từ khoá phủ định cấp chiến dịch. Bỏ trống mà = false là dữ liệu sai — Google không có từ khoá thường ở cấp chiến dịch, service sẽ báo lỗi chứ không tự đổi cấp.

Từ khoá phủ định hay từ khoá nhắm mục tiêu

Nội dung từ khoá, không kèm dấu ngoặc của kiểu khớp

Kiểu khớp

Giá thầu CPC riêng cho từ khoá. Bỏ trống = dùng giá thầu của nhóm. Không áp dụng cho từ khoá phủ định (phủ định không có giá thầu).

Thêm nhiều từ khoá một lần bằng cách dán danh sách — mỗi dòng một từ khoá.

null = phủ định cấp chiến dịch

Kiểu khớp áp cho cả lô

Danh sách nội dung từ khoá. Dòng trắng bị bỏ qua; dòng trùng nhau (sau khi chuẩn hoá) bị gộp lại và báo rõ số lượng đã gộp, không âm thầm bỏ.

Kéo lịch từ nền tảng về cho nhiều chiến dịch — chỉ đọc, không đổi gì trên tài khoản quảng cáo

Tối đa 500 Id; có Id không tồn tại hoặc đã xoá là từ chối cả lô (plan §3.9)

Model áp một mẫu lịch cho nhiều chiến dịch một lượt. Dùng body (không phải query string) vì danh sách id có thể dài tới hàng chục phần tử.

Các chiến dịch cần áp. Có giới hạn số lượng một lô — xem AdsScheduleService.MaxBulkCampaigns. Vượt giới hạn thì báo lỗi, không âm thầm cắt bớt.

Khoá mẫu lịch — xem AdsScheduleTemplates

% chung theo dạng hệ số Google (1.2 = +20%). null = dùng % của mẫu.

false = chỉ lưu nháp trong LADA. true = lưu nháp rồi đẩy lên nền tảng.

true = dry-run: nhờ nền tảng kiểm tra cả lô mà không ghi thật. Chỉ có nghĩa khi bằng true. UI phải chạy dry-run trước rồi mới cho đẩy thật — áp sai lịch cho hàng chục chiến dịch cùng lúc là sự cố tốn tiền, không phải lỗi nhỏ.

Model tạo / cập nhật một khung giờ chạy quảng cáo trong LADA (bản nháp, chưa đẩy lên nền tảng). Lưu ở đây KHÔNG gọi ra nền tảng: dòng được đánh SyncStatus = OutOfSync rồi chờ người dùng bấm "Đẩy lên nền tảng". Tách hai bước là cố ý — sửa lịch là đổi giá thầu, phải xem trước rồi mới ghi.

Id khung giờ — Guid.Empty nghĩa là khung giờ mới

Chiến dịch chứa khung giờ (ad schedule là criterion cấp chiến dịch)

Thứ trong tuần áp dụng khung giờ

Giờ bắt đầu, 0–23

Phút bắt đầu — chỉ nhận 0, 15, 30, 45

Giờ kết thúc, 1–24 (24 = hết ngày)

Phút kết thúc — chỉ nhận 0, 15, 30, 45

Hệ số điều chỉnh giá thầu, lưu **đúng dạng hệ số của Google**: 1.2 = +20%, 0.5 = -50%. Người dùng gõ "+20" thì frontend phải đổi sang 1.2 trước khi gửi. null = không điều chỉnh (Google hiện "—"). Đây là giá trị khác hẳn với 0.

Model DTO để tạo mới hoặc cập nhật AI Provider.

Model DTO để tạo mới hoặc cập nhật Prompt Template.

Model cho tạo mới AppConfig

Model cho cập nhật AppConfig

Model cho search AppConfig

Model kết quả cho AppConfig

Model cho bulk update AppConfig

Model cho cache status

Cấu hình màn hình chặn truy cập bằng điện thoại của app khách hàng (Lada.App). Mỗi thuộc tính tương ứng một khoá trong bảng AppConfig (tiền tố MobileApp.).

Bật chặn truy cập từ điện thoại. Tắt thì app khách chạy bình thường trên mọi thiết bị.

Link tải app trên App Store (iOS).

Link tải app trên CH Play (Android).

Ảnh QR do quản trị tải lên. Có ảnh thì app khách hiển thị đúng ảnh này, bỏ trống thì app tự sinh QR từ .

Link mà mã QR trỏ tới khi app tự sinh QR (thường là trang tải app chung, tự điều hướng sang store theo hệ điều hành). Bỏ trống thì app dùng link Android.

Tiêu đề thông báo trên màn hình chặn.

Nội dung thông báo trên màn hình chặn.

Cho phép khách bấm "Tiếp tục trên trình duyệt" để bỏ qua màn hình chặn. Mặc định tắt — chặn cứng.

Lý do fail

Loại cập nhật fail: lấy hàng, giao hàng

Số lái xe THỰC THU của người gửi khi lấy (Ví bưu cục v2 — E1): chỉ dùng khi bên lấy bật ví và đơn Người gửi trả / Thu 2 đầu; bỏ trống = bằng cước thu người gửi trên đơn; biên 0–150 % cước tạm tính, ngoài biên từ chối lấy. Đơn LADA thuần bỏ qua.

Cân thật từng đơn (gram) đo tại kho — Ví bưu cục v2: dùng chốt cước chính thức khi kho LADA nhập đơn có chi nhánh bật ví tham gia; bắt buộc khi AppConfig FranchiseWallet.InboundWeightRequired bật, thiếu thì chốt theo Σ cân kiện. Đơn LADA thuần bỏ qua.

Cân thật của một đơn lúc nhập kho.

Gram, > 0.

Model xuất kho trung chuyển

Mã người dùng

Trạm kế tiếp

Danh sách đơn hàng

Cập nhật bởi

Cập nhật bởi

Model để cập nhật danh sách location cho agency

ID của đại lý

Danh sách LocationId cần gán cho agency (chỉ phường/xã - Level 3)

ID người cập nhật

Tên người cập nhật

Model cập nhật vùng phủ cho chi nhánh

Mã Agency

Tên chi nhánh

Mô tả

Mã chi nhánh

Đại lý cha

Người đại diện pháp lý (người của đại lý) Nếu là phòng ban của LADA thì giá trị là 0

Tên cán bộ quản lý (để hiển thị frontend)

Trạng thái Agency

Tên doanh nghiệp

Mã số thuế

Địa chỉ công ty / xuất hóa đơn

Id của phường/xã gửi

Id của phường/xã giao

Khoảng cách đầu cuối

Loại cấp hành chính (2 cấp / 3 cấp).

Danh mục cha

1: Tỉnh / thành phố, 2: Quận / huyện, 3: Phường / xã

Phụ phí khu vực (VND) của phường/xã. AreaSurchargeResolver tra trực tiếp cột này để ra phụ phí lấy/giao, nên thiếu trường ở đây là engine luôn tính 0.

Tên danh mục

Mô tả danh mục

Thứ tự hiển thị

Danh mục cha

Là danh mục nổi bật hay không

Loại danh mục

Mã icon Material (VD: "two_wheeler", "kitchen"). Chỉ dùng cho ContentType = GoodsType.

Mã nhánh nội dung cấp 2 (A1, B3, F2...) để kho nội dung AI đăng bài vào đúng danh mục này. Bỏ trống với danh mục không thuộc kế hoạch nội dung.

Model tạo/cập nhật cấu hình tính giá của danh mục hàng hóa (Admin)

FK → Category (ContentType = GoodsType). Mỗi danh mục chỉ có 1 cấu hình.

Cách áp giá thuộc tính vào cước đơn

Ghi chú nội bộ

Danh sách thuộc tính động kèm lựa chọn

Model tạo/cập nhật thuộc tính động của danh mục hàng hóa

Tên hiển thị (VD: "Loại xe")

Mã slug (chỉ chữ thường / số / gạch ngang), không trùng trong cùng cấu hình

Đơn vị đo, chỉ dùng cho NumberRange

Thuộc tính này có phải trục cột của bảng giá riêng theo tuyến không

⚠️ Bật cờ này là đổi cách tính tiền của cả danh mục: danh mục chuyển từ tính theo trọng lượng sang tra ô bảng giá theo (tuyến, danh mục, lựa chọn trục). Cần xác nhận rõ ràng trên UI. Ràng buộc "tối đa 1 trục và phải là chọn một" kiểm ở tầng service bằng .

Lựa chọn / khoảng giá trị kèm giá

Model tạo/cập nhật lựa chọn kèm giá của một thuộc tính

Giá khi chọn lựa chọn này

Trọng lượng quy ước khi chọn lựa chọn này (kg), 0 = không khai. Chỉ điền vào cân của kiện, không tính tiền — xem GoodsAttributeOption.Weight.

Biên dưới (chỉ NumberRange), null = mở biên

Biên trên (chỉ NumberRange), null = mở biên

Ảnh đại diện (WebP)

Ảnh đại diện dạng JPEG cho Open Graph / Social Media sharing

Tiêu đề bài viết

Mô tả ngắn

Nội dung bài viết

Trạng thái bài viết

Trạng thái bài viết

Là bài viết nổi bật hay không

Bưu cục mà bài viết nói về (Agency LadaBranch/Franchise). null = client không gửi → giữ nguyên; 0 = bỏ gắn; > 0 = gắn. Form bài viết trước GĐ B1 chưa có ô này (bẫy DTO nullable, docs/plan-buu-cuc.md §7).

Danh mục bài viết

Một khối nội dung của trang dịch vụ (dùng trong ProductModel.Blocks).

Tiêu đề khối, đồng thời là mục TOC trên trang. Có thể để trống.

JSON theo schema từng loại block — service validate trước khi ghi.

Ảnh đại diện (WebP)

Ảnh đại diện dạng JPEG cho Open Graph / Social Media sharing

Tên dịch vụ

Mô tả ngắn

Là sản phẩm nổi bật hay không?

Table of Content Từ thẻ H3 => H6 Tự sinh trong khi thêm mới / cập nhật bài viết

Tỉnh đi của trang tuyến (Location Level 1 LevelType 2). null = client không gửi → giữ nguyên; 0 = bỏ; > 0 = đặt. Form Dịch vụ trước GĐ B1 chưa có ô này nên không được coi null là "xoá" (bẫy DTO nullable, docs/plan-buu-cuc.md §7).

Tỉnh đến của trang tuyến — cùng quy ước null/0/>0 với .

Các khối nội dung của trang dịch vụ, sắp theo SortOrder. Ghi theo kiểu replace-all như Tags/Categories, NHƯNG phân biệt: null = client không gửi trường này → giữ nguyên blocks hiện có (client cũ chưa biết blocks không được phép xoá dữ liệu); list rỗng = chủ ý xoá hết blocks.

Tên hệ thống

Tiêu đề bài viết

Gets or sets the value indicating whether this topic should be included in footer (column 1)

Gets or sets the value indicating whether this topic should be included in footer (column 1)

Gets or sets the value indicating whether this topic should be included in footer (column 1)

Hiển thị phần dưới cùng footer

Nội dung bài viết

Trạng thái bài viết

Trạng thái xem bài viết

Khối nội dung ĐANG SỬA của topic có bộ khối (xem GET api/Topic/BlockProfile). Null = client không gửi → không đụng khối hiện có; GetById cũng trả null khi topic chưa có khối nào. Gửi danh sách thì cả bộ phải qua luật của bộ khối (vd. đúng 1 Form đăng ký). Topic không có bộ khối mà gửi danh sách khác rỗng → bị từ chối. Lưu cùng topic trong một transaction; sửa khối KHÔNG đổi trang công khai cho tới khi xuất bản.

Chỉ đọc — lần xuất bản khối gần nhất. Client gửi lên cũng bị bỏ qua.

Chỉ đọc — người xuất bản khối gần nhất.

Chỉ đọc — bản đang sửa khác bản đã xuất bản (máy chủ so nội dung, xem PublishedBlocks.SameContent); FE hiện nhãn "Có thay đổi chưa xuất bản". False với topic không có bộ khối.

Chỉ đọc — dấu phiên bản bản đang sửa (PublishedBlocks.Fingerprint). Nút "Xuất bản" gửi lại dấu này; có người lưu khối sau khi mở màn thì máy chủ từ chối thay vì xuất bản thứ người duyệt chưa xem. Null với topic không có bộ khối.

Gets or sets the slug

Tên thực thể và cũng là tên controller luôn

Model để cập nhật thông tin cơ bản của UrlRecord

Id của UrlRecord cần cập nhật

Meta title

Meta description

Meta keywords

Có bao gồm trong sitemap hay không

Độ ưu tiên

Mật độ cập nhật

Dữ liệu form thêm/sửa một luật chuyển hướng URL.

Các DataAnnotations ở đây chỉ chặn cái rẻ tiền — trống, quá dài, mã HTTP lạ. Luật thật (chuẩn hoá đường dẫn, chặn chuyển hướng ra tên miền ngoài, chặn chuỗi và vòng, tắt cờ sitemap) nằm ở tầng service, vì chúng phải đọc chính bảng đó và bảng UrlRecord. Đừng nhân đôi chúng lên đây: hai bản sao sẽ lệch nhau, và bản nào cũng trông như bản đúng.

Khoá; null hoặc 0 nghĩa là thêm mới.

Người thực hiện — controller ghi từ token, form không gửi lên.

Người thực hiện — controller ghi từ token, form không gửi lên.

Trang đăng nhập OAuth (/connect/login) — tài khoản LADA, dùng cho luồng cấp quyền MCP.

Đường dẫn quay lại /connect/authorize?… sau khi đăng nhập — chỉ nhận đường dẫn cục bộ.

Trang đồng ý (/connect/authorize): client nào, user nào, xin quyền gì.

Tên mặt MCP đang xin kết nối ("LADA Express — kho nội dung AI", "LADA Express — số liệu vận hành").

Toàn bộ tham số OAuth của yêu cầu — chép lại thành input ẩn để POST giữ nguyên yêu cầu.

Trang thông báo từ chối / lỗi của luồng OAuth.

Payload tạo token truy cập cá nhân (PAT) cho MCP — quản trị tạo hộ một user (plan §3.4).

User mà token đại diện — không được là Founder, phải có ≥ 1 role ContentStore.*.

Tên gợi nhớ, ≤ 100 ký tự: "Claude Code máy Thắng".

Scope: content:read và/hoặc content:write.

Số ngày hiệu lực, 1..365; bỏ trống = 90.

Kết quả tạo token — chỉ trả về MỘT lần, không lưu và không tra lại được.

Chuỗi token lada_cs_… — sao chép ngay, server chỉ giữ hash.

Lý do thu hồi (tuỳ chọn).

Một token trong danh sách quản trị — không bao giờ chứa chuỗi token hay hash.

16 ký tự đầu để nhận ra token.

Chưa thu hồi và chưa hết hạn.

Kết quả kiểm một chuỗi token lúc xác thực /mcp — service, không phải HTTP.

Lý do từ chối (log server; không trả nguyên văn cho client ngoài 401).

Payload tạo bài nháp 4 phần (đặc tả §5.2 create_article_draft, Phụ lục A) — bản REST PascalCase. Enum nhận cả số lẫn tên (Newtonsoft mặc định). Dự án bật nullable nên [ApiController] coi thuộc tính không có dấu ? là bắt buộc (400 kèm tên trường): trường đặc tả bắt buộc để không-null, trường tuỳ chọn để ?. Service vẫn kiểm hình thức lần nữa (VALIDATION_ERROR) vì MCP (GĐ C) không đi qua MVC.

Mã đề bài, dạng W2-01 (regex ^W[0-9]{1,2}-[0-9]{2}$).

Slug không dấu ^[a-z0-9]+(-[a-z0-9]+)*$, ≤ 200.

Đúng 2 tiêu đề thay thế.

≤ 320; > 155 chỉ cảnh báo mềm.

Thân bài Markdown viết trọn, KHÔNG để ô chờ [[CẦN …]] (cơ chế ô chờ bỏ từ 2026-09-12); ≤ 200 KB. Số chưa có thì viết định tính và ghi khoản còn thiếu vào Brief.DataNeeded.

Bộ ảnh — ≥ 1, đúng 1 ThumbnailOg.

"claude-routine" hoặc tên người.

Phần (a) BRIEF. Khoá lạ giữ trong Extra để không mất dữ liệu trợ lý gửi thêm.

≥ 2 link ngang hàng.

Số liệu bài cần mà trợ lý không tra được — mỗi khoản một dòng, nói rõ chờ ai chốt. Đây là chỗ thay cho ô chờ [[CẦN …]] đã bỏ; danh sách này hiện ở tab Brief của màn duyệt để người duyệt biết phải hỏi ai.

Chỉ bài BranchNews — điều kiện đăng §3.3d(4) đọc Address/Phone/OpeningHours.

Feature/CaseStudy — điều kiện đăng §3.3d(5).

Một cặp câu hỏi/trả lời FAQ — tách riêng để xuất FAQPage.

Chân trang bài — hai dòng hồ sơ tác giả/người kiểm tra nằm ở đây (Phụ lục C đặc tả).

Dòng chân trang không khớp nhãn nào khi nhập từ file .md — giữ lại để không mất chữ của người viết. Null khi không có (không serialize thừa).

Một dòng bộ ảnh (đặc tả §4.6) — prompt, chưa phải file.

1 = ảnh đại diện; duy nhất trong bài.

Slug H2 mà ảnh minh hoạ; null với thumbnail.

Bắt buộc khi Decision = None.

E1, E2a… ^[A-E][1-6][a-d]?$

"A" brand kit (mặc định) · "B" nền trơn.

null = không chữ.

Phần (d) phiếu tự chấm — cấu trúc bắt buộc đặc tả §4.7. Khoá Sections giữ nguyên "A_facts"… vì là dữ liệu, không phải tên thuộc tính.

Đúng 3 việc người duyệt phải sửa.

Output của create_article_draft (đặc tả §5.2).

Khoá = tên enum ContentImageDecision: AiPrompt, ManualCanva, RealPhoto, None — luôn đủ 4 khoá.

Bài đầy đủ trả về cho GetById / GetByTopicCode: 4 phần đã parse JSON + ảnh.

Ảnh tham chiếu thương hiệu đang bật — thứ người tạo ảnh phải đính kèm khi chạy prompt làn A. Kèm sẵn trong chi tiết bài để màn ảnh không phải gọi thêm một lượt nữa.

Output của render_article.

"html" | "markdown".

Thân bài (+ FAQ nối cuối) ở định dạng yêu cầu.

Payload lưu một phiên bản khối STYLE BASE / DO NOT.

0 = tạo mới.

Mã phiên bản, khớp ContentImage.StyleBaseVersion (ví dụ "laneA-2026-08-29").

"A" hoặc "B".

Khối STYLE BASE — bắt buộc, đây là lý do tồn tại của bản ghi.

Bản mặc định của làn. Bật bản này thì bản mặc định cũ của cùng làn tự tắt.

Payload lưu một khuôn ảnh.

Payload lưu một ảnh tham chiếu thương hiệu.

Đường dẫn ảnh đã tải lên qua PictureController — bắt buộc.

"A", "B" hoặc để trống nếu dùng cho mọi làn.

Bài xuất bản ra Post ở trạng thái nào (plan §7.11 — Q6 chốt 2026-09-06).

Mặc định: Post vào hàng chờ, người trong CMS cũ bấm đăng như mọi bài khác.

Đăng thẳng lên website. Đòi role Post.Publish ở tầng service, không phải ở giao diện: MCP và PAT cũng đi qua đúng hàm này.

Yêu cầu xuất bản một bài sang CMS.

Mặc định (§7.11).

Mặc định TRUE, và đó là chủ ý. GĐ E đã cắn đúng lỗi ngược lại: một đường "xem trước" mặc định an toàn mà vẫn ghi thật (spec §13.8). Ở đây hậu quả lớn hơn hẳn — ghi nhầm là một bài rác trên website đang phục vụ khách. Người gọi muốn ghi thật phải nói ra.

Danh mục CMS. Bỏ trống thì lấy ContentArticle.CmsCategoryId, vẫn trống thì tra danh mục mang đúng mã nhánh nội dung của bài (Category.ContentCategoryCode = CategoryL2), cuối cùng mới tới AppConfig ContentStore.DefaultCategoryId (§7.10).

Kết quả một lượt xuất bản — cùng một hình dạng cho lượt soát thử và lượt ghi thật.

true = chưa ghi một dòng nào.

Slug bài — cũng là đường dẫn công khai /{slug}.

Id Post vừa tạo; null ở lượt soát thử.

Vì sao ra danh mục đó: "chọn trên bài", "khớp mã nhánh nội dung \"A2\"", hay "AppConfig ContentStore.DefaultCategoryId". Người duyệt đọc dòng này ở lượt soát thử để biết bài sắp rơi vào danh mục mặc định hay vào đúng nhánh của nó — hai chuyện trông giống hệt nhau nếu chỉ nhìn tên danh mục.

Tên tag sẽ ghi (soát thử) hoặc đã ghi (thật) vào PostTag, theo đúng thứ tự: từ khoá chính trước, từ khoá phụ sau. Đã chuẩn hoá chữ thường như TagService của CMS.

Mốc đăng, luôn ghi ở +07:00 tường minh (§4.7 câu 3).

Số ảnh thật sự được chèn vào thân bài (đã duyệt và có file).

HTML cuối cùng sẽ ghi vào Post.Description — trả cả ở lượt ghi thật để đối chiếu.

Mục lục sinh từ H3 ở máy chủ, sẽ ghi vào Post.TOC.

Bài duyệt bằng cờ PublishWithoutImages nên lên website không có ảnh đại diện.

Số lần sanitizer phải cắt. Khác 0 ở một bài bình thường là dấu hiệu đáng xem lại.

Việc sẽ ghi (soát thử) hoặc đã ghi (thật), theo đúng thứ tự. Đây là thứ người bấm đọc để biết lượt này chạm vào những bảng nào của CMS.

Yêu cầu đồng bộ lại ảnh của một bài đã xuất bản sang bài viết CMS của nó.

Đường sửa sau, cho đúng một tình huống: bài đã đăng rồi mới thấy ảnh không sang cùng (ảnh nộp muộn, hoặc ảnh rơi vì luật lọc cũ đòi Approved). Không tạo Post mới, không đụng slug, danh mục, FAQ hay trạng thái bài.

Mặc định TRUE, cùng lý do với : đây cũng là đường ghi ra website.

Kết quả một lượt đồng bộ lại ảnh — cùng hình dạng cho soát thử và ghi thật.

Bài viết CMS đang được sửa.

true = chưa ghi một dòng nào.

Bài không có ảnh đại diện dùng được — Post.Thumbnail giữ nguyên giá trị đang có.

Ảnh đại diện / OG của Post khác với ảnh trong kho ⇒ lượt này ghi lại.

Thân bài dựng lại khác thân bài đang nằm trong Post ⇒ lượt này ghi lại.

Post.Description không còn khớp bản do kho sinh ra — ai đó đã sửa bài trong CMS. Khi cờ này bật, lượt đồng bộ không đụng thân bài (chỉ ảnh đại diện), để không xoá công sửa tay.

Số ảnh chèn được vào thân bài dựng lại.

HTML thân bài sẽ ghi (hoặc đã ghi). Rỗng khi lượt này không đụng thân bài.

Việc sẽ ghi (soát thử) hoặc đã ghi (thật), theo đúng thứ tự.

Một danh mục CMS chọn được cho bài — đủ để dựng ô chọn ở màn đăng, không hơn.

Danh mục sẽ dùng nếu người bấm không chọn gì (ContentStore.DefaultCategoryId).

Mã nhánh nội dung gắn cho danh mục này (A1, B3, F2…), null nếu chưa gắn. Ô chọn ở màn đăng in nó cạnh tên để người bấm thấy ngay danh mục nào ứng với nhánh của bài — và thấy cả danh mục nào còn chưa ai gắn mã.

Kết quả một lượt chạy job đồng bộ trạng thái đăng.

Số bài có PostId và Post.Status = Published nhưng bài còn ở Approved.

Payload update_article (đặc tả §5.2). Mọi trường trong đều tuỳ chọn: null = không đụng tới, có giá trị = thay cả trường (không hợp nhất từng phần tử mảng).

Một trong hai: Id bài hoặc mã đề. Gửi cả hai thì Id thắng.

Số phiên bản người sửa đang cầm; lệch bản hiện tại → 409 VERSION_CONFLICT.

Ghi chú thay đổi, vào ContentArticleVersion.ChangeNote.

Các trường sửa được của bài — trùng danh sách đặc tả §5.2 patch.

Kết quả sửa bài: bản mới sau khi lưu.

Số phiên bản mới (= bản cũ + 1).

Payload set_article_status (đặc tả §5.2).

Lý do — bắt buộc khi chuyển sang Tạm giữ / Từ chối / Chờ dữ liệu.

Payload duyệt đăng (§3.3d) — đường ghi RIÊNG, gác bằng ContentStore.Approve thay vì ContentStore.Edit của . Ba trường ghi đè là quyết định của người duyệt, chỉ lưu khi bài thật sự qua đủ 8 điều kiện: gửi cờ mà bài còn thiếu điều kiện khác thì máy chủ trả 422 và không ghi gì.

Đăng khi bộ ảnh chưa duyệt xong (§3.3d(6)) — bật thì bắt buộc.

Vì sao chấp nhận đăng thiếu ảnh — vào cột cùng tên, hiện lại trên màn duyệt.

Ghi chú bỏ qua ngưỡng điểm tự chấm (§3.3d(8)) — có ghi chú thì điểm dưới 80 vẫn duyệt được.

Ghi chú duyệt, vào ContentArticle.StatusReason.

Payload rút lại bài đã duyệt (Approved → PendingReview) — cũng cần ContentStore.Approve.

Lý do rút lại — bắt buộc, để lịch sử nói được vì sao bài rời khỏi hàng chờ đăng.

Payload update_topic_status (đặc tả §5.1) — Drafted bắt buộc kèm ArticleId.

Kết quả check_slug (đặc tả §5.3).

Slug trống gần nhất dạng slug-2; null khi slug đang trống hoặc thử 20 lần đều bận.

Ai đang giữ slug: "ContentArticle #12" hoặc "UrlRecord" (kể cả bản xoá mềm của CMS).

Giải thích cho người đọc khi slug sai định dạng hoặc không gợi ý được.

Hồ sơ tác giả — dữ liệu E-E-A-T đứng tên trên bài, không nhất thiết là tài khoản hệ thống. Điều kiện đăng §3.3d(2) đòi không rỗng nên đây là trường phải nhập.

0 = tạo mới.

Tài khoản người dùng tương ứng, nếu người này có tài khoản.

Tham số list_people (đặc tả §5.3).

Lọc theo chức danh, so khớp chứa chuỗi không phân biệt hoa thường.

Mặc định chỉ người còn hoạt động.

Mặc định 50, tối đa 200.

Gán tác giả / người kiểm tra cho một bài.

Payload append_run_log (đặc tả §5.1).

Điểm tự chấm từng bài trong lượt — trung bình tính ở server.

DI SẢN — tổng số ô chờ theo loại. Cơ chế ô chờ bỏ từ 2026-09-12, trường này chỉ còn để đọc lại nhật ký những lượt chạy cũ; lượt mới bỏ trống.

Kết quả nhập một lượt: mỗi file một dòng, thành công hay không đều có dòng.

Đề bài được tạo mới trong lượt này (file có mã đề chưa có trong hàng đợi).

Một file trong lượt nhập.

Mã lỗi khi thất bại (mã của parser hoặc của CreateDraft).

Vi phạm cứng kèm dòng — người sửa file đọc thẳng danh sách này.

Gợi ý slug khi slug trùng — người nhập tự quyết, server không đổi im lặng.

Bản sao gọn của ContentStoreIssue để trả trong kết quả nhập (giữ nguyên vị trí).

Cập nhật một dòng ảnh sau khi nộp file (đặc tả §5.3 set_image_status). Mỗi trường null = không đụng tới. Chỉ chạm bốn cột kết quả — mọi thông số ảnh (khuôn, làn, prompt, kích thước) vẫn thuộc update_article.

URL ảnh đã tải lên (từ PictureController).

URL bản JPEG cho OG — chỉ ảnh ThumbnailOg mới có.

Ghi chú kiểm ảnh, vào ContentImage.QaChecklistJson dạng { "note": "..." }.

Kết quả kiểm điều kiện đăng (§3.3d) — CHỈ ĐỌC ở GĐ D: màn chi tiết hiện danh sách còn thiếu, không có nút duyệt. GĐ E nối đúng lớp kiểm này vào set_article_status(Approved).

Không còn điều kiện nào thiếu (không có nghĩa là đã duyệt — duyệt là GĐ E).

Đủ 7 điều kiện §3.3d theo thứ tự, mỗi điều kiện đạt hay không kèm lý do.

Chỉ những điều kiện chưa đạt — để giao diện hiện nhanh.

Một điều kiện đăng.

Mã cố định để giao diện gắn hành động: AUTHOR_PROFILE, CHECKER, BRANCH_INFO, SUBJECT_CONSENT, IMAGES, CONTENT_GATE, SELF_SCORE.

Câu nói rõ thiếu gì khi chưa đạt; rỗng khi đạt.

Tham số nhập cả thư mục — đường dẫn đưa qua tham số, không hard-code trong code.

Đường dẫn tuyệt đối tới thư mục chứa file .md trên máy chạy API.

Chỉ đọc, không ghi gì — để soát trước khi nhập thật.

Một đề bài trong payload create_topics (đặc tả §5.1).

W2-03 — ^W[0-9]{1,2}-[0-9]{2}$.

Bỏ trống thì suy từ TopicCode (W2-03 → 2).

A2, B2, F1… ^[A-F][0-9]$ — CategoryL1 suy từ ký tự đầu.

Bỏ trống thì xếp sau đề cuối cùng đang có.

Tuỳ chọn — dấu ? để [ApiController] không coi là bắt buộc (dự án bật nullable).

Tham số list_topics (đặc tả §5.1): trả theo SortOrder tăng dần.

Mã L2 loại trừ, ví dụ ["F2"] khi F2 chưa mở bán.

Mặc định 20, tối đa 100.

Kết quả tạo hàng loạt: đề hợp lệ được tạo, đề trùng mã / sai định dạng bị từ chối từng dòng.

Yêu cầu đăng ký client động (RFC 7591) tới POST /connect/register — Claude.ai / Cowork / ChatGPT gửi khi người dùng thêm connector. Tên trường theo RFC, không theo quy ước PascalCase của REST.

Phản hồi 201 của đăng ký client động (RFC 7591 §3.2.1).

Lỗi 400 theo RFC 7591 §3.2.2: invalid_redirect_uri hoặc invalid_client_metadata.

Model chứa thông tin gán người quản lý hàng loạt cho khách hàng.

CallLog Model - DTO cho tạo/cập nhật cuộc gọi

Call number - mỗi cuộc gọi có một số, nội bộ của 3CX

Call ID - định danh duy nhất của cuộc gọi

Thời gian cuộc gọi

Thời gian bắt đầu cuộc gọi

Thời gian trả lời

Thời gian kết thúc cuộc gọi

Lý do cuộc gọi bị chấm dứt

Số điện thoại nguồn

Số điện thoại đích

Distinguished name của người gọi

Distinguished name của đích

Số được quay

Lý do thay đổi trong cuộc gọi

Số cuối cùng

Distinguished name của số cuối cùng

Mã thanh toán

Tỷ lệ thanh toán

Chi phí của cuộc gọi

Tên tỷ lệ của biến thể thanh toán

Tất cả các điểm cuối tham gia vào cuộc gọi

Loại nguồn

Loại đích

Loại đích cuối cùng

Tên hiển thị nguồn

Tên hiển thị đích

Tên hiển thị đích cuối cùng

Danh sách các agent hàng đợi

Loại cuộc gọi

Trạng thái Lead

Nội dung trạng thái

Đối tượng đại diện cho thông tin địa chỉ của khách hàng.

Địa chỉ.

Địa chỉ đầy đủ.

Id của tỉnh/thành phố.

Id của quận/huyện.

Id của phường/xã.

Số điện thoại liên hệ.

Tên người liên hệ.

Latitude của địa chỉ.

Longitude của địa chỉ.

Loại địa chỉ.

Ghi chú.

Id của khách hàng.

Model tạo/cập nhật tài khoản ngân hàng khách hàng

ID (0 nếu tạo mới)

ID khách hàng

Số tài khoản

Tên chủ tài khoản

Mã ngân hàng

Tên ngân hàng

Tên chi nhánh

Địa chỉ chi nhánh

Có phải tài khoản mặc định

Ghi chú

Người cập nhật (sẽ được set từ controller)

Tên người cập nhật (sẽ được set từ controller)

Validate model

Model thao tác xử lý khiếu nại phía nhân viên (tiếp nhận / phản hồi / giải quyết).

Phản hồi của nhân viên cho khách (bắt buộc khi phản hồi; khi giải quyết phải có sẵn hoặc truyền kèm)

Model duyệt/từ chối yêu cầu đổi nhân viên phụ trách.

Nhân viên phụ trách mới (bắt buộc khi duyệt, bỏ qua khi từ chối)

Ghi chú khi duyệt/từ chối (bắt buộc khi từ chối để khách biết lý do)

Họ và tên

Số điện thoại

Địa chỉ

Địa chỉ email

Liên hệ zalo

Liên hệ zalo

Khách có bảng giá riêng. Bật → engine tra bảng giá riêng trước, thiếu thì mượn bảng mặc định (QĐ-2). Tắt → luôn dùng bảng mặc định.

Cờ này cũng bỏ phụ phí khu vực — xem AreaSurchargeResolver.cs:77. Đó là chủ ý đã chốt: khách có bảng giá riêng đã tính trọn phí vận chuyển trong giá, phụ phí khu vực là phần dư. Ai "sửa" hành vi này sẽ thu khách hai lần.

Lớp dùng để cập nhật từng thông tin của khách hàng

Loại thông tin cần cập nhật

Giá trị cần cập nhật

Thông tin đặt lại mật khẩu cho tài khoản đăng nhập của khách hàng.

Id của KHÁCH HÀNG (không phải Id người dùng). Backend tự tra ra tài khoản đăng nhập gắn với khách hàng này — nhờ vậy quyền Customer.SetPassword không thể dùng để đổi mật khẩu của nhân viên hay quản trị.

Mật khẩu mới.

Họ và tên

Số điện thoại

Thông tin cần hỗ trợ

Đường dẫn gửi

Thông tin tạo tài khoản đăng nhập cho một khách hàng đã có hồ sơ.

Id của khách hàng cần tạo tài khoản.

Tên đăng nhập.

Mật khẩu.

Xác nhận mật khẩu.

Thông tin cập nhật định vị (toạ độ) cho một địa chỉ trong sổ địa chỉ khách hàng. Tách khỏi vì đây là thao tác riêng: chỉ ghi Lat/Long, KHÔNG đụng tới tỉnh/phường nên không ảnh hưởng tới cước hay bưu cục dự kiến của các đơn dùng địa chỉ này. Cùng dạng với UpdateOrderAddressCoordModel của địa chỉ đơn hàng.

Id của địa chỉ khách hàng.

Vĩ độ. Để null (cả Lat và Long) nghĩa là xoá định vị đang có.

Kinh độ. Để null (cả Lat và Long) nghĩa là xoá định vị đang có.

Model thông tin xuất hóa đơn VAT (dùng cho cả tạo mới và cập nhật)

ID khách hàng

Tên công ty/cá nhân

Mã số thuế

Email nhận hóa đơn

Địa chỉ

Người liên hệ

Điện thoại

Ghi chú

Có phải mặc định không

Thông tin chấm công hiện tại (nếu đã check-in nhưng chưa check-out)

Đã check-in hôm nay chưa

Đã check-out hôm nay chưa

Thời gian check-in hôm nay (nếu có)

Thời gian check-out hôm nay (nếu có)

ODO khi check-in hôm nay

ODO khi check-out hôm nay

Thông tin xe đang phụ trách (nếu có)

Có đang phụ trách xe nào không

Biển số xe đang phụ trách

Tên đại lý của xe đang phụ trách

ODO gần nhất của xe đang phụ trách

Model cập nhật trạng thái lấy hàng cho Driver App

ID đại lý

Danh sách media (ảnh, video)

Số lái xe THỰC THU của người gửi khi lấy (Ví bưu cục v2 — E1): chỉ dùng khi bên lấy bật ví và đơn Người gửi trả / Thu 2 đầu; null = bằng cước thu người gửi trên đơn (app chưa có ô nhập — GĐ E); biên 0–150 % cước tạm tính, ngoài biên từ chối lấy.

Model cập nhật trạng thái giao hàng cho Driver App

ID đại lý

Danh sách media (ảnh, video)

Model cập nhật trạng thái trả hàng thành công cho Driver App

ID đại lý

Danh sách media (ảnh, video) minh chứng trả hàng

Model cập nhật trạng thái thất bại cho Driver App

Lý do thất bại

Loại cập nhật thất bại: lấy hàng, giao hàng

Danh sách media (ảnh, video) minh chứng thất bại (không bắt buộc)

Enum loại thất bại cho Driver App

Lấy hàng thất bại

Giao hàng thất bại

Trả hàng thất bại

Model chứa thông tin tài chính của lái xe

Tổng số tiền cước lấy hàng (SourceFee) lái xe đang cầm

Tổng số tiền cước giao hàng (DestFee) lái xe đang cầm

Tổng số tiền thu hộ (COD) lái xe đang cầm

Tổng số tiền lái xe đang cầm (SourceFee + DestFee + CollectAmount)

Ví bưu cục v2 (V-40): tiền lái xe bưu cục nhượng quyền bật ví THU HÔM NAY (giờ VN) trên đơn Ví ghi — nộp cho bưu cục, KHÔNG nộp LADA, nên không nằm trong các tổng trên. Chỉ hôm nay vì stage đơn Ví ghi không bao giờ rời "Lái xe đang cầm". App hiện băng khi > 0.

Số đơn Ví ghi lái xe thu tiền hôm nay (đi cùng ).

Có phiếu chuyển tiền đang chờ duyệt không

Thông tin phiếu đang chờ duyệt (nếu có)

Danh sách 10 đơn gần đây nhất mà lái xe đang cầm tiền

Model chứa thông tin đơn hàng mà lái xe đang cầm tiền

ID của đơn hàng

Mã đơn hàng

Số tiền cước lấy hàng (SourceFee) của đơn này

Số tiền cước giao hàng (DestFee) của đơn này

Số tiền thu hộ (COD) của đơn này

Tổng số tiền của đơn này

Ngày tạo đơn hàng

Ghi chú

Model sắp xếp thứ tự đơn hàng

Danh sách thứ tự đơn hàng mới

Item sắp xếp thứ tự đơn hàng (OrderId + vị trí mới)

ID đơn hàng (OrderOps Id)

Thứ tự hiển thị mới

Yêu cầu tải giọng đọc cho một loạt câu chỉ dẫn (POST api/Tts/Batch).

Các câu cần đọc, ĐÃ chuẩn hoá ở app (plan §3.5.5), theo thứ tự cần trước → cần sau. Tối đa Tts:MaxTextsPerBatch câu, mỗi câu tối đa Tts:MaxTextLength ký tự.

Hash những câu app ĐÃ có file trên máy — server vẫn trả dòng kết quả cho câu đó nhưng không gửi lại bytes âm thanh. Không bắt buộc.

Kết quả POST api/Tts/Batch.

Result == Success: mọi câu hợp lệ đã có âm thanh — trừ câu bị nguồn từ chối riêng lẻ (ErrorCode = "Rejected") hoặc đang chờ nguồn tự host sinh nền ("Pending"); hai loại đó vẫn tính là Success, app bỏ câu im lặng. Result == Failed kèm khi lỗi ở tầng nguồn/hạn mức: app chuyển nút loa sang lỗi, nhưng các dòng đã Ready vẫn dùng được.

Mã lỗi cấp lượt gọi, rỗng khi không lỗi. Một trong .

Nhận diện giọng đang dùng — đổi giọng/engine/nguồn trên server thì chuỗi này đổi, app bỏ các file giọng cũ thay vì trộn hai giọng.

Kết quả từng câu, cùng thứ tự với .

Kết quả của một câu.

Câu đã chuẩn hoá khoảng trắng — chính chuỗi được đọc.

Khoá cache (sha256 hex) — app lưu file theo khoá này.

Đã có âm thanh ở server.

Bytes âm thanh (JSON: base64). null khi chưa sẵn sàng hoặc khi hash nằm trong .

Mã lỗi riêng câu này khi chưa sẵn sàng, rỗng khi sẵn sàng.

Mã lỗi của gateway giọng đọc — app rẽ nhánh theo mã, không theo câu chữ.

Yêu cầu sai: cả lượt (số câu ngoài 1…60 → HTTP 400) hoặc RIÊNG một câu (rỗng, quá dài, ký tự cấm → dòng đó mang mã này, các câu khác vẫn xử lý).

Server chưa có khoá nguồn giọng (VieNeu Cloud hoặc sidecar tự host), hoặc khoá bị từ chối.

Hết token / gói hết hạn (VieNeu Cloud 403).

Nguồn giới hạn tần suất hoặc hạn mức ngày (429), hoặc hàng đợi sidecar đầy.

Nguồn lỗi hoặc không kết nối được.

Nguồn quá thời gian chờ.

Vượt trần ký tự câu mới trong ngày (của người dùng hoặc toàn server).

Nguồn từ chối riêng câu này.

Câu chưa có ở nguồn tự host, đã xếp hàng sinh nền (RTF ≈ 2, không sinh lúc xe chạy). Chỉ ở cấp CÂU, không bao giờ làm cả lượt thất bại. Đã kiểm code app 2026-09-28: dòng không Ready bị bỏ qua im lặng, không vào Have nên tự được hỏi lại ở lượt sau — app không cần sửa.

Ảnh chụp trạng thái gateway giọng đọc cho người vận hành (GET api/Tts/Status): nguồn đang có hiệu lực, năm khoá AppConfig đã nạp (khoá bí mật che), kết quả thăm dò sidecar và một lượt tổng hợp thử qua đúng đường app đi. Có vì backend production chỉ ghi log ra console (IIS không giữ) — không có endpoint này thì "app không tải được giọng" không biết hỏng ở tầng nào (đợt tự host 2026-09-28).

Tên lớp engine đang có hiệu lực: VieNeuCloudEngine hay VieNeuSelfHostEngine.

Engine có khoá/địa chỉ để gọi được không. false = app sẽ nhận NotConfigured.

Khoá cache của nguồn (thành phần hash) — đổi giọng/phiên bản/nguồn là đổi.

Nhận diện giọng app nhận về — khác giá trị app đang giữ là app bỏ chỉ mục cũ.

Giá trị AppConfig theo khoá (khoá bí mật che, chỉ còn độ dài và 4 ký tự đầu); trống = chưa có / rơi về appsettings.

Giá trị đang dùng sau khi hợp nhất AppConfig + appsettings (khoá che).

Thư mục cache mp3 của backend (Tts:CacheDir hoặc {ContentRoot}/App_Data/tts-cache).

Tiến trình tạo được thư mục và ghi/xoá được một file thử trong đó. false = mọi câu có âm thanh sẽ Unavailable.

Lỗi khi thử ghi (loại ngoại lệ + thông điệp), rỗng khi ghi được.

Số file âm thanh đang có trong cache (đếm tới 100.000).

Kết quả GET {BaseUrl}/health của sidecar (chỉ khi nguồn tự host): mã HTTP + thân cắt ngắn, hoặc lỗi kết nối.

Kết quả lượt tổng hợp thử qua TtsCacheService với một câu cố định.

Một lượt thử BatchAsync với câu .

Câu thử — đoạn cố định sidecar sinh sẵn nên bình thường phải Ready.

Success / Failed của lượt.

Mã lỗi cấp lượt, rỗng khi không lỗi.

Mã lỗi riêng câu thử (ví dụ Pending), rỗng khi sẵn sàng.

Câu thử đã có âm thanh.

Số byte âm thanh trả về (0 khi chưa sẵn sàng hoặc app đã có).

Thời gian lượt thử, mili giây.

Thông điệp của gateway (câu chữ cho người vận hành).

Model tài khoản gửi email (dùng cho cả tạo mới và cập nhật). Lưu ý: và khi CẬP NHẬT để trống nghĩa là GIỮ NGUYÊN giá trị (đã mã hóa) cũ — chỉ ghi đè khi nhập giá trị mới.

Tên gợi nhớ (VD: "SES chính - Singapore").

Loại nhà cung cấp: SMTP / SES / Mock.

Mật khẩu SMTP (giá trị thô mới nhập; để trống khi sửa = giữ nguyên).

Secret key SES (giá trị thô mới nhập; để trống khi sửa = giữ nguyên).

Tài khoản gửi mặc định (chỉ 1 tài khoản mặc định).

Thứ tự ưu tiên fallback (nhỏ hơn = thử trước).

Đang bật để dùng hay không.

Model yêu cầu gửi email thử để kiểm tra cấu hình một tài khoản.

ID tài khoản gửi cần kiểm tra.

Email người nhận thử.

Model để tạo mới báo lỗi

URL trang web xảy ra lỗi

Nội dung mô tả lỗi

Tên người báo lỗi (nếu không đăng nhập)

Email người báo lỗi

Số điện thoại người báo lỗi

Thông tin trình duyệt

Thông tin thiết bị

Danh sách hình ảnh lỗi

Model để cập nhật báo lỗi (dành cho admin)

ID báo lỗi

Trạng thái xử lý báo lỗi

Ghi chú từ admin khi xử lý

Model để điều chỉnh số dư ví (cân ví)

Số dư mong muốn

Lý do điều chỉnh

Model cho tài khoản ngân hàng

Tên tài khoản ngân hàng

Số tài khoản

ID thông tin ngân hàng

Người quản lý tài khoản

Có tự động cập nhật số dư không

Tài khoản có thể thu hộ COD (tài khoản nhận cước)

Model chi tiết tài khoản ngân hàng

Tên ngân hàng

Mã ngân hàng

Tên người quản lý

Họ tên người quản lý

Ngày cập nhật số dư cuối cùng

Ngày giao dịch cuối cùng

Số lượng giao dịch

Số dư hiện tại

Tổng tiền vào trong tháng

Tổng tiền ra trong tháng

Model cho import sao kê ngân hàng

ID tài khoản ngân hàng

File Excel sao kê

Có ghi đè dữ liệu trùng lặp không

Ngày bắt đầu lọc dữ liệu (optional)

Ngày kết thúc lọc dữ liệu (optional)

Có tự động phân loại giao dịch không

Có cập nhật số dư tài khoản không

Kết quả import sao kê ngân hàng

ID import

Tổng số dòng

Số dòng xử lý thành công

Số dòng lỗi

Số dòng bỏ qua

Số dòng trùng lặp

Danh sách thông báo lỗi

Danh sách cảnh báo

Danh sách giao dịch đã import

Thời gian xử lý (milliseconds)

Số dư tài khoản sau khi import

Ngày giao dịch đầu tiên

Ngày giao dịch cuối cùng

Model tìm kiếm import sao kê

Từ khóa tìm kiếm

ID tài khoản ngân hàng

Mã ngân hàng

Trạng thái import

Ngày import từ

Ngày import đến

Người thực hiện import

Kết quả parse file sao kê

Có thành công không

Thông báo lỗi chính

Danh sách thông báo lỗi chi tiết

Tổng số dòng

Số dòng xử lý thành công

Số dòng lỗi

Danh sách giao dịch đã parse

Model cho giao dịch ngân hàng

ID tài khoản ngân hàng

Mã giao dịch từ ngân hàng

Ngày giao dịch

Số tiền ghi có (tiền vào)

Số tiền ghi nợ (tiền ra)

Số dư sau giao dịch

Nội dung giao dịch

Thời gian giao dịch chi tiết

Trạng thái xử lý

Loại giao dịch

Mã tham chiếu

Tên người gửi/nhận

Số tài khoản người gửi/nhận

Ngân hàng của người gửi/nhận

Ghi chú xử lý

Model tìm kiếm giao dịch ngân hàng

Từ khóa tìm kiếm

ID tài khoản ngân hàng

Mã giao dịch

Ngày giao dịch từ

Ngày giao dịch đến

Số tiền từ

Số tiền đến

Loại giao dịch (Credit/Debit)

Trạng thái xử lý

Loại giao dịch

ID import

Model hủy đối soát

ID đối soát cần hủy

Lý do hủy đối soát

Ghi chú bổ sung

Người hủy (sẽ được set từ controller)

Tên người hủy (sẽ được set từ controller)

Thời gian hủy (sẽ được set từ service)

Có tạo OrderTrack không (mặc định true)

Có gửi thông báo không (mặc định false)

Validate model

Danh sách lỗi validation

Model để kiểm tra giá cước

Phường / xã nguồn

Phường / xã đích

Khoảng cách

Trọng lượng (Kg)

Danh mục hàng hóa khách chọn (Category có ContentType = GoodsType). Null = không phân loại, giữ nguyên cách báo giá cũ.

Lựa chọn thuộc tính hàng hóa. Client chỉ gửi lựa chọn, giá luôn resolve từ DB.

Các loại hàng của đơn, mỗi món một dòng. Rỗng = đơn một loại hàng ⇒ dùng / / như trước.

Gửi danh sách này thì ba trường trên không còn được dùng để tra cước — xem OrderFeeCalculationRequest.GoodsLines.

Một loại hàng trong lần báo giá: loại hàng + trọng lượng tính cước + lựa chọn thuộc tính của nó.

Loại hàng của món. null / 0 = không khai ⇒ backend điền loại mặc định cho riêng món này.

Trọng lượng tính cước của món, đơn vị Kg — giống , controller quy đổi sang gram khi dựng request.

Lựa chọn thuộc tính hàng hóa của riêng món này.

Tên hàng hóa — chỉ để ghi vào căn cứ dòng phí, không tham gia phép tính.

Model sao chép bảng giá từ một phạm vi nguồn sang phạm vi đích.

Chặn copy chéo hình dạng: bảng giá chung là tuyến × khoảng trọng lượng, bảng loại hàng là tuyến × lựa chọn trục — khác hình dạng, không nhân bản được. Nên SourceGoodsCategoryId và TargetGoodsCategoryId phải cùng null hoặc cùng có giá trị (hai loại hàng khác nhau thì ok, miễn đều là bảng loại hàng). ⚠️ Đừng nhầm với InitGoodsCategoryPriceMatrix — chức năng đó sinh mới bằng tích Descartes routes × options với Value = BaseValue * factor. Chức năng này copy dòng Price thật từ phạm vi nguồn.

Khách nguồn. 0 = khách mặc định.

Loại hàng nguồn. null = bảng giá chung theo cân.

Khách đích. 0 = khách mặc định.

Loại hàng đích. null = bảng giá chung theo cân.

Loại giá (FixPrice / StepPrice / …).

true = đè ô đã có ở đích. Mặc định false — bỏ qua ô đã tồn tại, không đè im lặng.

Tỷ lệ điều chỉnh giá, tính theo phần trăm. null = copy nguyên giá. 10 = tăng 10%. -5 = giảm 5%.

Model tạo đối soát mới

ID khách hàng

Từ ngày

Đến ngày

Danh sách ID đơn hàng được chọn để đối soát

Ghi chú đối soát

Số tài khoản ngân hàng

Tên chủ tài khoản

Mã ngân hàng

Tên ngân hàng

Tên chi nhánh ngân hàng

Địa chỉ chi nhánh ngân hàng

Thông tin chuyển khoản bổ sung

Tự động xác nhận sau khi tạo

Loại phiếu đối soát

ID thông tin xuất hóa đơn VAT (tùy chọn)

Người tạo (sẽ được set từ controller)

Tên người tạo (sẽ được set từ controller)

Validate model

Model tạo phiếu chuyển tiền lái xe

Ghi chú

Ảnh chuyển khoản (1 file required)

Model từ chối phiếu chuyển tiền

ID phiếu

Lý do từ chối

ID của chi phí

Trạng thái chi phí

Lý do từ chối (nếu có)

Ghi chú

Mô tả chi phí

Ghi chú cho chi phí

Số tiền chi phí

Danh mục chi phí

Tên danh mục chi phí (chỉ đọc)

Trạng thái chi phí (chỉ đọc - được set tự động)

Phương thức thanh toán

UserId của người duyệt (chỉ đọc - được lấy từ ExpenseCategory)

Lý do từ chối (nếu có)

ID tài khoản ngân hàng nhận tiền

Thông tin tài khoản ngân hàng (chỉ đọc)

Model tạo/cập nhật kỳ sao kê thẻ xăng

Model thanh toán kỳ sao kê (xác nhận đã thanh toán)

Model tạo/cập nhật hợp đồng vay xe

Danh sách xe trong hợp đồng (tạo/sửa)

Các giai đoạn lãi suất (nếu rỗng → dùng InterestRate cố định)

Model xác nhận thanh toán kỳ trả góp

Model khởi tạo dư nợ hiện tại cho thẻ xăng dầu

Dư nợ hiện tại (lấy từ sao kê ngân hàng)

Ngày bắt đầu theo dõi (các giao dịch từ ngày này sẽ được gom vào kỳ mới)

Model tạo/cập nhật tất toán khoản vay

Model khoản phí tất toán

Model xác nhận thanh toán 1 khoản phí tất toán

Payload ghi MA TRẬN giá theo loại hàng: tuyến (hàng) × lựa chọn thuộc tính trục (cột).

Vì sao không nhồi vào . Bảng giá chung có hình dạng tuyến × khoảng trọng lượng nên PriceDetailModel mang MinWeight/MaxWeight và không có chỗ cho GoodsCategoryId / OptionId. Hai bảng khác hình dạng, không nhân bản được cho nhau. Thêm field tuỳ chọn vào DTO cũ nghĩa là mọi nơi đọc nó phải tự đoán đang cầm bảng nào — đúng loại nhập nhằng đã sinh ra nợ PSVC ở đường bảng giá chung. Xoá là cờ tường minh, không phải phép trừ. Đường bảng giá chung suy ra "dòng cần xoá" bằng đang có trong DB − có trong payload, tức giả định payload luôn chứa đủ mọi dòng người dùng nhìn thấy. Giả định đó vỡ là mất dữ liệu im lặng. Ở đây ô nào cần xoá thì phải mang = true; ô vắng mặt là ô KHÔNG ĐỤNG TỚI. Nhờ vậy lưu từng phần ma trận (từng tuyến, hoặc client đang lọc) an toàn theo thiết kế. Xem PriceMatrixRule.

Danh mục hàng hóa của bảng giá này. Bắt buộc > 0 — null/0 là bảng giá CHUNG, thuộc đường , không đi qua đây.

Khách sở hữu bảng giá. 0 = khách mặc định — client cũ không gửi nên giữ hành vi cũ.

Loại giá áp cho các ô trong lô này. Ô ma trận bình thường là .

Các ô giá cần tạo / sửa / xoá mềm trong lần lưu này.

Rỗng = không có gì để lưu, KHÔNG phải "xoá sạch bảng giá". Muốn xoá cả bảng thì dùng endpoint xoá bảng giá riêng của danh mục — thao tác đó đưa danh mục về tính theo trọng lượng nên phải nhìn thấy rõ trên URL, không được là hệ quả phụ của một lần gửi payload rỗng.

Một ô của ma trận giá theo loại hàng.

Id ô giá trong DB. 0 = ô mới chưa lưu.

Tuyến — HÀNG của ma trận.

Lựa chọn của thuộc tính trục (GoodsAttributeOption.Id) — CỘT của ma trận.

Giá của ô. 0 hợp lệ và có nghĩa: ô đã khởi tạo nhưng chưa khai giá.

Bước trọng lượng, chỉ có nghĩa với .

Ô ma trận thường là FixPrice nên để 0. Với dòng bước giá, 0 là một DivideByZeroException nằm sẵn trên đường tiền — PriceMatrixRule.ValidateStepWeight chặn đúng chỗ đó, và chỉ chặn ở nhánh có phép chia.

Đánh dấu xoá mềm ô này.

⚠️ Xoá ô CUỐI CÙNG của một danh mục làm cả danh mục rơi khỏi nhánh bảng giá riêng về nhánh tính theo trọng lượng — engine chọn trục bằng EXISTS(Price WHERE GoodsCategoryId = C AND IsDeleted = 0). Đơn vẫn ra tiền, chỉ là sai giá, không lỗi nào bay lên. Service trả cảnh báo trong BaseResult.Message để UI hỏi lại người bấm.

Payload khởi tạo ma trận giá cho một danh mục chưa có bảng giá riêng.

Không phải "sao chép bảng mặc định". Bảng chung là tuyến × khoảng trọng lượng, bảng riêng là tuyến × option trục — khác hình dạng nên không nhân bản được. Ở đây sinh đủ ô rỗng theo option của thuộc tính trục, cho phép nhập một giá gốc + hệ số theo từng option để đỡ nhập tay. ⚠️ Đây là thao tác đổi cách tính tiền của cả danh mục: ô giá đầu tiên xuất hiện là danh mục chuyển từ nhánh trọng lượng sang nhánh bảng giá riêng ngay lập tức, mọi đơn sau đó tra bảng mới.

Danh mục hàng hóa cần khởi tạo bảng giá riêng.

Khách sở hữu bảng giá sẽ sinh ra. 0 = khách mặc định — client cũ không gửi nên giữ hành vi cũ.

Giá gốc dùng cho mọi ô trước khi nhân hệ số. Để 0 thì sinh ma trận rỗng (mọi ô giá 0).

Hệ số riêng theo từng option trục, nhân với .

Option không khai hệ số thì lấy hệ số 1. Danh sách rỗng = mọi option cùng giá gốc.

Chỉ khởi tạo cho các tuyến này. Rỗng = mọi tuyến đang có.

Hệ số giá của một option trục khi khởi tạo ma trận.

Lựa chọn của thuộc tính trục.

Hệ số nhân với giá gốc.

ID của doanh thu

Trạng thái doanh thu

Lý do từ chối (nếu có)

Ghi chú

Mô tả doanh thu

Ghi chú cho doanh thu

Số tiền doanh thu

Danh mục doanh thu

Tên danh mục doanh thu (chỉ đọc)

Trạng thái doanh thu (chỉ đọc - được set tự động)

UserId của người duyệt (chỉ đọc - được lấy từ IncomeCategory)

Lý do từ chối (nếu có)

Loại hàng của bảng giá. null = bảng giá CHUNG theo khoảng trọng lượng.

Trường THÊM VÀO khi tổng quát hoá bảng giá v2: cùng với và nó tạo thành bộ ba định danh phạm vi bảng giá. ⚠️ Client cũ không gửi trường này ⇒ nhận null ⇒ đúng bảng giá chung, tức y hệt hành vi trước đây. Đừng đổi mặc định thành một danh mục nào đó: đường lưu suy ra "dòng cần xoá" bằng phép trừ trong phạm vi, nên phạm vi sai là xoá mềm dữ liệu của phạm vi khác — đúng hình dạng của nợ PSVC.

Khối lượng nhỏ nhất

Khối lượng lớn nhất

Giá trị

Loại giá

Model chi tiết đối soát

ID đối soát

Mã đối soát

Thông tin khách hàng

Từ ngày

Đến ngày

Ngày chuyển tiền

Tổng tiền COD

Tổng phí trừ

Số tiền thực chuyển

Số lượng đơn hàng

Trạng thái

Trạng thái dạng string

Loại phiếu đối soát

Loại phiếu đối soát dạng string

ID thông tin xuất hóa đơn VAT

Thông tin xuất hóa đơn VAT

Thông tin tài khoản ngân hàng

Người tạo

Ngày tạo

Người phê duyệt

Người chuyển tiền

Ghi chú

Thông tin chuyển khoản

Danh sách đơn hàng trong đối soát

Có thể chỉnh sửa không

Có thể xác nhận không

Có thể chuyển tiền không

Có thể hủy không

Thông tin tài khoản ngân hàng trong đối soát

Số tài khoản

Tên chủ tài khoản

Mã ngân hàng

Tên ngân hàng

Tên chi nhánh

Địa chỉ chi nhánh

Thông tin hiển thị đầy đủ

Model filter cho tìm kiếm đối soát

Từ khóa tìm kiếm (mã đối soát, tên khách hàng)

ID khách hàng

Trạng thái đối soát

Từ ngày tạo

Đến ngày tạo

Từ ngày chuyển tiền

Đến ngày chuyển tiền

Số tiền từ

Số tiền đến

Người tạo

Người phê duyệt

Người chuyển tiền

Tên tuyến

Mô tả tuyến

Khoảng cách tối thiểu

Khoảng cách tối đa

Thứ tự hiển thị

Mô tả giao dịch

Ghi chú cho giao dịch

Số tiền giao dịch

Số tiền mặt

Số tiền chuyển khoản

Loại giao dịch

Hướng giao dịch

Ngày giao dịch

ID ví nguồn

ID ví đích (nullable)

Danh mục chi phí (nullable)

Danh sách đơn hàng liên kết

ID đơn hàng

Số tiền COD

Cước nguồn

Cước đích

Model thực hiện chuyển tiền đối soát

ID đối soát

Phương thức chuyển tiền

Ghi chú chuyển tiền

Thông tin bổ sung (JSON hoặc text)

Có tạo giao dịch tự động không

Có gửi thông báo cho khách hàng không

Người thực hiện (sẽ được set từ controller)

Tên người thực hiện (sẽ được set từ controller)

Validate model

Phương thức chuyển tiền

Model yêu cầu chuyển tiền giữa 2 ví Ví nguồn sẽ được lấy tự động từ người dùng đang đăng nhập

ID ví đích (ví nhận tiền)

Số tiền cần chuyển

Ghi chú cho giao dịch

Request ID để đảm bảo idempotency (tránh chuyển tiền trùng khi retry) Nếu không truyền, hệ thống sẽ tự tạo

Người thực hiện giao dịch

Username người thực hiện giao dịch

File ảnh chứng từ giao dịch chuyển tiền (bắt buộc)

ID ví

Số dư

Trạng thái ví

Id chủ sở hữu

Tên đăng nhập chủ sở hữu

Họ và tên chủ sở hữu

Người dùng hiện tại có được phép cân ví hay không (chỉ Founder)

Model để duyệt hóa đơn thanh toán chuyển khoản

ID hóa đơn cần duyệt

Ghi chú khi duyệt

Thông tin chuyển khoản (nội dung chuyển khoản, mã giao dịch, v.v.)

ID người duyệt

Tên người duyệt

Model cho CRUD operations của Bank

Mã ngân hàng

Tên đầy đủ ngân hàng

Tên thương hiệu

Thứ tự hiển thị

Model hủy hóa đơn thanh toán chuyển khoản

ID hóa đơn cần hủy

Lý do hủy hóa đơn

Ghi chú bổ sung

Người hủy (sẽ được set từ controller)

Tên người hủy (sẽ được set từ controller)

Thời gian hủy (sẽ được set từ controller)

Có tạo OrderTrack không (mặc định true)

Có gửi thông báo không (mặc định false)

Validate model

Danh sách lỗi validation

Model để tạo hóa đơn thanh toán chuyển khoản

ID khách hàng

Danh sách ID đơn hàng

File ảnh chứng từ chuyển khoản (bắt buộc, đúng 1 ảnh)

Ghi chú

Nội dung chuyển khoản

Model xuất Excel phiếu đối soát khách hàng

Tên file Excel (không bao gồm extension)

Danh sách ID phiếu đối soát cần xuất

Ngày bắt đầu (để filter)

Ngày kết thúc (để filter)

ID khách hàng (để filter)

Trạng thái phiếu đối soát (để filter)

Loại phiếu đối soát (để filter)

Có bao gồm chi tiết đơn hàng không

Có bao gồm thông tin duyệt/hoàn thành không

Có bao gồm ghi chú không

Đường dẫn thư mục lưu file (tùy chọn)

Validate model

Danh sách lỗi validation

Model tạo phiếu đối soát

ID khách hàng

Danh sách ID đơn hàng được chọn

Ghi chú nội bộ

File ảnh chứng từ (bắt buộc cho phiếu âm - khách chuyển khoản cho công ty)

Số tài khoản ngân hàng

Tên chủ tài khoản

Mã ngân hàng (VCB, TCB, VTB, etc.)

Tên ngân hàng

Tên chi nhánh ngân hàng

Địa chỉ chi nhánh ngân hàng

Model từ chối phiếu

Model hoàn thành phiếu (xác nhận thanh toán)

Ảnh chứng từ (nếu có)

Ghi chú thêm

Model xuất Excel danh sách đơn hàng nợ cước của khách hàng

ID khách hàng

Tên file Excel (không bao gồm extension)

Có bao gồm thông tin khách hàng không

Có bao gồm thông tin địa chỉ không

Có bao gồm thông tin trạng thái không

Có bao gồm thông tin tài chính không

Đường dẫn thư mục lưu file (tùy chọn)

Validate model

Model chứa thông tin khách hàng và danh sách đơn hàng có thể tạo hóa đơn thanh toán

Thông tin khách hàng

Danh sách đơn hàng có thể tạo hóa đơn thanh toán

Tổng số đơn hàng

Tổng tiền TransferFee

Model thông tin khách hàng

ID khách hàng

Tên khách hàng

Số điện thoại khách hàng

Email khách hàng

Địa chỉ khách hàng

Username khách hàng

Model cho việc tạo/cập nhật danh mục chi phí

Tên danh mục chi phí

Mã danh mục chi phí chuẩn hóa theo TT133

Mô tả danh mục chi phí

Thứ tự hiển thị

ID của danh mục cha (null nếu là danh mục gốc)

ID người duyệt

Tên người duyệt

Mã tài khoản

Model đầu vào cho việc xuất Excel thông tin đơn hàng

Danh sách ID đơn hàng cần xuất

Danh sách mã đơn hàng cần xuất

Tên file Excel (không bao gồm extension)

Đường dẫn thư mục lưu file (tùy chọn)

Có bao gồm thông tin hàng hóa chi tiết không

Có bao gồm thông tin địa chỉ chi tiết không

Có bao gồm thông tin tài chính chi tiết không

Có bao gồm thông tin thời gian chi tiết không

Model cho việc tạo/cập nhật danh mục doanh thu

Tên danh mục doanh thu

Mô tả danh mục doanh thu

Thứ tự hiển thị

ID của danh mục cha (null nếu là danh mục gốc)

ID người duyệt

Tên người duyệt

Request model cho báo cáo thu chi

Ngày bắt đầu

Ngày kết thúc

Model xuất Excel phiếu đối soát

Tên file Excel (không bao gồm extension)

Danh sách ID phiếu đối soát cần xuất

Ngày bắt đầu (để filter)

Ngày kết thúc (để filter)

ID khách hàng (để filter)

Trạng thái phiếu đối soát (để filter)

Có bao gồm chi tiết đơn hàng không

Có bao gồm thông tin chuyển khoản không

Có bao gồm ghi chú không

Đường dẫn thư mục lưu file (tùy chọn)

Validate model

Danh sách lỗi validation

Model tạo hóa đơn thuế

ID phiếu đối soát

ID thông tin VAT

Ghi chú

Model cập nhật trạng thái hóa đơn thuế

ID hóa đơn thuế

Trạng thái mới (2=Draft, 3=Issued)

Số hóa đơn (bắt buộc khi status = Draft hoặc Issued)

Ngày xuất hóa đơn (bắt buộc khi status = Draft hoặc Issued)

File PDF hóa đơn (bắt buộc khi hóa đơn chưa có file; nếu đã có thì bỏ trống để giữ file cũ)

Model chi tiết hóa đơn thanh toán chuyển khoản

Mã hóa đơn

ID khách hàng

Tên khách hàng

Số điện thoại khách hàng

Email khách hàng

Địa chỉ khách hàng

Tổng tiền TransferFee

Tổng tiền TransferFee (formatted)

Số đơn hàng

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

Tên trạng thái hóa đơn

Mức độ ưu tiên

Tên mức độ ưu tiên

Số tài khoản ngân hàng công ty/đại lý

Tên chủ tài khoản công ty/đại lý

Mã ngân hàng công ty/đại lý

Tên ngân hàng công ty/đại lý

Tên chi nhánh ngân hàng công ty/đại lý

Địa chỉ chi nhánh ngân hàng công ty/đại lý

Ghi chú

Thông tin chuyển khoản

Người duyệt hóa đơn

Tên người duyệt

Ngày duyệt

ID giao dịch liên kết

Danh sách đơn hàng trong hóa đơn

ID media chứng từ chuyển khoản

URL hình ảnh chứng từ chuyển khoản

Có thể chỉnh sửa không (chỉ người tạo và trạng thái Draft)

Có thể hủy không (chỉ người tạo và trạng thái Draft)

Có thể duyệt không (role Accountant và trạng thái Draft)

Model xuất Excel phiếu chuyển khoản

Tên file Excel (không bao gồm extension)

Danh sách ID phiếu chuyển khoản cần xuất

Ngày bắt đầu (để filter)

Ngày kết thúc (để filter)

ID khách hàng (để filter)

Trạng thái phiếu chuyển khoản (để filter)

Có bao gồm chi tiết đơn hàng không

Có bao gồm thông tin duyệt không

Có bao gồm ghi chú không

Đường dẫn thư mục lưu file (tùy chọn)

Validate model

Danh sách lỗi validation

Model cho tài khoản ngân hàng người dùng

ID người dùng

Số tài khoản

Tên chủ tài khoản

ID ngân hàng

Có phải tài khoản mặc định không

Ghi chú

Model để tạo/cập nhật hóa đơn VAT (nếu cần edit thủ công)

Request model cho tìm kiếm hóa đơn VAT

Từ khóa tìm kiếm (số hóa đơn, tên người bán/mua)

Từ ngày

Đến ngày

MST người bán

MST người mua

Tình trạng hóa đơn

Model cho lái xe xác nhận nhận thẻ xăng dầu

ID bản ghi bàn giao

Ghi chú

Ảnh minh chứng

Model cho lái xe trả thẻ xăng dầu

ID thẻ xăng dầu

Ghi chú

Ảnh minh chứng

ID người phụ trách thẻ (nullable)

Model import lịch sử giao dịch thẻ xăng dầu từ Excel. File Excel phải có cột "Tài khoản thẻ/ Số thẻ" để hệ thống ánh xạ với thẻ tương ứng.

File Excel chứa lịch sử giao dịch

ID thẻ xăng dầu (khi import từ trang chi tiết thẻ). Nếu có, hệ thống sẽ gán tất cả giao dịch cho thẻ này thay vì tìm từ cột trong Excel.

Có ghi đè giao dịch trùng không (optional, default: false)

Lọc theo ngày bắt đầu (optional)

Lọc theo ngày kết thúc (optional)

Model import sao kê thẻ tín dụng xăng dầu từ Excel

ID thẻ xăng dầu

File Excel sao kê

Kỳ sao kê từ ngày (optional)

Kỳ sao kê đến ngày (optional)

Model cập nhật giao dịch thẻ tín dụng xăng dầu

ID giao dịch (GUID)

Số tiền gốc (có thể âm)

Loại giao dịch

Địa điểm giao dịch

Ghi chú

Model tạo phiếu thanh toán tiền dầu khoán cho lái xe

ID lái xe được thanh toán

Số lít được thanh toán

Đơn giá dầu tại thời điểm thanh toán (VND/lít)

Ngày thanh toán

Phương thức thanh toán (Tiền mặt, Chuyển khoản...)

Mã tham chiếu thanh toán

Ghi chú

Trạng thái (Pending, Approved, Paid, Cancelled)

Model yêu cầu duyệt phiếu đổ dầu

ID phiếu đổ dầu

ID giao dịch thẻ xăng để đối soát (bắt buộc khi phiếu đổ bằng thẻ)

ODO đổ dầu gần nhất (admin có thể điều chỉnh khi duyệt)

ODO hiện tại (admin có thể điều chỉnh khi duyệt)

Model đổ dầu - Lái xe gửi thông tin đổ dầu với hình ảnh

ID xe tải (tự động lấy từ xe hiện tại của lái xe)

ID thẻ xăng dầu (nullable - có thể trả tiền mặt)

ID lái xe thực hiện đổ dầu (nullable - mặc định là người dùng hiện tại)

ID giao dịch thẻ tín dụng cần đối soát (nullable) Nếu có, hệ thống sẽ tự động liên kết giao dịch với lần đổ dầu

ODO hiện tại khi đổ dầu

ODO trước đó (bắt buộc)

Số tiền đổ dầu

Đơn giá dầu (VND/lít)

Phương thức thanh toán

Tên cây xăng

Địa chỉ cây xăng

Thời gian đổ dầu

Ghi chú

Danh sách hình ảnh (ODO trước, ODO sau, cây dầu, hóa đơn)

Loại hình ảnh tương ứng (OdoBeforePhoto, OdoAfterPhoto, FuelPumpPhoto, FuelReceiptPhoto) Phải tương ứng 1-1 với Files

Danh sách ID của media hiện có cần giữ lại khi update Dùng để tối ưu: chỉ upload ảnh mới, giữ lại ảnh cũ VD: [1, 2, 0, 4] nghĩa là giữ media ID 1,2,4 và upload ảnh mới cho vị trí thứ 3

Model yêu cầu từ chối phiếu đổ dầu

ID phiếu đổ dầu

Lý do từ chối

Model cập nhật thông tin đổ dầu

ID bản ghi đổ dầu cần cập nhật

ID xe tải

ID thẻ xăng dầu (nullable - có thể trả tiền mặt)

ID lái xe thực hiện đổ dầu

ODO hiện tại khi đổ dầu

ODO trước đó (bắt buộc)

Số tiền đổ dầu

Đơn giá dầu (VND/lít)

Số lít đổ thực tế

Tên trạm xăng

Địa chỉ trạm xăng

Thời gian đổ dầu

Ghi chú

Model để tạo và cập nhật ứng viên

Họ và tên

Số điện thoại

Năm sinh

Địa chỉ hiện tại

Giới thiệu về bản thân

Trạng thái hồ sơ

Tên trạng thái (chỉ đọc)

Nội dung đánh dấu trạng thái

Thời gian hẹn phỏng vấn

Ghi chú

ID vị trí tuyển dụng

Nguồn ứng viên

Tên nguồn ứng viên (chỉ đọc)

ID người phụ trách tuyển hồ sơ này — để trống nếu ứng viên tự nộp và chưa ai nhận. Là căn cứ đếm của chỉ số KPI "Số ứng viên onboard".

Tên người phụ trách tuyển (chỉ đọc, service tra theo )

Thời điểm hồ sơ chuyển sang trạng thái nhận việc (chỉ đọc, hệ thống tự đóng dấu)

File CV để upload (chỉ sử dụng khi tạo/cập nhật)

Tên file CV gốc

Đường dẫn lưu trữ CV trong hệ thống (chỉ đọc)

Kích thước file CV (bytes) (chỉ đọc)

Kích thước file CV hiển thị (chỉ đọc)

Loại file CV (pdf, doc, docx, jpg, png, etc.) (chỉ đọc)

URL để truy cập CV (chỉ đọc)

Thời gian upload CV (chỉ đọc)

Thời gian upload CV hiển thị (chỉ đọc)

Có CV hay không (chỉ đọc)

Format kích thước file để hiển thị

Kích thước tính bằng bytes Chuỗi hiển thị kích thước file

ID người phụ trách tuyển hồ sơ này — để trống nghĩa là chưa ai nhận.

Đặt ở đây (màn đánh giá hồ sơ) vì đó là chỗ nhân sự thao tác trên hồ sơ đã tồn tại; màn tạo mới chỉ gán được lúc tạo. Thiếu đường này thì hồ sơ ứng viên tự nộp không bao giờ gán được người tuyển và chỉ số hr.onboard-count mất số (plan §7.6).

Tên người phụ trách tuyển (chỉ đọc)

Số ODO hiện tại của xe (bắt buộc, >= 0)

Model tạo phiếu tạm ứng lương

Model hoàn cọc trách nhiệm

Model tạo/cập nhật Bảng đánh giá lái xe

Model điểm từng tiêu chí

Chế độ lương — bắt buộc khi tạo/cập nhật cấu hình

% hoa hồng từ doanh số cấp dưới (TeamLeader / BranchManager). Mặc định 2%.

Ảnh đại diện (WebP)

Ảnh đại diện dạng JPEG cho Open Graph / Social Media sharing

Tên công việc / chức danh

Mô tả công việc

Yêu cầu kinh nghiệm (ví dụ: 2 năm c++)

Địa chỉ làm việc

Loại hình công việc

Mức lương tối thiểu

Mức lương tối đa

Phòng ban

Vị trí ứng tuyển

Ngày bắt đầu

Ngày kết thúc

Email tiếp nhận CV

Trạng thái tin tuyển dụng: mở / đóng

Model tạo phiếu nghỉ phép

Model duyệt / từ chối phiếu nghỉ phép

Model cấu hình loại nghỉ phép

Model cấu hình ngày lễ

Model điều chỉnh quỹ phép nhân viên

Mô hình chấm công thủ công (admin bổ sung khi nhân viên/lái xe quên chấm vào/ra). Giờ vào và giờ ra tách biệt, có thể bổ sung độc lập. ODO tùy chọn.

Id bản ghi chấm công. Null = tạo mới; có giá trị = cập nhật/bổ sung.

Id nhân viên được chấm công.

Thời gian chấm vào (FE ghép ngày + giờ). Tùy chọn khi bổ sung.

Thời gian chấm ra (FE ghép ngày + giờ). Tùy chọn khi bổ sung.

Số ODO khi chấm vào (tùy chọn).

Số ODO khi chấm ra (tùy chọn).

Mô hình chấm ra thủ công (admin bổ sung giờ ra cho bản ghi chưa có chấm ra), cho phép upload ảnh ODO bù. Dùng multipart/form-data.

Id bản ghi chấm công cần bổ sung giờ ra.

Thời gian chấm ra (FE ghép ngày + giờ, hỗ trợ ca qua đêm).

Số ODO khi chấm ra (tùy chọn).

Ảnh ODO bù khi chấm ra (tùy chọn, nhiều ảnh).

Model lập phiếu lương

Nếu có Id → UPDATE phiếu lương đã tồn tại; null → CREATE mới

Danh sách User IDs cần lập phiếu (hoặc null = tất cả)

Tháng lập phiếu

Năm lập phiếu

Số ngày Lễ trong tháng (KT nhập tay)

Công thực tế nhập tay (override dữ liệu chấm công). Nếu null → tự tính từ bảng Attendance.

Thưởng chuyên cần (KT nhập tay, chỉ Office)

Thưởng hiệu suất (KT nhập tay, chỉ Office)

Số kíp vượt công nhập tay (override tự tính từ chấm công). Nếu null → tự tính từ bảng Attendance.

Các khoản trừ khác (KT nhập tay khi lập phiếu lương). Loại: Fixed (VNĐ) hoặc Percentage (% GrossIncome trước thuế)

Model NLĐ xác nhận/từ chối phiếu lương

0 = Fixed (VNĐ), 1 = Percentage (% Gross)

Nếu Fixed = số tiền; nếu Percentage = % (VD: 5.0)

Một dòng đối tượng gửi lên (plan §3.3).

Theo : Permission.Id / Agency.Id / giá trị AgencyType / User.Id; bỏ trống khi Tất cả.

Chỉ có nghĩa với Phòng ban / bưu cục: gồm cả đơn vị con.

Thông tin một bài (tạo khi = 0, sửa khi > 0). GHI ĐÈ TOÀN BỘ: giao diện gửi đủ mọi trường; trường ngày để null nghĩa là bỏ trống (bẫy "không gửi" ≡ "muốn xoá", plan §7). Riêng : null = giữ nguyên đối tượng đang có, mảng rỗng = bỏ hết; và : null = giữ nguyên phạm vi đang có. Có hiệu lực ngay khi lưu kể cả với bài đã đăng; nội dung khối thì chỉ đổi khi "Đăng lại" (plan §6.3).

Chỉ nhân viên LADA / Gồm cả bưu cục nhượng quyền (plan §6.6). null = giữ nguyên (bài mới: Chỉ nhân viên LADA). Người mức đơn vị bị ép phạm vi (§5 câu 12c) thì máy chủ bỏ qua giá trị này. Gửi lại đúng phạm vi đang có KHÔNG tính là đổi (máy chủ so giá trị) — chỉ đổi thật mới huỷ lịch của bài đang hẹn giờ.

Bộ khối của bản đang sửa — thay cả bộ, thứ tự theo SortOrder.

Đăng ngay / hẹn giờ / đăng lại.

Mốc tương lai = hẹn giờ (chỉ bài chưa đăng); bỏ trống hoặc đã qua = đăng ngay.

"Báo lại cho mọi người" khi Đăng lại — mặc định không gửi chuông lần hai (plan §6.3).

Dấu bản đang sửa người đăng đã xem (DraftVersion); khác = có người lưu sau đó → từ chối.

Ước tính người nhận cho đối tượng đang chọn (chưa cần lưu bài).

Phạm vi đang chọn trên form; null = Chỉ nhân viên LADA (hoặc phạm vi bị ép).

Tên Permission Group

Mô tả Permission Group

Permission có đang hoạt động không

Danh sách Role IDs (chỉ dùng cho việc hiển thị, không dùng cho CreateOrUpdate)

Danh sách Role IDs mới

Model chuyển cả bộ chỉ tiêu của một chủ thể trong một kỳ sang trạng thái Assigned (§7.8) — chặn cứng khi tổng trọng số ≠ 100%

Loại chủ thể

User.Id hoặc Agency.Id theo SubjectKind

Năm của kỳ

Tháng của kỳ (1-12)

Model copy bộ chỉ tiêu của một chủ thể từ kỳ trước sang kỳ mới (trạng thái Draft) — bỏ qua metric đã có chỉ tiêu ở kỳ đích

Loại chủ thể

User.Id hoặc Agency.Id theo SubjectKind

Năm kỳ nguồn

Tháng kỳ nguồn (1-12)

Năm kỳ đích

Tháng kỳ đích (1-12)

Model giao/sửa một dòng chỉ tiêu KPI (kỳ tháng)

Chỉ số được giao (KpiMetric.Id)

Loại chủ thể

User.Id hoặc Agency.Id theo SubjectKind

Năm của kỳ

Tháng của kỳ (1-12)

Giá trị mục tiêu — phải > 0

Trọng số %, thuộc (0, 100]

Trần % hoàn thành khi tính điểm

Ghi chú

Đầu vào tạo/sửa mẫu bậc thang thưởng KPI (§7.5, §7.14).

Bậc gửi trọn bộ mỗi lần lưu (bám cách EmployeeSalaryConfigService xử lý SalesCommissionTier): service xoá bậc cũ rồi ghi lại theo danh sách này.

Một bậc của mẫu: điểm trong [MinScore, MaxScore) ⇒ tiền

Null = "trở lên" (bậc cuối)

Đầu vào tạo/sửa dòng cấu hình thưởng của MỘT nhân viên trong MỘT tháng (§7.14).

Nguồn điểm: bản thân (Employee) hay bưu cục/khu vực phụ trách (Agency)

Bỏ trống khi nguồn điểm là bản thân — service tự điền bằng

Gán hàng loạt dòng cấu hình cho một kỳ — idempotent, dùng cho màn quản trị GĐ F (§7.14).

Hai kiểu dùng: (a) / để sao chép cấu hình của một tháng trước sang kỳ đích; (b) để gửi thẳng danh sách. Gửi cả hai thì được ghép thêm vào kết quả sao chép (dòng cùng nhân viên thì thắng).

Chỉ áp cho những nhân viên này khi sao chép; để trống là mọi dòng của kỳ nguồn

Ghi đè dòng đã có của kỳ đích. Mặc định false: chạy lại lần hai không đụng dòng ai đã chỉnh tay.

Tham số bảng tính thử / sinh thưởng cho một kỳ tháng

Lọc theo một nhân viên nhận thưởng; 0 = cả kỳ

Lọc theo chủ thể nguồn điểm của dòng cấu hình — 0 nghĩa là không lọc.

Khác (người NHẬN tiền): đây là chủ thể mà điểm được lấy từ đó (KpiBonusSetting.ScoreSubjectKind/ScoreSubjectId). Đường chốt kỳ MỘT chủ thể dùng nó để giới hạn lần sinh thưởng đúng vào chủ thể vừa chốt — nếu không, một trưởng bưu cục chốt lại chỉ tiêu của nhân viên mình sẽ khởi động việc ghi/gỡ tiền cho cả công ty.

Xem ; 0 = không lọc theo chủ thể nguồn điểm

Model tạo/sửa chỉ số KPI

Mã định danh duy nhất "nhom.ten-kebab" — không đổi sau khi đã có chỉ tiêu tham chiếu

Tên hiển thị

Đơn vị đo

Chiều đánh giá

Áp cho loại chủ thể nào

Nguồn giá trị thực

Mã provider — bắt buộc khi SourceType = Auto

Còn dùng để giao chỉ tiêu mới

Yêu cầu chốt kỳ (hoặc chốt lại) cho một chủ thể — đường thủ công của §3.4.

Cùng một model cho cả chốt lần đầu lẫn chốt lại: người dùng không phải biết kỳ đã chốt hay chưa, service tự nhận ra và tự áp cửa sổ Kpi.RecloseWindowDays khi là lần chốt thứ hai.

Loại chủ thể được chốt

Id chủ thể — User.Id hoặc Agency.Id theo SubjectKind

Năm của kỳ

Tháng của kỳ (1-12)

Nhập tay giá trị thực cho một chỉ tiêu trước khi chốt kỳ (§3.4).

Dùng cho chỉ số SourceType = Manual, và cho cả ca override số của engine khi nghiệp vụ có căn cứ. Job chốt kỳ **không ghi đè** giá trị nhập tay.

Chỉ tiêu được nhập giá trị

Giá trị thực nhập tay

Lý do nhập tay — bắt buộc (§3.9c, §3.10 để lại dấu vết)

Bản đánh giá KPI định kỳ quý/năm do người quản lý ghi (§7.1).

Không có trường AggregatedScore: điểm là số hệ thống tự tính và chỉ snapshot lúc chuyển Final. Cho client gửi điểm lên là mở đường ghi đè căn cứ tăng lương bằng tay.

0 = tạo mới

Quarter hoặc Year

Quý 1-4; bỏ qua (ghi 0) khi PeriodType = Year

Xếp loại — danh mục do nghiệp vụ chốt, null = chưa xếp

Nhận xét / điều chỉnh hướng

Đề xuất: giữ nguyên / điều chỉnh chỉ tiêu / tăng lương / thăng chức...

Yêu cầu chốt một bản đánh giá định kỳ sang Final — snapshot điểm tổng hợp tại thời điểm chốt.

Người thực hiện thao tác trên hồ sơ bưu cục — controller dựng từ JWT.

Tạo hồ sơ nháp cho một Agency chưa có hồ sơ.

Tên hiển thị; bỏ trống thì server gợi ý từ tên chi nhánh (bỏ tiền tố "LADA", "Trung tâm"…).

Sửa hồ sơ theo nhóm trường. Server CHỈ ghi các nhóm trong ; trong một nhóm được ghi, mọi trường lấy nguyên giá trị payload (null = xoá). Trường thuộc nhóm không liệt kê bị bỏ qua — "không gửi" ≠ "muốn xoá". Nhóm liệt kê mà người dùng không có quyền → 403 FORBIDDEN_FIELD, không âm thầm bỏ.

Số phiên bản client đang giữ — lệch thì 409 VERSION_CONFLICT.

Nhóm muốn ghi: Core, Geo, Contact, Pause, Content, Commerce, ServiceArea, Seo.

Chuyển trạng thái công bố (Published / Paused / Closed).

Khi đóng: bưu cục đích (đang công bố/tạm ngưng) cho 301.

Khi đóng không chọn đích: xác nhận 301 về trang danh sách /buu-cuc.

Có gửi thì lệch là 409.

Mở lại hồ sơ đã đóng về nháp.

Giờ làm việc đủ 7 ngày.

0 = Chủ nhật … 6 = Thứ bảy.

Thêm/sửa (hoặc gỡ khi ) ngoại lệ giờ của một ngày.

Thay toàn bộ danh sách tuyến của bưu cục.

Thêm (Id = 0) hoặc sửa nhân sự hiển thị.

Sắp lại thứ tự MỌI nhân sự hiển thị của bưu cục trong MỘT phiên bản: theo thứ tự mới, phải đủ đúng tập nhân sự hiện có (khuôn ). Trước đây FE đổi chỗ bằng N lần Staff/Upsert — N phiên bản rác trong lịch sử và thứ tự ghi dở khi một lần giữa chừng hỏng (review B1).

Tải MỘT ảnh lên (multipart/form-data). Nội dung file quyết định loại (JPEG/PNG/WebP theo magic bytes) — tên file, đuôi và content-type client gửi đều bị bỏ qua; tên lưu đĩa do server sinh.

Mô tả ảnh (alt) — bắt buộc, tối đa 200 ký tự.

Ảnh chụp thật tại bưu cục (không phải ảnh minh hoạ) — điều kiện công bố #5 đòi ảnh bìa thật.

Người có role AgencyProfile.Media chọn ảnh lên web ngay hay chờ duyệt; bỏ trống = duyệt luôn. Branch.Manager (phạm vi bưu cục của mình) gửi gì cũng thành chờ duyệt.

Bỏ trống = xếp cuối nhóm ảnh cùng vai.

Sửa thông tin một ảnh (không đổi file, không đổi trạng thái duyệt).

Gỡ một ảnh (xoá mềm; gỡ luôn tham chiếu ảnh Open Graph / chân dung nhân sự).

Sắp lại thứ tự MỌI ảnh của một vai: theo thứ tự mới, phải đủ đúng tập ảnh của vai đó.

Duyệt (hoặc bỏ duyệt) một ảnh để lên trang công khai.

Đổi slug; slug cũ vào lịch sử để trang công khai 301.

Khôi phục nội dung của một phiên bản cũ thành phiên bản MỚI.

Branch.Manager gửi đề xuất sửa MỘT nhóm trường của bưu cục mình (GĐ D, plan §3.4 cột "đề xuất"). Chỉ đọc các trường của : Geo → toạ độ + Place ID; Content → + ; ServiceArea → ; Routes → (đủ danh sách, thay toàn bộ như Routes/Set); Staff → (một thao tác trên một người, như Staff/Upsert|Delete). Nhóm ghi cả khối: trường trống = đề xuất xoá.

Lời giải thích cho người duyệt, tối đa 1000 ký tự.

Thao tác trên một nhân sự hiển thị trong đề xuất. Giá trị số lưu trong PayloadJson, không đổi.

Thêm (Id = 0) hoặc sửa (Id của nhân sự có sẵn) — như Staff/Upsert.

Gỡ nhân sự Id — như Staff/Delete.

Một thao tác nhân sự được đề xuất.

Duyệt một đề xuất: áp vào hồ sơ qua đúng đường ghi sẵn có, luật nội dung chạy lại lúc duyệt.

Phiên bản hồ sơ người duyệt đang nhìn khi đọc bảng so sánh (CurrentVersionNo của dòng hàng đợi). Lệch → 409: cột "hiện tại" người duyệt thấy đã cũ. Không gửi = bỏ khoá có chủ đích.

Ghi chú của người duyệt (tuỳ chọn), vào ghi chú phiên bản.

Từ chối một đề xuất — bắt buộc lý do để Branch.Manager biết sửa gì.

Ngoại lệ giờ cho nhiều bưu cục một lần (nghỉ lễ, đổi giờ) — GĐ D. Một ngày ( trống) hoặc một khoảng tối đa 31 ngày; mỗi bưu cục có thay đổi được một phiên bản + nhật ký; tất cả trong một transaction.

Gỡ ngoại lệ các ngày trong khoảng (sửa lần áp nhầm) thay vì đặt.

Tham số báo cáo bưu cục (GĐ D) — query string của GET Report và GET Report/Export.

Tháng yyyy-MM; trống = tháng hiện tại (giờ Việt Nam).

Một bưu cục; trống/0 = mọi bưu cục trong phạm vi.

Khu vực (node Region) — lấy bưu cục con cháu.

Sửa CẢ bộ tham số kế hoạch kinh doanh trong một lần (POST api/FranchiseBusinessPlan/update): đủ năm bậc phường + bộ tham số chung, kèm dấu nhận ở GET get.

Dấu nhận ở GET get — khác dấu hiện tại = người khác vừa sửa.

Tham số chung. Tiền: đồng.

Tính thử (POST api/FranchiseBusinessPlan/preview): số phường mỗi bậc do người dùng gõ + tham số ĐANG SỬA (chưa lưu). / null = dùng bộ đã lưu. Không nhận Id mã truy cập nào — xem thử không bao giờ đọc phường của một mã.

Số phường của một bậc trong ô xem thử.

Đổi trạng thái một đăng ký nhượng quyền, kèm ghi chú (thay ghi chú đang hiện; ghi chú cũ còn trong lịch sử). Giữ nguyên trạng thái mà đổi ghi chú = ghi thêm một dòng tiến độ.

Tối đa 2000 ký tự; rỗng = xoá ghi chú.

Lịch hẹn gặp / khảo sát (plan cổng §6.29) — BẮT BUỘC khi là , trong vòng một năm quanh hôm nay; bỏ giây. Trạng thái khác: bỏ qua, lịch đang có giữ nguyên.

Địa điểm hẹn, tối đa 200 ký tự; chỉ đọc khi là Meeting — rỗng = xoá địa điểm.

Thông tin người đăng ký do nhân viên nhập — sửa một đăng ký đã có (POST update). Luật kiểm ở FranchiseLeadService, cùng chuẩn với form website trừ chỗ ghi ở từng trường.

2–100 ký tự.

Chuẩn hoá về 0xxxxxxxxx; nhận cả số bàn 11 chữ số (người gọi tổng đài).

Mã trong filter-options.Provinces (Location.Code hoặc khac).

Tối đa 200 ký tự; bắt buộc khi là khac.

Chỉ giữ khi là khac.

Mã trong filter-options.BusinessStatuses; rỗng = chưa hỏi.

Tối đa 200 ký tự.

Một giá trị trong filter-options.ManualChannels. Đăng ký đến từ form website giữ kênh Website — trường này bị bỏ qua.

Nhập tay một đăng ký mới (POST create) cho người nhắn tin hoặc gọi tổng đài.

Ghi chú ban đầu, tối đa 2000 ký tự — vào StatusNote và dòng lịch sử đầu tiên.

Người phụ trách — chỉ người có FranchiseLead.Manage chọn được (rỗng/0 = chưa giao). Người chỉ có FranchiseLead.Search luôn tự phụ trách đăng ký mình nhập: giao cho ai khác là chính họ không còn thấy nó.

Hỏi các đoạn trạng thái theo thời gian của nhiều đăng ký một lúc (biểu đồ Gantt trang lịch hẹn) — tối đa FranchiseLeadService.MaxTimelineLeads id; id ngoài phạm vi người gọi bị bỏ qua, không báo lỗi.

Giao người phụ trách một đăng ký; PicId rỗng hoặc 0 = bỏ giao.

Giao cùng một người phụ trách cho nhiều đăng ký (các dòng đang chọn trên một trang danh sách) — tối đa FranchiseLeadService.MaxAssignLeads id; PicId rỗng hoặc 0 = bỏ giao.

Sửa tham số CẢ bộ bậc gói vùng phủ trong một lần (POST api/FranchisePackageTier/update) — dải phường của các bậc dính vào nhau nên kiểm chung. Phải gửi đủ mọi bậc đang có, không thêm / bớt bậc.

Dấu nhận ở GET list — khác dấu hiện tại = người khác vừa sửa.

Siêu dữ liệu của một mục Cổng nhượng quyền (POST create / POST update) — không chạm khối nội dung. Luật kiểm ở FranchisePortalSectionService.

2–256 ký tự.

Đoạn đường dẫn của mục; bỏ trống khi tạo thì sinh từ tiêu đề. Chữ thường không dấu, số, gạch nối; không trùng mục khác và không trùng đoạn dành riêng của cổng (vao, thoat…).

Tối đa 500 ký tự.

Khoá icon trong bộ icon máy chủ trả (GET form-options); bỏ trống = không icon.

Thứ tự mới của TOÀN BỘ mục cổng — mỗi mục đang có đúng một lần.

Bộ khối đang sửa của một mục (POST {id}/blocks) — thay TOÀN BỘ khối hiện có theo thứ tự SortOrder.

Dấu DraftVersion của bản đang sửa mà người lưu đã mở (từ GET {id}/blocks) — bắt buộc. Có người lưu khối sau đó thì lần lưu này bị từ chối (DraftChanged = true) thay vì đè mất bản của họ.

Xuất bản khối của một mục (POST {id}/publish).

Dấu DraftVersion của bản đang sửa người bấm đã thấy (từ GET {id}/blocks) — bắt buộc.

Tạo mã truy cập cho một khách (POST create).

Đăng ký nhượng quyền của khách — BẮT BUỘC từ GĐ L (plan §6.23): người tạo phải là người phụ trách đăng ký, và đăng ký chưa có mã chưa thu hồi.

2–256 ký tự; bỏ trống thì lấy họ tên của đăng ký nhượng quyền.

Chuẩn hoá về 0xxxxxxxxx; bỏ trống thì lấy số của đăng ký nhượng quyền.

Mã tỉnh (Location.Code) sale ghi cho mã — nhãn lọc, không gác gì trên cổng (gắn giá bằng POST {id}/price-scope).

Tối đa 1000 ký tự.

Các mục cần mở hoặc khoá cho một mã (POST {id}/unlock, POST {id}/lock).

Phạm vi giá sale gắn cho một mã (POST {id}/price-scope): các phường/xã — gói vùng phủ tự xếp theo số phường (GĐ K, plan cổng §6.17). Gửi danh sách trống = gỡ phạm vi giá.

ĐÃ BỎ (gói "Toàn tỉnh / Cấp 1"). Chỉ còn để trang quản trị bản cũ gửi lên thì bị TỪ CHỐI, thay vì hiểu "không có phường" thành gỡ sạch phạm vi giá của khách.

Location.Id các phường/xã 2 cấp thuộc vùng phủ — được ở nhiều tỉnh.

Thu hồi một mã (POST {id}/revoke).

Tối đa 500 ký tự.

Lưu cấu hình trợ lý AI cổng (POST api/FranchisePortalAssistant/config).

null / 0 = tắt trợ lý (không lùi về nhà cung cấp mặc định); chỉ loại Anthropic / OpenAI.

Dấu của dòng nhà cung cấp mà người quản lý ĐANG THẤY trên form (Providers[].Pin của lần đọc cấu hình). Bắt buộc khi chọn nhà cung cấp: dòng vừa bị sửa giữa lúc mở form và lúc bấm Lưu thì máy chủ từ chối (CNQ-65).

Rỗng = model mặc định; tối đa 100 ký tự, chỉ chữ, số, . - _ : /.

Văn bản nền — HTML của trình soạn hoặc chữ thường, tối đa 20.000 ký tự.

"Hỏi thử" trợ lý với ngữ cảnh của một mã (POST api/FranchisePortalAssistant/ask-test).

Yêu cầu xuất bảng giá nhượng quyền của sale.

Tỉnh/thành phố (2 cấp) — bắt buộc.

Phường/xã đã tích chọn. Rỗng = xuất bảng giá cả tỉnh, không có phần tổng.

Ô "Số xe thuê LADA", mặc định 0.

Thêm/sửa tay một dòng giá của phiên bản hiện hành. Ô bắt buộc để kiểu nullable để phân biệt "bỏ trống" với số 0; luật kiểm giống hệt sheet BangGia của file upload.

Phường/xã 2 cấp — chỉ đọc khi thêm; khi sửa lấy theo đường dẫn.

bac 1–5.

gia_nhuong_quyen — đồng, gồm VAT.

coc_theo_san_luong — đồng.

san_luong_du_kien — đơn/ngày.

Dấu của dòng lúc mở form (FranchisePriceLineItem.Stamp) — bắt buộc khi sửa.

Bộ lọc danh sách phường/xã có giá, đọc từ SmartTableParam.Search.PredicateObject.

Tìm theo tên, có dấu hay không dấu đều ra.

Lập / làm mới nháp phiếu tháng.

Kỳ yyyyMM; null = kỳ trước tháng hiện tại.

Chỉ một bưu cục; null = mọi ví có dòng trong kỳ.

Đánh dấu đã lập hoá đơn.

Số hoá đơn LADA xuất cho bưu cục.

Số hoá đơn bưu cục xuất cho LADA.

Ghi chú khi phát hành / khoá.

Ghi chú.

Dấu UpdatedTime lúc mở phiếu — lệch thì từ chối.

Tạo một điều chỉnh tay (thưởng / bồi thường / điều chỉnh) — chờ duyệt.

Bưu cục nhượng quyền.

Thưởng / Bồi thường / Điều chỉnh.

Số tiền có dấu (+ LADA trả bưu cục, − bưu cục trả LADA). Thưởng phải dương.

Lý do — bắt buộc.

Đơn liên quan (tuỳ chọn).

Dòng gốc được điều chỉnh (tuỳ chọn).

Đưa điều chỉnh "vào kỳ" của phiếu đối soát đang NHÁP của đúng bưu cục này (SPEC §3.6, tuỳ chọn). Bỏ trống thì điều chỉnh vào kỳ chứa ngày được duyệt.

Bật ví cho một chi nhánh (Ví v2 plan §1.1 — bưu cục nhượng quyền hoặc chi nhánh LADA).

Chi nhánh được bật ví.

Sửa tham số + tài khoản của một ví (Ví v2 plan §3.8.1 "Cấu hình ví", role Config). Không có cờ bật / chặn: bật ví đi wallets/enable, chặn xuất kho theo loại chi nhánh (§6 mục 15). Tham số chỉ áp cho bưu cục nhượng quyền.

Số dư tối thiểu sau rút / để được xuất kho (đồng, ≥ 0).

Ngưỡng cảnh báo số dư thấp (đồng, ≥ 0).

Số rút tối thiểu một lệnh (đồng, ≥ 0).

Số lệnh rút một ngày (1–10).

Tạm giữ (bồi thường — trừ khỏi số rút được, đồng, ≥ 0).

Tài khoản nhận tiền rút — đủ cả ba hoặc trống cả ba.

Tài khoản ảo nạp tiền (đối chiếu sao kê).

Từ chối một điều chỉnh tay.

Lý do từ chối.

Gán / bỏ bưu cục sở hữu khách.

Bưu cục nhượng quyền; null = khách của LADA.

Chủ bưu cục tạo lệnh rút (Ví v2 §3.5). KHÔNG có bưu cục / tài khoản nhận trong yêu cầu: ví = bưu cục của người gọi, tài khoản nhận chụp từ ví do kế toán khai (chống IDOR / đổi tài khoản nhận).

Số tiền rút (đồng, số nguyên dương).

Ghi chú (tối đa 500 ký tự).

Kế toán quỹ xác nhận đã chuyển tiền lệnh rút.

Mã giao dịch ngân hàng (bắt buộc).

Kế toán quỹ từ chối lệnh rút.

Lý do (bắt buộc, ít nhất 5 ký tự).

Kế toán quỹ ghi nhận tiền bưu cục nạp vào tài khoản LADA (Ví v2 §3.5 đường 1 — nhập tay).

Bưu cục được cộng ví.

Số tiền (đồng, số nguyên dương).

Ngày tiền vào tài khoản LADA (không sau hôm nay).

Mã giao dịch ngân hàng — bắt buộc, không trùng khoản nạp đã ghi nhận của cùng ví.

Nội dung chuyển khoản.

Bưu cục sale báo đã tự thu cước nợ đơn hoàn của khách, ngoài ví (mota L2-4).

Ghi chú (bắt buộc, ít nhất 5 ký tự — thu khi nào, bằng gì).

Tạo nháp một phiên bản — từ khung niêm yết hiện tại, hoặc sao chép từ bản khác.

Bảng nào.

Mã phiên bản; để trống = hệ thống gợi ý theo mẫu.

Tên; để trống = "<Tên bảng> <mã>".

Ghi chú.

Ngày bắt đầu áp dụng.

Ngày ngừng áp dụng (ngày đầu tiên không còn áp); null = tới khi có bản sau thay.

Toàn mạng hay danh sách bưu cục.

Bưu cục của phạm vi (chỉ khi = danh sách).

Cách sinh.

Hệ số chung khi sinh từ khung (bắt buộc với cách sinh theo hệ số).

Bước làm tròn ô trọn gói: 1 / 100 / 1.000 đồng.

Sao chép giá từ bản này (cùng bảng); null = sinh từ khung.

Sửa nháp: thông tin chung, phạm vi, và (tuỳ chọn) các ô.

Mã phiên bản (nullable để thiếu / rỗng đi tới câu kiểm tiếng Việt của service thay vì 400 tự động).

Tên.

Ghi chú.

Ngày bắt đầu.

Ngày ngừng áp dụng.

Phạm vi.

Bưu cục của phạm vi.

Bước làm tròn ô trọn gói.

Các ô cần ghi; null = không đụng ô nào.

Dấu UpdatedTime lúc mở bản — lệch thì từ chối (người khác vừa sửa).

Một ô sửa trên màn hình.

Id ô (thuộc bản đang sửa).

Giá gõ tay — dùng khi null.

Hệ số của ô; có giá trị thì server tự tính giá = niêm yết × hệ số.

Ô sửa tay (Sinh theo % không đè trừ khi xác nhận).

"Sinh theo %".

Hệ số chung (0,70 = 70 %).

Bước làm tròn ô trọn gói; null = giữ bước của bản.

Đè cả ô đã sửa tay.

Dấu UpdatedTime lúc mở bản.

Duyệt.

Dấu UpdatedTime của bản người duyệt đang xem — lệch thì từ chối, phải tải lại xem bản mới.

Huỷ.

Lý do — bắt buộc (service kiểm; nullable để không bị 400 tự động).

Đặt / bỏ ngày ngừng áp dụng của bản đã duyệt.

Ngày đầu tiên không còn áp; null = bỏ ngày ngừng.

Model gửi thông báo (Admin)

SystemName của NotificationCategory

Tiêu đề (override template nếu có)

Nội dung (override template nếu có)

Ảnh minh họa

URL điều hướng khi click

JSON data bổ sung

Phạm vi: 0=All, 1=Role, 2=User, 3=UserGroup

Giá trị phạm vi (RoleId, UserId list...)

Lên lịch gửi (null = gửi ngay)

Độ ưu tiên (null = dùng default của category)

Model tạo/cập nhật NotificationCategory

Model cập nhật notification preferences

Model đăng ký device token

0=Web, 1=Android, 2=iOS

VAPID subscription JSON (chỉ cho Web Push)

Filter cho danh sách thông báo

Lọc theo trạng thái đọc: null=tất cả, true=đã đọc, false=chưa đọc

Lọc theo group name (order, finance, system...)

Lọc theo category SystemName

Model Create/Update lý do thất bại

Tên/tiêu đề lý do thất bại

Mô tả chi tiết

Loại thất bại: 1 = Pickup, 2 = Delivery, 3 = Both

Có bắt buộc tải ảnh minh chứng không

Tiêu đề/hướng dẫn ảnh cần tải

Thứ tự hiển thị

Trạng thái hoạt động

Model sử dụng để truyền thông tin thu tiền

Đối tượng đại diện cho thông tin địa chỉ chi tiết của đơn hàng.

Id của địa chỉ.

Id của đơn hàng.

Tên người liên hệ.

Số điện thoại chính.

Số điện thoại phụ.

Địa chỉ chính.

Địa chỉ phụ.

Loại địa chỉ.

Chuỗi mô tả loại địa chỉ.

Id của tỉnh/thành phố.

Id của quận/huyện.

Id của phường/xã.

Địa chỉ đầy đủ.

Ghi chú.

Vĩ độ đã ghim. Null nghĩa là chưa có định vị — trang tra cứu dựa vào đây để hiện trạng thái "đã / chưa định vị".

Kinh độ đã ghim. Null nghĩa là chưa có định vị.

Nguồn toạ độ: 0 = chưa có, 1 = ghim chính xác, 2 = tâm phường/xã (gần đúng). Do service gán qua , không map từ entity.

Thời gian hẹn lấy/giao hàng.

Chuỗi hiển thị thời gian hẹn lấy/giao hàng.

Tiền đối soát dựa trên PayFeeType

Phụ phí lấy hàng

Phụ phí giao hàng

Phụ phí theo thuộc tính loại hàng (0 với đơn không chọn danh mục)

Đối tượng đại diện cho thông tin chung của đơn hàng.

Mã đơn hàng.

Trạng thái đơn hàng.

Chuỗi mô tả trạng thái đơn hàng.

Chiều đơn hàng (đi giao / trả về).

Chuỗi mô tả chiều đơn hàng.

Trạng thái vật lý của đơn hàng.

Chuỗi mô tả trạng thái vật lý của đơn hàng.

Nội dung trạng thái đơn hàng.

Tên tuyến đường.

Tên khách hàng.

Tên đăng nhập của khách hàng.

Id của khách hàng.

Id của người phụ trách hiện tại.

Tên người phụ trách hiện tại.

Tên bưu cục hiện tại.

Tên bưu cục lấy hàng dự kiến.

Tên bưu cục giao hàng dự kiến.

Ngày tạo.

Chuỗi hiển thị ngày tạo.

Ngày cập nhật.

Chuỗi hiển thị ngày cập nhật.

Thời gian lấy hàng thành công.

Chuỗi hiển thị thời gian lấy hàng thành công.

Thời gian giao hàng thành công.

Chuỗi hiển thị thời gian giao hàng thành công.

Danh mục hàng hóa khách chọn (Category có ContentType = GoodsType)

Thuộc tính loại hàng đã lưu trên đơn (snapshot). Rỗng với đơn cũ / đơn không phân loại.

Loại hàng của riêng kiện này, null = kiện không khai loại (đơn cũ dùng loại cấp đơn).

Đối tượng đại diện cho thông tin theo dõi chi tiết đơn hàng.

Loại hành động theo dõi.

Chuỗi mô tả loại hành động theo dõi.

Tên hành động theo dõi.

Nguồn hành động.

Dữ liệu trước khi thay đổi.

Dữ liệu sau khi thay đổi.

Quy định hiển thị của đơn hàng: khách hàng, nội bộ hoặc cả 2.

Id của người phụ trách.

Tên người phụ trách.

Id của đại lý.

Tên bưu cục/đại lý thao tác.

Số điện thoại của người phụ trách.

Id của đơn hàng.

Model chi tiết đơn hàng với thông tin đơn vị đo

Packages với thông tin đơn vị đo

Thông tin về đơn vị đo

Danh mục hàng hóa khách chọn (Category có ContentType = GoodsType)

Thuộc tính loại hàng đã lưu trên đơn (snapshot). Rỗng với đơn cũ / đơn không phân loại.

Phân loại địa chỉ: 2 cấp (mới, sau sáp nhập) hoặc 3 cấp (cũ)

Vĩ độ điểm đã ghim. Null nghĩa là đơn chưa được định vị — khi đó hệ thống hiển thị tạm tâm phường/xã. Client gửi lên khi địa chỉ chọn từ sổ địa chỉ khách hàng đã có sẵn điểm ghim.

Kinh độ điểm đã ghim. Null nghĩa là đơn chưa được định vị.

Model xuất Excel đơn hàng

Thông số tìm kiếm (giống Search nhưng không có phân trang)

Tên file Excel (tùy chọn)

Có bao gồm header không

Có format ngày tháng không

Đường dẫn thư mục lưu file (tùy chọn)

Validate model

Danh sách lỗi validation

Có bao gồm thông tin địa chỉ không

Có bao gồm thông tin gói hàng không

Có bao gồm thông tin tài chính không

Có bao gồm thông tin thời gian không

Enum định nghĩa các loại template xuất Excel

Template cho tài chính - TransferPaymentBill

Template cho vận hành - Operations

Template cho logistics - Pickup/Delivery

Template cho báo cáo - Reporting

Template cho khách hàng - Customer view

Template cơ bản - Basic info

Template đầy đủ - All information

Template tùy chỉnh

Model chung cho việc xuất Excel đơn hàng

Loại template xuất

Danh sách ID đơn hàng cần xuất

Danh sách mã đơn hàng cần xuất

Tên file Excel (không bao gồm extension)

Đường dẫn thư mục lưu file (tùy chọn)

Tên worksheet (tùy chọn, sẽ dùng default của template nếu không có)

Có bao gồm thông tin hàng hóa chi tiết không

Có bao gồm thông tin địa chỉ chi tiết không

Có bao gồm thông tin tài chính chi tiết không

Có bao gồm thông tin thời gian chi tiết không

Có bao gồm thông tin tracking không

Có bao gồm thông tin media/hình ảnh không

Các tùy chọn bổ sung (JSON format)

Validate model

Danh sách lỗi validation

Lấy tên template dạng string

Tên template

Model cho việc xuất Excel với filter nâng cao

Lọc theo khách hàng

Lọc theo sale

Lọc theo trạng thái đơn hàng

Lọc theo trạng thái vật lý

Lọc theo ngày tạo từ

Lọc theo ngày tạo đến

Lọc theo ngày lấy hàng từ

Lọc theo ngày lấy hàng đến

Lọc theo ngày giao hàng từ

Lọc theo ngày giao hàng đến

Lọc theo tuyến

Lọc theo agency

Từ khóa tìm kiếm (mã đơn, tên khách hàng, sdt)

Validate model với filter

Danh sách lỗi validation

Kiểm tra có filter nào không

True nếu có filter

Phụ phí theo thuộc tính loại hàng. Server tự tính, client gửi lên sẽ bị ghi đè.

ID thông tin xuất hóa đơn VAT (null nếu không xuất VAT)

Tiền đối soát dựa trên PayFeeType

Cước chuyển khoản

Người giữ tiền cước thu từ chuyển khoản

Cước chuyển khoản

Người giữ tiền cước thu từ chuyển khoản

Đơn hàng của khách hàng nào

Địa chỉ nguồn

Địa chỉ đích

Địa chỉ trả về (nếu không dùng IsReturnSameAsSource)

Nếu true, địa chỉ trả về giống địa chỉ lấy hàng (tự động copy)

Ghi chú đơn hàng

Danh mục hàng hóa khách chọn (Category có ContentType = GoodsType). Null = không phân loại, giữ nguyên cách tính cước cũ.

Lựa chọn thuộc tính hàng hóa. Client chỉ gửi lựa chọn, giá luôn resolve từ DB.

Đơn hàng của sale nào

Có xuất hóa đơn VAT không

ID thông tin xuất hóa đơn VAT (bắt buộc nếu IsVatRequired = true)

Mã đối tác

Model hàng hóa trong đơn hàng

ID của kiện hàng

Ảnh kiện hàng

Mã kiện hàng

Tên hàng hóa

Trọng lượng cân nặng của 1 kiện hàng

Chiều dài 1 kiện hàng

Chiều rộng 1 kiện hàng

Chiều cao 1 kiện hàng

Số lượng kiện

Tổng trọng lượng của kiện hàng

Ghi chú của kiện hàng

Loại hàng của riêng kiện này. null / 0 = không khai ⇒ backend điền loại mặc định.

Một đơn được phép nhiều loại hàng (1 xe máy + 1 kiện hàng), mỗi kiện tra bảng giá theo loại của chính nó. Kênh chưa khai theo kiện thì bỏ trống và OrderModel.GoodsCategoryId cấp đơn vẫn dùng được như trước.

Lựa chọn thuộc tính hàng hóa của riêng kiện này. Giá luôn resolve từ DB, không tin giá client gửi.

Đơn vị trọng lượng (hiển thị cho client)

Đơn vị kích thước (hiển thị cho client)

Xác thực kiện hàng, hàng phải có trọng lượng cân nặng hoặc trọng lượng kích thước

Quy định hiển thị của đơn hàng: khách hàng, nội bộ hoặc cả 2

Số điện thoại của người phụ trách

Thông tin cập nhật định vị (toạ độ) cho một địa chỉ đơn hàng. Tách khỏi vì đây là thao tác riêng: chỉ ghi Lat/Long, KHÔNG đụng tới tỉnh/phường nên không kéo theo việc tính lại cước hay đổi bưu cục dự kiến.

Id của địa chỉ đơn hàng.

Vĩ độ. Để null (cả Lat và Long) nghĩa là xoá định vị đang có.

Kinh độ. Để null (cả Lat và Long) nghĩa là xoá định vị đang có.

Cách lấy toạ độ, chỉ để ghi vào hành trình cho dễ truy vết: "link" (link Google), "map" (ghim trên bản đồ), "manual" (nhập tay), "clear" (xoá).

Id của người cập nhật (controller gán từ token, client không gửi).

Tên người cập nhật (controller gán từ token, client không gửi).

Yêu cầu bóc toạ độ từ một link Google Maps rút gọn (maps.app.goo.gl).

Link người dùng dán vào. Chỉ nhận các miền của Google.

Đối tượng đại diện cho thông tin cập nhật địa chỉ đơn hàng.

Id của địa chỉ.

Id của đơn hàng.

Tên người liên hệ.

Số điện thoại chính.

Số điện thoại phụ.

Địa chỉ chính.

Địa chỉ phụ.

Loại địa chỉ.

Id của tỉnh/thành phố.

Tên của tỉnh/thành phố.

Id của quận/huyện.

Tên của quận/huyện.

Id của phường/xã.

Tên của phường/xã.

Phân loại địa chỉ: 2 cấp (mới, sau sáp nhập) hoặc 3 cấp (cũ)

Ghi chú.

Id của người cập nhật.

Tên người cập nhật.

Thời gian hẹn lấy/giao hàng.

Vĩ độ đã ghim. Null nghĩa là chưa có định vị. Dialog cập nhật định vị đọc trường này để nạp toạ độ hiện tại; OrderAddressService.Update KHÔNG ghi trường này — định vị đi qua UpdateCoord riêng.

Kinh độ đã ghim. Null nghĩa là chưa có định vị.

Phương thức kiểm tra tính hợp lệ của đối tượng.

Ngữ cảnh kiểm tra tính hợp lệ. Danh sách các kết quả kiểm tra tính hợp lệ.

Model để cập nhật thông tin tài chính đơn hàng.

ID của tài chính đơn hàng (cũng chính là OrderId).

Số tiền thu hộ.

Loại phí thanh toán.

Giảm giá.

Phí phụ thu khi lấy hàng.

Phí phụ thu khi giao hàng.

Phí.

Phí COD.

Phụ phí theo thuộc tính loại hàng. Server tự tính lại, client gửi lên sẽ bị ghi đè.

Danh mục hàng hóa của đơn (Category có ContentType = GoodsType). Null = không phân loại, giữ nguyên cách tính cước cũ.

Lựa chọn thuộc tính hàng hóa sau khi sửa. Client chỉ gửi lựa chọn, giá luôn resolve từ DB.

Tổng phí.

Phí nguồn.

Phí đích.

ID của người cập nhật.

Tên người cập nhật.

Model cập nhật các kiện hàng trong đơn hàng

Mã đơn hàng

Danh sách kiện hàng

ID của người cập nhật

Tên đăng nhập của người cập nhật

Model cập nhật kiện hàng với thông tin đơn vị đo

ID của đơn hàng

Danh sách kiện hàng với thông tin đơn vị đo

Thông tin tổng hợp về đơn vị đo được sử dụng

Thông tin về đơn vị đo được sử dụng trong hệ thống

Đơn vị trọng lượng hiển thị cho client

Đơn vị kích thước hiển thị cho client

Đơn vị trọng lượng lưu trong database

Đơn vị kích thước lưu trong database

Hệ số chuyển đổi trọng lượng (client -> database)

Hệ số chuyển đổi kích thước (client -> database)

Cập nhật bởi chi nhánh nào

Model tạo/cập nhật liên hệ mặt bằng

Model tạo/cập nhật thông tin tài chính mặt bằng

Model tạo/cập nhật mặt bằng

Danh sách liên hệ

Danh sách điểm chấm theo tiêu chí

Thông tin tài chính (optional)

Danh sách file ảnh upload mới

Loại media tương ứng với từng file (FrontageImage, InsideImage, StreetImage...)

Danh sách PremiseMedia.Id cần xóa (khi chỉnh sửa)

Model cập nhật trạng thái mặt bằng

Model tạo/cập nhật điểm chấm của mặt bằng theo tiêu chí

Model tạo/cập nhật tiêu chí chấm điểm (Admin)

Danh sách options kèm điểm

Model tạo/cập nhật option cho tiêu chí

Model tạo/cập nhật mã khuyến mãi

Model sinh mã hàng loạt

Tiền tố mã (VD: LADA)

Số lượng mã cần sinh

Số ký tự phần random

Số lượt sử dụng tối đa mỗi mã

Model tạo/cập nhật chương trình khuyến mãi

Danh sách điều kiện áp dụng

Model điều kiện áp dụng

Model chuẩn bị cho màn hình thống kê chuyển khoản theo sale

Danh sách trạng thái đơn hàng

Danh sách trạng thái vật lý đơn hàng

Vì sao bảng lượt bot đang hiện con số nó đang hiện. Ba cách ra số 0, và chúng đòi ba phản ứng khác nhau — cùng bài học với tab hiệu suất (), nhưng ở đây ba cách ấy khác hẳn về nội dung: website chưa deploy bản có middleware đếm, hoặc công tắc đang tắt — không có gì đang đếm cả, và con số 0 không nói gì về bot; đã đếm, nhưng chưa bot nào ghé trong khoảng đang xem — 0 là một phép đo thật; đã đếm, có bot ghé, nhưng đường dẫn cụ thể đang xem thì không ai ghé — cũng là một phép đo thật, ở phạm vi hẹp hơn. Phân biệt (1) với (2) không nhìn vào bảng là biết được, vì cả hai đều cho bảng rỗng. Tín hiệu duy nhất tách được chúng là công tắc cộng với mốc ghi gần nhất: website có đếm thì dù 0 lượt vẫn để lại dòng của những ngày trước đó.

Bảng chưa có dòng nào bao giờ. Việc cần làm: kiểm tra website đã deploy bản có middleware đếm chưa, và khoá Search.BotVisit.Enabled có đang bật không.

Đã ghi và khoảng đang xem có số. Trạng thái bình thường.

Đã từng ghi nhưng riêng khoảng ngày đang xem không có dòng nào — không bot nào ghé trong khoảng ấy, hoặc dữ liệu đã bị job dọn 90 ngày xoá.

Công tắc Search.BotVisit.Enabled đang tắt. Số cũ vẫn còn đó nhưng không có gì mới được ghi thêm — một cảnh báo, không phải một con số.

Các con số tổng hợp của tab lượt bot.

Độ dài khoảng đang xem, tính bằng ngày.

Ngày đầu khoảng đang xem.

Ngày cuối khoảng đang xem.

Ngày sớm nhất bảng còn giữ — cho biết job dọn đã cắt tới đâu.

Ngày gần nhất bảng có số.

Số ngày từ tới hôm nay.

Công tắc Search.BotVisit.Enabled đang bật hay tắt.

Số ngày dữ liệu được giữ trước khi job dọn xoá — để màn hình nói ra con số đó.

Xem .

Câu giải thích đọc được, hiện thẳng lên màn hình. Rỗng khi mọi thứ bình thường.

Số ngày thật sự có dòng trong khoảng.

Tổng lượt của mọi bot trong khoảng.

Tổng lượt trả mã dưới 400.

Tổng lượt trả mã từ 400 trở lên.

Số bot khác nhau đã ghé trong khoảng.

Số đường dẫn khác nhau có bot ghé trong khoảng.

Có dòng nào rơi vào rổ gộp "(khác)" không — nghĩa là bộ đếm đã chạm trần số khoá và phần chi tiết của những lượt đó đã mất. Màn hình phải nói ra thay vì để nó trông như một trang có thật.

Tổng lượt theo từng bot, xếp giảm dần.

Tổng lượt theo từng ngày, xếp theo ngày tăng dần — để vẽ đường xu hướng.

Một bot trong bảng tổng hợp.

Số đường dẫn khác nhau bot này đã ghé.

Mốc lượt gần nhất của bot này trong khoảng.

Một ngày trong đường xu hướng.

Một dòng của bảng xếp hạng đường dẫn.

Đường dẫn đã chuẩn hoá. Giá trị "(khác)" là rổ gộp khi bộ đếm chạm trần.

Mã trạng thái của lượt gần nhất — cho biết đường dẫn này hiện đang trả về gì.

Mốc lượt gần nhất.

Số bot khác nhau đã ghé đường dẫn này.

Đường dẫn này có trong hàng tồn kho URL không. Phép so là so giữa hai dạng ĐÃ chuẩn hoá, vì hai cột vốn khác dạng: SearchUrl.Path ghi bằng Uri.AbsolutePath nên giữ chữ hoa và giữ mã hoá phần trăm, còn BotVisitDaily.Path đã hạ chữ thường và bỏ / cuối. So thẳng hai cột là cách chắc chắn ra kết quả sai — bài học đã cắn ở giai đoạn E và lặp lại ở giai đoạn F.

Còn trong sitemap không. null khi hàng tồn kho không có đường dẫn này.

Nhãn tiếng Việt cho các mã của miền đồng bộ công cụ tìm kiếm. Vì sao nhãn nằm ở tầng hiển thị chứ không nằm trong DB. Mã lưu xuống (PASS, SearchUrlGroup.Product) là thứ ổn định để đếm và để lọc; câu chữ hiện trên màn hình thì đổi theo cách người vận hành quen gọi. Tách hai thứ ra nghĩa là sửa chữ không cần migration, còn con số thống kê không bao giờ đổi nghĩa vì ai đó sửa một từ. Cố ý không đọc [Description] của enum. Mô tả trên enum là nhãn dùng chung cho cả hệ thống; nhãn ở đây là ngôn ngữ của người làm SEO — "Chưa khớp nội dung" nói rõ việc phải làm, còn "Không rõ" thì không. Đổi [Description] để sửa một chữ trên dashboard sẽ kéo theo mọi màn hình khác đang dùng cùng enum. Đặt ở đây, cạnh DTO, vì cả ba nơi đều cần đúng một bảng chữ này: dashboard, widget trang chủ và kết quả một lượt "kiểm ngay".

Nhãn tiếng Việt của một nhóm URL.

Nhãn tiếng Việt của một Verdict do Google trả về. Mã lạ được trả nguyên văn thay vì quy về "không rõ": Google thêm giá trị mới mà không báo trước, và một mã lạ hiện ra trên màn hình là đủ để người vận hành tra cứu, còn chữ "không rõ" thì xoá sạch thông tin đó.

Một dòng của bảng chính: URL trong hàng tồn kho kèm trạng thái index gần nhất của một công cụ tìm kiếm. Một dòng là phép nối hai bảng, không phải một thực thể. SearchUrl trung lập với công cụ tìm kiếm còn SearchIndexStatus thì theo từng công cụ, nên không có entity nào ánh xạ thẳng ra được dòng này — cũng là lý do nó không đi qua AutoMapper (xem SearchConsoleDashboardService.SearchAsync).

Khoá của SearchUrl — dùng để mở chi tiết và để bấm "kiểm ngay".

URL tuyệt đối đúng như trong sitemap.

Phần đường dẫn sau tên miền — cột hẹp để đọc nhanh trên bảng.

Nhóm nguồn sinh ra URL.

Nhãn tiếng Việt của . Tự suy từ khi chỗ tạo dòng chưa gán, nên một dòng dựng tay ở nơi khác (kết quả "kiểm ngay", widget trang chủ) không bao giờ trả về nhãn rỗng. Vẫn để gán được để chỗ gọi ghi đè khi cần.

Tên thực thể theo cách gọi của UrlRecord — đường lần về bản ghi nội dung.

Khoá thực thể đứng sau URL, nếu khớp được.

Mốc lastmod đọc từ chính sitemap — thứ website đã báo cho Google.

URL có nằm trong sitemap ở lượt quét gần nhất hay không.

Kết luận tổng của lượt kiểm gần nhất (PASS, NEUTRAL, FAIL...). Đây là mã ổn định, dùng được để đếm và để lọc. NULL nghĩa là chưa từng kiểm.

Câu Google hiện ngay trên giao diện Search Console. Chỉ để hiển thị và để lọc, tuyệt đối không dùng để nhóm hay đếm. Google trả câu này theo ngôn ngữ của property nên nó đổi chữ khi đổi ngôn ngữ — mọi con số đếm theo nó sẽ vỡ vào đúng ngày đó mà không ai biết. Đếm thì đếm theo .

Trạng thái cho phép index: INDEXING_ALLOWED, BLOCKED_BY_META_TAG...

Trạng thái theo robots.txt.

Kết quả lượt Google tải trang: SUCCESSFUL, SERVER_ERROR, SOFT_404...

Lần Google thu thập trang gần nhất. NULL nghĩa là Google chưa từng thu thập.

Thời điểm mình hỏi Google — khác hẳn .

URL chuẩn tắc theo Google.

URL chuẩn tắc do chính trang khai.

Hai URL chuẩn tắc có khớp nhau không. NULL khi thiếu một trong hai — "chưa biết" phải khác hẳn "lệch", vì chỉ cái sau mới là lỗi SEO cần sửa.

Google có thấy URL này trong sitemap không — theo lời Google. Lệch với thường nghĩa là Google đang đọc một bản sitemap cũ.

Trang vừa sửa mà Google chưa đọc lại — câu hỏi có giá trị nhất của cả màn hình, nên nó cũng là khoá sắp xếp mặc định của bảng.

Đã từng hỏi Google về URL này hay chưa.

Số lượt nhấp từ kết quả tìm kiếm. Luôn NULL cho tới khi có phần đọc Search Analytics. NULL và 0 là hai điều khác nhau: 0 nghĩa là đã đo và không ai nhấp, NULL nghĩa là chưa đo. Giao diện phải hiện "chưa có dữ liệu" chứ không được hiện số 0.

Số lượt hiển thị trong kết quả tìm kiếm. Luôn NULL — xem .

Đường dẫn của URL này có một luật trong bảng UrlRedirect đang bật hay không.

Dữ liệu của chính mình nên luôn biết được — vì thế là bool chứ không phải bool?, khác hẳn ngay dưới. Nó là một nửa của phép đối chiếu mà kế hoạch §3.4 đòi: Google bảo một URL có lệnh chuyển hướng thì phải xem có đúng mình cố ý làm thế hay không.

Công cụ tìm kiếm có nói URL này đang chuyển hướng hay không. null = chưa hỏi bao giờ, không phải "không chuyển hướng".

Đây là một phép dò theo chuỗi, không phải một mã ổn định — và phải đọc nó với đúng mức tin cậy đó. urlInspection của Google không có trường riêng nào cho "trang có lệnh chuyển hướng"; điều đó chỉ xuất hiện trong CoverageState, là câu tiếng Việt hiển thị trên giao diện Search Console (đo thật 2026-09-15: "Đã được gửi và lập chỉ mục", "Lỗi máy chủ (5xx)"…). Nên ở đây phải dò theo cách diễn đạt, và dò cả tiếng Việt lẫn tiếng Anh vì chuỗi đổi theo ngôn ngữ của property. Chưa từng khớp một dòng thật nào. Việc 0 của GĐ D đếm trên 148 URL của DB dev: 0 URL có CoverageState chứa "chuyển hướng" hay "redirect". Điều đó đúng như kỳ vọng — hàng tồn kho dựng từ sitemap, mà URL trong sitemap thì lẽ ra không được chuyển hướng — nên cờ này là một hàng rào canh cho ngày điều đó sai, chứ không phải một số đo đang có người đọc.

Google nói URL này chuyển hướng, mà mình không có luật nào cho nó — chuyển hướng ở đâu ra? null khi chưa hỏi Google về URL này.

Nguồn khả dĩ khi cờ này bật: một chỗ RedirectPermanent trong controller (PricingController, AgencyController — canonical theo route, cố ý giữ trong code), một tầng đứng trước ứng dụng (CDN, cấu hình IIS), hoặc chính Google đang giữ một bản ghi cũ từ trước khi luật bị xoá.

URL còn trong sitemap mà đã có luật chuyển hướng đang bật — mâu thuẫn cần sửa.

Không cần hỏi Google mới biết: cả hai vế đều là dữ liệu của mình, nên đây là cờ đối chiếu dùng được ngay, khác phải chờ một lượt kiểm. Bật nghĩa là sitemap đang nói "hãy vào đọc trang này" trong khi máy chủ trả 301 "trang này chuyển đi rồi" — công cụ tìm kiếm ghi nhận nó thành lỗi chứ không tự chọn giúp bên nào (bài học GEO-12). Tầng lưu của màn 301 tự tắt cờ sitemap khi tạo luật, nên bật ở đây nghĩa là có người bật lại sau đó, hoặc URL quay vào sitemap từ một nguồn khác UrlRecord.

Các con số tổng của một công cụ tìm kiếm — phần thẻ đầu trang dashboard.

Tổng số URL trong hàng tồn kho (chưa xoá mềm).

Số URL có Verdict = PASS.

Số URL đã kiểm mà Verdict khác PASS.

Số URL chưa từng hỏi Google — không cộng vào .

Số URL vừa sửa mà Google chưa đọc lại.

Số URL có hai URL chuẩn tắc lệch nhau.

Số URL mà Google nói là không thấy trong sitemap.

Số URL Google nói đang chuyển hướng mà bảng UrlRedirect không có luật nào — chuyển hướng ở đâu ra?

null nghĩa là chưa hỏi Google về URL nào, khác hẳn 0 nghĩa là đã hỏi và không có URL nào như thế. Đây là trạng thái mặc định sau khi deploy, vì hai công tắc gọi Google mặc định TẮT — in 0 ở đó là đúng loại nói dối bằng số mà giai đoạn C đã mắc ("Đã index: 0" cho một hệ thống chưa kiểm lần nào). Chỉ đếm trong số URL đã kiểm: URL chưa hỏi Google thì không có ý kiến nào để đối chiếu. Đo trên DB dev 2026-09-15: 0, trên một hàng tồn kho 148 URL mà cả 148 đều đã có lượt kiểm — nên số 0 đó là "đã đo và bằng không", không phải "chưa đo".

Số URL còn trong sitemap mà đã có luật chuyển hướng đang bật.

Cả hai vế đều là dữ liệu của mình nên con số này không phụ thuộc lượt kiểm Google nào — nó đúng kể cả khi hai công tắc gọi Google còn tắt. Nhưng nó vẫn phụ thuộc một thứ: vế "còn trong sitemap" đọc SearchUrl.InSitemap, nên trước lượt dựng hàng tồn kho đầu tiên ( còn null) thì bảng rỗng và con số này là 0 vì chưa có gì để đếm, không phải vì đã đếm. Giao diện phải đọc nó cùng .

Số lời gọi ra công cụ tìm kiếm trong 24 giờ gần nhất.

Số lời gọi thất bại trong 24 giờ gần nhất.

Đã có số liệu nhấp/hiển thị hay chưa. Còn false tới khi có phần đọc Search Analytics — giao diện dựa vào cờ này để ẩn hẳn khối đó thay vì vẽ một biểu đồ toàn số 0.

Lần gần nhất hàng tồn kho được dựng lại từ sitemap.

Lần gần nhất hỏi Google trạng thái một URL bất kỳ.

Đếm theo Verdict — mã ổn định, đây là bảng số liệu dùng được.

Đếm theo câu mô tả của Google. Chỉ để trả lời "vì sao" và để người dùng bấm lọc theo đúng câu chữ họ nhìn thấy trong Search Console — không phải một chỉ số để theo dõi theo thời gian, vì câu chữ đổi theo ngôn ngữ property.

Đếm theo nhóm URL — Key là số của SearchUrlGroup.

Công tắc và hạn mức đang hiệu lực.

Một dòng đếm: mã để lọc, nhãn để đọc, số để xem.

Mã ổn định — chính là giá trị giao diện gửi ngược lên khi bấm lọc.

Nhãn tiếng Việt hiện trên màn hình.

Số URL thuộc nhóm này.

Công tắc, định danh property và hạn mức — phần "vì sao màn hình đang im lặng" của dashboard. Có mặt cả khi mọi công tắc đang tắt: trạng thái tắt là trạng thái hợp lệ, và người vận hành phải đọc được ngay lý do thay vì nhìn một màn hình trống rồi tưởng hệ thống hỏng.

Công tắc ĐỌC.

Công tắc GHI (nộp sitemap).

Được phép gọi lời gọi đọc hay không.

Được phép gọi lời gọi ghi hay không.

Câu tiếng Việt giải thích vì sao chưa được gọi; rỗng khi đã được phép ghi.

Định danh property trong Search Console.

Tệp sitemap đang theo dõi.

Trần số lượt kiểm URL mỗi ngày.

Số lượt kiểm đã dùng hôm nay — đếm chung cho job theo lịch và nút bấm tay, vì cả hai tiêu vào đúng một hạn mức của Google.

Số lượt kiểm còn lại hôm nay, không bao giờ âm.

Trạng thái tệp sitemap dưới mắt công cụ tìm kiếm.

Tệp sitemap đang theo dõi, lấy từ cấu hình — có giá trị kể cả khi chưa đo lần nào, để màn hình nói được "đang theo dõi tệp nào" trước cả khi có số.

Đã có bản ghi đo hay chưa. false là trạng thái hợp lệ (chưa lần nào chạy job đọc sitemap). Giao diện phải hiện lý do chứ không được hiện số 0 như thể đã đo và kết quả bằng không — hai điều đó dẫn tới hai quyết định khác hẳn nhau.

Lần hệ thống này gửi sitemap đi.

Mốc nộp gần nhất theo ghi nhận của Google, bất kể ai nộp.

Lần Google thật sự tải tệp về đọc — mốc đáng theo dõi nhất.

Thời điểm mình hỏi Google về tệp này.

Google đang xử lý dở tệp này.

Số lỗi Google báo trên tệp.

Số cảnh báo Google báo trên tệp.

Số URL Google đếm được trong tệp.

Số dòng URL đang sống trong hàng tồn kho — để đặt cạnh . Hai số lệch nhau nghĩa là Google đang đọc một bản sitemap cũ.

Một dòng nhật ký lời gọi ra công cụ tìm kiếm. Cố ý không mang RequestSummary/ResponseSummary: bảng trên màn hình chỉ cần trả lời "việc gì, lúc nào, mã bao nhiêu", trong khi hai cột tóm tắt dài tới 8 KB mỗi dòng và chỉ hữu ích khi soi lại trực tiếp trong DB.

Khoá dòng nhật ký.

Việc đã làm: Inspect, GetSitemap, SubmitSitemap, DryRun...

URL liên quan, nếu lượt gọi nhắm vào một trang cụ thể.

Endpoint đã gọi, đã bỏ tham số truy vấn.

Mã HTTP trả về. NULL với lượt chạy thử vì không có lời gọi nào đi ra.

Lượt gọi có thành công không.

Thông báo lỗi đã rút gọn, nếu thất bại.

Thời gian gọi, tính bằng mili giây.

Thời điểm gọi.

Yêu cầu kiểm ngay một URL. Chỉ nhận đúng một URL, và URL đó phải đã có trong hàng tồn kho (service kiểm lại). Nhận URL tự do vừa là đường SSRF vừa là đường đốt hạn mức của Google bằng những trang không phải của mình.

URL tuyệt đối, khớp chính xác một dòng SearchUrl chưa xoá.

Kết quả một lượt kiểm ngay: trạng thái mới của URL kèm hạn mức còn lại, để màn hình cập nhật đủ cả hai thứ mà không phải gọi thêm lượt nào.

Trạng thái URL sau khi kiểm. NULL khi lượt kiểm bị từ chối hoặc thất bại.

Số lượt kiểm đã dùng hôm nay sau lượt vừa rồi.

Số lượt kiểm còn lại hôm nay, không bao giờ âm.

Vì sao màn hình đang hiện con số nó đang hiện. Ở miền này có ít nhất ba cách ra số 0, và chúng đòi ba phản ứng khác nhau. Một màn hình in "0 lượt bấm" cho cả ba là nói với người đọc rằng website không ai vào — trong khi sự thật có thể là chưa ai bấm chạy tác vụ kéo số. Con số 0 chỉ có nghĩa khi nó nghĩa là "đã đo và bằng không".

Bảng chưa có dòng nào — chưa kéo lần nào. Việc cần làm: bấm chạy tác vụ kéo bù.

Đã kéo và khoảng đang xem có số. Đây là trạng thái bình thường.

Đã kéo nhưng riêng khoảng ngày đang xem không có ngày nào có số — ví dụ hỏi 7 ngày trong khi mới kéo bù tới một mốc cũ hơn.

Số mới nhất cũ hơn hẳn mức Google thường chốt (~3 ngày). Gần như luôn nghĩa là job hằng ngày chưa được đăng ký, hoặc đang hỏng. Đây là một cảnh báo, không phải một con số.

Các con số tổng hợp của tab hiệu suất.

Độ dài khoảng đang xem, tính bằng ngày.

Ngày đầu khoảng đang xem. null khi chưa kéo lần nào.

Ngày cuối khoảng đang xem.

Ngày sớm nhất bảng có số — cho biết lượt kéo bù đã đi ngược tới đâu.

Ngày gần nhất bảng có số.

Số ngày từ tới hôm nay.

Độ trễ chốt số bình thường của Google, để màn hình nói ra ngưỡng nó đang so.

Xem .

Câu giải thích đọc được, hiện thẳng lên màn hình. Rỗng khi mọi thứ bình thường.

Số ngày thật sự có dòng trong khoảng — khác khi dữ liệu thủng.

Tổng lượt bấm. Lấy từ mức toàn site, không phải cộng từ mức trang — đo 2026-09-16: cộng từ mức trang cho lượt hiển thị lệch +47 %.

Tổng lượt hiển thị, cùng nguồn với .

Tổng (vị trí × lượt hiển thị) — để màn hình tính lại vị trí trung bình cho đúng.

CTR của cả khoảng, tính từ tổng chứ không phải trung bình các CTR ngày.

Vị trí trung bình của cả khoảng, tính từ tổng có trọng số.

Lượt bấm của kỳ liền trước cùng độ dài. null khi chưa đủ dữ liệu để so.

Lượt hiển thị của kỳ liền trước.

Số ngày có số ở kỳ trước. Quan trọng hơn vẻ ngoài của nó: kỳ trước chỉ có 3/28 ngày thì phép so "giảm 89 %" là vô nghĩa, và màn hình phải biết để không vẽ ra một mũi tên đỏ.

Số liệu từng ngày, để vẽ đường xu hướng. Đã xếp theo ngày tăng dần.

Một ngày trong đường xu hướng.

Một dòng của bảng xếp hạng trang hoặc truy vấn.

Giá trị chiều đã gộp — URL đã chuẩn hoá, hoặc truy vấn.

URL, khi dòng này là một trang.

Truy vấn, khi dòng này là một truy vấn.

Tính từ tổng của dòng, không phải trung bình các CTR ngày.

Tính từ tổng có trọng số của dòng.

Trang này còn trong sitemap không. null nghĩa là hàng tồn kho không có URL này — không phải "không có trong sitemap". Hai điều đó khác nhau, và cái sau là một phát hiện đáng xem: Google có lưu lượng cho một trang mà hệ thống chưa biết tới.

URL này có mặt trong hàng tồn kho không. Tách khỏi để màn hình nói được ba câu khác nhau thay vì hai.

Model cho CallPathVersion - dùng cho Create/Update/GetById

Số phiên bản (ví dụ: 1.0.0)

Số build (ví dụ: 101)

Domain cơ sở (ví dụ: https://api.ladaexpress.vn)

Mô tả phiên bản

Đánh dấu phiên bản mặc định

Request model để copy CallPath từ một version sang version khác.

Id của CallPathVersion nguồn (copy từ).

Id của CallPathVersion đích (copy sang).

Thêm hoặc sửa một dòng "nhân viên phụ trách kênh".

Bỏ trống (0) là thêm mới

Ép trọng số phân phối. Bỏ trống là tính theo điểm chất lượng. Khoảng cho phép cùng khoảng của trọng số suy từ điểm (§3.6).

Đổi cấu hình phân phối của một kênh: bưu cục sở hữu và chế độ phân phối. Đổi AssignmentMode khỏi Shared là bật hàng rào quyền xem cho kênh — một hành động đổi phạm vi dữ liệu người ta đọc được, không phải một tuỳ chọn hiển thị. Giao diện phải hỏi lại trước khi gửi.

Bưu cục sở hữu kênh; bỏ trống là gỡ liên kết bưu cục

Tham số một lượt phát lại lịch sử để dựng bảng đối chiếu dry-run.

Đầu cửa sổ (bao gồm)

Cuối cửa sổ (không bao gồm)

Chỉ một kênh; bỏ trống hoặc 0 = mọi kênh đang tự phân phối

Đặt trạng thái sẵn sàng — cho chính mình hoặc cho người khác.

Một model dùng cho cả hai đường, nhưng hai endpoint riêng với hai [Authorize] khác nhau: đặt cho người khác đòi ChatAgentPresence.ManageOthers. Gộp thành một endpoint rồi phân nhánh theo là dựng một đường mà quyền phụ thuộc vào nội dung thân yêu cầu — đúng loại hàng rào dễ quên nhất.

Người được đặt trạng thái. Bỏ trống (0) ở đường "của tôi" nghĩa là chính người đăng nhập; ở đường "đặt hộ" thì bắt buộc.

Trạng thái muốn đặt. Chỉ nhận Available / Busy / Away / OnLeave — Suspended đi qua đường riêng, còn OffShift và Resigned là trạng thái suy ra, không ai khai được.

Đến khi nào. Bắt buộc với Busy / Away / OnLeave, và phải nằm trong tương lai; bỏ qua với Available.

Ghi chú hiện cho quản lý và đồng nghiệp

Đặt, sửa hoặc xoá giờ làm việc riêng của một sale (KC-18) — cho chính mình hoặc cho người khác.

Cùng khuôn với : một model, hai endpoint với hai [Authorize] khác nhau (me/working-hours và staff/working-hours). Đường "của tôi" không đọc . Mọi trường giờ là string? và ngày làm là int[]? có chủ ý: assembly bật <Nullable>enable, nên một kiểu tham chiếu không-null bị ASP.NET Core suy ra [Required] ngầm — gửi null để xoá giờ riêng sẽ ăn 400 trước khi dòng code đầu tiên chạy (đúng lỗi L13 ghi ở ChatPresenceController.SearchDurations). Luật hợp lệ nằm ở ChatWorkingHours.ValidateStaffInput, không ở attribute, để API và đường dựng từ cột dùng chung một định nghĩa.

Người được đặt giờ. Bỏ qua ở đường "của tôi"; bắt buộc ở đường "đặt hộ".

Giờ bắt đầu làm việc, dạng HH:mm. Để trống cùng là xoá giờ riêng, về "chưa đặt" (luôn trong ca).

Giờ kết thúc làm việc, dạng HH:mm; 23:59 (hoặc 24:00) = làm tới hết ngày

Giờ bắt đầu nghỉ trưa, dạng HH:mm; trống cùng = không nghỉ trưa

Giờ kết thúc nghỉ trưa, dạng HH:mm

Ngày làm, mã 2 (Thứ Hai) … 7 (Thứ Bảy), 8 (Chủ Nhật); phải có ít nhất một ngày khi đặt giờ

Quản lý tạm ngưng chia khách cho một người, hoặc gỡ lệnh tạm ngưng.

Tạm ngưng đến khi nào. Bỏ trống là gỡ lệnh tạm ngưng.

Lý do tạm ngưng. Bắt buộc khi đặt, bỏ qua khi gỡ. Bắt buộc có chủ ý: §3.6 chọn "quản lý bấm tạm ngưng" làm đường cắt hẳn một người khỏi việc nhận khách, chính vì nó có tên người chịu trách nhiệm — một lệnh cắt không lý do thì bằng đúng cái công thức trọng số mà §3.6 vừa từ chối.

Uỷ quyền tạm bằng tay: giao hội thoại của một người đang không sẵn sàng cho người khác cùng kênh, người cũ vẫn giữ quyền đọc.

Người đang giữ hội thoại (đang nghỉ / bị tạm ngưng / ngoài giờ)

Người nhận tạm. Bỏ trống (0) là để hệ thống tự chọn người ít việc nhất đang sẵn sàng trong cùng kênh.

Ghi chú, ghi thẳng vào dòng lịch sử phân công

Tạo hoặc sửa một mẫu tin nhắn nhanh — dùng chung cho save-personal và save-shared (docs/plan-tin-nhan-nhanh-chat.md §3.3). Model này KHÔNG có, và không bao giờ được có, bốn trường: Scope, OwnerUserId, ImageUrl, ImageSystemPath. Phạm vi do endpoint quyết định — mỗi phạm vi một endpoint, gác bằng một role khác nhau. Chủ của mẫu cá nhân là người đang đăng nhập. Ảnh chỉ vào qua , máy chủ tự lưu và tự sinh đường dẫn. Thêm một trong bốn trường ấy là mở lại đúng lỗ mà §3.8 đóng; ca test Model_KhongNhanPhamViChuVaDuongDanTuClient canh điều này. Không khai thuộc tính kiểm tra dữ liệu: mọi luật (độ dài, định dạng phím tắt, trùng phím tắt) nằm ở ChatQuickReplyService để một luật chỉ có một chỗ, trả cùng một kiểu BaseResult với thông điệp tiếng Việt, và ca test gọi thẳng vào được.

Bỏ trống (hoặc 0) là tạo mới

Tên hiện trong danh sách chọn — bắt buộc, tối đa 200 ký tự

Từ khoá gõ sau dấu /; bỏ trống là không có phím tắt. Máy chủ bỏ dấu / gõ kèm và hạ chữ thường, rồi chỉ nhận [a-z0-9_-], tối đa 50 ký tự.

Nội dung mẫu — bắt buộc, tối đa 2.000 ký tự (giới hạn một tin của Zalo)

Thứ tự trong danh sách chọn, xét sau số lượt dùng

Ảnh mới cho mẫu — JPG/PNG, tối đa 1 MB. Bỏ trống là giữ nguyên ảnh đang có.

Bỏ ảnh khỏi mẫu: xoá hai cột ảnh, không xoá tệp trên đĩa — tin đã gửi từ mẫu vẫn đang trỏ vào tệp ấy (nguyên tắc 1.4). Có mới thì cờ này bị bỏ qua.

Gửi một tin vào hội thoại, xuất phát từ một mẫu tin nhắn nhanh (send-quick-reply). Không có, và không bao giờ được có, trường đường dẫn tệp. Client chỉ nói mẫu nào và có gửi kèm ảnh của mẫu hay không; máy chủ tra ảnh theo mã mẫu — cùng lý do SendChatImageModel nhận chính tệp chứ không nhận đường dẫn.

Mẫu xuất phát — phải thấy được với người gửi và đang bật

Nội dung gửi đi: chữ trong ô soạn sau khi nhân viên đã sửa và đã thay placeholder, không phải nội dung gốc của mẫu (§3.2). Với tin kèm ảnh thì đây là chú thích, có thể bỏ trống.

true = gửi kèm ảnh của mẫu; mẫu không có ảnh thì bị từ chối

Mã tin trong LADA được trả lời trích dẫn, như SendChatMessageModel.ReplyToMessageId. Tin kèm ảnh không trích dẫn được — luật đó nằm sẵn trong SendMessageAsync.

Gắn một hội thoại với hồ sơ khách hàng có sẵn trong hệ thống.

Từ khoá mà nhân viên đã dùng để tìm ra khách hàng này (thường là số điện thoại). Bắt buộc, và không phải để tìm lại: máy chủ chạy lại ĐÚNG đường gợi ý có phạm vi với từ khoá này rồi đối chiếu nằm trong kết quả. Không có bước đó thì endpoint gắn khách thành một máy tra tên khách hàng theo mã — gọi lần lượt 1, 2, 3… là đọc được tên của cả tệp khách hàng mà không cần từ khoá nào.

Có ghi thêm dấu vết liên hệ (tên + định danh nền tảng) vào hồ sơ khách hàng không. Ghi THÊM chứ không đè — cột đó là văn bản tự do đã có người nhập tay từ trước.

Phân công một hội thoại cho nhân viên. để trống nghĩa là GỠ phân công — đó là một hành động có thật ("tôi không cầm việc này nữa"), không phải dữ liệu thiếu.

Đổi trạng thái vòng đời của một hội thoại.

Nhả một hội thoại về hàng chờ.

không phải một nhãn hiển thị: nó quyết định người vừa nhả còn đọc được hội thoại nữa không (§6.2). Vì thế nó bắt buộc, và giao diện không có ô nào cho người dùng tự đặt cờ quyền đọc — cờ ấy suy ra từ lý do, ở ChatReleaseReasonRules.KeepsReadAccess.

Ghi chú bắt buộc — nhật ký chỉ có mã lý do thì tháng sau không ai đọc lại được

Thu hồi quyền xem một hội thoại của một nhân viên đã thôi giữ nó.

Nhân viên bị thu hồi quyền xem

Bắt buộc là lý do CẮT quyền xem (§6.2); lý do khác bị máy chủ từ chối

Chuyển một hội thoại sang nhân viên khác.

Người nhận hội thoại

Vì sao người cũ thôi giữ — quyết định phạm vi dữ liệu của họ (§6.2)

Dữ liệu hỏi danh sách Page mà một tài khoản Facebook đang quản lý. Điền đúng MỘT trong hai trường. là đường chuẩn: quản trị viên đã bấm "Đăng nhập bằng Facebook" và token đang nằm trong bộ nhớ máy chủ, trình duyệt không giữ gì. là đường dự phòng cho lúc ứng dụng Facebook chưa khai xong đường chuyển hướng. Cả hai đi trong THÂN request chứ không trên query string: query string bị ghi vào nhật ký truy cập của mọi proxy và của chính máy chủ, mà đây là bí mật mở được cả tệp Page.

User access token dán từ Graph API Explorer. Máy chủ tự đổi sang bản dài hạn rồi dùng để hỏi /me/accounts; giá trị này KHÔNG bao giờ được lưu xuống database.

Chuỗi state của phiên Facebook Login vừa hoàn tất, lấy từ GET facebook/authorization-url. Không phải bí mật tự thân — nó chỉ mở được phiên của đúng người đã bấm cấp quyền, và chỉ trong 10 phút.

Dữ liệu kết nối một Page cụ thể thành kênh chat.

Định danh Page được chọn ở bước trước

Dữ liệu tải một ảnh lên rồi gửi vào hội thoại. Model này KHÔNG có, và không bao giờ được có, trường đường dẫn tệp. Chỉ có chính tệp () — máy chủ lưu rồi tự sinh đường dẫn. Nhận đường dẫn từ client là mở đường đọc tệp bất kỳ trên máy chủ rồi gửi thẳng ra ngoài cho khách.

Chú thích đi kèm ảnh, có thể bỏ trống

Tệp ảnh — JPG hoặc PNG, tối đa 1 MB (giới hạn của Zalo)

Dữ liệu nhân viên gửi lên khi trả lời một hội thoại. Cố ý rất hẹp. Mọi thứ khác — kênh nào, gửi cho ai, gửi bằng token nào — đều tra từ hội thoại phía máy chủ, vì đó là những giá trị quyết định tin đi tới đâu. Trường thứ ba thêm ở giai đoạn G cũng theo đúng luật ấy: nó mang mã tin nội bộ, không mang mã tin của nền tảng.

Nội dung văn bản. Zalo giới hạn 2.000 ký tự, tầng ZaloApiService kiểm lại.

Mã tin trong LADA mà tin này trả lời trích dẫn; bỏ trống là tin thường. Cố ý KHÔNG nhận mã tin của nền tảng. Máy chủ tra mã ấy ra từ mã nội bộ này, và tra theo CẶP (tin, hội thoại) — nhận thẳng mã nền tảng thì không kiểm được nó thuộc hội thoại nào, và một mã đoán được sẽ kéo nội dung của khách khác vào câu trả lời gửi ra ngoài.

Dữ liệu nhân viên gửi lên khi thả hoặc gỡ một biểu tượng cảm xúc trên một tin nhắn. Cùng luật với : chỉ mang mã tin nội bộ, còn kênh nào, gửi cho ai, gửi bằng token nào đều tra từ hội thoại phía máy chủ. Nhận mã tin của nền tảng từ client thì không kiểm được nó thuộc hội thoại nào.

Mã tin trong LADA cần thả biểu tượng cảm xúc

Ký tự emoji cần thả. Bỏ trống nghĩa là GỠ biểu tượng đang có; gửi lại đúng biểu tượng đang hiển thị cũng được hiểu là gỡ, đúng thói quen bấm ở chính hai nền tảng. Là emoji thật chứ không phải mã riêng của nền tảng — việc đổi sang react_icon của Zalo làm ở tầng nền tảng. Zalo chỉ nhận sáu biểu tượng và sẽ từ chối phần còn lại; danh sách hợp lệ của từng hội thoại nằm ở ChatConversationItem.ReactionEmojis.

Model tạo/cập nhật khóa học

Model tạo/cập nhật section

Model tạo/cập nhật bài giảng

Model đổ dầu cho lái xe trên app mobile. Lái xe là người đăng nhập, xe là xe đang phụ trách (tự động xác định).

ID thẻ xăng dầu (nullable - có thể của mình hoặc người khác, hoặc trả tiền mặt)

QR Code được quét từ thẻ (thay thế FuelCardId khi đổ bằng thẻ)

ODO hiện tại khi đổ dầu

Số tiền đổ dầu

Đơn giá dầu (VND/lít)

Phương thức thanh toán: Card(1) hoặc Cash(2)

Tên cây xăng

Địa chỉ cây xăng

Thời gian đổ dầu

Ghi chú

Danh sách hình ảnh (ODO trước, ODO sau, cây dầu, hóa đơn)

Loại hình ảnh tương ứng (OdoBeforePhoto, OdoAfterPhoto, FuelPumpPhoto, FuelReceiptPhoto) Phải tương ứng 1-1 với Files

Dữ liệu tạo/sửa garage

Tên garage

Địa chỉ

Số điện thoại

Người liên hệ

Ghi chú

Còn sử dụng hay không

Payload multipart đọc phiếu bằng AI lúc TẠO MỚI bản ghi bảo dưỡng (QĐ3-3) — tệp chỉ được đọc, không lưu làm media.

Phiếu / hoá đơn: ảnh (JPG, PNG, WebP, HEIC) hoặc PDF.

Xe đang chọn trên form — phải thuộc phạm vi chi nhánh của người gọi.

Gắn một lượt đọc lúc tạo mới vào bản ghi vừa lưu.

Dòng media vừa tải lên từ cùng tệp (nếu có).

Ghi nhớ một tên gọi khác cho loại bộ phận K200.

Tên như trên phiếu, ví dụ "nhớt", "bố thắng".

Số ODO hiện tại của xe (chỉ áp dụng cho hoạt động đổ dầu)

Đơn giá

Model cho việc nhận/trả xe tải

ID xe tải

ID đại lý (tự động lấy từ thông tin người dùng)

Ghi chú

Số ODO hiện tại của xe (bắt buộc, >= 0)

Danh sách file hình ảnh upload

Dữ liệu gắn/sửa bộ phận trên xe

Xe

Loại bộ phận

Vị trí trên xe (giá trị enum ComponentPosition; 0 = không theo vị trí)

Ngày lắp

ODO lúc lắp. Bỏ trống thì hệ thống lấy ODO hiện tại của xe.

Nguồn gốc (giá trị enum ComponentSource: 1 = nguyên bản nhà máy, 2 = đã thay mới)

Tuổi thọ theo km riêng cho bộ phận này

Tuổi thọ theo tháng riêng cho bộ phận này

Ghi chú

Còn đang lắp trên xe hay không

Yêu cầu khởi tạo bộ bộ phận hàng loạt cho một xe từ danh mục đang bật

Xe cần khởi tạo bộ phận

Chỉ khởi tạo các loại bộ phận này. Bỏ trống = mọi loại đang bật và KHÔNG yêu cầu vị trí (loại theo vị trí như lốp phải gắn tay vì số lượng phụ thuộc cấu hình trục của từng xe).

Ngày lắp áp dụng chung. Bỏ trống = hôm nay.

ODO lúc lắp áp dụng chung. Bỏ trống = ODO hiện tại của xe.

Nguồn gốc áp dụng chung (mặc định 1 = nguyên bản nhà máy)

Dữ liệu tạo/sửa loại bộ phận xe

Mã loại bộ phận

Tên hiển thị

Tuổi thọ mặc định theo km

Tuổi thọ mặc định theo tháng

Có gắn với vị trí trên xe hay không

Ngưỡng cảnh báo trước theo km (null = dùng mặc định toàn cục)

Ngưỡng cảnh báo trước theo ngày (null = dùng mặc định toàn cục)

Nhóm phân loại

Số lượng trên mỗi xe, dạng chữ tham khảo (tối đa 128 ký tự)

Chi phí tham khảo dạng chữ (tối đa 256 ký tự)

Ghi chú

Còn dùng hay không

Thứ tự hiển thị

Model cho hoạt động đổ dầu xe tải

ID của xe tải

ID của đại lý (tự động lấy từ thông tin người dùng)

Số ODO hiện tại của xe

Ghi chú về việc đổ dầu

Danh sách file ảnh đổ dầu (tối thiểu 2, tối đa 5)

Payload multipart tải tệp đính kèm cho một lần bảo dưỡng.

Lần bảo dưỡng nhận tệp

Loại tệp — giá trị enum TruckMaintenanceMediaType: 1 hoá đơn, 2 ảnh hiện trạng

Các tệp ảnh

Đối tượng đại diện cho thông tin bảo dưỡng xe tải.

Id của đại lý.

Id của xe tải.

Tiêu đề của hoạt động bảo dưỡng.

Mô tả của hoạt động bảo dưỡng.

Id của người dùng thực hiện bảo dưỡng.

Tên của gara thực hiện bảo dưỡng.

Địa chỉ của gara thực hiện bảo dưỡng.

Số điện thoại của gara thực hiện bảo dưỡng.

Chi phí bảo dưỡng.

Có hóa đơn hay không.

URL của hóa đơn.

Thời gian bắt đầu bảo dưỡng.

Thời gian kết thúc bảo dưỡng.

Thời gian bảo dưỡng tiếp theo.

Garage chọn từ danh mục. Null = không nhắc tới (màn cũ nhập garage bằng ba trường chuỗi).

Luồng cập nhật chỉ ghi đè khi trường này có giá trị — payload kiểu cũ thiếu trường mới không được phép xoá trắng dữ liệu màn mới đã nhập (§3.11 dòng bẫy DTO).

Chỉ số ODO của xe tại thời điểm bảo dưỡng — mốc reset tuổi thọ khi thay bộ phận mới. Null = không nhắc tới.

Danh sách các liên kết bảo dưỡng xe tải.

null nghĩa là payload không nhắc tới dòng công việc nào ⇒ giữ nguyên toàn bộ dòng đang có. Danh sách rỗng mới là lệnh xoá hết dòng không gắn bộ phận.

Id các dòng công việc cần xoá — cách duy nhất để xoá một dòng đã gắn bộ phận.

Dòng gắn bộ phận không được suy ra ý định xoá từ việc payload thiếu nó: màn cũ không hề biết trường TruckComponentId tồn tại nên payload của nó luôn "thiếu" (nợ BD-8). Muốn xoá thì phải nói ra.

Gỡ hẳn garage khỏi bản ghi (đặt GarageId về null).

Cần một cách nói tường minh vì GarageId = null đã mang nghĩa "không nhắc tới" — nếu không thì màn mới không bao giờ gỡ được garage đã chọn nhầm. Cờ này thắng GarageId: gửi cả hai thì garage bị gỡ.

Gỡ hẳn chỉ số ODO khỏi bản ghi (đặt Odo về null). Cùng lý do với .

Tham số xoá một lần bảo dưỡng — chỉ cần Id.

Không dùng lại : các trường bắt buộc của nó (Title, Description, GarageName, InvoiceUrl) làm mọi payload chỉ có Id bị chặn ở bước kiểm tra model và trả 400 trước khi vào action — nút "Xóa lần bảo dưỡng" vì thế chưa từng xoá được. Hình dạng này khớp với tài liệu API và với màn đang gọi.

Id của lần bảo dưỡng cần xoá.

Hạng mục theo danh mục cũ; null hoặc 0 = không có (dòng phải gắn bộ phận thay vào đó)

Bộ phận trên xe mà dòng công việc này chạm tới. Null = dòng không gắn bộ phận (dữ liệu lịch sử, hoặc màn cũ chưa gửi trường này).

Null nghĩa là "không nhắc tới", không phải "hãy xoá". Màn cũ /bao-tri-xe-tai không gửi ba trường mới của dòng công việc — nợ BD-8 chính là việc luồng lưu cũ hiểu nhầm sự vắng mặt này thành lệnh xoá.

Hành động lên bộ phận: thay mới / đảo vị trí / sửa / kiểm tra. Null = không nhắc tới.

Chi phí riêng của dòng công việc. Null = không nhắc tới.

Gỡ bộ phận khỏi dòng đã lưu (kéo theo gỡ ) và tính lại mốc lắp của bộ phận vừa gỡ. Cần cờ riêng vì TruckComponentId = null nghĩa là "không nhắc tới" (BD-8) — không có cờ này thì dòng "Thay mới" gắn nhầm bộ phận không gỡ được, mốc lắp đã reset nằm sai mãi (finding review GĐ E). Cùng họ với ClearGarageId/ClearOdo của bản ghi.

Gỡ hành động khỏi dòng đã lưu (giữ bộ phận); mốc lắp của bộ phận được tính lại

Biển số xe (bắt buộc, tối đa 20 ký tự)

Thương hiệu xe tải (ví dụ: "Kia", "Hyundai", "Isuzu")

Model xe tải (ví dụ: "K200", "Porter", "D-Max")

ID chi nhánh mà xe tải thuộc về

Tải trọng tối đa cho phép (tấn)

Chiều dài khu vực chứa hàng (cm)

Chiều rộng khu vực chứa hàng (cm)

Chiều cao khu vực chứa hàng (cm)

Trạng thái vận hành hiện tại (Running/Stop)

Trạng thái xe tải (Normal/Broken/Maintenance/etc)

ID tài xế hiện đang phụ trách xe

Năm sản xuất của xe tải

Thông tin đăng kiểm (tối đa 200 ký tự)

Định mức khoán xăng dầu (lít/100km)

Danh sách file ảnh upload mới

Loại media tương ứng với từng file (RegistrationPhoto, InspectionPhoto)

Danh sách ID TruckMedia hiện có cần giữ lại (khi cập nhật). ID = 0 nghĩa là vị trí đó cần upload file mới.

Model để đổi mật khẩu của người dùng

ID của người dùng cần đổi mật khẩu

Mật khẩu hiện tại

Mật khẩu mới

Xác nhận mật khẩu mới

ID người cập nhật

Tên người cập nhật

Thông tin tạo tài khoản đăng nhập kiểu khách hàng.

Thông tin nhân thân (họ tên, email, số điện thoại, địa chỉ) do tầng gọi lấy từ hồ sơ khách hàng, KHÔNG lấy từ request — người quản trị chỉ được đặt tên đăng nhập và mật khẩu.

Mã đại lý của người dùng

Mã chấm công (khớp với máy chấm công vân tay)

ID người cập nhật

Tên người cập nhật

ID người quản lý trực tiếp (từ UserPreference.ManagerId)

Tên người quản lý trực tiếp (readonly, để hiển thị)

Tên đăng nhập người quản lý trực tiếp (readonly, để hiển thị)

Phạm vi truy cập dữ liệu (0=SelfOnly, 10=ManagedTeam, 20=All)

Số tiền tạm ứng lương hiện tại trong tháng

Tổng hạn mức cọc trách nhiệm yêu cầu của lái xe (tối đa 5,000,000 đ)

Số tiền cọc trách nhiệm đã đóng lũy kế

Số tiền cọc trách nhiệm cấn trừ hàng tháng qua lương

Mã chấm công (khớp với mã máy chấm công vân tay khi import)

Ánh xạ cho module quảng cáo đa nền tảng. Nguyên tắc bảo mật: mọi credential đều đi qua — DTO không bao giờ mang giá trị gốc.

Che thông tin mật để trả ra API: giữ 4 ký tự đầu và 4 ký tự cuối. Chuỗi quá ngắn thì che hoàn toàn — thà mất tiện lợi hơn để lộ credential.

Đọc mảng text lưu dạng JSON trong entity. JSON hỏng thì trả danh sách rỗng thay vì ném lỗi — một bản ghi lỗi không nên làm sập cả trang danh sách.

Thứ trong tuần sang tiếng Việt. Không dùng CultureInfo("vi-VN") vì .NET trả "Thứ Hai" ở dạng khác nhau tuỳ phiên bản ICU của máy chủ — bảng cứng cho kết quả ổn định.

Khoảng giờ dạng "08:00 – 17:00". Giờ kết thúc 24 giữ nguyên là "24:00" (Google dùng 24 nghĩa là hết ngày) — đổi thành 00:00 sẽ đọc thành nửa đêm hôm trước.

Hệ số giá thầu của Google sang phần trăm để hiển thị: 1,2 → "+20%"; 0,5 → "-50%"; 1,0 → "0%"; 0,0 → "-100%"; null → "—". null và 0 là hai chuyện khác nhau: null = nền tảng không đặt điều chỉnh, 0 = đặt -100%. Gộp lại sẽ hiển thị sai hoàn toàn ý định của người đặt lịch.

Trạng thái duyệt của nền tảng sang tiếng Việt. Giá trị lạ thì giữ nguyên chuỗi gốc chứ không đoán thành "Đã duyệt" — nói sai chỗ này là để quảng cáo bị từ chối trông như đang chạy bình thường.

Nội dung từ khoá kèm ký hiệu kiểu khớp theo đúng cách Google Ads hiển thị: khớp chính xác là [từ khoá], khớp cụm từ là "từ khoá", khớp rộng để trần. Ký hiệu này là quy ước người chạy quảng cáo đọc quen — hiển thị trần hết sẽ làm ba kiểu khớp trông giống nhau.

Giá thầu riêng của từ khoá. null hiển thị "theo nhóm" chứ không để trống: ô trống đọc thành "không có giá thầu", còn thực tế là dùng giá thầu của nhóm.

Các hàm mở rộng ánh xạ cho module quảng cáo.

Chỉ nói có key hay chưa và đã mã hoá chưa — không in ký tự nào của key (bản cũ in 4 ký tự đầu + 4 ký tự cuối của bản rõ). Form sửa không gửi lại chuỗi này (mở form là ô key trống — ProviderModal.vue).

Extension methods cho mapping Bank entities

Convert BankAccount entity sang BankAccountItem

Convert BankTransaction entity sang BankTransactionItem

Convert BankStatementImport entity sang BankStatementImportItem

Convert Bank entity sang BankItem

Convert Bank entity sang BankModel

Convert BankModel sang Bank entity

Convert Bank entity sang BankOptionItem

Format file size

Ánh xạ entity kho nội dung AI → DTO. Các cột *Json của bài (AltTitles, Brief, Faq, Footer, SelfScore…) và hai collection ô/ảnh được Ignore ở đây — service tự parse và sắp thứ tự, để profile không giấu lỗi JSON và không phụ thuộc Include. Mapping chạy in-memory nên gọi được trong MapFrom (TextOnImage của ảnh).

Extension ánh xạ cho miền kho nội dung — theo quy ước .ToItem() của repo.

Bản đầy đủ chưa có phần JSON/ô/ảnh — service gọi rồi điền tiếp.

AutoMapper profile cho domain Email (tài khoản gửi + nhật ký). Lưu ý: secret (Password/SecretKey) KHÔNG map ra Item — chỉ suy ra cờ Has*.

Extension mapping tiện dụng (giống CrmMappingExtensions).

Lấy tên hiển thị của trạng thái chi phí

Helper methods cho Transaction mapping

Lấy icon cho loại giao dịch

Tạo mô tả ngắn gọn cho giao dịch

Extension methods để map giữa FuelCard entities và items

Chuyển đổi FuelCardTransaction entity sang FuelCardTransactionItem

Extension ánh xạ cho cấu hình danh mục hàng hóa động

Mapping cho cấu hình danh mục hàng hóa động

Ánh xạ Bảng tin nội bộ. Trường tính theo người xem (đã đọc, tên tác giả, đang ghim theo giờ hiện tại) do service điền sau khi ánh xạ — profile chỉ chép cột.

Chép các trường người soạn được sửa vào bài đang có (hoặc bài mới).

AutoMapper profile cho các ánh xạ liên quan đến Truck.

Item báo cáo đổ dầu thực tế theo ngày

Ngày đổ dầu

Số lần đổ dầu trong ngày (số phiếu)

Tổng số km chạy trong ngày

Số lít đổ dầu thực tế trong ngày

Số tiền đổ dầu thực tế trong ngày

Đơn giá bình quân gia quyền trong ngày (tổng tiền / tổng lít)

Tiền đổ bằng thẻ trong ngày (PaymentMethod = Card)

Tiền đổ bằng tiền mặt trong ngày (PaymentMethod = Cash)

Chi tiết theo lái xe và xe trong ngày

Chi tiết đổ dầu thực tế theo lái xe và xe trong 1 ngày

ID lái xe

Tên đăng nhập lái xe

Họ và tên lái xe

ID xe

Biển số xe

Tên xe

Trạng thái phiếu đổ dầu (0: Pending, 1: Approved, 2: Rejected)

Số lần đổ dầu (số phiếu)

Số km chạy

Số lít đổ dầu thực tế

Số tiền đổ dầu thực tế

Đơn giá bình quân gia quyền (tổng tiền / tổng lít)

Tiền đổ bằng thẻ (PaymentMethod = Card)

Tiền đổ bằng tiền mặt (PaymentMethod = Cash)

Item báo cáo đổ dầu thực tế theo lái xe

ID lái xe

Tên đăng nhập lái xe

Họ và tên lái xe

Số lần đổ dầu (số phiếu)

Số km chạy trong tháng (tổng DistanceKm)

Số lít đổ dầu thực tế (tổng ActualLiters)

Số tiền đổ dầu thực tế (tổng Amount)

Đơn giá bình quân gia quyền (tổng tiền / tổng lít)

Tiền đổ bằng thẻ (PaymentMethod = Card)

Tiền đổ bằng tiền mặt (PaymentMethod = Cash)

Chi tiết số liệu theo từng xe mà lái xe đã chạy

Item chi tiết đổ dầu thực tế theo xe (dùng trong báo cáo theo lái xe)

ID xe

Biển số xe

Tên xe

Số lần đổ dầu (số phiếu)

Số km chạy trong khoảng thời gian (tổng DistanceKm)

Số lít đổ dầu thực tế (tổng ActualLiters)

Số tiền đổ dầu thực tế (tổng Amount)

Đơn giá bình quân gia quyền (tổng tiền / tổng lít)

Tiền đổ bằng thẻ (PaymentMethod = Card)

Tiền đổ bằng tiền mặt (PaymentMethod = Cash)

Item báo cáo tổng hợp đổ dầu thực tế theo xe

ID xe

Biển số xe

Tên xe

Số lần đổ dầu (số phiếu)

Số km chạy (tổng DistanceKm)

Số lít đổ dầu thực tế (tổng ActualLiters)

Số tiền đổ dầu thực tế (tổng Amount)

Đơn giá bình quân gia quyền (tổng tiền / tổng lít)

Tiền đổ bằng thẻ (PaymentMethod = Card)

Tiền đổ bằng tiền mặt (PaymentMethod = Cash)

Chi tiết số liệu theo từng lái xe đã đổ dầu cho xe này

Item chi tiết đổ dầu thực tế theo lái xe (dùng trong báo cáo theo xe)

ID lái xe

Tên đăng nhập lái xe

Họ và tên lái xe

Số lần đổ dầu (số phiếu)

Số km chạy (tổng DistanceKm)

Số lít đổ dầu thực tế (tổng ActualLiters)

Số tiền đổ dầu thực tế (tổng Amount)

Đơn giá bình quân gia quyền (tổng tiền / tổng lít)

Tiền đổ bằng thẻ (PaymentMethod = Card)

Tiền đổ bằng tiền mặt (PaymentMethod = Cash)

Một dòng doanh số của một bưu cục bán hàng — kết quả sp_GetAgencyRevenueStatistics.

"Bưu cục bán hàng" là Order.SaleAgencyId (bưu cục của sale, đóng dấu lúc tạo đơn), không phải bưu cục vận hành đơn. Xem chú thích ngữ nghĩa đầy đủ trong chính file SP.

ID bưu cục bán hàng

Số đơn tính vào doanh số của bưu cục trong khoảng

Tổng cước sau VAT (OrderFin.TotalFeeAfterVat, SP cộng tay 7 thành phần)

Item nhóm báo cáo năng suất lái xe (chứa tổng và chi tiết từng ngày)

ID lái xe

Tên đăng nhập lái xe

Tên đầy đủ lái xe

Tổng số lượng đơn hàng lấy hàng trong khoảng thời gian

Tổng số lượng đơn hàng giao hàng trong khoảng thời gian

Tổng số lượng đơn hàng trong khoảng thời gian

Chi tiết theo từng ngày

Item báo cáo năng suất lái xe theo ngày

ID lái xe

Tên đăng nhập lái xe

Tên đầy đủ lái xe

Ngày hoạt động

Số lượng đơn hàng lấy hàng trong ngày

Số lượng đơn hàng giao hàng trong ngày

Tổng số lượng đơn hàng trong ngày

Tên ngày trong tuần

Thời gian bắt đầu (từ tham số)

Thời gian kết thúc (từ tham số)

Bản ghi báo cáo doanh số theo khách hàng

ID của khách hàng

Mã khách hàng

Tên khách hàng

Số điện thoại khách hàng

ID Sale quản lý khách hàng

Tên Sale quản lý khách hàng

Tổng số đơn hàng

Tổng doanh số

Tổng tiền thu hộ

Tổng số bản ghi (dùng cho phân trang)

Kiểm tra có phải dòng tổng cộng không

Tổng số đơn đang xử lý (chưa hoàn thành)

Tổng số đơn thất bại

Tổng số đơn hoàn thành

Tỷ lệ thành công (%)

Tổng doanh số đơn đang xử lý

Tổng doanh số đơn thất bại

Tổng doanh số đơn hoàn thành

Tổng tiền thu hộ đơn đang xử lý

Tổng tiền thu hộ đơn thất bại

Tổng tiền thu hộ đơn hoàn thành

Chi tiết đơn hàng tồn đọng (drill-down từ bảng tổng hợp)

ID đơn hàng

Mã đơn hàng

Trạng thái đơn hàng

Trạng thái vật lý

Nội dung trạng thái (mô tả)

Thời gian cập nhật lần cuối

Số ngày tồn đọng

Tổng số bản ghi (dùng cho phân trang)

DTO chứa thống kê tồn đọng đơn hàng theo trạng thái và thời gian

Mã bưu cục (dùng cho phân nhóm theo Agency)

Tên bưu cục

Tên nhóm trạng thái (VD: "Tạo mới", "Đang lấy hàng", ...)

Thứ tự sắp xếp trạng thái

Số đơn cập nhật hôm nay (0 ngày trước)

Số đơn cập nhật 1 ngày trước

Số đơn cập nhật 2 ngày trước

Số đơn cập nhật 3 ngày trước

Số đơn cập nhật 4 ngày trước

Số đơn cập nhật 5 ngày trước

Số đơn cập nhật 6 ngày trước

Số đơn cập nhật 7 ngày trước

Số đơn cập nhật trên 7 ngày trước

Tổng số đơn theo trạng thái

Tổng cước D0

Tổng cước D1

Tổng cước D2

Tổng cước D3

Tổng cước D4

Tổng cước D5

Tổng cước D6

Tổng cước D7

Tổng cước D7+

Tổng cước tất cả

Bản ghi báo cáo sản lượng

Chuỗi hiển thị ngày, nếu là ngày tổng hợp thì hiển thị "TỔNG CỘNG"

Kiểm tra xem có phải là dòng tổng cộng không

Tổng số đơn đang xử lý

Tổng số đơn thất bại

Tổng số đơn hoàn thành

Tỷ lệ thành công

DTO cho báo cáo số lượng đơn và doanh số theo tuyến

Tên tuyến (Tỉnh/Thành gửi - Tỉnh/Thành nhận)

Tên tỉnh/thành phố gửi hàng

Tên tỉnh/thành phố nhận hàng

Tên trạng thái đơn hàng

Thứ tự sắp xếp trạng thái (1-6)

Số lượng đơn hàng

Tổng doanh số

Doanh số trung bình

Doanh số thấp nhất

Doanh số cao nhất

Ngày bắt đầu lọc

Ngày kết thúc lọc

Một dòng báo cáo doanh số theo bưu cục (sp_GetOrderRevenueByAgency). Bưu cục của đơn = Order.SaleAgencyId — bưu cục của sale lúc tạo đơn, cùng trục với KPI agency.revenue.

Id bưu cục.

Mã bưu cục.

Tên bưu cục.

Bưu cục đã xoá mềm — service điền, không phải cột SP. Founder/kế toán vẫn thấy dòng này để tổng báo cáo bằng tổng KPI (plan §6.3, DS-7); giao diện gắn nhãn "(đã ngừng)".

Bản ghi báo cáo doanh thu đơn hàng theo ngày nhận tiền (Collection Date) Chỉ bao gồm thống kê tài chính (không có thống kê trạng thái triển khai)

Ngày công ty nhận tiền

Chuỗi hiển thị ngày, nếu là ngày tổng hợp thì hiển thị "TỔNG CỘNG"

Tổng số đơn (trừ hủy)

Tổng doanh thu (trừ hủy)

Số đơn chưa thanh toán

Doanh thu chưa thanh toán

Số đơn chờ xác nhận

Doanh thu chờ xác nhận

Số đơn đã thanh toán

Doanh thu đã thanh toán

Doanh thu ghi nhận (đã trừ VAT 8%)

Kiểm tra xem có phải là dòng tổng cộng không

Tỷ lệ thanh toán (%)

Tỷ lệ chưa thanh toán (%)

Tỷ lệ chờ xác nhận (%)

Bản ghi báo cáo doanh thu theo Sale (chỉ thống kê tài chính)

ID nhân viên sale

Tên nhân viên sale

Tên đăng nhập nhân viên sale

Tổng số đơn (trừ hủy)

Tổng doanh thu (trừ hủy)

Số đơn chưa thanh toán

Doanh thu chưa thanh toán

Số đơn chờ xác nhận

Doanh thu chờ xác nhận

Số đơn đã thanh toán

Doanh thu đã thanh toán

Doanh thu ghi nhận (đã trừ VAT 8%)

Một dòng báo cáo doanh số theo nhóm (sp_GetOrderRevenueByTeam). Nhóm của đơn = UserPreference.ManagerId của sale tạo đơn — quản lý trực tiếp, không đệ quy.

Id quản lý trực tiếp; 0 = dòng "Chưa có quản lý trực tiếp".

Tên nhóm = họ tên quản lý (SP đã đặt sẵn tên cho dòng 0).

Số sale có đơn trong kỳ thuộc nhóm — không phải số người dưới quyền.

Một dòng báo cáo doanh số theo phường/xã (sp_GetOrderRevenueByWard) của điểm lấy hoặc điểm giao. Chỉ nhóm theo xã bộ 2 cấp; địa chỉ hệ cũ gom vào một dòng WardId = 0.

Id xã 2 cấp; 0 = "Địa chỉ hệ 3 cấp cũ (chưa quy đổi)".

Tên xã ("Phường Ba Đình"); SP đã đặt sẵn tên cho dòng 0.

Tỉnh/thành phố của xã; null ở dòng 0.

Bưu cục phụ trách vùng phủ (Location.AgencyId); null khi xã chưa có.

Tên bưu cục phụ trách vùng phủ.

Một đơn trong danh sách drill-down của một ô báo cáo doanh số theo chiều (sp_GetOrderRevenueDetail).

Id đơn.

Mã đơn.

Thời điểm tạo đơn — mốc của kỳ báo cáo.

Mã OrderStatus; null khi đơn không có dòng OrderOps.

Tên trạng thái đơn — mô tả của , để giao diện không giữ bảng tên riêng. Đơn không có dòng OrderOps hoặc mang mã ngoài enum hiện "Không xác định", đúng nhóm mà view xếp chúng vào.

Nhóm trạng thái OrderStatusGroup (1–4).

Doanh số của đơn (7 khoản, gồm VAT).

Tên khách hàng.

Tên sale tạo đơn.

Tên bưu cục bán (Order.SaleAgencyId).

Tổng số đơn của ô (lặp ở mọi dòng, COUNT(*) OVER()) — service chuyển thành TotalRecord.

Bản ghi báo cáo doanh thu đơn hàng theo ngày

Chuỗi hiển thị ngày, nếu là ngày tổng hợp thì hiển thị "TỔNG CỘNG"

Kiểm tra xem có phải là dòng tổng cộng không

Tổng số đơn đang xử lý

Tổng số đơn thất bại

Tổng số đơn hoàn thành

Tỷ lệ thành công

Tổng doanh số đơn đang xử lý

Tổng doanh số đơn thất bại

Tổng doanh số đơn hoàn thành

Tổng tiền thu hộ đơn đang xử lý

Tổng tiền thu hộ đơn thất bại

Tổng tiền thu hộ đơn hoàn thành

Bốn cặp (số đơn, doanh số) theo nhóm trạng thái OrderStatusGroup + tổng — phần chung của mọi dòng báo cáo doanh số theo chiều (bưu cục / nhóm / phường xã) và của dòng tổng cộng.

Tên property trùng tên cột của sp_GetOrderRevenueBy* để Dapper ánh xạ thẳng. Doanh số = 7 khoản OrderFin (đúng TotalFeeAfterVat, gồm VAT), tính theo ngày tạo đơn — công thức nằm duy nhất ở view vw_OrderRevenueFact (plan-bao-cao-doanh-so-theo-chieu §3.1).

Số đơn nhóm Tạo mới.

Doanh số nhóm Tạo mới.

Số đơn nhóm Đang triển khai.

Doanh số nhóm Đang triển khai.

Số đơn nhóm Đã triển khai.

Doanh số nhóm Đã triển khai.

Số đơn nhóm Huỷ.

Doanh số nhóm Huỷ.

Tổng số đơn của dòng (cả 4 nhóm).

Tổng doanh số của dòng (cả 4 nhóm, kể cả Huỷ).

Cộng dồn các dòng thành dòng "Tổng cộng" — SP không trả dòng tổng.

Bản ghi báo cáo công nợ theo sale

ID của sale

Tên sale

Số điện thoại sale

Tổng số đơn hàng

Tổng doanh số

Tổng tiền đã thu

Tổng công nợ (doanh số - đã thu)

Số đơn hàng chưa thu

Số đơn hàng đã thu

Tỷ lệ thu hộ (%)

Ngày cập nhật cuối

Bản ghi báo cáo doanh thu theo sale

ID của sale

Tên sale

Số điện thoại sale

Tổng số đơn hàng

Tổng doanh số

Tổng tiền thu hộ

Kiểm tra có phải dòng tổng cộng không

Tổng số đơn đang xử lý (chưa hoàn thành)

Tổng số đơn thất bại

Tổng số đơn hoàn thành

Tỷ lệ thành công (%)

Tổng doanh số đơn đang xử lý

Tổng doanh số đơn thất bại

Tổng doanh số đơn hoàn thành

Tổng tiền thu hộ đơn đang xử lý

Tổng tiền thu hộ đơn thất bại

Tổng tiền thu hộ đơn hoàn thành

Kết quả báo cáo Công nợ phải thu khách hàng Tracking cước phí khách hàng nợ chưa trả (PayFeeType = BankTransfer)

Kết quả quyền truy cập báo cáo doanh thu theo khách hàng

User có thể chọn sale để lọc hay không true = Founder/Accountant (có thể chọn sale) false = Sale (chỉ xem được khách hàng của mình)

User có thể chọn nhiều khách hàng hay không true = Founder/Accountant false = Sale

Kết quả báo cáo doanh số theo khách hàng

Kết quả báo cáo năng suất lái xe theo ngày

Cập nhật item tổng hợp từ danh sách items

Tổng quan tình hình tài chính — Financial Health Overview Tổng hợp 12 KPIs: Profitability (5) + Liquidity (5) + Franchise (2)

Tổng doanh thu cước (30 ngày gần nhất)

Tổng biến phí vận hành (Expense nhóm 6421, Paid)

Tổng định phí (Expense nhóm 6422 + Lãi vay, Paid)

Lãi vay xe (LoanRepaymentSchedule.InterestAmount, Paid)

Lợi nhuận gộp = Revenue - Variable Cost

Gross Margin % = GrossProfit / Revenue × 100

EBITDA = GrossProfit - FixedCost

EBITDA Margin % = EBITDA / Revenue × 100

Lợi nhuận ròng ước tính = EBITDA - InterestExpense - Tax(20%)

Net Margin % = NetProfit / Revenue × 100

Tổng số đơn hàng trong kỳ

Doanh thu bình quân mỗi đơn = Revenue / TotalOrders

Chi phí bình quân mỗi đơn = TotalCost / TotalOrders

DSO — Days Sales Outstanding (đã tính sẵn)

Số phiếu đối soát dùng tính DSO

DPO — Days Payable Outstanding = Avg(PaymentsDate - CreatedTime) của Expense

Float Period — Trung bình ngày chiếm dụng vốn thẻ tín dụng

Cash Conversion Cycle = DSO - DPO (âm = tốt)

DSCR — Debt Service Coverage Ratio = Operating Cash Flow / Debt Service

Tổng nợ ngắn hạn

Nợ thẻ dầu

Nợ vay xe 30 ngày tới

Nợ COD chưa đối soát

Số khoản trả góp quá hạn

Tổng công nợ phải thu

Số khách hàng đang nợ

Nợ quá 30 ngày

AR Aging breakdown

Tổng thu vào 30 ngày

Tổng chi ra 30 ngày

Dòng tiền ròng 30 ngày

Vốn lưu động = AR - Short-term Liabilities

Đánh giá tổng thể: Healthy / Warning / Critical

Điểm sức khỏe tài chính (0-100)

Danh sách cảnh báo

Ngày bắt đầu kỳ phân tích

Ngày kết thúc kỳ phân tích

Mã cảnh báo (VD: AR-01, LOAN-01)

Mức độ: Critical / Warning / Info

Nội dung cảnh báo

Nhóm: AR / Loan / FuelCard / CashFlow / Expense

Kết quả báo cáo đổ dầu theo ngày

Danh sách báo cáo theo từng ngày

Dòng tổng hợp

Tổng số bản ghi

Cập nhật item tổng hợp từ danh sách items

Kết quả báo cáo đổ dầu theo lái xe

Danh sách báo cáo theo từng lái xe

Dòng tổng hợp

Tổng số bản ghi

Cập nhật item tổng hợp từ danh sách items

Kết quả báo cáo đổ dầu thực tế theo xe

Danh sách báo cáo theo từng xe

Dòng tổng hợp

Tổng số bản ghi

Cập nhật item tổng hợp từ danh sách items

Nhóm thống kê tồn đọng theo bưu cục

Mã bưu cục

Tên bưu cục

Danh sách thống kê theo trạng thái của bưu cục này

Hàng tổng cộng của bưu cục

Tổng đơn hàng tồn đọng của bưu cục

Kết quả thống kê tồn đọng đơn hàng phân nhóm theo Agency

Danh sách nhóm theo bưu cục

Hàng tổng cộng tất cả bưu cục

Danh sách thống kê theo trạng thái của tất cả bưu cục

Cho phép hiển thị tổng cước (chỉ Founder mới thấy)

Kết quả chi tiết đơn hàng tồn đọng (drill-down)

Danh sách đơn hàng chi tiết

Tổng số bản ghi (dùng cho phân trang)

Kết quả thống kê tồn đọng đơn hàng (Backlog)

Danh sách thống kê theo từng trạng thái

Hàng tổng cộng (tổng theo cột)

Cho phép hiển thị tổng cước (chỉ Founder mới thấy)

Kết quả báo cáo sản lượng

Cập nhật OrderProductionTotalItem dựa trên Items

Thêm item vào danh sách và tự động cập nhật tổng

Xóa tất cả items và reset tổng

Kết quả báo cáo số lượng đơn và doanh số theo tuyến

Danh sách báo cáo theo tuyến và trạng thái

Tổng số bản ghi

Kết quả báo cáo doanh thu đơn hàng theo ngày nhận tiền

Cập nhật TotalItem dựa trên Items

Thêm item vào danh sách và tự động cập nhật tổng

Xóa tất cả items và reset tổng

Kết quả báo cáo doanh thu theo Sale (chỉ thống kê tài chính)

Cập nhật TotalItem dựa trên Items

Thêm item vào danh sách và tự động cập nhật tổng

Xóa tất cả items và reset tổng

Danh sách đơn của một ô báo cáo doanh số theo chiều (drill-down), một trang.

Đơn của trang hiện tại, mới nhất trước.

Tổng số đơn của ô — bằng số đơn hiện ở ô trên bảng (dùng cho phân trang).

Kết quả một báo cáo doanh số theo chiều (bưu cục / nhóm / phường xã) — dòng đã ép phạm vi người xem + dòng tổng cộng tính ở service.

Kiểu dòng của chiều.

Các dòng, sắp theo tổng doanh số giảm dần (thứ tự của SP).

Dòng "Tổng cộng" — 4 cặp + tổng cộng dồn từ .

Số dòng.

Đầu kỳ thực dùng — 00:00 giờ Việt Nam của ngày đầu.

Cuối kỳ thực dùng — 23:59:59 giờ Việt Nam của ngày cuối.

File Excel của báo cáo doanh số theo chiều. Controller trả thẳng byte qua File() với no-store — không lưu ra wwwroot, vì doanh số theo bưu cục/nhóm không được nằm ở một URL tải công khai.

Danh sách cho ô lọc của ba báo cáo doanh số theo chiều — đã ép phạm vi người xem, để giao diện không phải gọi danh mục bưu cục / nhân sự toàn cục (plan §3.4).

Bưu cục trong phạm vi; rỗng khi người xem không có role báo cáo bưu cục/phường xã.

Nhóm (quản lý trực tiếp) trong phạm vi; rỗng khi người xem không có role báo cáo nhóm.

Tỉnh/thành phố bộ 2 cấp cho ô lọc của trang phường/xã; rỗng khi người xem không có role báo cáo phường/xã. Trả ở đây để trang không phải mượn Location/LoSug — endpoint ấy đòi role của miền địa danh.

Một bưu cục trong ô lọc.

Bưu cục đã xoá mềm — chỉ Founder/kế toán thấy (plan §6.3).

Node khu vực — không bao giờ là một dòng báo cáo; chọn nó = lọc theo mọi bưu cục con cháu.

Một nhóm trong ô lọc; Id = 0 là "Chưa có quản lý trực tiếp".

Một tỉnh/thành phố bộ 2 cấp trong ô lọc; Id là giá trị CityId của báo cáo phường/xã.

Kết quả báo cáo doanh thu đơn hàng

Cập nhật OrderRevenueTotalItem dựa trên Items

Thêm item vào danh sách và tự động cập nhật tổng

Xóa tất cả items và reset tổng

Kết quả báo cáo công nợ theo sale

Cập nhật item tổng hợp từ danh sách items

Thêm item vào danh sách và tự động cập nhật tổng

Xóa tất cả items và reset tổng

Kết quả báo cáo doanh thu theo sale

Cập nhật item tổng hợp từ danh sách items

Kết quả báo cáo nợ ngắn hạn

Tổng nợ ngắn hạn (tất cả loại)

Tổng nợ thẻ dầu

Tổng nợ vay xe sắp đến hạn (30 ngày)

Tổng nợ vay xe sắp đến hạn (60 ngày)

Tổng nợ vay xe sắp đến hạn (90 ngày)

Tổng dư nợ gốc vay xe còn lại

Chi tiết nợ theo thẻ dầu

Chi tiết kỳ trả nợ vay xe sắp tới

Tổng nợ COD (đã thu nhưng chưa đối soát cho khách)

Tổng COD đã thu

Tổng cước phí trừ đi

Chi tiết nợ COD theo khách hàng (paginated)

Chi tiết nợ 1 thẻ dầu

Ngày thanh toán tiếp theo (ước tính)

Chi tiết nợ COD theo khách hàng

Nợ ròng = TotalCollectAmount - TotalFeeAmount

Chi tiết 1 kỳ trả nợ vay xe sắp tới

Số ngày còn lại đến hạn

Flag xác định user có phải Founder hay không (dùng cho UI). Không trả về danh sách roles.

Thông tin chi nhánh của user

Kết quả cho AppConfig operations

Key của AppConfig

Value của AppConfig

Description của AppConfig

Kết quả TỪNG đơn (Ví bưu cục v2, plan §3.4 "Xuất kho") — chỉ có khi người được gán thuộc chi nhánh bật ví: đơn bị từ chối vì ví bưu cục phát không đủ kèm số thiếu, đơn khác vẫn đi. Lô không dính ví giữ hợp đồng cũ (danh sách rỗng).

Một đơn trong lô gán cho bưu cục phát.

Ví không đủ nhưng công tắc chặn đang tắt — đã đi, đã ghi "sẽ chặn" vào sổ vấn đề.

Số ví phải giữ cho đơn này (cước chính thức / tiền thu hộ).

Số dư khả dụng của ví lúc kiểm.

Thiếu bao nhiêu để xuất được.

Kết quả từng đơn (Ví v2): đơn bị từ chối nhập (thiếu cân thật bắt buộc) kèm lý do; đơn khác vẫn nhập.

Một đơn trong lô nhập kho.

Cước chính thức vừa chốt (null = không thuộc phạm vi v2 / đã chốt trước / nhập tại bưu cục).

Đơn COD có tiền thu hộ nhỏ hơn cước chính thức — đã giữ hàng, bên bán phải sửa trước khi xuất kho.

Kết quả xuất bản khối (POST api/Topic/PublishBlocks).

True = bản đang sửa đã đổi kể từ lúc người bấm mở màn (dấu DraftVersion lệch) — chưa xuất bản gì; FE tải lại bản mới nhất để người duyệt xem lại.

Link xem trước bản đang sửa (POST api/Topic/PreviewToken). là đường dẫn trên website kèm token (/nhuong-quyen?xem-truoc=…) — FE ghép với địa chỉ website của môi trường.

Kết quả một lần lưu hoặc xoá luật chuyển hướng URL.

Khoá của luật sau khi lưu; 0 khi thất bại.

Câu giải thích khi không lưu được — viết cho người nhập đọc, nói cả cách sửa.

Lời nhắc khi lưu thành công nhưng hệ thống đã tự làm thêm một việc mà người nhập không yêu cầu — hiện nay chỉ có một việc: tắt cờ IncludeInSiteMap của bản ghi UrlRecord cùng đường dẫn.

Tách khỏi vì giao diện xử lý hai thứ này khác nhau: một cái làm form đứng lại, một cái hiện kèm thông báo lưu xong. Nhập nó vào là để giao diện phải đoán, và nó sẽ đoán sai đúng một lần rồi không ai nhớ.

CallLog Result - Kết quả thao tác với CallLog

Id của CallLog đã tạo / cập nhật

Kết quả thao tác với tài khoản ngân hàng khách hàng

Dữ liệu tài khoản ngân hàng

Id của Lead đã tạo / cập nhật

Kết quả tạo mới hoặc cập nhật thông tin xuất hóa đơn VAT

ID thông tin xuất hóa đơn VAT

Kết quả tạo mới hoặc cập nhật tài khoản gửi email.

ID tài khoản gửi email.

Kết quả tạo mới báo lỗi

Thông tin báo lỗi vừa tạo

Kết quả danh sách báo lỗi

Danh sách báo lỗi

Tổng số bản ghi

Số trang hiện tại

Kích thước trang

Tổng số trang

Kết quả chi tiết báo lỗi

Thông tin chi tiết báo lỗi

Kết quả cập nhật báo lỗi

ID báo lỗi đã cập nhật

Thông tin báo lỗi sau khi cập nhật

Đường dẫn tải file

Kết quả điều chỉnh số dư ví

Số dư cũ trước khi điều chỉnh

Số dư mới sau khi điều chỉnh

Số tiền điều chỉnh (dương = cộng tiền, âm = trừ tiền)

ID giao dịch được tạo

Hướng giao dịch (Cộng tiền / Trừ tiền)

Kết quả sao chép bảng giá — luôn trả về cả ba số để UI hiện đủ cho người dùng.

⚠️ Đừng chỉ hiện "Thành công". Người dùng cần biết cái gì không được copy — và nói rõ điều đó.

Số ô giá đã tạo mới ở đích.

Số ô đã tồn tại ở đích và bị bỏ qua (khi OverwriteExisting = false).

Số ô đã tồn tại ở đích và bị đè (khi OverwriteExisting = true).

Cảnh báo không chặn — ví dụ: nguồn có tuyến mà đích không nhận diện được. Rỗng khi không có cảnh báo nào.

Kết quả thao tác với đối soát

Dữ liệu đối soát

Thông tin giao dịch đã tạo/cập nhật

Chi tiết giao dịch

Danh sách đơn hàng liên quan

Thông tin ví nguồn

Thông tin ví đích (nếu có)

Tổng số giao dịch

Tổng tiền thu vào

Tổng tiền chi ra

Tổng tiền mặt

Tổng tiền chuyển khoản

Tổng tiền COD

Tổng cước nguồn

Tổng cước đích

Thống kê theo loại giao dịch

Thống kê theo ngày

ID ví

Tên chủ ví

Loại ví

Số dư hiện tại

Trạng thái ví

Loại giao dịch

Số lượng giao dịch

Tổng tiền

Ngày

Số giao dịch

Tổng tiền thu vào

Tổng tiền chi ra

Số dư cuối ngày

Kết quả tìm kiếm giao dịch với thông tin tổng thu và tổng chi

Tổng số tiền thu (Income)

Tổng số tiền chi (Outcome)

Số dư thực tế (TotalIncome - TotalOutcome)

Tổng tiền mặt

Tổng tiền chuyển khoản

Lịch sử số dư theo ngày trong khoảng thời gian search

ID ví

Tên chủ ví

Số dư ban đầu

Số dư hiện tại

Số dư ban đầu hiển thị

Số dư hiện tại hiển thị

Lịch sử số dư theo ngày

Lịch sử số dư theo giao dịch

Ngày

Ngày hiển thị

Số dư đầu ngày

Số dư cuối ngày

Thay đổi số dư trong ngày

Số dư đầu ngày hiển thị

Số dư cuối ngày hiển thị

Thay đổi số dư hiển thị

Màu sắc thay đổi

ID giao dịch

Mô tả giao dịch

Loại giao dịch

Hướng giao dịch

Số tiền giao dịch

Số tiền hiển thị

Số dư sau giao dịch

Số dư hiển thị

Thời gian giao dịch

Thời gian hiển thị

Màu sắc số tiền

Icon giao dịch

Result cho các operations của Bank

ID của ngân hàng (sau khi tạo/cập nhật)

Kết quả xuất Excel phiếu đối soát khách hàng

Đường dẫn file Excel đã tạo

Tên file Excel

Kích thước file (bytes)

Tổng số bản ghi đã xuất

URL download file

Thời gian bắt đầu xử lý

Thời gian kết thúc xử lý

Thời gian xử lý (ms)

Thông tin chi tiết quá trình xử lý

Thông tin chi tiết quá trình xử lý xuất Excel phiếu đối soát khách hàng

Thời gian query database (ms)

Thời gian chuyển đổi dữ liệu (ms)

Thời gian tạo file Excel (ms)

Thời gian lưu file (ms)

Tổng thời gian xử lý (ms)

Đơn hoàn khách nợ cước được cấn vào phiếu này (Ví v2 E13 — V-37): đang giữ chỗ hoặc đã cấn.

Danh sách tài khoản ngân hàng của khách hàng (chỉ hiển thị với phiếu Receivable - công ty cần chuyển tiền cho khách)

Người dùng hiện tại có thể duyệt phiếu (chỉ áp dụng cho phiếu chi tiền)

Người dùng hiện tại có thể từ chối phiếu

Người dùng hiện tại có thể hoàn thành phiếu

Kết quả trả về cho các thao tác với danh mục chi phí

Danh sách danh mục chi phí

Tổng số bản ghi

Kết quả xuất Excel thông tin đơn hàng

Đường dẫn file Excel đã tạo

Tên file Excel

URL để download file (nếu có)

Kích thước file (bytes)

Số lượng đơn hàng đã xuất

Số lượng đơn hàng không tìm thấy

Danh sách mã đơn hàng không tìm thấy

Thời gian tạo file

Thông tin tóm tắt kết quả

Model cho từng dòng trong báo cáo thu chi

Tên danh mục

ID danh mục (nếu có)

ID danh mục cha (nếu có)

Cấp độ trong cây (0: gốc, 1: con, 2: cháu...)

Loại dòng: "Income", "Expense", "Total"

Số tiền theo từng ngày (Key: "yyyy-MM-dd", Value: số tiền)

Tổng cộng

Kết quả báo cáo thu chi

Ngày bắt đầu

Ngày kết thúc

Danh sách các cột ngày ["2025-10-01", "2025-10-02", ...]

Danh sách các dòng dữ liệu

Tổng thu

Tổng chi

Chênh lệch (Thu - Chi)

Model nhận dữ liệu từ stored procedure

Ngày giao dịch

Loại giao dịch (3=OrderFee, 4=CollectFromDriver, ...)

Hướng giao dịch: "Income" hoặc "Outcome"

ID danh mục chi phí (nếu có)

Tên danh mục

ID danh mục cha

Cấp độ trong cây

Thứ tự hiển thị

Số tiền

Số lượng giao dịch

Kết quả xuất Excel phiếu đối soát

Đường dẫn file Excel đã tạo

Tên file Excel

Kích thước file (bytes)

Tổng số bản ghi đã xuất

URL download file

Thời gian bắt đầu xử lý

Thời gian kết thúc xử lý

Thời gian xử lý (ms)

Thông tin chi tiết quá trình xử lý

Thông tin chi tiết quá trình xử lý xuất Excel

Thời gian query database (ms)

Thời gian chuyển đổi dữ liệu (ms)

Thời gian tạo file Excel (ms)

Thời gian lưu file (ms)

Tổng thời gian xử lý (ms)

Kết quả thao tác hóa đơn thuế

ID hóa đơn thuế

Số hóa đơn

Trạng thái

Tên trạng thái

Kết quả trả về từ stored procedure SP_GetTransferableOrdersByCustomer

ID đơn hàng

Mã đơn hàng

Ngày tạo đơn hàng

Ghi chú đơn hàng

Số tiền TransferFee của đơn hàng

Loại thanh toán phí

Giai đoạn hiện tại của TransferFee

Tên người gửi

Địa chỉ người gửi

Số điện thoại người gửi

Tên người nhận

Địa chỉ người nhận

Số điện thoại người nhận

Trạng thái đơn hàng

Trạng thái vật lý đơn hàng

Tên đầy đủ khách hàng

Số điện thoại khách hàng

Email khách hàng

Địa chỉ khách hàng

Username khách hàng

Thông tin sản phẩm (gộp các package thành chuỗi)

Kết quả xuất Excel phiếu chuyển khoản

Đường dẫn file Excel đã tạo

Tên file Excel

Kích thước file (bytes)

Tổng số bản ghi đã xuất

URL download file

Thời gian bắt đầu xử lý

Thời gian kết thúc xử lý

Thời gian xử lý (ms)

Thông tin chi tiết quá trình xử lý

Thông tin chi tiết quá trình xử lý xuất Excel

Thời gian query database (ms)

Thời gian chuyển đổi dữ liệu (ms)

Thời gian tạo file Excel (ms)

Thời gian lưu file (ms)

Tổng thời gian xử lý (ms)

Result class cho các thao tác với hóa đơn thanh toán chuyển khoản

Mã hóa đơn được tạo

Số lượng đơn hàng được xử lý

Tổng tiền của hóa đơn

ID giao dịch được tạo (khi duyệt)

Result cho tài khoản ngân hàng người dùng

ID tài khoản ngân hàng được tạo/cập nhật

Thông tin đồng bộ hóa đơn VAT gần nhất

Có lịch sử đồng bộ hay chưa

Thời gian đồng bộ gần nhất

Khoảng thời gian đã đồng bộ (FromDate - ToDate)

Trạng thái: Success, Failed, InProgress

Số hóa đơn đã insert

Số hóa đơn đã update

Tổng số hóa đơn

Thời gian thực hiện (giây)

Loại đồng bộ: Auto hoặc Manual

Thông báo lỗi nếu có

Thông báo cho người dùng

Kết quả trả về sau khi import lịch sử giao dịch thẻ xăng dầu

Tổng số dòng trong file Excel

Số dòng xử lý thành công

Số dòng lỗi

Số dòng bỏ qua (không có số thẻ, dữ liệu thiếu...)

Số dòng trùng lặp (đã có trong hệ thống)

Số thẻ trong file không tìm thấy trong hệ thống

Danh sách số thẻ không tìm thấy trong hệ thống

Danh sách thông báo lỗi chi tiết theo từng dòng

Danh sách cảnh báo (không nghiêm trọng)

Tổng số tiền chi tiêu đã import

Tổng số tiền thanh toán ngân hàng đã import

Kết quả xuất Excel lịch sử đổ dầu

Đường dẫn file Excel đã tạo

Tên file Excel

Kích thước file (bytes)

Tổng số bản ghi đã xuất

URL download file

Thời gian bắt đầu xử lý

Thời gian kết thúc xử lý

Thời gian xử lý (ms)

Kết quả xuất Excel báo cáo đổ dầu theo lái xe

Đường dẫn file Excel đã tạo

Tên file Excel

Kích thước file (bytes)

Tổng số bản ghi đã xuất

URL download file

Thời gian bắt đầu xử lý

Thời gian kết thúc xử lý

Thời gian xử lý (ms)

Kết quả import bảng chấm công từ file Excel (máy chấm công vân tay).

Tổng số dòng dữ liệu đọc được (không tính header).

Số dòng import thành công.

Số dòng lỗi (đã tồn tại chấm công cùng ngày + nhân viên).

Số dòng bỏ qua (mã chấm công không map được, hoặc ngày nghỉ không có giờ).

Chi tiết các dòng lỗi / bỏ qua.

Kết quả kiểm tra chồng lấp ca chấm công của cùng một nhân viên. Dùng cho FE cảnh báo sớm trong dialog chấm công thủ công / chấm ra bù, trước khi người dùng bấm lưu.

Có bị trùng (chồng lấp thời gian) với ca đã tồn tại hay không.

Thông báo mô tả ca bị trùng. Rỗng nếu không trùng.

Giờ vào của ca bị trùng (null nếu không trùng).

Giờ ra của ca bị trùng (null nếu không trùng hoặc ca đó chưa chấm ra).

Kết quả trả về khi check-in/check-out chấm công

Thông tin bản ghi chấm công

Loại hành động vừa thực hiện (CheckIn hoặc CheckOut)

Thời gian thực hiện hành động

Có phải là check-in không (true = check-in, false = check-out)

Kết quả gợi ý giờ chấm ra suy ra từ thời điểm giao/lấy hàng muộn nhất của lái xe trong ca. Dùng cho dialog chấm bù công khi lái xe quên chấm ra.

Có suy ra được giờ ra từ hoạt động đơn hàng hay không.

Giờ chấm ra được gợi ý (thời điểm giao/lấy hàng muộn nhất trong ca). Null nếu không có dữ liệu.

Kết quả lưu chỉ tiêu KPI — Draft lưu lẻ dòng được nhưng response kèm cảnh báo tổng trọng số hiện tại của chủ thể trong kỳ (§7.8); chặn cứng chỉ xảy ra lúc Assign.

Tổng trọng số (%) hiện tại của chủ thể trong kỳ sau thao tác

Cảnh báo khi tổng trọng số ≠ 100% — chỉ cảnh báo, không chặn ở trạng thái Draft

ID của media record trong database (nếu có lưu)

DTO trả về cho 1 thông báo của user

DTO trả về cho danh sách thông báo (phân trang)

DTO cho NotificationCategory

DTO cho notification preference

DTO cho real-time push qua SignalR (gọn nhất)

Kết quả xuất Excel đơn hàng

Đường dẫn file đã xuất

URL download file

Tên file

Kích thước file (bytes)

Số lượng đơn hàng đã xuất

Thời gian bắt đầu xử lý

Thời gian kết thúc xử lý

Kết quả xuất Excel đơn hàng (Generic)

Loại template đã sử dụng

Tên template đã sử dụng

Đường dẫn file Excel đã tạo

Tên file Excel

URL để download file (nếu có)

Kích thước file (bytes)

Số lượng đơn hàng đã xuất

Số lượng đơn hàng không tìm thấy

Danh sách mã đơn hàng không tìm thấy

Danh sách ID đơn hàng không tìm thấy

Thời gian bắt đầu xử lý

Thời gian hoàn thành xử lý

Thời gian xử lý (milliseconds)

Thời gian tạo file

Thông tin chi tiết về quá trình xử lý

Thông tin tóm tắt kết quả

Đánh dấu hoàn thành xử lý

Thông tin chi tiết về quá trình xuất Excel

Thời gian query database (ms)

Thời gian chuyển đổi dữ liệu (ms)

Thời gian tạo file Excel (ms)

Số lượng bản ghi đã xử lý

Số lượng cột trong Excel

Số lượng dòng trong Excel (bao gồm header)

Memory usage peak (bytes)

Các cảnh báo trong quá trình xử lý

Thông tin debug (chỉ trong development)

Tổng thời gian xử lý (ms)

Kết quả xuất Excel với thông tin template cụ thể

Loại DTO export

Danh sách items đã xuất (để debug hoặc preview)

Metadata về các cột đã xuất

Thông tin về cột trong file Excel

Tên cột

Index cột (1-based)

Loại dữ liệu

Định dạng hiển thị

Chiều rộng cột

Có phải cột bắt buộc không

Mô tả cột

Kết quả bóc toạ độ từ link Google Maps. Chỉ dùng để điền vào form, không ghi CSDL.

Vĩ độ bóc được. Null khi không tìm thấy toạ độ trong link.

Kinh độ bóc được. Null khi không tìm thấy toạ độ trong link.

URL cuối cùng sau khi đi theo redirect — trả về để người dùng đối chiếu khi link rút gọn trỏ tới địa điểm khác với họ nghĩ.

Kết quả chi tiết mặt bằng

Thông tin tài chính

Danh sách liên hệ

Danh sách điểm chấm

Danh sách ảnh/media

Gợi ý đọc từ một hoá đơn bảo dưỡng đã đính kèm: số tiền / ngày / biển số, kèm kết quả đối chiếu biển số với xe của bản ghi. Mọi trường đều là gợi ý "máy đọc — kiểm lại": người dùng bấm mới điền vào form, không có đường nào ghi thẳng vào DB (quyết định chủ dự án 2026-08-21, plan trích-xuất-văn-bản §6).

= Failed khi không đọc được tệp (không tìm thấy, định dạng lạ, PDF hỏng); Success kể cả khi không bóc được trường nào — khi đó mọi trường null và nói rõ. Không trả Confidence của OCR: đo GĐ B cho thấy nó không đo độ đúng (ảnh tin cậy 81 đúng 1/8 trường, ảnh tin cậy 84 đúng 8/8).

Id dòng đính kèm (TruckMaintenanceMedia.Id) đã đọc.

Tên tệp hiển thị (PDF) hoặc rỗng.

Định dạng nhận diện từ nội dung tệp ("Pdf", "Jpeg", "Webp"...).

Có trang nào phải OCR không. True với ảnh và PDF scan — UI phải hiện lời nhắc "ảnh chụp giấy thường không đọc được, hãy nhập tay" (đo GĐ B: ảnh chụp giấy 6,2%).

Số trang đã đọc.

Thời gian đọc (ms) — để theo dõi, không hiển thị.

Tổng giá trị thanh toán gợi ý (đồng). Null = không thấy dòng tổng.

Số nguyên văn trên chứng từ ("3.082.849").

Nhãn dòng đã chọn ("Tổng giá trị thanh toán").

Loại dòng đã chọn — GrandTotal chắc nhất; Subtotal/Computed đi kèm cảnh báo.

Mọi dòng tổng nhận ra trên chứng từ (trước/sau giảm giá, thuế...) để người dùng đối chiếu.

Ngày chứng từ / ngày vào xưởng gợi ý (giờ địa phương máy chủ, không kèm offset).

Chuỗi ngày nguyên văn.

Nhãn đứng trước ngày ("Ngày vào xưởng"), rỗng nếu không có.

Chứng từ có in giờ kèm ngày không — false thì 00:00 chỉ là giá trị mặc định.

Ngày hoàn thành / giao xe / ra xưởng nếu chứng từ có — gợi ý cho ô "Kết thúc".

Chuỗi nguyên văn của .

Nhãn của .

Chứng từ có in giờ kèm không.

Biển số đọc được, chuẩn hoá (chỉ chữ/số, IN HOA). Null = không thấy.

Biển số nguyên văn trên chứng từ.

Mọi biển số chuẩn hoá đọc được (xe kéo + rơ-moóc, bảng nhiều xe) — client so với xe đang chọn bằng danh sách này.

Biển số của xe đang gắn với bản ghi bảo dưỡng (nguyên văn trong DB).

Biển số trên chứng từ có khớp xe của bản ghi không (so sau khi chuẩn hoá cả hai). Null = không đọc được biển số nên không đối chiếu được. False = "hoá đơn này có vẻ của xe khác".

Điều cần người dùng kiểm lại — hiển thị thẳng.

Một dòng tổng tiền trên chứng từ — bản phẳng của cho API.

Loại dòng (tên enum ).

Nhãn nguyên văn.

Giá trị (đồng).

Số nguyên văn.

Kết quả "Đọc phiếu bằng AI" (plan bảo dưỡng đợt 3 §3.1): tiêu đề phiếu + từng dòng kèm gợi ý khớp danh mục. Mọi thứ ở đây là GỢI Ý — người dùng bấm "Dùng" mới thành dòng của form, không có đường nào tự ghi DB.

= Offline khi AI lỗi và máy chủ đã chuyển sang OCR cũ (QĐ3-6): khi đó chỉ có số (tiền / ngày / biển số), rỗng.

Id dòng nhật ký — dùng cho Khớp lại / mở lại / gắn vào bản ghi khi lưu.

Lấy lại kết quả của cùng tệp + cùng model trong 30 ngày, không gọi AI.

Biển số xe của bản ghi / xe đang chọn, nguyên văn trong DB.

null khi phiếu không ghi biển số; false là dấu hiệu đính nhầm phiếu xe khác.

Lượt khớp lại (bước 2b) còn được chạy cho reading này.

Kết quả OCR cũ khi AI lỗi (chỉ có ở ).

Phần đầu phiếu — mỗi ô có nút "Dùng" riêng trên giao diện như khối gợi ý OCR cũ.

Ngày chứng từ đã kiểm (null nếu phiếu không ghi hoặc ngày không hợp lệ).

Độ tự tin AI tự báo: high / medium / low.

Một dòng trên phiếu, đã kiểm số, kèm gợi ý khớp.

part / labor / service / fee / other.

MaintenanceActionType suy từ hành động trên phiếu; null khi không rõ hoặc "việc khác".

Gợi ý khớp một dòng — kết quả tầng 2a (thuần) hoặc 2b (LLM, đã kiểm mã tồn tại).

match / new / skip / unmatched (chưa khớp được, chưa có gợi ý).

componentType / attribute / null.

high / medium / low.

Khớp nhờ đâu: alias / code / name / attribute / fuzzy / llm.

Đề xuất cho người quản lý danh mục — chỉ mở form có sẵn, điền sẵn; không tự ghi.

alias / newComponentType / newAttribute / editComponentType.

Giá trị TruckComponentGroup (1–5) đã kiểm; null khi AI đưa nhóm lạ.

Kết quả một đơn hàng CK kế toán chi tiết (dùng cho xuất Excel khi click từng ô số liệu)

Mã đơn hàng

Mã đối tác

Tên sale

SĐT sale

Tên khách hàng

SĐT khách hàng

Phí chuyển khoản

Tổng cước

Trạng thái phí CK (stage)

Trạng thái đơn

Trạng thái vật lý

Thời gian tạo đơn

Thời gian giao hàng

Người gửi

SĐT người gửi

Người nhận

SĐT người nhận

Ghi chú

Kết quả trả về từ stored procedure sp_GetBankTransferSummaryByCustomer

ID khách hàng

Tên khách hàng

Số điện thoại khách hàng

Tổng số đơn hàng

Tổng tiền cước

Tổng phí chuyển khoản

Tổng số tiền chưa thu

Số lượng đơn chưa thu

Tổng số tiền đã tạo phiếu

Số lượng đơn đã tạo phiếu

Tổng số tiền đã thu

Số lượng đơn đã thu

Kết quả dòng Tổng toàn cục (theo bộ lọc) cho báo cáo công nợ CK theo khách hàng. Trả về từ stored procedure sp_GetBankTransferSummaryByCustomerTotals — dùng cho summary cards + dòng Tổng, tính trên TOÀN BỘ khách hàng khớp filter (không theo trang).

Tổng số khách hàng (số dòng của báo cáo)

Tổng số đơn hàng

Tổng tiền cước

Tổng phí chuyển khoản

Tổng số tiền chưa thu

Số lượng đơn chưa thu

Tổng số tiền đã tạo phiếu

Số lượng đơn đã tạo phiếu

Tổng số tiền đã thu

Số lượng đơn đã thu

Kết quả trả về từ stored procedure sp_GetBankTransferSummaryBySale

ID sale

Tên sale

Số điện thoại sale

Tổng số đơn hàng

Tổng tiền cước

Tổng phí chuyển khoản

Tổng số tiền chưa thu

Số lượng đơn chưa thu

Tổng số tiền đã tạo phiếu

Số lượng đơn đã tạo phiếu

Tổng số tiền đã thu

Số lượng đơn đã thu

Kết quả dòng Tổng toàn cục (theo bộ lọc) cho báo cáo công nợ CK theo Sale. Trả về từ stored procedure sp_GetBankTransferSummaryBySaleTotals — dùng cho summary cards, tính trên TOÀN BỘ sale khớp filter (không theo trang).

Tổng số sale (số dòng của báo cáo)

Tổng số đơn hàng

Tổng tiền cước

Tổng phí chuyển khoản

Tổng số tiền chưa thu

Số lượng đơn chưa thu

Tổng số tiền đã tạo phiếu

Số lượng đơn đã tạo phiếu

Tổng số tiền đã thu

Số lượng đơn đã thu

Result class for sp_SearchCustomersForReconciliation stored procedure

Kết quả trả về từ stored procedure SP_SearchCustomersForTransferPayment

ID khách hàng

Tên khách hàng

Số điện thoại khách hàng

Email khách hàng

Địa chỉ khách hàng

Số lượng đơn hàng chờ thanh toán

Tổng số tiền TransferFee chờ thanh toán

Ngày tạo đơn hàng cũ nhất

Ngày tạo đơn hàng mới nhất

ID quản lý khách hàng

Tên quản lý khách hàng

Có thể tạo hóa đơn không

Tổng số bản ghi (cho pagination)

Tổng số trang (cho pagination)

Kết quả trả về từ stored procedure sp_GetDriverProductivityReportByDate

ID lái xe

Tên đăng nhập lái xe

Tên đầy đủ lái xe

Ngày hoạt động

Số lượng đơn hàng lấy hàng trong ngày

Số lượng đơn hàng giao hàng trong ngày

Tổng số lượng đơn hàng trong ngày

Tên ngày trong tuần

Thời gian bắt đầu (từ tham số)

Thời gian kết thúc (từ tham số)

Result class for sp_GetReconciliableOrdersByCustomer stored procedure

Extension methods để cấu hình Media Services

Đăng ký tất cả Media Services mới (ImageService, VideoService, UnifiedMediaService)

Service collection Configuration Service collection

Đăng ký Media Services với backward compatibility Giữ lại interface cũ nhưng sử dụng implementation mới

Service collection Configuration Service collection

Migration helper - Thay thế dần dần các service cũ

Service collection Configuration Có enable legacy services không Service collection

Backward Compatible Media Service - Wrapper cho legacy interfaces

Chuyển đổi từ PermissionModel sang Permission entity

Chuyển đổi từ Permission entity sang PermissionModel

Authorization filter cho Hangfire Dashboard. Chỉ cho phép truy cập nếu user đã đăng nhập và có role Founder hoặc Admin.

Bộ lọc "đơn đang hoạt động" của app tài xế — nơi duy nhất định nghĩa tổ hợp trạng thái nào thì đơn xuất hiện trên tab Đơn hàng, và tách được theo nhóm (lấy / giao / trả / trung chuyển).

Tách khỏi DriverAppOrderService để ca test canh được bằng FakeRepository mà không phải dựng cả service với hàng chục phụ thuộc. Nhóm trung chuyển () thêm 2026-09-22: Deploy.AssignTransit vẫn gán PicId cho lái xe trung chuyển và đưa đơn về Outbound, nhưng bộ lọc cũ không có mã này nên lái xe trung chuyển mở tab Đơn hàng luôn thấy trống. Đơn trung chuyển chỉ để tra cứu — app không mở thao tác lấy/giao cho nhóm này. phải là MỘT biểu thức viết tay (không ghép OrElse từ các nhóm) để EF dịch thẳng sang SQL; ca test kiểm rằng nó đúng bằng hợp của bốn nhóm.

Đang lấy hàng hoặc lấy thất bại chờ lấy lại.

Đang giao hoặc giao thất bại chờ giao lại.

Đang trả hàng về người gửi.

Đã xuất kho, đang trên xe trung chuyển tới bưu cục kế tiếp. Chỉ cần mã vật lý: mọi đường gán Outbound cho một PicId đều là gán lái xe trung chuyển (xem DeployService.AssignTransit).

Hợp của bốn nhóm trên — viết tay thành một biểu thức để EF dịch được.

Bộ lọc thêm theo nhóm app gửi lên qua PredicateObject.Group; null khi nhóm rỗng hoặc không nhận ra (giữ nguyên danh sách "tất cả" thay vì trả rỗng vì một chuỗi lạ).

Ghép bản ghi Media của một đơn với OrderTrack sinh ra nó và URL đã đổi, thành danh sách cho app tài xế.

Thứ tự trả về: theo thời điểm sự kiện tăng dần (ảnh lấy hàng trước, ảnh giao sau), trong cùng sự kiện theo DisplayOrder. Ảnh không đổi được URL bị bỏ qua thay vì trả ô trống cho app. Bản ghi ảnh của đơn. Các track mà ảnh trỏ tới (thiếu cũng được — nhóm sẽ không có tên). URL tương ứng từng phần tử của , cùng thứ tự.

Như nhưng cho ảnh của nhiều đơn nạp chung một lượt (danh sách đơn): tách theo Media.OrderId rồi xếp từng đơn như . Đơn không còn ảnh nào thì không có khoá.

Bản ghi ảnh của nhiều đơn, thứ tự bất kỳ. Các track mà ảnh trỏ tới, của mọi đơn. URL tương ứng từng phần tử của , cùng thứ tự.

Bóc toạ độ ra khỏi link Google Maps. Frontend cũng có bản parse riêng (Ladaer.FrontEnd/src/views/orders/shared/googleMapLink.js) để xử lý ngay link đầy đủ mà không cần gọi server. Bản này phục vụ link RÚT GỌN (maps.app.goo.gl) — browser không đọc được Location header của redirect nên bắt buộc phải nhờ server đi theo redirect rồi parse.

Toạ độ điểm được Google nhúng trong tham số `data`: !3d{lat}!4d{lng}. Đây là toạ độ CỦA ĐỊA ĐIỂM, chính xác hơn `@lat,lng` (toạ độ camera).

Toạ độ trong query string: q= / query= / ll= / daddr= / center= / destination=.

Toạ độ camera: /@{lat},{lng},{zoom}z — dùng khi không có toạ độ điểm.

Chuỗi toạ độ thuần "21.028, 105.834" người dùng dán trực tiếp.

Tìm toạ độ trong một chuỗi (link hoặc cặp số). Trả về null nếu không thấy toạ độ hợp lệ.

Toạ độ nằm trong khoảng hợp lệ và không phải điểm 0,0 (Vịnh Guinea).

Host được phép gọi khi đi theo redirect. Đây là chốt chặn SSRF: người dùng dán được URL bất kỳ, nếu không khoá host thì endpoint này thành công cụ để server đi thăm mạng nội bộ (169.254.169.254, localhost, IP LAN…).

Kiểm tra một URL có thuộc miền Google được phép hay không. Chỉ nhận http/https và so khớp theo nhãn tên miền (chặn kiểu "google.com.evil.tld").

Hợp đồng tối thiểu để điền toạ độ cho một địa chỉ đơn hàng. Có nhiều DTO địa chỉ khác nhau (OrderAddressItem cho danh sách, OrderDetailAddressModel cho trang tra cứu) nhưng tất cả cần cùng một quy tắc điền toạ độ. Dùng interface thay vì viết lại từng nơi — lệch nhau thì cùng một địa chỉ sẽ hiện "đã định vị" ở trang này và "chưa định vị" ở trang khác.

Vĩ độ.

Kinh độ.

Nguồn toạ độ: 0 = chưa có, 1 = ghim chính xác, 2 = tâm phường/xã.

Id phường/xã (0 với địa chỉ 2 cấp).

Id quận/huyện.

Điền toạ độ cho địa chỉ đơn hàng, dùng chung cho bản đồ triển khai (portal), danh sách đơn / trang tra cứu của portal và bản đồ đơn hàng của app lái xe. Trước đây logic này chỉ nằm riêng trong DeployService nên API của app lái xe không có toạ độ gần đúng và luôn trả CoordSource = 0. Tách ra đây để các luồng dùng cùng một quy tắc, tránh lệch nhau khi sửa về sau.

Toạ độ tâm của một đơn vị hành chính.

Toạ độ tâm của một đơn vị hành chính.

Gom Id đơn vị hành chính cần nạp để tra tâm cho một loạt địa chỉ. Địa chỉ 3 cấp tra theo phường/xã, địa chỉ 2 cấp (WardId = 0) tra theo quận/huyện.

Danh sách địa chỉ cần điền toạ độ Danh sách Id Location cần nạp (đã loại trùng)

Dựng bảng tra toạ độ tâm từ entity Location (dùng khi service có repository).

Dựng bảng tra toạ độ tâm từ DTO LocationItem (dùng khi service chỉ có ILocationService, không có repository Location — như OrderService).

Điền toạ độ cho một địa chỉ đơn hàng theo 2 tầng (không gọi mạng): 1 = toạ độ đã ghim sẵn trên đơn, 2 = tâm phường/xã (hoặc quận/huyện với địa chỉ 2 cấp). Tầng gọi Google nằm ở DeployService.GeocodeOrderAddresses, chỉ nhân viên điều hành gọi được (role Deploy.GetDeployDetail).

Địa chỉ cần điền toạ độ Bảng tra tâm đơn vị hành chính (xem BuildCoordLookup)

Quá tải cho các luồng đang truyền thẳng danh sách entity Location (DeployService, DriverAppOrderService). Quét tuyến tính chứ KHÔNG dựng lại lookup: hàm này được gọi trong vòng lặp theo từng địa chỉ, dựng dictionary mỗi lần sẽ thành O(số địa chỉ × số phường). Luồng nào gọi nhiều nên tự dựng lookup một lần rồi dùng quá tải ở trên.

Hub đẩy sự kiện chat đa nền tảng về SPA quản trị. Bốn nhóm, bốn mục đích khác nhau: — mọi nhân viên đang mở trang chat. Chỉ còn dùng cho kênh ở chế độ Shared, nơi ai có quyền cũng thấy mọi hội thoại (§6.3). chan-{channelId} — những người xem được TOÀN BỘ một kênh đã bật hàng rào: trưởng nhóm, chủ kênh, và người có quyền xem tất cả. staff-{userId} — đúng một người. Dùng để báo cập nhật của hội thoại đang giao cho họ trên kênh có hàng rào, mà không phải phát cho cả kênh. conv-{id} — những người đang mở đúng hội thoại đó. Dùng cho bong bóng tin và trạng thái giao nhận. Server tự chấm, không tin tham số client gửi lên. Danh sách kênh được vào lấy từ ngay lúc kết nối, và tra lại hội thoại trong phạm vi trước khi cho vào phòng. Không có bước này thì hàng rào của 13 endpoint REST vô nghĩa: bản đẩy ConversationUpdated mang theo LastMessage — nguyên văn tin của khách. Quyền được chấm ở ngay lớp này, không phó mặc cho giao diện: kết nối đòi ChatConversation.Search, vào một hội thoại đòi ChatConversation.GetById. Role không nằm trong JWT — ServerRoleAuthorizationHandler tra database, và nó chạy cho cả SignalR chứ không riêng controller.

Nhóm gồm mọi nhân viên đang mở trang chat — chỉ dùng cho kênh chế độ Shared

Tiền tố tên nhóm của một hội thoại

Tên nhóm SignalR của một hội thoại. Khai đúng một chỗ để hub và bản đẩy dùng chung.

Mã hội thoại đọc ngược từ tên nhóm; 0 nếu đây không phải nhóm hội thoại. Dùng khi thu hồi phòng: sổ kết nối chỉ giữ tên nhóm, không giữ mã.

Tên nhóm của một kênh đã bật hàng rào — chỉ người xem được toàn kênh mới ở trong.

Tên nhóm riêng của một nhân viên — nơi nhận cập nhật của hội thoại mình đang giữ.

Những nhóm mà một phạm vi được vào — một luật duy nhất, dùng chung cho lúc kết nối và cho lúc thu hồi (). Tách ra vì hai chỗ ấy phải luôn nói cùng một câu: chỗ nào rộng hơn chỗ kia thì hoặc thu hồi nhầm phòng đang cần, hoặc để lại phòng lẽ ra phải gỡ.

Vào một nhóm và ghi vào sổ kết nối — hai việc luôn đi cùng nhau.

Vào phòng của một hội thoại để nhận tin nhắn của riêng nó. Gọi khi nhân viên mở hội thoại trên khung chat. Chấm phạm vi tại đây, không chỉ chấm role: role nói "được xem chi tiết hội thoại nói chung", còn câu hỏi thật là "hội thoại NÀY có thuộc phạm vi của người này không". Bỏ qua bước này thì một lời gọi JoinConversation(id) với mã đoán được là đủ để nhận mọi tin nhắn của khách người khác theo thời gian thực.

Rời phòng của một hội thoại — gọi khi nhân viên chuyển sang hội thoại khác.

Id nhân viên lấy từ claim — cùng cặp claim mà UserHelper.GetCurrentUser đọc ở tầng controller. Giá trị này giờ quyết định phạm vi dữ liệu chứ không còn chỉ để ghi nhật ký, nên đọc thiếu một trong hai claim là đẩy người dùng xuống phạm vi rỗng.

SignalR Hub cho hệ thống thông báo real-time. Clients kết nối qua WebSocket, nhận thông báo push.

Khi client kết nối: thêm vào group theo UserId và Roles

Khi client ngắt kết nối

Client gọi để đánh dấu thông báo đã đọc

Lấy UserId từ claims

Hangfire job kéo số liệu quảng cáo theo ngày về LADA cho mọi tài khoản đã bật đồng bộ định kỳ (plan cải tổ giao diện quảng cáo, quyết định Q5). Trước job này số liệu chỉ về khi ai đó bấm "Đồng bộ" (POST report/sync-now) — trên production bảng AdsMetricDaily dừng ở 18/08/2026 vì không ai bấm. Job tái dùng đúng đường của nút đó (): duyệt tuần tự từng tài khoản, lỗi một tài khoản không giết cả lô, ghi AdsSyncLog đứng tên "System". Khoảng ngày: ngày kết thúc ở hôm nay. Kéo lại vài ngày cũ vì nền tảng còn cập nhật chuyển đổi muộn; kéo cả hôm nay vì job chạy mỗi 30 phút (08/09/2026, trước đó 5:10 sáng hằng ngày và dừng ở hôm qua) — mục đích là thấy hiệu suất trong ngày, mà bỏ hôm nay ra thì chạy dày bao nhiêu cũng vẫn là số của hôm qua. Bản ghi upsert theo (Level, EntityId, Date) nên chạy lại không sinh dòng trùng, dòng hôm nay bị ghi đè lớn dần theo từng lần kéo. Hệ quả cần biết: mốc "Số liệu đến ngày X" trên thanh ngữ cảnh giờ là hôm nay và là số dở dang — nền tảng còn cộng thêm tới hết ngày, nên đừng so ngang một ngày đang chạy với một ngày đã trọn. Thanh ngữ cảnh đứng cạnh mốc đó có giờ đồng bộ gần nhất để đọc ra điều này. Chi phí quota tăng theo số lần chạy (~144 lời gọi/ngày với 3 tài khoản đang bật, thay vì 3 khi còn chạy mỗi đêm — sổ nợ N-7); lo quota thì tạm dừng từ /tac-vu-nen.

Số ngày nhìn lại mỗi lần chạy, tính cả hôm nay

Tên ghi vào AdsSyncLog — cùng quy ước với

Id người dùng cho luồng chạy nền — 0 = không phải tài khoản nào cả

Kéo số liệu ngày gần nhất (tính cả hôm nay) cho các tài khoản đang bật đồng bộ định kỳ.

Hangfire job dò lệch lịch quảng cáo giữa LADA và nền tảng. Job chỉ đọc và đánh dấu: chiến dịch nào lệch thì bị đặt SyncStatus = OutOfSync kèm chi tiết để UI hiện badge "Lịch lệch". Job không tự sửa lịch ở bất kỳ phía nào — người dùng mở chiến dịch rồi tự chọn đẩy lịch LADA lên hay kéo lịch nền tảng về. Chạy mỗi ngày một lần vào lúc ít người dùng nhất. Người chạy job không phải người thật nên mọi bản ghi AdsSyncLog đứng tên "System" — xem .

Tên người thực hiện ghi vào AdsSyncLog. Dùng "System" giống các luồng chạy nền khác của repo để người đọc log phân biệt được ngay việc nào do job, việc nào do người.

Id người dùng cho luồng chạy nền — 0 = không phải tài khoản nào cả

Quét toàn bộ chiến dịch đã đẩy lên nền tảng và đánh dấu chiến dịch có lịch lệch.

Hangfire job network-gop-su-kien-ngay (docs/plan-buu-cuc.md §3.8, GĐ D): gộp sự kiện thô trang bưu cục công khai () thành số theo ngày () — nguồn của báo cáo bưu cục và cột "Gọi 30n". Idempotent: mỗi ngày được XOÁ rồi CHÈN LẠI trong một transaction, nên bấm "Chạy ngay" hai lần, hay job chạy lại sau lỗi, ra đúng một bộ số — không cộng dồn. Ngày tính theo giờ Việt Nam bằng khoảng thời điểm (), không theo ngày của offset đã lưu. Mỗi lần tính lại ngày (hôm qua + 2 ngày trước): máy chủ tắt qua 01:10 một hai đêm thì lần chạy kế tiếp tự bù, không cần ai chạy tay. Hôm nay không gộp (còn đang ghi).

[DisableConcurrentExecution] (review GĐ D): bấm "Chạy ngay" đúng lúc lịch 01:10 đang chạy thì bản sau chờ khoá thay vì chạy chồng (hai bản xoá–chèn cùng ngày làm một bản vấp khoá chính và báo đỏ). Mỗi ngày gộp độc lập: một ngày lỗi không bỏ các ngày sau (hôm qua vẫn có số) — lỗi ném lại ở cuối để Hangfire thử lại.

Tính lại số của MỘT ngày (giờ Việt Nam): xoá mọi dòng của ngày đó rồi chèn lại từ sự kiện thô, trong một transaction. Trả số dòng gộp đã chèn.

Hangfire job network-don-su-kien (plan §3.2, §3.8): xoá cứng sự kiện thô trang bưu cục cũ hơn 13 tháng. Số gộp theo ngày () KHÔNG bị dọn — báo cáo tháng cũ vẫn còn số lượt/phiên, chỉ mất bảng nguồn truy cập / trang (cần sự kiện thô). Mốc cắt là 00:00 giờ Việt Nam — một ngày không bao giờ bị dọn dở nửa.

Hangfire job analytics-nap-dim-dem (docs/plan-mcp-tra-cuu-so-lieu.md §3.3, GĐ A): nạp lại bảy bảng danh mục analytics.Dim* cho MCP số liệu — chi nhánh, địa danh, loại hàng, đội xe (không biển số), dải cự ly, bảng giá công khai, tham số cước. Idempotent (xoá–chèn trong một transaction), mỗi lượt ghi một dòng analytics.LoadRun.

Công tắc Analytics:Enabled TẮT thì job không làm gì (log một dòng) — trên production tính năng tắt tới khi qua nghiệm thu GĐ D. Chạy 1:20 sáng, trước job nạp fact vận đơn (1:30, GĐ B) để fact luôn gặp danh mục mới. [DisableConcurrentExecution]: bấm "Chạy ngay" đúng lúc lịch đang chạy thì bản sau chờ khoá thay vì hai bản xoá–chèn chồng nhau. Lỗi ném lại để Hangfire thử lại (dòng LoadRun đã ghi failed).

Hangfire job nạp fact cho MCP số liệu (docs/plan-mcp-tra-cuu-so-lieu.md §3.3): fact vận đơn analytics.ShipmentFact (GĐ B), NGAY SAU ĐÓ điểm dừng ước lượng analytics.StopFact (GĐ C — dựng từ fact vận đơn vừa nạp), rồi lần đổ dầu analytics.FuelFact (GĐ D), lượt qua trung tâm khai thác analytics.HubEventFact và khiếu nại analytics.ComplaintFact (GĐ E — ba bảng này luôn dựng lại cả cửa sổ) — MỘT phương thức cho cả hai lịch: analytics-nap-fact-dem (, 1:30 sáng, sau danh mục 1:20) và analytics-nap-lai-400-ngay (, bấm tay).

Chung một phương thức là CỐ Ý: khoá [DisableConcurrentExecution] của Hangfire đặt theo lớp + phương thức, nên bấm "Nạp lại 400 ngày" đúng lúc job đêm đang chạy thì bản sau chờ khoá thay vì hai lượt xoá–chèn cùng lô đơn chồng nhau. Điểm dừng nằm CHUNG job (không lịch riêng) vì nó đọc fact vận đơn: chạy sau trong cùng khoá là chắc chắn gặp fact mới, và đổi Analytics.StopGapMinutes xong chỉ cần bấm một job nạp lại. Chữ ký Execute(mode) giữ nguyên để lịch đã đăng ký trong Hangfire không vỡ. Công tắc Analytics:Enabled TẮT thì không làm gì. Lỗi ném lại để Hangfire thử lại (dòng LoadRun đã ghi failed; cả hai builder idempotent).

Hangfire job analytics-don-log-12-thang (plan §3.10): xoá dbo.AnalyticsCallLog cũ hơn 12 tháng — yêu cầu §6 "log lời gọi giữ 12 tháng". Xoá theo lô để không phình log giao dịch. Hằng tuần; bỏ qua khi Analytics:Enabled tắt.

Hangfire job bảo trì chấm công: tự đóng các ca treo (lái xe quên chấm ra) bằng thời điểm hoạt động giao/lấy hàng muộn nhất TRONG CỬA SỔ CA (trần 20h). Chạy hàng ngày lúc ~3:00 AM, quét toàn bộ ca treo bất kể cũ đến đâu.

⚠ Từ 16/08/2026 job không còn bị giới hạn "48h gần đây" nữa. Đêm đầu tiên sau khi bản vá GĐ A lên production, nó sẽ đóng phần tồn cũ (147/166 ca treo đo trên DB dev 16/08/2026) và qua đó LÀM THAY ĐỔI số công/kíp của kỳ lương đang Draft. Vì vậy việc chụp bảng lương và báo kế toán phải làm TRƯỚC khi deploy GĐ A, không phải trước khi chạy migration backfill của GĐ B — xem docs/plan-sua-cham-cong-trung.md §4.1.

Hangfire job tự động phát hiện vi phạm nộp tiền trễ và sinh phiếu phạt. Chạy định kỳ (VD: mỗi 30 phút). Sử dụng EarliestCollectedTime (thời gian thu tiền sớm nhất) thay vì BusinessDate cố định.

Ví bưu cục v2: tiền người của bưu cục nhượng quyền bật ví cầm trên đơn Ví ghi không nộp LADA (Quỹ từ chối — V-05), nên stage không bao giờ về Tổng — không được tính là nợ nộp trễ. Null khi dựng không có ví.

Execute job - phát hiện vi phạm nộp tiền trễ dựa trên thời gian thu tiền sớm nhất

Lấy DS người đang cầm tiền từ OrderFin (kèm EarliestCollectedTime) Không filter theo ngày — lấy tất cả đơn đang cầm (stage giữa NotCollected và Head)

Cộng nợ theo người cầm tiền: mọi khoản có thời điểm thu và stage giữa "Chưa thanh toán" và "Tổng đã thu". Hàm thuần. Ví bưu cục v2: khoản của người thuộc bưu cục nhượng quyền bật ví trên đơn Ví ghi ( — cùng mốc màn Quỹ / CollectCashier) KHÔNG tính: tiền đó đã thuộc bưu cục, Quỹ LADA từ chối thu nên stage đứng mãi ở "Lái xe đang cầm" — tính vào là phạt nộp trễ khoản không bao giờ nộp được. Từ V-60 khoản đó chuyển sang "Bưu cục giữ" — loại theo stage, không chỉ dựa vào người cầm: cước lấy / giao đứng mãi ở 10 nên người chuyển chi nhánh / ví tắt sau khi thu vẫn không bị phạt. COD đi tiếp 10 → 11 / 12 khi đối soát khách mà CodCashierId giữ nguyên — khoản 12 chỉ còn được loại nhờ Covers (sổ nợ V-70).

Dòng tài chính kèm thời điểm tạo đơn. Người cầm tiền thuộc bưu cục nhượng quyền bật ví, theo UserId.

Cập nhật thời gian thu tiền sớm nhất cho cashier

Tính tổng tiền đã nộp trước deadline từ Transaction

Thời gian thu tiền sớm nhất trong các đơn đang cầm

Dọn bảng BotVisitDaily — xoá hẳn những ngày đã quá Search.BotVisit.RetentionDays (mặc định 90). Job này ra đời cùng lượt thay đổi tạo ra bảng nó dọn, không để lại thành việc phải nhớ. Bảng AdsSyncLog của miền quảng cáo đã cho thấy hậu quả của cách làm ngược lại (nợ Ads N-7). Vì sao bảng này dọn còn SearchMetricDaily thì không. Số liệu hiệu suất tìm kiếm là thứ Google xoá mất sau 16 tháng — giữ lại bản của mình là toàn bộ lý do kéo nó về. Lượt bot thì ngược lại: nó trả lời "bot nào đang ghé, ghé những đâu", một câu hỏi luôn về hiện tại. Hai bảng cùng hình dạng nhưng khác bản chất, nên đừng chép quyết định của bảng này sang bảng kia. Xoá cứng, không xoá mềm. Chỉ số duy nhất (Date, Bot, Path) không lọc theo IsDeleted, nên một dòng xoá mềm vẫn chiếm chỗ và sẽ chặn lượt ghi của đúng bộ ba ấy nếu ngày cũ quay lại (kéo bù, sửa tay). Dọn ở đây cũng không có gì để khôi phục: đây là số đếm gộp, không phải chứng từ. Không gọi ra ngoài nên tự đăng ký khi khởi động, cùng nhóm với SearchApiLogCleanupJob.

Xoá hẳn các ngày đã quá hạn giữ.

Hangfire job dọn nhật ký quyết định phân phối cũ hơn 180 ngày (giai đoạn D). Bảng là append-only và ghi một dòng cho mỗi lượt máy chạy, kể cả lượt không ai nhận. Ở quy mô đích nó lớn nhanh hơn hẳn bảng phân công, mà giá trị của nó thì hết hạn: câu hỏi "sao hôm qua tôi không được chia khách" đáng trả lời, câu hỏi ấy về một ngày cách đây một năm thì không. Xoá cứng, không xoá mềm. Xoá mềm ở đây chẳng dọn được gì — dòng vẫn nằm đó, chỉ số vẫn phình — trong khi bảng này không phải bằng chứng nghiệp vụ cần đối soát về sau: bằng chứng ấy là ChatConversationAssignment, và bảng đó không bị dọn.

Giữ lại bấy nhiêu ngày — §3.2 chốt 180

Hangfire job kéo lịch sử hội thoại chat MỚI từ nền tảng về để bù tin webhook không chở tới — ca gốc là tin Page trả lời riêng từ bình luận Facebook. Toàn bộ luật nằm ở ; job chỉ gọi và ghi nhật ký.

[DisableConcurrentExecution]: bấm "Chạy ngay" ở /tac-vu-nen đúng lúc lịch đang chạy thì hai lượt cùng chèn một tin vào cùng một hội thoại. [AutomaticRetry(Attempts = 0)]: lượt hỏng không cần Hangfire chạy lại — hội thoại gặp lỗi tạm vẫn chưa đánh dấu, lượt sau một phút tự nhặt.

Hangfire job lưu tệp đính kèm chat (ảnh, video, tin thoại, tệp) từ CDN Zalo/Facebook về máy chủ LADA — sổ nợ SC-9. Toàn bộ luật nằm ở ; job chỉ gọi và ghi nhật ký.

[DisableConcurrentExecution]: bấm "Chạy ngay" ở /tac-vu-nen đúng lúc lịch đang chạy thì hai lượt cùng tải một tệp và cùng ghi một tin. [AutomaticRetry(Attempts = 0)]: lượt hỏng không cần Hangfire chạy lại — lượt kế tiếp 5 phút sau tự nhặt các tin còn chờ, và đếm lần thử đã nằm trong từng tin.

Hangfire job tính lại điểm chất lượng chat của toàn bộ sale đang phụ trách kênh. Chạy 03:20 hằng ngày trên cửa sổ trượt 30 ngày (giai đoạn F). Job này không đổi hành vi phân phối. Nó chỉ ghi hai bảng điểm; điểm có được dùng hay không nằm ở công tắc Chat.Quality.AffectsDistribution (mặc định TẮT) mà máy phân phối đọc. Tách như thế để điểm được tính và quan sát được trước khi nó có hiệu lực — không có bước ấy thì không cách nào đối chiếu trước lúc bật. Vì sao chạy đêm chứ không tính lúc phân phối. Máy phân phối chạy trên đường nóng nhất của hệ thống (mỗi tin của khách vào một hội thoại chưa ai giữ); tính trung vị thời gian phản hồi 30 ngày ở đúng chỗ ấy là đặt một phép quét bảng tin nhắn vào giữa đường webhook. §3.6 chốt: máy phân phối chỉ đọc ChatQualitySummary.

Hangfire job quét hàng chờ chat: thử phân phối lại hội thoại chưa ai nhận và báo trưởng nhóm khi khách chờ quá lâu. Chạy mỗi 2 phút (giai đoạn D). Vì sao cần job dù máy đã chạy trên webhook. Máy phân phối chạy đúng lúc tin của khách đến; nếu lúc ấy không ai đủ điều kiện — ngoài giờ làm, cả đội đang bận, kênh chưa xếp ai phụ trách — thì hội thoại vào hàng chờ và không có sự kiện nào đưa nó ra. Số đo D0-5 đếm được 12/62 hội thoại trên dev có tin đầu tiên rơi ngoài giờ làm, tức khoảng một phần năm lưu lượng phụ thuộc hoàn toàn vào lượt quét này. Chu kỳ 2 phút là con số của §3.3, và nó rẻ: số đo Đ4 đếm 21 hội thoại/ngày, nên mỗi lượt quét gần như luôn chạy trên một hàng chờ rỗng.

Hangfire job quét hạn phản hồi chat: nhắc người đang giữ khi khách chờ quá lâu, thu hồi và chia lại khi chờ lâu hơn nữa. Chạy mỗi 2 phút (giai đoạn E). Vì sao cần. Giai đoạn D dựng máy tự chia khách, nhưng chia xong rồi thì không ai canh nữa — một hội thoại giao cho người đang bận rồi để đó ba tiếng thì hệ thống hoàn toàn im lặng. Không có sự kiện nào phát ra khi không có gì xảy ra, nên chỉ một lượt quét theo đồng hồ mới phát hiện được. Công tắc Chat.Sla.Enabled mặc định TẮT. Job vẫn đăng ký và vẫn chạy — nó còn mang việc dọn trạng thái hết hạn (PP-26, PP-27) vốn không phụ thuộc công tắc — nhưng phần nhắc và thu hồi im lặng cho tới khi người vận hành bật. Lý do ở : bật sớm là trộn hai hiệu ứng vào bảng đối chiếu của cổng D2.

Hangfire job làm mới access token của các kênh chat sắp hết hạn. Chạy mỗi giờ. Vì sao phải có job thay vì làm mới lúc gửi tin: access token của Zalo sống 25 giờ, còn refresh token sống 3 tháng và chỉ dùng được một lần. Để token hết hạn rồi mới chữa thì kênh đã chết một quãng, mà chết im lặng — không có lỗi nào cho tới khi nhân viên bấm gửi. Ngưỡng 2 giờ với chu kỳ 1 giờ nghĩa là mỗi token có ít nhất hai lượt để được làm mới trước khi hết hạn: một lượt hỏng vì mạng vẫn còn lượt sau.

Làm mới khi token còn hạn dưới ngưỡng này

Hangfire job dọn client OAuth do đăng ký động (DCR) tạo ra mà không còn ai dùng, cùng với token và authorization đã hết hiệu lực (sổ nợ CS-16).

Vì sao cần. POST /connect/register là mặt công khai rộng nhất của đợt này: không cần đăng nhập, ai gọi cũng được, và mỗi lời gọi hợp lệ tạo một dòng mới trong OpenIddictApplications. Claude và ChatGPT tự đăng ký lại mỗi lần kết nối, nên bảng đó phình cả khi không có ai phá. Chặn duy nhất hiện có là rate limit 10 lời gọi/phút/IP — tức vẫn 14.400 dòng/ngày/IP nếu ai đó muốn. Không có lượt dọn thì đây là đường làm đầy database mà không cần một tài khoản nào. Ba lớp an toàn để không xoá nhầm. (1) Chỉ đụng client có thuộc tính dcr — client khai tay không có nó và không bao giờ bị xoá. (2) Chỉ xoá client đã quá hạn giữ. (3) Chỉ xoá khi không còn authorization hay token nào trỏ tới — nghĩa là không ai đang dùng, và cũng tránh vỡ khoá ngoại. Luật quyết định nằm ở , có ca test riêng. Thứ tự cố ý: dọn token và authorization trước, rồi mới xét client. Làm ngược lại thì client nào cũng "còn token" vì token hết hạn vẫn nằm đó, và job không bao giờ xoá được gì.

Token / authorization hết hiệu lực cũ hơn bấy nhiêu ngày thì dọn.

14 ngày là đúng hạn refresh token dài nhất (ContentStore:OAuth:RefreshTokenDays mặc định 14) — dọn sớm hơn là cắt phiên của người đang dùng.

Client DCR không còn ai dùng và cũ hơn bấy nhiêu ngày thì xoá.

30 ngày, rộng hơn hẳn hạn token: một client vừa đăng ký xong mà người dùng chưa kịp bấm đồng ý thì chưa có authorization nào — xoá nó ngay là làm hỏng lượt kết nối đang dở.

Trần số client xét mỗi lượt — để một bảng đã phình không làm lượt chạy kéo dài vô hạn.

Luật quyết định xoá client DCR — hàm thuần, không chạm OpenIddict, có ca test riêng.

Tách ra vì đây là chỗ duy nhất của job xoá dữ liệu: một điều kiện viết lỏng tay ở đây là xoá mất client khai tay hoặc cắt phiên của người đang dùng, mà cả hai chỉ lộ ra ở production.

Tên thuộc tính mà McpClientRegistrationService đóng dấu lên client do DCR tạo.

Ngày đăng ký của một client DCR, hoặc null nếu không phải client DCR (hoặc dấu đóng bị hỏng) — và null nghĩa là không được xoá.

Xoá được khi: là client DCR, đăng ký trước , và không còn authorization lẫn token nào trỏ tới.

Hangfire job đồng bộ trạng thái đăng của kho nội dung: bài đã có PostId mà Post đã Đã đăng trong CMS ⇒ bài chuyển sang Đã đăng. Chạy mỗi 15 phút (plan §3.7 bước 5). Vì sao cần job dù đường xuất bản đã biết mình vừa tạo Post gì. Đường mặc định (§7.11) tạo Post ở Chờ xuất bản rồi trả bài lại cho CMS cũ. Người bấm "Đăng" ở đó là người trong màn CMS, và CMS không biết gì về kho nội dung — không có sự kiện nào chạy ngược về. Không có lượt quét này thì bài nằm mãi ở "Đã duyệt" trong khi nó đã lên website từ lâu, và mọi con số thống kê của kho nội dung đọc sai. 15 phút là con số của plan, và nó rẻ: mỗi lượt là một phép nối hai bảng lọc theo hai trạng thái, gần như luôn trả về rỗng. Người vận hành không muốn chờ thì bấm POST /api/ContentPublish/SyncPublishedStatus.

Job đêm franchise-ledger-recheck (SPEC §3.5, M19): đối chiếu lại Ví của các đơn có cập nhật trong FranchiseWallet.RecheckDays ngày gần nhất dính tới bưu cục nhượng quyền, cộng các đơn còn vấn đề mở — bù dòng bị sót khi móc sự kiện lỗi, ghi phải thu / phải nộp cho tiền thu ở màn thu ngân, đóng dấu đơn từ app khách. Idempotent.

Chạy một lượt.

Job franchise-settlement-monthly (SPEC §3.6): sáng mùng 1 lập NHÁP phiếu đối soát kỳ tháng trước cho mỗi ví có dòng chốt trong kỳ. Không phát hành — kế toán xem, điều chỉnh rồi bấm phát hành.

Lập nháp kỳ trước (theo giờ Việt Nam).

Job franchise-settlement-auto-confirm: tự xác nhận phiếu quá hạn 3 ngày làm việc (TS10, SPEC M9).

Chạy một lượt.

Job internal-news-schedule (docs/plan-bang-tin-noi-bo.md §3.7): 5 phút một lần (1) đăng bài hẹn giờ đã tới giờ — gọi ĐÚNG đường đăng của service (ảnh chụp + chuông), không chép logic; (2) chuyển bài quá ExpiresAt sang Đã lưu trữ. Mỗi lần đổi trạng thái là một UPDATE có điều kiện theo trạng thái + mốc sửa cuối, nên hai lần chạy chồng không đăng hai lần và không gửi chuông hai lần. Chưa có bài nào thì no-op.

Mỗi bài đăng trong một phạm vi DI RIÊNG: chuông của một bài lỗi để lại thực thể hỏng trong DbContext, dùng chung một context thì mọi bài sau trong cùng lượt cũng lỗi chuông theo (review GĐ A).

Job internal-price-effective-reminder (SPEC §3.11): 08:00 hằng ngày nhắc bưu cục về bản giá nội bộ bắt đầu áp dụng sau đúng InternalPrice.ReminderDaysBefore ngày, và phiếu đối soát có hạn xác nhận là hôm nay (quá hôm nay hệ thống tự xác nhận).

Chạy một lượt (ngày theo giờ Việt Nam).

Job chốt kỳ KPI — chạy sáng sớm mùng 1 hằng tháng, chốt kỳ THÁNG VỪA QUA (plan §3.4).

Job cố ý mỏng: toàn bộ luật nằm ở để đường thủ công và đường tự động không thể ra hai kết quả khác nhau. Job không được ném ra ngoài (§3.9d). Khác các job khác của repo vốn throw lại cho Hangfire retry: ở đây một lần chạy có thể đã ghi KpiResult cho hàng trăm chỉ tiêu, nên retry tự động không phải là "chạy lại từ đầu" mà là "chạy lại phần còn lại" — service đã idempotent nên vẫn an toàn, nhưng ném ra rồi retry liên tục chỉ làm nhiễu log mà không sửa được nguyên nhân thật (nguồn dữ liệu hỏng). Lỗi từng dòng đã được service gói vào tổng kết; lỗi hạ tầng thì log ERROR để người quản trị vào chốt lại thủ công trong cửa sổ cho phép.

Tài khoản đứng tên chốt khi job tự chạy — 0 là quy ước tài khoản hệ thống của repo (script seed migration cũng ghi CreatedBy = 0, CreatedByUserName = 'SYSTEM')

Hangfire job dọn dẹp thông báo cũ hơn 90 ngày. Chạy hàng ngày lúc 2:00 AM.

Số ngày giữ lại thông báo (retention policy)

Hangfire job kiểm tra ngân sách chương trình KM. Chạy hàng ngày. Cảnh báo khi ngân sách sử dụng >= 80%.

Hangfire job hoàn ví cuối kỳ. Chạy đầu mỗi tháng, tổng hợp đơn thành công tháng trước → tính hoàn thưởng theo RewardRule → credit vào PromotionWallet.

Hangfire job kiểm tra chương trình KM hết hạn → chuyển status Expired. Chạy hàng ngày.

Một tác vụ định kỳ mà hệ thống biết cách đăng ký lại: id, lịch mặc định và biểu thức gọi job.

Id trong Hangfire, ví dụ notification-cleanup.

Tên hiển thị tiếng Việt trên trang Tác vụ nền.

Job làm gì, vì sao chạy vào giờ đó.

Cron 5 trường theo múi giờ Việt Nam.

Tên lớp.phương thức, để trang hiển thị cả khi job chưa đăng ký.

true: tự đăng ký khi API khởi động (trừ khi đã bị tạm dừng). false: chỉ đăng ký khi người vận hành bấm "Đăng ký" trên trang Tác vụ nền.

Đăng ký (hoặc cập nhật) job này vào Hangfire với lịch mặc định.

Danh mục tác vụ định kỳ của hệ thống + cờ "tạm dừng" lưu trong storage Hangfire. Hangfire lưu lịch trong DB, nên xoá/comment dòng AddOrUpdate trong code KHÔNG gỡ job — nó vẫn chạy đều cho tới khi có ai gọi RemoveIfExists. Danh mục này là nguồn sự thật duy nhất về job nào tồn tại, chạy lịch gì; trang /tac-vu-nen đọc nó để cho phép tạm dừng / đăng ký lại.

Set trong storage Hangfire chứa id các job đã bị tạm dừng từ trang Tác vụ nền. Đặt cùng chỗ với dữ liệu Hangfire để production và dev không cần thêm bảng hay migration.

Tìm định nghĩa theo id; null nếu job không nằm trong danh mục (job mồ côi do code cũ để lại).

Id các job đã bị tạm dừng.

Ghi / gỡ cờ tạm dừng cho một job.

Gọi lúc API khởi động: đăng ký mọi job , trừ job đã bị tạm dừng — job đó bị gỡ khỏi lịch để chắc chắn không chạy. Trả về từng dòng mô tả để ghi log.

Kéo bù toàn bộ lịch sử Google còn giữ — một việc chạy đúng một lần, bấm tay. Số tháng để rộng hơn mức Google công bố, có chủ đích. Google nói giữ 16 tháng, nhưng đo thật 2026-09-16 thì dữ liệu đi xa tới 16,4 tháng lịch. Kéo đúng 16 sẽ bỏ lại 12 ngày cũ nhất — đúng phần dễ mất nhất. Mặc định là 17, và phần thừa không tốn gì vì job dừng sau hai lô rỗng. Vì sao là một job riêng chứ không phải một nhánh của job hằng ngày. Lượt này đi ngược 16 tháng, chia thành ~17 lô 30 ngày × 4 mức ≈ 68 lời gọi và mất vài phút. Nhét nó vào job hằng đêm thì hoặc nó chạy lại vô ích mỗi đêm, hoặc phải có một cờ "đã chạy chưa" cất ở đâu đó — mà một cờ như thế luôn là thứ bị đặt sai ở lần deploy tiếp theo. Tách ra thì việc bật/tắt chính là việc bấm hay không bấm. Chạy lại được bao nhiêu lần cũng không hỏng gì. Khoá upsert (Engine, Level, Date, DimensionHash) làm lượt thứ hai ghi đè lượt thứ nhất thay vì nhân đôi. Nó chỉ tốn lời gọi, nên vẫn nên bấm một lần rồi thôi. Cron đặt vào 29/02 lúc 03:03 — ngày hiếm nhất có thể, chứ KHÔNG phải một ngày không tồn tại. Bản ghi chú đầu tiên ở đây viết là "một ngày không tồn tại", và điều đó sai: 29/02 có thật trong năm nhuận, lần tới là 2028. Thứ thật sự giữ job này không tự chạy là autoRegister: false; cron chỉ là lớp phòng thứ hai. Nếu có ai lỡ đăng ký thì hậu quả duy nhất là một lượt kéo thừa vào một ngày 29/02 — vô hại, vì kéo lại không sinh dòng trùng. Dừng ngay khi một lô hỏng. Đi tiếp sau một lỗi sẽ để lại một khoảng trống ở giữa lịch sử mà không ai biết là trống — và bảng số liệu thì không có cách nào phân biệt "tháng ấy không có lưu lượng" với "tháng ấy chưa kéo được". Dừng lại thì lần bấm sau kéo tiếp từ chỗ dở.

Độ dài một lô. 30 ngày vì đo 2026-09-16: lô nhiều dòng nhất (tháng 5/2025) trả 13.657 dòng ở mức mịn nhất — quá nửa trần 25.000 dòng của một lời gọi, nhưng vẫn trong một trang. Lô rộng hơn sẽ thường xuyên phải phân trang; hẹp hơn thì tốn thêm lời gọi vô ích.

Trần số lô cho một lượt bấm. 16 tháng ≈ 17 lô; 40 là dây an toàn chống vòng lặp, không phải một giới hạn nghiệp vụ.

Kéo số liệu hiệu suất tìm kiếm của những ngày gần nhất đã chốt về bảng SearchMetricDaily. Vì sao cửa sổ trượt chứ không phải "kéo hôm qua". Google chốt số chậm vài ngày, và còn sửa lại số của những ngày đã chốt gần nhất. Kéo đúng một ngày rồi thôi là giữ mãi một con số tạm thời — và sai vĩnh viễn, vì lượt sau sẽ không bao giờ quay lại ngày đó. Kéo lại một cửa sổ 10 ngày mỗi đêm thì mỗi ngày được ghi đè 10 lần trước khi trôi ra khỏi tầm với, và khoá upsert làm việc ghi đè ấy không sinh dòng trùng. Job này KHÔNG kéo bù lịch sử. Lượt kéo 16 tháng là một việc chạy đúng một lần, kéo dài vài chục lời gọi — nhét nó vào job hằng đêm thì hoặc nó chạy lại vô ích mỗi đêm, hoặc phải có một cờ "đã chạy chưa" nằm đâu đó. Tách thành bấm tay. Chạy lúc 05:23. Lệch khỏi phút tròn và khỏi giờ tròn cùng lý do với các job khác của miền này: không xếp hàng cùng lúc với mọi job khác trong hệ thống. Sau 05:00 vì lượt kéo này đọc số của những ngày đã qua hẳn, không có gì phải chờ. Khai autoRegister: false như ba job gọi Google khác: sau khi deploy nó tồn tại nhưng không tự chạy, cho tới khi người vận hành bấm "Đăng ký" ở trang Tác vụ nền. Công tắc Search.Google.Enabled còn tắt thì kể cả có đăng ký nó cũng không gọi gì ra ngoài.

Khoảng ngày của lượt chạy này: [hôm nay − N, hôm nay − 1]. Không cần trừ thêm độ trễ chốt số của Google: client viết cứng dataState=final, nên những ngày chưa chốt đơn giản là không được trả về. Đo 2026-09-16: hỏi tới hôm nay thì final trả tới T−3, không trả T−2 và T−1. Hỏi rộng hơn thực tế chỉ tốn đúng một khoảng trống trong phản hồi, còn hỏi hẹp hơn thì có ngày không bao giờ được kéo.

Câu nói ra ý nghĩa của con số 0, thay vì để người đọc tự đoán. Ở miền này có ba cách ra số 0 khác hẳn nhau và chúng đòi ba phản ứng khác nhau: chưa kéo bao giờ (bấm chạy đi), đã kéo mà Google chưa chốt ngày nào trong cửa sổ (chờ), và đã kéo mà website thật sự không có lượt hiển thị nào (đó là một tin, không phải một lỗi).

Dọn nhật ký lời gọi và nhật ký đổi trạng thái index. Job này ra đời cùng lúc với hai bảng nó dọn, không để lại thành việc phải nhớ — bảng AdsSyncLog của miền quảng cáo đã cho thấy hậu quả của cách làm ngược lại (nợ Ads N-7: bảng log không có ai dọn). Ba thứ được dọn, hai thời hạn. Nhật ký lời gọi là thứ để gỡ lỗi trong vài tuần (Search.ApiLogRetentionDays, mặc định 30 ngày). Nhật ký đổi trạng thái là thứ để đọc xu hướng, giữ 180 ngày — cố định trong code vì nó không phải nút vặn của vận hành mà là một quyết định về ý nghĩa dữ liệu. Hàng đợi thông báo URL đi theo thời hạn của nhật ký lời gọi vì nó cùng bản chất: dấu vết của một việc đã xong. Việc CHƯA gửi không bao giờ bị dọn. Một dòng còn ở trạng thái chờ là việc chưa làm chứ không phải dấu vết; xoá nó là làm mất việc, và mất im lặng. Không gọi ra ngoài nên tự đăng ký khi khởi động, khác ba job còn lại.

Số ngày giữ nhật ký đổi trạng thái index.

Xoá hẳn các dòng nhật ký đã quá hạn.

Hỏi công cụ tìm kiếm trạng thái index của từng URL trong hàng tồn kho. Thứ tự ưu tiên có lý do. Hạn mức mỗi ngày không đủ để kiểm lại tất cả mãi mãi, nên phải chọn: (1) URL chưa từng kiểm — không biết gì là tệ hơn biết một thông tin cũ; (2) URL có lastmod mới hơn lần Google thu thập gần nhất — đây chính là câu hỏi của cả đợt, "trang nào vừa sửa mà Google chưa đọc lại"; (3) còn lại thì lấy URL lâu chưa kiểm nhất, để mọi trang đều được ghé qua theo vòng. Gặp 429 là dừng hẳn lượt chạy, không thử lại và không đi tiếp: hết hạn mức thì mọi URL còn lại cũng sẽ hỏng y như vậy, và mỗi lần thử thêm là tiêu thêm vào phần hạn mức đang cạn. Phần chưa kiểm để lượt sau — hàng đợi tự sắp lại đúng thứ tự ưu tiên trên.

Tên việc ghi vào nhật ký — cũng là khoá đếm hạn mức đã dùng trong ngày.

Kiểm trạng thái index cho tới khi hết hàng đợi hoặc hết hạn mức ngày.

Chạy một mình. Người vận hành bấm chạy tay trong lúc lượt theo lịch đang chạy sẽ làm hai lượt cùng đọc một sổ đếm hạn mức rồi cùng kiểm một danh sách URL — tiêu gấp đôi hạn mức cho đúng ngần ấy thông tin. Lượt thứ hai bị bỏ ngay thay vì xếp hàng chờ: hàng đợi tự sắp lại đúng thứ tự ưu tiên ở lượt sau, không có gì để giữ.

Xếp hàng đợi theo ba mức ưu tiên đã mô tả ở phần đầu lớp. Sắp xếp trong bộ nhớ vì hàng tồn kho chỉ khoảng 150 dòng — viết thành một truy vấn SQL sẽ khó đọc hơn nhiều mà không nhanh hơn.

Ghi đè trạng thái hiện tại và ghi thêm một dòng lịch sử chỉ khi CoverageState hoặc Verdict đổi.

true nếu trạng thái vừa đổi.

Cắt một chuỗi về đúng độ dài cột; null giữ nguyên là null.

0 = chưa từng kiểm, 1 = đã sửa sau lần Google thu thập, 2 = còn lại.

Dựng lại hàng tồn kho URL mỗi đêm từ chính tệp sitemap.xml mà công cụ tìm kiếm đọc. Job duy nhất của đợt này không gọi ra ngoài — nó chỉ tải một tệp công khai của chính website. Nên nó chạy được ngay cả khi mọi công tắc còn tắt, và đó là chủ ý: hàng tồn kho phải dựng xong và đối chiếu được bằng mắt trước khi có lời gọi đầu tiên ra Google. Số URL dựng được phải bằng số URL trong sitemap tại thời điểm chạy — không phải một con số cố định. Sitemap production ngày 15/09/2026 có 151 URL / 148 khác nhau; sau khi giai đoạn trước lên production sẽ là 151 URL không trùng nhau.

Tải sitemap và ghi lại chênh lệch vào bảng SearchUrl.

Chạy một mình. Hai lượt song song cùng thêm một URL mới sẽ đâm vào chỉ số duy nhất trên cột Url và cả hai cùng hỏng.

Đọc trạng thái tệp sitemap dưới mắt công cụ tìm kiếm, và nộp lại tệp khi có thay đổi đáng nộp. Hai công tắc, hai vai. Search.Google.Enabled cho phép đọc trạng thái; Search.Google.SubmitEnabled cho phép nộp. Khi công tắc nộp còn tắt, job vẫn chạy hết logic — kể cả bước quyết định "có đáng nộp không" — rồi ghi vào nhật ký một dòng DryRun kèm danh sách URL vừa đổi. Đây là cách duy nhất để biết trước mình sắp báo cho Google cái gì; bật công tắc chỉ sau khi đọc dòng đó thấy đúng. Không nộp lại mỗi ngày một cách vô điều kiện. Nộp một tệp không đổi gì chỉ dạy công cụ tìm kiếm rằng tín hiệu của mình vô nghĩa. Job chỉ nộp khi có URL mới xuất hiện hoặc có URL đổi lastmod kể từ đầu ngày hôm qua.

Tên việc khi nộp thật.

Tên việc khi chạy thử — không có lời gọi nào đi ra.

Tên việc khi đọc trạng thái tệp sitemap.

Cửa sổ coi là "vừa đổi", tính bằng ngày chứ không bằng giờ. Vì sao không dùng "24 giờ qua". Thẻ lastmod trong sitemap chỉ ghi ngày, không ghi giờ (đo trên sitemap production 15/09/2026: 141/141 thẻ ở dạng 2026-09-14), nên khi đọc vào nó thành 00:00 của ngày đó. Job chạy 4:17 sáng mà so với mốc "24 giờ trước" tức 4:17 hôm qua thì một trang sửa hôm qua có lastmod 00:00 hôm qua luôn rớt — và rớt vĩnh viễn, vì hôm sau nó còn cũ hơn. Kết quả là sửa nội dung trang cũ sẽ không bao giờ kích hoạt nộp lại sitemap. Lấy mốc là đầu ngày hôm qua thì cả trang sửa hôm qua lẫn hôm nay đều lọt.

Số URL tối đa liệt kê trong nhật ký chạy thử — đủ để đọc mà không phình bảng.

Đọc trạng thái sitemap, rồi nộp lại (hoặc chạy thử) khi có thay đổi.

Chạy một mình, cùng lý do với job kiểm trạng thái: hai lượt song song sẽ nộp sitemap hai lần liền nhau và cùng ghi vào một dòng trạng thái tệp.

Đọc trạng thái tệp sitemap và ghi đè dòng trạng thái hiện tại.

URL mới xuất hiện hoặc vừa đổi lastmod kể từ đầu ngày hôm qua.

Gửi hàng đợi thông báo URL cho công cụ tìm kiếm. Vì sao mười lăm phút một lần chứ không phải mỗi ngày. Giá trị của Indexing API nằm ở chỗ nhanh — một tin tuyển dụng mới được Google đọc trong vài phút thay vì chờ lượt thu thập tự nhiên. Chạy hằng ngày là vứt bỏ đúng cái lý do dùng nó. Mười lăm phút đủ nhanh mà vẫn gộp được nhiều lần sửa liên tiếp của cùng một tin thành một lời gọi. Khi công tắc còn tắt, job KHÔNG để hàng đợi tích lại. Nó đánh dấu các việc đang chờ thành kèm lý do, và ghi một dòng nhật ký chạy thử liệt kê đúng những URL đã có thể được gửi. Hai lý do: Đọc nhật ký ấy là cách duy nhất biết trước mình sắp báo Google cái gì — điều kiện bắt buộc trước lượt ghi đầu tiên theo Nguyên tắc số 1 của cả đợt. Để chúng nằm chờ thì ngày bật công tắc sẽ dội ra Google một loạt "vừa cập nhật" cho những tin sửa từ hàng tuần trước — đó không phải tín hiệu thật, và đó đúng là thứ Nguyên tắc số 1 cấm. Khai autoRegister: false cùng nhóm với ba job gọi Google: phải có người bấm "Đăng ký" trên trang Tác vụ nền sau khi bật công tắc.

Tên việc khi gửi thật — cũng là khoá đếm hạn mức trong ngày.

Tên việc khi chạy thử. Cố ý khác tên chạy thử của job nộp sitemap: hai đường đi ra ngoài khác nhau thì phải đếm và đọc được tách nhau.

Số việc tối đa nhặt trong một lượt chạy, trước khi gộp trùng. Trần này không phải hạn mức ngày mà là hàng rào chống một lượt chạy đọc cả bảng vào bộ nhớ khi hàng đợi bất ngờ phình (một job đồng bộ chạm hàng loạt tin chẳng hạn). Hạn mức ngày được xét riêng, sau khi đã gộp.

Số lượt thử tối đa cho một việc. Hết lượt thì chuyển hẳn sang thay vì thử lại mỗi mười lăm phút mãi mãi — một URL Google từ chối vì trang thiếu dữ liệu có cấu trúc sẽ bị từ chối y như thế ở lượt thứ một nghìn.

Số URL tối đa liệt kê trong một dòng nhật ký.

Nhặt hàng đợi, gộp trùng, rồi gửi (hoặc chạy thử) trong phạm vi hạn mức ngày.

Chạy một mình: hai lượt song song sẽ cùng nhặt một dòng và gửi hai lần — vừa tốn hạn mức vừa làm sổ đếm sai.

Các việc đang chờ, cũ trước — hàng đợi phải công bằng theo thứ tự xếp hàng.

Gộp các việc theo URL. Loại thông báo lấy theo việc mới nhất của URL đó.

Thứ tự quan trọng và chỉ có một cách đúng: nếu một tin vừa được sửa rồi bị xoá, trạng thái sau cùng là "đã gỡ" — báo "vừa cập nhật" cho một trang không còn nữa là sai. Chiều ngược lại (xoá rồi khôi phục) thì việc mới nhất là "cập nhật", cũng đúng.

Chạy thử: ghi đúng thứ sẽ gửi rồi khép các việc lại, không gửi gì.

Gửi thật, dừng đúng ở hạn mức còn lại.

Khép một việc lại ở trạng thái cuối.

Một URL cùng mọi việc đang chờ của nó trong lượt chạy này.

Một URL cùng mọi việc đang chờ của nó trong lượt chạy này.

Kết quả một lượt quét — để log và để test khẳng định bằng số thay vì bằng lời.

Số bộ phận đã xét

Số cảnh báo mới tạo

Số cảnh báo được đóng lại vì bộ phận đã khoẻ hoặc đã đổi mức

Số cảnh báo đã gửi thông báo trong lượt này

Công tắc gửi thông báo lúc quét

Quét tuổi thọ toàn bộ bộ phận đang lắp, sinh cảnh báo và gửi thông báo.

Một công tắc duy nhất cho cả luồng gửi (TruckMaintenance.NotificationEnabled, mặc định TẮT): tắt thì job vẫn quét và ghi TruckComponentAlert nhưng để NotifiedAt null — đúng chế độ chạy thử của §5.2 bước 4. Hai công tắc liên quan nhau là bài học lệch số của đợt GoodsLines, ở đây cố ý chỉ có một.

Tên bộ phận kèm vị trí — "Lốp (Trục 2 - trái ngoài)"

Diễn giải "còn bao nhiêu" / "quá bao nhiêu" theo tiêu chí đến trước.

Chọn con số nhỏ hơn giữa km và ngày để câu thông báo nói đúng cái sắp chạm trước; tiêu chí nào không tính được thì bỏ qua, không bịa số.

Job tự chữa dấu vân tay nội dung: mỗi đêm tính lại dấu vân tay của mọi URL bài viết, dịch vụ và tin tuyển dụng rồi đối chiếu với giá trị đang lưu. Vì sao cần dù ba dịch vụ lưu đã tự đóng dấu. Đường sửa mới thêm về sau — một màn quản trị khác, một lệnh nhập hàng loạt, một job đồng bộ — sẽ không tự biết phải đóng dấu. Không có job này thì nội dung đổi mà lastmod đứng yên, và không ai phát hiện ra cho tới lúc thắc mắc vì sao Google không đọc lại trang. Có job thì sai sót chỉ trễ tối đa một ngày, và dòng cảnh báo chỉ thẳng slug nào đang đi qua đường không đóng dấu. Dấu vân tay chưa có thì điền im lặng, không dời mốc. Ngay sau khi backfill, cả 91 URL trên DB dev đều chưa có dấu vân tay; nếu job coi "chưa có" là "đã đổi" thì toàn bộ website khai vừa sửa trong cùng một đêm — đúng loại tín hiệu giả mà cả đợt này được lập ra để tránh.

Quét toàn bộ URL của ba nhóm thực thể có nội dung và chữa dấu vân tay lệch.

Số dấu vân tay được điền mới và số URL bị dời mốc vì nội dung đã đổi.

Áp dấu vân tay vừa tính và đếm kết quả. Một URL bị dời mốc ở đây nghĩa là nội dung của nó đã đổi qua một đường không đóng dấu — ghi cảnh báo kèm slug để còn lần ra đường đó.

Hangfire job để đồng bộ hóa đơn VAT hàng ngày

Execute job - đồng bộ hóa đơn của ngày hôm qua

data của mọi tool truy vấn fact qua (query_shipments, query_stops, query_vehicles nhien_lieu).

Bảng đã trả — chỉ tool nhiều bảng (query_vehicles); null thì không có khoá.

Mỗi dòng: khoá = mã chiều / chỉ tiêu (hoặc mã cột phân bố).

Cùng chỉ tiêu trên toàn bộ kỳ + bộ lọc, không nhóm.

Nhãn mức cân đang dùng — chỉ có khi chiều mức cân được dùng.

Lần nạp thành công gần nhất.

Ngày cuối cùng có số đủ (ngày trước lần nạp gần nhất, giờ Việt Nam).

Ngày đầu tiên có số đủ (mốc của lượt nạp lại 400 ngày thành công gần nhất).

Phần chung của các tool truy vấn fact (docs/plan-mcp-tra-cuu-so-lieu.md §3.4): công tắc mã người, lỗi tham số, độ tươi + mốc phủ (NO_DATA), cảnh báo độ tươi / phân trang, vỏ . Tool chỉ còn dựng request và cảnh báo riêng của chủ đề — hai tool không lệch nhau ở luật chung.

Khoá AppConfig bật/tắt chiều mã người (câu hỏi Q3). Thiếu khoá hoặc giá trị khác "true" = TẮT (fail-closed).

Lỗi tham số của engine → vỏ lỗi (mã của lỗi đầu tiên, mọi lỗi ở errors[]).

Độ tươi của chủ đề; Failure khác null = trả NO_DATA: chưa nạp thành công lần nào, hoặc chỉ có lượt đêm mà chưa lượt nạp lại cả cửa sổ nào thành công (trả số là trả tổng thiếu lịch sử — review GĐ B).

"Fact vận đơn", "Fact điểm dừng" — mở đầu câu báo.

Ngày cuối có số đủ = ngày trước lần nạp thành công gần nhất (giờ Việt Nam).

Cảnh báo chung: lượt nạp lỗi, kỳ vượt ngày đủ số, kỳ trước mốc phủ, không dòng nào, phân trang.

Câu khi bộ lọc không khớp dòng nào ("Không có vận đơn nào khớp …"). Bảng của tool nhiều bảng (query_vehicles: nhien_lieu); null = tool một bảng, không trả khoá table.

Dòng kết quả → JObject giữ null tường minh (serializer của MCP bỏ thuộc tính null của đối tượng C#).

Hợp đồng giữa MCP số liệu (/analytics) và trợ lý AI — chỉ dẫn server (initialize.instructions), số hiệu hợp đồng và mã lỗi (docs/plan-mcp-tra-cuu-so-lieu.md §3.7). Nguồn sự thật duy nhất cùng với mô tả từng tool và AnalyticsCatalog; tách khỏi của kho nội dung vì hai hợp đồng tiến hoá độc lập.

Luật giữ hợp đồng khỏi lệch pha (bài học ): đổi hành vi, đổi tên hay định nghĩa một chiều/chỉ tiêu thì sửa mô tả + catalog trong cùng commit, nâng và . Định nghĩa cũ giữ trong describe_catalog kèm ngày hết hiệu lực (yêu cầu §6). Test AnalyticsContractTests canh: chỉ dẫn mang và ≤ 1.500 ký tự, mọi mô tả tool nêu role + scope, mọi mã snake_case nhắc trong chỉ dẫn/mô tả tồn tại trong catalog hoặc tham số tool.

Số hiệu hợp đồng. Nâng khi tên/định nghĩa chiều, chỉ tiêu hoặc hành vi tool đổi.

Ngày hành vi của bản hợp đồng này có hiệu lực. 0.1 (GĐ A, 2026-09-23) = chỉ describe_catalog; 0.2 (GĐ B, 2026-09-24) mở query_shipments; 0.3 (GĐ C, 2026-09-24) mở query_stops + get_price_tables; 0.4 (GĐ D, 2026-09-26) mở query_vehicles; 0.5 (GĐ E, 2026-09-26) mở query_revenue, query_claims, query_hub_throughput và cho don_vi_sale theo công tắc mã người. Là ngày CHỐT HÀNH VI trong code, không phải ngày lên production (plan §7 GĐ D: ngày production chưa biết lúc build, hằng không đổi được sau build — ngày production ghi ở docs/mcp-tra-cuu-so-lieu.md §10).

Chuỗi trợ lý so với đặc tả nó đang cầm: contract: 0.1 — 2026-09-23.

Phiên bản server báo trong initialize.serverInfo.version.

Tên hiển thị của server.

Mã lỗi riêng của MCP số liệu (plan §3.7), cộng FORBIDDEN / RATE_LIMITED / UNAVAILABLE dùng chung của lớp MCP.

Mọi mã lỗi trợ lý có thể gặp ở /analytics — liệt kê trong chỉ dẫn.

Chỉ dẫn server trả trong initialize ở /analytics — thứ trợ lý đọc trước khi gọi tool đầu tiên.

Mặt không generic của mọi tool số liệu — để test hợp đồng và bộ tool duyệt được mọi tool bất kể kiểu tham số.

Lớp nền mỏng của mọi tool MCP số liệu (docs/plan-mcp-tra-cuu-so-lieu.md §3.1, §3.10) — kế thừa nguyên trạng (guard quyền, đọc tham số snake_case, vỏ kết quả, không JSON-RPC error), và thêm ba thứ riêng của miền số liệu: role Analytics.Read + scope analytics:read, chỉ đọc, idempotent — cố định, tool con không chọn; công tắc Analytics:Enabled TẮT → UNAVAILABLE; quét MỌI kết quả trước khi trả (lớp 3 hàng rào dữ liệu cá nhân); ghi AnalyticsCallLog cho MỌI lời gọi — kể cả bị guard từ chối, kể cả tham số sai.

Tool số liệu KHÔNG đăng ký vào DI qua WithTools: chúng chỉ nằm trong bộ tool của mặt /analytics (), nên về cấu trúc không thể hiện ra ở /mcp.

Tham số sai kiểu → INVALID_PARAM (bảng mã lỗi của hợp đồng số liệu, không phải VALIDATION_ERROR của kho nội dung).

Thân tool số liệu. Lỗi nghiệp vụ nằm trong vỏ; đặt để ghi nhật ký.

Chạy trên data và extra rồi trả vỏ MỚI mang CHÍNH cây JSON đã quét (không dựng lại từ đối tượng gốc — một lần chuyển đổi cho mỗi lời gọi). Có chỗ phải che thì kèm cảnh báo và log LỖI (dấu hiệu dữ liệu bẩn lọt vào schema analytics — phải đi tìm nguồn).

Danh sách tool của mặt /analytics — thứ tự hiện trong tools/list. Mô tả từng tool là hợp đồng với trợ lý AI (): đổi hành vi thì sửa mô tả trong cùng commit.

Bộ tool + chỉ dẫn của mặt /analytics, gán vào McpServerOptions của từng request trong ConfigureSessionOptions (xem McpRegister). Singleton: tool là đối tượng không trạng thái, dựng một lần.

Spike SDK 2.2.0 (plan §4 GĐ A): ở chế độ Stateless mỗi request nhận một McpServerOptions MỚI từ IOptionsFactory, và server đọc tools/list, tools/call, instructions từ đúng bản đó — nên gán ở đây là tách hẳn bộ tool theo endpoint. Luôn gán một collection MỚI (), không sửa collection có sẵn: collection dùng chung mà ai đó lỡ Add vào là rò giữa các request đồng thời.

Thay bộ tool, chỉ dẫn và thông tin server của một request /analytics.

Tham số describe_catalog (T1, yêu cầu §5).

Chỉ trả một chủ đề: shipments, stops, vehicles, prices, revenue, claims, hubs (trips = vehicles). Bỏ trống = mọi chủ đề.

Kèm danh mục: chi nhánh/bưu cục, tỉnh, loại hàng, xe (không biển số), dải cự ly, bảng giá công khai, tham số cước. Mặc định false.

Mã tỉnh bộ 2 cấp (ví dụ "01") — kèm danh sách xã/phường của tỉnh đó; chỉ có tác dụng khi include_lists = true.

Danh mục theo tên (chi_nhanh, tinh, xa_phuong…) — khoá khớp lookup của chiều.

Lần nạp danh mục thành công gần nhất.

Theo chủ đề nạp (danh_muc, shipments…): lần thành công gần nhất + trạng thái lượt gần nhất.

Ngày đầu tiên có số đủ (fact nạp lại cả cửa sổ); null = chủ đề chưa có lượt nạp lại nào.

Chỉ tiêu trả khi bỏ trống metrics.

Phân bố nhận ở tham số histogram_of.

Mã cột nhóm trong rows[] và các nhóm theo thứ tự.

describe_catalog — T1: từ điển số liệu (chủ đề, chiều, chỉ tiêu kèm định nghĩa + công thức, mục chưa có dữ liệu kèm lý do) sinh thẳng từ , cộng độ tươi từ analytics.LoadRun và — khi include_lists — danh mục từ analytics.Dim*.

Tên các danh mục trong lists — khớp lookup của chiều trong catalog.

Khoá AppConfig liệt kê Id đơn vị là "trung tâm khai thác" (quyết định Q7, 2026-09-26) — cùng khoá builder lượt qua trung tâm đọc.

Trung tâm khai thác = các Id đơn vị khai ở AppConfig (Q7) — cùng luật đọc với builder lượt qua trung tâm.

Tham số get_price_tables (T5, yêu cầu §5).

Bảng: niem_yet (mặc định) | dai_cu_ly | phu_phi | khu_vuc_xa | dich_vu_cong_them | bang_gia_loai_hang.

Ngày hiệu lực (YYYY-MM-DD, mặc định hôm nay). Bảng giá không lưu ngày hiệu lực: khác hôm nay → cảnh báo NO_HISTORY.

Xin cả lịch sử bảng giá — không có (cảnh báo NO_HISTORY), vẫn trả bảng đang lưu.

data của get_price_tables.

Ngày đã dùng để chọn tham số cước (FeeConfig có ngày hiệu lực); bảng giá luôn là bản đang lưu.

Giá trong bảng ĐÃ GỒM VAT (đo GĐ C) — khác mọi chỉ tiêu tiền của query_shipments.

Thuế suất VAT hiệu lực tại effective_date — để quy giá gồm VAT về chưa VAT.

Cách ra cước từ bảng niem_yet (chỉ có ở bảng đó).

Mỗi dòng: khoá = mã trong describe_catalog topic prices.

get_price_tables — T5: bảng giá CÔNG KHAI và tham số cước đang hiệu lực, đọc thẳng các bảng danh mục analytics.Dim* (không kỳ, không nhóm — không qua ) bằng login chỉ đọc.

Giá lưu ĐÃ GỒM VAT (, đo Việc 0 GĐ C) nên trả kèm cờ gom_vat + thuế suất thay vì tự quy đổi từng dòng: bước giá theo cân quy đổi từng dòng rồi cộng sẽ lệch làm tròn so với cước hệ thống tính. Bảng niem_yet trả luật ra cước () cùng các cột gia_nen, moc_nen_kg dựng sẵn cho dòng theo bước — đúng luật FeeService.GetFeeByWeightAxis; test DB tính lại bằng chính FeeService trên dữ liệu dev (nghiệm thu 5 phần "khớp engine").

Trần số dòng một lời gọi (danh sách xã khu vực xa có thể dài).

Bảng chung theo cân (GoodsCategoryId null) của mọi dải còn hiệu lực — thứ tự dải, rồi cân, fix trước bước.

Một dòng tham số: ma = mã chỉ tiêu trong catalog (nhãn, đơn vị lấy từ đó).

Tham số cước hiệu lực tại một ngày — đúng luật FeeConfigProvider.GetValueAsync: dòng có EffectiveFrom muộn nhất thắng (rồi Id lớn nhất); không dòng nào → hằng dự phòng FeeConfigProvider.DefaultValues.

Bỏ số 0 thừa sau dấu phẩy (80000.00 → 80000, 0.500 → 0.5) — cột decimal(18,2)/(12,3) đọc ra giữ scale.

Ô số của dòng: null giữ tường minh; số nguyên in không đuôi ".0" (Newtonsoft in decimal 80000 thành 80000.0).

Tham số query_claims (T7, yêu cầu §5 giai đoạn 2 — chỉ số vụ).

Từ ngày, gồm (YYYY-MM-DD, giờ Việt Nam). Bắt buộc; khoảng tối đa 400 ngày.

Đến ngày, gồm (YYYY-MM-DD, giờ Việt Nam). Bắt buộc.

Cột ngày dùng để lọc kỳ: gui (ngày khách gửi — mặc định) | giai_quyet (ngày giải quyết).

Mảng mã chiều để nhóm, tối đa 6 (describe_catalog topic claims). Bỏ trống = một dòng tổng.

Lọc: {mã chiều: giá trị | [giá trị, …]}; null trong mảng = lọc ô trống; tối đa 500 giá trị mỗi chiều.

Mảng mã chỉ tiêu. Bỏ trống = so_vu, so_van_don_lien_quan, so_vu_da_giai_quyet.

Mốc mức cân (kg, tăng dần, cận trên gồm) thay mốc mặc định của chiều bac_can.

Trang, bắt đầu từ 1.

Số dòng một trang: mặc định 1000, tối đa 5000.

Sắp xếp "mã asc|desc, mã asc|desc" — mã phải có trong group_by hoặc metrics. Mặc định theo group_by tăng dần.

query_claims — T7: khiếu nại của khách trên analytics.ComplaintFact, CHỈ SỐ VỤ (hệ thống không lưu tiền bồi thường, tiền hỗ trợ, bên lỗi — AN-3). Cùng engine với các tool fact khác; đơn vị suy qua vận đơn của khiếu nại.

Cảnh báo theo bộ đếm chẩn đoán của đúng tập khiếu nại đã lọc.

Tham số query_hub_throughput (T8, yêu cầu §5 giai đoạn 2).

Từ ngày, gồm (YYYY-MM-DD, giờ Việt Nam) — theo ngày hàng đến / rời trung tâm. Bắt buộc; khoảng tối đa 400 ngày.

Đến ngày, gồm (YYYY-MM-DD, giờ Việt Nam). Bắt buộc.

Mảng mã chiều để nhóm, tối đa 6 (describe_catalog topic hubs). Bỏ trống = một dòng tổng.

Lọc: {mã chiều: giá trị | [giá trị, …]}; null trong mảng = lọc ô trống; tối đa 500 giá trị mỗi chiều.

Mảng mã chỉ tiêu. Bỏ trống = so_van_don_qua, so_luot, tong_kg, so_van_don_bq_ngay, thoi_gian_luu_kho_bq_gio.

Mốc mức cân (kg, tăng dần, cận trên gồm) thay mốc mặc định của chiều bac_can.

Trang, bắt đầu từ 1.

Số dòng một trang: mặc định 1000, tối đa 5000.

Sắp xếp "mã asc|desc, mã asc|desc" — mã phải có trong group_by hoặc metrics. Mặc định theo group_by tăng dần.

query_hub_throughput — T8: sản lượng qua trung tâm khai thác trên analytics.HubEventFact (lượt hàng đến / rời các đơn vị khai ở AppConfig Analytics.HubAgencyIds). Chỉ tiêu theo ngày (so_van_don_bq_ngay, phân vị) là chỉ tiêu hai tầng của engine trên cặp (nhóm, ngày).

Danh sách trung tâm của lượt nạp gần nhất (khoá hubs= trong LoadRun.Message); null khi không đọc được.

Cảnh báo theo bộ đếm chẩn đoán của đúng tập lượt đã lọc.

Tham số query_revenue (T6, yêu cầu §5 giai đoạn 2).

Từ ngày, gồm (YYYY-MM-DD, giờ Việt Nam). Bắt buộc; khoảng tối đa 400 ngày.

Đến ngày, gồm (YYYY-MM-DD, giờ Việt Nam). Bắt buộc.

Cột ngày dùng để lọc kỳ: tao (ngày tạo đơn) | lay (ngày lấy hàng — mặc định) | giao (ngày giao thành công).

Mảng mã chiều để nhóm, tối đa 6 (describe_catalog topic revenue). Bỏ trống = một dòng tổng.

Lọc: {mã chiều: giá trị | [giá trị, …]}; null trong mảng = lọc ô trống; tối đa 500 giá trị mỗi chiều.

Mảng mã chỉ tiêu. Bỏ trống = doanh_thu_cuoc_chua_vat, doanh_thu_niem_yet_tuong_ung, ty_le_giam_bq, so_khach.

Trang, bắt đầu từ 1.

Số dòng một trang: mặc định 1000, tối đa 5000.

Sắp xếp "mã asc|desc, mã asc|desc" — mã phải có trong group_by hoặc metrics. Mặc định theo group_by tăng dần.

query_revenue — T6: doanh thu cước và giảm giá theo nhóm trên analytics.ShipmentFact (cùng bảng fact với query_shipments, chủ đề revenue bỏ đơn huỷ bằng điều kiện dòng cố định của catalog). Tỷ trọng 10 khách lớn nhất là chỉ tiêu hai tầng có hạng cặp của engine () — không SQL riêng ngoài catalog.

Cảnh báo theo bộ đếm chẩn đoán của đúng tập đơn (không huỷ) đã lọc.

Tham số query_shipments (T2, yêu cầu §5 + §6).

Từ ngày, gồm (YYYY-MM-DD, giờ Việt Nam). Bắt buộc; khoảng tối đa 400 ngày.

Đến ngày, gồm (YYYY-MM-DD, giờ Việt Nam). Bắt buộc.

Cột ngày dùng để lọc kỳ: tao (ngày tạo đơn) | lay (ngày lấy hàng — mặc định) | giao (ngày giao thành công).

Mảng mã chiều để nhóm, tối đa 6 (describe_catalog topic shipments). Bỏ trống = một dòng tổng.

Lọc: {mã chiều: giá trị | [giá trị, …]}; null trong mảng = lọc ô trống; tối đa 500 giá trị mỗi chiều.

Mảng mã chỉ tiêu. Bỏ trống = so_van_don, so_kien, tong_kg_tinh_cuoc, tong_cuoc_thuc_chua_vat.

Mốc mức cân (kg, tăng dần, cận trên gồm) thay mốc mặc định của chiều bac_can, ví dụ [5, 25, 100].

Trả phân bố thay cho chỉ tiêu: van_don_cung_khach_cung_ngay.

Trang, bắt đầu từ 1.

Số dòng một trang: mặc định 1000, tối đa 5000.

Sắp xếp "mã asc|desc, mã asc|desc" — mã phải có trong group_by hoặc metrics. Mặc định theo group_by tăng dần.

query_shipments — T2: tổng hợp vận đơn trên analytics.ShipmentFact theo chiều/chỉ tiêu của . Kiểm tham số + sinh SQL ở (lớp thuần), chạy ở (login chỉ đọc); tool chỉ ghép cảnh báo và vỏ kết quả.

Cảnh báo theo số liệu thật của lời gọi (bộ đếm chẩn đoán tính trên đúng tập dòng đã lọc).

Tham số query_stops (T3, yêu cầu §5 — nghĩa ĐD-1 theo lái xe, plan §2.10).

Từ ngày, gồm (YYYY-MM-DD, giờ Việt Nam) — theo ngày của điểm dừng. Bắt buộc; khoảng tối đa 400 ngày.

Đến ngày, gồm (YYYY-MM-DD, giờ Việt Nam). Bắt buộc.

Mảng mã chiều để nhóm, tối đa 6 (describe_catalog topic stops). Bỏ trống = một dòng tổng.

Lọc: {mã chiều: giá trị | [giá trị, …]}; null trong mảng = lọc ô trống; tối đa 500 giá trị mỗi chiều.

Mảng mã chỉ tiêu. Bỏ trống = so_diem_dung, so_van_don, van_don_bq_moi_diem, diem_bq_moi_lai_xe_ngay.

Mốc mức cân (kg, tăng dần, cận trên gồm) thay mốc mặc định của chiều bac_can_lon_nhat_tai_diem.

Trang, bắt đầu từ 1.

Số dòng một trang: mặc định 1000, tối đa 5000.

Sắp xếp "mã asc|desc, mã asc|desc" — mã phải có trong group_by hoặc metrics. Mặc định theo group_by tăng dần.

query_stops — T3: điểm dừng lấy/giao ƯỚC LƯỢNG (ĐD-1, plan §3.6) trên analytics.StopFact. Cùng engine với query_shipments (): chỉ tiêu *_lai_xe_ngay là chỉ tiêu hai tầng — engine gộp theo (nhóm, lái xe, ngày) trước rồi mới bình quân/phân vị.

Nghiệm thu 3 (3 lái xe × 5 ngày đếm tay, ±1 điểm) chưa có người đếm (Q9, 2026-09-24) — mọi kết quả kèm cảnh báo "chưa nghiệm thu"; khi nghiệp vụ đếm xong và đạt thì đặt = true cùng lượt nâng hợp đồng.

Định nghĩa ĐD-1 đã qua nghiệm thu 3 với đếm tay chưa.

Cảnh báo theo bộ đếm chẩn đoán của đúng tập điểm dừng đã lọc.

Tham số query_vehicles (thay T4 query_trips, plan §2.10).

Bảng: nhien_lieu (mặc định — lần đổ dầu theo kỳ) | doi_xe (đội xe hiện có, không kỳ).

Từ ngày, gồm (YYYY-MM-DD, giờ Việt Nam) — theo ngày đổ dầu. Bắt buộc ở nhien_lieu; khoảng tối đa 400 ngày.

Đến ngày, gồm (YYYY-MM-DD). Bắt buộc ở nhien_lieu.

Mảng mã chiều để nhóm, tối đa 6 (describe_catalog topic vehicles). Bỏ trống = một dòng tổng.

Lọc (chỉ bảng nhien_lieu): {mã chiều: giá trị | [giá trị, …]}; null trong mảng = lọc ô trống.

Mảng mã chỉ tiêu. Bỏ trống = mặc định của bảng.

Trang (bảng nhien_lieu), bắt đầu từ 1.

Số dòng một trang (bảng nhien_lieu): mặc định 1000, tối đa 5000.

Sắp xếp "mã asc|desc, …" (bảng nhien_lieu) — mã phải có trong group_by hoặc metrics.

data của query_vehicles bảng doi_xe (đội xe hiện có, không kỳ).

query_vehicles — thay T4 query_trips (hệ thống không có bảng chuyến xe, AN-2). Hai bảng: nhien_lieu chạy trên engine (, analytics.FuelFact + join DimVehicle) theo kỳ ngày đổ; doi_xe đọc thẳng analytics.DimVehicle (đội xe HIỆN CÓ, không kỳ) như get_price_tables đọc bảng giá.

Tách hai bảng vì hai nguồn khác hạt (plan §7 GĐ D): đếm xe trên fact chỉ ra xe CÓ ĐỔ DẦU trong kỳ (dev: ~15/26 xe mỗi tháng), còn đội xe đăng ký phải gồm cả xe đứng. Tiền nhiên liệu trả nguyên số trên phiếu (ĐÃ GỒM THUẾ — không bóc được VAT, AN-22). Không có chiều lái xe: nối mã xe với mã lái xe là để lộ vết một người (AN-20).

Cảnh báo theo bộ đếm chẩn đoán của đúng tập phiếu đã lọc.

Yêu cầu của policy gác một endpoint MCP ( cho /mcp, cho /analytics).

Mặt MCP mà endpoint này phục vụ — quyết định audience token OAuth phải mang.

Endpoint MCP chỉ mở cho user đã xác thực, còn sống và không bị khoá (Identity LockoutEnd — cơ chế vô hiệu tài khoản của LADA; JWT login/refresh và PAT đều kiểm, đường OAuth phải kiểm ở đây vì OpenIddict tự cấp lại token từ principal đã lưu), không phải Founder (plan §1.3, §7.4d), có ít nhất một role MCP (), và — với token OAuth — token được cấp cho đúng resource của endpoint này. Từng tool còn kiểm role/scope riêng ().

Gọi context.Fail chứ không chỉ "không Succeed": ServerRoleAuthorizationHandler chạy cho mọi policy và Succeed MỌI requirement khi user là Founder — chỉ Fail tường minh mới thắng được bypass đó. Kiểm audience (đợt MCP số liệu): OpenIddict validation nhận token của CẢ HAI resource (AddAudiences cả hai), nên nếu không kiểm ở đây thì token xin cho /mcp dùng được ở /analytics và ngược lại. Scope đã chặn tool của mặt kia, nhưng hàng rào này làm việc tách hai connector không phụ thuộc vào việc scope luôn được cấp đúng. PAT không có audience — PAT gác bằng scope ở từng tool. Endpoint chỉ đòi "có role MCP nào đó", KHÔNG đòi đúng tiền tố của mặt này: token của người chỉ có ContentStore.Draft gọi /analytics vẫn tới được tool và nhận FORBIDDEN nêu thiếu Analytics.Read — một câu trợ lý đọc được, thay vì HTTP 403 trần. BẮT BUỘC: hàng rào audience phải fail-closed — một cách dựng DI thiếu registry là lỗi khởi tạo, không phải một handler âm thầm bỏ qua bước tách token /mcp khỏi /analytics.

Application manager của OpenIddict với một khác biệt: redirect URI loopback so khớp bỏ qua cổng (RFC 8252 §7.3). Claude Code khai http://localhost/callback / http://127.0.0.1/callback không cổng rồi mở cổng tạm (ví dụ :3118) mỗi lần đăng nhập; OpenIddict mặc định so chính xác chuỗi nên sẽ trả invalid_redirect_uri. Redirect URI không phải loopback (claude.ai, chatgpt.com) vẫn so chính xác.

Luật thuần so khớp redirect URI loopback — test được không cần OpenIddict.

Cùng scheme, cùng host (không phân biệt hoa thường), cùng đường dẫn và query; cổng bỏ qua.

Allowlist redirect URI cho đăng ký client động — luật thuần, đọc từ AppConfig ContentStore.McpRedirectAllowlist (cách nhau bằng dấu chấm phẩy; hậu tố * là ký tự đại diện đường dẫn). Host loopback khớp mọi cổng (RFC 8252 §7.3); host khác phải trùng cổng. Chỉ nhận https, trừ http loopback.

Kết quả đăng ký: 201 kèm metadata client, hoặc mã lỗi RFC 7591.

Kiểm metadata đăng ký — luật thuần để test không cần OpenIddict.

Null khi hợp lệ; ngược lại là lỗi để trả 400.

Tên client hiển thị trên trang đồng ý — cắt ngắn, bỏ ký tự điều khiển; rỗng → "Client MCP".

Đăng ký client động (RFC 7591) vì OpenIddict 7.6.1 chưa có (issue #2404): tạo public client PKCE trong OpenIddictApplications với quyền tối thiểu (authorize, token, revocation, code + refresh, scope của các mặt MCP). Claude tạo client mới mỗi lần kết nối — bảng sẽ phình dần, dọn định kỳ là việc sổ nợ.

Một client được cấp scope và rsrc: của CẢ HAI mặt (/mcp, /analytics): DCR diễn ra trước khi biết người dùng là ai, và client của Claude không cho biết nó định nối mặt nào. Ranh giới thật nằm ở bước đồng ý (ConnectController chỉ cấp scope thuộc resource đã xin, và đòi role của mặt đó) và ở audience của token (McpAccessHandler) — quyền theo client ở đây chỉ là trần.

Kết quả bước đồng ý OAuth: resource + scope sẽ cấp, hoặc lý do từ chối.

Resource ghi vào token (audience).

Scope sẽ cấp — giao của scope xin với scope thuộc các resource đã xin (+ offline_access nếu xin).

Scope client xin nhưng không thuộc resource đã xin — bị bỏ, không cấp.

Lý do từ chối (tiếng Việt, hiện cho người dùng); null khi được cấp.

Tên các mặt MCP đang xin, để trang đồng ý nói đúng "kết nối cái gì".

Luật cấp quyền ở trang đồng ý OAuth khi một issuer phục vụ HAI mặt MCP (/mcp và /analytics) — luật thuần để test không cần OpenIddict.

Founder bị từ chối (plan Content Store §7.4d). Không gửi resource → coi là /mcp (hành vi trước khi có mặt thứ hai; client MCP hiện hành đều gửi resource theo RFC 8707). User phải có role của MỌI mặt đã xin (ContentStore.* cho /mcp, Analytics.* cho /analytics). Scope không lọt chéo: chỉ cấp scope thuộc các resource đã xin; scope của mặt kia bị bỏ im lặng (OAuth cho phép cấp ít hơn xin — phản hồi token ghi scope thật). Không còn scope nào của mặt đã xin → từ chối.

Chặn cấp lại token ở /connect/token (grant refresh_token / authorization_code) khi user trong principal đã xoá mềm, đang bị khoá (LockoutEnd — cơ chế vô hiệu tài khoản của LADA), là Founder hoặc không còn role của mặt MCP mà token phục vụ (ContentStore.* cho /mcp, Analytics.* cho /analytics). OpenIddict mặc định tự cấp lại từ principal đã lưu, không hỏi DB — không có handler này thì connector của nhân viên đã nghỉ vẫn sống tới hết hạn refresh token (finding security review GĐ C). chặn ở từng lời gọi /mcp; handler này cắt sớm hơn một bước, ngay lúc xin token.

Null nếu user còn dùng được MCP của các resource trong token. Token của resource nào thì user phải còn role của mặt đó (token /analytics đòi Analytics.*, token /mcp đòi ContentStore.*); token cũ không ghi resource được coi là của /mcp — trước đợt MCP số liệu chỉ có một resource.

Scheme : xác thực Authorization: Bearer lada_cs_… bằng . Principal mang cùng tên claim với token OpenIddict (sub, name) cộng claim chuẩn .NET để guard và service dùng chung một cách đọc. Không có token PAT → NoResult (policy scheme chỉ chuyển tới đây khi thấy tiền tố).

Lớp nền của 13 tool MCP kho nội dung AI — và, qua lớp con mỏng AnalyticsMcpTool<TInput>, của tool MCP số liệu (tên lớp giữ nguyên trong đợt đó để không chạm 13 tool đang chạy; đổi tên trung lập là AN-11). Mỗi tool là một class con nhỏ: tên snake_case, mô tả tiếng Việt (+ một dòng tiếng Anh, ví dụ), role bắt buộc (đúng role action REST tương ứng), scope, và phần thân chỉ gọi service GĐ A/B — MCP không có luật riêng, nó là lớp vận chuyển thứ hai bên cạnh REST.

Tự cài thay vì [McpServerTool] reflection của SDK để: (1) schema tham số sinh từ DTO với tên snake_case và mô tả tiếng Việt (); (2) tham số đọc bằng Newtonsoft như REST; (3) mọi kết quả — kể cả từ chối quyền, tham số sai, lỗi hệ thống — đều là một vỏ với isError, không bao giờ là JSON-RPC error làm trợ lý mất ngữ cảnh. Instance là singleton không trạng thái; service lấy từ request.Services (scope của HTTP request vì transport chạy Stateless).

Không dùng attribute reflection của SDK — không có metadata kèm theo.

Toàn bộ vòng đời một lời gọi, tách khỏi để test gọi thẳng: guard quyền → đọc tham số → chạy thân tool → vỏ kết quả + log.

Thân tool: gọi service, trả vỏ kết quả. Lỗi nghiệp vụ nằm trong vỏ, không ném exception.

Mã lỗi khi tham số sai kiểu/sai enum. Kho nội dung: VALIDATION_ERROR (bảng mã của hợp đồng 0.3); mặt số liệu đổi thành INVALID_PARAM cho khớp bảng mã lỗi của hợp đồng của nó.

Gọi ở MỌI đường ra của một lời gọi — kể cả bị guard từ chối ( = null) và tham số sai — ngay trước khi trả kết quả. Mặc định không làm gì; tool số liệu dùng để ghi AnalyticsCallLog cho mọi lời gọi (plan MCP số liệu §3.10). Ngoại lệ ném ra ở đây bị nuốt + log, không đổi kết quả.

Cổng quyền thứ hai, chạy sau khi đọc tham số: dành cho tool mà quyền phụ thuộc giá trị tham số chứ không chỉ tên tool. Trả null là cho qua; trả một câu tiếng Việt là từ chối kèm FORBIDDEN. Mặc định không chặn gì.

Có vì set_article_status: chuyển sang needs_data là việc trợ lý vừa viết bài làm được (nó biết rõ nhất bài thiếu số gì), còn hold / rejected / needs_rewrite là phán xét của người duyệt. Một role cho cả tool thì hoặc chặn hết, hoặc mở hết — không diễn đạt được ranh giới đó. Chạy ở base chứ không ở thân tool để lời từ chối luôn cùng một hình dạng (FORBIDDEN + có log), và để không tool nào lỡ trả lời "thành công" trước khi kiểm quyền.

Tool không tham số (list_service_pages).

Một lời gọi tool vừa xong — đưa cho OnCompletedAsync.

Principal của request (có thể chưa xác thực).

Người gọi đã qua guard; null khi guard từ chối.

Tham số JSON-RPC nguyên gốc.

Hằng số dùng chung của lớp MCP + OAuth — một nơi để không lệch chuỗi. Có hai mặt MCP trên cùng API (): kho nội dung AI (GĐ C đợt Content Store) và số liệu vận hành (đợt MCP số liệu); thứ khác nhau giữa hai mặt gom ở .

Tên server báo cho client MCP (initialize.serverInfo.name).

Tên server của mặt số liệu (initialize.serverInfo.name trên /analytics).

Policy scheme chọn PAT hay OpenIddict theo tiền tố token; challenge chuyển sang handler MCP (401 + resource_metadata).

Policy scheme của /analytics — như nhưng challenge trỏ PRM của /analytics.

Scheme AddMcp thứ hai: phục vụ PRM /.well-known/oauth-protected-resource/analytics và challenge của /analytics.

Authorization policy gác /analytics (như , thêm kiểm audience của token OAuth).

Scheme xác thực PAT lada_cs_….

Cookie phiên đăng nhập ngắn hạn cho trang đăng nhập/đồng ý OAuth (/connect/*).

Authorization policy gác endpoint /mcp: đã xác thực, không Founder, có ≥ 1 role MCP, token OAuth cấp cho đúng resource /mcp.

Rate limit theo IP cho /mcp (trước xác thực) — chặn dội, còn 60/phút/user làm ở middleware sau xác thực.

Scope duy nhất của MCP số liệu — chỉ đọc (không có analytics:write).

Mọi scope MCP (OAuth + PAT), không gồm offline_access.

Scope → tiền tố role của mặt MCP sở hữu scope đó — MỘT nguồn cho OAuth ( suy danh sách scope của từng mặt từ đây) và PAT (ContentAccessTokenService). Thêm scope/mặt mới thì thêm ở đây.

Tiền tố role của mặt mà scope thuộc về — token xin scope của mặt nào thì user phải có role của mặt đó.

Scope không thuộc mặt MCP nào (người gọi phải lọc bằng trước).

Scope của một mặt MCP, theo thứ tự .

Claim scope của principal PAT (mỗi scope một claim). Principal OpenIddict dùng claim riêng của nó (oi_scp).

Claim nhận diện client: "pat:<id>" hoặc client_id OpenIddict. Tên riêng (tiền tố lada_) để không đụng claim OpenIddict tự quản.

Tiền tố role mở cửa lớp MCP (AN-9): user phải có ≥ 1 role mang một trong các tiền tố này mới qua được endpoint, trang đăng nhập OAuth và bước cấp token. Role cụ thể của từng tool vẫn kiểm riêng ở .

Role thuộc lớp MCP (mang một trong ).

Danh sách tiền tố viết cho người đọc: "ContentStore.* hoặc Analytics.*".

Giới hạn payload một lời gọi MCP — đặc tả §9 (512 KB), cùng số với REST.

Khoá AppConfig đọc lúc chạy (cache 1 giờ trong AppConfigService).

Mã lỗi riêng của lớp MCP, ngoài bảng ContentStoreErrorCodes (không phải lỗi nghiệp vụ).

Mặt MCP đang tắt bằng công tắc riêng (Analytics:Enabled = false).

Lời gọi bị huỷ giữa chừng — CHỈ ghi vào nhật ký lời gọi, trợ lý không nhận vỏ kết quả nào.

Whitelist IP cho endpoint MCP — luật thuần, không DB, test được: nhận danh sách "IP hoặc CIDR" (cách nhau bằng dấu phẩy / chấm phẩy / xuống dòng) từ AppConfig ContentStore.McpAllowedIps. IPv4 ánh xạ trong IPv6 (::ffff:1.2.3.4) được đưa về IPv4 trước khi so.

Số luật hợp lệ đã nạp.

Mục trong cấu hình không đọc được — log để người vận hành sửa, không âm thầm bỏ.

JSON của lớp MCP: snake_case theo đặc tả §5 (topic_code, body_markdown…), enum là chuỗi (pending_review, gpt_image_2), trong khi REST vẫn PascalCase — đúng như ContentStoreJson đã dự tính ("GĐ C tự chuyển sang snake_case ở lớp tool").

Hai bộ serializer, một luật đặt tên (): Newtonsoft đọc/ghi dữ liệu thật — DTO GĐ A/B viết cho Newtonsoft ([JsonExtensionData] kiểu JToken, enum nhận cả số lẫn tên) nên không đổi serializer để khỏi lệch hành vi với REST. System.Text.Json chỉ để sinh JSON Schema tham số tool (): .NET 9 có sẵn JsonSchemaExporter, kèm mô tả tiếng Việt lấy từ XML doc của DTO để trợ lý đọc đúng nghĩa từng trường. Khoá từ điển (self_score.sections.A_facts, placeholder_counts.RealNumber) là DỮ LIỆU, không đổi.

PascalCase → snake_case. Khác Newtonsoft/STJ mặc định ở một điểm: số đứng sau chữ thường được tách (GptImage2 → gpt_image_2 như Phụ lục A đặc tả), còn số sau chữ hoa thì dính (CategoryL2 → category_l2, H2Key → h2_key, BlogB2b → blog_b2b).

Đường dẫn trường trong ContentStoreIssue.Field (Images[3].PromptEn, SelfScore.Sections.A_facts) → dạng trợ lý nhìn thấy (images[3].prompt_en). Đoạn có dấu gạch dưới sẵn (khoá dữ liệu) giữ nguyên.

Đọc chuỗi enum "mềm": bỏ mọi ký tự không phải chữ/số rồi so không phân biệt hoa thường — nhận cả pending_review, PendingReview, gpt_image_2, gptImage2.

Enum ↔ chuỗi snake_case; đọc mềm (xem ), nhận cả số.

Cấu hình Newtonsoft dùng cho MỌI tham số vào và kết quả ra của tool MCP.

Tham số JSON-RPC (arguments) → DTO. Khoá không có trong DTO được trả về để tool cảnh báo (thường là trợ lý viết camelCase/PascalCase thay vì snake_case) chứ không âm thầm bỏ.

JSON sai kiểu / enum sai giá trị — kèm đường dẫn trường.

Tên JSON (snake_case) của các thuộc tính DTO — để nhận ra khoá lạ.

Thuộc tính [Newtonsoft.JsonExtensionData] kiểu IDictionary<string, JToken> (Brief.Extra) không có nghĩa trong schema và STJ không biết JToken — bỏ khỏi metadata trước khi sinh schema.

JSON Schema (draft 2020-12) cho tham số một tool, sinh từ chính DTO GĐ A/B: tên snake_case, enum liệt kê giá trị kèm nghĩa tiếng Việt, required cho trường không nullable kiểu chuỗi/số/bool, description lấy từ <summary> của DTO (file Ladaer.BackEnd.xml).

Bắt buộc = không nullable VÀ không có giá trị mặc định trong DTO: chuỗi khởi tạo rỗng (= string.Empty) hay số/enum còn ở default là "chưa có giá trị" → bắt buộc; int Limit = 20, string Format = "html" là tuỳ chọn; bool không bao giờ bắt buộc (vắng = false). List/object không nullable đều có = new() → tuỳ chọn.

Tham số tool sai kiểu / sai enum — có đường dẫn trường để trợ lý sửa đúng chỗ.

Đọc <summary> từ file XML doc của assembly (Ladaer.BackEnd.xml, sinh vì GenerateDocumentationFile=True) để đưa vào description của schema tool. Không có file thì schema vẫn đúng, chỉ thiếu mô tả.

Đăng ký toàn bộ lớp MCP + OAuth 2.1 — một nơi để đọc được cả bức tranh. Hai mặt MCP trên cùng API, cùng issuer OAuth, cùng trang đăng nhập/đồng ý, cùng DCR và PAT (): /mcp — kho nội dung AI (GĐ C đợt Content Store, plan §3.4): 13 tool, role ContentStore.*, scope content:*. /analytics — số liệu vận hành (đợt MCP số liệu, docs/plan-mcp-tra-cuu-so-lieu.md §3.1): tool số liệu, role Analytics.Read, scope analytics:read, PRM và chỉ dẫn riêng. Gồm: OpenIddict (server + validation + EF store trên LadaDbContext), scheme PAT, hai policy scheme chọn scheme theo tiền tố token, hai handler challenge MCP (401 + resource_metadata, mỗi cái phục vụ PRM của một mặt), hai policy, một server MCP Streamable HTTP stateless mà ConfigureSessionOptions đổi bộ tool + chỉ dẫn theo endpoint, và ba điểm mắc vào pipeline.

Luật mà trợ lý AI đọc nằm ở (kho nội dung) và (số liệu) — đổi hành vi thì sửa ở đó trong cùng commit, đừng để chỉ dẫn nói một đằng code làm một nẻo.

HttpServerTransportOptions.ConfigureSessionOptions: chọn bộ tool + chỉ dẫn theo mặt của endpoint đã route (). Ở chế độ Stateless SDK 2.2.0 gọi hàm này MỖI request trên một McpServerOptions mới dựng từ IOptionsFactory — kết luận spike GĐ A, xem plan §4.

Thiếu metadata là lỗi cấu hình → ném (fail-closed), không đoán mặt theo chuỗi path. Mặt kho nội dung giữ nguyên options factory dựng (13 tool + chỉ dẫn 0.3) — hành vi /mcp không đổi.

Dịch vụ của miền số liệu (docs/plan-mcp-tra-cuu-so-lieu.md GĐ A).

Khoá ký (RSA PEM, bắt buộc bất đối xứng) và khoá mã hoá (đối xứng base64). Thiếu: Production → dừng khởi động (token OAuth mà mất hiệu lực mỗi lần deploy là lỗi vận hành, không được im lặng); môi trường khác → khoá tạm + cảnh báo để máy dev không vỡ vì thiếu cấu hình.

Trước UseAuthentication: request-id, giới hạn thân, công tắc McpEnabled (503), whitelist IP (403) — chỉ path của hai mặt MCP (cùng công tắc tổng và whitelist: cả hai chỉ mở cho dải IP của Anthropic).

Sau UseAuthorization: N lời gọi / phút / user → 429 — chỉ path của hai mặt MCP (chung một hạn mức mỗi user).

Map endpoint của hai mặt MCP: mỗi mặt gắn (để chọn bộ tool), policy của nó (qua policy scheme của nó) và rate limit theo IP (600/phút). Rate limiter chạy sau UseAuthentication từ 2026-10-16 (để giới hạn toàn cục tính theo user), nên policy IP này cũng đứng sau xác thực; hàng rào trước xác thực của MCP là whitelist IP ở .

Không trả builder: convention nào gắn thêm vào một builder duy nhất sẽ chỉ áp lên một mặt — hàng rào nào cần cho endpoint MCP thì thêm TRONG vòng lặp này để cả hai mặt cùng nhận.

Hợp đồng giữa server và trợ lý AI — chỉ dẫn server (initialize.instructions) và những câu luật mà mô tả tool dùng chung. Đây là nguồn sự thật duy nhất: trợ lý đọc nó tự động mỗi phiên, không cần ai nhắc, kể cả lượt chạy tự động lúc 6 giờ sáng.

Luật giữ hợp đồng khỏi lệch pha (phản hồi của trợ lý AI 2026-09-13): đổi hành vi thì sửa mô tả trong cùng commit, và nâng + . Trợ lý so số hiệu này với đặc tả nó đang cầm để biết bên nào cũ. Tài liệu nào ghi khác mô tả tool thì mô tả tool đúng. Lịch sử đã cắn phải: cơ chế ô chờ [[CẦN …]] bị bỏ 2026-09-12 trong code nhưng chỉ dẫn server vẫn ghi "giữ nguyên ô [[CẦN …]] cho số liệu chưa có", nên trợ lý vừa được bảo để ô lại vừa bị cảnh báo LEGACY_PLACEHOLDER vì đã để ô — server tự mâu thuẫn với chính nó suốt một ngày. Ca test McpContractTests canh: không mô tả tool nào còn dạy để ô chờ, và chỉ dẫn server luôn mang số hiệu hợp đồng.

Số hiệu hợp đồng. Nâng khi hành vi hoặc luật viết bài đổi, không nâng khi chỉ sửa câu chữ.

Ngày hành vi của bản hợp đồng này bắt đầu có hiệu lực. 0.3 = mở hàng đợi viết lại: người duyệt đánh dấu needs_rewrite được (kèm lý do bắt buộc) và có tool list_articles để trợ lý lấy hàng đợi đó.

Chuỗi trợ lý so với đặc tả nó đang cầm: contract: 0.3 — 2026-09-13.

Ngày bỏ cơ chế ô chờ [[CẦN …]] — luật số liệu vẫn nhắc lại ngày này, không phải ngày hợp đồng.

Luật số liệu — câu thay thế cơ chế ô chờ. Dùng chung cho mô tả create_article_draft và update_article để hai chỗ không bao giờ nói hai điều khác nhau.

Cảnh báo khi bài còn chuỗi [[CẦN …]] — nói cách làm đúng, không chỉ nói cách cũ đã bỏ. Tầng service phát cảnh báo này (ContentArticleService, ContentPublishService) nên giữ cùng một lời để trợ lý đọc đâu cũng thấy một luật.

Chỉ dẫn server trả trong initialize — thứ trợ lý đọc trước khi gọi tool đầu tiên.

Hai "mặt" MCP trên cùng API: kho nội dung (/mcp) và số liệu vận hành (/analytics).

Metadata gắn lên endpoint MapMcp để ConfigureSessionOptions biết request thuộc mặt nào — đọc metadata của endpoint đã route chắc hơn so khớp chuỗi path (không lo PathBase, dấu / cuối, hoa thường).

Mọi thứ khác nhau giữa hai mặt MCP, gom một chỗ: đường dẫn, resource OAuth (= URL người dùng nhập vào connector), PRM, tiền tố role, scope, scheme challenge và policy. Mọi so khớp path / resource / tiền tố role của lớp MCP đi qua đây — không rải chuỗi "/analytics" hay "ContentStore." khắp nơi.

Đường dẫn endpoint trên API: "/mcp", "/analytics".

Resource OAuth — ĐÚNG URL người dùng nhập vào connector (không dấu / cuối).

URL tài liệu PRM (RFC 9728) của mặt này — <issuer>/.well-known/oauth-protected-resource<path>.

Tiền tố role mở cửa mặt này: "ContentStore.", "Analytics.".

Scope OAuth thuộc mặt này (không gồm offline_access).

Tên hiển thị trên PRM và trang đồng ý.

Scheme AddMcp — phục vụ PRM và ghi WWW-Authenticate: Bearer resource_metadata=… khi 401.

Policy scheme chọn PAT/OpenIddict theo tiền tố token, chuyển challenge/forbid sang .

Authorization policy gác endpoint.

Hai mặt MCP dựng từ appsettings — singleton.

Request thuộc path của một mặt MCP nào đó.

Mặt có resource đúng nguyên văn (so không phân biệt dấu / cuối); null khi không khớp.

Scope OAuth của mọi mặt (không gồm offline_access).

Người gọi tool sau khi qua guard — dựng cho service GĐ A/B.

"mcp:<client_id>" (OAuth) hoặc "pat:<id>" — vào cột ContentAuditLog.Client (≤ 100 ký tự).

Guard từ chối — mã lỗi là , thông điệp tiếng Việt trả thẳng cho trợ lý.

Kiểm quyền cho MỖI lời gọi tool: đã xác thực → không phải Founder (plan §7.4d) → có ≥ 1 role MCP () → có role của tool (đúng role mà action REST tương ứng đòi) → token có scope của tool (content:read / content:write / analytics:read). Role đọc từ DB qua (cache 15 phút), không từ claim — như REST.

Đọc claim từ principal của cả hai scheme (OpenIddict dùng tên claim JWT: sub, name, oi_scp; PAT thêm claim chuẩn .NET).

Hợp của claim "scope" (PAT, một claim mỗi scope hoặc cách nhau bằng dấu cách) và scope OpenIddict (oi_scp).

"pat:<id>" hoặc "mcp:<client_id>" — client_id đặt lúc đồng ý, dự phòng lấy presenter của OpenIddict.

Audience của token OAuth = resource đã cấp lúc đồng ý (OpenIddict ghi claim riêng oi_aud khi đọc token, cộng claim chuẩn aud phòng khi token đọc theo đường khác). PAT không có audience.

Vỏ kết quả của mọi tool — chính là ở dạng snake_case, để trợ lý đọc một cấu trúc cho cả 13 tool: success, data, error_code, message, errors[] (kèm field/position), warnings[], extra, request_id.

Mã yêu cầu — cùng chuỗi ghi vào ContentAuditLog.RequestId và log server, để tra vết.

Số dòng dữ liệu tool trả — CHỈ để ghi nhật ký lời gọi (AnalyticsCallLog), không gửi cho trợ lý.

Kết quả service → vỏ MCP. Tên trường trong Errors và khoá Extra đổi sang snake_case; mã lỗi giữ nguyên (hợp đồng §5.4).

Một vi phạm — bản snake_case của .

Đường dẫn trường theo tên tham số tool: images[3].prompt_en, self_score.sections.A_facts.

Cổng TRƯỚC xác thực cho /mcp, theo thứ tự rẻ → đắt: gắn request-id → giới hạn thân request 512 KB → công tắc ContentStore.McpEnabled (tắt → 503, REST/OAuth vẫn sống) → whitelist IP (ContentStore.McpIpWhitelistEnabled + ContentStore.McpAllowedIps, sai IP → 403). Chỉ mắc vào path MCP (xem McpRegister.UseContentStoreMcpGate).

Giới hạn N lời gọi / phút / user cho /mcp (N = AppConfig ContentStore.McpRateLimitPerMinute, mặc định 60). Luật thuần trên ; một limiter cho mỗi ngưỡng để đổi ngưỡng lúc chạy không cần khởi động lại. Singleton.

Chạy SAU UseAuthorization (đã có user) cho path MCP: lời gọi thứ N+1 trong một phút của cùng user → 429 kèm Retry-After. Rate limit theo IP (chống dội, 600/phút) làm ở policy ; whitelist IP trước xác thực nằm ở .

create_article_draft — tool chính, đặc tả §5.2.

update_article — đặc tả §5.2.

get_article — đặc tả §5.2.

list_articles — đặc tả §5.2. Bọc IContentArticleService.Search (đường REST của màn danh sách cũng đi qua đúng hàm này) và cắt bớt cột: danh sách là để chọn bài, đọc bài là việc của get_article.

Sinh ra cho hàng đợi viết lại (quyết định 2026-09-13): trước đó trợ lý không có tool nào liệt kê bài, nên muốn viết lại 55 bài cũ phải dán tay danh sách mã bài mỗi phiên — không xong trong một lượt, phiên sau không biết bài nào đã làm, nên vừa sót vừa trùng.

Trần số dòng một lời gọi — danh sách dài hơn thì phân trang bằng page.

set_article_status — đặc tả §5.2 (trừ approved: GĐ E).

Quyền phụ thuộc đích (phản hồi của trợ lý AI 2026-09-13). Hợp đồng bảo trợ lý "cả bài phụ thuộc số chưa có thì set_article_status needs_data", nhưng tool đòi ContentStore.Edit mà tài khoản trợ lý chỉ có Search/GetById/Draft — chỉ dẫn dạy một việc mà server từ chối làm, suốt từ 0.2. Chữa bằng cách mở đúng một đích: ContentStore.Draft chuyển được sang needs_data — nó vừa viết bài, nó biết rõ nhất bài thiếu số gì. Mọi đích còn lại vẫn đòi Edit, vì hold / rejected / needs_rewrite là phán xét của người duyệt (ranh giới "trợ lý nhận hàng đợi, không tạo hàng đợi"). Cấp thẳng Edit cho tài khoản trợ lý thì mở hết cả ba đích kia — không làm.

Đích duy nhất mà role ContentStore.Draft tự chuyển được.

Không có ContentStore.Edit thì chỉ đi được tới . Thiếu status thì cho qua để service trả VALIDATION_ERROR — "quên tham số" không phải chuyện thiếu quyền.

render_article — đặc tả §5.2.

check_slug — đặc tả §5.3.

list_service_pages — đặc tả §5.3.

list_people — đặc tả §5.3.

Danh sách 13 tool đăng ký vào server — thứ tự hiện trong tools/list. Mô tả từng tool là hợp đồng với trợ lý AI (): đổi hành vi thì sửa mô tả trong cùng commit.

Tham số create_topics — danh sách đề bài (đặc tả §5.1).

Các đề bài cần thêm vào hàng đợi; mã trùng bị từ chối từng dòng, tiêu đề trùng ≥ 85% chỉ cảnh báo.

Tham số get_article — chọn bài bằng MỘT trong ba khoá, và chọn phần muốn nhận để tiết kiệm ngữ cảnh.

Id bài (ưu tiên nếu gửi kèm mã đề/slug).

Mã đề bài dạng W2-01.

Slug bài (không dấu, gạch nối).

Kèm thân bài Markdown (có thể tới 200 KB). Mặc định true.

Kèm bộ ảnh. Mặc định true.

Kèm phiếu tự chấm. Mặc định true.

Tham số list_articles — bộ lọc của IContentArticleService.Search viết phẳng ra, mọi trường đều tuỳ chọn. Không có khoá nào thì trả trang đầu của toàn kho, mới sửa lên trước.

Lọc theo trạng thái bài; needs_rewrite chính là hàng đợi viết lại.

Mã nhánh L2, ví dụ "A2".

Lọc theo loại trang.

Tuần của đề bài.

Tìm chứa chuỗi trong tiêu đề, slug hoặc mã đề.

Lọc theo người/máy đã nháp, ví dụ "claude-routine" (khớp đúng cả chuỗi).

Số dòng một trang. Mặc định 20, tối đa 50.

Trang thứ mấy, đếm từ 1. Mặc định 1.

Một dòng kết quả list_articles — rút gọn có chủ đích: đủ để chọn bài và biết phải sửa gì, không có thân bài. Cần cả bài thì gọi get_article cho đúng bài đã chọn.

Câu người duyệt ghi khi đánh dấu — với needs_rewrite đây là yêu cầu sửa.

Số phiên bản hiện tại — dùng làm expected_version khi gọi update_article.

Tham số check_slug.

Slug muốn dùng, dạng van-chuyen-tu-dong-di-tinh.

Tham số render_article.

Id bài.

"html" (mặc định) hoặc "markdown".

list_topics — đặc tả §5.1.

create_topics — đặc tả §5.1.

update_topic_status — đặc tả §5.1.

append_run_log — đặc tả §5.1.

Middleware kiểm tra request có đến từ frontend hợp lệ không. Yêu cầu header X-LADA-Client với giá trị khớp cấu hình trong appsettings.

Danh sách đường dẫn được bỏ qua kiểm tra (không phân biệt hoa thường)

Kiểm tra xem đường dẫn có nằm trong danh sách bỏ qua không

Extension method để đăng ký middleware

Một luật duy nhất để cả API biết IP thật của client: whitelist IP của MCP, rate limit theo IP, và nhật ký đăng ký client DCR đều đọc ở đây.

Luật: chỉ tin X-Forwarded-For khi kết nối đến từ proxy nội bộ (loopback / dải private), và khi đó lấy phần tử cuối cùng — là hop do chính proxy tin cậy nối vào (nginx $proxy_add_x_forwarded_for, IIS ARR, ngrok đều NỐI THÊM chứ không ghi đè), còn các phần tử trước là do client tự khai nên giả được. Kết nối thẳng từ ngoài thì dùng RemoteIpAddress. Header có mà không đọc được thì trả null — không đoán, để bên gọi đóng an toàn. Vì sao gộp về đây (sổ nợ CS-23, đóng 2026-09-07): trước đó tồn tại hai luật lệch nhau. McpIpAllowlist lấy phần tử cuối (đúng), còn RateLimitingRegister.GetClientIpAddress lấy phần tử đầu — nghĩa là sau khi dựng reverse proxy, bất kỳ ai cũng tự khai X-Forwarded-For: <IP bịa> để đổi phân vùng rate limit và bơm request không giới hạn. Bản cũ còn gọi MapToIPv4() cho mọi IPv6, nên một IPv6 công cộng có 4 byte cuối rơi vào dải riêng (ví dụ 2001:db8::a00:1 → 10.0.0.1) bị coi là proxy nội bộ và được tin header. Có hai proxy tin cậy nối tiếp thì phần tử cuối là IP proxy trong → whitelist từ chối (đóng an toàn); khi đó đăng ký ForwardedHeadersMiddleware với KnownProxies/KnownNetworks thay vì nới luật này. Xem docs/checklist-production-content-store.md §5.

IP thật của client, hoặc null khi không xác định được.

Chuỗi phân vùng cho rate limit: IP đã giải, hoặc "unknown".

Gộp mọi trường hợp không giải được vào một phân vùng là cố ý: kẻ gửi X-Forwarded-For rác không tự tách mình ra khỏi hạn mức của người khác được, mà lại nằm chung với nhau nên bị chặn sớm hơn.

IP thuộc dải nội bộ? IPv4: 10/8, 172.16/12, 192.168/16. IPv6 thật: link-local, site-local, unique-local — không ép MapToIPv4(), vì 4 byte cuối của một IPv6 công cộng không nói lên điều gì về việc nó có nội bộ hay không.

Khoá phân vùng cho giới hạn toàn cục: theo user khi request đã xác thực, theo IP khi chưa.

Phải chạy sau UseAuthentication thì HttpContext.User mới có — xem thứ tự middleware ở GeneralRegister.ConfigAndRunApp. Đặt trước xác thực thì mọi request đều rơi về IP và cả văn phòng (một IP NAT) lại chia nhau một hạn mức như bản cũ. Chỉ tin danh tính đã được middleware xác thực kiểm chữ ký; không tự đọc header Authorization để lấy sub, vì khi đó ai cũng bịa được token với sub ngẫu nhiên để tự cấp cho mình một phân vùng mới và né giới hạn theo IP. Tiền tố user: / ip: là cố ý: một user có id trùng dạng chuỗi với một IP không bao giờ chung phân vùng, và nhìn log biết ngay phân vùng thuộc loại nào.

Kết quả giải khoá phân vùng.

Chuỗi phân vùng, ví dụ user:42 hoặc ip:203.0.113.5. true khi phân vùng theo user đã xác thực.

Kết quả giải khoá phân vùng.

Chuỗi phân vùng, ví dụ user:42 hoặc ip:203.0.113.5. true khi phân vùng theo user đã xác thực.

Chuỗi phân vùng, ví dụ user:42 hoặc ip:203.0.113.5.

true khi phân vùng theo user đã xác thực.

Theo user khi HttpContext.User đã xác thực và có claim định danh (sub hoặc NameIdentifier, cùng luật với ); còn lại theo IP qua .

Yêu cầu tạo URL xác thực OAuth cho một kết nối.

Id kết nối — sẽ được nhúng vào tham số state để callback biết thuộc kết nối nào

Chuỗi state đã ký/mã hoá, dùng chống CSRF

Redirect URI đã đăng ký với nền tảng (ghi đè giá trị trong kết nối nếu có)

Kết quả trao đổi code / refresh token với nền tảng.

Thành công hay không

Access token mới

Refresh token mới (nền tảng chỉ trả về ở lần cấp quyền đầu tiên)

Thời điểm access token hết hạn

Thông báo lỗi bằng tiếng Việt khi thất bại

Mã lỗi gốc của nền tảng — giữ nguyên để tra cứu tài liệu

Kết quả kiểm tra kết nối (nút "Kiểm tra kết nối" trên form cấu hình).

Gọi được API nền tảng hay không

Thông báo tiếng Việt cụ thể: thiếu field nào, token sai, hay thiếu quyền

Danh sách key field credential đang thiếu hoặc sai — để UI highlight đúng ô nhập

Số tài khoản quảng cáo truy cập được (nếu nền tảng cho biết)

Mã lỗi gốc của nền tảng

Thời gian gọi (ms)

Tài khoản quảng cáo lấy từ nền tảng.

Id tài khoản bên nền tảng

Tên tài khoản

Mã tiền tệ của tài khoản (không giả định VND)

Múi giờ của tài khoản

Là tài khoản quản lý (MCC / manager)

Là tài khoản test của nền tảng

Trạng thái đã chuẩn hoá

Dữ liệu đặc thù nền tảng chưa map được vào canonical model

Lỗi khi đọc thông tin một tài khoản quảng cáo cụ thể. Tách riêng để một tài khoản lỗi không làm sập cả lần đồng bộ, nhưng lỗi vẫn được đưa lên tới service để ghi vào sync log — nếu chỉ log ra console thì người dùng không có cách nào biết vì sao đồng bộ ra 0 tài khoản.

Id tài khoản bên nền tảng (nếu biết)

Thông báo lỗi tiếng Việt

Mã lỗi gốc của nền tảng — giữ nguyên để tra tài liệu

Thao tác đã gọi khi gặp lỗi, dùng làm nhãn Endpoint trong sync log

Bối cảnh lần gọi (id tài khoản, login-customer-id, câu truy vấn) dạng JSON. Không chứa thông tin mật — chỉ để trả lời được câu "gọi cái gì với tham số nào".

Kết quả đọc danh sách tài khoản quảng cáo: phần đọc được và phần lỗi.

Các tài khoản đọc được đầy đủ thông tin

Các tài khoản nền tảng có trả về nhưng không đọc được chi tiết

Số tài khoản nền tảng khai là truy cập được (trước khi đọc chi tiết)

Chiến dịch lấy từ nền tảng.

Id chiến dịch bên nền tảng

Id tài khoản quảng cáo bên nền tảng

Tên chiến dịch

Trạng thái đã chuẩn hoá

Mục tiêu đã chuẩn hoá (suy ra từ channel type / objective của nền tảng)

Loại ngân sách

Giá trị ngân sách theo đơn vị tiền tệ của tài khoản (đã chia micros)

Mã tiền tệ

Id ngân sách bên nền tảng

Chiến lược đặt giá của nền tảng

Ngày bắt đầu chạy

Ngày kết thúc

Loại kênh của nền tảng (Google AdvertisingChannelType)

Loại kênh con của nền tảng

Cấu hình đặc thù nền tảng chưa map được — không được làm mất dữ liệu

Payload gốc từ nền tảng

Nhóm quảng cáo lấy từ nền tảng.

Id nhóm bên nền tảng

Id chiến dịch cha bên nền tảng

Tên nhóm

Trạng thái đã chuẩn hoá

Giá thầu CPC tối đa (đã chia micros)

Mã tiền tệ của giá thầu

Loại nhóm của nền tảng

Cấu hình đặc thù nền tảng chưa map được

Payload gốc từ nền tảng

Một khung giờ chạy quảng cáo lấy từ nền tảng (ad schedule criterion). Ánh xạ 1-1 với AdScheduleInfo của Google — thuộc cấp chiến dịch, không phải cấp nhóm.

Id criterion bên nền tảng

Id chiến dịch cha bên nền tảng

Thứ trong tuần

Giờ bắt đầu, 0–23

Phút bắt đầu (Google chỉ dùng 0, 15, 30, 45)

Giờ kết thúc, 0–24 (24 = hết ngày)

Phút kết thúc (Google chỉ dùng 0, 15, 30, 45)

Hệ số điều chỉnh giá thầu theo đúng dạng của Google (1.2 = +20%, 0.5 = -50%). null = nền tảng không set (UI Google hiện "—"); 0.0 = -100%, khác hẳn null. Adapter phải phân biệt hai trường hợp này bằng cờ HasBidModifier của proto, không so sánh giá trị — proto3 trả 0.0 cho field chưa set.

Trạng thái đã chuẩn hoá

Payload gốc từ nền tảng

Một quảng cáo cụ thể trong nhóm, lấy về từ nền tảng (Google: ad_group_ad).

Id quảng cáo bên nền tảng, dạng id trần. Google trả resource name customers/{cid}/adGroupAds/{adGroupId}~{adId}, nhưng DTO này chỉ chứa {adId}. Việc ghép lại thành resource name là việc của adapter — nơi duy nhất biết định dạng của từng nền tảng. Lưu dạng ghép vào canonical entity từng gây hai lỗi: ghép lần hai khi bật/tắt quảng cáo, và số liệu cấp quảng cáo không khớp được.

Id nhóm quảng cáo cha bên nền tảng

Id chiến dịch cha bên nền tảng

Tên hiển thị. Google hầu như luôn để rỗng ad.name với quảng cáo tìm kiếm, nên adapter dựng tên từ tiêu đề đầu tiên của mẫu quảng cáo. Không bao giờ để trống — danh sách toàn dòng không tên thì người dùng không phân biệt được quảng cáo nào.

Loại quảng cáo theo tên enum của nền tảng (ví dụ RESPONSIVE_SEARCH_AD)

Trạng thái đã chuẩn hoá

Trạng thái xét duyệt của nền tảng, giữ nguyên tên gốc (APPROVED / DISAPPROVED / APPROVED_LIMITED…). Không dịch sang enum của LADA: mỗi nền tảng có tập giá trị riêng và người dùng cần tra đúng tên đó trong tài liệu nền tảng.

Trạng thái review của nền tảng (REVIEW_IN_PROGRESS / REVIEWED…)

URL đích đầu tiên, để người dùng đối chiếu nhanh

Payload gốc từ nền tảng

Một từ khoá lấy về từ nền tảng — dùng cho cả từ khoá thường và từ khoá phủ định, phân biệt bằng . Một DTO cho hai loại vì Google dùng chung resource ad_group_criterion / campaign_criterion, chỉ khác cờ negative. Tách hai DTO sẽ nhân đôi mọi tầng bên trên mà không thêm thông tin gì.

Criterion id bên nền tảng, dạng id trần (không phải {adGroupId}~{criterionId}) — cùng quy ước với .

Id chiến dịch cha bên nền tảng — luôn có, kể cả với từ khoá cấp nhóm

Id nhóm cha bên nền tảng. null khi là (từ khoá phủ định cấp chiến dịch không thuộc nhóm nào).

Cấp của từ khoá — chỉ nhận Campaign hoặc Group

Là từ khoá phủ định (loại trừ) hay từ khoá thường (nhắm chọn)

Nội dung từ khoá, không kèm dấu ngoặc biểu thị kiểu khớp

Kiểu khớp đã chuẩn hoá

Giá thầu CPC riêng của từ khoá. null = nền tảng không set (dùng giá thầu của nhóm). Adapter phải kiểm cờ HasCpcBidMicros của proto chứ không so giá trị: proto3 trả 0 cho field chưa set, mà 0 với giá thầu là con số có nghĩa hoàn toàn khác.

Mã tiền tệ của giá thầu

Trạng thái đã chuẩn hoá

Trạng thái xét duyệt, giữ nguyên tên gốc của nền tảng. Từ khoá phủ định không được nền tảng xét duyệt nên field này rỗng — đúng, không phải lỗi.

Điểm chất lượng (Google: 1–10). null khi nền tảng chưa có đủ dữ liệu để chấm, hoặc với từ khoá phủ định (không được chấm điểm).

Payload gốc từ nền tảng

Một dòng số liệu theo ngày lấy từ nền tảng. Chi phí đã được chia micros trong adapter — không bao giờ trả micros ra ngoài.

Cấp của số liệu

Id đối tượng bên nền tảng (campaign / ad group / ad id)

Id tài khoản quảng cáo bên nền tảng

Ngày của số liệu (từ segments.date)

Số lần hiển thị

Số lần nhấp

Chi phí theo đơn vị tiền tệ của tài khoản

Mã tiền tệ

Số chuyển đổi

Giá trị chuyển đổi

Tỷ lệ nhấp (%)

Chi phí trung bình mỗi lần nhấp

Số lượt xem video

Payload gốc của dòng số liệu

Yêu cầu đẩy một chiến dịch từ LADA lên nền tảng.

Id tài khoản quảng cáo bên nền tảng

Tên chiến dịch

Mục tiêu chuẩn hoá

Loại ngân sách

Giá trị ngân sách theo đơn vị tiền tệ của tài khoản

Ngày bắt đầu chạy

Ngày kết thúc

Trạng thái mong muốn khi tạo. Mặc định Paused để tránh bug làm tiêu tiền ngoài ý muốn.

Danh sách nhóm quảng cáo kèm mẫu QC và targeting

Cấu hình đặc thù nền tảng do UI gửi lên (render từ Capabilities)

Một nhóm quảng cáo trong yêu cầu publish.

Tên nhóm

Giá thầu CPC tối đa

Danh sách mẫu quảng cáo trong nhóm

Targeting của nhóm

Cấu hình đặc thù nền tảng

Mẫu quảng cáo trong yêu cầu publish.

Danh sách headline

Danh sách description

URL đích

Đường dẫn hiển thị 1

Đường dẫn hiển thị 2

URL ảnh

URL video

Targeting trong yêu cầu publish.

Danh sách từ khoá

Danh sách mã vị trí của nền tảng

Danh sách mã ngôn ngữ của nền tảng

Độ tuổi tối thiểu

Độ tuổi tối đa

Giới tính nhắm chọn

Cấu hình targeting đặc thù nền tảng

Yêu cầu áp lịch quảng cáo lên nền tảng: một lô thao tác đã được AdsScheduleDiff tính sẵn, gửi trong một request atomic. Cố ý gộp cả xoá/thêm/sửa vào một request thay vì ba lần gọi: đổi được một nửa lịch là trạng thái tệ nhất — người dùng không biết khung nào đã đổi, khung nào chưa, mà giá thầu thì đã thay đổi thật.

Id tài khoản quảng cáo bên nền tảng

Id chiến dịch bên nền tảng — lịch là criterion cấp chiến dịch

Các thao tác cần gửi, đã theo đúng thứ tự an toàn (xoá trước, rồi thêm, rồi sửa) do AdsScheduleDiffResult.AllOperations sắp.

Một dòng đổi giá thầu của nhóm quảng cáo cần gửi lên nền tảng.

Id nhóm bên nền tảng (id trần, không phải resource name)

Giá thầu mới, đơn vị tiền tệ của tài khoản (VND: đồng) — adapter tự đổi ra micros. Không bao giờ truyền micros xuống đây: cả LADA lẫn giao diện đều nói bằng đơn vị tiền.

Tên nhóm — chỉ để dựng câu lỗi cho người đọc, không gửi lên nền tảng

Yêu cầu đổi giá thầu cho một lô nhóm quảng cáo trong cùng một tài khoản, gửi trong một request atomic. Cùng lý do gộp như lịch chạy và từ khoá: đổi được một nửa lô là trạng thái tệ nhất — tiền đã đổi thật trên một phần nhóm mà LADA không biết phần nào.

Id tài khoản quảng cáo bên nền tảng

Các nhóm cần đổi giá thầu

Yêu cầu áp từ khoá lên nền tảng: một lô thao tác đã được AdsKeywordDiff tính sẵn, gửi trong một request atomic. Cố ý gộp cả xoá/thêm/sửa vào một request thay vì ba lần gọi, cùng lý do như lịch chạy: đổi được một nửa là trạng thái tệ nhất. Riêng với từ khoá còn tệ hơn — xoá xong nhưng thêm lỗi thì chiến dịch mất từ khoá phủ định mà vẫn chạy, tiền chảy ra ngay.

Id tài khoản quảng cáo bên nền tảng

Id chiến dịch bên nền tảng — luôn có, kể cả khi áp cho một nhóm

Id nhóm bên nền tảng. null = lô này là từ khoá phủ định cấp chiến dịch (Google: campaign_criterion); có giá trị = từ khoá cấp nhóm (Google: ad_group_criterion). Một lô không được trộn hai cấp: hai cấp là hai loại operation khác nhau của Google, và trộn vào sẽ làm mô tả trên hộp xác nhận nói sai phạm vi ảnh hưởng.

Các thao tác cần gửi, đã theo đúng thứ tự an toàn (xoá trước, rồi thêm, rồi sửa) do AdsKeywordDiffResult.AllOperations sắp.

Yêu cầu cập nhật chiến dịch đã tồn tại trên nền tảng.

Id tài khoản quảng cáo bên nền tảng

Id chiến dịch bên nền tảng

Tên mới (null = không đổi)

Trạng thái mới (null = không đổi)

Ngân sách mới (null = không đổi)

Ngày bắt đầu mới

Ngày kết thúc mới

Cấu hình đặc thù nền tảng

Kết quả một lần ghi dữ liệu ra nền tảng.

Thành công hay không

Thông báo tiếng Việt (kể cả khi lỗi)

Id chiến dịch bên nền tảng sau khi tạo/sửa

Id ngân sách bên nền tảng

Id các đối tượng con đã tạo, dùng để lưu ExternalId về canonical entity. Key là tên/định danh do LADA gửi lên, value là id bên nền tảng.

Id các quảng cáo đã tạo

Id criterion của các khung giờ vừa tạo. Key là AdsScheduleSlot.WindowKey (thứ + giờ bắt đầu + giờ kết thúc), value là criterion id bên nền tảng. Cần khoá theo khung giờ chứ không theo index: nhờ vậy service gắn được ExternalId vào đúng dòng LADA. Gắn lệch một dòng là lần đẩy sau sẽ sửa/xoá sai khung giờ.

Criterion id của các từ khoá vừa tạo. Key là AdsKeywordOperation.IdentityKey (cấp + phủ định + kiểu khớp + nội dung đã chuẩn hoá), value là criterion id bên nền tảng. Khoá theo danh tính chứ không theo index, cùng lý do như : gắn lệch một dòng là lần đẩy sau sẽ sửa/xoá sai từ khoá — với từ khoá phủ định thì đó là xoá mất lá chắn của một truy vấn khác.

Mã lỗi gốc của nền tảng — giữ nguyên để tra cứu tài liệu

Payload gốc trả về từ nền tảng

Tra cứu adapter theo nền tảng. Thêm nền tảng mới chỉ cần đăng ký thêm một vào DI, không phải sửa factory.

Lấy adapter của nền tảng. Ném kèm thông báo tiếng Việt nếu nền tảng chưa được triển khai.

Lấy adapter của nền tảng, trả về null nếu chưa có — dùng khi chỉ cần dò xem có hỗ trợ hay không.

Năng lực của mọi nền tảng đã đăng ký, để UI dựng danh sách chọn nền tảng.

Mô tả năng lực của một nền tảng quảng cáo. UI dùng object này để render form cấu hình kết nối và bật/tắt các chức năng, nhờ vậy thêm nền tảng mới không phải sửa frontend.

Nền tảng

Tên hiển thị của nền tảng

Phiên bản API đang dùng

Nền tảng đã được triển khai hay chỉ là placeholder cho giai đoạn sau

Lấy được danh sách tài khoản quảng cáo

Lấy được danh sách chiến dịch

Lấy được danh sách nhóm quảng cáo

Lấy được số liệu theo ngày

Đọc được lịch chạy quảng cáo (ad schedule) của chiến dịch

Đọc được danh sách quảng cáo cụ thể trong từng nhóm (Google: ad_group_ad). Tách khỏi vì nền tảng có thể cho đọc nhóm mà không cho đọc chi tiết từng quảng cáo — UI ẩn tab "Quảng cáo" theo cờ này.

Đọc được danh sách từ khoá về từ nền tảng (an toàn, chỉ đọc). Tách khỏi : nền tảng có thể nhắm mục tiêu bằng từ khoá khi tạo chiến dịch nhưng chưa có đường đọc lại danh sách đó.

Các cấp lấy số liệu mà nền tảng hỗ trợ

Tạo được chiến dịch mới trên nền tảng

Cập nhật được chiến dịch đã tồn tại

Bật/tạm dừng được chiến dịch

Các mục tiêu chiến dịch nền tảng hỗ trợ tạo từ LADA

Các loại ngân sách nền tảng hỗ trợ

Đổi được ngân sách của chiến dịch đã đẩy lên nền tảng

Sửa được lịch chạy quảng cáo (thêm/xoá khung giờ, đổi % giá thầu theo giờ). Tách riêng khỏi vì đọc lịch an toàn còn ghi lịch đổi giá thầu là tiêu tiền thật — frontend đọc cờ này để ẩn/hiện chức năng sửa thay vì hard-code nền tảng vào UI.

Sửa được từ khoá trên nền tảng (thêm/xoá/đổi giá thầu từ khoá). Tách khỏi vì đọc từ khoá thì an toàn còn ghi từ khoá là đổi cấu hình đang tiêu tiền: thêm từ khoá khớp rộng có thể làm chi phí tăng vọt.

Nền tảng có khái niệm từ khoá phủ định (loại trừ truy vấn) hay không. UI ẩn hẳn tab khi cờ này false — không hiện tab rỗng.

Nền tảng có từ khoá phủ định ở cấp chiến dịch hay không (áp cho mọi nhóm bên trong). Phải tách khỏi vì hai cấp là hai tab khác nhau trong UI: nền tảng chỉ có phủ định cấp nhóm thì tab cấp chiến dịch không được xuất hiện.

Các chiến lược đặt giá có áp dụng % điều chỉnh giá thầu theo khung giờ. Đặt ở đây thay vì hard-code trong service: nền tảng nào biết luật của nền tảng đó. Tên viết theo enum của nền tảng (SNAKE_CASE); so sánh đi qua nên không phụ thuộc cách viết hoa/gạch dưới.

Các chiến lược đặt giá bỏ qua % điều chỉnh giá thầu theo khung giờ (nhưng vẫn tôn trọng khung giờ chạy/không chạy). Cần liệt kê riêng chứ không suy ra bằng "không nằm trong danh sách áp dụng": còn một nhóm thứ ba là chưa xác định được, và nói sai về tiền thì tệ hơn nói "chưa rõ".

Chiến lược đặt giá của chiến dịch có áp dụng % điều chỉnh theo khung giờ hay không. Trả khi chưa tra được chắc chắn — UI phải nói đúng là "chưa xác định", tuyệt đối không đoán.

Chiến lược lấy từ AdsCampaign.BiddingStrategy. Adapter Google lưu giá trị BiddingStrategyType.ToString() (PascalCase, ví dụ "ManualCpc") nên hàm này bỏ gạch dưới và viết hoa hết trước khi so sánh.

Bỏ gạch dưới + viết hoa để so "MANUAL_CPC" với "ManualCpc" ra cùng một khoá

Nền tảng cho phép sửa giá thầu của nhóm quảng cáo từ LADA hay không

Nền tảng cho phép sửa giá thầu riêng của từ khoá từ LADA hay không

Các chiến lược đặt giá có dùng giá thầu của nhóm/từ khoá khi đấu giá. Danh sách riêng, không dùng chung với : hai thứ khác nhau. Ví dụ TARGET_SPEND vẫn áp dụng % điều chỉnh theo khung giờ nhưng bỏ qua giá thầu nhóm (giới hạn giá thầu của nó nằm ở cấp chiến dịch).

Các chiến lược đặt giá bỏ qua giá thầu nhóm/từ khoá khi đấu giá. Ghi vẫn ghi được và Google không báo lỗi — y hệt cái bẫy của % điều chỉnh theo khung giờ — nên không thể dựa vào API để biết nó có tác dụng. Phải cảnh báo trên UI dựa vào danh sách này.

Chiến lược đặt giá của chiến dịch có dùng giá thầu nhóm/từ khoá hay không. Trả khi chưa tra được chắc chắn — UI phải nói đúng là "chưa xác định" chứ không được đoán.

Chiến lược lấy từ AdsCampaign.BiddingStrategy. Adapter Google lưu BiddingStrategyType.ToString() (PascalCase, ví dụ "ManualCpc") nên hàm này bỏ gạch dưới và viết hoa hết trước khi so sánh.

Nền tảng cho phép kiểm tra trước khi ghi thật (dry-run). Google Ads có validate_only, các nền tảng khác chưa chắc có.

Chiến dịch của nền tảng có tầng nhóm quảng cáo (AdGroup) hay không. Performance Max dùng AssetGroup nên cờ này phải đọc từ Capabilities, đừng giả định.

Nền tảng nhắm mục tiêu bằng từ khoá (Search) hay không

Nền tảng nhắm mục tiêu theo vị trí địa lý hay không

Nền tảng nhắm mục tiêu theo ngôn ngữ hay không

Giới hạn mẫu quảng cáo của nền tảng — service validate theo object này, tuyệt đối không hard-code số 30/90 vào tầng nghiệp vụ.

Nền tảng dùng OAuth (cần bấm "Cấp quyền" để lấy refresh token)

Nền tảng yêu cầu developer token riêng ngoài OAuth

Danh sách field credential UI cần render

Ghi chú cho người cấu hình (tiếng Việt)

Chiến lược đặt giá của chiến dịch có áp dụng % điều chỉnh giá thầu theo khung giờ hay không.

Chưa tra được chắc chắn. UI phải nói đúng là "chưa xác định" chứ không được đoán — đoán sai ở phần giá thầu là tiêu tiền thật của người dùng.

Nền tảng áp dụng % điều chỉnh theo khung giờ

Nền tảng bỏ qua % điều chỉnh theo khung giờ, nhưng vẫn tôn trọng khung giờ chạy/không chạy. Đặt % vẫn ghi được, chỉ là không có tác dụng.

Chiến lược đặt giá của chiến dịch có dùng giá thầu của nhóm quảng cáo / từ khoá hay không.

Chưa tra được chắc chắn. UI phải nói đúng là "chưa xác định" chứ không được đoán — đoán sai ở phần giá thầu là tiêu tiền thật của người dùng.

Nền tảng dùng giá thầu của nhóm/từ khoá khi đấu giá

Nền tảng bỏ qua giá thầu của nhóm/từ khoá (chiến lược tự động tự đặt giá). Ghi vẫn ghi được và đọc lại vẫn thấy giá trị, chỉ là không ảnh hưởng phân phối.

Giới hạn mẫu quảng cáo của một nền tảng. Cả backend (validate) và frontend (đếm ký tự realtime) đều đọc từ đây, nhờ vậy khi Google đổi giới hạn chỉ phải sửa một chỗ trong adapter.

Số tiêu đề tối thiểu

Số tiêu đề tối đa

Độ dài tối đa của một tiêu đề (ký tự)

Số mô tả tối thiểu

Số mô tả tối đa

Độ dài tối đa của một mô tả (ký tự)

Độ dài tối đa của mỗi đoạn đường dẫn hiển thị (Path1/Path2)

Nền tảng có dùng Path1/Path2 (đường dẫn hiển thị) hay không

Bắt buộc phải có URL đích

Bắt buộc phải có ảnh

Số từ khoá tối đa cho một nhóm quảng cáo (0 = không giới hạn / không áp dụng)

Một field credential trong form cấu hình kết nối. Frontend render động theo danh sách này — không hard-code field của từng nền tảng.

Khoá field. Trùng tên property của AdsConnection thì lưu thẳng vào cột, còn lại lưu vào CredentialPayloadJson.

Nhãn hiển thị (tiếng Việt)

Loại input: text | password | url | select

Bắt buộc nhập

Gợi ý trong ô nhập

Hướng dẫn lấy giá trị này ở đâu

Là thông tin mật — API trả về dạng đã che (abcd***wxyz), khi lưu nếu giá trị gửi lên còn chứa *** thì giữ nguyên giá trị cũ trong DB.

Giá trị mặc định

Danh sách lựa chọn khi Type = select

Một lựa chọn của field dạng select.

Giá trị lưu xuống

Nhãn hiển thị

Phần adapter Google Ads phụ trách giá thầu của nhóm quảng cáo (ad_group.cpc_bid_micros). Tách khỏi file chính vì đây là đường ghi chạm tiền trực tiếp: một con số sai ở đây là tiền thật tiêu sai ngay phiên đấu giá kế tiếp. Giá thầu của từ khoá không nằm ở đây — nó đi lại đúng đường ApplyKeywordsAsync (ad_group_criterion) trong GoogleAdsAdapter.Keywords.cs, cố ý một đường ghi cho một loại đối tượng. Các helper dùng chung (ExecuteWithRetryAsync, Failure, FailureFrom) nằm ở GoogleAdsAdapter.cs — cùng một partial class nên gọi trực tiếp được.

Adapter Google Ads (API v25). Xác thực OAuth, kiểm tra kết nối, đọc tài khoản / chiến dịch / nhóm / số liệu. Phần ghi (tạo & sửa chiến dịch, đổi trạng thái, đổi ngân sách) nằm ở GoogleAdsAdapter.Write.cs — tách riêng vì đó là phần tiêu tiền thật.

Phần adapter Google Ads phụ trách quảng cáo cụ thể trong nhóm và từ khoá (cả từ khoá thường và từ khoá phủ định, cả cấp nhóm và cấp chiến dịch). Tách khỏi file chính vì đây là hai cây đối tượng riêng của Google (ad_group_ad, ad_group_criterion, campaign_criterion) và phần ghi từ khoá là thao tác đổi cấu hình đang tiêu tiền: xoá một từ khoá phủ định là mở cửa cho truy vấn rác chạy lại ngay lập tức. Gom vào một chỗ để dễ soát lại. Các helper dùng chung (SearchAsync, ExecuteWithRetryAsync, Failure, FailureFrom, ExtractCriterionId, CriterionResource) nằm ở GoogleAdsAdapter.cs — cùng một partial class nên gọi trực tiếp được.

Scope OAuth duy nhất mà Google Ads API dùng

Endpoint hiện consent screen của Google

Endpoint đổi code / refresh token

Số lần thử lại tối đa khi gặp lỗi tạm thời (quota, mạng)

Gọi endpoint token của Google và dịch lỗi sang tiếng Việt.

Dịch mã lỗi OAuth của Google sang thông báo hành động được cho người cấu hình.

Liệt kê các tài khoản nằm dưới một tài khoản quản lý (MCC) và thêm vào kết quả. Truy vấn chạy với chính MCC làm operating customer nên chỉ cần một lần gọi cho cả cây, kể cả tài khoản cấp cháu. Lỗi ở đây không làm sập lần đồng bộ — MCC vẫn được giữ lại.

Tạo cả cây ngân sách → chiến dịch → nhóm → quảng cáo → từ khoá trong **một** request atomic. Tạo rời từng bước mà lỗi giữa đường sẽ để lại rác trên tài khoản Google (ngân sách mồ côi, chiến dịch không có quảng cáo) mà LADA không biết để dọn. = true thì Google chỉ kiểm tra, không tạo gì thật.

Dựng danh sách operation kèm bảng tra thứ tự để đọc lại id sau khi tạo.

Ghép id nền tảng trả về vào từng cấp bằng cách đi song song danh sách operation đã gửi và danh sách kết quả — Google trả kết quả đúng thứ tự operation.

Gửi một operation đơn lẻ qua GoogleAdsService.Mutate và dịch lỗi sang tiếng Việt.

Dựng criterion lịch quảng cáo để tạo mới. Thứ/giờ của AdScheduleInfo là bất biến bên Google nên mọi thay đổi thứ/giờ đều đi qua đây (tạo mới) chứ không phải update.

Resource name của một campaign criterion. Định dạng có dấu ngã: customers/{cid}/campaignCriteria/{campaignId}~{criterionId}. Nguồn: https://developers.google.com/google-ads/api/rest/reference/rest/v21/customers.campaignCriteria

Lấy phần id con (sau dấu ngã) từ resource name ghép của Google. Chỉ là lớp gọi lại — logic nằm ở mapper để unit test chạm được (adapter cần một GoogleAdsClient thật). Giữ tên cũ vì trong adapter phần lớn đối tượng con là criterion.

Resource name tạm với id âm — dùng để nối các cấp trong cùng một request atomic.

Đọc match type từ cú pháp quen thuộc của Google Ads Editor: [từ khoá] = khớp chính xác, "từ khoá" = khớp cụm, còn lại = khớp rộng.

Khoá nhận lại id quảng cáo sau khi tạo: tên nhóm + headline đầu tiên.

Danh sách operation kèm bảng tra thứ tự để ghép id nền tảng trả về vào đúng cấp.

Khoá do LADA gửi lên (tên nhóm / khoá quảng cáo) để nhận lại id

Chạy một câu GAQL và trả về toàn bộ dòng (tự phân trang). Dùng cho dữ liệu cấu hình (tài khoản, chiến dịch, nhóm) — số dòng nhỏ.

Chạy một câu GAQL bằng SearchStream — dùng cho số liệu theo ngày (nhiều dòng).

Thử lại với thời gian chờ tăng dần khi Google trả lỗi tạm thời (quota, rate limit, mạng). Lỗi nghiệp vụ (sai quyền, sai câu truy vấn) không thử lại — thử lại chỉ tốn quota mà không đổi kết quả.

Lỗi có đáng thử lại không: hết quota, quá tải, timeout, hoặc lỗi nội bộ của Google.

Dịch lỗi Google Ads sang thông báo tiếng Việt, kèm mã lỗi gốc để tra tài liệu.

Mã lỗi của Google là một message dạng JSON — rút gọn lại thành chuỗi ngắn để lưu log.

Chuyển các mã lỗi Google hay gặp thành hướng dẫn xử lý cụ thể. Mã không nằm trong danh sách vẫn giữ nguyên thông báo gốc của Google để không mất thông tin.

Suy ra field credential cần sửa từ mã lỗi, để UI highlight đúng ô nhập.

Dựng tên hiển thị của một quảng cáo. ad.name hầu như luôn rỗng với quảng cáo tìm kiếm (Google chỉ cho đặt tên ở vài loại), nên lấy tiêu đề đầu tiên của mẫu quảng cáo thay thế. Không bao giờ trả chuỗi rỗng: danh sách toàn dòng không tên thì người dùng không phân biệt được đang bật/tắt quảng cáo nào — đúng cái nhầm lẫn dẫn tới tắt sai thứ đang chạy tốt.

Map các dòng ad_group_criterion thành DTO từ khoá cấp nhóm. Gộp cả từ khoá thường và phủ định — Google dùng chung một resource, chỉ khác cờ.

Map các dòng campaign_criterion thành DTO từ khoá phủ định cấp chiến dịch. GAQL cố ý không lọc negative = TRUE nên phải lọc tại đây. Từ khoá cấp chiến dịch không phủ định là chuyện Google không dùng cho tìm kiếm — bỏ qua, vì hiện nó lên danh sách "từ khoá phủ định cấp chiến dịch" là nói sai với người dùng.

Dựng operation cho từ khoá cấp nhóm (ad_group_criterion). Trả null kèm tiếng Việt khi dữ liệu không đủ để gửi.

Dựng operation cho từ khoá phủ định cấp chiến dịch (campaign_criterion). Không có nhánh Update: từ khoá phủ định cấp chiến dịch không có giá thầu, mà text và kiểu khớp là bất biến bên Google. Mọi thay đổi đều là xoá + tạo lại.

Resource name của một ad group criterion. Định dạng có dấu ngã: customers/{cid}/adGroupCriteria/{adGroupId}~{criterionId}. Đây là nơi duy nhất ghép dạng này. Canonical entity luôn lưu criterion id trần — lưu dạng ghép từng gây hai lỗi ở AdsItem: ghép lần hai khi đổi trạng thái, và số liệu theo cấp không bao giờ khớp được. Nguồn: https://developers.google.com/google-ads/api/rest/reference/rest/v25/customers.adGroupCriteria

Tạo từ credentials lưu trong . Credentials không nằm trong appsettings — người dùng nhập ở trang cấu hình kết nối.

Tạo client cho một kết nối. Ném (tiếng Việt) nếu thiếu credential bắt buộc — gọi trước để có danh sách field thiếu.

Kiểm tra đủ credential để gọi API chưa. Trả về danh sách key field còn thiếu (rỗng = đủ).

Phiên bản API mặc định khi kết nối không cấu hình

Bỏ dấu gạch ngang và khoảng trắng khỏi customer id (Google hiển thị dạng 123-456-7890).

Toàn bộ câu truy vấn GAQL của module quảng cáo nằm ở một chỗ. Lý do: khi Google đổi tên field hoặc sunset version, chỉ phải sửa file này thay vì đi tìm chuỗi query rải rác trong adapter. Quy ước: field tiền tệ của Google là micros — adapter luôn chia qua trước khi trả ra ngoài.

Thông tin một tài khoản quảng cáo (chạy với chính customer id đó làm operating customer).

Các tài khoản nằm dưới một tài khoản quản lý (MCC), kể cả cấp cháu (level > 1). Cần thiết vì ListAccessibleCustomers chỉ trả về tài khoản mà email đã cấp quyền truy cập trực tiếp — thường chỉ là MCC, không có tài khoản con chạy quảng cáo. Bỏ tài khoản đã ẩn để danh sách trong LADA không bị rác.

Danh sách chiến dịch kèm ngân sách, chiến lược giá và khoảng thời gian chạy. Bỏ chiến dịch đã xoá để danh sách trong LADA không bị rác.

Danh sách nhóm quảng cáo. Thêm điều kiện chiến dịch bằng khi cần giới hạn.

Lịch chạy quảng cáo của chiến dịch (ad schedule). Ad schedule là campaign_criterion kiểu AD_SCHEDULE — thuộc cấp chiến dịch, không phải cấp nhóm. Lọc type = 'AD_SCHEDULE' để không kéo cả criterion vị trí / ngôn ngữ (cùng nằm trong bảng này). campaign_criterion.bid_modifier có thể **không được set** — khác hẳn với set = 0.0 (0.0 nghĩa là -100%). Adapter phải kiểm tra cờ HasBidModifier chứ không so giá trị. Không lấy criterion đã REMOVED để danh sách trong LADA không bị rác.

Số liệu theo ngày ở cấp chiến dịch. segments.date trong SELECT là thứ tách số liệu thành từng ngày — thiếu nó Google trả về một dòng tổng cho cả khoảng thời gian.

Số liệu theo ngày ở cấp nhóm quảng cáo.

Số liệu theo ngày ở cấp từng quảng cáo.

Danh sách quảng cáo cụ thể trong các nhóm (cấu trúc, không có số liệu). Khác : câu đó cũng FROM ad_group_ad nhưng chỉ lấy ad.id + metrics theo ngày. Câu này lấy tên / loại / trạng thái xét duyệt để dựng được danh sách quảng cáo trong nhóm. Bẫy: ad_group_ad.ad.name hầu như luôn rỗng với quảng cáo tìm kiếm — Google chỉ cho đặt name ở một số loại quảng cáo. Vì vậy lấy kèm responsive_search_ad.headlines để adapter dựng tên hiển thị từ tiêu đề đầu tiên, tránh danh sách toàn dòng trống tên. Bỏ quảng cáo đã REMOVED để danh sách trong LADA không bị rác.

Từ khoá cấp nhóm quảng cáo — cả từ khoá thường và từ khoá phủ định. Google dùng chung một resource ad_group_criterion cho hai loại, phân biệt bằng cờ negative. Câu này cố ý không lọc theo negative trong WHERE: một lần gọi lấy đủ cả hai loại (tiết kiệm quota), adapter tự chia theo cờ. Bẫy proto3: ad_group_criterion.negative và cpc_bid_micros có thể chưa được set, khác hẳn với set = false / 0. Adapter phải kiểm cờ HasNegative / HasCpcBidMicros chứ không so giá trị — cùng cái bẫy HasBidModifier đã ghi ở . quality_info và approval_status chỉ có với từ khoá thường; từ khoá phủ định không được Google chấm điểm nên hai field đó sẽ rỗng — đúng như vậy, không phải lỗi.

Từ khoá phủ định cấp chiến dịch (áp cho mọi nhóm bên trong chiến dịch). Cùng bảng campaign_criterion với lịch chạy quảng cáo nhưng lọc type = 'KEYWORD' thay vì 'AD_SCHEDULE' — đây là câu mới, giữ nguyên không sửa. Cố ý không lọc negative = TRUE trong WHERE mà để adapter kiểm cờ HasNegative/Negative: query trả về tập rộng hơn rồi lọc ở tầng adapter thì không phụ thuộc vào việc Google có cho lọc field đó hay không, và không tốn thêm lần gọi nào (adapter vốn đã đi qua từng dòng).

Số liệu theo ngày ở cấp từ khoá. Phải là FROM keyword_view, không phải ad_group_criterion: resource ad_group_criterion chỉ mang cấu trúc và không có metrics nào. Chỉ từ khoá thường mới có số liệu — từ khoá phủ định không chạy nên không xuất hiện trong keyword_view.

Thêm điều kiện giới hạn theo một chiến dịch vào câu truy vấn nhóm quảng cáo.

Thêm điều kiện giới hạn theo một chiến dịch vào câu truy vấn lịch quảng cáo.

Giới hạn câu theo một chiến dịch.

Giới hạn câu theo một nhóm quảng cáo.

Giới hạn câu theo một chiến dịch.

Giới hạn câu theo một nhóm quảng cáo.

Giới hạn câu theo một chiến dịch.

Điền khoảng ngày vào câu truy vấn số liệu (Google nhận định dạng yyyy-MM-dd).

Chuyển đổi giữa kiểu dữ liệu của Google Ads và canonical model của LADA. Toàn bộ phép đổi micros nằm ở đây — tuyệt đối không nhân/chia 1.000.000 rải rác trong adapter, vì sai chiều một lần là chi phí lệch một triệu lần.

Hệ số micros của Google (1 đơn vị tiền tệ = 1.000.000 micros)

Đổi số tiền theo đơn vị tiền tệ của tài khoản sang micros để gửi lên Google. Làm tròn về số nguyên gần nhất (Google chỉ nhận số nguyên).

Đổi micros nhận từ Google về đơn vị tiền tệ của tài khoản.

Đổi micros nhận từ Google về đơn vị tiền tệ, coi null là 0.

Đổi micros dạng số thực về đơn vị tiền tệ (một vài metric của Google khai báo double, ví dụ metrics.average_cpc). Vẫn đi qua đúng một chỗ chia micros.

Bỏ dấu gạch ngang khỏi customer id (Google hiển thị dạng 123-456-7890, API nhận 1234567890).

Lấy id số cuối cùng trong một resource name của Google (ví dụ "customers/123/campaigns/456" → "456").

Lấy id con trần từ resource name ghép của Google. Google định danh mọi đối tượng con bằng {parentId}~{childId}: adGroupAds/{adGroupId}~{adId}, adGroupCriteria/{adGroupId}~{criterionId}, campaignCriteria/{campaignId}~{criterionId}, keywordViews/{adGroupId}~{criterionId}. Vì sao cần hàm riêng: chỉ cắt theo dấu "/" nên trả về cả cụm ghép. Dùng nó cho đối tượng con chính là lỗi đã làm AdsItem.ExternalId lưu sai định dạng — kéo theo hai hậu quả: đổi trạng thái ghép id lần thứ hai thành {groupId}~{groupId}~{adId}, và số liệu theo cấp không bao giờ khớp được vì phía số liệu trả id trần. Chuẩn của LADA: canonical luôn lưu id trần; việc ghép lại chỉ xảy ra trong adapter.

Trạng thái Google (ENABLED / PAUSED / REMOVED) → trạng thái canonical. Giá trị lạ (UNKNOWN / UNSPECIFIED) map về Draft để không hiển thị sai là đang chạy.

Trạng thái canonical → chuỗi trạng thái Google. Draft không tồn tại bên Google nên đẩy lên thành PAUSED (an toàn về chi phí).

AdvertisingChannelType của Google → mục tiêu canonical. Google không có khái niệm "objective" như Facebook, nên đây chỉ là suy luận gần đúng; giá trị gốc luôn được giữ trong ChannelType và PlatformPayloadJson.

Mục tiêu canonical → AdvertisingChannelType của Google. Phase 2 chỉ hỗ trợ Search nên mọi mục tiêu đều tạo chiến dịch SEARCH; khi mở thêm loại chiến dịch thì sửa ở đây, không sửa ở tầng nghiệp vụ.

Loại ngân sách canonical → BudgetDeliveryMethod / period của Google. Google Ads chỉ có ngân sách theo ngày cho chiến dịch Search; ngân sách trọn chiến dịch không được hỗ trợ nên gọi hàm này với Lifetime sẽ báo lỗi rõ ràng.

Đổi ngày sang định dạng yyyy-MM-dd mà Google Ads dùng cho start_date_time. V25 nhận chuỗi "yyyy-MM-dd HH:mm:ss" — phần giờ để 00:00:00 nghĩa là tính theo ngày.

Đổi ngày kết thúc sang định dạng Google. Phần giờ 23:59:59 để chạy hết ngày cuối.

Đọc ngày Google trả về. V25 trả "yyyy-MM-dd HH:mm:ss" cho start_date_time / end_date_time, các field cũ trả "yyyy-MM-dd" hoặc "yyyyMMdd". Trả null nếu không parse được.

Thứ trong tuần của Google (MONDAY…SUNDAY) → của .NET. Không dùng ép kiểu số: enum Google là MONDAY = 2 (0 = UNSPECIFIED, 1 = UNKNOWN) còn .NET là Sunday = 0. Ép kiểu sẽ lệch ngày — lịch chạy sai hẳn một thứ. Giá trị lạ trả về null để service bỏ qua dòng thay vì ghi sai thứ.

Phút của Google (MinuteOfHour: ZERO / FIFTEEN / THIRTY / FORTY_FIVE) → số phút. Google chỉ cho 4 mốc này; giá trị lạ coi như 0 để không dựng ra khung giờ vô nghĩa. Tên enum trong SDK C# là dạng PascalCase (Zero, Fifteen, Thirty, FortyFive) — nhận cả dạng SNAKE_CASE của GAQL cho chắc.

Chiều ghi: của .NET → enum thứ của Google. Đổi theo tên, tuyệt đối không ép kiểu số: .NET Sunday = 0 còn Google MONDAY = 2. Ép kiểu là ghi lịch lệch một thứ lên tài khoản thật.

Chiều ghi: số phút → enum MinuteOfHour của Google. Google chỉ nhận 4 mốc 0/15/30/45; số khác bị chặn từ tầng validate (AdsScheduleDiff.Validate) nên tới đây mà lạ là lỗi lập trình → ném luôn.

Kiểu khớp của Google (EXACT / PHRASE / BROAD) → kiểu khớp canonical. Trả null với UNSPECIFIED / UNKNOWN / giá trị lạ. Cố ý không quy về : khớp rộng là kiểu ăn truy vấn không liên quan và đốt ngân sách nhanh nhất, nên đoán sai về phía đó là đoán sai về phía tốn tiền. Adapter bỏ qua dòng và ghi log — cùng cách xử lý như . Nhận cả SNAKE_CASE của GAQL và PascalCase của SDK C# (MatchType.ToString()). Đổi theo tên, tuyệt đối không ép kiểu số: enum Google có UNSPECIFIED = 0, UNKNOWN = 1 nên EXACT = 2 chứ không phải 1 như canonical.

Chiều ghi: kiểu khớp canonical → enum kiểu khớp của Google. Giá trị canonical lạ thì ném lỗi chứ không trả UNSPECIFIED: gửi UNSPECIFIED lên Google sẽ bị nền tảng tự hiểu, và cái nó hiểu có thể là khớp rộng — tức là tạo ra một từ khoá tốn tiền hơn hẳn thứ người dùng chọn.

Đổi tên enum của SDK C# (PascalCase) về đúng dạng tài liệu Google dùng (SNAKE_CASE hoa): ResponsiveSearchAd → RESPONSIVE_SEARCH_AD, ReviewInProgress → REVIEW_IN_PROGRESS. Dùng cho các field LADA cố ý giữ nguyên tên gốc của nền tảng (loại quảng cáo, trạng thái xét duyệt): người dùng phải tra được đúng chuỗi đó trong tài liệu Google. Trả về PascalCase của SDK sẽ khiến tra cứu không ra. UNSPECIFIED / UNKNOWN trả null — hai giá trị này không mang thông tin nào, hiện lên UI chỉ làm người dùng tưởng nền tảng đã trả về một trạng thái thật.

Hợp đồng chung cho mọi nền tảng quảng cáo (Google, Facebook, TikTok, Zalo). Nguyên tắc: không một kiểu dữ liệu nào của SDK nền tảng được lọt ra ngoài adapter — mọi thứ đi vào/đi ra đều là entity canonical hoặc DTO trong AdsAdapterDtos.cs. Mọi thông báo lỗi trả về phải là tiếng Việt, kèm mã lỗi gốc của nền tảng để tra cứu.

Nền tảng mà adapter này phục vụ

Năng lực của nền tảng — UI dùng để render form credential và bật/tắt chức năng. Không cần kết nối, gọi được ngay khi chưa cấu hình gì.

Tạo URL để người dùng bấm vào cấp quyền (OAuth consent screen).

Đổi authorization code (nhận từ callback) thành access token + refresh token.

Làm mới access token bằng refresh token đang lưu.

Kiểm tra kết nối: gọi thử một API nhẹ của nền tảng. Trả về thông báo tiếng Việt cụ thể (thiếu field nào, token sai, hay thiếu quyền).

Lấy danh sách tài khoản quảng cáo mà kết nối này truy cập được. Trả về cả phần lỗi của từng tài khoản đọc không được — service dùng để ghi sync log, nhờ vậy đồng bộ ra 0 tài khoản luôn kèm lý do cụ thể thay vì im lặng.

Lấy danh sách chiến dịch của một tài khoản quảng cáo.

Id tài khoản bên nền tảng

Lấy danh sách nhóm quảng cáo. Truyền để giới hạn theo một chiến dịch.

Lấy lịch chạy quảng cáo (ad schedule) của tài khoản. Truyền để giới hạn theo một chiến dịch. Ad schedule là criterion cấp chiến dịch. Trả về danh sách rỗng nghĩa là chiến dịch **chạy cả tuần 24/7** — không phải "không chạy". Nền tảng chưa hỗ trợ thì trả về danh sách rỗng, không ném exception.

Lấy danh sách quảng cáo cụ thể trong các nhóm (cấu trúc, không kèm số liệu). Truyền và/hoặc để giới hạn phạm vi. trả về là id trần. Việc ghép thành resource name dạng {adGroupId}~{adId} nằm hoàn toàn trong adapter. Yêu cầu = true. Nền tảng chưa hỗ trợ thì trả về danh sách rỗng, không ném exception.

Lấy danh sách từ khoá — cả từ khoá thường và từ khoá phủ định, phân biệt bằng và . Phạm vi theo tham số: có : chỉ từ khoá cấp nhóm của nhóm đó; chỉ có : từ khoá cấp nhóm của mọi nhóm cộng từ khoá phủ định cấp chiến dịch; không có gì: toàn bộ tài khoản. Danh sách rỗng nghĩa là không có từ khoá nào — với từ khoá phủ định, đó là "không loại trừ truy vấn nào", tức mọi truy vấn liên quan đều có thể tiêu tiền. LADA không đọc được từ khoá phủ định nằm trong danh sách dùng chung (Google shared set) — chúng vẫn có tác dụng trên nền tảng nhưng không xuất hiện ở đây. UI phải nói rõ điều này thay vì để người dùng tưởng danh sách đã đủ. Yêu cầu = true. Nền tảng chưa hỗ trợ thì trả về danh sách rỗng, không ném exception.

Lấy số liệu theo ngày trong khoảng [from, to] ở cấp . Chi phí đã được chia micros trong adapter — không bao giờ trả micros ra ngoài.

Tạo chiến dịch (kèm nhóm, mẫu QC, targeting) trên nền tảng. Mặc định tạo ở trạng thái tạm dừng để tránh tiêu tiền ngoài ý muốn.

Gửi yêu cầu tạo chiến dịch ở chế độ kiểm tra (dry-run): nền tảng validate toàn bộ nhưng không tạo gì thật. Chỉ gọi được khi = true. Đây là cách duy nhất biết trước Google có nhận dữ liệu hay không mà không tiêu tiền.

Cập nhật chiến dịch đã tồn tại trên nền tảng.

Đổi trạng thái (bật/tạm dừng) một đối tượng quảng cáo trên nền tảng.

Id đối tượng bên nền tảng, dạng id trần — không phải resource name, cũng không phải dạng ghép {parentId}~{id}. Việc ghép là việc của adapter. Id đối tượng cha bên nền tảng, bắt buộc với : Google định danh một quảng cáo bằng {adGroupId}~{adId} nên thiếu id nhóm thì không dựng được resource name. Các cấp khác không cần.

Đổi ngân sách của một chiến dịch đã tồn tại trên nền tảng. Nhận số tiền theo đơn vị tiền tệ của tài khoản — việc đổi sang micros là việc của adapter.

Id đối tượng ngân sách bên nền tảng Ngân sách/ngày theo đơn vị tiền tệ của tài khoản

Áp lịch chạy quảng cáo lên nền tảng: gửi cả lô thao tác (xoá + thêm + đổi % giá thầu) trong một request atomic. Cố ý là một method cho cả lô, không tách thành ba: đổi được một nửa lịch là trạng thái tệ nhất — giá thầu đã thay đổi thật mà LADA lại không biết khung nào đã đi, khung nào chưa. = true thì nền tảng chỉ kiểm tra, không ghi gì (Google: validate_only). Chỉ gọi được khi = true. Yêu cầu = true. Nền tảng chưa hỗ trợ thì trả về Success = false kèm lý do tiếng Việt, không ném exception.

Áp từ khoá lên nền tảng: gửi cả lô thao tác (xoá + thêm + đổi giá thầu) trong một request atomic. Cố ý là một method cho cả lô: xoá được một nửa rồi lỗi là trạng thái tệ nhất — chiến dịch mất từ khoá phủ định mà vẫn đang chạy, tiền chảy ra ngay và LADA không biết dòng nào đã đi. = true thì nền tảng chỉ kiểm tra, không ghi gì (Google: validate_only). Chỉ gọi được khi = true — nền tảng không có dry-run thì phải trả về lỗi, tuyệt đối không âm thầm ghi thật. Yêu cầu = true. Nền tảng chưa hỗ trợ thì trả về Success = false kèm lý do tiếng Việt, không ném exception.

Đổi giá thầu cho cả lô nhóm quảng cáo của một tài khoản trong một request atomic. Giá thầu trong là đơn vị tiền tệ; việc đổi ra micros là của adapter, tầng nghiệp vụ không được biết đến micros. = true thì nền tảng chỉ kiểm tra, không ghi gì. Chỉ gọi được khi = true — nền tảng không có dry-run thì phải trả về lỗi, tuyệt đối không âm thầm ghi thật. Yêu cầu = true. Nền tảng chưa hỗ trợ thì trả về Success = false kèm lý do tiếng Việt, không ném exception.

Quản lý tài khoản quảng cáo đồng bộ từ nền tảng về. Tài khoản không được tạo tay trong LADA — luôn kéo từ nền tảng để ExternalId chắc chắn đúng.

Danh sách tài khoản đang dùng được của một kết nối (cho dropdown)

Kéo danh sách tài khoản từ nền tảng về, upsert theo (AdsConnectionId, ExternalId).

Bật/tắt việc đưa tài khoản vào các job đồng bộ định kỳ

Lấy entity kèm kết nối — dùng nội bộ backend khi cần credential

Kết quả đồng bộ tài khoản quảng cáo.

Số tài khoản mới thêm

Số tài khoản đã cập nhật

Tổng số tài khoản nền tảng trả về

Phép tính áp lên giá thầu cũ của từng dòng.

Đặt thẳng một giá thầu mới, không phụ thuộc giá cũ

Tăng theo phần trăm giá cũ

Giảm theo phần trăm giá cũ

Cộng thêm một số tiền vào giá cũ

Trừ bớt một số tiền khỏi giá cũ

Lý do một dòng không đổi được giá thầu, ở mức phép tính (không phải mức dữ liệu). Là enum chứ không phải chuỗi để test khẳng định được đúng nhánh mà không phụ thuộc câu chữ tiếng Việt; câu hiển thị dựng ở .

Tính được bình thường

Chưa có giá thầu riêng mà phép tính lại dựa trên giá cũ (±% hoặc ± số tiền). Ca thật: 2.711/2.718 từ khoá đang kế thừa giá thầu của nhóm — nhân lên sẽ vô tình sinh hàng nghìn giá thầu riêng, đúng thứ người dùng không hề yêu cầu.

Giá thầu mới bằng đúng giá cũ — gửi lên nền tảng chỉ tốn quota và làm số đếm sai

Kết quả tính giá thầu mới cho một dòng.

Giá thầu mới đã làm tròn và kẹp. null khi dòng bị bỏ qua.

Lý do bỏ qua; nghĩa là tính được

Tính được và có thay đổi

Giá trị đã bị sàn/trần kéo về — giao diện phải nói rõ, vì "tăng 50 %" mà kết quả không tăng 50 % là chuyện người dùng cần biết ngay trên dòng đó.

Luật tính giá thầu hàng loạt — thuần, không chạm DB, không chạm SDK nền tảng. Tách riêng để test được từng luật và từng ca biên: đây là chỗ duy nhất quyết định con số sẽ ghi lên nền tảng, mà ghi sai một con số ở đây là tiêu sai tiền thật ngay phiên đấu giá kế tiếp. Mọi thứ cần biết đều truyền vào tham số, không đọc trạng thái bên ngoài.

Các mã tiền tệ không có phần lẻ (ISO 4217 minor unit = 0). Giá thầu VND phải là số nguyên đồng; gửi 1234,5 ₫ lên Google là tự chuốc lấy sai số làm tròn ở phía nền tảng.

Trần phần trăm tăng một lần — chặn lỗi gõ thừa số 0 biến giá thầu thành gấp trăm lần

Bội số so với giá cũ mà vượt qua thì cảnh báo mềm (sổ nợ N-32). Phép "Đặt giá thầu" không có trần nào: gõ thừa một số 0 (60.000 ₫ thay vì 6.000 ₫) qua được . Cố ý cảnh báo chứ không chặn — giá thầu hợp lệ khác nhau theo tài khoản, một con số cứng sẽ chặn nhầm nhiều hơn chặn đúng (cùng nếp cảnh-báo-không-chặn của plan §3.5).

Giá mới có vọt lên quá lần giá cũ không. Giá cũ đúng bằng sàn cứng của tiền tệ thì không tính — và đó không phải ngoại lệ cho đẹp: đo trên dữ liệu thật ngày 05/09/2026, 146/149 nhóm đang ở 1 ₫, tức mức nhỏ nhất gửi được. Với chúng thì mọi giá thầu thật đều vượt 10 lần, nên không lọc ra thì cảnh báo bật trên gần như mọi dòng và trở thành cái chuông kêu suốt — đúng thứ làm người ta bỏ qua cả những cảnh báo có thật. 1 ₫ là "chưa đặt giá bao giờ", không phải một mốc để so.

Số chữ số thập phân của một loại tiền (VND = 0, mặc định = 2)

Giá thầu nhỏ nhất gửi được của một loại tiền — 1 đơn vị nhỏ nhất (VND: 1 ₫; USD: 0,01 $). Google từ chối cpc_bid_micros ≤ 0 nên đây là sàn cứng, không phải lựa chọn giao diện.

Kiểm tra tham số của cả lô trước khi tính dòng nào. Trả null là hợp lệ. Tách khỏi vì đây là lỗi của yêu cầu, không phải của một dòng: sai ở đây thì từ chối cả lô và không gọi ra nền tảng lần nào.

Tính giá thầu mới cho một dòng. Thứ tự cố ý: tính thô → làm tròn theo tiền tệ → kẹp vào sàn/trần người dùng nhập → kéo lên sàn cứng của nền tảng → so với giá cũ. Kẹp trước khi làm tròn sẽ để lọt giá trị vượt trần đúng bằng nửa đơn vị làm tròn.

Giá thầu hiện tại. null = chưa có giá thầu riêng (từ khoá đang kế thừa của nhóm): đặt giá riêng mới, còn ± thì bỏ qua vì không có gốc để tính. Sàn do người dùng nhập (tuỳ chọn) — kẹp sau khi tính Trần do người dùng nhập (tuỳ chọn) — kẹp sau khi tính Mã tiền của tài khoản, quyết định cách làm tròn và sàn cứng

Câu tiếng Việt cho lý do bỏ qua, khác nhau theo cấp vì người đọc cần biết phải làm gì tiếp.

true = dòng từ khoá, false = dòng nhóm quảng cáo

Kết cục của một dòng trong lô đổi giá thầu.

Nền tảng từ chối hoặc lời gọi lỗi — dòng này chưa đổi gì cả

Đổi được (xem trước: sẽ đổi được)

Không đổi vì lý do hợp lệ — không phải lỗi

Nền tảng đã đổi giá thầu nhưng LADA chưa ghi lại được (DB lỗi ngay sau lời gọi). Phải là một kết cục RIÊNG, không được gộp vào : gộp vào là nói với người dùng "chưa đổi gì" trong khi tiền đã đổi thật, và bảng kết quả trở thành lời mời chạy lại — chạy lại thì mức tăng cộng chồng lên nhau trên nền tảng.

Một dòng kết quả đổi giá thầu — mỗi nhóm hoặc mỗi từ khoá một dòng.

Id nhóm hoặc Id từ khoá bên LADA

Tên nhóm, hoặc nội dung từ khoá

Tên nhóm cha — chỉ có ý nghĩa với dòng từ khoá

Giá thầu hiện tại. null = đang kế thừa giá thầu nhóm.

Giá thầu sau khi đổi. null khi dòng bị bỏ qua hoặc thất bại.

Nhãn kết cục cho giao diện — chỉ một chỗ dựng chữ, tránh mỗi bảng một kiểu

Lý do bỏ qua / thất bại, tiếng Việt, nói rõ phải làm gì tiếp

Giá trị đã bị sàn/trần kéo về nên không đúng bằng phép tính đã nhập

Cảnh báo chiến lược đặt giá bỏ qua giá thầu — không chặn, nhưng phải hiện trên đúng dòng đó. Google vẫn nhận và đọc lại vẫn thấy giá trị, nên không có cách nào biết bằng API là nó vô tác dụng.

Cảnh báo mềm "giá mới vọt hơn 10 lần giá hiện tại" (sổ nợ N-32) — không chặn, hiện ngay trên dòng xem trước để lỗi gõ thừa số 0 lộ ra trước khi bấm ghi.

Dòng bị bỏ qua vì giá thầu đã đổi so với lúc xem trước (sổ nợ N-31). Tách khỏi để giao diện làm nổi bật riêng — đây không phải một lý do bỏ qua thông thường mà là dấu hiệu bảng xác nhận đã cũ.

Kết quả một lô đổi giá thầu. là ca lô bị từ chối trước khi chạy (Id lạ, quá trần, tham số sai): rỗng, Message là lý do — controller trả 400, giao diện dừng lô thay vì suy đoán từ số dòng. Giống hệt khuôn của kéo lịch về hàng loạt.

Bản xem trước (nền tảng chỉ kiểm tra) hay lần ghi thật

Lô bị từ chối trước khi chạy — không dòng nào được xử lý, không gọi nền tảng lần nào

Nền tảng đã nhận toàn bộ phần gửi lên hay chưa. Xem trước mà cờ này false nghĩa là bấm ghi thật cũng sẽ hỏng đúng chỗ đó.

Số dòng nền tảng đã đổi mà LADA chưa ghi lại được — giao diện phải nói rõ đừng chạy lại lô, vì chạy lại là cộng chồng mức tăng trên nền tảng.

Số dòng bị bỏ qua vì giá thầu đã đổi từ lúc xem trước (N-31). Đếm riêng vì giao diện phải mời người dùng xem trước lại, khác hẳn các lý do bỏ qua khác.

Số lời gọi mutate đã gửi ra nền tảng — để ước lượng quota

Cảnh báo gộp cho cả lô khi có dòng thuộc chiến dịch dùng chiến lược bỏ qua giá thầu. Hiện thành băng-rôn trên hộp thoại, ngoài cảnh báo từng dòng.

Đổi giá thầu hàng loạt cho nhóm quảng cáo và từ khoá.

Xem trước: tính giá mới cho từng dòng rồi hỏi nền tảng bằng validate_only. Không ghi gì vào LADA và không ghi gì lên nền tảng.

Ghi thật: gửi lên nền tảng trước, thành công mới ghi giá thầu mới vào LADA. Nền tảng từ chối thì LADA giữ nguyên số cũ, không bao giờ lệch.

Trần Id một lô — cùng con số với mọi endpoint nhận danh sách Id khác (plan §3.9)

Field mask duy nhất được gửi khi đổi giá thầu — dựng tay, xem bẫy proto3 ở adapter

Lõi dùng chung của xem trước và ghi thật, khác nhau đúng một cờ . Cố ý dùng chung: bản xem trước không bao giờ được tính khác bản ghi thật — cùng bài học đã rút ở luồng áp lịch (ApplyCoreAsync).

Gửi một cụm lên nền tảng. Cụm là một chiến dịch (nhóm) hoặc một nhóm (từ khoá) nên mọi dòng trong cụm chắc chắn cùng tài khoản, cùng kết nối.

Ghi một dòng nhật ký đồng bộ; lỗi ghi log chỉ được cảnh báo, không được ném ra.

Ghi giá thầu mới vào LADA sau khi nền tảng đã nhận.

Các ca bỏ qua vì dữ liệu, kiểm trước khi tính toán gì. Cùng khuôn với AdsScheduleService.SkipReasonFor: gọi vào nền tảng ở các ca này là chắc chắn thất bại và chỉ tốn quota.

Cảnh báo chiến lược đặt giá bỏ qua giá thầu. Không chặn: Google vẫn nhận, vẫn lưu và đọc lại vẫn thấy giá trị — chặn ở đây sẽ lệch với tính năng lịch chạy đang cho đặt % kèm cảnh báo trên đúng các chiến lược này (plan §3.5).

Bảng "giá cũ người dùng đã nhìn thấy" theo Id (N-31), hoặc null khi không phải kiểm. Trả null ở bước xem trước và khi client không gửi gì: hàng rào này là ràng buộc giữa hai bước, không phải một trường bắt buộc — biến nó thành bắt buộc sẽ làm mọi lời gọi cũ hỏng mà không thêm an toàn nào cho luồng giao diện (nút ghi chỉ mở sau xem trước).

Cảnh báo mềm giá vọt (N-32) cho một dòng — chỉ dựng câu chữ, luật nằm ở để test được không qua DB.

Số tiền cho câu tiếng Việt trong lý do / cảnh báo. null là "kế thừa nhóm", khác hẳn 0 ₫ — cùng quy ước với bảng ở giao diện.

Một câu gộp cho băng-rôn hộp thoại, đếm số dòng bị ảnh hưởng.

Một dòng cần đổi giá thầu, đã gom đủ mọi thứ cần biết từ hai cây entity khác nhau (nhóm và từ khoá) để phần tính toán bên dưới chỉ viết một lần.

Chính nó, khi lô là lô nhóm quảng cáo

Chính nó, khi lô là lô từ khoá

Id nhóm (lô nhóm) hoặc criterion id (lô từ khoá) bên nền tảng

Id nhóm cha bên nền tảng — bắt buộc với lô từ khoá

Đọc và soạn chiến dịch quảng cáo trong LADA. Service này chỉ làm việc với bản ghi canonical — mọi thao tác đẩy ra nền tảng (tiêu tiền thật) nằm ở và yêu cầu quyền riêng.

Chi tiết chiến dịch: thông tin chiến dịch, danh sách nhóm và số liệu tổng hợp trong khoảng ngày (mặc định 30 ngày gần nhất).

Lấy entity kèm tài khoản và kết nối — dùng nội bộ backend

Lưu cả cây chiến dịch nháp: chiến dịch → nhóm → mẫu quảng cáo → targeting. Chiến dịch đã có trên nền tảng chỉ cho sửa những trường đẩy lên được — không cho thay cấu trúc nhóm/mẫu vì bản trên nền tảng sẽ lệch ngay.

Xoá mềm chiến dịch trong LADA. Chiến dịch đã đẩy lên nền tảng thì phải xoá trên nền tảng trước — xoá trong LADA không dừng được quảng cáo đang tiêu tiền.

Phần soạn chiến dịch nháp trong LADA (chưa chạm tới nền tảng). Tách file để phần đọc ở AdsCampaignService.cs giữ được độ ngắn dễ đọc.

Đường riêng cho việc sắp theo cột số liệu: sắp chính truy vấn chiến dịch bằng một truy vấn con tương quan cộng AdsMetricDaily của khoảng ngày, rồi mới cắt trang. Không gộp sẵn bằng GroupBy rồi nối trái vào: EF Core không dịch nổi một projection của GroupBy nằm ở vế trong của phép nối và ném "The LINQ expression … could not be translated" ngay khi chạy thật (bẫy đã cắn — test chạy trên repository giả trong bộ nhớ dịch được mọi thứ nên không thấy). Ba điểm đã cân nhắc: Công thức gộp phải khớp — tỉ lệ tính từ tổng tử số chia tổng mẫu số, không phải trung bình cột tỉ lệ của từng ngày. Lệch thì bảng sắp một đằng còn cột hiện một nẻo, và người xem tin vào cột. Chiến dịch chưa có dòng số liệu nào coi như 0 khi sắp (ô vẫn hiện "—"): sắp giảm dần chúng nằm cuối, sắp tăng dần chúng nằm cùng nhóm chi 0 đồng. Sau khoá sắp còn hai khoá phụ (mới nhất trước, rồi Id) để thứ tự ổn định. Rất nhiều chiến dịch cùng chi phí 0; thứ tự nhập nhằng làm một dòng hiện ở hai trang liền nhau còn dòng khác biến mất.

Gắn số liệu gộp cho các chiến dịch của trang vừa phân trang (plan §3.6): một truy vấn AdsMetricDaily cấp chiến dịch cho cả trang rồi gộp trong bộ nhớ bằng đúng mà report/overview dùng — nên tổng cột của mọi trang cộng lại bằng thẻ KPI cùng bộ lọc (test đối chiếu AdsCampaignSearchMetricsTests). Không truyền khoảng ngày thì không đụng bảng số liệu: các chỗ gọi search chỉ để đếm hay lấy danh sách (thanh trạng thái, ô chọn) không phải trả giá cho cột mình không dùng.

Đọc một mốc ngày từ PredicateObject. Chỉ nhận đúng yyyy-MM-dd (giao diện gửi từ store ngữ cảnh); giá trị lạ thì báo lỗi rõ thay vì lặng lẽ bỏ qua hay đoán — bảng trống số liệu vì một ngày sai định dạng là lỗi rất khó nhìn ra, còn "01/08/2026" mà đoán thành ngày 8 tháng 1 thì bảng vẫn có số và không ai nghi ngờ.

Lưu danh sách nhóm kèm mẫu quảng cáo và targeting. Trả về kết quả lỗi khi có vấn đề, null nghĩa là thành công.

Gắn các mẫu quảng cáo vào nhóm dưới dạng bản ghi AdsItem chưa publish.

Lưu targeting của nhóm. Mỗi nhóm chỉ có một bản ghi targeting.

Cột số liệu mà lưới chiến dịch sắp xếp được. Số liệu nằm ở AdsMetricDaily chứ không phải trên entity, nên sắp theo các cột này phải gộp trước khi phân trang — xem AdsCampaignService.SearchByMetricSortAsync.

Chi phí — tổng Cost trong khoảng ngày

Lượt hiển thị — tổng Impressions

Lượt nhấp — tổng Clicks

CTR — tổng Clicks / tổng Impressions, không phải trung bình CTR từng ngày

CPC trung bình — tổng Cost / tổng Clicks

Chuyển đổi — tổng Conversions

Đọc yêu cầu sắp xếp của lưới chiến dịch. Thuần logic — không chạm database. Có hai họ cột và chúng đi hai đường khác nhau: cột của chính chiến dịch (tên, ngân sách, trạng thái...) sắp được ngay trên truy vấn entity, còn cột số liệu phải gộp AdsMetricDaily theo khoảng ngày rồi mới sắp. Vì sao phải lọc danh sách trắng: khoá sắp xếp đi trên URL của trang danh sách nên người dùng sửa tay được. OrderByName ném khi tên trường không có thật — nghĩa là một URL gõ nhầm sẽ thành lỗi 500 chứ không phải một bảng sắp theo mặc định.

Sắp mặc định khi không yêu cầu gì, hoặc khi yêu cầu không hợp lệ: mới nhất trước.

Khoá cột trên lưới → chỉ số cần gộp. Khoá trùng đúng key của cột trong campaigns/index.vue để không phải dịch tên ở giữa hai đầu.

Trường của entity AdsCampaign cho phép sắp. So sánh không phân biệt hoa thường nhưng luôn trả về tên chuẩn trong tập này: OrderByName tra property phân biệt hoa thường, nên trả lại nguyên chuỗi người dùng gửi là mở đường cho đúng lỗi 500 ở trên.

Cột số liệu tương ứng, hoặc null nếu yêu cầu không phải cột số liệu.

Yêu cầu sắp xếp trên chính entity, đã chuẩn hoá: tên ngoài danh sách trắng (kể cả tên cột số liệu khi bảng không có khoảng ngày để gộp) rơi về sắp mặc định.

Sắp truy vấn chiến dịch theo một chỉ số gộp từ bằng truy vấn con tương quan — không gộp sẵn rồi nối trái, vì EF Core không dịch nổi một projection của GroupBy ở vế trong của phép nối (đã cắn: "The LINQ expression … could not be translated"). Ca dịch được kiểm bằng ToQueryString() trong AdsCampaignSortSqlTests: repository giả trong bộ nhớ của các test khác chạy được cả những truy vấn mà SQL Server không dịch nổi, nên nó KHÔNG chứng minh được điều này. CTR và CPC tính lại tại chỗ từ tổng, đúng công thức — không đọc cột Ctr/Cpc của từng dòng ngày (chúng là tỉ lệ của riêng ngày đó). Mẫu số 0 trả 0 như SafeRatio/SafeDivide. Chỗ này KHÔNG làm tròn như bên đó: làm tròn chỉ đổi được thứ tự của hai giá trị vốn đã bằng nhau sau khi làm tròn, mà thứ tự của chúng đã do hai khoá phụ quyết định. Hai khoá phụ (mới nhất trước, rồi Id) là bắt buộc: rất nhiều chiến dịch cùng chi phí 0, thứ tự nhập nhằng làm một dòng hiện ở hai trang liền nhau còn dòng khác biến mất.

Quản lý kết nối tới nền tảng quảng cáo: CRUD, luồng OAuth, kiểm tra kết nối. Credentials do người dùng nhập ở trang cấu hình, không đọc từ appsettings.

Năng lực của một nền tảng — UI render form credential từ đây

Năng lực của mọi nền tảng đã khai báo adapter

Tạo URL cấp quyền OAuth cho một kết nối

Xử lý callback OAuth: kiểm tra state, đổi code lấy token, lưu vào kết nối.

Kiểm tra kết nối bằng một lệnh gọi nhẹ tới nền tảng

Lấy entity kèm credential gốc — chỉ dùng nội bộ backend, không trả ra API

Kết quả tạo URL cấp quyền.

Danh sách field còn thiếu để UI highlight đúng ô nhập

Chuỗi bí mật dùng ký tham số state của OAuth (chống CSRF)

Chuỗi state = "{connectionId}.{chữ ký HMAC}". Chỉ callback do LADA khởi tạo mới ký đúng.

Giá trị mật gửi lên có chứa *** nghĩa là client trả lại chuỗi đã che → không ghi vào DB.

Quản lý mẫu quảng cáo (creative) và cầu nối từ nội dung website sang quảng cáo. Mọi giới hạn ký tự đều đọc từ của nền tảng đích — tuyệt đối không hard-code 30/90 ở đây, vì Google có thể đổi và mỗi nền tảng một con số.

Kiểm tra mẫu theo giới hạn của nền tảng. Gọi được cả khi chưa lưu (form gọi realtime).

Giới hạn mẫu quảng cáo của một nền tảng — form đếm ký tự theo object này

Gợi ý mẫu quảng cáo từ nội dung AI Marketing. Chỉ nhận nội dung đã duyệt (Approved / Published) — không quảng cáo bản nháp chưa ai đọc.

Gợi ý mẫu quảng cáo từ bài viết CMS. Final URL dựng từ slug của bài nếu không truyền vào.

Rút gọn một đoạn text cho vừa giới hạn ký tự, cắt theo ranh giới từ. Không bao giờ cắt âm thầm — kết quả luôn kèm cờ .

Lấy entity kèm quan hệ — dùng nội bộ backend khi publish

Kết quả tạo gợi ý mẫu quảng cáo từ nội dung nguồn.

Gợi ý để wizard hiển thị (luôn có khi thành công)

Id mẫu đã lưu — chỉ có khi SaveAsCreative = true

Khoá cấu hình domain website — dùng dựng Final URL cho bài viết CMS

Domain mặc định khi cấu hình chưa khai

Lưu gợi ý thành mẫu nếu người dùng yêu cầu, đồng thời trả gợi ý cho wizard hiển thị.

Bổ sung ghi chú khi số lượng gợi ý chưa đủ mức tối thiểu của nền tảng, hoặc có đoạn text phải rút gọn — để người dùng biết chỗ cần sửa tay.

Tiêu đề nguồn: tiêu đề nội dung + các câu ngắn tách ra từ phần mô tả ngắn.

Mô tả nguồn: meta description, mô tả ngắn, rồi các câu đầu của nội dung chính.

Cắt text tại ranh giới từ gần nhất trước giới hạn. Cắt giữa từ tiếng Việt ra chuỗi vô nghĩa nên thà bỏ cả từ cuối; nếu từ đầu tiên đã dài quá giới hạn thì mới cắt cứng.

Tách một đoạn văn thành các câu, bỏ câu quá ngắn (không dùng làm tiêu đề được).

Bỏ thẻ HTML để lấy text thuần từ nội dung bài viết.

Dựng URL bài viết từ slug và domain trong cấu hình.

Tên mẫu bị giới hạn 500 ký tự trong DB

Đọc nhóm quảng cáo và các quảng cáo bên trong nó. Service này chỉ đọc. Bật/tắt một quảng cáo hay một nhóm là thao tác tiêu tiền và đã có sẵn ở (endpoint api/ads/campaign/ad/{adId}/status và api/ads/campaign/group/{groupId}/status, quyền Ads.Publish) — cố ý không làm lại ở đây để chỉ có một đường ghi. Quảng cáo có = null là quảng cáo đồng bộ về từ nền tảng, LADA không quản mẫu của nó. Đó là dữ liệu chỉ đọc hợp lệ, không phải bản ghi thiếu dữ liệu — UI phải hiển thị khác đi chứ không báo lỗi.

Tìm kiếm nhóm quảng cáo có phân trang.

Chi tiết một nhóm: thông tin nhóm (kèm 3 số đếm con), bối cảnh chiến dịch / tài khoản, và năng lực nền tảng để UI biết ẩn tab nào.

Danh sách quảng cáo trong một nhóm, kèm số liệu gộp trong khoảng ngày (mặc định 30 ngày gần nhất).

Số liệu tổng hợp của nhóm trong khoảng ngày.

Điền 3 số đếm con (AdCount, KeywordCount, NegativeKeywordCount) cho một danh sách nhóm bằng hai truy vấn gộp, không phải mỗi nhóm một truy vấn. AutoMapper không map được các số này (entity không mang sẵn) nên chúng mặc định là 0. Mọi chỗ trả ra UI phải gọi hàm này, nếu không bảng sẽ hiện "0 quảng cáo" cho nhóm thật ra có quảng cáo — sai theo hướng người dùng tin luôn.

Điền tên chiến dịch / tài khoản / chiến lược thầu cho trang hiện tại. Chạy SAU khi đã cắt trang (cùng nếp với số liệu chiến dịch ở plan §3.6): join trước phân trang thì trần 149 nhóm hôm nay không sao, nhưng luật sẽ sai ngay khi số nhóm lớn lên. Một truy vấn cho cả trang, không phải mỗi dòng một lượt.

Một việc cần xử lý trước khi trừ bỏ qua — đơn vị nhỏ nhất, gắn với đúng một bản ghi.

Băm nội dung việc — so với AdsIssueDismissal.Fingerprint để biết bỏ qua còn đúng không

Riêng lệch lịch: số khung theo Kind, để đặt tiêu đề nhóm cho đúng nghĩa

Dữ liệu đầu vào đã tải sẵn — classifier là hàm thuần, không chạm repository

Mọi tài khoản chưa xoá — dùng cả để tra tên cho chiến dịch, nên KHÔNG lọc trước

Chiến dịch đang Failed hoặc OutOfSync, đã lọc ở SQL theo nền tảng / tài khoản (rẻ hơn tải hết) — classifier không lọc lại danh sách này.

max(AdsMetricDaily.Date) cấp chiến dịch trong phạm vi lọc; null = chưa có dòng nào

Có chiến dịch nào đã đẩy lên nền tảng trong phạm vi lọc — chưa có thì "chưa có số liệu" là đương nhiên, không phải việc

Bộ lọc áp cho kết nối / tài khoản / số liệu (chiến dịch đã lọc ở SQL)

Phân loại "việc cần xử lý" của phân hệ quảng cáo thành 6 loại (plan §3.4) và gộp theo loại. Hàm thuần, tách khỏi để test bằng dữ liệu giả không cần repository — cùng lý do với AdsScheduleDiff. Cột AdsCampaign.OutOfSyncDetailJson không có schema cố định: reconcile lịch ghi mảng , còn đồng bộ chiến dịch / sửa tay ghi mảng — hai luồng ghi đè nhau. Vì vậy lệch lịch bắt theo có Window, lệch trường theo có Field; không so tên Kind — Việc 0 GĐ C đo được cả 3 giá trị của trong dữ liệu thật, mà plan ban đầu chỉ ghi một.

Tài khoản đang bật mà quá ngần này ngày chưa kéo lại từ nền tảng

Số liệu mới nhất cũ hơn hôm nay − ngần này ngày thì báo (cùng ngưỡng với thanh ngữ cảnh)

EntityId cố định của việc mức hệ thống "số liệu cũ"

Liệt kê mọi việc trong phạm vi lọc, chưa trừ bỏ qua

Gộp các mục đang hiện của một loại thành một dòng panel

Thứ tự hiện: lỗi trước cảnh báo, trong cùng mức thì theo số của loại

SHA-256 rút gọn còn 32 ký tự hex — đủ để phát hiện nội dung đổi, ngắn để làm cột index

Guid chiến dịch ở dạng chuỗi chuẩn (chữ thường, có gạch) để so khớp ổn định

Chuẩn hoá Id client gửi lên về đúng dạng classifier sinh ra

Thông điệp lỗi nền tảng thường kèm request-id / thời điểm / số lần thử khác nhau mỗi lần gọi; băm nguyên văn thì bỏ qua vô hiệu ngay lần probe kế tiếp dù lỗi không đổi. Xoá các cụm số / hex dài trước khi băm.

Nhãn [Description] của trạng thái kết nối, kèm việc phải làm khi token hết hạn

Tên nền tảng ([Description]) khi cả nhóm cùng một nền tảng; lẫn lộn hoặc chưa rõ thì nói chung "nền tảng"

Đọc OutOfSyncDetailJson bao dung: mảng gốc, phần tử có Window là (reconcile lịch ghi), có Field là (đồng bộ chiến dịch ghi); JSON hỏng thì Readable = false chứ không ném.

"Việc cần xử lý" của phân hệ quảng cáo: liệt kê đã gộp theo loại, bỏ qua có thời hạn, hiện lại. Phân loại nằm ở (hàm thuần); lớp này chỉ tải dữ liệu, trừ các mục đã bỏ qua còn hạn và khớp fingerprint, rồi gộp. Bỏ qua không chạm AdsCampaign hay dữ liệu đồng bộ nào (plan §1.3) — chỉ ghi AdsIssueDismissal. Một mục = một dòng AdsIssueDismissal suốt đời: bỏ qua lại thì cập nhật dòng cũ, hiện lại thì đặt ExpiresAt = now (không xoá mềm — hết hạn đã là cơ chế tắt, chồng thêm xoá mềm chỉ làm bảng mọc theo số lần bấm và làm mất lịch sử ai bỏ qua / ai hiện lại trên cùng dòng).

Mọi loại việc còn mục (đang hiện hoặc đang bị bỏ qua), sắp lỗi trước cảnh báo. Lọc theo nền tảng / tài khoản là tuỳ chọn; bỏ trống = toàn hệ thống.

Bỏ qua một lô mục cùng loại trong N ngày. Hàng rào plan §3.9: từng Id phải là một việc đang tồn tại đúng loại — có Id lạ là từ chối cả lô, không âm thầm bỏ phần lạ.

Hiện lại các mục đã bỏ qua của một loại — bỏ trống Id = hiện lại tất cả

Số mục đã bỏ qua / hiện lại

Trần Id mỗi lời gọi bỏ qua / hiện lại — cùng con số với các endpoint nhận danh sách Id khác (§3.9)

Hạn bỏ qua mặc định (Q1)

Bỏ trống = giờ hệ thống. Test truyền giờ cố định để các ngưỡng "quá 7 ngày" / "quá 3 ngày" không phụ thuộc lúc chạy.

Nguồn dữ liệu cho liệt kê: kết nối + tài khoản (tải hết, vài chục dòng), chiến dịch có việc lọc ở SQL, mốc số liệu.

Nguồn dữ liệu cho bỏ qua: toàn hệ thống nhưng chỉ phần loại này cần — bỏ qua một kết nối không cần tải 80 chiến dịch kèm JSON, bỏ qua chiến dịch chỉ cần đúng các Id gửi lên.

Có chiến dịch nào đã đẩy lên nền tảng chưa — chưa có thì "chưa có số liệu" là chuyện đương nhiên, không phải việc

Cùng phạm vi với report/metrics-status: chỉ cấp chiến dịch, cùng bộ lọc nền tảng / tài khoản

Bỏ qua còn hạn, khoá bộ ba → fingerprint. Trùng khoá (hai request bỏ qua đồng thời) thì lấy bản gần nhất.

Một từ khoá ở dạng thuần dữ liệu, không phụ thuộc EF hay SDK Google. Dùng cho cả hai phía của phép so sánh: bên LADA (trạng thái mong muốn) và bên nền tảng (trạng thái đang có, đọc về từ FetchKeywordsAsync). Tách khỏi entity để logic diff test được mà không cần DB lẫn Google.

Id dòng bên LADA. null với từ khoá chỉ tồn tại trên nền tảng.

Criterion id bên nền tảng, dạng id trần. null = bản nháp chưa đẩy lên.

Cấp của từ khoá — chỉ nhận Campaign hoặc Group

Là từ khoá phủ định (loại trừ) hay từ khoá thường (nhắm chọn)

Nội dung từ khoá, không kèm dấu ngoặc biểu thị kiểu khớp

Kiểu khớp

Giá thầu CPC riêng của từ khoá. null = dùng giá thầu của nhóm. Khác hẳn 0 — 0 là một con số có nghĩa và Google từ chối nó.

Nội dung đã chuẩn hoá để so sánh: bỏ khoảng trắng đầu/cuối, gộp khoảng trắng liên tiếp, hạ chữ thường. Google không phân biệt chữ hoa/thường trong từ khoá: thêm "Giày Nam" khi đã có "giày nam" sẽ bị nền tảng từ chối vì trùng. So sánh không chuẩn hoá thì LADA tưởng là từ khoá mới và cả lô mutate bị Google trả lỗi.

Số từ trong từ khoá (Google giới hạn 10 từ)

Danh tính của từ khoá trên nền tảng. Google không cho sửa text lẫn match_type của một criterion đã tạo — hai thứ đó chính là danh tính của nó: đổi chữ hoặc đổi kiểu khớp = criterion khác, phải xoá cái cũ rồi tạo cái mới. Cùng một tính chất bất biến như khung giờ của lịch chạy. Cố ý không đưa nhóm/chiến dịch vào khoá: mỗi lần diff chỉ xử lý một phạm vi (một nhóm, hoặc phủ định cấp chiến dịch của một chiến dịch). Đưa vào sẽ làm mọi phép so hỏng, vì phía LADA biết id nhóm nội bộ còn phía nền tảng biết id nhóm bên đó.

Nhãn tiếng Việt, hiển thị nguyên văn trên hộp xác nhận và thông báo lỗi

Loại thao tác cần thực hiện trên nền tảng

Tạo criterion mới

Cập nhật giá thầu của criterion đã có (text/kiểu khớp không sửa được)

Xoá criterion

Một thao tác trong bản diff từ khoá. Có mô tả tiếng Việt sẵn để hộp xác nhận trên UI không phải tự dựng câu — nói sai việc sắp làm là nguyên nhân tiêu tiền oan.

Loại thao tác

Nhãn loại thao tác cho UI

Id dòng bên LADA (nếu có)

Criterion id bên nền tảng — bắt buộc với Update/Remove

Từ khoá liên quan

Khoá danh tính, dùng để gắn criterion id nền tảng trả về vào đúng dòng LADA. Gắn lệch một dòng thì lần đẩy sau sẽ sửa/xoá sai từ khoá.

Giá thầu sẽ ghi. null nghĩa là xoá giá thầu riêng, quay về giá thầu nhóm.

Có gán giá trị cpc_bid_micros lên object gửi đi hay không. false + mask có cpc_bid_micros = yêu cầu Google xoá giá thầu riêng.

Các đường dẫn field mask cần gửi kèm khi Update. Dựng tay, không dùng FieldMasks.AllSetFieldsOf(): proto3 coi field chưa set và 0 là như nhau nên helper đó sẽ bỏ cpc_bid_micros khỏi mask, khiến "xoá giá thầu riêng" biến thành không làm gì. Cùng cái bẫy đã ghi ở AdsScheduleOperation.

Giá thầu hiện có trên nền tảng — chỉ có nghĩa với Update

Mô tả tiếng Việt của thao tác, hiển thị nguyên văn trên hộp xác nhận

Kết quả so sánh từ khoá LADA với từ khoá trên nền tảng.

Các lỗi dữ liệu phát hiện trước khi gọi nền tảng (tiếng Việt)

Không có lỗi nào

Từ khoá cần tạo mới trên nền tảng

Từ khoá chỉ đổi giá thầu

Từ khoá cần xoá khỏi nền tảng

Từ khoá hai bên đã giống nhau — không sinh thao tác nào

Tổng số thao tác sẽ gửi lên nền tảng

Có việc phải làm hay không. Không có thì tuyệt đối đừng gọi ra nền tảng.

Số từ khoá phủ định sắp bị xoá. UI dùng con số này để nâng mức ma sát: xoá từ khoá phủ định là mở cửa cho truy vấn rác, tiền chảy ra ngay mà không có gì báo.

Toàn bộ thao tác theo thứ tự gửi: xoá trước, rồi tạo, rồi cập nhật

Mô tả tiếng Việt từng thao tác, đúng thứ tự gửi

Câu tóm tắt cho tiêu đề hộp xác nhận

So sánh từ khoá giữa LADA và nền tảng, sinh danh sách thao tác cần ghi. Toàn bộ lớp này là logic thuần: không chạm DB, không chạm SDK Google. Nhờ vậy phần dễ sai nhất của luồng ghi được test đầy đủ trước khi có bất kỳ lệnh gọi ra ngoài. Quy tắc ánh xạ: text và match_type của criterion là bất biến — đổi một trong hai phải xoá rồi tạo lại; chỉ cpc_bid_micros là sửa được tại chỗ. Xem https://developers.google.com/google-ads/api/fields/v21/ad_group_criterion Mỗi lần gọi chỉ xử lý một phạm vi: từ khoá của một nhóm, hoặc từ khoá phủ định cấp chiến dịch của một chiến dịch. Trộn nhiều nhóm vào cùng một lần diff sẽ khiến từ khoá trùng tên ở hai nhóm bị coi là một.

Độ dài tối đa của một từ khoá (ký tự). Nguồn: giới hạn Google Ads cho keyword text. Cột AdsKeyword.Text để 200 ký tự để còn chỗ cho nền tảng khác nới rộng hơn.

Số từ tối đa trong một từ khoá. Nguồn: giới hạn Google Ads cho keyword text.

Tên field cpc_bid_micros trong field mask của Google

Các ký tự dùng để viết kiểu khớp, không phải phần nội dung từ khoá: [từ khoá] = khớp chính xác, "từ khoá" = khớp cụm từ. Người dùng gõ kèm dấu này vào ô nội dung thì kiểu khớp bị nói hai lần và lệch nhau — bắt lỗi ngay thay vì đẩy lên rồi mới biết.

Nhãn tiếng Việt của kiểu khớp — dùng trong nhãn và mô tả thao tác

Kiểm tra tính hợp lệ của danh sách từ khoá mong muốn trước khi so sánh.

Từ khoá mong muốn — các dòng trong LADA Giới hạn số từ khoá của nền tảng (CreativeLimits.MaxKeywordsPerGroup). 0 = không áp dụng. Đọc từ Capabilities, không hard-code vào đây. Danh sách lỗi tiếng Việt; rỗng nghĩa là hợp lệ.

Tìm từ khoá trùng nhau (cùng nội dung + cùng kiểu khớp + cùng cấp + cùng loại). Nền tảng từ chối cả lô mutate khi có trùng, nên phải bắt trước và nói rõ trùng ở đâu.

So sánh hai phía và sinh thao tác, không kiểm tra hợp lệ. Dùng khi cần biết diff thuần (ví dụ test phân biệt giá thầu null với 0).

Từ khoá mong muốn — các dòng trong LADA Từ khoá đang có trên nền tảng, vừa đọc về

Kiểm tra hợp lệ rồi so sánh. Có lỗi thì trả về bản diff rỗng kèm lỗi — không bao giờ trả thao tác dựa trên dữ liệu đã biết là sai.

Phần đuôi nói rõ phạm vi ảnh hưởng. Chỉ ghi với cấp chiến dịch, vì đó là chỗ dễ hiểu nhầm nhất: một dòng ở đây áp cho mọi nhóm trong chiến dịch.

Phần đuôi mô tả giá thầu, bỏ hẳn khi dùng giá thầu của nhóm

Hiển thị giá thầu; không có giá thầu riêng thì nói rõ là theo nhóm, không in "0"

Từ khoá và từ khoá phủ định của chiến dịch / nhóm quảng cáo. Một dòng ánh xạ 1-1 với một criterion kiểu KEYWORD bên nền tảng, khớp theo ExternalId (criterion id trần). Luồng ghi cố ý chia làm ba bước tách biệt, vì đổi từ khoá là đổi cấu hình đang tiêu tiền: (1) sửa bản nháp trong LADA (, , ) — không gọi ra nền tảng; (2) xem trước () — tính diff rồi nhờ nền tảng kiểm tra bằng validate_only, không ghi gì; (3) đẩy thật () — ghi rồi đọc lại để xác nhận. Mỗi lần đẩy chỉ xử lý một phạm vi: từ khoá của một nhóm, hoặc từ khoá phủ định cấp chiến dịch của một chiến dịch. Trộn hai phạm vi vào một lô sẽ khiến từ khoá trùng nội dung ở hai nhóm bị coi là một, và làm mô tả trên hộp xác nhận nói sai phạm vi ảnh hưởng. Từ khoá phủ định nằm trong danh sách dùng chung của nền tảng (Google shared set) không được LADA đọc về. Chúng vẫn có tác dụng thật, nên UI phải hiện thay vì để người dùng tưởng danh sách đã đủ.

Tìm kiếm từ khoá có phân trang cho bảng danh sách.

Bối cảnh của một phạm vi (nhóm nếu có , ngược lại là chiến dịch) — năng lực nền tảng, trạng thái publish, số đếm — không kèm danh sách. Đây là thứ màn hình danh sách phải gọi, cặp với phân trang. Mọi con số tính bằng câu đếm gộp dưới DB, không đọc dòng nào lên bộ nhớ.

Từ khoá trong phạm vi một chiến dịch: phần phủ định là phủ định cấp chiến dịch, phần thường là tổng hợp từ khoá của mọi nhóm bên trong (chỉ đọc). Trả về toàn bộ dòng, không phân trang — chỉ dùng cho luồng cần đủ dữ liệu để tính diff. Màn hình danh sách phải dùng + .

Từ khoá trong phạm vi một nhóm. Phần phủ định chỉ gồm phủ định của riêng nhóm — phủ định cấp chiến dịch nằm ở trang chiến dịch, không trộn vào đây để không ai tưởng xoá ở nhóm này là hết ảnh hưởng. Trả về toàn bộ dòng, không phân trang — xem ghi chú ở .

Kéo từ khoá từ nền tảng về cho một chiến dịch (cả phủ định cấp chiến dịch và từ khoá của mọi nhóm đã đồng bộ): upsert theo ExternalId, soft-delete các dòng nền tảng không còn trả về.

Tạo / sửa một từ khoá trong LADA. Không gọi ra nền tảng. Validate qua trên toàn bộ phạm vi sau khi áp thay đổi, nên từ khoá trùng bị chặn ngay lúc lưu nháp chứ không đợi nền tảng từ chối cả lô.

Thêm nhiều từ khoá một lần bằng danh sách dán vào trong LADA. Không gọi ra nền tảng. Dòng trắng bị bỏ, dòng trùng nhau bị gộp và báo rõ số lượng đã gộp.

Xoá một từ khoá trong LADA (soft-delete). Không gọi ra nền tảng. Dòng đã có ExternalId thì bên nền tảng vẫn còn từ khoá đó cho tới khi đẩy lên — sẽ liệt kê nó ở nhóm "Xoá". Với từ khoá phủ định, đây chính là chỗ dễ hiểu nhầm nhất: xoá trong LADA chưa mở cửa cho traffic rác, bấm đẩy mới mở.

Xem trước những gì sẽ ghi lên nền tảng cho một phạm vi: đọc từ khoá hiện tại từ nền tảng, so với LADA, rồi gửi cả lô ở chế độ validate_only. Không ghi bất cứ thứ gì lên tài khoản quảng cáo.

Chiến dịch chứa phạm vi Nhóm cần áp. null = áp từ khoá phủ định cấp chiến dịch.

Đẩy từ khoá lên nền tảng thật. Việc này tiêu tiền: thêm từ khoá là mở thêm đường hiển thị, xoá từ khoá phủ định là mở cửa cho truy vấn rác — cả hai đều có hiệu lực ngay. Sau khi ghi xong luôn gọi lại để đọc lại — request thành công không đồng nghĩa dữ liệu đúng, chỉ đọc lại mới chắc.

Kết quả một lần đồng bộ từ khoá từ nền tảng về.

Số từ khoá mới thêm

Số từ khoá đã cập nhật

Số từ khoá bị bỏ (nền tảng không còn trả về)

Số từ khoá nền tảng trả về nhưng nhóm cha chưa có trong LADA nên bị bỏ qua. Đếm riêng và nói rõ trong thông báo — im lặng thì người dùng tưởng danh sách đã đủ.

Tổng số dòng nền tảng trả về

Kết quả một lần xem trước / đẩy từ khoá lên nền tảng. Luôn trả kèm để hộp xác nhận trên UI nói đúng sẽ đổi gì — nói sai việc sắp làm là nguyên nhân tiêu tiền oan.

Đây là lần chạy thử (validate_only) chứ không phải ghi thật

Có thay đổi nào cần đẩy lên hay không

Câu tóm tắt: sẽ thêm mấy, đổi giá thầu mấy, xoá mấy từ khoá

Mô tả tiếng Việt từng thao tác, đúng thứ tự sẽ gửi lên nền tảng

Lỗi dữ liệu phát hiện trước khi gọi nền tảng (trùng, quá dài, quá nhiều từ…)

Nền tảng đã kiểm tra và chấp nhận lô thay đổi này

Mã lỗi gốc của nền tảng — giữ nguyên để tra tài liệu

Số từ khoá phủ định trong lô sắp xoá. UI dùng để nâng mức ma sát của hộp xác nhận: xoá phủ định là mở cửa cho truy vấn rác, tiền chảy ra ngay mà không có gì báo.

Phạm vi của lô: tên nhóm, hoặc "cấp chiến dịch". Hiện nguyên văn trên hộp xác nhận để người bấm biết chắc mình đang đổi chỗ nào.

Từ khoá đọc lại từ nền tảng sau khi ghi. Đây là sự thật, không phải payload đã gửi.

Ghi chú cố định về danh sách phủ định dùng chung. Hiện luôn trên tab từ khoá phủ định: LADA không đọc shared set nên danh sách ở đây có thể chưa đủ, và người dùng không được tưởng ngược lại.

Phần bối cảnh dùng chung: định danh phạm vi, năng lực nền tảng, trạng thái publish. Năng lực đọc từ Capabilities chứ không để frontend tự đoán — nền tảng không có khái niệm từ khoá thì UI ẩn hẳn tab, không hiện tab rỗng. Cố ý không đụng tới số đếm: nơi gọi tự tính, hoặc bằng câu đếm gộp (), hoặc từ danh sách đã có sẵn ().

Dựng bọc dữ liệu đầy đủ cho luồng cần cả danh sách: bối cảnh + mọi dòng của phạm vi.

Vô hiệu hoá ký tự đại diện của LIKE trong chuỗi người dùng gõ, để tìm "50%" ra đúng "50%" chứ không thành khớp mọi thứ bắt đầu bằng "50".

Chép dữ liệu nền tảng vào entity. = true thì chỉ nhận về các field do nền tảng quyết định (trạng thái duyệt, điểm chất lượng, id) và ghi chỗ lệch vào OutOfSyncDetailJson; nội dung người dùng đang soạn được giữ nguyên.

Ghi lại chỗ lệch giữa LADA và nền tảng để UI chỉ đúng field nào khác nhau. JSON hỏng thì trả null — một bản ghi lỗi không được làm sập cả lần đồng bộ.

Một đường code duy nhất cho cả xem trước và ghi thật — hai đường song song sẽ lệch nhau, và chỗ lệch nằm đúng trên đường tiêu tiền.

Chiến dịch kèm tài khoản và kết nối — cần cả ba để gọi ra nền tảng.

Toàn bộ từ khoá của một phạm vi: cả nhắm mục tiêu và phủ định của một nhóm, hoặc từ khoá phủ định cấp chiến dịch. Hai loại nằm cùng một resource bên nền tảng nên phải cùng một lô — tách ra sẽ khiến diff của lô này coi dòng của lô kia là "cần xoá".

Danh sách từ khoá của phạm vi để trả về UI sau khi ghi — đọc lại từ DB chứ không dựng từ payload đã gửi.

Kiểm tra phạm vi hợp lệ: nhóm có tồn tại, thuộc đúng chiến dịch, và cấp chiến dịch chỉ nhận từ khoá phủ định.

Nền tảng có khái niệm từ khoá / phủ định / phủ định cấp chiến dịch hay không. Thiếu năng lực thì báo lý do tiếng Việt, không im lặng lưu một dòng vô nghĩa.

Giới hạn số từ khoá để đưa vào validate. Chỉ áp cho phạm vi nhóm: giới hạn của nền tảng là giới hạn mỗi nhóm, đem áp cho danh sách phủ định cấp chiến dịch sẽ báo lỗi sai chỗ. Trả 0 = không kiểm số lượng.

Entity sang một dòng để so sánh — nơi duy nhất quyết định cách chuẩn hoá.

Dòng so sánh cho một từ khoá chưa có trong DB.

Dựng entity mới cho một từ khoá nháp. và được gán tường minh: mặc định của entity là "Rộng" còn mặc định của model là "Cụm từ", để trống ở đây sẽ lưu kiểu khớp khác cái người dùng chọn.

Đánh dấu dòng đã lệch với nền tảng sau khi sửa trong LADA. Dòng chưa từng lên nền tảng vẫn là nháp () — gọi nó là "lệch" sẽ khiến người dùng tưởng nền tảng đang chạy một giá trị khác.

Đánh dấu dòng đã khớp nền tảng sau khi ghi thành công.

Ghi lý do lỗi vào từng dòng trong phạm vi để người dùng thấy ngay trên bảng, không phải mở log mới biết vì sao lần đẩy vừa rồi không có tác dụng.

Nội dung request để lưu log: đủ để sau này dựng lại chính xác đã gửi gì lên nền tảng. Serialize lỗi thì trả bản tối giản chứ không để trống — mất log là mất khả năng truy vết một lần ghi đã tiêu tiền.

Ghi một dòng log gọi nền tảng. Mọi payload đi qua nên token được che trước khi lưu.

Gộp số liệu quảng cáo theo ngày thành một bản tổng hợp. Thuần logic — không chạm database, không chạm SDK nền tảng — nên gọi được trực tiếp từ unit test. Tách ra khỏi vì công thức này giờ có ba nơi dùng: tổng hợp cấp chiến dịch, số liệu từng quảng cáo trong nhóm, và số liệu từng từ khoá. Chép công thức ra ba chỗ là cách chắc chắn để ba chỗ lệch nhau sau vài lần sửa. Nguyên tắc không được phá: mọi chỉ số dạng tỉ lệ (CTR, CPC, CPA, ROAS) đều tính lại từ tổng của tử số và tổng của mẫu số. Lấy trung bình cột tỉ lệ của từng ngày cho ra số khác hẳn khi lượng hiển thị các ngày lệch nhau — và sai theo hướng khó phát hiện, vì con số vẫn "trông hợp lý".

Gộp danh sách dòng số liệu theo ngày thành một bản tổng hợp cho khoảng [from, to]. Trả null khi không có dòng nào — "chưa có dữ liệu" khác hẳn "có dữ liệu và bằng 0", nên không trả về một bản tổng hợp toàn số 0.

Gộp số liệu cho nhiều đối tượng cùng lúc, trả về map theo EntityId. Dùng cho bảng danh sách (từng quảng cáo, từng từ khoá): một truy vấn cho cả trang rồi gộp trong bộ nhớ, thay vì gọi GetSummaryAsync mỗi dòng — 500 từ khoá là 500 lượt truy vấn. Đối tượng không có dòng số liệu nào không xuất hiện trong map. Chỗ gọi dùng TryGetValue và để Metrics = null, giữ đúng phân biệt "chưa có dữ liệu".

Chia an toàn cho tỉ lệ dạng số nguyên / số nguyên. Mẫu số 0 trả 0 chứ không ném lỗi: một từ khoá chưa có lượt hiển thị là chuyện bình thường, không phải lỗi dữ liệu.

Chia an toàn cho chi phí / số lượt. Mẫu số 0 trả 0.

Các mã tiền tệ khác nhau xuất hiện trong tập số liệu (bỏ qua giá trị rỗng).

Đồng bộ và tổng hợp số liệu quảng cáo theo ngày. Job đồng bộ sẽ chạy lại trên cùng khoảng ngày nên mọi thao tác ghi đều là upsert theo khoá (Level, EntityId, Date) — chạy 10 lần vẫn ra đúng một bản ghi mỗi ngày.

Kéo số liệu của một tài khoản trong khoảng ngày về LADA ở cấp .

Số liệu tổng hợp của một đối tượng canonical trong khoảng ngày. Trả null khi chưa có dữ liệu nào — UI hiển thị "chưa đồng bộ số liệu" thay vì toàn số 0.

Số liệu tổng hợp của cả một tài khoản quảng cáo ở cấp chiến dịch.

Số liệu tổng quan cho trang chủ phân hệ, kèm kỳ liền trước để so sánh tăng/giảm.

Số liệu đã về tới ngày nào và đồng bộ lần cuối lúc nào — cho thanh ngữ cảnh. Lọc theo nền tảng / tài khoản như các báo cáo khác nhưng KHÔNG theo khoảng ngày.

Chuỗi số liệu theo thời gian để vẽ biểu đồ, gộp theo ngày / tuần / tháng.

Số liệu gộp theo từng nền tảng quảng cáo, sắp giảm dần theo chi phí.

Xếp hạng chiến dịch theo một chỉ số trong khoảng ngày.

Đồng bộ số liệu cho mọi tài khoản đang bật đồng bộ định kỳ. Một tài khoản lỗi không làm hỏng cả lượt — phần lỗi được gom vào thông báo trả về.

Bộ lọc dùng chung cho các truy vấn đọc số liệu tổng hợp.

Null nghĩa là lấy tất cả nền tảng

Null nghĩa là lấy tất cả tài khoản

Số ngày của kỳ, tính cả hai đầu

Luật khoảng ngày chung cho mọi nơi đọc số liệu theo kỳ (báo cáo tổng quan, cột số liệu của bảng chiến dịch…) — một chỗ, một thông điệp. Ném để controller trả 400 kèm lý do người dùng đọc được.

Mức gộp thời gian khi vẽ biểu đồ.

Kết quả một lần đồng bộ số liệu.

Số dòng số liệu mới thêm

Số dòng số liệu đã cập nhật

Số dòng nền tảng trả về nhưng không khớp đối tượng nào trong LADA (thường do chưa đồng bộ chiến dịch / nhóm trước).

Tổng số dòng nền tảng trả về

Bảng tra ExternalId → Id canonical theo cấp số liệu. Cấp lạ thì ném lỗi chứ không trả bảng rỗng: bảng rỗng làm mọi dòng nền tảng trả về rơi vào SkippedCount và báo "đồng bộ thành công 0 bản ghi" — đúng kiểu lỗi im lặng đã từng giấu bug số liệu cấp quảng cáo.

Truy vấn số liệu theo bộ lọc chung. Luôn giới hạn ở cấp chiến dịch: cấp nhóm và cấp quảng cáo là số liệu chi tiết của cùng khoản chi đó, gộp lẫn vào sẽ đội chi phí lên nhiều lần.

Ngày đầu của mốc gộp chứa .

Các mã tiền tệ khác nhau xuất hiện trong tập số liệu (bỏ qua giá trị rỗng).

Tính tổng và các chỉ số dẫn xuất. Công thức nằm ở — thuần logic, không chạm database — để trang nhóm quảng cáo, bảng từ khoá và unit test dùng đúng một công thức. CTR / CPC / CPA / ROAS tính lại từ tổng, không lấy trung bình cột tỉ lệ.

Lấy mô tả tiếng Việt của enum, không ném lỗi khi enum chưa khai báo Description.

Các nút của phân hệ Quảng cáo mà máy chủ gác bằng quyền có được hiện cho một người hay không (rule quyen-hien-thi; plan cải tổ giao diện quảng cáo GĐ B, GĐ C).

Hàm thuần — không chạm database, không đọc HttpContext: nhận danh sách role đã phân giải qua IUserRoleResolver, trả các cờ. Cùng khuôn với , và vì cùng một lý do: luật "ai thấy gì" phải có ca test gọi thẳng vào nó, mà controller thì không test được sạch (User.GetCurrentUser() nuốt mọi ngoại lệ rồi trả UserId = 0). Cờ đọc đúng bó quyền của thứ nó gác. Nút "Đồng bộ" trên thanh ngữ cảnh gọi POST api/ads/report/sync-now, endpoint ấy đòi Ads.Publish (gọi ra nền tảng, tốn quota) — không phải Ads.Search của các lời gọi đọc số liệu quanh nó. Lấy bó Ads.Search làm cờ là cho người chỉ được xem thấy nút, bấm, và ăn 403. Mỗi cờ một bó quyền, không mượn cờ của bó khác: CanSyncMetrics và CanPublish hiện trùng bó Ads.Publish nhưng cố ý tách (một endpoint đổi role thì chỉ một cờ đổi); CanDismissIssues gác "bỏ qua việc cần xử lý" (Ads.Update — chỉ ghi trong LADA); CanSyncAccounts gác "đồng bộ tài khoản" (Ads.Connection — kéo danh sách tài khoản từ kết nối). Ba bó khác nhau cho ba nút cạnh nhau trên cùng một panel.

Vai bỏ qua mọi kiểm tra role của hệ thống — ẩn nút của Founder là dựng hàng rào không có thật.

Role của mọi lời gọi ra nền tảng: report/sync-now, campaign/{id}/publish|pause|resume|budget, schedule/sync-many…

Role sửa dữ liệu trong LADA không chạm nền tảng: issue/dismiss, sửa nháp lịch / từ khoá

Role quản lý kết nối: account/sync/{connectionId}, trang Kết nối

Role đã phân giải qua IUserRoleResolver; null = không có role nào

Cờ hiển thị của phân hệ quảng cáo — mỗi cờ gác đúng một bó quyền (xem )

Cờ hiển thị của phân hệ quảng cáo — mỗi cờ gác đúng một bó quyền (xem )

Điều phối việc đẩy chiến dịch từ LADA lên nền tảng quảng cáo. Đây là service duy nhất trong module có khả năng làm phát sinh chi phí thật, nên: chiến dịch mới luôn tạo ở trạng thái tạm dừng, validate đầy đủ trước khi gọi API, và chặn publish lại khi chiến dịch đang đẩy hoặc đã có ExternalId.

Dựng thông tin cho hộp thoại xác nhận: tài khoản bị trừ tiền, ngân sách, thời gian chạy, ước tính chi phí tối đa, kèm danh sách lỗi/cảnh báo.

Gửi chiến dịch sang nền tảng ở chế độ kiểm tra (dry-run): nền tảng validate toàn bộ nhưng không tạo gì thật. Không tiêu tiền, không tạo rác.

Đẩy chiến dịch lên nền tảng. Tạo ở trạng thái tạm dừng, người dùng tự bật sau.

Đẩy thay đổi (tên, trạng thái, thời gian chạy) của chiến dịch lên nền tảng

Bật / tạm dừng / xoá một đối tượng ở cấp chiến dịch, nhóm hoặc quảng cáo

Bật / tạm dừng nhiều chiến dịch trong một lượt, gọi tuần tự đúng logic của bản lẻ. Chiến dịch đã ở trạng thái đích → bỏ qua chứ không gọi ra nền tảng: gửi lệnh thừa vừa tốn quota vừa làm số "thành công" trông to hơn thật.

Đổi ngân sách theo ngày của một chiến dịch đã có trên nền tảng

Kết quả một lần đẩy dữ liệu ra nền tảng.

Id chiến dịch bên nền tảng (có sau khi publish thành công)

Id ngân sách bên nền tảng

Mã lỗi gốc của nền tảng — giữ nguyên để tra tài liệu

Danh sách lỗi validate trước khi gọi API (tiếng Việt, nói rõ trường nào)

Kết cục của một chiến dịch trong lô đổi trạng thái.

Đã ở trạng thái đích, hoặc chưa đẩy lên nền tảng — không phải lỗi

Kết quả đổi trạng thái của một chiến dịch trong lô.

Kết quả bật / tạm dừng cả lô chiến dịch. là ca lô bị từ chối trước khi chạy (Id lạ, quá trần, rỗng): rỗng, controller trả 400. Cùng khuôn với kéo lịch về hàng loạt.

Lưu ExternalId cho cả 4 cấp (ngân sách, chiến dịch, nhóm, quảng cáo). Thiếu id ở bất kỳ cấp nào thì lần đồng bộ sau sẽ tạo bản ghi trùng, nên phải lưu đủ.

Ghi bản ghi quảng cáo canonical (AdsItem) tương ứng mẫu đã đẩy lên. Upsert theo (nhóm, mẫu) để publish lại không sinh bản ghi trùng.

Cập nhật trạng thái canonical sau khi nền tảng đã nhận — chỉ gọi khi nền tảng trả về thành công, để trạng thái trong LADA không nói dối về những gì đang chạy thật.

Trần Id một lô đổi trạng thái — cùng con số với các endpoint nhận danh sách Id khác (plan §3.9)

Đọc toàn bộ cây dữ liệu cần cho việc publish: chiến dịch, tài khoản, kết nối, nhóm, mẫu quảng cáo, targeting.

Kiểm tra toàn bộ cây theo của nền tảng đích. Mọi con số giới hạn đều lấy từ capabilities — nền tảng khác chỉ cần khai capabilities khác.

Kiểm tra một mẫu quảng cáo theo giới hạn của nền tảng. Trùng logic với về mặt luật, nhưng ở đây đọc từ entity (đã lưu) chứ không từ model form, và gắn tên nhóm vào thông báo để người dùng biết sửa ở đâu.

Chuyển cây canonical thành yêu cầu publish cho adapter. Trạng thái mong muốn luôn là tạm dừng — không có đường nào để tạo chiến dịch đang chạy.

Số ngày chạy tính cả ngày đầu và ngày cuối. Null khi chưa có ngày kết thúc.

Đọc mảng chuỗi lưu dạng JSON. JSON hỏng thì trả rỗng — một bản ghi lỗi không nên làm gãy cả luồng publish, và validate sẽ báo thiếu dữ liệu.

Ghi log lần gọi ra nền tảng. Hướng Push cho mọi thao tác trong service này.

Serialize payload để ghi log. Lỗi serialize không được làm gãy nghiệp vụ.

Cây dữ liệu cần cho một lần publish.

Một nhóm quảng cáo kèm mẫu và targeting đã parse.

Một khung giờ quảng cáo ở dạng thuần dữ liệu, không phụ thuộc EF hay SDK Google. Dùng cho cả hai phía của phép so sánh: bên LADA (trạng thái mong muốn) và bên nền tảng (trạng thái đang có, đọc về từ FetchSchedulesAsync). Tách khỏi entity để logic diff test được mà không cần DB lẫn Google.

Id dòng bên LADA. null với khung giờ chỉ tồn tại trên nền tảng.

Id criterion bên nền tảng. null = bản nháp chưa đẩy lên.

Thứ trong tuần (theo của .NET)

Giờ bắt đầu, 0–23

Phút bắt đầu, chỉ nhận 0/15/30/45

Giờ kết thúc, 1–24 (24 = hết ngày)

Phút kết thúc, chỉ nhận 0/15/30/45

Hệ số điều chỉnh giá thầu theo dạng của Google (1.2 = +20%). null = không điều chỉnh — khác hẳn 0.0 (= -100%).

Mốc phút tính từ đầu ngày của thời điểm bắt đầu — dùng để kiểm tra chồng giờ

Mốc phút tính từ đầu ngày của thời điểm kết thúc

Nhãn tiếng Việt của khung giờ, dùng trong thông báo lỗi và hộp xác nhận

Khoá nhận dạng khung thời gian. Google không cho sửa thứ/giờ của một criterion, nên khung thời gian chính là danh tính của nó: đổi giờ = criterion khác.

Loại thao tác cần thực hiện trên nền tảng

Tạo criterion mới

Cập nhật hệ số giá thầu của criterion đã có

Xoá criterion

Một thao tác trong bản diff. Có mô tả tiếng Việt sẵn để hộp xác nhận trên UI không phải tự dựng câu — nói sai việc sắp làm là nguyên nhân tiêu tiền oan.

Loại thao tác

Nhãn loại thao tác cho UI

Id dòng bên LADA (nếu có)

Id criterion bên nền tảng — bắt buộc với Update/Remove

Khung giờ liên quan

Giá trị hệ số giá thầu sẽ ghi. null nghĩa là xoá điều chỉnh (bỏ trống field nhưng vẫn đưa bid_modifier vào field mask).

Có gán giá trị bid_modifier lên object gửi đi hay không. false + mask có bid_modifier = yêu cầu Google xoá điều chỉnh.

Các đường dẫn field mask cần gửi kèm khi Update. Dựng tay, không dùng FieldMasks.AllSetFieldsOf(): proto3 coi field chưa set và 0.0 là như nhau nên helper đó sẽ bỏ bid_modifier khỏi mask, khiến cả "xoá điều chỉnh" và "đặt -100%" đều biến thành không làm gì.

Giá trị hệ số hiện có trên nền tảng — chỉ có nghĩa với Update

Mô tả tiếng Việt của thao tác, hiển thị nguyên văn trên hộp xác nhận

Kết quả so sánh lịch LADA với lịch nền tảng.

Các lỗi dữ liệu phát hiện trước khi gọi nền tảng (tiếng Việt)

Không có lỗi nào

Khung giờ cần tạo mới trên nền tảng

Khung giờ chỉ đổi hệ số giá thầu

Khung giờ cần xoá khỏi nền tảng

Khung giờ hai bên đã giống nhau — không sinh thao tác nào

Tổng số thao tác sẽ gửi lên nền tảng

Có việc phải làm hay không. Không có thì tuyệt đối đừng gọi ra Google.

Toàn bộ thao tác theo thứ tự gửi: xoá trước, rồi tạo, rồi cập nhật

Mô tả tiếng Việt từng thao tác, đúng thứ tự gửi

Câu tóm tắt cho tiêu đề hộp xác nhận

So sánh lịch quảng cáo giữa LADA và nền tảng, sinh danh sách thao tác cần ghi. Toàn bộ lớp này là logic thuần: không chạm DB, không chạm SDK Google. Nhờ vậy phần dễ sai nhất của luồng ghi được test đầy đủ trước khi có bất kỳ lệnh gọi ra ngoài. Quy tắc ánh xạ (quyết định 3 của Phase 6): AdScheduleInfo của Google là bất biến — đổi thứ/giờ phải xoá criterion cũ rồi tạo cái mới; chỉ có bid_modifier là sửa được tại chỗ. Xem tài liệu: https://developers.google.com/google-ads/api/fields/v21/campaign_criterion

Phút Google cho phép trong lịch quảng cáo — MinuteOfHour chỉ có 4 mốc này

Hệ số giá thầu nhỏ nhất Google nhận cho criterion. Nguồn: tài liệu field campaign_criterion.bid_modifier — "must be in the range 0.1 - 10.0", giá trị 0 chỉ dùng để tắt hẳn một loại thiết bị (device), không áp dụng cho lịch quảng cáo. https://developers.google.com/google-ads/api/fields/v21/campaign_criterion

Hệ số giá thầu lớn nhất Google nhận (= +900%). Cùng nguồn với .

Tên field bid_modifier trong field mask của Google

Kiểm tra tính hợp lệ của lịch mong muốn trước khi so sánh: mốc phút, giờ kết thúc, thứ tự đầu–cuối, khoảng hệ số giá thầu và chồng giờ trong cùng một thứ.

Danh sách lỗi tiếng Việt; rỗng nghĩa là hợp lệ.

Tìm các cặp khung giờ chồng nhau trong cùng một thứ. Google từ chối cả lô mutate khi có chồng giờ, nên phải bắt trước và nói rõ chồng ở đâu.

So sánh hai phía và sinh thao tác, không kiểm tra hợp lệ. Dùng khi cần biết diff thuần (ví dụ test phân biệt 0.0 với null).

Lịch mong muốn — các dòng trong LADA Lịch đang có trên nền tảng, vừa đọc về

Kiểm tra hợp lệ rồi so sánh. Có lỗi thì trả về bản diff rỗng kèm lỗi — không bao giờ trả thao tác dựa trên dữ liệu đã biết là sai.

Phần đuôi mô tả hệ số giá thầu, bỏ hẳn khi không có điều chỉnh

Lịch chạy quảng cáo (ad schedule) của chiến dịch. Ad schedule là criterion cấp chiến dịch bên Google, khớp theo ExternalId (criterion id). Luồng ghi cố ý chia làm ba bước tách biệt, vì sửa lịch là đổi giá thầu — tiêu tiền thật: (1) sửa bản nháp trong LADA (, , ) — không gọi ra nền tảng; (2) xem trước () — tính diff rồi nhờ Google kiểm tra bằng validate_only, không ghi gì; (3) đẩy thật () — ghi rồi đọc lại từ nền tảng để xác nhận. Chiến dịch không có dòng nào nghĩa là **chạy cả tuần 24/7**, không phải "không chạy".

Lấy lịch của một chiến dịch, sắp xếp theo thứ (Thứ Hai trước) rồi theo giờ bắt đầu.

Lấy lịch kèm bối cảnh UI cần: múi giờ của tài khoản, chiến dịch đã publish chưa, nền tảng có cho sửa lịch không. Trả cả bọc này để UI không phải gọi thêm API và không phải tự đoán múi giờ (giờ lịch chạy theo múi giờ tài khoản, không phải giờ server).

Kéo lịch từ nền tảng về: upsert theo (AdsCampaignId, ExternalId), soft-delete các dòng nền tảng không còn trả về.

Dò lệch lịch của một chiến dịch: đọc lịch nền tảng, so với LADA và chỉ đánh dấu khi lệch. Không sửa lịch ở bất kỳ phía nào.

Dò lệch lịch toàn bộ chiến dịch đã đẩy lên nền tảng. Dùng cho job chạy định kỳ và cho nút chạy tay. Một chiến dịch lỗi không làm chết cả lượt.

Tạo / sửa một khung giờ trong LADA. Không gọi ra nền tảng: dòng được đánh SyncStatus = OutOfSync rồi chờ người dùng bấm đẩy lên. Validate qua AdsScheduleDiff.Validate trên toàn bộ lịch sau khi áp thay đổi, nên chồng giờ bị chặn ngay lúc lưu nháp chứ không đợi Google từ chối cả lô.

Xoá một khung giờ trong LADA (soft-delete). Không gọi ra nền tảng. Dòng đã có ExternalId thì bên nền tảng vẫn còn khung giờ đó cho tới khi đẩy lên — sẽ liệt kê nó ở nhóm "Xoá".

Đặt / xoá hệ số điều chỉnh giá thầu của một khung giờ trong LADA.

Hệ số theo dạng Google (1.2 = +20%). null = xoá điều chỉnh, khác hẳn 0 — xem .

Xem trước những gì sẽ ghi lên nền tảng: đọc lịch hiện tại từ nền tảng, so với lịch trong LADA, rồi gửi cả lô ở chế độ validate_only để nền tảng kiểm tra. Không ghi bất cứ thứ gì lên tài khoản quảng cáo.

Đẩy lịch lên nền tảng thật. Việc này tiêu tiền: giá thầu theo giờ đổi ngay sau khi ghi. Sau khi ghi xong luôn gọi lại để đọc lại — request thành công không đồng nghĩa dữ liệu đúng, chỉ đọc lại mới chắc.

Áp một mẫu lịch () cho một chiến dịch — chỉ ghi nháp trong LADA, không gọi ra nền tảng. Thay toàn bộ lịch hiện tại: các khung giờ cũ bị xoá (soft-delete) rồi tạo lại theo mẫu. Dòng cũ đã có ExternalId vẫn còn trên nền tảng cho tới khi người dùng đẩy lên.

% chung ghi đè cho mọi khung của mẫu. null nghĩa là dùng % của mẫu (DefaultBidModifier, hoặc % riêng từng khung nếu mẫu có).

Áp một mẫu lịch cho nhiều chiến dịch rồi (tuỳ ) đẩy luôn lên nền tảng. Một chiến dịch lỗi không làm chết cả lô: mỗi chiến dịch được bọc try/catch riêng, phần còn lại vẫn chạy, và kết quả trả về nói rõ từng dòng thành công / thất bại / bỏ qua kèm lý do. Chiến dịch chưa publish và tài khoản MCC được tính là bỏ qua, không phải thất bại.

false = chỉ ghi nháp trong LADA. true = ghi nháp rồi đẩy lên nền tảng thật. true = dry-run cả lô: ghi nháp trong LADA rồi nhờ nền tảng kiểm tra (validate_only) mà không ghi thật. Chỉ có nghĩa khi .

Kéo lịch từ nền tảng về cho nhiều chiến dịch — tuần tự, một chiến dịch lỗi không giết lô, kết quả từng dòng; chiến dịch còn khung giờ sửa trong LADA chưa đẩy lên thì bỏ qua (kéo về sẽ ghi đè). Mỗi chiến dịch một lượt đọc nền tảng: lõi kéo về tự dò lệch lại bằng danh sách vừa đọc và gỡ cờ. Có Id không tồn tại / đã xoá là từ chối cả lô trước khi gọi nền tảng (Rejected). Tối đa 500 Id.

Lịch của một chiến dịch kèm bối cảnh hiển thị.

Các khung giờ đã sắp xếp

Múi giờ của tài khoản quảng cáo (ví dụ "Asia/Saigon"). Lịch chạy theo múi giờ này, KHÔNG phải giờ máy chủ — UI phải ghi rõ cạnh lưới giờ.

Tên tài khoản quảng cáo

Chiến dịch đã đẩy lên nền tảng chưa — chưa thì không đồng bộ được

Tài khoản là MCC — không chứa criterion nên không đồng bộ được

Nền tảng đọc được lịch hay không

Nền tảng cho sửa lịch hay không. UI đọc cờ này để ẩn/hiện chức năng sửa thay vì hard-code nền tảng.

Nền tảng có kiểm tra trước khi ghi (dry-run) hay không — không có thì UI phải nói rõ

Chiến lược đặt giá của chiến dịch có áp dụng % điều chỉnh theo khung giờ hay không. Ignored → UI cảnh báo vàng nhưng vẫn cho lưu; Unknown → nói rõ là "chưa xác định được", tuyệt đối không đoán.

Câu cảnh báo tiếng Việt về giá thầu theo giờ — null nghĩa là không có gì phải cảnh báo

Có khung giờ nào chưa khớp nền tảng (nháp / OutOfSync) đang chờ đẩy lên

Thời điểm đồng bộ lịch gần nhất (lấy mốc mới nhất trong các dòng)

Chiến lược đặt giá của chiến dịch — smart bidding thì Google bỏ qua bid modifier

Kết quả một lần xem trước / đẩy lịch lên nền tảng. Luôn trả kèm để hộp xác nhận trên UI nói đúng sẽ đổi gì — nói sai việc sắp làm là nguyên nhân tiêu tiền oan.

Đây là lần chạy thử (validate_only) chứ không phải ghi thật

Có thay đổi nào cần đẩy lên hay không

Câu tóm tắt: sẽ thêm mấy, đổi giá thầu mấy, xoá mấy khung giờ

Mô tả tiếng Việt từng thao tác, đúng thứ tự sẽ gửi lên nền tảng

Lỗi dữ liệu phát hiện trước khi gọi nền tảng (chồng giờ, phút sai mốc…)

Nền tảng đã kiểm tra và chấp nhận lô thay đổi này (chỉ có nghĩa khi xem trước)

Mã lỗi gốc của nền tảng — giữ nguyên để tra tài liệu

Lịch đọc lại từ nền tảng sau khi ghi. Đây là sự thật, không phải payload đã gửi — UI phải hiển thị danh sách này chứ không hiển thị thứ mình vừa gửi lên.

Cảnh báo về chiến lược đặt giá (nếu có) — vẫn ghi được, chỉ là % có thể không có tác dụng

Kết quả một lần đồng bộ lịch.

Số khung giờ mới thêm

Số khung giờ đã cập nhật

Số khung giờ nền tảng không còn trả về nên bị soft-delete

Tổng số khung giờ nền tảng trả về

Số khung còn lệch sau khi kéo về và dò lại bằng chính danh sách vừa đọc — 0 nghĩa là chiến dịch đã khớp nền tảng (cờ OutOfSync vì lệch lịch đã được gỡ). Null khi chưa dò (kéo về thất bại).

Kết quả áp lịch cho một chiến dịch trong lô — một dòng của bảng kết quả.

Kết cục của dòng này. Cố ý tách Skipped khỏi Failed: chiến dịch chưa publish hay tài khoản MCC là chuyện bình thường, đếm chúng là thất bại sẽ làm người dùng đi tìm lỗi không tồn tại.

Lý do — bắt buộc có khi bỏ qua hoặc thất bại, để người dùng biết phải làm gì

Số thao tác đã (hoặc sẽ) gửi lên nền tảng cho chiến dịch này

Mã lỗi gốc của nền tảng, giữ nguyên để tra tài liệu

Cảnh báo chiến lược đặt giá bỏ qua % giá thầu (nếu có)

Kết cục của một chiến dịch trong lô

Không áp được vì lý do hợp lệ (chưa publish, tài khoản MCC…) — không phải lỗi

Phần chung của mọi kết quả lô theo chiến dịch (áp mẫu lịch, kéo lịch về): bảng từng dòng + số đếm. Luôn mang đầy đủ từng dòng: câu "8/12 chiến dịch" mà không nói 4 cái nào lỗi thì vô dụng. là ca lô bị từ chối trước khi chạy (Id lạ, quá trần, rỗng): rỗng, Message là lý do — controller trả 400, giao diện dừng lô thay vì suy đoán từ số dòng.

Kết quả từng chiến dịch — thứ tự giữ nguyên theo danh sách gửi lên

Lô bị từ chối trước khi chạy — không chiến dịch nào được xử lý

Tổng cả lô — nghĩa tuỳ luồng, xem lớp con

Kết quả áp lịch cho cả lô chiến dịch. TotalOperationCount là số thao tác gửi lên nền tảng — dùng để ước lượng quota.

Đây là bản dry-run (chưa ghi gì lên nền tảng) hay lần ghi thật

Mẫu đã áp

Kết quả kéo lịch về cả lô. OperationCount / TotalOperationCount ở đây là số khung giờ thay đổi trong LADA (thêm + cập nhật + bỏ), không phải thao tác gửi lên nền tảng: kéo về không ghi gì lên.

Số chiến dịch sau khi kéo về đã khớp với nền tảng (dò lệch lại không thấy gì)

Phần dò lệch lịch (schedule drift) của . Chỉ đọc và đánh dấu, tuyệt đối không tự ghi đè. Một job âm thầm ghi đè thay đổi thủ công của người dùng — dù theo hướng nào — là hành vi tệ nhất có thể: người ta sửa giá thầu trên Google Ads UI lúc 9h, job chạy lúc 2h sáng xoá mất, không ai biết vì sao. Job này chỉ đặt SyncStatus = OutOfSync + OutOfSyncDetailJson rồi để người dùng tự quyết: đẩy lịch LADA lên, hay kéo lịch nền tảng về.

Nhãn endpoint ghi vào sync log — là bảng GAQL được truy vấn

Tên thao tác ghi vào sync log

Nhãn endpoint cho luồng ghi — mutate criterion qua GoogleAdsService

Thao tác xem trước (validate_only) — ghi log riêng để phân biệt với lần ghi thật

Thao tác đẩy lịch thật lên nền tảng

Phần lõi của kéo lịch về, nhận chiến dịch đã tải kèm tài khoản + kết nối (luồng lô tải một lần rồi gọi thẳng vào đây). Sau khi ghi xong, dò lệch lại bằng chính danh sách nền tảng vừa đọc để gỡ cờ OutOfSync của chiến dịch — không tốn lượt đọc thứ hai, và cả endpoint lẻ lẫn lô đều gỡ cờ (trước GĐ C kéo về xong panel "việc cần xử lý" vẫn đỏ tới job đêm).

Thân chung của xem trước và đẩy thật. Chỉ khác nhau một cờ — cố ý dùng chung một đường code để bản xem trước không bao giờ lệch với bản ghi thật.

Giới hạn số chiến dịch một lô. Quota Google Ads Basic Access là 15.000 operations/ngày; mỗi chiến dịch có thể sinh vài chục operation (xoá lịch cũ + tạo lịch mới), nên 30 chiến dịch là mức vừa đủ dùng mà vẫn còn xa quota — và đủ nhỏ để người dùng còn đọc hết được bảng kết quả. Vượt giới hạn thì báo lỗi, tuyệt đối không âm thầm cắt bớt danh sách.

Áp mẫu cho một chiến dịch trong lô. Không ném lỗi ra ngoài trong các ca đã lường được — trả về dòng kết quả có lý do, để lô còn chạy tiếp.

Thay toàn bộ lịch nháp của chiến dịch bằng danh sách khung giờ của mẫu. Khớp theo WindowKey (thứ + giờ) chứ không xoá sạch rồi tạo lại. Lý do rất cụ thể: xoá sạch làm mất ExternalId của những khung giờ vẫn đang tồn tại trên nền tảng, và khớp dòng theo ExternalId — dòng nháp ExternalId = null sẽ không khớp được nên bước đọc lại sinh thêm một dòng nữa cho cùng khung giờ. Dòng nháp mồ côi đó cũng không bị bước dọn dẹp xoá (bước đó chỉ xét dòng có ExternalId), kết quả là hai dòng trùng khung giờ và validate báo chồng giờ vĩnh viễn — lịch của chiến dịch coi như hỏng, phải sửa tay trong DB. Giữ lại ExternalId còn lợi về quota: đổi % giá thầu của khung giờ đã có trở thành một update thay vì cặp remove + create.

Số khung giờ cũ bị xoá vì không có trong mẫu

Dựng danh sách khung giờ của mẫu, áp % giá thầu theo thứ tự ưu tiên: % người dùng nhập → % riêng của khung → % mặc định của mẫu.

Câu thông báo sau khi áp mẫu vào lịch nháp của một chiến dịch

Câu tổng kết cả lô. Luôn nêu số bỏ qua tách riêng số thất bại.

Trần Id một lần kéo lịch về — cùng con số với các endpoint nhận danh sách Id khác (plan §3.9)

Một chiến dịch trong lô: gác các ca bỏ qua (kể cả kết nối lỗi / tài khoản tắt — gọi vào là chắc chắn thất bại), từ chối chiến dịch còn khung giờ sửa trong LADA chưa đẩy lên (kéo về sẽ ghi đè im lặng), rồi kéo về bằng lõi dùng chung — lõi đã dò lệch lại và gỡ cờ. Trả thêm cờ "đã khớp" để đếm ở kết quả lô.

Lý do một chiến dịch bị BỎ QUA trong các luồng lô (hợp lệ, không phải lỗi): chưa gắn tài khoản / kết nối (kể cả đã xoá mềm — Include không lọc xoá mềm), tài khoản MCC, chưa đẩy lên nền tảng. Null = xử lý được. Dùng chung cho áp mẫu lịch và kéo lịch về để cùng một chiến dịch nhận cùng một câu dù đi endpoint nào.

Việc người dùng định làm, để câu gợi ý đúng ngữ cảnh ("áp lịch", "kéo lịch về") Luồng phải ĐỌC được từ nền tảng (kéo lịch về): thêm các ca tài khoản đã tắt đồng bộ, kết nối đang lỗi, nền tảng chưa hỗ trợ đọc lịch — gọi vào đó là chắc chắn thất bại và chỉ tốn log.

Chiến dịch còn khung giờ đã sửa trong LADA mà chưa đẩy lên (dòng lịch OutOfSync) thì kéo về hàng loạt sẽ ghi đè im lặng thứ người dùng vừa nhập — luồng lẻ cho họ xem hai cột trước khi bấm, luồng lô thì không, nên ở lô là bỏ qua kèm lý do (finding review GĐ C).

Tên chiến dịch cho dòng kết quả khi luồng chính đã ném lỗi

Các dòng lịch còn hiệu lực của một chiến dịch trong LADA

Entity → slot thuần dữ liệu để đưa vào AdsScheduleDiff. Giữ nguyên BidModifier kể cả null — null (không điều chỉnh) khác hẳn 0 (-100%).

DTO nền tảng → slot. LocalId để null vì đây là phía nền tảng, chưa biết ứng với dòng LADA nào.

Áp dữ liệu model lên entity rồi đánh dấu lệch với nền tảng

Đánh dấu dòng đã sửa trong LADA nhưng chưa đẩy lên nền tảng. Dòng chưa từng lên nền tảng giữ Local; dòng đã có criterion thì thành OutOfSync — UI đọc cờ này để hiện chấm "chờ đẩy lên".

Nhãn tiếng Việt của một khung giờ, dùng trong thông báo

Câu cảnh báo về việc % điều chỉnh giá thầu có tác dụng hay không với chiến lược đặt giá đang dùng. Trả null khi nền tảng thật sự áp dụng — không có gì phải cảnh báo.

Nội dung định ghi, lưu vào RequestJson của sync log. Cố ý lưu cả mô tả tiếng Việt từng thao tác chứ không chỉ payload máy đọc: khi cần truy "vì sao chi phí tăng", đọc log phải hiểu ngay đã đổi gì mà không cần dịch proto.

Ghi lỗi lên các dòng lịch hiện có để UI chỉ ra được lần đồng bộ gần nhất đã thất bại, thay vì hiển thị dữ liệu cũ như thể vẫn đúng.

Ghi một dòng sync log. Mặc định là hướng Pull / thao tác đồng bộ để giữ nguyên hành vi phần đọc; luồng ghi truyền AdsSyncDirection.Push kèm nội dung định ghi.

Đổi của .NET (Sunday = 0) sang số thứ tự để sắp xếp theo cách người Việt đọc lịch: Thứ Hai = 1 … Chủ Nhật = 7.

Lô bị từ chối trước khi chạy — Rejected để controller trả 400 và giao diện dừng lô

Thao tác ghi vào AdsSyncLog cho lượt dò lệch

Dò lệch lịch cho một chiến dịch: đọc lịch từ nền tảng, so với LADA, và nếu lệch thì đánh dấu chiến dịch OutOfSync kèm chi tiết. Không ghi bất cứ thứ gì lên nền tảng. Chiến dịch chưa publish / tài khoản MCC / kết nối đã tắt được bỏ qua, không tính là lỗi.

Dò lệch lịch cho mọi chiến dịch đã publish thuộc các tài khoản đang bật. Một chiến dịch lỗi không làm chết cả lượt: mỗi chiến dịch bọc try/catch riêng. Đây là điều kiện sống của job chạy đêm — một kết nối hết token không được làm 200 chiến dịch còn lại không được kiểm tra.

So lịch LADA với lịch nền tảng, trả về danh sách khung giờ lệch. Logic thuần, không chạm DB — test được. Khớp theo WindowKey giống vì Google không cho sửa thứ/giờ của một criterion: khung thời gian chính là danh tính của nó. Chỉ so những dòng LADA đã có ExternalId hoặc khung mà nền tảng có. Bản nháp chưa đẩy lên (ExternalId rỗng) không tính là lệch: người dùng đang cố ý sửa và chưa đẩy, báo lệch ở đó là báo động giả và sẽ khiến người ta bỏ qua cả badge thật.

Ghi kết quả dò lệch vào chiến dịch. Chỉ đánh dấu — không sửa một dòng lịch nào. Hết lệch thì xoá cờ, nhưng chỉ khi chiến dịch đang OutOfSync: chiến dịch đang Local/Publishing/Failed mang nghĩa khác của luồng publish, ghi Synced lên là mất thông tin của luồng đó.

true khi vừa gỡ cờ lệch (trước đó OutOfSync, nay đã khớp lại)

Các phần tử lệch trường ({Field, LocalValue, RemoteValue}) đang lưu trong chi tiết — phần không thuộc luồng lịch, phải giữ nguyên. JSON rỗng / hỏng → rỗng (chi tiết hỏng thì ghi mới).

Câu tóm tắt cho log và cho người bấm chạy tay

Một khung giờ đang lệch giữa LADA và nền tảng, ở dạng đủ để UI hiện hai cột cạnh nhau. Cố ý không tái dùng (Field/LocalValue/RemoteValue) của chiến dịch: lệch lịch không phải "một trường đổi giá trị" mà là "khung giờ này có bên kia mà không có bên này". Nhồi vào cấu trúc 3 cột kia thì phải nhét nhãn khung giờ vào tên trường, UI không tách lại được để tô màu theo loại lệch.

Loại lệch: MissingOnPlatform (LADA có, nền tảng không), MissingInLada (nền tảng có, LADA không), BidModifierDiffers (cùng khung, khác giá thầu).

Nhãn tiếng Việt của loại lệch, để UI không phải tự dịch

Nhãn khung giờ, ví dụ "Thứ Hai 08:00–17:30"

Giá thầu phía LADA đã định dạng (%), null khi LADA không có khung này

Giá thầu phía nền tảng đã định dạng (%), null khi nền tảng không có khung này

Criterion id bên nền tảng (nếu khung đó tồn tại bên nền tảng)

Giá trị của — chuỗi lưu trong OutOfSyncDetailJson và được classifier "việc cần xử lý" đọc lại, nên là hằng dùng chung: đổi chữ ở đây là đổi dữ liệu đã lưu.

LADA nghĩ khung này đang chạy nhưng bên nền tảng không còn

Cùng khung giờ nhưng % giá thầu hai bên khác nhau

Nền tảng có khung mà LADA không biết

Kết quả dò lệch lịch của một chiến dịch.

Chiến dịch được kiểm tra

Tên chiến dịch — để log/thông báo không phải join lại

Đã kiểm tra được hay không (false = bỏ qua hoặc lỗi kết nối)

Có lệch hay không. Chỉ có nghĩa khi .

Trước đó đang lệch, lượt này đã khớp lại nên cờ OutOfSync vừa được gỡ. Tách riêng khỏi "không lệch" để log nói được "hết lệch 3" — người vận hành cần biết cảnh báo cũ đã tự hết, không phải đi tìm xem ai đã xử lý.

Danh sách khung giờ lệch

Lý do bỏ qua / lỗi. null khi kiểm tra bình thường.

Lỗi khi gọi nền tảng, nếu có

Kết quả một lượt chạy dò lệch trên nhiều chiến dịch.

Số chiến dịch đã gọi ra nền tảng để so

Số chiến dịch phát hiện lệch

Số chiến dịch vừa hết lệch (trước đó OutOfSync, giờ khớp lại)

Số chiến dịch bỏ qua (chưa publish, MCC, kết nối tắt…) — không phải lỗi

Số chiến dịch lỗi khi gọi nền tảng

Chi tiết từng chiến dịch có lệch hoặc lỗi (chiến dịch khớp không đưa vào cho gọn)

Câu tóm tắt tiếng Việt cho log và cho endpoint kích hoạt tay

Định nghĩa các mẫu lịch áp nhanh. Cố ý để ở backend (không hard-code trong Vue) vì hai lý do: thêm/sửa mẫu không phải build lại frontend, và job tự động (nếu có) dùng chung được đúng một định nghĩa — hai bản định nghĩa lệch nhau là cách chắc chắn nhất để áp sai lịch mà không ai biết. Áp mẫu = thay toàn bộ lịch hiện tại, không phải cộng thêm vào lịch đang có.

Thứ Hai–Thứ Sáu 08:00–17:30

Phần bù của — ngoài giờ hành chính và cả cuối tuần

Thứ Bảy + Chủ Nhật cả ngày

Chạy suốt — tương đương xoá hết khung giờ

Hai đỉnh đặc thù vận tải: sáng điều xe, chiều chốt lịch lấy hàng hôm sau

Các thứ trong tuần theo cách người Việt đọc lịch: Thứ Hai trước, Chủ Nhật cuối. Không dùng thứ tự của (.NET đánh Sunday = 0).

Toàn bộ mẫu, theo thứ tự muốn hiện trên UI.

Tìm mẫu theo khoá. Trả null nếu không có — người gọi phải xử lý, không được lặng lẽ áp mẫu khác.

Cùng một khung giờ áp cho nhiều thứ

Phần bù của giờ hành chính. Ngày làm việc tách thành hai khung để không chồng lên khoảng 08:00–17:30; cuối tuần lấy cả ngày.

Giờ cao điểm vận tải — mỗi khung mang % riêng, không dùng % mặc định chung.

Một mẫu lịch áp nhanh.

Khoá bền, dùng trong API và log — đừng đổi sau khi đã phát hành

Tên hiện trên UI

Giải thích mẫu làm gì, hiện thẳng trên UI để người dùng không phải đoán

Hệ số giá thầu mặc định theo dạng Google (1.2 = +20%). null = không điều chỉnh. Người dùng ghi đè được khi áp.

Mẫu tự mang % riêng cho từng khung giờ (như giờ cao điểm vận tải). UI nên nói rõ rằng nhập % chung sẽ ghi đè các % riêng này.

Mẫu này xoá sạch lịch chứ không tạo khung giờ nào (mẫu 24/7). UI phải cảnh báo rõ vì nhìn danh sách khung giờ rỗng dễ tưởng là mẫu lỗi.

Các khung giờ của mẫu. Rỗng là hợp lệ — nghĩa là chạy 24/7.

Số khung giờ mẫu sẽ tạo — UI hiện trước để người dùng ước lượng

Một khung giờ trong mẫu. Thuần dữ liệu, không gắn chiến dịch nào.

0–24, trong đó 24 nghĩa là hết ngày

% riêng của khung này theo dạng hệ số Google. null = dùng % chung khi áp.

Ghi log mọi lần gọi ra nền tảng quảng cáo — công cụ debug chính của module. Bắt buộc đi qua service này thay vì ghi trực tiếp, để không có chỗ nào lọt credential vào DB.

Ghi một dòng log. Nội dung request/response được scrub trước khi lưu. Lỗi khi ghi log không được làm hỏng nghiệp vụ gọi nó — chỉ nuốt và bỏ qua.

Xoá thông tin mật khỏi một chuỗi trước khi lưu hoặc trả ra UI.

Danh sách log để tra cứu trên UI. Payload đã được scrub từ lúc ghi, nhưng vẫn scrub lại một lần nữa khi trả ra để chắc chắn với dữ liệu cũ.

Dữ liệu một dòng log gọi nền tảng.

Tên hành động, ví dụ FetchAccounts, SyncCampaigns, PublishCampaign

Giới hạn độ dài payload lưu vào log — response metrics có thể rất lớn

Độ dài cột ErrorMessage trong AdsSyncLogMap

Độ dài cột PlatformErrorCode trong AdsSyncLogMap

Độ dài cột Endpoint trong AdsSyncLogMap

Độ dài cột Action trong AdsSyncLogMap

Các mẫu credential cần xoá. Bao gồm cả dạng header thô và dạng JSON, vì payload log đến từ nhiều nguồn (HttpClient, SDK, chuỗi tự ghép).

Cắt chuỗi cho vừa độ dài cột trong DB.

Kéo chiến dịch / nhóm / quảng cáo từ nền tảng về bản ghi canonical của LADA. Quy tắc đối chiếu: khớp theo ExternalId; bản ghi LADA đang có ExternalId mà số liệu khác nền tảng thì đánh kèm danh sách trường lệch — không tự ghi đè, vì có thể người dùng vừa sửa trong LADA và chưa đẩy lên.

Đồng bộ chiến dịch của một tài khoản quảng cáo

Đồng bộ nhóm quảng cáo. Truyền để chỉ đồng bộ một chiến dịch.

Đồng bộ quảng cáo (Google: AdGroupAd) từ nền tảng về. Truyền để chỉ đồng bộ một chiến dịch. Quảng cáo tồn tại trên nền tảng nhưng không do LADA soạn sẽ có = null — đó là dữ liệu chỉ đọc, không phải lỗi.

Đồng bộ cả chiến dịch, nhóm rồi tới quảng cáo của một tài khoản

Kết quả một lần đồng bộ.

Số bản ghi mới thêm

Số bản ghi đã cập nhật

Số bản ghi bị đánh dấu lệch dữ liệu

Tổng số bản ghi nền tảng trả về

Một trường đang lệch giữa LADA và nền tảng.

So sánh các trường người dùng sửa được. Không so RawResponseJson / LastSyncedAt vì chúng luôn khác nhau và không phản ánh sự lệch thật.

So sánh các trường có thể lệch. Không so ApprovalStatus: trạng thái xét duyệt do nền tảng quyết, LADA không sửa được nên nó đổi không phải là "lệch dữ liệu" mà là tin mới cần nhận về.

Ghi log một lần đồng bộ. / là tuỳ chọn để các hàm đồng bộ cũ không phải đổi; hàm mới nên truyền đủ để bộ lọc log theo cấp dùng được.

Tài khoản quản lý (MCC) không chứa chiến dịch / nhóm / số liệu — Google bắt gọi riêng vào từng tài khoản con. Chặn ở service thay vì chỉ ở UI để job định kỳ cũng an toàn.

Chuyển các API key còn ở dạng bản rõ trong bảng AiProvider sang bản mã hoá tại chỗ (plan cổng §3.6, đóng CNQ-1). Chạy lúc API khởi động (StartupHostedService) vì FluentMigrator chỉ chạy SQL, không gọi được ISecretProtector. Tiêu chí chọn dòng là — đúng tiêu chí của script khảo sát Lada.Migrations/Sql/KhaoSat/TroLyAiCongNhuongQuyen.KhaoSat.sql.

Chạy lại vô hại: dòng đã mã hoá không còn khớp tiêu chí. Mỗi dòng ghi bằng ExecuteUpdate có điều kiện "key vẫn là giá trị vừa đọc" — người sửa key cùng lúc không bị đè. Máy chủ không mã hoá được (thiếu Security:SecretKey) thì dừng và cảnh báo, KHÔNG bao giờ ghi lại bản rõ. Log chỉ có số dòng, không có key. Số dòng đã chuyển.

Interface quản lý nhà cung cấp AI

API key bản rõ của một nhà cung cấp để gắn vào lời gọi — key lưu mã hoá trong DB (CNQ-1); rỗng khi không có hoặc không giải mã được. KHÔNG gán kết quả lại vào : entity đang được theo dõi, một lần UpdateAsync sau đó sẽ ghi bản rõ xuống DB.

Tạo ảnh bằng OpenAI. Nếu có brandContext → dùng Responses API (POST /v1/responses) với tools image_generation + file_search. Nếu không có brandContext → fallback Images API (POST /v1/images/generations). Nếu enhancePrompt = true → prompt được LLM viết lại thành prompt tiếng Anh chi tiết trước khi tạo ảnh.

Kết quả tạo ảnh AI

Prompt sau khi được LLM enhance (null nếu không enhance hoặc enhance thất bại)

Thông tin model AI trả về cho client

Kết quả sync models

Thông báo khi máy chủ không mã hoá được key (thiếu Security:SecretKey) — không bao giờ lưu bản rõ.

Key người dùng vừa nhập → bản mã hoá để ghi DB; ném khi key quá dài hoặc máy chủ không mã hoá được.

Tạo ảnh bằng OpenAI. Nếu có brandContext → dùng Responses API (POST /v1/responses) với tools. Nếu không có brandContext → fallback Images API cũ. Nếu enhancePrompt = true → prompt được LLM viết lại thành prompt tiếng Anh chi tiết trước khi tạo ảnh.

System prompt cho bước enhance image prompt

Viết lại prompt tạo ảnh thành prompt tiếng Anh chi tiết bằng LLM (gpt-4.1-mini). Trả về null nếu thất bại — caller sẽ fallback về prompt gốc, không chặn việc tạo ảnh.

Tạo ảnh qua Responses API (POST /v1/responses) Model orchestrator (gpt-4.1-mini/gpt-4.1) sẽ: 1. Đọc developer instructions (luật brand cố định) 2. Dùng file_search tra cứu brand guidelines từ Vector Store 3. Xem ảnh tham chiếu (logo, xe tải, đồng phục) qua file_id 4. Gọi tool image_generation để tạo ảnh phù hợp

Fallback: Tạo ảnh qua Images API cũ (POST /v1/images/generations) Dùng khi không có brand context

Gọi OpenAI API GET /v1/models để lấy danh sách models https://developers.openai.com/api/reference/resources/models/methods/list Thông tin chi tiết về các model xem ở https://developers.openai.com/api/docs/models/compare

Danh sách model của Anthropic qua SDK chính thức (cổng nhượng quyền GĐ G — màn Cấu hình trợ lý chọn model từ đây). Luôn gọi địa chỉ mặc định của SDK, không theo ô BaseUrl (mặc định của form là địa chỉ OpenAI).

Kết quả trả về từ Brand Registry cho image generation

Interface quản lý Brand Registry + Brand Assets trên OpenAI

Lấy BrandRegistry hiện tại (singleton cho lada_express)

Cập nhật developer instructions

Upload file lên OpenAI Files API và lưu BrandAsset

Xóa brand asset (cả trên OpenAI + DB)

Lấy tất cả assets đang active

Lấy chỉ image assets (cho image generation)

Sync knowledge base MD files lên OpenAI Vector Store

Lấy brand context cho image generation (developer instructions + file_ids + vector_store_id)

Đăng ký file đã có trên OpenAI làm Brand Asset (không upload lại)

Gắn Vector Store ID đã có vào BrandRegistry làm Knowledge Base

Developer instructions mặc định nếu chưa cấu hình

Upload file lên OpenAI Files API, trả về file_id POST /v1/files với multipart/form-data

Xóa file trên OpenAI Files API DELETE /v1/files/{file_id}

Service quản lý và truy xuất dữ liệu Knowledge Base cho RAG

Lấy toàn bộ ngữ cảnh kiến thức từ các tài liệu trong thư mục knowledge

Interface cho Marketing Agent Service

Tạo bài blog từ brief

Tạo bài social media từ brief

Duyệt nội dung

Từ chối nội dung

Tìm kiếm nội dung với SmartTableParam (search, filter, sort, pagination)

Lấy danh sách nội dung chờ duyệt

Lấy nội dung theo ID

Lấy danh sách AI models được hỗ trợ

Marketing Agent Service sử dụng Semantic Kernel để tạo nội dung marketing. Giai đoạn MVP: gọi LLM trực tiếp qua SK, chưa có RAG/MCP.

Timeout cho một lần gọi LLM (không retry). Bài blog cần thời gian dài.

Model mặc định

Tải prompt template từ database theo category. Ném nếu không tìm thấy template active. Prompt KHÔNG dùng fallback hardcode — mọi thay đổi prompt phải qua DB.

Gọi LLM qua Semantic Kernel với logging

Xóa markdown code block nếu LLM bọc JSON trong ```json ... ```

Lấy danh sách AI models được hỗ trợ

Resolve model name — fallback về DefaultModel nếu không hợp lệ

Trích xuất field từ JSON response

Legacy OpenAI service — giờ dùng Semantic Kernel IChatCompletionService. Giữ interface cũ để backward compatibility với AiController.

Interface quản lý các prompt template dùng cho AI

Ghi cho MỌI lời gọi tool số liệu (plan §3.10).

Ghi nhật ký bằng kết nối CHÍNH, mở riêng (không dùng DbContext của request): lời gọi đọc số liệu chạy trên kết nối chỉ đọc không ghi được, và một lỗi DbContext của request không được kéo nhật ký chết theo.

Chờ ghi xong (vài mili giây) thay vì fire-and-forget như plan ghi: fire-and-forget trong request dễ mất dòng khi request kết thúc sớm, và lỗi ghi đã được lớp nền tool nuốt + log nên câu trả lời không bao giờ hỏng vì nhật ký. Không dùng CancellationToken của request: trợ lý huỷ giữa chừng vẫn phải có dòng nhật ký.

Độ dài tối đa của tham số lưu lại — khớp cột ParamsJson nvarchar(4000).

Dựng dòng nhật ký — tách riêng để test không cần DB.

Tham số JSON cắt ≤ ký tự (kèm dấu cắt) — không bao giờ lưu nguyên một tham số dài.

Mức độ có dữ liệu của một chiều / chỉ tiêu.

Đọc thẳng hoặc tính chắc chắn từ dữ liệu hệ thống.

Ước lượng theo một định nghĩa ghi rõ (ví dụ điểm dừng ĐD-1) — đọc kèm định nghĩa.

Chỉ có một phần (ví dụ chỉ đơn từ một ngày trở đi) — phần thiếu trả null kèm cảnh báo.

Một cột ngày mà tool cho chọn qua tham số date_field.

Cột ngày trong bảng fact.

Bảng danh mục mà biểu thức SQL của một chiều cần join thêm (alias cố định trong engine).

LEFT JOIN analytics.DimAgency sa ON sa.AgencyId = f.SourceAgencyId.

LEFT JOIN analytics.DimAgency da ON da.AgencyId = f.DestAgencyId.

LEFT JOIN analytics.DimAgency ag ON ag.AgencyId = f.AgencyId — fact có MỘT cột bưu cục (điểm dừng, đổ dầu).

LEFT JOIN analytics.DimVehicle vh ON vh.VehicleCode = f.VehicleCode — mẫu xe, tải trọng của lần đổ dầu.

Một chiều nhóm/lọc (group_by, filters).

Mã snake_case — thứ trợ lý truyền vào group_by.

Kiểu giá trị: date, week, month, int, string (mã đơn vị hành chính), text (chữ tự do), bool, enum, hashed_code, bin.

Nguồn của chiều bằng lời (cột fact → cột nghiệp vụ) — tài liệu cho người đọc code; không trả cho trợ lý.

Biểu thức SQL cố định trong code trên bảng fact (alias f) và bảng join () — thứ engine ghép vào câu truy vấn. {date} được thay bằng cột ngày của date_field (cũng lấy từ catalog). Null = chủ đề chưa mở hoặc chiều do engine tự dựng (bac_can theo weight_bins). Không bao giờ ghép chuỗi của người gọi vào đây — người gọi chỉ chọn MÃ.

Bảng danh mục cần join để tính .

true = chiều lộ số của TỪNG NGƯỜI: mã băm của người (nhân viên, khách, lái xe) hoặc chiều mà nhóm thường chỉ có một người (don_vi_sale — đo GĐ E). Tắt được bằng AppConfig Analytics.ExposePersonCodes (câu hỏi Q3).

Tên danh mục trong describe_catalog.lists để tra nhãn, nếu có.

Giá trị liệt kê được (kiểu enum/bin).

Một chỉ tiêu (metrics).

Đơn vị: van_don, kien, kg, dong, ty_le, khach, diem, lai_xe_ngay, xe, lai_xe, lit, km, lan, lit_moi_100km, dong_moi_lit, dong_moi_km, cm3_per_kg, dong_gia, xa, theo_don_vi, vu, gio, luot, ngay.

Định nghĩa nghiệp vụ bằng lời.

Công thức trên cột nguồn.

Biểu thức gộp SQL cố định trong code trên các cột của bảng fact (không alias, vì engine gộp trên CTE chứa f.*). Null khi là phân vị () hoặc chủ đề chưa mở.

Phân vị (0–1) tính bằng PERCENTILE_CONT … OVER (PARTITION BY nhóm) trên .

Cột fact của phân vị.

Chỉ tiêu HAI TẦNG (ví dụ "điểm dừng bình quân / lái xe / ngày"): engine gộp trước theo (nhóm, khoá cặp của chủ đề — ) rồi mới bình quân / phân vị trên các cặp. và viết trên cột [pv] = giá trị của cặp, chỉ có ở MỘT dòng mỗi cặp (các dòng khác NULL — hàm gộp và PERCENTILE_CONT đều bỏ NULL).

Chỉ tiêu hai tầng cần HẠNG của cặp trong nhóm (ví dụ "tỷ trọng doanh thu 10 khách lớn nhất"): engine thêm cột [prk] = thứ hạng của cặp theo [pv] giảm dần trong từng nhóm (1 = lớn nhất; chỉ có ở dòng mang [pv], còn lại NULL). viết trên [pv] và [prk]; bắt buộc . Cặp bằng giá trị nhau xếp hạng tuỳ ý nhưng tổng của N cặp đầu không đổi.

Chỉ tiêu KHÔNG chạy trên engine mà thuộc một bảng tool đọc thẳng danh mục (ví dụ doi_xe của query_vehicles — đội xe hiện có, không kỳ). Engine từ chối nó kèm câu chỉ đúng bảng; null = chỉ tiêu của engine.

Một nhóm của phân bố histogram_of: nhãn + cận trên (gồm); cận trên null = nhóm cuối "trên …".

Một phân bố mà tool trả thay cho bảng chỉ tiêu khi có tham số histogram_of (yêu cầu §5 T2): đếm số lần một cặp (khoá, ngày) có bao nhiêu vận đơn, rồi xếp vào nhóm.

Giá trị của tham số histogram_of.

Mã cột nhóm trong rows[].

Mã cột "số lần" (số cặp khoá–ngày) trong rows[].

Mã cột "số vận đơn" trong rows[].

Biểu thức SQL cố định của khoá cặp — mỗi dòng thiếu khoá thành một khoá riêng để tổng không hụt.

Chiều / chỉ tiêu / tham số yêu cầu có nêu nhưng hệ thống không có dữ liệu — ghi rõ vì sao.

chieu | chi_tieu | tham_so | bang.

Mã sổ nợ (AN-n) nếu có.

Một chủ đề số liệu = một tool truy vấn.

Tool phục vụ chủ đề.

Giai đoạn mở tool (plan §4).

true khi tool đã chạy ở hợp đồng hiện tại.

Bảng nguồn trong schema analytics.

Bảng fact SQL (tên đầy đủ, hằng trong code) mà engine truy vấn; null khi chủ đề chưa có engine.

Điều kiện cố định (hằng trong code, alias f) áp lên MỌI câu của chủ đề cùng với kỳ và bộ lọc — ví dụ doanh thu bỏ đơn huỷ trên cùng bảng fact vận đơn. Null = không có.

Chỉ tiêu trả khi người gọi bỏ trống metrics.

Phân bố nhận ở tham số histogram_of.

Bộ đếm chẩn đoán (mã → biểu thức gộp SQL cố định) engine tính kèm mỗi lời gọi trên đúng tập dòng đã lọc — tool dùng để sinh warnings[] (ví dụ số đơn còn địa chỉ bộ 3 cấp). Không trả cho trợ lý.

Bảng danh mục câu chẩn đoán cần join (biểu thức chẩn đoán viết trên alias f, sa, da, ag).

Khoá cặp của chỉ tiêu hai tầng () — tên cột fact, ví dụ (DriverCode, StopDate) = một cặp lái xe – ngày. Rỗng = chủ đề không có chỉ tiêu hai tầng.

Biểu thức SQL cố định (trên cột fact, không alias) mà mỗi dòng góp vào giá trị của cặp: giá trị cặp = SUM của nó.

true = tool đọc thẳng các bảng danh mục (không kỳ, không nhóm) chứ không qua AnalyticsQueryEngine — ví dụ bảng giá. Khi đó null là đúng.

Từ điển số liệu cố định trong code (docs/plan-mcp-tra-cuu-so-lieu.md §3.4) — nguồn sự thật duy nhất của chiều và chỉ tiêu: describe_catalog sinh từ đây, engine truy vấn (GĐ B) tra mã ở đây, nên mô tả và code không bao giờ lệch pha. Không tool nào nhận tên cột hay biểu thức từ người gọi — chỉ nhận MÃ trong lớp này.

Định nghĩa bám plan §2.10 (đổi/bỏ so với yêu cầu), §3.5 (tiền, khối lượng, ngày) và §3.6 (điểm dừng ĐD-1). Đổi tên hay định nghĩa một mã thì nâng AnalyticsMcpContract.Version và sửa trong cùng commit. Lớp thuần, không DB — test AnalyticsCatalogTests canh: mã duy nhất trong chủ đề, snake_case, mọi chiều có cột, mọi chỉ tiêu có định nghĩa và công thức.

Mã chủ đề cũ của yêu cầu → mã thay thế (T4 query_trips → query_vehicles, plan §2.10).

Khoảng ngày tối đa một lời gọi (plan §1).

Số chiều tối đa trong group_by.

Mốc mức cân mặc định (kg): ≤ 5; 5–10; 10–25; 25–50; 50–100; 100–300; 300–1.000; > 1.000.

Nhãn các mức cân theo mốc mặc định — cũng là giá trị của chiều bac_can.

Vì sao don_vi_sale theo công tắc mã người dù không phải mã băm — đo Việc 0 GĐ E (2026-09-26, dev): 22/58 cặp (đơn vị sale, tháng) chỉ có ĐÚNG một nhân viên kinh doanh, riêng đơn vị 29 có một sale suốt 13/13 tháng → doanh số theo đơn vị × tháng là doanh số (đầu vào hoa hồng) của một người mà ai trong công ty cũng biết là ai.

Tìm chủ đề theo mã (đã đổi alias). Null khi không có.

Mọi mã chủ đề nhận được ở tham số topic, kể cả alias.

Mọi mã chiều + chỉ tiêu (mọi chủ đề) — test hợp đồng dùng để kiểm mô tả tool không nhắc mã không tồn tại.

Bảng fact vận đơn (GĐ B).

Mã phân bố "số vận đơn một khách gửi trong một ngày" của tham số histogram_of.

Mã bộ đếm chẩn đoán của query_shipments ().

CASE f.Status WHEN 55 THEN 'delivered' … sinh từ enum — hằng trong code, cùng một luật snake_case với danh sách giá trị của chiều trang_thai.

Thuộc tính chứ KHÔNG phải trường static readonly: khởi tạo trước mọi trường khai phía dưới nó trong lớp (thứ tự khởi tạo static theo vị trí), nên trường ở đây còn null lúc dựng catalog — đã cắn ở GĐ B.

Tuần ISO dạng 2026-W33: năm ISO = năm của ngày (26 − số tuần ISO) ngày sau.

Số khách lớn nhất của chỉ tiêu ty_trong_doanh_thu_10_khach_lon_nhat — hằng trong SQL của chỉ tiêu.

Mã bộ đếm chẩn đoán của query_revenue ().

Bảng fact khiếu nại (GĐ E).

Mã bộ đếm chẩn đoán của query_claims ().

Loại sự cố của catalog theo enum — yêu cầu §5 T7 nêu hu_hong | mat | cham | khac; hệ thống có thêm thái độ phục vụ và cước phí nên tách riêng (không gộp mất thông tin). Thuộc tính (không phải trường static readonly) vì khai sau ; test canh mọi giá trị enum có mã.

Trạng thái khiếu nại của catalog theo enum — test canh mọi giá trị có mã.

CASE f.<cột> WHEN 10 THEN 'hu_hong' … ELSE 'khac' END sinh từ bảng mã — hằng trong code; null = ELSE NULL.

Bảng fact lượt qua trung tâm khai thác (GĐ E).

Mã bộ đếm chẩn đoán của query_hub_throughput ().

Chỉ tiêu hai tầng trên cặp (nhóm, ngày) của trung tâm: biểu thức gộp trên [pv] hoặc phân vị của pv.

Bảng fact điểm dừng ước lượng (GĐ C).

Ngưỡng phút mặc định của ĐD-1 khi AppConfig Analytics.StopGapMinutes thiếu hoặc sai.

Mã bộ đếm chẩn đoán của query_stops ().

Nhóm số vận đơn tại điểm — nhãn cố định 1, 2, 3-5, 5+ (trên 5); không theo weight_bins.

Chỉ tiêu hai tầng trên cặp lái xe – ngày: biểu thức gộp trên [pv] hoặc phân vị của pv.

Bảng fact lần đổ dầu (GĐ D).

Giá trị tham số table của query_vehicles.

Lần đổ dầu theo kỳ — engine trên (mặc định).

Đội xe hiện có — đọc thẳng analytics.DimVehicle, không kỳ.

Chiều nhóm được ở bảng (thuộc tính của xe; không có chiều thời gian, trạng thái phiếu).

Mã bộ đếm chẩn đoán của query_vehicles bảng nhien_lieu ().

Ngày đổ sớm nhất của tập đã lọc, dạng số ngày kể từ 2000-01-01 (0 khi không dòng nào).

Mốc của bộ đếm .

Tải trọng khai trên mức này (kg) là bất thường với đội xe tải nhẹ — chỉ cảnh báo, không sửa số (ví dụ gõ 19 thay 1,9 tấn).

dạng số SQL — hằng chuỗi cạnh hằng số, test AnalyticsVehiclesTests canh hai giá trị khớp.

Chỉ tiêu của bảng đội xe (đọc thẳng DimVehicle) — engine từ chối nó ở bảng nhien_lieu.

Bảng giá công khai lưu giá ĐÃ GỒM VAT — đo Việc 0 GĐ C (2026-09-24) bằng code tính cước: mọi khoản phí của hệ thống là giá gồm VAT, VAT được bóc ngược ra thành dòng giải trình (VatFeeCalculator: "Mọi khoản phí trong hệ thống đang là giá đã gồm VAT"), và cước tuyến trên đơn (OrderFin.Fee, vốn gồm VAT) gán thẳng từ Price.Value (FeeService.GetFeeByWeightAxis). Trang tra cước công khai /bang-gia gọi đúng FeeService.GetFee đó.

Giá trị tham số table của get_price_tables.

Cách ra cước từ bảng niem_yet — đúng luật FeeService.GetFeeByWeightAxis (test đối chiếu GetPriceTablesDbTests tính lại bằng chính FeeService). Trả trong data.cach_tinh và mô tả tool.

Lượt nạp gần nhất của một chủ đề + lượt thành công gần nhất.

Lúc xong của lượt THÀNH CÔNG gần nhất — thứ trả ra freshness.last_loaded_at.

Trạng thái lượt gần nhất (kể cả lỗi).

Mốc đầu vùng phủ của lượt nạp lại cả cửa sổ THÀNH CÔNG gần nhất; null = chưa có lượt nào (fact thiếu lịch sử).

Đơn vị quản lý xe (Truck.AgencyId).

Chi nhánh của đơn vị đó; null = đơn vị không thuộc chi nhánh nào (0.3 trả nhầm AgencyId ở khoá này).

Null = chưa khai (0.3 trả 0 và trả nguyên số khai nhầm theo kg × 1.000).

.

Tóm tắt bảng giá công khai theo (dải cự ly, loại hàng) — chi tiết là việc của get_price_tables.

Mọi danh mục describe_catalog trả khi include_lists = true.

Xã/phường của một tỉnh; null khi không xin tỉnh nào.

Đọc schema analytics cho describe_catalog.

Mã tỉnh bộ 2 cấp để kèm danh sách xã/phường; null = không kèm.

Đọc bằng Dapper qua — login chỉ đọc thành viên db_analytics_reader trên production, nên câu SQL nào lỡ chạm dbo sẽ lỗi quyền thay vì đọc được. SQL cố định, không ghép chuỗi từ người gọi; giá trị lọc duy nhất (mã tỉnh) đi qua tham số.

Trần thời gian một câu truy vấn (plan §1).

Bảy danh mục, đúng thứ tự đọc ở .

Loại đối tượng được băm — mỗi loại một tiền tố mã.

Khách hàng — KH-.

Nhân viên (kinh doanh) — NV-.

Lái xe / người bấm lấy–giao — LX-.

Xe — XE-.

Mã băm ổn định cho khách, nhân viên, lái xe, xe trong schema analytics (docs/plan-mcp-tra-cuu-so-lieu.md §3.2): HMAC-SHA256(Analytics:CodeHashKey, "<tiền tố>:<Id>") → 5 byte đầu → 8 ký tự base32, kèm tiền tố KH- / NV- / LX- / XE-.

Có khoá bí mật nên người ngoài không băm thử Id 1..N để suy ngược được (SHA thuần thì được). Cùng Id + cùng loại → cùng mã qua mọi lần nạp; khác loại → khác mã dù cùng Id (một người vừa là sale vừa là lái xe mang hai mã). 40 bit: với 10.000 khách xác suất trùng ~5·10⁻⁵ — đủ cho quy mô hiện tại. Đổi khoá = đổi toàn bộ mã (ghi trong catalog).

Hình dạng mọi mã băm — PiiOutputGuard dùng để không che nhầm chính mã của mình.

Base32 RFC 4648 (không đệm) của byte đầu — 5 byte = đúng 8 ký tự.

Kết quả một lượt nạp khiếu nại.

Khiếu nại gắn đơn nhưng đơn không có trong fact vận đơn (đơn đã xoá / ngoài cửa sổ) → không có bưu cục, kg.

Tóm tắt ghi vào LoadRun.Message (≤ 200 ký tự).

Nạp analytics.ComplaintFact (khiếu nại của khách).

Chỉ để ghi nhật ký — MỌI lượt đều dựng lại cả cửa sổ 400 ngày.

Dựng analytics.ComplaintFact (docs/plan-mcp-tra-cuu-so-lieu.md §3.2, GĐ E) từ dbo.CustomerComplaint chưa xoá, gửi trong cửa sổ 400 ngày — nguồn của query_claims (chỉ số vụ: hệ thống không lưu tiền bồi thường, bên lỗi — AN-3).

Không đọc Content, StaffResponse (chữ tự do của khách / nhân viên), không mã khiếu nại, không khách. Khiếu nại không có cột đơn vị: bưu cục gửi / nhận + kg lấy từ fact vận đơn theo OrderId (chạy trước trong cùng job). Đo Việc 0 GĐ E (2026-09-26): bảng 0 dòng trên dev (phân hệ khiếu nại mở cho app khách, dev chưa có dữ liệu) → dựng lại cả cửa sổ mỗi lượt như FuelFact; số liệu thật chỉ có trên production.

Một khiếu nại đã chọn cột — đầu vào hàm thuần .

Một khiếu nại đã chọn cột — đầu vào hàm thuần .

Khiếu nại → dòng fact của cửa sổ: ngày giờ Việt Nam, giờ giải quyết, bưu cục + kg theo vận đơn. Hàm thuần (test không DB).

Ảnh chụp trạng thái triển khai của MCP số liệu, đọc được từ trình duyệt (GET api/Analytics/DeployCheck, gác Founder) — thay cho mọi câu SQL tay trên Ladaer2 production (ràng buộc 2026-08-27, như ContentDeployCheckService).

Mật thử login chỉ đọc chạy NGAY TRONG endpoint (plan §3.9 "GĐ D"): mở ConnectionStrings:AnalyticsConnection — đúng kết nối mà tool dùng — rồi đọc analytics.LoadRun (phải được) và dbo.Customer (phải lỗi 229). Người triển khai đọc hai cờ thay vì tự đăng nhập bằng login đó vào SQL client. Số đo Việc 0 production (plan §4.2, AN-18) đọc qua CHÍNH kết nối chỉ đọc trên schema analytics: kênh bán 12 tháng, số xã có phụ phí khu vực xa, dòng tham số cước, đội xe, số lần đổ dầu — nên có số mà không ai phải mở dbo. Không lộ gì nhạy cảm: chỉ số đếm, cờ, tên login SQL, URL công khai. Không trả chuỗi kết nối, không trả khoá băm, không danh sách người. Test AnalyticsDeployCheckTests canh.

Đọc trạng thái triển khai. Không ghi một dòng nào.

Bảng của schema analytics mà migration GĐ A–E tạo — liệt kê tường minh để bảng THIẾU vẫn hiện ra (-1).

Chủ đề nạp mà tool đọc độ tươi — mỗi chủ đề một dòng trạng thái.

Khoá AppConfig ảnh hưởng hành vi MCP số liệu (giá trị không nhạy cảm).

Lỗi SQL Server "The SELECT permission was denied" — thứ login chỉ đọc PHẢI nhận khi đọc dbo.

Cấu hình đang chạy, dạng an toàn để in: cờ, không chuỗi kết nối, không khoá.

Mọi thứ đọc qua kết nối CHỈ ĐỌC: danh tính login, quyền (analytics được, dbo bị 229), số dòng từng bảng, lượt nạp, số đo Việc 0. Kết nối hỏng thì trả lỗi trong , không ném.

Số đo Việc 0 trên production (plan §4.2 GĐ D mục 4) — chỉ đọc schema analytics, chỉ số tổng hợp.

Role Analytics.Read đã seed chưa và bao nhiêu người đang có (gán thẳng hoặc qua nhóm quyền) — không trả tên.

Client OAuth (DCR + khai tay) và bao nhiêu client đã có quyền scope analytics:read — backfill migration 1705.

Analytics:Enabled — tắt thì tool trả UNAVAILABLE và job nạp bỏ qua.

Số dòng từng bảng analytics; -1 = bảng chưa có (migration chưa chạy) hoặc login chỉ đọc không đọc được.

Số đo Việc 0 production; null khi chưa đọc được (bảng chưa có / login lỗi).

SUSER_SNAME() của kết nối chỉ đọc — production phải là lada_analytics_ro. USER_NAME() trong Ladaer2. Thành viên db_analytics_reader. Đọc được analytics.LoadRun. Đọc dbo.Customer bị lỗi 229 — hàng rào lớp 4 (plan §1). Số lỗi SQL khi đọc dbo (229 là đúng); null khi đọc được. Không mở được kết nối chỉ đọc (loại lỗi + số lỗi, không chuỗi kết nối). SUSER_SNAME() của kết nối chỉ đọc — production phải là lada_analytics_ro. USER_NAME() trong Ladaer2. Thành viên db_analytics_reader. Đọc được analytics.LoadRun. Đọc dbo.Customer bị lỗi 229 — hàng rào lớp 4 (plan §1). Số lỗi SQL khi đọc dbo (229 là đúng); null khi đọc được. Không mở được kết nối chỉ đọc (loại lỗi + số lỗi, không chuỗi kết nối).

SUSER_SNAME() của kết nối chỉ đọc — production phải là lada_analytics_ro.

USER_NAME() trong Ladaer2.

Thành viên db_analytics_reader.

Đọc được analytics.LoadRun.

Đọc dbo.Customer bị lỗi 229 — hàng rào lớp 4 (plan §1).

Số lỗi SQL khi đọc dbo (229 là đúng); null khi đọc được.

Không mở được kết nối chỉ đọc (loại lỗi + số lỗi, không chuỗi kết nối).

Mốc phủ của lượt nạp lại thành công gần nhất — null với chủ đề fact nghĩa là tool còn trả NO_DATA.

Kênh bán của đơn tạo trong 12 tháng (AN-18: dev 100 % buu_cuc). Xã/phường có phụ phí khu vực xa (dev 0). Dòng tham số cước (dev chỉ DEFAULT_GOODS_CATEGORY_ID). Lượt qua trung tâm 12 tháng theo "trung tâm:chiều" (GĐ E). Lượt có trung tâm suy từ người thao tác — nhật ký kho không ghi đơn vị (AN-25). Khiếu nại 12 tháng theo giá trị số của ComplaintType (dev 0 dòng). Số cặp (đơn vị sale, tháng) có đơn gắn sale. Trong đó chỉ có MỘT nhân viên kinh doanh — số theo don_vi_sale × tháng là số của một người (dev 22/58 — lý do don_vi_sale theo công tắc mã người). Kênh bán của đơn tạo trong 12 tháng (AN-18: dev 100 % buu_cuc). Xã/phường có phụ phí khu vực xa (dev 0). Dòng tham số cước (dev chỉ DEFAULT_GOODS_CATEGORY_ID). Lượt qua trung tâm 12 tháng theo "trung tâm:chiều" (GĐ E). Lượt có trung tâm suy từ người thao tác — nhật ký kho không ghi đơn vị (AN-25). Khiếu nại 12 tháng theo giá trị số của ComplaintType (dev 0 dòng). Số cặp (đơn vị sale, tháng) có đơn gắn sale. Trong đó chỉ có MỘT nhân viên kinh doanh — số theo don_vi_sale × tháng là số của một người (dev 22/58 — lý do don_vi_sale theo công tắc mã người).

Kênh bán của đơn tạo trong 12 tháng (AN-18: dev 100 % buu_cuc).

Xã/phường có phụ phí khu vực xa (dev 0).

Dòng tham số cước (dev chỉ DEFAULT_GOODS_CATEGORY_ID).

Lượt qua trung tâm 12 tháng theo "trung tâm:chiều" (GĐ E).

Lượt có trung tâm suy từ người thao tác — nhật ký kho không ghi đơn vị (AN-25).

Khiếu nại 12 tháng theo giá trị số của ComplaintType (dev 0 dòng).

Số cặp (đơn vị sale, tháng) có đơn gắn sale.

Trong đó chỉ có MỘT nhân viên kinh doanh — số theo don_vi_sale × tháng là số của một người (dev 22/58 — lý do don_vi_sale theo công tắc mã người).

Kết quả một lượt nạp danh mục.

Tóm tắt ghi vào LoadRun.Message (≤ 200 ký tự).

Nạp bảy bảng analytics.Dim* từ bảng nghiệp vụ.

Bản sao đêm của danh mục cho MCP số liệu (docs/plan-mcp-tra-cuu-so-lieu.md §3.3): đọc bảng nghiệp vụ bằng kết nối CHÍNH (job là ngoại lệ duy nhất được đọc dbo), chỉ chép cột công khai, rồi xoá–chèn cả bảy bảng trong một transaction — chạy lại bao nhiêu lần cũng ra một bộ, và người đọc không bao giờ thấy danh mục nửa cũ nửa mới.

Lọc có chủ đích: DimVehicle không biển số, không Id hệ thống (chỉ mã băm XE-…); DimPrice chỉ dòng giá của khách mặc định chưa xoá và duy nhất (luật DefaultCustomerResolver — bảng giá công khai; đo dev 2026-09-24: 114 dòng chưa xoá thuộc khách Id 4 "LADA Express"); DimAgency không địa chỉ/điện thoại/mã số thuế. Đơn vị: khối lượng bảng giá gram → kg, cự ly Route mét → km, tải trọng xe tấn → kg. Chi nhánh bị xoá mềm và xe đã xoá vẫn chép (đánh dấu IsActive = false) vì đơn/lần đổ dầu cũ còn trỏ tới chúng. Mỗi lượt ghi một dòng chủ đề TRƯỚC khi mở transaction (dòng "running" không bị rollback cuốn mất), cập nhật thành success/failed khi xong (). Mã đơn vị hành chính chuẩn hoá số 0 đầu ().

Số ở cột tấn từ mức này trở lên là nhập nhầm theo kg — không xe nào của đội chở 100 tấn.

Truck.MaxPayload (tấn theo quy ước cột) → kg + căn cứ. Việc 0 GĐ D (2026-09-26, dev): 5/26 xe nhập theo kg (990 Tera T100, 2.350 Kia K250, 3.400 JAC N350 ×2, 4.700 Fuso Canter — đúng tải trọng thương mại của các mẫu đó tính bằng kg) nên nhân 1.000 là ra 4,7 triệu kg; 8/26 xe để 0 (chưa khai) → null chứ không phải xe chở 0 kg.

Một xe của đội xe hiện có (bản chụp đêm analytics.DimVehicle) — không biển số.

Chi nhánh của đơn vị quản lý xe (DimAgency.BranchId); null = đơn vị không thuộc chi nhánh nào.

Đọc đội xe hiện có cho bảng doi_xe của query_vehicles.

Một câu cố định trên analytics.DimVehicle + DimAgency bằng kết nối CHỈ ĐỌC — không nhận gì của người gọi; nhóm theo chiều làm ở C# () vì đội xe chỉ vài chục dòng.

Gộp đội xe theo các chiều của bảng doi_xe () — hàm thuần, test được không DB. Khoá dòng = mã chiều / chỉ tiêu của catalog.

Giá trị của một chiều ở một xe (kiểu như engine trả: int, chuỗi, null).

Giá trị một chỉ tiêu trên một nhóm xe.

Dòng theo nhóm (sắp tăng dần theo các chiều, null trước) + dòng tổng.

So từng chiều: null trước, số theo số, chữ theo thứ tự ordinal — tất định.

Kết quả một lượt nạp lần đổ dầu.

Phiếu chờ duyệt (vẫn nạp — việc đổ đã xảy ra; số có thể còn được sửa).

Phiếu bị từ chối — không nạp.

Phiếu nghi gửi trùng đã bỏ (trong cửa sổ).

Tóm tắt ghi vào LoadRun.Message (≤ 200 ký tự).

Nạp analytics.FuelFact (lần đổ dầu của đội xe).

Chỉ để ghi nhật ký — MỌI lượt đều dựng lại cả cửa sổ 400 ngày (bảng nhỏ, xem remarks của lớp).

Dựng analytics.FuelFact (docs/plan-mcp-tra-cuu-so-lieu.md §3.2, GĐ D) từ dbo.FuelRefills chưa xoá, trừ phiếu bị từ chối — nguồn bảng nhien_lieu của query_vehicles.

Mỗi lượt dựng lại CẢ cửa sổ 400 ngày (xoá–chèn trong một transaction), kể cả job đêm: đo Việc 0 GĐ D (2026-09-26, dev) cả bảng nghiệp vụ chỉ 1.447 phiếu (01/2026 → 08/2026, ~200 phiếu/tháng) nên dựng lại toàn bộ rẻ hơn theo dõi phiếu nào vừa sửa (mọi phiếu đều có UpdatedTime; duyệt / tính lại chuỗi ODO sửa phiếu cũ). Hệ quả: lượt thành công nào cũng phủ đủ cửa sổ nên cũng ghi mốc phủ (CoverFrom) — khác fact vận đơn / điểm dừng chỉ lượt nạp lại mới ghi. Phiếu gửi trùng (cùng xe, cùng ODO, cùng số tiền — lái xe bấm gửi hai lần; review GĐ D đo dev 4 nhóm, có nhóm chờ duyệt 8 tháng không ai dọn, có nhóm cả hai bản đã duyệt) chỉ giữ MỘT phiếu (ưu tiên đã duyệt, rồi Id nhỏ), ghi số bản đã bỏ vào để tool cảnh báo. Km theo ODO dựng từ chuỗi CurrentOdo của xe theo thời gian (sau khi bỏ trùng): km = ODO nay − ODO phiếu liền trước; phiếu đầu của xe dùng ODO lúc nhận xe (PreviousOdo > 0) nếu có. KHÔNG dùng FuelRefill.DistanceKm: trường đó bị khoá theo kỳ lương (IsPayrollLocked) nên phiếu chèn muộn làm hai phiếu cùng tính một quãng — review GĐ D đo dev: Σ DistanceKm vượt khoảng ODO thật ở 4 xe, tổng lệch 1.255 km. Bỏ km (null + ) khi không có ODO trước, km ≤ 0, hoặc km > (thiếu phiếu ở giữa / ODO gõ nhầm). KHÔNG loại theo lít/100 km của từng phiếu: đổ không đầy bình làm từng phiếu lệch nhưng tổng lít ÷ tổng km trên chuỗi phiếu vẫn đúng — loại một phía là thiên lệch. Tiền giữ nguyên số trên phiếu (ĐÃ GỒM THUẾ): phiếu nhập số tiền + đơn giá tại cây xăng, không lưu thuế suất hay hoá đơn tách VAT, và thuế suất VAT nhiên liệu đổi theo kỳ trong 2025–2026 — bóc bằng một hằng tự đặt là bịa số (plan §7 GĐ D, AN-22).

Km giữa hai lần đổ vượt mức này thì không dùng (≈ 3 bình dầu của xe tải nhẹ).

Một phiếu đổ dầu đã chọn cột — đầu vào hàm thuần .

Một phiếu đổ dầu đã chọn cột — đầu vào hàm thuần .

Phiếu (mọi thời điểm, chưa xoá) → dòng fact của cửa sổ [, ]: bỏ phiếu từ chối, gộp phiếu gửi trùng, dựng km từ chuỗi ODO từng xe, băm mã, ngày giờ Việt Nam. Hàm thuần theo dữ liệu đầu vào (test không DB).

Luật dùng km của một phiếu theo ODO trước (null = không có) — xem remarks của lớp.

Kết quả một lượt nạp lượt qua trung tâm khai thác.

Trung tâm khai ở AppConfig lúc nạp (rỗng = chưa khai → bảng rỗng).

Dòng có trung tâm suy từ đơn vị người thao tác (nhật ký không ghi đơn vị).

Lượt đến kết thúc vì hàng được gán giao (trung tâm phát thẳng).

Tóm tắt ghi vào LoadRun.Message (≤ 200 ký tự) — khoá hubs= được tool đọc lại để so với AppConfig hiện tại.

Nạp analytics.HubEventFact (lượt hàng đến / rời trung tâm khai thác).

Chỉ để ghi nhật ký — MỌI lượt đều dựng lại cả cửa sổ 400 ngày (xem remarks của lớp).

Dựng analytics.HubEventFact (docs/plan-mcp-tra-cuu-so-lieu.md §3.2, GĐ E) từ nhật ký đơn OrderTrack loại Nhận hàng vào kho (7) và Chuyển hàng tới bưu cục kế tiếp (8) tại các trung tâm khai ở AppConfig — nguồn của query_hub_throughput.

Đơn vị của lượt: OrderTrack.AgencyId khi có; không có thì đơn vị HIỆN TẠI của người thao tác (CreatedBy → User.AgencyId). Đo Việc 0 GĐ E (2026-09-26, dev): mọi lượt 7/8 từ 23/05/2026 có AgencyId NULL (WarehouseService, DeployService hiện không ghi — AN-25); trên dữ liệu còn ghi, đơn vị người thao tác trùng 98,9 % lượt nhập / 99,5 % lượt xuất (lệch duy nhất: một người chuyển 29 → 27). Đơn vị của nhật ký 8 là nơi ĐANG xuất hàng đi (đo cả code lẫn chuỗi nhật ký). Máy trạng thái trên chuỗi của mỗi (vận đơn, trung tâm), sắp theo (thời điểm, loại — nhập, rồi xuất, rồi gán giao khi trùng giờ); trạng thái chỉ phụ thuộc loại của sự kiện liền trước (câu LAG độc lập kiểm được): nhập khi hàng chưa ở kho → dòng den mở lượt lưu kho; nhập khi đã ở kho → quét lặp; xuất khi hàng ở kho → dòng di, ghi DwellHours vào dòng den; gán giao hàng (205) khi hàng ở kho → đóng lượt, dòng den mang LeftForDelivery, không giờ lưu kho; xuất khi không ở kho → quét xuất lặp nếu sự kiện trước là xuất, ngược lại "đi thẳng" (dòng di không có nhập — đo dev 2,1 % lượt xuất tại 29). Mốc gán giao là của VẬN ĐƠN (không theo đơn vị) nên chèn vào mọi chuỗi trung tâm của đơn đó. Review GĐ E: thiếu mốc này thì hàng giao lỗi quay về trung tâm bị nuốt thành quét lặp (đo dev: 881/1.155 cặp nhập–nhập cách ≤ 12 giờ và gần như mọi cặp cách > 24 giờ có lượt gán giao ở giữa) và lượt xuất sau đó đóng lượt lưu kho CŨ — giờ lưu kho bị thổi lên hàng trăm giờ. Đọc lùi thêm ngày trước cửa sổ để lượt đầu cửa sổ biết hàng đã nhập từ trước. Dựng lại CẢ cửa sổ mỗi lượt (như FuelFact): ~70.000 lượt / năm, và danh sách trung tâm đổi trên AppConfig chỉ cần một lượt nạp là đúng lại toàn bộ. Bưu cục gửi / nhận, kg lấy từ fact vận đơn (chạy trước trong cùng job) — một nguồn luật với query_shipments.

Khoá AppConfig liệt kê Id đơn vị là trung tâm khai thác (quyết định Q7).

Số ngày đọc lùi trước cửa sổ để biết hàng đã ở kho từ trước (đo dev: p99 lưu kho 25 giờ, max 20 ngày).

Danh sách Id trung tâm từ giá trị AppConfig ("29,25" — phẩy, chấm phẩy hoặc khoảng trắng); bỏ giá trị không phải số dương.

Một dòng nhật ký nhập / xuất kho / gán giao đã chọn cột — đầu vào hàm thuần .

Một dòng nhật ký nhập / xuất kho / gán giao đã chọn cột — đầu vào hàm thuần .

Thứ tự khi trùng thời điểm: nhập, rồi xuất, rồi gán giao (hàng vào kho rồi mới rời được).

Nhật ký (từ trước cửa sổ ngày) → dòng fact của cửa sổ [, ] tại các trung tâm : đơn vị của lượt, máy trạng thái lưu kho, giờ lưu kho, bưu cục gửi/nhận + kg từ fact vận đơn. Hàm thuần theo dữ liệu đầu vào (test không DB).

Phần của fact vận đơn mà fact trung tâm / khiếu nại cần: bưu cục gửi, nhận, kg tính cước.

Phần của fact vận đơn mà fact trung tâm / khiếu nại cần: bưu cục gửi, nhận, kg tính cước.

Cả bảng fact vận đơn (4 cột; ~32.000 dòng trên dev 2026-09-26) — một câu, thay vì lọc theo danh sách Id. Đọc SAU khi fact vận đơn của cùng job đã nạp xong nên bưu cục / kg theo đúng luật của query_shipments tại lượt này.

Khung ghi analytics.LoadRun chung của mọi builder (danh mục, fact vận đơn…): mở dòng "running" TRƯỚC khi mở transaction (để rollback không cuốn mất dòng đó), đóng thành success/failed khi xong.

Không nhận CancellationToken: lượt đã huỷ giữa chừng vẫn phải đóng dòng LoadRun. Mốc đầu vùng phủ — chỉ lượt nạp lại cả cửa sổ truyền (xem ).

Mã đơn vị hành chính chuẩn hoá: tỉnh 2 chữ số, quận/huyện 3, xã/phường 5. Đo Việc 0 GĐ B (2026-09-24): dbo.Location lưu thiếu số 0 đầu ở 126 xã bộ 2 cấp (toàn bộ tỉnh 08, hai xã tỉnh 04 — "1006" thay vì "01006"), nên so khớp theo mã mà không chuẩn hoá là lạc hẳn một tỉnh.

Danh sách cấm dữ liệu cá nhân của MCP số liệu (docs/plan-mcp-tra-cuu-so-lieu.md §3.9) — MỘT nguồn cho cả test quét schema (AnalyticsPiiSchemaTests, lớp 2) lẫn bộ lọc kết quả (, lớp 3).

Tên đơn vị hành chính, tên chi nhánh/bưu cục, tên loại hàng, tên dải cự ly là dữ liệu CÔNG KHAI — được phép qua , không phải bằng cách nới luật "Name". Thêm một cột Name vào bảng khác (ví dụ tên khách) là test đỏ ngay.

Cột chuỗi dài hơn mức này (hoặc nvarchar(max)) trong schema analytics là cấm — chữ tự do dài là nơi PII trốn.

Tên cột cấm (so khớp nguyên tên, không phân biệt hoa thường).

Mảnh tên cột cấm (chứa là cấm): PhoneNumber2, SenderAddress, ReceiverEmail…

Ngoại lệ có chủ đích: cột Name của bảng danh mục CÔNG KHAI (bảng, cột).

Lý do một cột schema analytics vi phạm; null khi hợp lệ.

Khoá JSON cấm trong kết quả tool (so khớp nguyên khoá snake_case).

Mảnh khoá JSON cấm (chứa là cấm).

Số điện thoại Việt Nam: 0 hoặc +84 rồi 9–10 chữ số, cho phép dấu cách / chấm / gạch giữa các số (0912345678, 0912.345.678, +84 912 345 678, 024 3826 1234).

Không bắt đầu ngay sau "chữ số + dấu : . ,": phần giây lẻ 7 chữ số của mốc giờ ISO (20:00.1234567) có đúng hình "0 + 8 chữ số" và từng bị che nhầm thành số điện thoại khi viết thử.

Giá trị là ngày / ngày giờ ISO-8601 — không bao giờ là dữ liệu cá nhân, bỏ qua khi quét.

Nhãn mức cân do CHÍNH engine sinh từ weight_bins ("0.125-12.125", "1000+"): phần nguyên ≤ 6 chữ số (mốc ≤ 100.000 kg), ≤ 3 số lẻ — không bao giờ đủ 10 chữ số liền của một số điện thoại, nhưng "0.125-12.125" vẫn trúng regex điện thoại (đo GĐ B: bị che nhầm). Giá trị khớp nguyên mẫu này được bộ che bỏ qua.

Khoá JSON được phép mang nhãn mức cân. Bỏ qua bộ che CHỈ ở các khoá này: mẫu nhãn cũng khớp số điện thoại viết có gạch nối ("0912-345678"), nên bỏ qua theo mọi chuỗi sẽ mở lối cho giá trị tự do trong danh mục (security review GĐ B).

true khi đường dẫn JSON (data.rows[3].bac_can, data.weight_bin_labels[1]) trỏ vào khoá nhãn mức cân.

Biển số xe Việt Nam: 29A-123.45, 51F12345, 29LD-123.45, 30E1-123.45 (không phân biệt hoa thường).

Một dòng bảng giá công khai (analytics.DimPrice) — khối lượng kg, giá gồm VAT.

Một dòng tham số cước (analytics.DimFeeConfig) kèm Id để chọn dòng hiệu lực đúng luật FeeConfigProvider.

Xã/phường bộ 2 cấp có phụ phí khu vực xa.

Mọi thứ get_price_tables cần — bảng danh mục nhỏ (vài trăm dòng), đọc một lần mỗi lời gọi.

Đọc bảng giá công khai + tham số cước từ schema analytics cho get_price_tables.

Dapper trên (login chỉ đọc db_analytics_reader trên production — câu nào lỡ chạm dbo sẽ lỗi quyền), như . Không qua AnalyticsQueryEngine: bảng giá không có kỳ, không nhóm (plan GĐ C). SQL cố định, không tham số nào của người gọi.

Năm câu, đúng thứ tự đọc ở (public để test chạy lại dưới login chỉ đọc).

Tham số một lời gọi truy vấn một chủ đề — đã đọc từ tool, CHƯA kiểm.

Mã chiều → một giá trị hoặc mảng giá trị (JToken, CLR primitive hoặc IEnumerable).

AppConfig Analytics.ExposePersonCodes: false thì mọi chiều mã người bị chặn (FORBIDDEN). Mặc định FALSE — tool nào quên truyền thì mã người đóng chứ không mở.

Một lỗi tham số: mã lỗi hợp đồng + trường (tên tham số snake_case) + câu tiếng Việt.

Một tham số Dapper của câu truy vấn — tên do engine đặt, giá trị đã kiểu hoá.

Một cột kết quả: alias SQL do engine đặt (d0, m1…) → mã trả cho trợ lý.

Giá trị float của PERCENTILE_CONT — làm tròn 3 số lẻ khi đọc.

Kế hoạch truy vấn đã kiểm: một batch SQL (tối đa 4 câu, thứ tự cố định: dòng theo trang, số nhóm, tổng, bộ đếm chẩn đoán) + tham số + ánh xạ alias → mã. Không có chuỗi nào của người gọi trong .

Mốc mức cân đang dùng (mặc định hoặc weight_bins).

true khi chiều bac_can có mặt ở group_by hoặc filters.

Mã chiều đã dùng ở filters (đã kiểm).

true = câu 1–2 (dòng theo trang + đếm nhóm) có mặt; false = không nhóm, rows là một dòng tổng.

alias → mã bộ đếm chẩn đoán ().

Thứ tự sắp xếp hiệu lực (mã, giảm dần?) — kể cả khoá phụ engine tự thêm cho phân trang tất định.

Kết quả dựng: có kế hoạch, hoặc danh sách lỗi (mã lỗi của lời gọi = mã của lỗi đầu tiên).

Bộ dựng SQL của MCP số liệu (docs/plan-mcp-tra-cuu-so-lieu.md §1, §3.4) — lớp thuần, không DB: kiểm tham số theo rồi sinh câu truy vấn trên bảng fact của chủ đề.

Không nhận SQL, tên cột hay biểu thức từ người gọi. Người gọi chỉ chọn MÃ; mã tra trong catalog (so khớp ), và mọi mảnh SQL — tên bảng, cột ngày, biểu thức chiều, biểu thức gộp — là hằng trong catalog. Mọi GIÁ TRỊ (ngày, giá trị lọc, mốc mức cân, phân trang) đi qua tham số Dapper. Alias trong câu ([d0], [m0]…) do engine đặt theo chỉ số; mã chỉ gắn lại ở C# khi đọc kết quả. Giới hạn §1: khoảng ngày ≤ 400 (RANGE_TOO_LARGE), ≤ 6 chiều (TOO_MANY_GROUPS), trang ≤ 5.000 dòng, mỗi bộ lọc ≤ 500 giá trị; thời gian chạy do bộ thực thi đặt . Hình câu: CTE base = f.* + biểu thức chiều, lọc kỳ + bộ lọc → (chỉ tiêu hai tầng) CTE pb thêm giá trị của cặp bằng hàm cửa sổ () → (tuỳ chỉ tiêu) CTE pct thêm PERCENTILE_CONT … OVER (PARTITION BY chiều) → GROUP BY chiều, ORDER BY … OFFSET/FETCH. Tổng là cùng CTE nhưng không GROUP BY (phân vị OVER ()). SQL Server cho CTE sống trong một câu nên mỗi câu của batch dựng lại CTE — ở quy mô ~30.000 dòng/năm việc lặp này không đáng kể.

Tổng giá trị lọc của mọi chiều — dưới xa trần 2.100 tham số một câu của SQL Server.

Độ dài tối đa một giá trị lọc của chiều chữ tự do (text) — bằng độ dài cột DimVehicle.Model.

Hàng rào thứ hai cho tên cột lấy từ catalog (catalog là hằng, nhưng engine không tin mù).

Alias đưa vào GROUP BY (chiều mức cân có thêm cột thứ tự để sắp theo mốc, không theo chữ).

Biểu thức SQL của một chiều — từ catalog; mức cân dựng từ tham số @wb/@wl.

CASE WHEN f.X <= @wb0 THEN @wl0 … ELSE @wlN END (labels) hoặc cùng CASE trả chỉ số 0..N (thứ tự). Cận trên gồm — khớp nhãn "5-10" nghĩa là 5 < kg ≤ 10.

FROM bảng fact f [LEFT JOIN …] WHERE kỳ AND bộ lọc — dùng chung cho CTE base và câu chẩn đoán (câu chẩn đoán cần thêm join của , ví dụ để đếm bưu cục không thuộc chi nhánh).

Chuỗi CTE cho câu có chỉ tiêu: base → (chỉ tiêu hai tầng) pb → (hạng cặp) pr → (phân vị) pct; trả tên CTE cuối để SELECT … FROM. Mọi CTE giữ nguyên số dòng của base nên chỉ tiêu một tầng (COUNT, SUM…) không đổi nghĩa.

CTE pb của chỉ tiêu hai tầng (): mỗi dòng mang giá trị của cặp nó thuộc về — [pn] = SUM() trên (nhóm, khoá cặp) — và [pv] = giá trị đó CHỈ ở một dòng mỗi cặp (ROW_NUMBER() = 1) khi > 0, còn lại NULL. Nhờ vậy COUNT([pv]) = số cặp, AVG([pv]) = bình quân trên cặp, PERCENTILE_CONT … ORDER BY [pv] = phân vị trên cặp (hàm gộp và PERCENTILE_CONT bỏ NULL) — cùng một câu GROUP BY với chỉ tiêu một tầng, không cần join lại theo chiều (chiều có thể NULL). SQL Server không có COUNT(DISTINCT a, b); cặp đếm theo cách này.

CTE pr của chỉ tiêu cần hạng cặp (): [prk] = thứ hạng của cặp theo [pv] giảm dần trong từng nhóm, CHỈ ở dòng mang [pv] (SQL Server xếp NULL cuối khi giảm dần, nên dòng NULL không chiếm hạng của cặp nào). Chỉ tiêu "N cặp lớn nhất" viết SUM(CASE WHEN [prk] <= N THEN [pv] END).

CTE pairs (một dòng / cặp khoá–ngày trong nhóm) và binned (chỉ số nhóm của phân bố).

Câu báo mã lạ: nói rõ nếu mã nằm ở mục "chưa có dữ liệu" (kèm lý do) hay là chiều/chỉ tiêu nhầm chỗ.

Nhãn mức cân: "0-5", "5-10", …, "1000+" — mốc là cận trên gồm của nhóm.

Giá trị lọc → danh sách giá trị đơn (null giữ nguyên = lọc IS NULL); null trả về = kiểu không nhận (object).

Một giá trị lọc → tham số đã kiểu hoá theo kiểu của chiều; null + lỗi khi sai kiểu/giá trị.

order_by: chuỗi "mã [asc|desc], mã [asc|desc]" — mã phải là chiều trong group_by hoặc chỉ tiêu đã chọn (với phân bố: mã nhóm, so_lan, so_van_don). Sau đó thêm mọi chiều còn lại (và nhóm phân bố) làm khoá phụ để phân trang tất định. Mặc định: theo thứ tự group_by, tăng dần.

Kết quả chạy một : dòng theo trang, tổng, số nhóm, bộ đếm chẩn đoán — khoá là MÃ.

Chạy kế hoạch truy vấn của trên schema analytics.

Dapper trên — login chỉ đọc thành viên db_analytics_reader trên production (như ), nên câu nào lỡ chạm dbo sẽ lỗi quyền. Một lần đi về DB (QueryMultiple), trần giây (plan §1).

alias SQL → mã; float của phân vị làm tròn 3 số lẻ; nhóm phân bố đổi chỉ số → nhãn.

Cách chọn đơn của một lượt nạp fact vận đơn.

Job đêm: đơn tạo trong ngày + đơn có thay đổi / lấy / giao trong ngày.

Nạp lại cả cửa sổ ngày và dọn dòng không còn trong cửa sổ.

Kết quả một lượt nạp fact vận đơn.

Số đơn đã nạp (chèn lại) vào fact.

Số dòng fact đã gỡ (đơn bị xoá, hoặc — khi nạp lại — ra ngoài cửa sổ).

Đơn không có ngày tạo — bỏ qua.

Đơn có VAT không hợp lệ trên đơn, bóc VAT bằng thuế suất cấu hình.

Đơn có bưu cục gửi / nhận suy từ bưu cục HIỆN TẠI của người bấm (đơn cũ chưa ghi cột trên đơn).

Địa chỉ trỏ tỉnh bộ 3 cấp không quy được về bộ mới (mã cũ không còn và không có trong bảng ánh xạ).

Tóm tắt ghi vào LoadRun.Message (≤ 200 ký tự).

Nạp analytics.ShipmentFact từ bảng nghiệp vụ.

Nạp đúng danh sách đơn (test, nạp tay) — vẫn ghi LoadRun.

Dựng fact vận đơn cho MCP số liệu (docs/plan-mcp-tra-cuu-so-lieu.md §3.3, §3.5) — khung như : đọc bảng nghiệp vụ bằng kết nối CHÍNH, ghi LoadRun "running" trước, xoá–chèn theo OrderId từng lô 1.000 đơn trong một transaction, ChangeTracker.Clear(), đóng LoadRun.

Tiền tính bằng thuộc tính của entity (, , ), không chép công thức sang SQL. Thuế suất của đơn = VatFee ÷ TotalFeeBeforeVat khi hợp lệ (0 < tỷ lệ ≤ 20 %), ngược lại thuế suất FeeConfig VatRate hiệu lực lúc tạo đơn (mặc định 8 %) — đo Việc 0: tháng 08/2025 gần như mọi đơn có VatFee = 0 dù cước đã gồm VAT. Mỗi khoản chưa VAT = khoản ÷ (1 + thuế suất), làm tròn đồng; riêng cước thực lấy phần còn lại để cước thực + phí thu hộ + bảo hiểm + hoàn = đúng TotalFeeBeforeVat của đơn. Ngày theo giờ Việt Nam tính trong C# () — không CAST trong SQL (bẫy +00:00). Khối lượng tính cước = Σ OrderPackage.SubTotalWeight (đo Việc 0: SubTotalWeight = max(cân thực, thể tích ÷ 6.000) × số lượng ở 99,4 % kiện, phần còn lại lệch do cắt phần lẻ gram). OrderFin.ChargeWeight không dùng: console không ghi, app khách ghi cân khai báo. Bưu cục gửi / nhận (): cột trên đơn OrderOps.AgencyPickedupId / AgencyDeliveredId khi có (ghi từ 05/2026; tháng 08/2026 trùng bưu cục người bấm 1.473/1.473 đơn); không có thì bưu cục HIỆN TẠI của người bấm lấy / giao (User.AgencyId); chưa lấy / giao thì bưu cục kế hoạch. Không dùng Order.SaleAgencyId — đó là bưu cục doanh số (HQ chiếm phần lớn). Tỉnh quy về bộ 34 tỉnh mới: mã tỉnh 3 cấp cũ còn tồn tại thì giữ, 29 mã đã đóng tra analytics.ProvinceCodeMap (AN-15). Bộ danh mục của địa chỉ lấy theo Location.LevelType của tỉnh, KHÔNG theo OrderAddress.AddressLevelType (đo: cờ này = 0 ở mọi đơn trước 05/2026). Mã xã giữ theo đúng bộ của địa chỉ.

Job đêm nạp lại mọi đơn tạo trong chừng này ngày (trạng thái đơn trẻ còn đổi).

Job đêm nạp lại đơn có thay đổi (UpdatedTime bảng đơn / tài chính / vận hành / mốc thời gian) hoặc lấy / giao trong chừng này ngày.

Cửa sổ nạp lại toàn bộ (giới hạn khoảng ngày của tool).

Thuế suất hợp lệ tối đa suy từ VatFee của đơn — trên mức này coi là dữ liệu lệch, dùng thuế suất cấu hình.

Mã tỉnh bộ 2 cấp (đã chuẩn hoá).

Mã tỉnh cũ đã đóng → mã mới (AN-15).

ActionSource của track tạo đơn → kênh bán. Nội bộ (app/web) gộp cả tổng đài — không tách được (AN-6).

Bóc VAT (plan §3.5): thuế suất theo đơn khi VatFee hợp lệ, không thì FeeConfig lúc tạo đơn (mặc định 8 %). Cước thực lấy phần còn lại để tổng các khoản chưa VAT = đúng .

FeeConfig VatRate hiệu lực lúc tạo đơn (theo EffectiveFrom/To); không có dòng nào → 8 % mặc định.

Một lượt bấm lấy/giao — đầu vào của thuật toán ĐD-1 ().

| .

Mã băm người bấm LX-….

Thời điểm bấm (OrderTimeTrack.PickupTime / DeliveryDate).

OrderAddress.WardId của địa chỉ gửi (lấy) / nhận (giao); 0 = không có.

Địa chỉ ĐÃ CHUẨN HOÁ (); null = trống. Chỉ sống trong bộ nhớ.

Kết quả một lượt nạp điểm dừng.

Số lượt bấm đã dựng thành điểm.

Lượt có trong fact nhưng không đọc được thời điểm bấm, hoặc ngày bấm lệch khỏi khoảng (fact cũ hơn bảng nghiệp vụ).

Lượt không có địa chỉ chuỗi / không có xã — mỗi lượt thành một điểm riêng.

Tóm tắt ghi vào LoadRun.Message (≤ 200 ký tự).

Nạp analytics.StopFact (điểm dừng ước lượng ĐD-1).

Nightly = 35 ngày gần nhất, lùi tới lần nạp thành công trước nếu cũ hơn, và tới ngày lấy/giao sớm nhất của đơn mà lượt fact vận đơn gần nhất vừa nạp lại; Rebuild = cả cửa sổ 400 ngày + dọn + mốc phủ.

Dựng lại đúng khoảng ngày (test, nạp tay) — vẫn ghi LoadRun, không ghi mốc phủ.

Dựng điểm dừng ước lượng ĐD-1 (docs/plan-mcp-tra-cuu-so-lieu.md §3.6) từ analytics.ShipmentFact (ngày lấy/giao, mã người bấm, kiện, kg, bưu cục, địa bàn — một nguồn luật với query_shipments) cộng bảng nghiệp vụ cho đúng hai thứ fact không có: thời điểm bấm và địa chỉ để so trùng.

Địa chỉ chỉ sống trong bộ nhớ: đọc OrderAddress.Address1, chuẩn hoá (), so trùng, rồi bỏ — bảng StopFact không có cột địa chỉ nào (hàng rào dữ liệu cá nhân lớp 1). ĐD-1 (, hàm thuần): các lượt của một người bấm trong một ngày giờ Việt Nam sắp theo thời điểm; lượt nối vào điểm đang mở khi cùng loại lượt, cùng xã (WardId), cùng địa chỉ chuẩn hoá và cách lượt trước ≤ ngưỡng AppConfig Analytics.StopGapMinutes. Việc 0 GĐ C (2026-09-24) bỏ điều kiện "toạ độ cách nhau ≤ 50 m" của plan: chỉ 7,3 % cặp lượt có toạ độ ở cả hai đầu. Ghi theo từng tháng: một transaction xoá–chèn các ngày của tháng đó, nên bảng vẫn đọc được trong lúc chạy và chạy lại nhiều lần ra một bộ. Mỗi lượt ghi một dòng LoadRun chủ đề stops; lượt nạp lại cả cửa sổ ghi mốc phủ (CoverFrom) như fact vận đơn.

Lượt đầu của điểm cách lượt cuối của điểm trước dưới chừng này giây mà khác xã → cờ bấm dồn.

Job đêm dựng lại chừng này ngày gần nhất — cùng cửa sổ đơn trẻ của fact vận đơn.

AppConfig Analytics.StopGapMinutes; thiếu, sai kiểu hoặc ngoài 1–240 → 30 + log cảnh báo.

Giá trị AppConfig ngưỡng phút → số nguyên trong [, ]; sai → null.

(xã, địa chỉ chuẩn hoá) của mọi bưu cục/chi nhánh chưa xoá — để đánh dấu điểm dừng tại bưu cục.

Chuẩn hoá chuỗi địa chỉ để so trùng: bỏ dấu tiếng Việt (đ → d), chữ thường, mọi ký tự không phải chữ/số thành khoảng trắng, gộp khoảng trắng. "Số 12, Ngõ 34/5 Đường Láng" và "so 12 ngo 34 5 duong lang" là một. Trống → null.

Gom lượt thành điểm dừng theo ĐD-1. Lượt nối vào điểm đang mở khi CÙNG người bấm, CÙNG ngày giờ Việt Nam, CÙNG loại lượt, CÙNG xã (), CÙNG địa chỉ chuẩn hoá (khác null) và cách lượt ngay trước ≤ phút (biên gồm). Lượt cùng thời điểm sắp theo mã vận đơn cho tất định.

Cùng xã: cùng WardId; hoặc hai địa chỉ thuộc HAI BỘ danh mục (3 cấp cũ / 2 cấp mới — đơn tạo hai bên mốc 06/2026 giao cùng ngày) mà cùng tỉnh đã quy về bộ mới: WardId hai bộ không so được và chưa có ánh xạ xã (AN-5), nên để điều kiện cùng địa chỉ chuẩn hoá quyết định (review GĐ C).

Khác xã CHẮC CHẮN: cùng bộ danh mục mà khác WardId (khác bộ thì không kết luận được).

Kết quả quét: dữ liệu đã che + cảnh báo cho trợ lý + số chỗ phải che (để log lỗi).

Lớp 3 của hàng rào dữ liệu cá nhân (docs/plan-mcp-tra-cuu-so-lieu.md §1, §3.9): quét MỌI kết quả tool số liệu trước khi trả — khoá JSON thuộc danh sách cấm bị bỏ hẳn; giá trị chuỗi chứa số điện thoại, email, biển số bị che — mỗi chỗ ghi một warnings[] để trợ lý biết số liệu có chỗ bị che, và tool log LỖI để người vận hành đi tìm nguồn rò.

Hai lớp trước (schema không có cột cấm; login chỉ đọc chỉ thấy schema analytics) chặn cột. Lớp này chặn GIÁ TRỊ: chữ tự do trong cột công khai (ví dụ ai đó gõ số điện thoại vào tên bưu cục, gõ biển số vào mẫu xe) — thứ không test schema nào bắt được. Mã băm của chính hệ thống (KH-3HT7ZPQA) có thể trùng hình dạng biển số, nên giá trị khớp nguyên được bỏ qua.

Số cảnh báo chi tiết tối đa — quá thì gộp một dòng, không để warnings[] phình theo dữ liệu bẩn.

Interface cho service quản lý AppConfig

Tìm kiếm AppConfig với SmartTable

Tham số tìm kiếm Kết quả tìm kiếm

Tạo hoặc cập nhật AppConfig

Model AppConfig Kết quả thao tác

Lấy AppConfig theo Id

Id của AppConfig AppConfig model

Xóa AppConfig

Id của AppConfig Kết quả xóa

Reload cache cho tất cả applications

Kết quả reload

Implementation của AppConfigManagementService

Khoá của trợ lý AI Cổng nhượng quyền chỉ sửa ở màn Cấu hình trợ lý (kiểm model, hạn mức, văn bản nền, dấu ghim nhà cung cấp) — security review GĐ G2a.

Làm mới cache của Lada.Framework sau khi sửa cấu hình.

Hai lớp cache song song, hai sơ đồ khoá khác nhau. Lớp này ghi qua ICacheService với tiền tố "AppConfig:", còn Lada.Framework.Infrastructures.Services.AppConfigService — nơi phần lớn code nghiệp vụ thật sự ĐỌC cấu hình — dùng IMemoryCache với tiền tố "AppConfig_" và TTL 1 giờ. Xoá tiền tố này không chạm được tiền tố kia. Hệ quả trước khi có hàm này: sửa một khoá qua màn quản trị (kể cả bấm "reload cache") vẫn mất tới một giờ mới có hiệu lực với code đọc qua Framework, mà không có gì báo cho người vận hành biết. Phát hiện khi bấm thật GĐ D — nới cửa sổ Kpi.RecloseWindowDays rồi gọi ReloadCache mà API vẫn đọc giá trị cũ. Đây không phải chuyện nhỏ với phân hệ KPI: Kpi.EffectiveFrom và (từ GĐ E) Kpi.EnableBonus đều đọc qua Framework, và đều là công tắc đổi được tiền.

Tìm kiếm AppConfig với SmartTable

Tham số tìm kiếm Kết quả tìm kiếm

Tạo hoặc cập nhật AppConfig

Model AppConfig Kết quả thao tác

Lấy AppConfig theo Id

Id của AppConfig AppConfig model

Xóa AppConfig

Id của AppConfig Kết quả xóa

Reload cache cho tất cả applications

Kết quả reload

Adapter để chuyển đổi Framework IAppConfigService thành Backend IAppConfigService (Backward compatibility)

Interface cho dịch vụ triển khai

Lấy danh sách vị trí triển khai

Trạng thái đơn hàng Trạng thái vật lý đơn hàng Loại địa chỉ Danh sách vị trí triển khai

Lấy danh sách vị trí triển khai

Trạng thái đơn hàng Trạng thái vật lý đơn hàng Loại địa chỉ Danh sách vị trí triển khai

Lấy danh sách đơn hàng triển khai

Tham số bảng thông minh Kết quả bảng thông minh chứa danh sách đơn hàng

Gán đơn hàng cho người dùng để lấy hàng

Mô hình gán đơn hàng Kết quả gán đơn hàng

Bỏ gán đơn hàng cho người dùng

Mô hình bỏ gán đơn hàng Kết quả bỏ gán đơn hàng

Lấy danh sách giám sát triển khai

Số trang Kích thước trang Danh sách giám sát triển khai và tổng số bản ghi

Lấy chi tiết đơn hàng triển khai

Tham số bảng thông minh Kết quả bảng thông minh chứa chi tiết đơn hàng

Lấy toạ độ chính xác cho các địa chỉ đơn hàng còn trống bằng Google Geocoding, đồng thời lưu lại vào CSDL để lần sau không phải gọi Google nữa.

Danh sách Id của OrderAddress cần geocode Id người dùng thao tác Tên người dùng thao tác Danh sách toạ độ đã lấy được (bỏ qua địa chỉ geocode thất bại)

Gán giao hàng

Model gán

Gán trung chuyển

Model gán

Sắp xếp thứ tự hiển thị đơn hàng

Danh sách đơn hàng với thứ tự mới ID người dùng thao tác Tên người dùng thao tác Kết quả sắp xếp

Lấy danh sách vị trí triển khai theo loại triển khai

Lấy danh sách đơn hàng triển khai theo loại triển khai

Gán đơn hàng cho nhân viên theo loại triển khai

Cập nhật đơn hàng sang chiều trả về (OrderDirection = ToReturn, Status = WaitToReturn)

Bên phát hoàn dự kiến điều phối chọn (Ví v2 plan §3.8.1); null = bưu cục đã lấy hàng.

Chi nhánh LADA đang hoạt động — lựa chọn "Bên phát hoàn" ngoài mặc định bưu cục đã lấy hàng.

Triển khai dịch vụ triển khai

Lấy danh sách vị trí triển khai

Trạng thái đơn hàng Trạng thái vật lý đơn hàng Loại địa chỉ Danh sách vị trí triển khai

Lấy danh sách đơn hàng triển khai

Tham số bảng thông minh Kết quả bảng thông minh chứa danh sách đơn hàng

Lấy danh sách giám sát triển khai

Số trang Kích thước trang Danh sách giám sát triển khai và tổng số bản ghi

Lấy chi tiết đơn hàng triển khai

Tham số bảng thông minh Kết quả bảng thông minh chứa chi tiết đơn hàng

Geocode các địa chỉ đơn hàng chưa có toạ độ qua Google, rồi lưu lại vào CSDL. Nhờ lưu lại nên mỗi địa chỉ chỉ tốn đúng một lần gọi Google trong toàn hệ thống.

Danh sách Id của OrderAddress cần geocode Id người thao tác Tên người thao tác Danh sách toạ độ đã lấy được (bỏ qua địa chỉ geocode thất bại)

Gán đơn hàng cho người dùng để lấy hàng

Mô hình gán đơn hàng Kết quả gán đơn hàng

Bỏ gán đơn hàng cho người dùng

Mô hình bỏ gán đơn hàng Kết quả bỏ gán đơn hàng

Gán đơn hàng cho người dùng để giao hàng

Mô hình gán đơn hàng Kết quả gán đơn hàng

Một đơn đã qua kiểm trạng thái trong lô gán, chờ ghi: đổi trạng thái trong bộ nhớ.

Một đơn đã qua kiểm trạng thái trong lô gán, chờ ghi: đổi trạng thái trong bộ nhớ.

Ghi một lô gán. Người được gán thuộc chi nhánh BẬT VÍ (Ví v2, plan §3.3 "Xuất kho", Docs §5) → TỪNG đơn một giao dịch: đơn đang ở chi nhánh khác đi qua điểm chặn (khoá ví bưu cục phát, đọc số dư sau khoá, giữ E2 / E3 cùng giao dịch); không đủ → đơn ĐÓ bị từ chối kèm số thiếu trong , đơn khác vẫn đi. Hàng đang ở chính chi nhánh được gán (bưu cục gán lái xe của mình) không phải mốc xuất kho — không kiểm. Người được gán không bật ví → đường cũ: một UpdateAsync cả lô, kết quả cả lô như trước (test đối chiếu đơn LADA thuần).

Chi nhánh của người được gán — bên phát P (0 = không kiểm ví). Gán trung chuyển (không phải gán giao): tới lái xe chi nhánh LADA là việc của kho, không phải xuất kho cho bên phát.

Gán đơn hàng cho người dùng để giao hàng

Mô hình gán đơn hàng Kết quả gán đơn hàng

Lấy danh sách vị trí triển khai theo loại triển khai (sử dụng DeployType)

Lấy danh sách đơn hàng triển khai theo loại triển khai (sử dụng DeployType)

Gán đơn hàng cho nhân viên theo loại triển khai (sử dụng DeployType)

Cập nhật đơn hàng sang chiều trả về Set OrderDirection = ToReturn, Status = WaitToReturn

Interface for operation service.

Searches for orders based on the provided parameters.

Search parameters. User ID. Search results.

Gets an order by its ID.

Order ID. User ID. Order item.

Picks up an order.

Pickup model. Order track result.

Giao hàng thành công

Implementation of the operation service.

Initializes a new instance of the class.

Location service. User service. Order operations repository. Order financial repository. Order track service. Order repository. Unified media service. Database connection.

Searches for orders based on the provided parameters.

Search parameters. User ID. Search results.

Gets an order by its ID.

Order ID. User ID. Order item.

Picks up an order.

Pickup model. Order track result.

Giao hàng.

model. Order track result.

Validates the update status of an order.

Current order status. Current physical status. New order status. New physical status. True if the update is valid, otherwise false.

Giao diện cho WarehouseService

Xử lý quá trình nhập kho cho một đơn hàng.

Mô hình nhập kho chứa thông tin đơn hàng. Kết quả nhập kho chỉ ra kết quả của thao tác.

Lấy danh sách tài xế theo ID của đại lý với tùy chọn lọc từ khóa và phân trang.

ID của đại lý. Từ khóa tùy chọn để lọc tài xế. Số trang cho phân trang. Kích thước trang cho phân trang. Danh sách các đối tượng DriverInfoItem.

Lấy danh sách đơn hàng cần inbound của 1 lái xe

Id của lái xe Số trang Số bản ghi / trang

Lớp dịch vụ để xử lý các hoạt động của kho hàng.

Khởi tạo một thể hiện mới của lớp .

Kết nối cơ sở dữ liệu. Kho lưu trữ các hoạt động đơn hàng. Kho lưu trữ đơn hàng. Dịch vụ theo dõi đơn hàng. Dịch vụ người dùng.

Lấy danh sách tài xế theo ID của đại lý với tùy chọn lọc từ khóa và phân trang.

ID của đại lý. Từ khóa tùy chọn để lọc tài xế. Số trang cho phân trang. Kích thước trang cho phân trang. Danh sách các đối tượng DriverInfoItem.

Lấy danh sách đơn hàng cần inbound của 1 lái xe

Id của lái xe Số trang Số bản ghi / trang

Xử lý quá trình nhập kho cho một đơn hàng.

Mô hình nhập kho chứa thông tin đơn hàng. Kết quả nhập kho chỉ ra kết quả của thao tác.

Xác thực trạng thái cập nhật của một đơn hàng.

Trạng thái hiện tại của đơn hàng. Trạng thái vật lý hiện tại của đơn hàng. Trạng thái mới của đơn hàng. Trạng thái vật lý mới của đơn hàng. True nếu cập nhật hợp lệ, ngược lại là false.

Interface cho dịch vụ xuất Excel vùng phủ chi nhánh

Xuất Excel vùng phủ của tất cả chi nhánh (hoặc lọc theo danh sách agencyIds)

Danh sách AgencyId được phép xem (null = tất cả) Kết quả xuất file

Dịch vụ xuất Excel vùng phủ chi nhánh

Xuất Excel vùng phủ chi nhánh

Lấy dữ liệu vùng phủ gộp theo chi nhánh

Tạo file Excel

Kết quả xuất Excel vùng phủ chi nhánh

Dòng dữ liệu vùng phủ chi nhánh (dùng nội bộ cho Excel)

Interface cho service quản lý vùng phủ của đại lý

Lấy thông tin vùng phủ của agency

ID của đại lý Thông tin vùng phủ

Thêm location vào agency

Thông tin các location cần thêm Kết quả thêm

Xóa location khỏi agency

Thông tin các location cần xóa Kết quả xóa

Lấy danh sách location chưa được chọn cho agency dưới dạng cây

ID của đại lý ID của location cha (0 = lấy tỉnh/thành phố, >0 = lấy con của location đó) Danh sách location dưới dạng cây

Service quản lý vùng phủ của đại lý Logic: Mỗi phường/xã (Level 3) chỉ thuộc về 1 Agency duy nhất Sử dụng Location.AgencyId để xác định ownership

Khởi tạo một thể hiện của .

Repository của Agency Repository của Location

Lấy thông tin vùng phủ của agency Logic: Lấy tất cả Location có AgencyId = agencyId, sau đó build hierarchy

Thêm location vào agency Logic: 1. Validate locations exist và là Level 3 (phường/xã) 2. Kiểm tra location chưa thuộc agency khác 3. Set AgencyId cho các location

Xóa location khỏi agency Logic: 1. Validate locations exist và thuộc agency này 2. Set AgencyId = 0 cho các location

Lấy danh sách location chưa được gán cho bất kỳ agency nào dưới dạng cây Logic: Location.AgencyId = 0 hoặc NULL = chưa được gán

Tìm kiếm đại lý

Tạo/cập nhật đại lý

Lấy thông tin đại lý

Xóa đại lý

Cập nhật trạng thái đại lý

Lấy danh sách chi nhánh

Lấy danh sách AgencyId bao gồm agency hiện tại và tất cả agency con cháu (đệ quy). Kết quả được cache 10 phút.

ID agency gốc Danh sách tất cả AgencyId trong nhánh

Lấy danh sách AgencyId bao gồm agency hiện tại và tất cả agency con cháu. Cache kết quả 10 phút.

Interface cho dịch vụ EndPoints.

Tìm kiếm EndPoints dựa trên tham số SmartTable.

Tham số SmartTable. Kết quả tìm kiếm dưới dạng SmartTableResult.

Tạo mới hoặc cập nhật EndPoints.

Mô hình EndPoints. Kết quả của việc tạo mới hoặc cập nhật.

Lấy EndPoints theo Id.

Id của EndPoints. Mô hình EndPoints.

Xóa EndPoints theo Id.

Id của EndPoints. Người dùng hiện tại. Kết quả của việc xóa.

Tự động tạo EndPoints.

Người dùng hiện tại. Kết quả của việc tự động tạo.

Lấy thông tin điểm đầu cuối EndPoints.

Id của EndPoints. Thông tin điểm đầu cuối EndPoints.

Dịch vụ EndPoints.

Khởi tạo một instance của EndPointsService.

Repository của EndPoints. Repository của Location.

Tìm kiếm EndPoints dựa trên tham số SmartTable.

Tham số SmartTable. Kết quả tìm kiếm dưới dạng SmartTableResult.

Thêm thông tin bổ sung cho danh sách EndPointsItem.

Danh sách EndPointsItem. Danh sách EndPointsItem đã được thêm thông tin bổ sung.

Tạo mới hoặc cập nhật EndPoints.

Mô hình EndPoints. Kết quả của việc tạo mới hoặc cập nhật.

Tạo mới EndPoints.

Thực thể EndPoints. Kết quả của việc tạo mới.

Cập nhật EndPoints.

Thực thể EndPoints. Kết quả của việc cập nhật.

Lấy EndPoints theo Id.

Id của EndPoints. Mô hình EndPoints.

Xóa EndPoints theo Id.

Id của EndPoints. Người dùng hiện tại. Kết quả của việc xóa.

Tự động tạo EndPoints theo từng batch 1000 bản ghi để tránh delay.

Người dùng hiện tại. Kết quả của việc tự động tạo.

Lấy thông tin điểm đầu cuối EndPoints.

Id của EndPoints. Thông tin điểm đầu cuối EndPoints.

Dịch vụ xử lý các thao tác liên quan đến địa điểm

Tìm kiếm địa điểm theo tham số SmartTable

Tham số tìm kiếm Kết quả tìm kiếm

Tạo mới hoặc cập nhật địa điểm

Thông tin địa điểm Kết quả tạo mới hoặc cập nhật

Lấy danh sách gợi ý địa điểm theo từ khóa

Từ khóa tìm kiếm Loại gợi ý ID cha Danh sách gợi ý

Lấy danh sách gợi ý địa điểm theo ID

Loại gợi ý ID địa điểm Danh sách gợi ý

Lấy thông tin địa điểm theo ID

ID địa điểm Thông tin địa điểm

Lấy danh sách địa điểm theo danh sách ID

Danh sách ID Danh sách địa điểm

Xóa địa điểm theo ID

ID địa điểm Người dùng hiện tại Kết quả xóa

Lấy địa chỉ đầy đủ theo ID và cấp độ

ID địa điểm Cấp độ địa điểm Địa chỉ đầy đủ

Lấy danh sách địa chỉ đầy đủ theo danh sách ID và cấp độ

Danh sách ID Cấp độ địa điểm Danh sách địa chỉ đầy đủ

Cập nhật tọa độ latlong cho các phường/xã chưa có

Cập nhật khoảng cách và văn bản khoảng cách của EndPoints

Cập nhật tên kết hợp

Tìm kiếm địa điểm tự động hoàn thành

Từ khóa tìm kiếm Kết quả tự động hoàn thành

Lấy chi tiết địa điểm theo Place ID

Place ID Chi tiết địa điểm

Import dữ liệu Location ĐVHC mới từ database Antin

Connection string tới database AntinDb Kết quả import

Import dữ liệu Location 2 cấp từ file Excel. Format: Tỉnh/TP (Mã) | Tên Xã mới | Mã Xã mới

File Excel upload Kết quả import

Cập nhật tọa độ lat/long hàng loạt cho các location theo danh sách ID

Danh sách ID location cần cập nhật Kết quả cập nhật

Lấy toạ độ (lat/long) của một địa chỉ dạng văn bản qua Google Geocoding API. Dùng khi địa chỉ chưa được ghim toạ độ — ví dụ địa chỉ đơn hàng nhập tay.

Địa chỉ đầy đủ, ví dụ "12 Lê Lợi, Phường Bến Nghé, TP Hồ Chí Minh" Toạ độ tìm được; Result = Failed nếu Google không trả kết quả

Lấy danh sách gợi ý địa điểm theo từ khóa

Từ khóa tìm kiếm Loại gợi ý ID cha Danh sách gợi ý

Lấy danh sách gợi ý địa điểm theo ID

Loại gợi ý ID địa điểm Danh sách gợi ý

Lấy toạ độ của một địa chỉ dạng văn bản qua Google Geocoding API. Chỉ là lớp bọc công khai cho đã dùng nội bộ, để service khác (Deploy) geocode được địa chỉ đơn hàng mà không lặp lại logic gọi Google.

Import dữ liệu Location ĐVHC mới từ database Antin. Đọc Location 2 cấp từ AntinDb, insert vào LADA, và cập nhật MappedWardId cho Location 3 cấp.

DTO nội bộ để đọc Location từ AntinDb

Import dữ liệu Location 2 cấp từ file Excel. Format cột: Tỉnh/TP (Mã) | Tên Xã mới | Mã Xã mới

Luật "ai thấy gì" của trang Bản đồ tô phường/xã (rule quyen-hien-thi).

Hàm thuần — nhận role đã phân giải qua IUserRoleResolver, không chạm DB hay HttpContext. CanManage không kéo theo CanView: các lời gọi nạp trang đòi đúng MapWardList.View, người chỉ có Manage mà thấy trang thì ăn 403 ngay khi nạp danh sách.

Vai bỏ qua mọi kiểm tra role — ẩn nút của Founder là dựng hàng rào không có thật.

Role của các lời gọi đọc: lists, get-by-id, provinces, wards.

Role của các lời gọi ghi: create-or-update, delete.

Role đã phân giải; null hoặc rỗng = không có role nào

Cờ hiển thị của trang Bản đồ tô phường/xã — mỗi cờ gác đúng một bó quyền

Cờ hiển thị của trang Bản đồ tô phường/xã — mỗi cờ gác đúng một bó quyền

Danh sách phường/xã để tô trên trang Bản đồ tô phường/xã. Chỉ nhận phường/xã bộ 2 cấp (LevelType = 2, Level = 3) — ranh giới trên bản đồ là của đơn vị sau sáp nhập, ghép theo Location.Code.

Tỉnh/thành bộ 2 cấp kèm số phường/xã — bước chọn tỉnh đầu trang

Toàn bộ phường/xã bộ 2 cấp của một tỉnh; null khi Id không phải tỉnh bộ 2 cấp

Tỉnh/thành bộ 2 cấp còn hiệu lực — Level = 1 (bộ 2 cấp không có cấp huyện)

Phường/xã bộ 2 cấp còn hiệu lực

Luật "ô Menu.AllowRoles có mở cho người này không": so đúng TÊN role, không so chuỗi con. Trước 2026-10-10 MenuService dùng AllowRoles.Contains(role) nên Lead.Search khớp ,FranchiseLead.Search, — mọi Sale thấy menu "Đăng ký nhượng quyền" (H-4, plan nhượng quyền website §9), lái xe có role Driver thấy "Đánh giá lái xe". Hàm thuần để có test; số đo trước khi vá: Sql/KhaoSat/MenuAllowRoles.KhaoSat.sql.

Ô rỗng = ai có role cũng thấy. Ô có chữ thì tách theo dấu phẩy (bọc phẩy hai đầu hay không đều được), bỏ khoảng trắng, và phải có một tên trùng nguyên văn (phân biệt hoa thường như luật cũ) với role của người dùng.

Các mục menu người dùng thấy, xếp theo đúng thứ tự ghép của luật cũ: ô rỗng trước, rồi theo role ĐẦU TIÊN của người dùng mở được mục đó. MenuService sắp tiếp bằng OrderBy(DisplayOrder) (ổn định) nên các mục trùng DisplayOrder giữ nguyên chỗ trên sidebar như trước bản vá.

Tên role (bỏ khoảng trắng hai đầu) → vị trí lần đầu xuất hiện trong danh sách role của người dùng.

null = không mở; -1 = ô rỗng; còn lại = vị trí role đầu tiên của người dùng có tên trong ô.

Dựng cho một vật chủ khối nội dung.

Media domain lấy ĐÚNG nguồn mà ảnh tải lên dùng để ghép URL (ImageService.GetUrlBySystemPath): khoá AppConfig Media.Domain, lùi về MediaProcessingSettings.Domain. Lấy nguồn khác là ảnh vừa tải qua UploadTopicContentPicture bị chính validator từ chối.

Giao diện cho dịch vụ quản lý danh mục.

Tìm kiếm danh mục.

Thông số tìm kiếm. Kết quả tìm kiếm danh mục.

Lấy cây danh mục.

Từ khóa tìm kiếm. Danh sách cây danh mục.

Tạo hoặc cập nhật danh mục.

Thông tin danh mục. Kết quả của thao tác.

Lấy thông tin danh mục qua Id.

Id của danh mục. Thông tin danh mục.

Xóa danh mục.

Id của danh mục. Kết quả của thao tác.

Triển khai dịch vụ quản lý danh mục.

Khởi tạo một thể hiện của .

Đối tượng IRepository của Category. Dịch vụ quản lý UrlRecord.

Tạo hoặc cập nhật danh mục.

Thông tin danh mục. Kết quả của thao tác.

Tạo danh mục.

Thông tin danh mục. Kết quả của thao tác.

Cập nhật danh mục.

Thông tin danh mục. Kết quả của thao tác.

Mã nhánh nội dung luôn được lưu IN HOA và không khoảng trắng ("a1" → "A1"), vì kho nội dung tra danh mục bằng đúng chuỗi này. Chuỗi rỗng lưu thành null: một mã rỗng không phải là mã, và để nguyên chuỗi rỗng thì chỉ số duy nhất sẽ coi mọi danh mục chưa gắn mã là trùng nhau.

Xóa danh mục.

Id của danh mục. Kết quả của thao tác.

Lấy thông tin danh mục qua Id.

Id của danh mục. Thông tin danh mục.

Tìm kiếm danh mục.

Thông số tìm kiếm. Kết quả tìm kiếm danh mục.

Lấy cây danh mục.

Từ khóa tìm kiếm. Danh sách cây danh mục.

Lấy danh sách con của danh mục.

Danh mục. Danh sách danh mục. Cấp độ. Danh sách con của danh mục.

Quy ước ghi các khoá liên kết tuỳ chọn mới thêm cho CMS ở đợt bưu cục (Product.RouteFromCityId/RouteToCityId, Post.AgencyId): null = client không gửi → giữ nguyên, 0 = bỏ liên kết, > 0 = đặt.

Form Dịch vụ / Bài viết trước GĐ B1 chưa có các ô này nên gửi null ở mọi lần lưu — gán thẳng là mỗi lần lưu xoá mất liên kết marketing đã đặt (bẫy DTO nullable, docs/plan-buu-cuc.md §7). Số âm bị chặn ở bước validate trước khi tới đây.

Giá trị mới khi SỬA bản ghi có sẵn.

Giá trị khi TẠO mới — AutoMapper chép nguyên 0 sang entity, 0 phải về null kẻo đụng khoá ngoại.

Đích hợp lệ của Product.RouteFromCityId/RouteToCityId: tỉnh bộ 2 cấp (sau sáp nhập). Dùng CHUNG cho bước validate lúc lưu và cho danh sách ô chọn của form — ô chọn đưa ra tỉnh nào thì lưu tỉnh đó phải qua, không trôi dạt. Xoá mềm do IRepository.Query() lọc.

Đích hợp lệ của Post.AgencyId: chi nhánh LADA hoặc chi nhánh nhượng quyền (không nhận khu vực, phòng ban). Dùng CHUNG cho PostService.ValidateAgencyAsync và PostService.AgencyOptions — cùng lý do như . Xoá mềm do IRepository.Query() lọc.

Giá trị gửi lên có phải kiểm hợp lệ không: chỉ khi ĐẶT một liên kết khác liên kết đang lưu. Form luôn gửi lại giá trị đang có (null = giữ, 0 = bỏ); kiểm lại cả giá trị không đổi thì một liên kết về sau hết hợp lệ (bưu cục bị xoá, tỉnh bị gộp) chặn MỌI lần lưu bài/trang — kể cả sửa một lỗi chính tả (review B1).

Dịch vụ cấu hình tính giá cho danh mục hàng hóa động

Mã thuộc tính chỉ cho phép chữ thường, số và gạch ngang

Role được phép bật/tắt trục bảng giá. Người có GoodsCategoryConfig.CreateOrUpdate sửa được cấu hình, nhưng đổi trục là đổi cách tính tiền của cả danh mục nên cần thêm cửa hẹp hơn.

Tìm kiếm cấu hình danh mục hàng hóa

Lấy cấu hình theo Id (kèm thuộc tính và lựa chọn còn hiệu lực)

Lấy cấu hình theo danh mục hàng hóa (dùng cho form lên đơn và app khách)

Lấy toàn bộ cấu hình đang bật (kèm thuộc tính và lựa chọn còn hiệu lực)

Tạo mới hoặc cập nhật cấu hình kèm đồng bộ thuộc tính + lựa chọn

Xóa mềm cấu hình kèm toàn bộ thuộc tính và lựa chọn con

Tính tổng phí thuộc tính theo lựa chọn của client. Giá luôn resolve từ DB theo AttributeId / OptionId — không tin giá client gửi. Logic thuần dùng chung với Lada.AppBackEnd qua GoodsAttributeFeeHelper.

Dựng Item kèm thuộc tính và lựa chọn đã sắp theo thứ tự hiển thị

Kiểm tra hợp lệ danh sách thuộc tính, trả null nếu hợp lệ

Tìm cặp khoảng bị chồng nhau, trả null nếu không có

Gác cửa và ghi log cho việc đổi trục bảng giá. Trả khi được phép đi tiếp.

Bật trục cho một thuộc tính là chuyển cả danh mục từ nhánh tính theo TRỌNG LƯỢNG sang nhánh tra Ô BẢNG GIÁ theo (tuyến, danh mục, lựa chọn trục) — mọi đơn thuộc danh mục đó ra số khác kể từ giây tiếp theo, không có bước duyệt nào ở giữa. Tắt trục cũng vậy, theo chiều ngược lại. Chỉ chặn khi cờ THỰC SỰ đổi, xem : người sửa tên thuộc tính hay thêm lựa chọn trong danh mục đã có trục từ trước vẫn lưu được bình thường. Vai trò kiểm bằng chứ không phải User.IsInRole — role không nằm trong JWT của hệ thống này nên IsInRole luôn trả false.

Chặn lưu nếu lần lưu này sẽ xoá mềm lựa chọn mà bảng giá theo loại hàng còn ô trỏ tới (nợ N8).

Phải chạy trước mọi lệnh ghi: xoá mềm ngay trong vòng lặp, chặn sau đó thì lựa chọn đã mất rồi. Đây cũng là lý do luật đứng ở chứ không nằm trong hai hàm Sync — hai hàm đó đã ở giữa chừng một lần ghi. Gom cả hai đường biến mất của một lựa chọn: (1) thuộc tính cha bị bỏ khỏi payload ⇒ xoá sạch lựa chọn con; (2) thuộc tính còn nhưng lựa chọn bị bỏ khỏi danh sách con. Bỏ sót đường nào cũng là bỏ lọt đúng ca hỏng cần chặn. Câu lỗi, hoặc null nếu không lựa chọn nào vướng ô giá.

Đồng bộ thuộc tính của cấu hình: Id = 0 → thêm (hồi sinh bản ghi xoá mềm cùng mã nếu có); Id > 0 → sửa; thiếu trong payload → xóa mềm

Chép các trường của model vào entity thuộc tính. Dùng chung cho CẢ nhánh thêm và nhánh sửa.

Trước đây hai nhánh chép tay riêng, và IsPriceAxis bị sót ở cả hai — đó chính là nợ N4: cờ trục có trong entity, có người đọc, nhưng không đường nào ghi được. Gộp về một chỗ vì mật thử đã chứng minh hai nhánh song song không được canh: bỏ hẳn dòng gán ở nhánh sửa mà toàn bộ 177 ca test vẫn xanh (service nằm ở project Ladaer.BackEnd, ngoài tầm tham chiếu của project test). Khi đã không có lưới test đỡ, cách chặn còn lại là làm cho việc sót nhánh không thể xảy ra: thêm trường mới vào đây là cả hai đường ghi cùng có.

Đồng bộ lựa chọn của một thuộc tính theo cùng quy tắc diff theo Id

Xóa mềm toàn bộ lựa chọn của một thuộc tính

Giao diện cho dịch vụ quản lý bài viết.

Tìm kiếm bài viết

Thông số tìm kiếm. Kết quả tìm kiếm bài viết.

Tạo / cập nhật bài viết

Thông tin bài viết. Kết quả của thao tác.

Lấy thông tin bài viết qua Id

Id của bài viết. Thông tin bài viết.

Xóa bài viết

Id của bài viết. Kết quả của thao tác.

Cập nhật trạng thái bài viết

Thông tin trạng thái bài viết. Kết quả của thao tác.

Nguồn cho ô "Bưu cục liên quan" của form Bài viết: đúng tập chi nhánh mà bước lưu bài chấp nhận, sắp theo tên.

Triển khai dịch vụ quản lý bài viết.

Khởi tạo một thể hiện của .

Đối tượng IRepository của Post. Dịch vụ quản lý UrlRecord. Cài đặt CMS. Đối tượng IRepository của Category. Đối tượng IRepository của Tag. Đối tượng IRepository của UrlRecord. Hồ sơ bưu cục — chỉ đọc tên hiển thị/trạng thái cho ô chọn bưu cục.

Tìm kiếm bài viết

Thông số tìm kiếm. Kết quả tìm kiếm bài viết.

Tạo hoặc cập nhật bài viết

Thông tin bài viết. Kết quả của thao tác.

Cập nhật bài viết

Thông tin bài viết. Kết quả của thao tác.

Bưu cục gắn với bài (phân hệ bưu cục) phải là chi nhánh LADA hoặc nhượng quyền chưa xoá. null/0 không kiểm; giá trị trùng liên kết đang lưu () cũng không kiểm lại (). Trả null nếu hợp lệ.

Nguồn cho ô "Bưu cục liên quan" của form Bài viết. Lọc bằng CHÍNH của nên mọi dòng đưa ra đều lưu được. Tên hiển thị/trạng thái công bố lấy từ hồ sơ bưu cục còn sống nếu có.

Tạo bài viết

Thông tin bài viết. Kết quả của thao tác.

Xóa bài viết

Id của bài viết. Kết quả của thao tác.

Lấy thông tin bài viết qua Id

Id của bài viết. Thông tin bài viết.

Cập nhật trạng thái bài viết

Thông tin trạng thái bài viết. Kết quả của thao tác.

Cập nhật danh mục bài viết

Danh sách danh mục bài viết. Danh sách danh mục đã cập nhật.

Cập nhật thẻ bài viết

Danh sách thẻ bài viết. Người tạo. Tên người tạo. Danh sách thẻ đã cập nhật.

Tham chiếu bảng giá theo tuyến rút ra từ payload PriceTable mode=route — service dùng để kiểm tra tuyến/danh mục có tồn tại thật trong DB.

Tham chiếu tệp riêng tư của Cổng nhượng quyền rút ra từ payload khối Video (source=file) và Tài liệu — validator là hàm thuần nên không tự tra database; service kiểm tệp còn sống, đúng loại và THUỘC MỤC của topic đang lưu (docs/plan-cong-nhuong-quyen.md §3.4).

Chỉ có nghĩa với tài liệu: khách được tải tệp về.

Ngữ cảnh kiểm khối: vật chủ (quyết loại khối, luật số lượng, bộ icon) và media domain (quyết ảnh https nào được nhận). Dựng bằng để media domain đọc đúng nguồn ảnh tải lên.

Kiểm tra cấu trúc Payload JSON của từng loại khối nội dung — schema mục 3.2 của docs/plan-block-dich-vu-website.md (loại 1–8) và §3.3 của docs/plan-nhuong-quyen-website.md (9–12, v1.2). Đây là ranh giới tin cậy: payload sai cấu trúc hoặc mang link/ảnh/icon ngoài luật bị chặn ngay lúc ghi, để trang public không bao giờ phải đỡ dữ liệu hỏng.

Schema v1.2 chỉ THÊM trường tuỳ chọn cho loại cũ — payload trang dịch vụ thiếu hết trường mới vẫn hợp lệ (test neo ProductBlockPayloadAnchorTests chạy mọi payload thật). Ba luật mới cũng chạm loại cũ, đều đã đo trên payload thật: link (ctaLink của Quy trình), ảnh (url của Hình ảnh), icon (items[].icon của Cam kết). Trường chuỗi đọc đã Trim() như ProductBlockViewFactory.ReadString — kiểm đúng thứ website sẽ in.

Kiểm cả bộ khối của một vật chủ: từng khối theo , rồi luật số lượng của vật chủ (vd. trang nhượng quyền đúng một Form đăng ký). Null = hợp lệ; ngược lại câu báo lỗi tiếng Việt kèm số thứ tự khối. Tham chiếu bảng giá theo tuyến gom vào , tham chiếu tệp riêng tư gom vào — service kiểm chúng với DB.

Payload ở dạng LƯU. Hiện chỉ khối Video đổi: link biên tập viên dán (url) thành nhà cung cấp + mã video () và bỏ trường của nguồn không dùng — database không giữ URL tự do nào của video. Gọi SAU khi đã nhận; payload không đọc được thì trả nguyên.

Trả về null nếu khối hợp lệ với vật chủ trong , ngược lại trả thông báo lỗi tiếng Việt. là tiêu đề khối (cột Title) — bắt buộc với Hero vì nó là H1. Với PriceTable mode=route, trả thêm tham chiếu (routeId, goodsCategoryId) qua để service kiểm tra tồn tại. Khối Video (tệp) và Tài liệu thêm tham chiếu tệp riêng tư vào .

Quy trình. Cổng nhượng quyền thêm tuỳ chọn cho TỪNG bước: resources (nguồn lực cần chuẩn bị) và duration (thời lượng) — skin trang dịch vụ và trang đích không in hai trường này.

Trình chiếu ảnh: slides[] 1–40 {image, alt, title?, caption?} — image là ảnh tải lên (bắt buộc), alt bắt buộc vì slide là nội dung chứ không phải trang trí; autoplaySec 0–20 (0 = không tự chạy), effect fade|kenburns, showCounter.

Video. source=embed: link YouTube / Vimeo biên tập viên dán (url) hoặc dạng đã chuẩn hoá (provider + videoId [+ hash]) — host ngoài danh sách bị từ chối. source=file: fileId của tệp video riêng tư. Tuỳ chọn: poster (ảnh tải lên), description.

Video nhúng của payload — luật ưu tiên nằm ở , chung với factory website.

Tài liệu: items[] 1–20 {fileId, title, description?, allowDownload}. Một tệp chỉ xuất hiện một lần trong khối. Tệp có thật, đúng loại và thuộc mục hay không do service kiểm (validator không chạm database).

Tệp riêng tư mà một khối ĐÃ LƯU tham chiếu, đọc khoan dung: payload hỏng hoặc sai luật ở trường khác vẫn trả các tham chiếu đọc được. Cho những nơi cần biết "khối này đang trỏ tới tệp nào" mà không kiểm cả khối — cảnh báo "khối trỏ tới tệp không còn" ở màn Nội dung cổng, chặn xoá tệp đang dùng (CNQ-32). Đọc đúng hai trường mà / gom lúc kiểm — có test giữ hai bên khớp nhau.

Cam kết / cột trụ. v1.2 thêm tuỳ chọn: image {url, alt}, tags[], ctaText/ctaLink, layout pillars; items[].icon phải thuộc bộ icon cố định của vật chủ.

Khối mở đầu (S01). Tiêu đề khối là H1 nên bắt buộc. Payload: eyebrow, description (đoạn dẫn — trường chung v1.1, thay cho "lead" của bảng §3.3), primaryButton/secondaryButton {text, link}, image {url, alt}, showPattern (hoạ tiết nền).

Số liệu nổi bật (S02): items[] {value, label} 1–6 dòng, showCoverage (in danh sách tỉnh vùng phủ đọc từ dữ liệu — GĐ E), note (nguồn số liệu), images[] tối đa 2.

Bộ ảnh (S05): items[] 1–6 ảnh {url, alt, caption}. url được để trống — khung ảnh chờ buổi chụp (nợ NQW-3) in khung giữ chỗ theo alt — nhưng mỗi ảnh phải có ít nhất url hoặc alt.

Cổng nhượng quyền thêm tuỳ chọn frame (none|phone|browser) cho CẢ khối — khung điện thoại / trình duyệt quanh ảnh chụp màn hình; thiếu = ảnh trần như trước. caption của từng ảnh đã có từ v1.2.

Form đăng ký (S07) — CHỈ CHỮ: eyebrow, description, submitText, successText. Ô nhập, danh sách tỉnh và câu đồng ý xử lý dữ liệu cá nhân cố định ở view — câu đồng ý là văn bản pháp lý được ghi nguyên văn vào lead, không cho biên tập viên sửa; trường nào khác trong payload đều bị bỏ qua.

Chuỗi tuỳ chọn: có mặt (khác null) thì phải là chuỗi và không dài quá .

Giá trị liệt kê tuỳ chọn (vd. layout); thiếu hoặc rỗng = mặc định.

Link tuỳ chọn: rỗng = không có; có thì phải qua .

Link ảnh tuỳ chọn: rỗng = không có; có thì phải qua .

Ảnh tuỳ chọn dạng object {url, alt}; url trống = khung giữ chỗ.

Mảng ảnh {url, alt, caption} từ tới ; mỗi ảnh phải có url hoặc alt.

Nút {text, link}: bỏ trống cả hai = không có nút; điền một nửa thì báo thiếu.

Icon tuỳ chọn: thuộc bộ icon cố định mà skin của vật chủ vẽ được (khoá hoặc class đã lưu).

Mảng chuỗi tuỳ chọn (vd. tags): mỗi mục là chuỗi không rỗng, giới hạn số mục và độ dài.

Khối "trả lời thẳng" (plan GEO §3.6). Mọi trường nội dung đều tuỳ chọn — khối nào marketing chưa có số thì bỏ trống, không bịa — nhưng phải còn ít nhất một dòng để khối có nghĩa, và updatedAt thì bắt buộc: một bảng số không có ngày cập nhật là tín hiệu tin cậy âm.

Số nguyên không âm tuỳ chọn; trả -1 khi có mặt nhưng không phải số hợp lệ (nơi gọi báo lỗi).

(long)token NÉM khi JSON mang số vượt long (Newtonsoft parse thành BigInteger mà vẫn giữ JTokenType.Integer). Hàm này chạy trước mọi thứ trong ProductService.ValidateBlocksAsync — nơi KHÔNG có try/catch — nên để lọt exception là API trả 500 thay vì một câu báo lỗi cho admin.

Số tiền tuỳ chọn; trả -1 khi có mặt nhưng không phải số hợp lệ. Xem ghi chú ở .

Chuỗi tuỳ chọn, cùng luật với ProductBlockViewFactory.ReadString phía website: chỉ nhận , mọi kiểu khác coi như rỗng.

Trường bắt buộc kiểu chuỗi, không rỗng.

Mảng object bắt buộc, không rỗng; mỗi phần tử phải có đủ các trường chuỗi kể tên.

Giao diện cho dịch vụ quản lý dịch vụ.

Tìm kiếm dịch vụ

Thông số tìm kiếm. Kết quả tìm kiếm dịch vụ.

Lấy thông tin dịch vụ qua Id

Id của dịch vụ. Thông tin dịch vụ.

Xóa bài viết

Id của bài viết. Kết quả của thao tác.

Nguồn cho ô "Tỉnh đi / Tỉnh đến" của form Dịch vụ: tỉnh bộ 2 cấp + gợi ý đoán từ tên trang.

Tên trang đang soạn; rỗng thì không đoán, vẫn trả danh sách tỉnh.

Bộ khối của trang dịch vụ (vật chủ Product): loại khối được thêm + bộ icon cố định — editor FE đọc từ đây thay cho danh sách chép tay (nhượng quyền website GĐ F). Icon trang dịch vụ lưu class Font Awesome.

Lấy thông tin dịch vụ qua Id

Id của dịch vụ. Thông tin dịch vụ.

Tạo hoặc cập nhật dịch vụ

Thông tin dịch vụ. Kết quả của thao tác.

Cập nhật dịch vụ

Thông tin dịch vụ. Kết quả của thao tác.

Tạo dịch vụ

Thông tin dịch vụ. Kết quả của thao tác.

Nguồn cho ô "Tỉnh đi / Tỉnh đến" của form Dịch vụ. dùng đúng của bước lưu nên tỉnh nào chọn được thì lưu được.

Đoán tuyến bằng trên tên tỉnh Level 1 của cả hai bộ (như list_service_pages) vì tên trang dịch vụ phần lớn viết trước sáp nhập, rồi map từng vế sang bộ 2 cấp. Vế là tỉnh cũ đã sáp nhập thì Id gợi ý null nhưng tên đoán thô vẫn trả về.

Tỉnh đi/đến của trang tuyến (phân hệ bưu cục) phải là tỉnh sống của bộ đơn vị hành chính 2 cấp (Location Level 1 LevelType 2). null/0 không kiểm; giá trị trùng tỉnh đang lưu cũng không kiểm lại ( — tỉnh cũ bị gộp không được chặn mọi lần lưu trang). Trả null nếu hợp lệ.

Kiểm tra toàn bộ khối nội dung của model theo bộ khối trang dịch vụ (, loại 1–8): cấu trúc payload theo loại, link/ảnh/icon theo luật v1.2, và với PriceTable mode=route thì tuyến + danh mục hàng phải tồn tại thật (gom kiểm tra tồn tại thành 2 truy vấn dù có nhiều block bảng giá). Trả về null nếu hợp lệ, ngược lại trả thông báo lỗi tiếng Việt.

Ghi lại toàn bộ khối nội dung của dịch vụ theo kiểu replace-all (xoá cứng bộ cũ rồi chèn bộ mới) — cùng pattern với Tags/Categories. model.Blocks == null nghĩa là client không gửi trường này → không đụng blocks hiện có. Xoá + chèn nằm trong một transaction để lỗi giữa chừng không làm mất trắng bộ block cũ. SortOrder được chuẩn hoá lại thành 0..n-1 theo thứ tự client gửi lên.

Cập nhật thẻ dịch vụ

Danh sách thẻ dịch vụ. Người tạo. Tên người tạo. Danh sách thẻ đã cập nhật.

Xóa bài viết

Id của bài viết. Kết quả của thao tác.

Cờ hiển thị của màn sửa topic và danh sách topic (rule quyen-hien-thi): người mở được topic bằng Topic.GetById (menu tắt "Nội dung trang nhượng quyền") chưa chắc lưu hay tải ảnh được — nút "Lưu lại" và nút tải ảnh của khối phải ẩn hẳn, nếu không bấm vào là 403 và interceptor đá cả SPA sang trang không quyền, mất bài đang sửa. Hàm thuần nhận danh sách role để có test; mỗi cờ đọc đúng bó role của endpoint nó gác (test đọc [Authorize(Roles)] bằng reflection).

POST api/Topic/CreateOrUpdate.

POST api/Picture/UploadTopicContentPicture.

POST api/Topic/PublishBlocks — người duyệt nội dung (GĐ G).

POST api/Topic/PreviewToken — như đọc topic: link chỉ lộ bản đang sửa mà role này đã đọc được.

DELETE api/Topic/Delete — mục "Xóa" ở danh sách topic.

Ghi các cột xuất bản của bằng MỘT lệnh UPDATE chỉ chạm đúng các cột đó (NQW-17). UpdateAsync cả dòng Topic (lưu topic) không ghi được các cột này — TopicMap đặt AfterSaveBehavior.Ignore — nên lưu topic đúng lúc người khác xuất bản không xoá mất lần xuất bản, và xuất bản không đè tiêu đề vừa sửa. Tách thành store riêng để test được bằng repo giả (ExecuteUpdateAsync/ExecuteDeleteAsync chỉ chạy trên EF thật). Cấp link xem trước cũng ở đây (thêm dòng + dọn link đã hết hạn).

Ghi ảnh chụp xuất bản + người/lúc xuất bản. False = không có dòng nào (topic đã bị xoá).

Thêm một link xem trước (băm token + hạn) — link khác của topic vẫn sống tới hạn của chúng; dọn luôn các link của topic này đã hết hạn trước .

Màn topic CMS (api/Topic). Topic là nội dung một mục Cổng nhượng quyền KHÔNG đi qua interface này với BẤT KỲ ai (kể cả Founder): không liệt kê, đọc / lưu / xuất bản / xem trước đều trả như không tồn tại, xoá bị từ chối. Nội dung cổng chỉ đi qua (màn Nội dung cổng, role FranchisePortal.Content / Manage) — plan cổng §3.10, nợ CNQ-12.

Tìm kiếm topic. Topic của Cổng nhượng quyền (theo tên hoặc theo tham chiếu từ mục) không bao giờ có trong danh sách.

Thông số tìm kiếm. Kết quả tìm kiếm dịch vụ.

Tạo/sửa topic. Người thao tác đọc từ model.UpdatedBy (controller đóng dấu). Topic của Cổng nhượng quyền trả "không tìm thấy"; tên hệ thống FranchisePortal.… không tạo mới và không đặt cho topic thường được ở đây — mục cổng chỉ sinh ra ở màn Nội dung cổng.

Topic của Cổng nhượng quyền trả model rỗng (như không tồn tại).

Id của topic theo tên hệ thống (khớp nguyên chuỗi đã cắt khoảng trắng); 0 = không có (kể cả topic của Cổng nhượng quyền). Menu tắt của SPA mở thẳng một topic hệ thống (vd. FranchiseLanding) qua đây thay vì ghi cứng Id — Id khác nhau giữa các DB.

Xóa bài viết

Id của bài viết. Kết quả của thao tác.

Bộ khối của topic theo tên hệ thống (khai ở ) cho editor FE.

Xuất bản bộ khối đang sửa: kiểm TOÀN BỘ khối theo bộ khối của topic (luật lưu + luật số lượng lúc xuất bản) rồi chụp thành Topic.PublishedBlocksJson (+ PublishedAt, PublishedBy) qua — chỉ ghi 4 cột đó (NQW-17). Website chỉ đọc ảnh chụp này. POST api/Topic/PublishBlocks, role Topic.Publish (plan nhượng quyền website §6.3).

Dấu DraftVersion người bấm đã thấy (GetById). Khác dấu bản đang sửa hiện tại → không xuất bản, DraftChanged = true. Null = không kiểm (chỉ dùng trong test/công cụ nội bộ).

Cấp link xem trước bản ĐANG SỬA trên website, hạn 30 phút (). Mỗi lần cấp một link mới; link cấp trước vẫn sống tới hạn của nó. Chỉ topic có bộ khối và có trang công khai riêng (PublicPath).

Lấy thông tin dịch vụ qua Id

Id của dịch vụ. Thông tin dịch vụ.

Tạo hoặc cập nhật dịch vụ

Thông tin dịch vụ. Kết quả của thao tác.

Cập nhật dịch vụ

Thông tin dịch vụ. Kết quả của thao tác.

Tạo dịch vụ

Thông tin dịch vụ. Kết quả của thao tác.

Thân việc xuất bản — nơi gọi ĐÃ qua cửa của mình (màn topic: không phải nội dung cổng; màn Nội dung cổng: role cổng + mục có thật) và đã có bộ khối của topic.

Sinh token xem trước, lưu băm + hạn. Trả token RÕ (chỉ có mặt trong link trả cho người gọi) và hạn.

Bản đang sửa khác ảnh chụp đã xuất bản? So NỘI DUNG (), không so chuỗi JSON thô hay Id khối. Chưa xuất bản lần nào / ảnh chụp hỏng mà đã có khối → có thay đổi (xuất bản sẽ sửa).

Khối đang sửa của topic, sắp theo thứ tự. Đọc qua Query() của chính bảng khối — xoá mềm lọc ở gốc truy vấn — thay cho Include từ Topic: Include thường KHÔNG lọc xoá mềm của bảng con (plan §7).

Người này có được chạm nội dung mục cổng không: FranchisePortal.Content, FranchisePortal.Manage hoặc Founder — đúng bó quyền của màn Nội dung cổng (plan §3.8). Chỉ cửa của màn Nội dung cổng () hỏi câu này; màn topic thì từ chối nội dung cổng với mọi người, vì role Topic.* không được là đường đọc/sửa/xuất bản mục "Kế hoạch kinh doanh".

Mục cổng (chưa xoá) đang lấy topic này làm vật chủ; null = không có.

Topic là nội dung của cổng: theo TÊN (FranchisePortal.<Code>) HOẶC theo THAM CHIẾU (một mục đang trỏ TopicId tới nó). Chỉ xét tên là để lại đường vòng "đổi tên rồi làm gì cũng được".

Null = qua. Chặn ba việc ở màn topic: (1) tạo topic mang tên của cổng — topic cổng chỉ sinh ra cùng mục ở màn Nội dung cổng; (2) sửa topic của cổng (theo tên hoặc theo tham chiếu từ mục) — với MỌI người, trả đúng câu "không tìm thấy" của topic không tồn tại, nên cũng không đổi tên / tách mục khỏi nội dung của nó được; (3) đổi một topic thường thành tên của cổng.

Tên hệ thống có bộ khối không được trùng topic khác — website tra trang theo tên hệ thống, hai topic cùng tên là biên tập viên sửa một trang còn website in trang kia. Kiểm cả khi không gửi khối.

Null = hợp lệ. Blocks == null = không gửi khối → không kiểm, không ghi. Topic không có bộ khối chỉ nhận danh sách rỗng. Topic có bộ khối: kiểm từng khối + luật số lượng, theo đúng thứ tự sẽ lưu (SortOrder) để "Khối nội dung thứ N" trong câu lỗi chỉ đúng khối biên tập viên thấy.

Luật LƯU của một bộ khối, dùng chung cho màn topic và màn Nội dung cổng: từng khối theo schema + luật số lượng của vật chủ, rồi tệp riêng tư mà khối tham chiếu (). Null = hợp lệ.

Khối đã qua kiểm → đổi sang dạng LƯU (vd. link video dán vào thành nhà cung cấp + mã video).

Tệp riêng tư mà khối Video / Tài liệu tham chiếu phải còn sống, đúng loại và thuộc ĐÚNG MỤC mà topic này là vật chủ. Thiếu phép kiểm "thuộc mục" thì biên tập viên nhúng được tệp của mục khác (vd. mục "Kế hoạch kinh doanh" còn khoá) vào một mục đang mở cho khách — cửa /tep của website cũng kiểm lại điều này lúc đọc. Chạy cả lúc lưu lẫn lúc xuất bản: tệp có thể bị xoá giữa hai lần.

Phần của một dòng tệp riêng tư mà phép kiểm tham chiếu cần — không đọc ExtractedText.

Phần của một dòng tệp riêng tư mà phép kiểm tham chiếu cần — không đọc ExtractedText.

Các tệp riêng tư CÒN SỐNG trong danh sách Id — tệp đã xoá không có mặt trong kết quả.

Null = khối được tham chiếu tệp này. null = không có / đã xoá. Tài liệu không phải PDF trình duyệt không xem trong trang được nên phải cho tải — nếu không khách thấy tên tệp mà không mở được.

Ghi lại toàn bộ khối đang sửa theo kiểu replace-all (xoá cứng bộ cũ rồi chèn bộ mới, như ProductService). Nơi gọi đã mở transaction. SortOrder chuẩn hoá thành 0..n-1 theo thứ tự client gửi.

Thân việc của — đường ghi DUY NHẤT lên TopicBlock.

Xóa bài viết

Id của bài viết. Kết quả của thao tác.

Topic vật chủ của một mục, đã có bộ khối của cổng.

Topic vật chủ của một mục, đã có bộ khối của cổng.

Kết quả mở cửa. null = không có mục HOẶC người gọi thiếu role cổng (hai ca trả giống nhau). null = mục không có khối ( null: mục bảng giá) hoặc nội dung lệch.

Kết quả mở cửa. null = không có mục HOẶC người gọi thiếu role cổng (hai ca trả giống nhau). null = mục không có khối ( null: mục bảng giá) hoặc nội dung lệch.

Cửa của màn Nội dung cổng — MỌI đường của đi qua đây trước. Kiểm role ở service là lớp thứ hai sau [Authorize] của controller: một action thêm sau quên khai role vẫn không đọc / sửa được nội dung mục khoá.

Phần của một khối (đang sửa hoặc đã xuất bản) mà phép tìm tệp tham chiếu cần.

Phần của một khối (đang sửa hoặc đã xuất bản) mà phép tìm tệp tham chiếu cần.

Khối trỏ tới tệp không còn dùng được, theo đúng luật của (đã xoá, sai loại, thuộc mục khác, tài liệu không phải PDF mà không cho tải) — CNQ-32: biên tập viên thấy trước khi lưu / xuất bản bị từ chối.

Khối nội dung của một mục Cổng nhượng quyền — CỬA của màn "Nội dung cổng" (docs/plan-cong-nhuong-quyen.md §3.9, §6.8, nợ CNQ-12): đọc / lưu bản đang sửa, xuất bản, cấp link xem trước. Người gọi phải có FranchisePortal.Content / FranchisePortal.Manage (hoặc Founder) — KHÔNG cần role Topic.* nào.

Mọi lời gọi đi vào bằng Id mục, không bằng Id topic: cửa này chỉ mở tới topic mà một mục đang trỏ tới, nên không dùng nó để chạm một topic thường được. Thân việc (luật khối, kiểm tệp tham chiếu, ghi TopicBlock, chụp bản xuất bản) là của — cửa này và màn topic gọi chung, không có đường ghi thứ hai.

null khi không có mục hoặc người gọi thiếu role cổng.

Thay TOÀN BỘ khối đang sửa của mục. Khối sai schema, hoặc trỏ tới tệp không thuộc đúng mục này, bị từ chối trước mọi lệnh ghi. Không đổi gì trên trang khách đang thấy — chỉ mới đổi.

Dấu DraftVersion của bản người lưu đã mở — bắt buộc. Lưu là thay cả bộ khối nên hai biên tập viên cùng mở một mục thì người lưu sau đè mất bản người lưu trước; dấu đã cũ → từ chối, DraftChanged = true.

Xuất bản đúng bản người bấm đã thấy ( bắt buộc), cần ít nhất 1 khối.

Cấp link xem trước bản ĐANG SỬA của đúng mục này trên website, hạn 30 phút (). Mỗi lần cấp một link mới; link cấp trước vẫn sống tới hạn của nó.

Giao diện cho dịch vụ quản lý UrlRecord.

Lấy thông tin bài viết qua Id.

Id của bài viết. Thông tin UrlRecord của bài viết.

Tạo hoặc cập nhật UrlRecord.

Thông tin UrlRecord. Kết quả của thao tác.

Tạo slug cho UrlRecord.

Slug cần tạo. Slug đã được tạo.

Tạo slug cho UrlRecord với loại thực thể.

Slug cần tạo. Loại thực thể của UrlRecord. Slug đã được tạo.

Lấy UrlRecord theo slug.

Slug của UrlRecord. Thông tin UrlRecord.

Thêm mới UrlRecord.

Thông tin UrlRecord. Kết quả của thao tác.

Tìm kiếm UrlRecord.

Thông số tìm kiếm. Kết quả tìm kiếm UrlRecord.

Lấy thông tin UrlRecord theo Id.

Id của UrlRecord. Thông tin UrlRecord.

Tạo hoặc cập nhật UrlRecord.

Thông tin UrlRecord. Kết quả của thao tác.

Cập nhật thông tin cơ bản của UrlRecord.

Model chứa thông tin cập nhật UrlRecord. Kết quả của thao tác.

Triển khai dịch vụ quản lý UrlRecord.

Khởi tạo một thể hiện của .

Đối tượng IRepository của UrlRecord.

Tạo hoặc cập nhật UrlRecord.

Thông tin UrlRecord. Kết quả của thao tác.

Lấy thông tin bài viết qua Id.

Id của bài viết. Thông tin UrlRecord của bài viết.

Tạo slug cho UrlRecord.

Slug cần tạo. Slug đã được tạo.

Tạo slug cho UrlRecord.

Slug cần tạo. Slug đã được tạo.

Tạo slug cho UrlRecord với loại thực thể.

Slug cần tạo. Loại thực thể của UrlRecord. UrlRecordId hiện tại Slug đã được tạo.

Lấy UrlRecord theo slug.

Slug của UrlRecord. Thông tin UrlRecord.

Thêm mới UrlRecord.

Thông tin UrlRecord. Kết quả của thao tác.

Tìm kiếm UrlRecord.

Thông số tìm kiếm. Kết quả tìm kiếm UrlRecord.

Lấy thông tin UrlRecord theo Id.

Id của UrlRecord. Thông tin UrlRecord.

Tạo hoặc cập nhật UrlRecord.

Thông tin UrlRecord. Kết quả của thao tác.

Thêm mới UrlRecord.

Thông tin UrlRecord. Kết quả của thao tác.

Cập nhật UrlRecord.

Thông tin UrlRecord. Kết quả của thao tác.

Cập nhật thông tin cơ bản của UrlRecord.

Model chứa thông tin cập nhật UrlRecord. Kết quả của thao tác.

Enum đại diện cho loại thực thể của UrlRecord.

Quản trị luật chuyển hướng URL của website công khai.

Danh sách luật, có lọc/sắp/phân trang theo SmartTable.

Một luật để mở form sửa; null khi không có hoặc đã xoá.

Thêm hoặc sửa một luật, sau khi qua hết các luật kiểm tra.

Xoá mềm một luật.

Tầng lưu của bảng UrlRedirect — nơi đặt toàn bộ luật kiểm tra của miền này. Vì sao luật nằm ở đây mà không phải ở DataAnnotations của model. Ba trong năm luật phải đọc dữ liệu: đường dẫn cũ đã có luật khác chưa, đích có trùng nguồn của luật khác không, có bản ghi UrlRecord nào cùng đường dẫn không. Chia đôi giữa hai chỗ là để hai chỗ lệch nhau, mà chỗ nào cũng trông như chỗ đúng. Bảng này có hiệu lực trên trang công khai mà không cần deploy. Middleware của website đọc nó với cache 5 phút, nên một dòng sai là một nhánh URL thật của website đi sai chỗ trong vòng năm phút — và với mã 301 thì công cụ tìm kiếm đã ghi nhận trước khi ai kịp sửa. Đó là lý do tầng này từ chối thẳng thay vì "lưu rồi cảnh báo".

Các cột người dùng được phép sắp xếp theo.

OrderByName dựng biểu thức bằng reflection và ném khi tên cột không tồn tại, nên một khoá sắp xếp lạ từ client sẽ thành lỗi 500 thay vì bị bỏ qua. Danh sách trắng biến nó thành "dùng sắp xếp mặc định".

Hàng tồn kho URL dựng từ chính sitemap.xml (miền đồng bộ công cụ tìm kiếm, GĐ B).

Cần nó vì sitemap sinh từ bảy nguồn, mà hơn mười đường dẫn tĩnh và toàn bộ trang bưu cục /mang-luoi/{slug} không đi qua UrlRecord. Soi mỗi UrlRecord rồi kết luận "không còn trong sitemap" là nói về một nhóm mình chưa kiểm.

Phép chiếu dùng chung của màn danh sách: bảng luật cộng cờ đối chiếu với sitemap.

Hàng tồn kho sitemap (SearchUrl) đã có dữ liệu hay chưa — quyết định cờ được phép kết luận false hay phải trả null. Mọi truy vấn con Any dịch được sang SQL nên bộ lọc và phân trang vẫn chạy ở DB, không phải kéo cả bảng về rồi lọc trong bộ nhớ. Slug của UrlRecord không có dấu / đầu nên phải cắt một ký tự của FromPath trước khi so.

Điền — số ngày luật đã tồn tại, để giao diện không trình bày HitCount = 0 của một luật vừa tạo như thể đã đo được là không ai vào.

Chặn chuỗi và vòng: đích của luật này không được là nguồn của luật khác, và nguồn của luật này không được là đích của luật khác. Trả null khi không có xung đột.

Chặn chuỗi là chặn luôn mọi vòng, dài bao nhiêu cũng vậy. Nếu không luật nào có đích trùng nguồn của luật nào, thì không dựng được đường đi hai bước — mà vòng thì bắt buộc phải đi ít nhất hai bước. Vì thế ở đây không cần thuật toán dò vòng, chỉ cần kiểm hai chiều. Chỉ xét các luật đang bật, và chỉ xét khi luật đang lưu cũng đang bật. Một luật tắt không chuyển hướng gì nên không tạo được chuỗi. Bật nó lên là một lần sửa, và lần sửa đó lại đi qua đúng hàm này. Đích được lưu ở dạng có thể mang query, nên phải quy về đường dẫn trước khi so — việc đó làm trong bộ nhớ. Bảng này là bảng nhỏ do người nhập tay (bốn dòng lúc dựng, hàng chục dòng là nhiều), nên tải danh sách luật đang bật về là rẻ; đổi lại được dùng đúng một hàm chuẩn hoá với middleware thay vì viết lại phép cắt query bằng SQL.

Đưa khoá sắp xếp của giao diện về đúng tên cột trong danh sách trắng; null = dùng mặc định.

Nối một dòng vào ghi chú sẵn có mà không xoá chữ của người nhập.

Token truy cập cá nhân (PAT) lada_cs_… cho MCP — đường phụ cho Claude Code (--header) và kiểm thử (plan §3.4). Chỉ lưu SHA-256; chuỗi gốc hiện một lần lúc tạo. Token luôn gắn với một user thật, không Founder.

Danh sách token (không chứa chuỗi/hash), mới trước; mặc định ẩn token đã thu hồi.

Kiểm chuỗi token lúc xác thực /mcp: tồn tại, chưa thu hồi, chưa hết hạn, user còn sống, không bị khoá.

SHA-256 hex thường của toàn bộ chuỗi token — public để test và script kiểm thử tính cùng một cách.

Bài viết trong kho nội dung AI (đặc tả §5.2–§5.3). GĐ A chỉ có tạo bản nháp, đọc, tìm và render; duyệt / điền ô / đăng thuộc các giai đoạn sau.

Tạo bản nháp bài 4 phần. Chạy hết mọi lớp kiểm tra (hình thức → đề → slug → cổng chặn → phiếu chấm → ảnh → ô) rồi mới ghi, tất cả trong một transaction. Không ghi gì khi bất kỳ lớp nào báo lỗi cứng.

Kiểm hình thức payload y như bước đầu của mà không ghi gì — để dry-run nhập liệu báo được "file này sẽ bị từ chối vì thiếu gì" thay vì chỉ "đọc được".

Bài đầy đủ theo Id — null nếu không có (controller trả 404).

Bài đầy đủ theo mã đề — null nếu đề chưa có bài.

Danh sách bài rút gọn theo SmartTableParam (Keyword, Status, CategoryL2, PageType, WeekNo, DraftedBy).

Render thân bài + FAQ ở dạng html hoặc markdown (GĐ A chưa thay ô). Null nếu không có bài; format lạ → VALIDATION_ERROR.

Sửa nội dung bài (đặc tả §5.2 update_article). Kiểm ExpectedVersion trước mọi thứ, chạy lại cổng chặn / phiếu chấm / luật ảnh như lúc tạo, trích lại ô dữ liệu và ghi một phiên bản mới — tất cả trong một transaction.

Đổi trạng thái bài theo máy trạng thái §3.3e. Không đi qua đây được: Approved và đường rút lại từ Approved (cả hai chiều đi qua / vì gác bằng role khác), và Published (job đồng bộ CMS — GĐ F).

Duyệt đăng: chạy đủ 8 điều kiện §3.3d rồi mới chuyển sang Approved. Thiếu bất kỳ điều kiện nào → PUBLISH_PRECONDITION_FAILED kèm Extra.Missing và Extra.Checks, không ghi gì — kể cả ba cờ ghi đè trong payload. Không có đường vòng cho ai cả (plan §7.4c): Founder qua đúng hàm này. Đường ghi duy nhất cho PublishWithoutImages / OverrideNote cũng ở đây, vì hai cờ đó chỉ có nghĩa trong một lần duyệt cụ thể.

Rút lại bài đã duyệt (Approved → PendingReview), lý do bắt buộc. Tách khỏi vì huỷ một quyết định duyệt phải cần đúng quyền đã ra quyết định đó.

Gán tác giả / người kiểm tra cho bài — điều kiện đăng §3.3d(2)(3) đọc hai trường này.

check_slug (đặc tả §5.3): slug còn trống không, kèm gợi ý. Nhìn cả bài trong kho lẫn UrlRecord của CMS kể cả bản xoá mềm — URL cuối cùng vẫn là /{slug}.

Lịch sử phiên bản của một bài, mới nhất trước. Null khi không có bài (controller trả 404). Không kèm nội dung từng bản — xem .

Cập nhật kết quả một dòng ảnh sau khi nộp file (đặc tả §5.3 set_image_status): AssetUrl/OgAssetUrl/Status/ghi chú kiểm. Không đụng thông số ảnh và không tạo phiên bản bài — bộ ảnh không nằm trong ảnh chụp ContentArticleVersion.

Bỏ một ảnh khỏi bộ ảnh của bài (xoá mềm). Dùng khi bài không cần tấm đó — trước đây bộ ảnh sinh một lần lúc tạo nháp rồi không ai bỏ bớt được.

Chạy tám điều kiện đăng §3.3d ở chế độ chỉ đọc để màn duyệt hiện danh sách còn thiếu. Không đổi gì trong DB; GĐ E mới nối lớp kiểm này vào SetStatus(Approved). Null khi không có bài.

Tên unique index trong ContentArticleMap — nhận diện va chạm đồng thời từ chuỗi lỗi mà Repository bọc lại.

Bộ công cụ ảnh — chỉ dùng để ghép prompt đầy đủ khi trả chi tiết bài, không ghi gì.

Chuẩn hoá toàn bộ chuỗi trong payload về FormC bằng một vòng JSON (Newtonsoft giữ nguyên JsonExtensionData của Brief). Chuỗi Unicode hỏng (surrogate lẻ) không chuẩn hoá được thì giữ nguyên payload.

Kiểm hình thức payload — gom mọi lỗi, Field = tên trường PascalCase của DTO.

Độ dài các cột nvarchar(n) của ContentImage; FrameCode/Lane so trên bản Trim vì entity lưu bản Trim.

Cắt về đúng độ dài cột; null → chuỗi rỗng (cột IsRequired).

Slug trống đầu tiên trong slug-2, slug-3… (tối đa 20 thử); null nếu đều đã dùng.

Chỉ đọc: không tracking; collection Images tách truy vấn để tránh tích Descartes.

Map phần phẳng bằng AutoMapper rồi điền JSON + ảnh đã sắp thứ tự, và ghép prompt đầy đủ cho từng ảnh từ (khối STYLE BASE + tên khuôn + ảnh tham chiếu).

Khối FAQ dạng Markdown nối sau thân bài; chuỗi rỗng khi không có FAQ.

Tên các trường thật sự có trong patch — ghi vào audit thay vì ghi cả nội dung bài.

Kiểm hình thức bản đã hợp nhất (patch + bài cũ) — cùng giới hạn cột như lúc tạo.

Trạng thái mà người duyệt phải nói rõ vì sao — để bài không bị treo mà không ai biết lý do.

Đích bắt buộc nêu lý do. nằm đây vì lý do là đầu vào của trợ lý viết lại — nó đọc đúng câu đó để biết sửa gì; "chưa đạt" cộc lốc thì nó viết ra đúng bài cũ (quyết định 2026-09-13). Bản sao của luật này ở frontend là STATUS_CAN_LY_DO trong constants/contentStore.js.

Đường dẫn ảnh chấp nhận được: tương đối, hoặc http/https tuyệt đối. Chặn javascript:/data:.

Dựng đầu vào cho từ một bài đã nạp kèm Author và Images. Dùng chung cho đường chỉ đọc () và đường ghi () — nhân bản logic này ra hai chỗ là cách chắc chắn để hai đường lệch nhau.

Ba cờ ghi đè do người duyệt gửi trong chính lời gọi duyệt; null thì lấy giá trị đang lưu của bài.

Bài để sửa — có tracking (khác chỉ đọc). Id thắng khi gửi cả hai.

Ảnh chụp nội dung hiện tại của bài thành một dòng .

Cảnh báo mềm khi bài còn chuỗi [[CẦN …]] của cơ chế ô chờ đã bỏ (2026-09-12). Cảnh báo chứ không chặn: chuỗi ấy bị xoá lúc đăng, và người duyệt là người quyết định đăng hay không.

Câu cảnh báo phải nói cách làm đúng, không chỉ nói cách cũ đã bỏ — trợ lý AI đọc đúng chuỗi này rồi tự sửa bài; nói trống "cơ chế đã bỏ" thì nó không biết phải làm gì thay thế.

Luôn đủ 4 khoá tên enum ContentImageDecision.

Dòng ảnh đã lưu → DTO, để chạy lại khi sửa thân bài.

Máy trạng thái bài viết (plan §3.3e) — một nơi duy nhất quyết định bài được đi từ đâu tới đâu và bản nháp mới sinh ra ở trạng thái nào. Gom về đây theo khuyến nghị review GĐ A: trước đó luật "điểm < 70 thì ép NeedsRewrite" nằm trong còn bảng chuyển trạng thái chưa có, nên hai nửa của cùng một luật ở hai chỗ. nay chỉ tính điểm và gọi .

Bảng chuyển hợp lệ. Đọc: từ khoá → các đích được phép. Trạng thái không có trong bảng (, ) là điểm cuối. Hàng đợi viết lại (quyết định 2026-09-13). vốn chỉ do hệ thống đặt lúc tự chấm (); nay người duyệt còn đánh dấu tay được từ PendingReview / NeedsData / Hold — đó chính là hàng đợi mà trợ lý AI lấy về viết lại (list_articles status=needs_rewrite). Lý do bắt buộc, vì trợ lý đọc đúng câu đó mà sửa. Cố ý không mở cho Approved / Published / Rejected: bài đã duyệt phải rút duyệt (RevokeApproval, role ContentStore.Approve) trước, không thì kho và website lệch nhau mà không ai biết.

Đích chỉ đạt tới bằng đường riêng, không qua set_article_status của người duyệt.

Trạng thái mà mọi đường ra đều cần role ContentStore.Approve, nên không hiện trong danh sách đích của set_article_status: rút lại một quyết định duyệt phải cần đúng quyền đã duyệt.

Chuyển chỉ hợp lệ khi đi qua update_article, không phải qua đổi trạng thái tay.

Các đích người duyệt bấm được ngay bây giờ (bỏ đích cần đường riêng).

Danh sách đích hợp lệ dạng chữ, để nhét vào thông báo INVALID_TRANSITION.

Trạng thái của bản nháp vừa tạo / vừa sửa, suy từ phiếu tự chấm (§3.3c): tự khai chưa qua cổng chặn hoặc tổng < 70 → (ưu tiên), kết luận "tạm giữ" → , còn lại chờ duyệt.

Lý do ép trạng thái, ghi vào ContentArticle.StatusReason; null nếu không ép.

Tác giả / người kiểm tra đứng tên trên bài (đặc tả §4.8 people, §5.3 list_people). Đây là hồ sơ E-E-A-T, không phải tài khoản đăng nhập: một người có thể chưa có tài khoản mà vẫn đứng tên bài, nên UserId là tham chiếu mềm và có thể để trống.

list_people — danh sách gọn cho trợ lý AI và ô chọn trên màn duyệt.

Tạo mới (Id = 0) hoặc sửa. Trùng họ tên với người còn hoạt động khác → cảnh báo, không chặn.

Xoá mềm. Người còn bài đứng tên thì từ chối — bài mất tác giả là mất điều kiện đăng §3.3d(2).

URL bắt đầu bằng // hoặc /\ — trình duyệt đọc cả hai là "giao thức tương đối" và đi ra máy chủ khác, dù chuỗi trông như đường dẫn nội bộ. Dùng chung với ContentArticleService.IsSafeAssetUrl: hai hàm kiểm URL trong cùng một miền phải nói cùng một luật.

Đếm bài đứng tên trong một truy vấn gộp — để danh sách không sinh N+1.

Ảnh chụp trạng thái triển khai của kho nội dung AI, đọc được từ trình duyệt — thay cho việc mở SQL client vào database production.

Vì sao có thứ này (quyết định Q7, chốt 2026-09-07 — plan §7.12). Trình tự deploy §4.4 bước 1 đòi "xác nhận bằng query": đếm bảng Content*, đếm role, kiểm ba khoá công tắc. Nhưng ràng buộc 2026-08-27 cấm chạy SELECT/INSERT/UPDATE tay vào Ladaer2 production. Endpoint này là đường thay thế: chỉ đọc, không tham số, gác role, và trả đúng những con số bước 1 cần. Nó còn kiểm được hai thứ mà SQL không kiểm được. (1) Khoá OpenIddict là khoá thật hay khoá tạm — thứ này chỉ hiện trong nhật ký lúc dựng pipeline, mà khoá tạm nghĩa là mọi token OAuth chết sau mỗi lần khởi động lại. (2) Reverse proxy có gửi đúng header không — Scheme và ClientIp ở đây là thứ API thật sự nhìn thấy, nên đọc chúng là cách duy nhất kết luận đúng về bẫy Forwarded Headers thay vì suy luận (checklist §5). Không được lộ gì nhạy cảm. Chỉ số đếm, cờ boolean và URL công khai. Không trả nội dung SigningKeyPem/EncryptionKey, không trả McpAllowedIps, không trả danh sách người. Ca test DeployCheck_KhongLoKhoaVaKhongLoDaiIp canh đúng mệnh đề này.

Đọc trạng thái triển khai. Không ghi một dòng nào.

Mười role của kho nội dung do migration M202609041520 seed, cộng Post.Publish của CMS (đường "Đăng ngay" §7.11 đòi nó). Liệt kê tường minh để role thiếu vẫn hiện ra — hỏi database "có role nào tên ContentStore.*" thì một seed chạy nửa chừng trông y hệt một seed đủ.

Ba công tắc quyết định hệ thống có đổi hành vi hay không. Cả ba phải false sau bước 2.

Cấu hình MCP đang chạy, dạng an toàn để in ra: URL công khai và cờ về khoá, không phải khoá.

PersistentSigningKey = false nghĩa là API đang chạy bằng khoá tạm sinh lúc khởi động — mọi access token và refresh token chết sau mỗi lần khởi động lại, và Cowork sẽ đòi đăng nhập lại sau mỗi lần deploy. Đây là hỏng lặng lẽ nhất của cả đợt: không có lỗi nào, chỉ có người dùng "tự nhiên bị đăng xuất".

Thứ API thật sự nhìn thấy về request này — nửa còn lại của bẫy Forwarded Headers.

Scheme phải là https khi gọi qua tên miền công khai. Thấy http nghĩa là proxy chưa gửi X-Forwarded-Proto, hoặc ForwardedHeadersMiddleware đã bỏ header vì proxy không nằm trong KnownProxies — và hệ quả là OpenIddict từ chối mọi /connect/* ngoài Development. ClientIp là kết quả của — đúng thứ whitelist và rate limit dùng. So nó với IP thật của máy đang bấm là cách kiểm duy nhất đáng tin; suy luận từ cấu hình proxy đã sai một lần rồi. ForwardedFor là header do chính người gọi gửi lên nên in lại không lộ gì.

Migration mới nhất đã áp dụng. Đọc thẳng VersionInfo — bảng do FluentMigrator sở hữu, ứng dụng không tham chiếu project migration nên không có đường EF nào tới nó.

Cùng câu lệnh mà StartupHostedService.LogSchemaVersionAsync in ra nhật ký lúc khởi động — đây là bản đọc được từ trình duyệt, cho người không có quyền đọc nhật ký máy chủ.

Đếm dòng từng bảng của miền, cộng OpenIddictApplications.

Đếm tất cả dòng, kể cả dòng đã xoá mềm: câu hỏi của bước 1 là "bảng có tồn tại và migration đã ăn chưa", không phải "còn bao nhiêu dòng đang dùng". OpenIddictApplications có mặt ở đây vì nợ CS-16: mỗi lần Claude/ChatGPT kết nối là một client DCR mới được tạo và chưa có job dọn. Con số này là cách theo dõi nó phình sau khi mở công khai.

Đếm một bảng; bảng chưa tồn tại (migration chưa chạy) trả -1 thay vì làm hỏng cả lời gọi.

Với mỗi role: đã seed chưa, và bao nhiêu người còn hiệu lực đang có nó.

Quyền tới người theo hai đường và phải cộng cả hai rồi loại trùng: gán trực tiếp (UserRole) và gán qua nhóm quyền (User.PermissionId → PermissionRole) — đúng hai nguồn mà UserRoleResolver hợp nhất lúc chạy. Đếm mỗi UserRole là ra số nhỏ hơn thực tế, vì hầu hết nhân viên nhận quyền qua nhóm.

Ảnh chụp trạng thái triển khai — xem .

Thời điểm đọc, theo múi giờ máy chủ — để không nhầm ảnh chụp cũ với ảnh mới.

ASPNETCORE_ENVIRONMENT đang chạy. Phải là Production trên máy chủ thật: handler lỗi an toàn (CS-25) và việc tắt Swagger đều gắn vào điều kiện "không phải Development".

Migration mới nhất đã áp dụng — thay cho SELECT MAX(Version) FROM VersionInfo.

Số dòng từng bảng; -1 = không đọc được (bảng chưa có).

Role của miền: đã seed chưa và bao nhiêu người đang có.

Ba công tắc — sau bước 2 của §4.4 cả ba phải là false.

Cấu hình MCP/OAuth đang chạy, dạng an toàn để in.

Thứ API nhìn thấy về chính request này — mật thử cho reverse proxy.

Tên bảng. Số dòng, hoặc -1 khi không đọc được. Tên bảng. Số dòng, hoặc -1 khi không đọc được.

Tên bảng.

Số dòng, hoặc -1 khi không đọc được.

Tên role. Role đã có trong bảng Role chưa. Số người còn hiệu lực đang có role (trực tiếp + qua nhóm quyền). Tên role. Role đã có trong bảng Role chưa. Số người còn hiệu lực đang có role (trực tiếp + qua nhóm quyền).

Tên role.

Role đã có trong bảng Role chưa.

Số người còn hiệu lực đang có role (trực tiếp + qua nhóm quyền).

Khoá AppConfig. Giá trị hiện tại — công tắc boolean, không phải bí mật. Khoá AppConfig. Giá trị hiện tại — công tắc boolean, không phải bí mật.

Khoá AppConfig.

Giá trị hiện tại — công tắc boolean, không phải bí mật.

Cấu hình MCP/OAuth dạng an toàn để in ra — cờ và URL, không có khoá.

Cấu hình MCP/OAuth dạng an toàn để in ra — cờ và URL, không có khoá.

Thứ API thật sự nhìn thấy về request đang gọi — dùng để kết luận về reverse proxy.

Thứ API thật sự nhìn thấy về request đang gọi — dùng để kết luận về reverse proxy.

Cách một luật gate quyết định có báo một match hay không.

Báo mọi match.

Chỉ báo khi câu chứa match (đoạn giữa các dấu .!? hoặc xuống dòng) có chữ "LADA" đứng trước match và giữa LADA với match không có từ phủ định (không / chưa / chẳng). Không thoả → bỏ qua hẳn, vì bài được phép nói về đối thủ ("Viettel Post phủ 63 tỉnh").

Chỉ báo khi câu chứa match không có chữ số nào — có số cụ thể thì không còn là sáo ngữ.

Một dòng trong bảng luật cổng chặn (đặc tả §7.1). Bất biến, dùng chung cho mọi request.

Mã luật, ví dụ GATE_01_HOTLINE_CU — ghi vào ContentStoreIssue.Rule.

true = lỗi cứng (chặn lưu); false = cảnh báo mềm (chỉ trả về).

Thông điệp tiếng Việt cho người đọc.

Bảng luật cổng chặn nội dung — hằng trong code (không đọc từ DB) để mỗi dòng có test riêng và đổi luật là đổi code có review. Thứ tự trong là thứ tự báo lỗi trong một trường.

Mọi regex của gate: không phân biệt hoa thường (Unicode, kể cả Đ/đ), bất biến văn hoá, biên dịch sẵn.

Meta description dài hơn ngưỡng này → cảnh báo mềm GATE_06_META_DAI (Google cắt khoảng 155–160 ký tự).

Văn bản đưa qua cổng chặn — mọi trường người đọc nhìn thấy được.

Chuỗi trong brief, dạng (đường dẫn, văn bản) từ ContentStoreJson.FlattenStrings — Field báo lỗi là "Brief.<đường dẫn>". Đây là trường nội bộ: vi phạm trong brief chỉ ra cảnh báo, không chặn lưu.

true (mặc định, lúc tạo bài): che nội dung bên trong ô [[…]] bằng khoảng trắng cùng độ dài trước khi chạy luật, vì mô tả ô là chỉ dẫn cho người điền, không phải nội dung đăng. false khi kiểm bản đã thay ô (§3.3d bước 7).

Cổng chặn nội dung (đặc tả §7.1, plan §3.3b). Luật là hằng trong ContentGateRules, mỗi dòng có test riêng. Lỗi cứng → Code = CONTENT_GATE_FAILED, Rule = mã luật, Field = trường, Position = "dòng n", Excerpt ≤ 80 ký tự. Cảnh báo mềm (tiền tệ / thời gian giao cụ thể, meta > 155) → Warnings.

Cài đặt cổng chặn: chạy bảng lên từng trường văn bản theo thứ tự Title → AltTitles → MetaDescription → Cta → BodyMarkdown → Faq → Brief. Thuần, không DB, không trạng thái. Văn bản được đưa về Unicode FormC trước khi so để chữ có dấu dạng tổ hợp (FormD) không lọt lưới regex. Phần áp luật lên một chuỗi nằm ở (tách ở GĐ A2 bưu cục, hành vi giữ nguyên — test ContentGateTextTests so từng phát hiện với bản chụp trước khi tách).

Trường lên website và trường nội bộ chịu mức phạt khác nhau (phản hồi của trợ lý AI 2026-09-13). Sáu trường đầu là thứ độc giả đọc — vi phạm cứng ở đó chặn lưu. Brief thì không có trường nào lên trang: audience, data_needed, editorial_notes là ghi chú cho người duyệt. Trước đây chúng chạy cùng một mức phạt, nên một dòng ghi chú hoàn toàn vô hại — "hồ sơ tác giả duy nhất trong kho" — dính GATE_03C và làm hỏng cả lời gọi create_article_draft; trợ lý phải né chữ trong ghi chú của chính mình, tức là luật chống hứa hẹn quảng cáo lại đi cấm một câu chẳng ai đọc. Vẫn chạy luật trên brief chứ không bỏ qua: brief ghi "hotline 1900 4509" hay "LADA là chuyển phát nhanh" là chỉ dẫn sai cho chính người viết bài sau đó — người duyệt cần thấy, chỉ là không đáng chặn lưu.

Số phát hiện tối đa cho một cặp luật × trường — đủ để sửa, không làm phình kết quả trả về.

Đuôi câu gắn vào cảnh báo của trường nội bộ — nói rõ vì sao lần này không chặn, để người đọc không tưởng cổng chặn đang hỏng.

Mã cảnh báo mềm khi meta description dài hơn .

Một đoạn văn bản đưa qua bảng luật, kèm việc nó có lên website hay không.

Một đoạn văn bản đưa qua bảng luật, kèm việc nó có lên website hay không.

Gom (Field, văn bản đã FormC) theo thứ tự người đọc gặp; bỏ qua trường rỗng.

Thay mỗi ô [[…]] bằng khoảng trắng cùng độ dài, giữ nguyên ký tự xuống dòng để số dòng báo lỗi không lệch.

Chạy bảng luật cổng chặn lên MỘT chuỗi văn bản — phần lõi tách ra khỏi (neo vào hình bài viết) để miền khác dùng được: hồ sơ bưu cục kiểm Intro, chú thích ảnh, hỏi đáp, thông báo tạm ngưng (docs/plan-buu-cuc.md §3.3 #10).

Thuần, không DB, không trạng thái. Văn bản được đưa về Unicode FormC trước khi so để chữ có dấu dạng tổ hợp (FormD) không lọt lưới regex. Không che ô [[…]] — đó là quy ước riêng của kho nội dung, việc của . Lỗi cứng: Code = CONTENT_GATE_FAILED, Rule = mã luật, Position = "dòng n", Excerpt ≤ 80 ký tự; luật mềm và mọi vi phạm ở trường nội bộ → Warnings.

Từ phủ định đứng giữa "LADA" và match làm câu thành phủ định ("LADA không phủ 63 tỉnh") — "không phải" đã nằm trong "không".

Áp đủ bảng luật lên , báo phát hiện dưới tên trường . = true: trường không lên website — vi phạm cứng chỉ thành cảnh báo (xem ).

Như nhưng ghi thêm vào một kết quả có sẵn.

Chạy một luật lên một trường. Vi phạm cứng ở trường lên website là lỗi; cùng vi phạm đó ở trường nội bộ chỉ là cảnh báo — xem .

Câu chứa match: [start, end) là đoạn không chứa dấu .!? hay xuống dòng bao quanh match.

Trong câu có "LADA" đứng trước match, và từ LADA gần nhất tới match không có từ phủ định.

FormC; chuỗi có surrogate hỏng thì giữ nguyên — vẫn chạy luật được.

Kết quả một lượt lọc HTML — kèm danh sách thứ bị cắt để đường xem trước nói được cho người bấm.

HTML sau khi lọc. Đây là chuỗi duy nhất được phép ghi vào Post.Description.

Mô tả từng thứ bị cắt ("thẻ <iframe>", "thuộc tính onerror trên <img>"…), đã gộp trùng.

Số lần cắt (đếm cả lần lặp lại), khác với số dòng trong .

Không cắt gì — nghĩa là HTML vào và ra giống nhau về cấu trúc.

Lọc HTML theo allowlist trước khi nó ra trang công khai (CS-9). Vì sao cần dù đã có : DisableHtml() chặn HTML thô trong nguồn Markdown, nó không lọc được thứ do chính extension của Markdig sinh ra, và cũng không bảo vệ được đoạn HTML mà GĐ F tự ghép thêm (khối <figure><img> chèn sau H2). Đây là lớp cuối cùng đứng giữa kho nội dung và Post.Description — chỗ website đọc ra bằng Html.Raw. Allowlist dựng từ số đo thật, không phải từ trí nhớ: 23 bài trong kho render ra đúng 20 thẻ (td p strong li tr h2 th h3 ul hr table thead tbody ol a em h1 code h4 blockquote) và 5 loại thuộc tính (h1–h4@id, a@href) — plan §4.7 câu 5. Phần còn lại của danh sách là những thẻ mà các extension đang bật có thể sinh ra dù nội dung hôm nay chưa dùng tới; thiếu chúng thì một bài dùng danh sách định nghĩa hay chú thích chân trang sẽ bị cắt mất chữ.

Lọc và cho biết đã cắt những gì. Trả chuỗi rỗng khi đầu vào rỗng.

Chính sách thứ hai, cho ô chữ định dạng người dùng gõ trong TinyMCE (Intro hồ sơ bưu cục — plan bưu cục §3.3): chỉ đoạn văn, xuống dòng, đậm/nghiêng/gạch chân, danh sách, tiêu đề phụ, trích dẫn; KHÔNG thuộc tính nào, KHÔNG link, KHÔNG ảnh. Thẻ ngoài danh sách bị gỡ nhưng GIỮ chữ bên trong (dán từ Word ra <span style>, <font>, <o:p> không làm mất câu); thẻ chạy mã / nhúng (script, style, iframe, object…) bỏ cả nội dung.

Không cho thuộc tính vì luật "không số điện thoại trong nội dung" chạy trên chữ thuần — số giấu trong href="tel:…", title, alt sẽ lọt. Không cho ảnh vì ảnh lên trang phải qua bước duyệt ảnh riêng.

Thẻ được giữ. Ba nhóm: (1) 20 thẻ đo được trên 23 bài thật; (2) thẻ các extension đang bật có thể sinh — pre (khối code rào), dl/dt/dd (DefinitionLists), abbr (Abbreviations), del/ins/sub/sup/mark (EmphasisExtras), col/colgroup/caption/tfoot (Pipe/GridTables), div/section + input (Footnotes, TaskLists), h5/h6, br; (3) thẻ do chính GĐ F ghép thêm: figure/figcaption/img cho ảnh chèn sau H2. Cố ý KHÔNG có span. HTML đăng lên website không được còn ô <span class="ld-placeholder"> nào — đó là thứ chỉ dùng cho màn duyệt. Không cho span nghĩa là nếu một ô lọt được tới đây thì nó lộ ra ngay ở lượt xem trước.

Thuộc tính được giữ, áp cho mọi thẻ. Không có on*, không có srcset, không có formaction, không có data-*. style có mặt vì PipeTables sinh style="text-align: right;" cho cột căn lề — cắt nó là bảng số trong bài mất căn lề. Nhưng nó chỉ là cửa: nội dung bên trong bị siết xuống đúng một thuộc tính, nên style="position:fixed" (lớp phủ toàn màn hình) vẫn bị cắt sạch.

Thuộc tính CSS duy nhất được giữ trong style — căn lề cột bảng của PipeTables.

Scheme URL được phép trong href/src. data: vắng mặt là có chủ đích: data:text/html;base64,… trong một thẻ a là XSS ở mọi trình duyệt còn chạy điều hướng. URL tương đối vẫn qua được vì BaseUrl để trống.

Thẻ của chính sách chữ định dạng ().

Thẻ bị gỡ CÙNG nội dung ở chính sách chữ định dạng — chữ bên trong là mã hoặc nội dung nhúng, giữ lại thành chữ thường chỉ là rác ("alert(1)" giữa đoạn giới thiệu).

Bộ công cụ ảnh: khối STYLE BASE/DO NOT dùng chung, từ điển khuôn ảnh, ảnh tham chiếu thương hiệu.

Ba danh mục nhỏ phục vụ đúng một việc: biến đặc tả ảnh trong kho nội dung thành thứ người tạo ảnh dùng được ngay — prompt ghép sẵn thay vì hai dòng "[… dán nguyên khối]", tên khuôn tiếng Việt thay vì mã "E2b", và ảnh tham chiếu tải về được thay vì phải đi tìm.

Ảnh chụp dùng để ghép prompt và hiện hướng dẫn ở màn chi tiết bài (chỉ đọc).

Toàn bộ bộ công cụ cho màn cấu hình, kể cả bản đã tắt, kèm số ảnh đang dùng từng khối.

Style base lấy CẢ bản đã tắt: ảnh cũ trỏ tới một phiên bản cụ thể phải ghép được bằng đúng bản đó, kể cả khi bản ấy đã nghỉ hưu. Ảnh tham chiếu thì chỉ lấy bản đang bật — đó là thứ người dùng sắp tải về.

Đường dẫn ảnh chỉ được là đường dẫn tương đối hoặc http/https.

Giá trị này đi thẳng vào <img :src> và <a :href> của tab Bộ ảnh, hiện cho mọi người có ContentStore.GetById — rộng hơn hẳn nhóm sửa được nó. Không chặn scheme thì một người có ManageAssets gài được javascript: vào liên kết mà người khác bấm. Bình thường trường này do PictureController điền nên luôn là đường dẫn tương đối.

Một file nháp đã đọc vào bộ nhớ — service không biết gì về HTTP hay đĩa.

Nhập bài từ file Markdown 4 phần: đọc file → tạo đề bài nếu hàng đợi chưa có → tạo bản nháp bằng đúng mà MCP và REST dùng. Đây là đường vào cho trợ lý không có MCP (ChatGPT, Gemini) và cho 30 file nháp đã viết trước khi kho nội dung tồn tại. Không có luật nghiệp vụ riêng ở đây: mọi cổng chặn, phiếu chấm, luật ảnh đều là của CreateDraft, nếu không sẽ có hai bộ luật lệch nhau.

Chỉ đọc và soát, không ghi gì — để xem trước 30 file trước khi nhập thật.

Nhập cả thư mục trên máy chạy API; đường dẫn do người gọi đưa, không hard-code.

Đuôi file duy nhất nhận vào.

Số file tối đa một lượt — 30 file là cỡ thật, để rộng gấp đôi cho chắc.

Đề bài chưa có trong hàng đợi — dựng từ dòng 1 của file (mã, nhánh L2, loại trang) + tiêu đề bài.

Soát trước: nói rõ đề đã có chưa, slug còn trống không — không ghi gì.

Dọn chuỗi [[CẦN …]] còn sót trong nội dung cũ.

Kho nội dung từng có cơ chế "ô chờ": trợ lý AI để trống mọi số liệu chưa kiểm chứng bằng [[CẦN SỐ THẬT: …]] / [[CẦN NGUỒN: …]], người duyệt điền từng ô, và bài không đăng được khi còn ô mở. Cơ chế đó bị bỏ hẳn 2026-09-12 (plan §6.8): quá nhiều ô, điền tay còn lâu hơn tự viết. Nay trợ lý AI tra cứu và viết thẳng số vào bài. Lớp này là thứ duy nhất còn lại của cơ chế cũ, và nó không còn là "ô" nữa mà là bộ lọc rác: bài nháp cũ (và bài do prompt chưa cập nhật sinh ra) vẫn có thể mang chuỗi ấy, mà chuỗi ấy lọt ra trang công khai thì rất khó coi. Dùng ở ba chỗ: làm sạch nội dung lúc đăng, lọc heading khi sinh slug và mục lục, và che khỏi cổng chấm nội dung để luật gate không chấm nhầm phần chỉ dẫn.

Nhóm 1 = nhãn ("CẦN SỐ THẬT"), nhóm 2 = mô tả sau dấu hai chấm (có thể vắng). Nhãn không chứa ']' hay ':'; mô tả non-greedy tới ']]' đầu tiên.

Bản dò RỘNG: chỉ cần [[ + khoảng trắng tuỳ ý + CẦN là tính, không đòi đóng ]].

Hàng rào cũ (ContentPublishHtmlBuilder.ODuLieuConSot) chặn đăng bằng đúng phép dò tiền tố này, nên nó phủ cả những chuỗi dị dạng mà không khớp: [[ CẦN NGUỒN: …]] (thừa dấu cách), [[CẦN NGUỒN [1]: …]] (nhãn có ]), [[CẦN: …]] (thiếu dấu cách), [[CẦN SỐ THẬT: 2024 (file nhập bị cắt, không đóng ngoặc). Dùng bản chặt cho việc bóc tách (parser cần hai nhóm nhãn/mô tả), dùng bản rộng cho việc dọn và đếm — thu hẹp phép dò lúc dọn là để chỉ dẫn biên tập nội bộ lọt ra trang công khai mà không ai được cảnh báo.

Đếm số chuỗi còn sót — để cảnh báo trước khi đăng (không chặn đăng). Đếm theo bản RỘNG.

Còn chuỗi nào không — dùng để canh bất biến "không chuỗi ô chờ nào ra trang công khai".

Xoá sạch chuỗi [[CẦN …]], gộp khoảng trắng thừa và dọn dấu câu bị bỏ rơi.

Xoá trơ để lại những câu kiểu "Phạt tiền ." hoặc "mức phạt là ,". Không cứu được nghĩa câu — người viết mới cứu được — nhưng ít nhất không để lại khoảng trắng đôi và dấu câu lơ lửng.

Thay bằng một khoảng trắng — dùng khi cần giữ ranh giới từ (sinh slug, mục lục).

Ghép prompt đầy đủ cho một ảnh: khối STYLE BASE dùng chung + phần riêng của ảnh + khối DO NOT.

Đặc tả §4.6 cố ý chỉ lưu phần riêng trong ContentImage.PromptEn. Người viết bài viết phần riêng theo hai kiểu, cả hai đều gặp trong dữ liệu thật: Có chỗ trống — một dòng "[STYLE BASE … dán nguyên khối]" ở đầu và "[DO NOT … ]" ở cuối; khi đó phải thay đúng dòng đó để giữ nguyên phần giữa. Không có chỗ trống (như fixture w2-01.md) — prompt tự chứa; khi đó nối khối chung vào trước và sau. Lớp này thuần hàm, không chạm DB, để test được không cần fixture: mọi dữ liệu tra cứu truyền vào qua .

Làn mặc định khi ảnh không ghi làn nào — làn A là brand kit ON, đúng mặc định của đặc tả §4.6.

Dòng chỗ trống: mở đầu bằng "[", có chữ khoá, kết thúc bằng "]" trên cùng một dòng. Bắt cả "[STYLE BASE — LADA EXPRESS (brand kit ON) — dán nguyên khối]" lẫn "[STYLE BASE làn A …]".

Kết quả ghép — tách riêng lý do thiếu để giao diện nói được cụ thể thay vì im lặng.

Prompt đã ghép; null khi không ghép được.

Không tìm được khối STYLE BASE nào áp dụng cho ảnh này.

Mã phiên bản đã dùng (để giao diện chỉ đúng bản ghi khi cần sửa).

Ghép prompt cho một ảnh. rỗng (ảnh dựng tay, chụp thật, không ảnh) thì trả FullPrompt = null và không coi là thiếu khối chung — những ảnh đó vốn không có prompt.

Tìm khối chung áp dụng cho ảnh.

Ảnh có ghi mã phiên bản: tra đúng mã đó, kể cả bản đã tắt — ảnh cũ phải ghép được bằng đúng bản nó tham chiếu. Không thấy mã đó thì trả null (→ StyleBaseMissing): lặng lẽ thay bằng bản mặc định là đưa cho người tạo ảnh một câu lệnh trông như đã ghép đúng, trong khi nó tả một bộ nhận diện khác với bộ mà bài này được viết cho. Ảnh không ghi mã: lấy bản mặc định của làn, rồi tới bản đang bật đầu tiên của làn. Bản đã tắt không bao giờ được chọn ở nhánh này — tắt nghĩa là "đừng dùng cho ảnh mới".

Một ảnh sẵn sàng chèn vào thân bài.

Slug của H2 mà ảnh thuộc về — khớp .

Chú thích, đồng thời là alt. Rỗng thì không in figcaption.

Kết quả dựng thân bài — HTML, mục lục và các con số để đối chiếu ở lượt soát thử.

Số ảnh thật sự chèn được — ảnh có H2Key không khớp H2 nào thì không chèn.

Ảnh bị bỏ vì không tìm được H2 tương ứng; hiện ra ở lượt soát thử chứ không im lặng.

Số H1 gặp trong thân bài. Bằng + .

H1 MỞ ĐẦU bị gỡ hẳn vì trang đã có H1 tiêu đề — nhiều nhất một cái.

H1 được hạ xuống H2 vì nó là một mục nội dung thật, không phải bản sao tiêu đề.

H2 trùng tên nhau — ảnh khai H2Key theo slug sẽ dồn hết vào cái ĐẦU, vì slug thứ hai đã bị đổi thành -2. Hiện ra ở lượt soát thử chứ không im lặng.

Một khối heading trọn vẹn — thẻ mở, thuộc tính, phần trong, thẻ đóng.

Ô dữ liệu chưa điền còn sót lại — không được phép ra trang công khai.

Mục lục đúng hình dạng CMS đang dùng — <ul><li><a href="#slug">, khớp Views/Post/Detail.cshtml vốn Html.Raw thẳng khối này vào div.ld-toc. H3 nằm trong một <ul> lồng bên trong mục H2 chứa nó — .ld-toc ul ul của site.css đã có sẵn thụt lề và đánh số "1.1." cho đúng hình dạng này.

Khối ảnh chèn sau H2. CaptionAlt đóng cả hai vai — alt và chú thích nhìn thấy được — nên alt để RỖNG khi đã in figcaption: trình đọc màn hình đọc figcaption như phần của figure, để cả hai là nó đọc đúng câu đó hai lần. Ảnh không có chú thích thì ngược lại — alt là thứ duy nhất mô tả ảnh, phải giữ.

Hai H2 trùng tên thì neo thứ hai thành -2 — trùng id là mục lục nhảy sai chỗ.

Xuất bản một bài từ kho nội dung sang CMS Post — bước cuối của cả đợt, và là lần đầu tiên dữ liệu kho nội dung chạm tới website đang phục vụ khách (nguyên tắc §1 của plan).

Ba lớp chặn, xếp theo thứ tự cố ý. (1) Công tắc AppConfig ContentStore.PublishEnabled — mặc định TẮT, và chỉ chặn đường ghi: soát thử vẫn chạy được khi công tắc tắt, vì soát thử là cách người vận hành kiểm bài trước khi xin bật công tắc. (2) Bài phải đang ở Approved. (3) Chạy lại đủ 8 điều kiện §3.3d ngay trước khi ghi — CS-34. Vì sao (3) không thừa dù bài đã Approved. Approved nghĩa là "đủ điều kiện tại thời điểm duyệt", không phải "đủ điều kiện mãi mãi". GĐ E đã bịt hai cửa làm hỏng điều kiện sau khi duyệt (SetStatus, SetPeople) nhưng vẫn còn đường vòng thật: ContentAuthor/CreateOrUpdate xoá ProfileUrl của một tác giả là phá điều kiện (2) của mọi bài đã duyệt của người đó cùng lúc. Bịt cửa không thay được việc kiểm lại. Soát thử không ghi một dòng nào. Nhánh DryRun rẽ trước mọi lệnh ghi, không phải sau — đúng khuôn rút ra từ lỗi GĐ E (tool chốt cụm dữ liệu — nay đã gỡ cùng cơ chế ô chờ — gọi Save(Confirm=true) rồi mới rẽ nhánh dry_run, spec §13.8). Ở đây hậu quả nặng hơn hẳn một bậc: một bài rác trên website thật.

Soát thử hoặc xuất bản. Trả cùng một hình dạng kết quả cho cả hai chế độ để người bấm so được "sẽ ra cái gì" với "đã ra cái gì".

Đồng bộ lại ảnh của một bài đã xuất bản sang đúng Post của nó — ảnh đại diện / OG và ảnh chèn trong thân bài. Đường sửa sau cho trường hợp ảnh không sang cùng lúc đăng.

Chỉ đụng ba cột của Post: Thumbnail, OgImage, và Description/TOC. Không tạo Post, không đổi slug, danh mục, FAQ, trạng thái đăng hay trạng thái bài — đó là việc của , và gộp hai việc vào một hàm là cách chắc chắn để một ngày nào đó lượt "sửa ảnh" ghi đè cả bài. Không ghi đè thân bài người ta đã sửa tay. Thân bài chỉ được ghi lại khi Post.Description hiện tại còn đúng bằng bản kho dựng ra (có ảnh hoặc chưa có ảnh). Khác đi nghĩa là ai đó đã sửa trong CMS — lượt này chỉ cập nhật ảnh đại diện và nói rõ phần thân bài phải tự chèn.

Job đồng bộ: bài có PostId mà Post đã Published ⇒ bài sang Published. Ghi audit từng bài — job không được là nơi duy nhất biết chuyện đó.

Danh mục CMS cho bài viết (ContentType = Post), đánh dấu cái đang là mặc định. Vì sao miền này tự phục vụ danh sách thay vì để giao diện gọi Category/GetTree. Đường kia gác role Category.GetTree — một role của miền CMS. Người chỉ có ContentStore.Publish sẽ thấy màn đăng với ô chọn danh mục trống rỗng và không hiểu vì sao. Đây đúng là hình dạng của CS-28 (màn token chết vì thiếu User.SugStaff); không lặp lại.

Khoá công tắc — mặc định "false", và khoá thiếu cũng là "false" (không cache khoá thiếu).

Danh mục CMS mặc định khi bài không chọn (§7.10).

Role của CMS cho phép đăng thẳng — đường "Đăng ngay" của §7.11 đòi đúng role này.

Founder đi qua bypass của ServerRoleAuthorizationHandler nên có mọi quyền (§7.4b).

Múi giờ ghi mốc đăng — tường minh, không lấy múi giờ của máy chạy job (§4.7 câu 3).

Ảnh đưa được sang CMS: đã có file và không bị từ chối. Vì sao không đòi Approved (sửa 2026-09-12). Luật cũ "chỉ ảnh đã duyệt mới lên CMS" đúng khi đứng một mình, nhưng ghép với hai luật khác thì thành bẫy: cổng đăng (5) cho bỏ qua "ảnh chưa duyệt" bằng cờ PublishWithoutImages, còn SetImageStatus khoá cả bộ ảnh ngay khi bài sang Approved. Quên bấm duyệt ảnh trước khi duyệt bài là hết đường sửa; người duyệt bật cờ để đi tiếp và ảnh đã nộp file bị vứt im lặng — đúng việc đã xảy ra với bài W2-25 (Post #64) ngày 12/09/2026: hai ảnh có file trên media.ladaexpress.vn, Post ra đời không ảnh đại diện, thân bài không ảnh nào. Ảnh Rejected vẫn bị loại — đó mới là câu "không dùng ảnh này". Spec/Generating rụng theo điều kiện có file, nên không cần kể tên.

Hai chuỗi HTML có phải cùng một bản không. Chuẩn hoá xuống dòng và cắt khoảng trắng hai đầu — hai thứ duy nhất đổi được trên đường đi qua EF/SQL mà không đổi nghĩa. Cố ý không chuẩn hoá sâu hơn: bài bị sửa tay trong CMS phải bị nhận ra là đã sửa, kể cả khi chỉ khác vài khoảng trắng.

Ảnh đại diện / OG dùng được, hoặc null khi bài không có.

Ảnh chèn vào thân bài, đã dọn ô chờ khỏi chú thích.

Tìm danh mục CMS đích theo ba bậc, dừng ở bậc đầu tiên cho kết quả: Id chọn tường minh (tham số lượt đăng, hoặc ContentArticle.CmsCategoryId) — người bấm nói rõ thì nghe người bấm. Mã nhánh nội dung của bài (CategoryL2) khớp Category.ContentCategoryCode. AppConfig ContentStore.DefaultCategoryId. Vì sao bậc 2 phải có. Trước khi có nó, không đường nào điền CmsCategoryId trước lúc đăng — cột ấy chỉ được GHI ở cuối hàm , tức là ghi lại kết quả chứ không phải đầu vào. Nên bậc 1 luôn trống và mọi bài rơi thẳng xuống bậc 3: đo trên production 2026-09-14, 10/10 bài đã đăng nằm sai danh mục, 8 trong số đó dồn vào đúng một danh mục mặc định. Kế hoạch nội dung vốn đã xếp từng bài vào một nhánh (A1…F4); bậc 2 chỉ là đọc lại điều bài đã tự khai. Bậc 2 không lọc theo ContentType: mã nhánh là duy nhất toàn bảng (chỉ số UX_Category_ContentCategoryCode), nên khớp được mã là khớp đúng danh mục. Lọc thêm chỉ tạo ra cảnh "gắn mã rồi mà vẫn đăng vào danh mục mặc định" không ai giải thích nổi.

Tên tag của bài: từ khoá chính trước, rồi các từ khoá phụ theo đúng thứ tự bài khai. Chuẩn hoá y hệt TagService của CMS — ToLower().Trim() — để bài do kho nội dung đăng và bài biên tập viên gõ tay dùng CHUNG một dòng Tag, không đẻ ra hai bản ghi "cod hàng nặng" và "COD hàng nặng" nằm cạnh nhau trên trang tag. Cắt theo và bỏ tên rỗng: Tag.Name là nvarchar(256), và một từ khoá dài quá cột sẽ làm cả lượt đăng vỡ ở lệnh INSERT sau khi Post đã ghi xong.

Ghi PostTag cho bài vừa tạo, tạo Tag mới cho tên chưa có. Dùng lại dòng Tag sẵn có thay vì luôn tạo mới, và tra bằng đúng tên đã chuẩn hoá. Tag trùng tên là hai trang tag rời nhau trên website, mỗi trang một nửa số bài. Tag mới kèm UrlRecord dựng theo cùng nếp TagService.CreateAsync: slug bỏ dấu tiếng Việt, đụng slug thì nối hậu tố đếm. Tag không có UrlRecord là một tag không bấm vào được — hiện ra trên bài mà dẫn tới 404.

Slug chưa ai dùng cho một tên tag. QueryAll chứ không Query: UrlRecord xoá mềm vẫn giữ chỗ ở chỉ số của DB, nhìn bằng Query là kết luận "còn trống" rồi vỡ ở lệnh INSERT — cùng cái bẫy mà đường kiểm slug bài viết đã cắn phải.

Nhật ký lượt chạy nháp bài (đặc tả §5.1 append_run_log). Một dòng cho mỗi lượt trợ lý AI chạy, để đối chiếu về sau: hôm đó nháp mấy bài, điểm trung bình bao nhiêu, còn bao nhiêu ô phải điền.

Các lượt gần nhất, mới trước — màn quản trị và trợ lý AI cùng đọc.

Ánh xạ tay (không qua AutoMapper) vì 4 cột là JSON phải parse — profile không nên giấu lỗi JSON.

Danh sách trang dịch vụ đang chạy trên website (đặc tả §5.3 list_service_pages). Trợ lý AI đặt link nội bộ theo danh sách này thay vì bịa URL — đây là toàn bộ lý do tool tồn tại.

Đọc thẳng Product + UrlRecord nên số trang luôn đúng thực tế (Việc 0 GĐ A đo được 25, không phải 24 như đặc tả ghi) và tự đúng khi marketing thêm trang mới. Không suy loại trang từ enum . Dữ liệu thật có giá trị 0 — 13/25 trang — mà enum không khai (General = 1, Bike = 2, Household = 3, Fulltrip = 6), nên GetDescription() trên giá trị 0 trả về chuỗi rỗng. Item trả cả số thô lẫn nhãn đọc được.

Tiền tố slug của trang dịch vụ trên website.

Tên tỉnh của cả hai bộ địa giới đang sống song song trong bảng Location (bộ 34 tỉnh sau sáp nhập và bộ 63 tỉnh cũ): tiêu đề trang dịch vụ viết từ trước sáp nhập nên còn tên tỉnh cũ. Luật lọc/sắp nằm ở .

Mã lỗi nghiệp vụ của kho nội dung AI — dùng chung cho REST (GĐ A) và MCP (GĐ C). Chuỗi mã là hợp đồng với trợ lý AI, không đổi.

Bảng này là bảng thật, không phải bảng §5.4 của đặc tả 0.1. Bốn mã của cơ chế ô chờ và cụm dữ liệu (PLACEHOLDER_NOT_FOUND, PLACEHOLDER_NOT_OPEN, CLUSTER_NOT_FOUND, CLUSTER_NOT_CONFIRMED) đã bỏ cùng cơ chế 2026-09-12 — giữ lại mã chết chỉ khiến trợ lý AI tin là đường đó còn sống. Thêm mã mới thì thêm cả nhánh trong .

topic_code không tồn tại.

Đề bài không ở trạng thái chờ nháp (blocked/dropped).

Đã có bài cho topic_code này (kèm ArticleId cũ trong Extra).

Slug trùng (kèm gợi ý slug mới trong Extra).

Vi phạm cổng chặn nội dung cứng (kèm danh sách vi phạm có vị trí).

expected_version lệch bản hiện tại.

Đổi trạng thái sai máy trạng thái.

Duyệt/đăng khi chưa đủ điều kiện (kèm danh sách thiếu).

Quá giới hạn kích thước (512 KB payload, 200 KB thân bài).

Phiếu tự chấm không nhất quán (total ≠ Σ, điểm > max, thiếu mục, todo ≠ 3…).

Bộ ảnh vi phạm quy tắc cứng §7.4 đặc tả (bổ sung ngoài bảng §5.4 — đặc tả ghi 422 nhưng không đặt mã).

Payload thiếu trường bắt buộc hoặc sai định dạng (bổ sung ngoài bảng §5.4).

Không có bài với article_id / topic_code / slug đã gửi (bổ sung ngoài bảng §5.4, GĐ B).

Token truy cập cá nhân (PAT) không tồn tại — GĐ C.

Dòng ảnh không tồn tại (set_image_status — GĐ D).

Bài khai PostId nhưng bài viết CMS đó không còn (bị xoá trong CMS sau khi đăng).

Công tắc AppConfig ContentStore.PublishEnabled đang tắt (GĐ F). Chỉ chặn đường ghi — soát thử vẫn chạy.

Không xác định được danh mục CMS: bài chưa chọn và ContentStore.DefaultCategoryId sai hoặc trỏ vào danh mục đã xoá (GĐ F, §7.10).

Thiếu quyền cho chính thao tác đang gọi, dù đã qua cổng [Authorize] của controller — hiện chỉ dùng cho "Đăng ngay" đòi Post.Publish (GĐ F, §7.11).

Giới hạn thân bài Markdown (ký tự) — đặc tả §9: 200 KB.

Giới hạn toàn payload (byte) — đặc tả §9: 512 KB.

Ánh xạ mã lỗi → HTTP status cho REST. MCP (GĐ C) dùng JSON-RPC error, không dùng hàm này.

JSON cho các cột *Json của bảng Content*: Newtonsoft, tên thuộc tính PascalCase như DTO (nội bộ, không phải hợp đồng MCP — GĐ C chuyển snake_case ở lớp tool). Null-safe hai chiều.

Trải phẳng mọi giá trị chuỗi trong một object JSON theo thứ tự khai báo thuộc tính (depth-first). Đường dẫn dạng EditorialNotes, DataNeeded[1], Branch.Address. Dùng chung cho trích placeholder và cổng chặn để hai bên đếm cùng một danh sách văn bản.

Mọi nút chuỗi của một object, đúng thứ tự mà duyệt. Trả về nút sống trong nên sửa Value là sửa luôn cây — đây là cách thay ngược giá trị vào đúng ô của Brief/Footer mà không phải viết lại đường dẫn.

Chuyển object thành cây JSON bằng đúng — để cây khớp chuỗi sẽ lưu.

Chuẩn hoá văn bản dùng chung cho so khớp từ khoá cụm dữ liệu và nhãn ô: FormKC (gấp ký tự tương thích: "m³" → "m3", chữ toàn chiều rộng → thường), bỏ dấu tiếng Việt (StringHelper.Unsigned), chữ thường, gộp khoảng trắng. Từ khoá seed trong DB đã ở dạng này; collation SQL_Latin1_General_CP1_CI_AS cũng coi "gia/m3" = "gia/m³" nên seed chỉ giữ dạng đã gấp. Regex gộp khoảng trắng chỉ khai báo ở đây — renderer và extractor gọi .

Gộp mọi chuỗi khoảng trắng (kể cả tab, xuống dòng) thành một dấu cách rồi Trim; null/rỗng → chuỗi rỗng. Không đổi hoa thường, không bỏ dấu — muốn cả hai thì dùng .

Số dòng (1-based) của vị trí ký tự trong văn bản.

Đoạn trích ≤ maxLen ký tự quanh [index, index+length), thay xuống dòng bằng khoảng trắng.

Nút và mục điều hướng nào của kho nội dung AI được hiện cho một người (rule quyen-hien-thi).

Hàm thuần — không chạm database, không đọc HttpContext: nhận danh sách role đã phân giải, trả các cờ. Cùng khuôn với ChatNavPermissions của miền chat, và vì cùng một lý do: luật quyết định ai thấy gì phải có ca test gọi thẳng vào nó, chứ không nằm rải trong controller. Vì sao cần cờ từ máy chủ. SPA cố ý không nhận danh sách role vào router (beforeEach chỉ kiểm đăng nhập), nên meta.roles là tài liệu chứ không phải hàng rào. Menu thì đã được MenuService lọc theo Menu.AllowRoles, nhưng nút bên trong trang — Đổi trạng thái, Nộp ảnh, Tạo token — không có ai lọc hộ. Chép danh sách role sang JavaScript là dựng nguồn sự thật thứ hai, và cái lệch chỉ lộ ra khi người duyệt bấm vào rồi ăn 403. Mỗi cờ đọc đúng bó quyền của thứ nó gác, không phải bó quyền của lời gọi nạp dữ liệu: ví dụ CanEdit lấy đúng ContentStore.Edit của SetStatus/ SetPeople/SetImageStatus, không lấy ContentStore.GetById vốn rộng hơn.

Vai bỏ qua mọi kiểm tra role của hệ thống (ServerRoleAuthorizationHandler).

Role đã phân giải qua IUserRoleResolver; null hoặc rỗng = không có quyền nào.

Cờ ẩn/hiện của kho nội dung AI — FE đọc bằng === true, mặc định false, và ẩn hẳn phần tử.

Cờ ẩn/hiện của kho nội dung AI — FE đọc bằng === true, mặc định false, và ẩn hẳn phần tử.

Một phát hiện của luật nghiệp vụ (lỗi cứng hoặc cảnh báo mềm). Luôn kèm trường và vị trí để người duyệt / trợ lý AI sửa đúng chỗ — đặc tả §5.4 yêu cầu "kèm vị trí".

Mã lỗi nghiệp vụ (ContentStoreErrorCodes) — với cảnh báo mềm có thể null.

Mã luật cụ thể, ví dụ GATE_01_HOTLINE_CU, IMG_LANE_A_UNBRANDED, SCORE_TOTAL_MISMATCH.

Trường bị vi phạm theo tên PascalCase của DTO: BodyMarkdown, MetaDescription, Title, Faq[2].A, Brief.EditorialNotes, Images[3].PromptEn, SelfScore.Sections.A_facts…

Vị trí trong trường: "dòng 12", "h2:cuoc-tinh-the-nao", "faq:2"… null nếu không áp dụng.

Đoạn văn bản quanh chỗ vi phạm (≤ 80 ký tự) để nhận ra ngay.

Thông điệp tiếng Việt cho người đọc.

Kết quả kiểm tra của một lớp luật thuần: lỗi cứng chặn lưu, cảnh báo mềm chỉ trả về.

Gộp kết quả của lớp luật khác vào (dùng trong service tổng hợp).

Kết quả trả về của service kho nội dung. Khác BaseResult của repo ở chỗ có mã lỗi nghiệp vụ, danh sách vi phạm có vị trí và dữ liệu phụ (ArticleId cũ, gợi ý slug…) — vì REST của miền này trả 201/404/409/413/422 theo mã (prompt GĐ A), và MCP cần cùng cấu trúc cho JSON-RPC error.

Mã lỗi từ ContentStoreErrorCodes; null khi Success.

Vi phạm cứng kèm vị trí (gate, ảnh, phiếu chấm, validation).

Cảnh báo mềm — chỉ trả về, không chặn. Nguồn duy nhất: Data không lặp lại danh sách này.

Dữ liệu phụ theo mã lỗi: ArticleId (ALREADY_EXISTS), SlugSuggestion (SLUG_TAKEN), CurrentVersion (VERSION_CONFLICT)…

Tạo lỗi từ kết quả kiểm tra luật (lấy mã của lỗi đầu tiên nếu không truyền).

Người/ứng dụng thực hiện thao tác — ghi vào audit và cột audit của entity.

"admin" cho REST/FE; "mcp:<client_id>" cho MCP (GĐ C).

Request-id để lần vết; REST GĐ A để null, MCP GĐ C sinh Guid mỗi request.

Đóng dấu cột audit của BaseEntity theo actor — dùng chung cho mọi entity kho nội dung ghi mới.

Tên hành động ghi vào ContentAuditLog.Action — một nơi để FE/MCP lọc đúng chuỗi.

Dựng dòng ContentAuditLog đã đóng dấu audit — hai service dùng chung để không lệch cột.

Mã đề bài dạng W2-01 / W12-05 (đặc tả §5.1). Một regex duy nhất cho cả service đề lẫn service bài — trước đây mỗi bên giữ một bản riêng, sửa một nơi là lệch nơi kia.

Nhóm 1 = tuần (1–2 chữ số), nhóm 2 = số thứ tự trong tuần (đúng 2 chữ số).

Đúng định dạng W{tuần}-{stt}; null/rỗng → false. Không tự Trim — bên gọi quyết định.

W2-03 → 2, W12-05 → 12; null nếu mã không đúng định dạng.

Hàng đợi đề bài của kho nội dung AI (đặc tả §5.1 list_topics / create_topics).

Danh sách đề cho màn quản trị theo SmartTableParam (Keyword, Status, CategoryL2, WeekNo, PageType).

Danh sách đề cho trợ lý AI: lọc Status / WeekNo / loại trừ L2, theo SortOrder tăng dần, tối đa 100.

Tạo nhiều đề một lần. Dòng sai định dạng / trùng mã bị từ chối riêng (Rejected là dữ liệu, không phải lỗi); các dòng hợp lệ ghi trong một transaction kèm một dòng audit.

update_topic_status (đặc tả §5.1): đổi trạng thái một đề trong hàng đợi. Drafted bắt buộc kèm ArticleId — đề "đã nháp" mà không trỏ tới bài nào là dữ liệu sai.

Ngưỡng cảnh báo tiêu đề trùng (đặc tả §5.1: "cảnh báo nếu title trùng ≥ 85%").

Cảnh báo đề mới trùng ý với đề / bài đã có (đặc tả §5.1: ≥ 85%). So bằng hệ số Dice trên tập trigram của tiêu đề đã bỏ dấu — đủ để bắt "Gửi tủ đông đi Thanh Hoá" ~ "Gửi tủ đông đi Thanh Hóa" và không cần extension nào của SQL Server.

Tập trigram của tiêu đề đã chuẩn hoá (bỏ dấu, thường, gộp khoảng trắng).

Hệ số Dice: 2·|giao| / (|A| + |B|) — 1 là hai chuỗi giống hệt sau chuẩn hoá.

Slug các H2 trong thân bài (từ IMarkdownRenderer) — để cảnh báo H2 chưa khai báo ảnh.

Kiểm bộ ảnh (đặc tả §7.4, Phụ lục A, plan §3.3f). Field báo lỗi dạng Images[i].PromptEn (i = chỉ số trong mảng gửi lên), Position = "OrderNo n". Lỗi cứng có Code = IMAGE_SPEC_INVALID: IMG_THUMBNAIL_COUNT (≠ 1 ThumbnailOg) · IMG_ORDER_DUP (OrderNo trùng hoặc < 1) · IMG_ROLE_DECISION_MISSING · IMG_SIZE_NOT_16 (Tool ∈ {GptImage2, NanoBanana} mà thiếu kích thước hoặc không chia hết 16) · IMG_LANE_A_UNBRANDED (Lane = "A" mà PromptEn chứa "unbranded" / "no logos" / "no text of any kind" / "render no text", không phân biệt hoa thường — nêu đúng cụm) · IMG_PROMPT_NOT_ALLOWED (ManualCanva/RealPhoto mà PromptEn không rỗng) · IMG_NONE_REASON (None mà thiếu NoneReason) · IMG_AIPROMPT_MISSING (AiPrompt thiếu FrameCode/Lane/Tool/WidthPx/HeightPx/BriefVi/CaptionAlt/PromptEn) · IMG_FRAME_CODE (không khớp ^[A-E][1-6][a-d]?$) · IMG_LANE (khác "A"/"B"). Cảnh báo mềm: IMG_THUMB_SPEC (thumbnail không phải E1 1200×800) · IMG_REAL_PHOTO_EXPECTED (PageType BranchNews/Feature/CaseStudy mà ảnh Inline là AiPrompt) · IMG_TEXT_PHONE (TextOnImage chứa số điện thoại) · IMG_H2_NO_IMAGE (H2 không có dòng ảnh nào) · IMG_H2_UNKNOWN (H2Key không khớp H2 nào).

Cài đặt — luật thuần trên payload ảnh, không chạm DB. Mã rule và ngữ nghĩa theo XML-doc của interface; mọi issue cấp dòng ảnh có Position = "OrderNo n", issue cấp bộ ảnh có Field = "Images". Ảnh None có H2Key vẫn tính là "H2 đã có dòng ảnh" — quyết định không dùng ảnh (kèm lý do) cũng là một quyết định.

Cụm cấm trong prompt làn A: làn A là brand kit (có logo/chữ thương hiệu), các cụm này mâu thuẫn với nó.

Số điện thoại VN trong chữ trên ảnh: 0 hoặc +84 rồi 9–10 chữ số, hoặc 1900 rồi 4–6 chữ số; giữa các chữ số cho phép một khoảng trắng / dấu chấm nên bắt được mọi cách nhóm ("0912 345 678", "091 234 5678", "1900.633.658"); không được nằm giữa dãy số dài hơn (mã đơn, số tiền) nhờ lookaround.

Loại trang mà ảnh trong bài nên là ảnh chụp thật (tin bưu cục, phóng sự, case study).

Toàn bộ luật cấp một dòng ảnh — lỗi cứng trước, cảnh báo mềm sau.

H2 nào cũng phải có một dòng ảnh (kể cả None kèm lý do); H2Key lạ báo để sửa slug. Không có H2 thì bỏ qua.

Dòng 1 của file nháp: mã đề, nhánh L2, loại trang, ngày nháp, số ảnh khai báo, trạng thái.

Nguyên văn dòng 1 (đã gỡ ký hiệu Markdown) — để đưa vào thông báo lỗi.

Tên loại trang tiếng Việt nguyên văn trong file ("trang loại hàng").

Ngày nháp ghi ở dòng 1 — vào ContentTopic.DraftedAt khi tạo đề.

Số ảnh khai báo ("6 ảnh") — chỉ để đối chiếu với số khối đọc được ở phần (c).

Tuỳ chọn đọc file nháp — không có gì bắt buộc, mặc định đủ chạy.

Giá trị DraftedBy của bài tạo ra (đặc tả: "claude-routine" hoặc tên người).

Ép slug thay vì suy từ tiêu đề — người nhập tự đặt khi slug suy ra bị trùng.

Kết quả đọc một file nháp: payload tạo bài + thông tin đề bài + đối chiếu số lượng.

Số ô ghi ở dòng cuối "Danh sách ô cần điền" — chỉ để đối chiếu, không lưu.

Số ô [[CẦN …]] đếm được trên toàn bộ payload đã đọc.

Lỗi cấu trúc (chặn) và cảnh báo (không chặn), đều kèm số dòng.

Đọc file bài nháp Markdown 4 phần thành payload tạo bài (Phụ lục C đặc tả). Thuần, không chạm DB.

Tên file — chỉ để ghi vào thông báo lỗi. Toàn bộ nội dung file.

Cài đặt . Nguyên tắc. File do trợ lý AI viết tay nên hình thức luôn lệch đôi chút: parser chấp nhận biến thể (nhãn có/không in đậm, dấu hai chấm trong/ngoài cặp **, gạch đầu dòng khác nhau, tiêu đề phần ghi # (a) BRIEF hay # a) Brief) và chỉ báo lỗi cứng khi thiếu thứ không suy ra được: dòng 1, một trong 4 phần, tiêu đề, meta, thân bài, bộ ảnh. Mọi lệch còn lại là cảnh báo kèm số dòng — mất dữ liệu im lặng nguy hiểm hơn một file bị từ chối. Tiêu đề trong file khác tiêu đề trong CSDL. File viết ## H1: … / ## H2: … (quy ước của người viết), còn BodyMarkdown lưu Markdown thật (# … / ## …) vì slug H2 do sinh phải khớp ContentImage.H2Key và PositionKey của ô dữ liệu. Parser bỏ tiền tố Hn: và hạ/nâng đúng cấp.

Độ dài cột ContentArticle.Slug — slug suy từ tiêu đề phải nằm trong khoảng này.

Khối ảnh mở đầu bằng "Ảnh 3 — …" (có thể bọc ** hoặc là tiêu đề ###).

Ngày ở dòng 1: 2026-09-03 hoặc 03/09/2026.

Một mục của bảng kê ô: số, từ đếm tuỳ chọn ("ô", "×", "khối", "hạng mục"), rồi tên ô.

Một dòng chữ trên ảnh: khu vực dưới: "GỬI TỦ ĐÔNG" (≤ 24 ký tự).

Khoảng dòng nửa mở [Start, End) — Start là dòng ngay sau tiêu đề phần.

Cắt file theo tiêu đề cấp 1. Nhận cả "# (a) BRIEF" lẫn "# a) Brief" / "# BRIEF"; phần nào không nhận ra thì bỏ qua (và sẽ báo thiếu ở cuối). Mọi thứ từ dòng "Danh sách ô cần điền" trở đi không thuộc phần nào — nó là bảng đối chiếu, không phải nội dung.

Chỉ số dòng "**Danh sách ô cần điền:**"; -1 nếu file không có.

Nhãn của phần brief → khoá nội bộ. Một khoá nhiều cách viết vì file mỗi tuần một khác.

Chia phần thân thành thân bài / FAQ / chân trang theo tiêu đề cấp 2, giữ nguyên thứ tự các khối không phải FAQ hay chân trang. Tiêu đề ## Hn: X viết lại thành đúng cấp n.

Mỗi câu hỏi mở đầu bằng **Câu hỏi?** hoặc một tiêu đề con; dòng sau nối vào câu trả lời.

"e2D" / "E2d" / "E2D" → "E2d": chữ khuôn hoa, hậu tố biến thể thường.

Có phải mô tả ảnh đại diện / OG không. "og" phải đứng trọn từ: dò Contains("og") thì một khối tên "ảnh logo đối tác" cũng thành ảnh đại diện, và bài sẽ có hai thumbnail → 422.

Quyết định ảnh suy từ từ khoá viết hoa trong khối (Phụ lục C), xét theo thứ tự ưu tiên cố định.

Câu sau "KHÔNG ẢNH" trên cùng dòng là lý do (Phụ lục C viết liền: "KHÔNG ẢNH — khối lập luận ngắn").

Mỗi mục điểm nhận theo từ khoá trong ô đầu của dòng bảng; khoá trả về đúng tên đặc tả.

Vị trí cột điểm / tối đa trong bảng điểm, đọc từ hàng tiêu đề (chỉ số tính từ ô sau tên mục).

Một dòng bảng điểm. Ô đầu là tên mục; các ô số đọc theo hàng tiêu đề nếu có.

Đo 30 file nháp thật (04/09/2026): 20 file kẻ bảng | Mục | Tối đa | Chấm | — số đầu là ĐIỂM TỐI ĐA, số sau mới là điểm; 10 file kẻ | Mục | Điểm | và ghi tối đa trong ngoặc ở tên mục (A. Dữ kiện thật (35)). Đọc theo thứ tự số như đặc tả gợi ý ("30 | 35") thì 20 file bị chấm ngược: B = 15/20 thành 20/15 và validator báo "tối đa mục B phải là 20". Hàng tiêu đề nói rõ cột nào là gì — tin nó trước, thứ tự số chỉ là đường lùi.

"QUA (…)" / "đạt" / "pass" / "có" → true; "KHÔNG QUA" / "trượt" / "fail" / "chưa" → false; còn lại null.

Đếm ô [[CẦN …]] trong mọi trường sẽ được trích (thân bài, meta, FAQ, brief, chân trang).

Mọi dòng đã gộp vào giá trị này (kể cả dòng nối tiếp) — số dòng thật trong file.

Kết quả đọc khối nhãn: cặp nhãn/giá trị và những dòng không thuộc nhãn nào.

Đọc khối "nhãn: giá trị". Dòng không mở đầu bằng nhãn đã biết được nối vào giá trị của nhãn trước đó — prompt ảnh và ghi chú biên tập đều dài hơn một dòng. Dòng đứng trước mọi nhãn trả về trong để bên gọi quyết định: brief/ảnh thì cảnh báo, chân trang thì đọc tiếp theo luật riêng (ô hồ sơ tác giả và link trần đứng một mình là đúng mẫu).

Dòng mở đầu bằng gạch đầu dòng / số thứ tự và không thụt lề.

Hàng bảng Markdown | Nhãn | Giá trị | → "Nhãn: Giá trị". Không phải hàng bảng thì trả nguyên dòng; hàng tiêu đề ("Hạng mục"/"Nội dung") và hàng gạch | --- | trả null để bỏ qua.

Rút các đường dẫn nội bộ /… và mã đề W2-01 khỏi một giá trị brief đầy chữ.

Đo 30 file nháp thật (04/09/2026): link trang trụ và link ngang hiếm khi đứng trần. Chúng nằm trong dấu backtick, kèm ghi chú trong ngoặc, và với bài mà trang trụ **chưa đăng** thì người viết ghi "bài W1-01 — trang trụ …" — tức tham chiếu mã đề, không có URL nào cả. Tách theo dấu phẩy rồi lấy từ đầu tiên là ra chữ "bài".

Cảnh báo cho mọi dòng lạc — dùng ở brief, đầu phần (b) và trong khối ảnh.

Tách danh sách: xuống dòng, dấu phẩy hoặc "·" — link và từ khoá đều viết kiểu này.

Dòng đầu tiên của một giá trị nhiều dòng — cho các trường vốn chỉ có một dòng.

Từ đầu tiên (đến khoảng trắng) — dùng cho mã khuôn, làn, slug H2, link trang trụ.

Slug suy từ tiêu đề khi file không ghi — trùng thì import báo và gợi ý, không tự đổi. NormalizeUrl đổi mọi cụm ký tự lạ thành "-" nhưng không cắt dấu gạch ở hai đầu, mà slug có gạch đầu/cuối thì trượt regex của CreateDraft — cắt ở đây cho gọn.

Tra loại trang từ chữ người viết gõ ở dòng 1.

Đo trên 30 file nháp thật (04/09/2026): tên loại trang gần như không bao giờ đứng trần. Nó luôn kéo theo một cái đuôi giải thích — "blog how-to (dạng giải đáp)", "trang trụ (pillar) — cụm C2 Hàng cồng kềnh", "vệ tinh tuyến (chiều ngược)". Khớp chuỗi tuyệt đối bắt 9/30 file; cắt đuôi rồi khớp tiền tố bắt hết. Cái đuôi là ghi chú cho người đọc, không phải một phần của tên loại — bắt người viết bỏ nó đi thì họ sẽ quên, và một file hỏng vì dấu ngoặc là kiểu lỗi làm người ta bỏ luôn công cụ.

Khoá là dạng đã bỏ khoảng trắng/gạch () để so Contains.

Tiện ích đọc văn bản Markdown của file bài nháp: gỡ ký hiệu Markdown quanh nhãn, tách cặp Nhãn: giá trị, và tra tên tiếng Việt trong file về enum. Tách riêng khỏi vì cả parser lẫn test ma trận ánh xạ tên loại trang đều dùng; và vì tra enum theo [Description] là luật chung, không phải chi tiết của một file.

Ký hiệu mở đầu dòng cần gỡ trước khi đọc nhãn: gạch đầu dòng, số thứ tự, dấu thăng tiêu đề.

Nhấn mạnh Markdown quanh nhãn: **Nhãn:**, __Nhãn__, *Nhãn*.

Nhãn được phép có phần đầu dài (xem ).

Dòng tiêu đề Markdown — nhóm 1 là dấu thăng, nhóm 2 là nội dung.

Tiền tố H1: / H2: trong tiêu đề của file nháp — quy ước viết, không phải cấp thật.

Kích thước ảnh: 1200×800, 1200x800, 1200 X 800.

Gỡ gạch đầu dòng / dấu thăng / số thứ tự rồi gỡ nhấn mạnh; giữ nguyên dấu tiếng Việt.

Tách - **Nhãn (ghi chú):** giá trị thành nhãn, phần trong ngoặc và giá trị. Dấu hai chấm của URL (https://) và của khung giờ (08:00) không tính là dấu tách: chỉ nhận dấu hai chấm đầu tiên nằm trong 60 ký tự đầu và không dính ngay ký tự / hoặc chữ số.

Khoá tra nhãn: bỏ dấu, thường, gộp khoảng trắng (dùng chung ).

Khoá tra tên công cụ / mã: bỏ luôn khoảng trắng, gạch, gạch dưới — "GPT Image 2" = "gpt_image_2".

Số nguyên đầu tiên trong chuỗi; null nếu không có.

Bảng tra tên → giá trị enum: nhận [Description] tiếng Việt ("Trang loại hàng"), tên C# ("GoodsPage") và tên snake_case của đặc tả ("goods_page"). Nhãn trong file so bằng .

GoodsPage → goods_page; BlogB2b → blog_b2b (tên snake_case đặc tả dùng).

Một tiêu đề trong thân bài Markdown.

1 = H1, 2 = H2…

Văn bản tiêu đề đã bỏ ký hiệu Markdown inline (giữ nguyên ô [[…]] nếu có).

Slug sinh bằng StringHelper.NormalizeUrl — dùng chung cho PositionKey h2:<slug> và ContentImage.H2Key.

Dòng (1-based) trong Markdown.

Vị trí ký tự bắt đầu dòng tiêu đề trong chuỗi gốc.

Markdown → HTML bằng Markdig. Ba lớp phòng thủ ở tầng render: DisableHtml (HTML thô thành văn bản đã escape), danh sách extension tường minh (KHÔNG có GenericAttributes — thứ cho tác giả gắn onerror/onclick/style qua {name=value} — cũng không có MediaLinks/Diagrams/CustomContainers sinh iframe/div), và gắn vào HtmlRenderer.LinkRewriter để href/src chỉ còn scheme an toàn. Đây KHÔNG phải sanitizer đầu ra: GĐ F phải thêm sanitizer allowlist (thẻ + thuộc tính) trước khi ghi Post.Description, vì HTML này rồi sẽ ra trang công khai. Là nguồn duy nhất sinh slug H2 để PositionKey và H2Key khớp nhau.

Render Markdown thành HTML.

Danh sách tiêu đề theo thứ tự xuất hiện (mọi cấp); lọc Level == 2 để lấy H2.

Chỉ H2 — tiện cho ImageSpecValidator.

Slug của một tiêu đề = StringHelper.NormalizeUrl(text đã bỏ ký hiệu Markdown và bỏ ô [[…]]).

Đếm từ thân bài: bỏ ký hiệu Markdown và ô [[…]], tách theo khoảng trắng, đếm token có chữ/số.

Cài đặt bằng Markdig. Pipeline dựng một lần (bất biến, dùng chung giữa các luồng). Tiêu đề và đếm từ tự quét theo dòng thay vì qua AST của Markdig — để giữ được số dòng và vị trí ký tự trong chuỗi gốc, thứ mà PositionKey của ô dữ liệu và thông báo lỗi cần tới.

Danh sách extension tường minh thay cho UseAdvancedExtensions — cái sau bật cả GenericAttributes ({onerror=…} lên img/a/heading, HtmlRenderer ghi tên thuộc tính nguyên), MediaLinks (iframe), Diagrams, CustomContainers, Mathematics, YAML… DisableHtml chỉ gỡ parser HTML thô, không phải sanitizer, nên phần còn lại phải tự chọn. Thêm extension mới vào đây là mở thêm bề mặt tấn công — cân nhắc kỹ.

Scheme/tiền tố URL được phép đi thẳng ra href/src (so không phân biệt hoa thường).

Ký tự kết thúc phần scheme theo cú pháp URL — có ':' sau một trong số này thì không còn là scheme.

Token thế chỗ ô [[…]] trước khi render — chỉ chữ và số nên không trùng cú pháp Markdown nào.

AutoIdentifier của Markdig sinh id heading từ văn bản đã tokenize (ví dụ id="gia-ldph0ldphend"). Dọn đuôi đó (không phân biệt hoa thường) TRƯỚC khi thay token bằng span, để không bao giờ chèn span vào trong thuộc tính.

Dòng tiêu đề ATX: ≤ 3 khoảng trắng đầu, 1–6 dấu #, khoảng trắng, nội dung, tuỳ chọn dấu # đóng.

Dòng mở/đóng khối code rào (``` hoặc ~~~, ≥ 3 ký tự).

Link / ảnh Markdown: [text](url),  → giữ lại text.

Ký hiệu inline dính vào từ (nhấn mạnh, code, gạch ngang) — bỏ hẳn, không thay bằng khoảng trắng.

Ký hiệu khối / bảng đứng tách từ (#, >, |, -) — thay bằng khoảng trắng.

Số thứ tự danh sách đầu dòng ("1. ", "2) ") — không phải từ.

Lọc scheme cho mọi URL Markdig ghi ra href/src (link, ảnh, autolink <…>, link tự nhận dạng) — gắn vào , được gọi trước khi URL được escape. Bỏ ký tự điều khiển và khoảng trắng trước khi so, vì trình duyệt cũng bỏ chúng khi đọc scheme ("java\tscript:" vẫn chạy). Cho phép http(s), mailto, tel, đường dẫn tuyệt đối/tương đối và neo; mọi scheme khác (javascript:, data:, vbscript:, file:, scheme lạ) trả "#" — giữ link nhưng vô hại. public static để test và để GĐ F (sanitizer allowlist) dùng lại.

Không dùng Markdown.ToHtml vì cần gắn vào LinkRewriter của HtmlRenderer — Markdig không tự lọc scheme URL. Renderer tạo mới mỗi lần (không thread-safe); Pipeline dùng chung.

Bỏ link/ảnh (giữ text) và ký hiệu inline, gộp khoảng trắng. Không đụng tới ô [[…]].

Escape tối thiểu cho text node (& < > "). Không dùng WebUtility.HtmlEncode vì nó đổi chữ Latin-1 (á, é, ô…) thành &#225; — vô hại nhưng làm phần này khác kiểu với HTML Markdig sinh ra quanh nó.

Dòng nằm trong (hoặc là dòng rào của) một khối code rào.

Tách dòng, giữ vị trí ký tự đầu dòng trong chuỗi gốc và đánh dấu dòng thuộc khối code rào.

Ảnh chụp bài đủ để chạy tám điều kiện đăng — dựng từ DB ở service, không dính EF.

Hồ sơ công khai của tác giả — điều kiện (1) đòi không rỗng.

Kết quả chạy lại cổng chặn §3.3b trên bản đã thay ô — điều kiện (6).

Phần của một dòng ảnh mà điều kiện (5) cần biết.

Tám điều kiện chuyển Approved (đặc tả §7.2, plan §3.3d). Trả danh sách thiếu, không chỉ true/false — người duyệt cần biết còn phải làm gì, không phải chỉ biết "chưa được".

Hàm thuần: không DB, không HttpContext — nhận ảnh chụp bài, trả kết quả. Test không cần DB. Phạm vi GĐ D: lớp này mới chỉ được gọi ở đường chỉ đọc GET /api/ContentArticle/PublishCheck/{id} để màn chi tiết hiện danh sách còn thiếu. GĐ E nối chính lớp này vào SetArticleStatus(Approved) — người gọi là ai cũng đi qua đúng một hàm (Nguyên tắc 1.4: không có đường tắt kể cả admin), và bổ sung chỗ sửa PublishWithoutImages/OverrideNote. Đừng nhân bản luật này ở nơi khác.

Ngưỡng điểm tự chấm để đăng mà không cần ghi chú bỏ qua (§3.3d(8)).

Loại trang bắt buộc có người kiểm tra khác tác giả (§3.3d(3)).

Kết quả kiểm phiếu tự chấm: lỗi cứng + trạng thái bị ép (nếu có).

Tổng điểm đã kiểm (= Total khi hợp lệ).

NeedsRewrite khi total < 70 hoặc GatePassed = false; Hold khi Verdict = Hold; null = giữ PendingReview.

Lý do ép trạng thái — ghi vào ContentArticle.StatusReason.

Kiểm phiếu tự chấm (đặc tả §4.7, plan §3.3c). Điểm tối đa cố định A_facts 35 · B_operations 20 · C_structure 15 · D_conversion 15 · E_seo 10 · F_language 5. Lỗi cứng (Code = SCORE_INCONSISTENT): thiếu mục, max sai, score < 0 hoặc > max, Total ≠ Σ score, thiếu GatePassed/Verdict/Total, ReviewerTodos ≠ 3. Không lỗi thì tính ForcedStatus: GatePassed = false hoặc Total < 70 → NeedsRewrite (ưu tiên); Verdict = Hold → Hold.

Hằng điểm tối đa từng mục — một nơi duy nhất.

Ngưỡng ép NeedsRewrite.

Ngưỡng điều kiện đăng §3.3d(8) — dùng ở GĐ E.

Cài đặt — luật thuần trên DTO, không chạm DB. Mọi lỗi cứng dùng chung Code = SCORE_INCONSISTENT và phân biệt bằng Rule; Field theo tên PascalCase của DTO (SelfScore.Sections.A_facts.Score…) để trợ lý AI sửa đúng chỗ. Khoá mục so khớp nguyên văn ("A_facts", không bỏ qua hoa thường) vì khoá là dữ liệu hợp đồng với trợ lý, không phải tên thuộc tính.

Đoán tuyến "tỉnh đi → tỉnh đến" từ tên một trang dịch vụ, dùng chung cho kho nội dung AI (, list_service_pages) và form Dịch vụ của CMS (ProductService.RouteCityOptions) — một bộ luật, hai nơi dùng, không trôi dạt.

Hàm thuần: nơi gọi tự nạp tên tỉnh từ bảng Location rồi đưa vào đây, nên luật test được không cần DB.

Nguồn tên để dò: tên tỉnh Level 1 của cả hai bộ (34 tỉnh sau sáp nhập + 63 tỉnh cũ) — tiêu đề trang dịch vụ phần lớn viết trước sáp nhập. Một truy vấn cho mọi nơi đoán tuyến; xoá mềm do IRepository.Query() lọc.

Tên tỉnh ngắn hơn ngần này không đem đi dò trong tiêu đề (tránh khớp bừa).

Tiền tố hành chính đứng đầu tên tỉnh, ở dạng đã chuẩn hoá (). Bộ 2 cấp ghi tên kèm tiền tố ("Thành phố Hà Nội", "Tỉnh Quảng Ninh") còn bộ 3 cấp để tiền tố ở cột riêng ("Hà Nội") — so tên hai bộ phải bỏ tiền tố ở cả hai vế. Dạng có dấu chấm đứng trước dạng không chấm.

Chuẩn bị danh sách tỉnh để dò: bỏ tên rỗng/quá ngắn, kèm khoá chuẩn hoá, tên dài xếp trước — "Bà Rịa - Vũng Tàu" phải thắng "Vũng Tàu" khi cả hai cùng khớp.

Hai tỉnh xuất hiện đầu tiên trong tên trang, theo thứ tự xuất hiện: "Xe tải ghép Hà Nội - Thanh Hóa" → (Hà Nội, Thanh Hóa). Không đủ hai tỉnh thì trả (null, null) — thà bỏ trống còn hơn đoán sai tuyến.

Tên trang dịch vụ. Kết quả của (tên dài trước).

Map một tên tỉnh đoán được (có thể thuộc bộ 3 cấp cũ) sang Id tỉnh bộ 2 cấp cùng tên, so khoá chuẩn hoá sau khi bỏ tiền tố hành chính đứng đầu ở cả hai vế. Không khớp — tỉnh cũ đã sáp nhập như "Hải Dương" — hoặc khớp hơn một tỉnh thì trả null: gợi ý sai tệ hơn không gợi ý.

Khoá chuẩn hoá đã bỏ một tiền tố hành chính đứng đầu ("Thành phố", "Tỉnh", "TP", "TP.").

Vị trí của khi nó đứng trọn từ (hai đầu không dính chữ/số); -1 nếu không có.

Interface cho CallLog Service

Tìm kiếm call log

Tham số tìm kiếm Kết quả tìm kiếm

Lấy call log theo ID

ID của call log Thông tin call log

Tạo/cập nhật call log

Thông tin call log Kết quả của thao tác

Tạo call log mới

Thông tin call log Kết quả của thao tác

Cập nhật call log

Thông tin call log Kết quả của thao tác

Xóa call log

ID của call log Kết quả của thao tác

CallLog Service Implementation

Tìm kiếm call log với phân trang

Lấy call log theo ID

Tạo hoặc cập nhật call log

Tạo call log mới

Cập nhật call log

Xóa call log (soft delete)

Trạng thái hoạt động của khách hàng theo sale phụ trách (plan §7.4).

Hai đường đọc dùng **chung một stored procedure**: chỉ số KPI sales.active-customers và danh sách khách không hoạt động mà người quản lý xem để nhắc sale chăm sóc. Cố ý không tách hai query — con số trên thẻ KPI và số dòng trong danh sách phải luôn khớp, hai query riêng sẽ trôi khỏi nhau ngay lần sửa đầu tiên.

Đọc thô theo danh sách sale — **không kiểm quyền**, chỉ dùng cho provider KPI đã được lớp trên ép phạm vi.

Thời điểm chốt; cửa sổ hoạt động là 3 tháng lùi từ mốc này Giới hạn ở các sale này; rỗng/null = mọi sale true = chỉ khách hoạt động, false = chỉ khách không hoạt động, null = cả hai

Danh sách khách **không hoạt động**, đã ép phạm vi theo quyền của người đang đăng nhập.

Hai tầng quyền: Kpi.ViewAll quyết định xem được KPI của ai, còn Customer.Search (hoặc Founder) mới quyết định đọc được **danh bạ khách hàng** ngoài đội của mình. Thiếu vế thứ hai thì kết quả luôn bị bó về cấp dưới trực tiếp, dù có Kpi.ViewAll. Thời điểm chốt; bỏ trống lấy hiện tại Lọc thêm về một sale; chỉ thu hẹp kết quả, không mở thêm quyền Người đang đăng nhập

Phân giải phạm vi được phép đọc, **chưa** chạm dữ liệu.

Tách riêng để luật phân quyền kiểm được bằng test đơn vị, không phải dựng cả SQL Server. Đây là luật đã có một lỗ hổng bị bắt ở review GĐ C nên nó xứng đáng có test ghim.

Phạm vi sale được phép đọc của một lần gọi.

Có được đọc gì không; false thì trả danh sách rỗng, không chạm DB

Giới hạn ở các sale này; null nghĩa là **mọi sale** — chỉ hợp lệ khi và người gọi đã qua được cửa quyền CRM.

Role CRM quyết định được xem danh bạ khách hàng ngoài phạm vi đội của mình

Có được đọc danh bạ khách hàng hay không — Founder hoặc role CRM Customer.Search.

Đây là điều kiện CẦN cho mọi nhánh, không phải chỉ cho nhánh "xem tất cả": endpoint này trả tên và số điện thoại khách hàng, đúng thứ mà /api/Customer/Search gác bằng role Customer.Search. Thiếu chốt này thì một tài khoản chỉ có role KPI vẫn đọc được danh bạ của cấp dưới mình, tức role KPI tự nó mở được dữ liệu miền CRM.

Giao diện cho dịch vụ quản lý địa chỉ khách hàng.

Tìm kiếm địa chỉ khách hàng.

Thông số tìm kiếm. Kết quả tìm kiếm địa chỉ khách hàng.

Gợi ý địa chỉ khách hàng.

Từ khóa tìm kiếm. Id của khách hàng. Loại địa chỉ. Danh sách địa chỉ khách hàng gợi ý.

Tạo hoặc cập nhật địa chỉ khách hàng.

Thông tin địa chỉ khách hàng. Kết quả của thao tác.

Lấy thông tin địa chỉ khách hàng theo Id.

Id của địa chỉ khách hàng. Thông tin địa chỉ khách hàng.

Xóa địa chỉ khách hàng.

Id của địa chỉ khách hàng. Thông tin người dùng hiện tại. Kết quả của thao tác.

Cập nhật địa chỉ khách hàng.

Id của địa chỉ khách hàng. Thông tin địa chỉ khách hàng. Kết quả của thao tác.

Cập nhật riêng định vị (Lat/Long) của một địa chỉ khách hàng.

Toạ độ cần ghi; để null cả hai nghĩa là xoá định vị. Thông tin người dùng hiện tại. Kết quả của thao tác.

Triển khai dịch vụ quản lý địa chỉ khách hàng.

Khởi tạo một thể hiện của .

Đối tượng IRepository của CustomerAddress. Đối tượng IRepository của Location. Đối tượng ILocationService.

Tìm kiếm địa chỉ khách hàng.

Thông số tìm kiếm. Kết quả tìm kiếm địa chỉ khách hàng.

Gợi ý địa chỉ khách hàng.

Từ khóa tìm kiếm. Id của khách hàng. Loại địa chỉ. Danh sách địa chỉ khách hàng gợi ý.

Tạo hoặc cập nhật địa chỉ khách hàng.

Thông tin địa chỉ khách hàng. Kết quả của thao tác.

Cập nhật địa chỉ khách hàng.

Thông tin địa chỉ khách hàng. Kết quả của thao tác.

Thêm mới địa chỉ khách hàng.

Thông tin địa chỉ khách hàng. Kết quả của thao tác.

Lấy thông tin địa chỉ khách hàng theo Id.

Id của địa chỉ khách hàng. Thông tin địa chỉ khách hàng.

Xóa địa chỉ khách hàng.

Id của địa chỉ khách hàng. Thông tin người dùng hiện tại. Kết quả của thao tác.

Cập nhật địa chỉ khách hàng.

Id của địa chỉ khách hàng. Thông tin địa chỉ khách hàng. Kết quả của thao tác.

Cập nhật riêng định vị (Lat/Long) của một địa chỉ khách hàng.

Toạ độ cần ghi; để null cả hai nghĩa là xoá định vị. Thông tin người dùng hiện tại. Kết quả của thao tác.

Giao diện cho dịch vụ quản lý tài khoản ngân hàng khách hàng.

Lấy danh sách tài khoản ngân hàng của khách hàng.

ID khách hàng. Danh sách tài khoản ngân hàng.

Lấy tài khoản ngân hàng mặc định của khách hàng.

ID khách hàng. Tài khoản ngân hàng mặc định.

Lấy thông tin tài khoản ngân hàng theo ID.

ID tài khoản. Thông tin tài khoản ngân hàng.

Tạo hoặc cập nhật tài khoản ngân hàng.

Thông tin tài khoản ngân hàng. Kết quả của thao tác.

Xóa tài khoản ngân hàng.

ID tài khoản. Thông tin người dùng hiện tại. Kết quả của thao tác.

Đặt tài khoản làm mặc định.

ID tài khoản. Thông tin người dùng hiện tại. Kết quả của thao tác.

Tìm kiếm tài khoản ngân hàng.

Từ khóa tìm kiếm. ID khách hàng (tùy chọn). Mã ngân hàng (tùy chọn). Danh sách tài khoản ngân hàng.

Tìm kiếm tài khoản ngân hàng với SmartTable.

Tham số SmartTable. Kết quả tìm kiếm dưới dạng SmartTableResult.

Gợi ý tài khoản ngân hàng cho khách hàng.

ID khách hàng. Từ khóa tìm kiếm. Danh sách gợi ý.

Dịch vụ quản lý tài khoản ngân hàng khách hàng.

Khởi tạo dịch vụ quản lý tài khoản ngân hàng khách hàng.

Repository tài khoản ngân hàng. Repository khách hàng.

Lấy danh sách tài khoản ngân hàng của khách hàng.

ID khách hàng. Danh sách tài khoản ngân hàng.

Lấy tài khoản ngân hàng mặc định của khách hàng.

ID khách hàng. Tài khoản ngân hàng mặc định.

Lấy thông tin tài khoản ngân hàng theo ID.

ID tài khoản. Thông tin tài khoản ngân hàng.

Tạo hoặc cập nhật tài khoản ngân hàng.

Thông tin tài khoản ngân hàng. Kết quả của thao tác.

Xóa tài khoản ngân hàng.

ID tài khoản. Thông tin người dùng hiện tại. Kết quả của thao tác.

Đặt tài khoản làm mặc định.

ID tài khoản. Thông tin người dùng hiện tại. Kết quả của thao tác.

Tìm kiếm tài khoản ngân hàng.

Từ khóa tìm kiếm. ID khách hàng (tùy chọn). Mã ngân hàng (tùy chọn). Danh sách tài khoản ngân hàng.

Tìm kiếm tài khoản ngân hàng với SmartTable.

Tham số SmartTable. Kết quả tìm kiếm dưới dạng SmartTableResult.

Gợi ý tài khoản ngân hàng cho khách hàng.

ID khách hàng. Từ khóa tìm kiếm. Danh sách gợi ý.

Tạo tài khoản ngân hàng mới.

Thông tin tài khoản ngân hàng. Kết quả của thao tác.

Cập nhật tài khoản ngân hàng.

Thông tin tài khoản ngân hàng. Kết quả của thao tác.

Dịch vụ xử lý ticket khiếu nại và yêu cầu đổi nhân viên phụ trách phía nhân viên (ticket do khách tạo từ app qua Lada.AppBackEnd).

Tìm kiếm khiếu nại của khách hàng.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Lấy chi tiết khiếu nại kèm ảnh đính kèm.

Id khiếu nại. Chi tiết khiếu nại, null nếu không tồn tại.

Tiếp nhận khiếu nại (Draft → Processing).

Thông tin thao tác. Kết quả của thao tác.

Phản hồi khiếu nại cho khách (khách xem qua api/complaints). Khiếu nại đang Draft sẽ tự chuyển sang Processing.

Thông tin phản hồi. Kết quả của thao tác.

Đóng khiếu nại (Processing → Resolved). Yêu cầu đã có phản hồi cho khách.

Thông tin thao tác (StaffResponse truyền kèm sẽ cập nhật phản hồi). Kết quả của thao tác.

Tìm kiếm yêu cầu đổi nhân viên phụ trách.

Các tham số tìm kiếm. Kết quả tìm kiếm.

Duyệt yêu cầu đổi nhân viên: gán nhân viên mới cho khách qua luồng AssignManager sẵn có.

Thông tin duyệt (NewManagerId bắt buộc). Kết quả của thao tác.

Từ chối yêu cầu đổi nhân viên (ProcessedNote bắt buộc để khách biết lý do).

Thông tin từ chối. Kết quả của thao tác.

Giao diện cho dịch vụ quản lý khách hàng.

Tìm kiếm khách hàng.

Thông số tìm kiếm. Kết quả tìm kiếm khách hàng.

Gợi ý danh sách sale quản lý mà người dùng được phép lọc theo. Founder thấy toàn bộ nhân viên; người dùng thường chỉ thấy bản thân và cấp dưới trực tiếp.

Từ khóa tìm kiếm. Id người dùng đang đăng nhập. Danh sách nhân viên gợi ý.

Gợi ý danh sách khách hàng trong phạm vi người dùng được phép xem.

Từ khóa tìm kiếm. Id người dùng đang đăng nhập. Danh sách khách hàng gợi ý.

Tạo hoặc cập nhật khách hàng.

Thông tin khách hàng. Kết quả của thao tác.

Lấy thông tin khách hàng theo Id.

Id của khách hàng. Thông tin khách hàng.

Xóa khách hàng.

Id của khách hàng. Thông tin người dùng hiện tại. Kết quả của thao tác.

Khóa khách hàng.

Id của khách hàng. Thông tin người dùng hiện tại. Kết quả của thao tác.

Mở khóa khách hàng.

Id của khách hàng. Thông tin người dùng hiện tại. Kết quả của thao tác.

Đặt lại mật khẩu cho tài khoản đăng nhập của khách hàng.

Thông tin đặt lại mật khẩu (Id khách hàng + mật khẩu mới). Thông tin người dùng hiện tại. Kết quả của thao tác, kèm ErrorList khi mật khẩu không đạt chính sách.

Tạo tài khoản đăng nhập cho một khách hàng đã có hồ sơ.

Id khách hàng, tên đăng nhập và mật khẩu. Thông tin người dùng hiện tại. Kết quả của thao tác, kèm ErrorList khi Identity từ chối.

Gán người quản lý cho khách hàng.

Thông tin người quản lý. Kết quả của thao tác. true khi lần đổi này đến từ yêu cầu của khách (duyệt CustomerManagerChangeRequest): người đang giữ hội thoại chat của khách mất luôn quyền xem (§6.2). false cho lần gán hành chính bình thường. Là THAM SỐ chứ không phải một trường trên , và đó là một bản vá bảo mật chứ không phải sở thích: model đi qua model binding, nên một trường ở đó là một trường client đặt được. Cắt quyền xem là hình phạt — nó phải do đường gọi quyết định, không do thân request.

Gán người quản lý hàng loạt cho nhiều khách hàng.

Thông tin gán hàng loạt. Kết quả của thao tác.

Lấy thông tin người quản lý theo Id khách hàng.

Id của khách hàng. Thông tin người quản lý.

Cập nhật thuộc tính của khách hàng.

Thông tin thuộc tính của khách hàng. Kết quả của thao tác.

Lấy thông tin thuộc tính của khách hàng.

Id của khách hàng. Loại thuộc tính. Thông tin thuộc tính của khách hàng.

Cập nhật trạng thái khách hàng.

Id của khách hàng. Trạng thái khách hàng. Kết quả của thao tác.

Xuất danh sách khách hàng ra file Excel.

Thông số tìm kiếm (dùng chung filter với Search). Id người thực hiện. Kết quả xuất Excel.

Lấy danh sách đồng quản lý của khách hàng.

Thêm đồng quản lý cho khách hàng (tự động bỏ qua nếu đã tồn tại).

Xóa đồng quản lý khỏi khách hàng.

Triển khai dịch vụ quản lý khách hàng.

Khởi tạo một thể hiện của .

Tìm kiếm khách hàng.

Thông số tìm kiếm. Kết quả tìm kiếm khách hàng.

Tìm kiếm khách hàng.

Thông số tìm kiếm. Kết quả tìm kiếm khách hàng.

Lấy danh sách Id sale mà người dùng được phép xem khách hàng: bản thân + cấp dưới trực tiếp.

Id người dùng đang đăng nhập. Danh sách Id sale trong phạm vi.

Gợi ý danh sách sale quản lý mà người dùng được phép lọc theo.

Từ khóa tìm kiếm. Id người dùng đang đăng nhập. Danh sách nhân viên gợi ý.

Gợi ý danh sách khách hàng trong phạm vi người dùng được phép xem.

Từ khóa tìm kiếm. Id người dùng đang đăng nhập. Danh sách khách hàng gợi ý.

Kiểm tra từ khóa có phải là một số điện thoại đầy đủ hay không.

Từ khóa tìm kiếm. Số điện thoại đã bỏ các ký tự phân cách. True nếu từ khóa chỉ gồm chữ số cùng ký tự phân cách và có từ 10 chữ số trở lên.

Tạo hoặc cập nhật khách hàng.

Thông tin khách hàng. Kết quả của thao tác.

Cập nhật thuộc tính của khách hàng.

Thông tin thuộc tính của khách hàng. Kết quả của thao tác.

Lấy thông tin thuộc tính của khách hàng.

Id của khách hàng. Loại thuộc tính. Thông tin thuộc tính của khách hàng.

Thêm mới khách hàng.

Thông tin khách hàng. Kết quả của thao tác.

Cập nhật khách hàng.

Thông tin khách hàng. Kết quả của thao tác.

Lấy thông tin khách hàng theo Id.

Id của khách hàng. Thông tin khách hàng.

Xóa khách hàng.

Id của khách hàng. Thông tin người dùng hiện tại. Kết quả của thao tác.

Khóa khách hàng.

Id của khách hàng. Thông tin người dùng hiện tại. Kết quả của thao tác.

Mở khóa khách hàng.

Id của khách hàng. Thông tin người dùng hiện tại. Kết quả của thao tác.

Đặt lại mật khẩu cho tài khoản đăng nhập của khách hàng.

Thông tin đặt lại mật khẩu (Id khách hàng + mật khẩu mới). Thông tin người dùng hiện tại. Kết quả của thao tác, kèm ErrorList khi mật khẩu không đạt chính sách.

Tạo tài khoản đăng nhập cho một khách hàng đã có hồ sơ.

Id khách hàng, tên đăng nhập và mật khẩu. Thông tin người dùng hiện tại. Kết quả của thao tác, kèm ErrorList khi Identity từ chối.

Lấy thông tin người quản lý theo Id khách hàng.

Id của khách hàng. Thông tin người quản lý.

Gán người quản lý cho khách hàng.

Thông tin người quản lý. Kết quả của thao tác.

Gán người quản lý hàng loạt cho nhiều khách hàng.

Thông tin gán hàng loạt. Kết quả của thao tác.

Cập nhật trạng thái khách hàng.

Id của khách hàng. Trạng thái khách hàng. Kết quả của thao tác.

Lấy danh sách đồng quản lý của khách hàng.

Thêm đồng quản lý cho khách hàng. Tự động bỏ qua nếu đã tồn tại hoặc nếu user là ManagerId chính.

Xóa đồng quản lý khỏi khách hàng (soft delete).

Tìm kiếm lead

Các tham số tìm kiếm. Nếu có giá trị, chỉ trả về lead do người này phụ trách hoặc chưa có ai phụ trách. Truyền null để xem toàn bộ lead (dành cho role quản lý).

Tạo/cập nhật đại lý

Tạo lead.

Thông tin lead. Kết quả của thao tác.

Cập nhật trạng thái của Lead

Lấy thông tin đánh giá lead theo ID.

ID của lead. Thông tin đánh giá lead.

Cập nhật trạng thái lead.

Id của lead. Trạng thái lead. Kết quả của thao tác.

Lấy thông tin đánh giá lead theo ID.

ID của lead. Thông tin đánh giá lead.

Interface service quản lý thông tin xuất hóa đơn VAT của khách hàng

Lấy danh sách thông tin xuất hóa đơn VAT theo điều kiện tìm kiếm

Model tìm kiếm Danh sách thông tin xuất hóa đơn VAT

Lấy thông tin chi tiết xuất hóa đơn VAT theo ID

ID thông tin xuất hóa đơn VAT Thông tin chi tiết xuất hóa đơn VAT

Lấy thông tin xuất hóa đơn VAT mặc định của khách hàng

ID khách hàng Thông tin xuất hóa đơn VAT mặc định

Tạo mới hoặc cập nhật thông tin xuất hóa đơn VAT

Model tạo mới hoặc cập nhật Kết quả tạo mới hoặc cập nhật

Xóa thông tin xuất hóa đơn VAT

ID thông tin xuất hóa đơn VAT Kết quả xóa

Đặt thông tin xuất hóa đơn VAT làm mặc định

ID thông tin xuất hóa đơn VAT Kết quả cập nhật

Service quản lý thông tin xuất hóa đơn VAT của khách hàng

Cập nhật thông tin xuất hóa đơn VAT

Model cập nhật Kết quả cập nhật

Tạo mới thông tin xuất hóa đơn VAT

Model tạo mới Kết quả tạo mới

Thư viện widget user hiện tại được dùng (server lọc theo nhóm quyền, Founder thấy tất cả)

Bố cục dashboard của user; lần đầu chưa có thì tự tạo bố cục mặc định

Lưu toàn bộ bố cục — zone/widget vắng mặt trong model bị xoá mềm (last-write-wins)

Dispatcher trung tâm: kiểm tra quyền → gọi provider theo Code → cache TTL ngắn

Chỉ giữ các khoá được khai báo trong SettingsSchema với UserEditable != false — đây là chốt server-side cho việc admin khoá tuỳ chọn.

Hợp đồng cắm một widget vào dashboard: mỗi widget = một provider trả data đúng envelope theo Type. Đăng ký DI bằng services.AddTransient<IWidgetDataProvider, XxxProvider>() — dispatcher resolve theo Code. Provider KHÔNG tự kiểm tra quyền và KHÔNG tự cache — dispatcher đã làm cả hai.

Trùng DashboardWidget.Code trong catalog

Trả object data đúng envelope theo Type của widget: kpi → { Value, Unit, Delta, DeltaPercent, CompareLabel, Series } chart → { ChartKind, Categories, Series[{ Name, Data }] } list → { Columns[{ Key, Label, Format }], Rows, TotalCount, MoreUrl } progress → { Value, Target, Percent, Label }

Ngữ cảnh gọi provider — Settings đã merge DefaultSettings + cài đặt user, quyền đã được dispatcher kiểm tra

Đọc settings JSON đã merge, getter có kiểu kèm fallback

Merge DefaultSettings của catalog với Settings riêng của user (user đè default, JSON hỏng thì bỏ qua phần đó)

Provider demo để nghiệm thu khung — trả KPI ngẫu nhiên theo khoảng thời gian đã chọn. Xoá cùng widget 'demo.random-kpi' (qua trang quản trị) khi đã có widget thật.

Widget danh sách "Năng suất lái xe" (vai trò Điều phối) — tái dùng sp_GetDriverProductivityReportByDate qua IDriverReportService. Chú ý: service này đọc khoá FromDate/ToDate (khác StartDate/EndDate của các report khác).

Widget biểu đồ "Chi phí nhiên liệu theo ngày" (vai trò Tài chính) — tái dùng sp_GetFuelRefillReportByDate qua IFuelRefillReportService (mặc định chỉ tính phiếu Approved).

Widget danh sách "Bảng tin mới" (plan bảng tin §3.17, GĐ D): mấy bài đầu bảng tin của chính người xem, kèm chấm chưa đọc và số bài chưa đọc.

Không có truy vấn riêng: gọi lại và — cùng luật đối tượng + phạm vi LADA / nhượng quyền, cùng thứ tự (ghim còn hạn trước, rồi mới đăng) với trang /bang-tin, nên widget không bao giờ lộ bài ngoài đối tượng. Ai thấy widget là việc của catalog (DashboardWidgetPermission — migration seed mở cho mọi nhóm quyền), provider không kiểm quyền lại. Dispatcher đệm dữ liệu 60 giây — đọc bài xong quay lại trang chủ có thể còn chấm.

Mã widget, trùng DashboardWidget.Code trong migration seed

Trang Bảng tin — nơi "Xem tất cả" trỏ tới; từng bài là /bang-tin/{Id}

Widget "KPI của tôi" (plan §3.7 mục 5): chỉ tiêu của chính người đang xem trong một kỳ tháng, kèm điểm tổng và danh sách từng chỉ tiêu.

Không có truy vấn riêng. Tái dùng — cùng engine với màn "Theo dõi KPI trong kỳ", nên số trên widget luôn khớp số của màn đó. Kèm theo đó là hai tính chất quan trọng được thừa hưởng miễn phí: kỳ ĐÃ CHỐT đọc thẳng snapshot KpiResult (nợ KPI-8), và một chỉ số lỗi nguồn không làm hỏng cả widget. Phạm vi ép ở máy chủ. Chủ thể luôn là context.UserId — không nhận từ settings của client — và vẫn tự áp IKpiVisibilityResolver lên trên. Xem KPI của chính mình thì ai cũng được, nên widget này không cần thêm lớp gác nào. "Chưa có số" KHÔNG BAO GIỜ thành 0 (plan §3.9d). Hai chỗ dễ tặc lưỡi nhất, cùng nằm ở đây: (a) chưa được giao chỉ tiêu nào ⇒ Value = null chứ không phải 0 điểm; (b) mọi chỉ tiêu đều chưa có số ⇒ điểm cũng null, vì lúc đó tổng điểm 0 chỉ phản ánh việc chưa ai nhập số. Còn thiếu một phần thì điểm là tạm tính (IsProvisional) — widget phải nói rõ, không được trưng ra như điểm cuối cùng.

Số chỉ tiêu hiển thị mặc định — diện tích widget hẹp, phần còn lại xem ở màn theo dõi

Màn theo dõi trong kỳ — nơi xem đầy đủ, khớp routers/kpi.js

Envelope khi người xem không có quyền đọc KPI — nói thẳng lý do thay vì trưng ô rỗng.

Ô rỗng ở đây sẽ bị đọc nhầm thành "tháng này chưa được giao chỉ tiêu", mà hai chuyện đó khác hẳn nhau — cùng họ với luật "chưa có số không phải 0" của chính widget này.

Xếp chỉ tiêu "cần chú ý" lên trước: chưa có số, rồi % hoàn thành thấp nhất.

Widget cắt bớt dòng nên thứ tự quyết định cái gì bị giấu. Xếp theo mã chỉ số như màn theo dõi thì đúng chỗ cần biết lại rơi xuống dưới lằn cắt — người ta mở dashboard chính là để thấy chỗ đang có vấn đề.

Widget "KPI đội của tôi" (plan §3.7 mục 5): tiến độ KPI của những chủ thể mà người xem được phép xem — cấp dưới trực tiếp và đơn vị mình quản lý — trong một kỳ tháng.

Phạm vi hoàn toàn do máy chủ quyết. Provider gọi KHÔNG truyền chủ thể, để chính IKpiVisibilityResolver (§3.6) quyết định tập trả về: cấp dưới trực tiếp theo UserPreference.ManagerId + đơn vị mình quản lý và đơn vị con của chúng; người có Kpi.ViewAll thì cả công ty. Widget không tự lọc theo AgencyId và không nhận chủ thể nào từ settings của client. Bỏ chính mình ra khỏi "đội". Tập xem được luôn gồm bản thân người xem; phần đó đã có widget kpi.my-progress lo. Quản lý không có cấp dưới nào sẽ thấy widget rỗng — đúng, chứ không phải hỏng. "Chưa có số" không thành 0 (plan §3.9d): chủ thể mà mọi chỉ tiêu đều chưa có số thì TotalScore = null ⇒ renderer hiện "—". Trưng 0 điểm cho một người chỉ vì stored procedure chưa trả số là biến trục trặc kỹ thuật thành kết luận về con người. Chủ thể còn thiếu một phần thì điểm là tạm tính, cột "chưa có số" nói rõ còn mấy dòng.

Xếp chủ thể cần chú ý lên trước (mặc định)

Xếp điểm cao lên trước

Envelope khi người xem không có quyền đọc KPI — nói thẳng thay vì trưng bảng rỗng, vì bảng rỗng ở đây đọc nhầm thành "bạn không quản lý ai".

Một dòng của widget — kiểu tường minh để sắp xếp được, thay cho object ẩn danh

Phần dùng chung của hai widget KPI: chọn kỳ theo tuỳ chọn người dùng và đặt nhãn kỳ.

Tách ra để hai provider không mỗi nơi một cách suy kỳ. Kỳ KPI là kỳ theo giờ Việt Nam (plan §8) nên mọi đường đều đi qua , không đọc thẳng DateTimeOffset.Now.Month.

Khoá tuỳ chọn chọn kỳ, dùng chung cho cả hai widget

Kỳ đang chạy

Kỳ tháng liền trước

Suy kỳ từ tuỳ chọn. Giá trị lạ quy về kỳ hiện tại thay vì ném lỗi — widget hỏng vì một chuỗi settings cũ là mất cả ô trên dashboard.

Nhãn kỳ hiển thị cho người dùng, ví dụ "tháng 8/2026"

Provider cho widget "Tra cứu cước phí" (pricing.fee-lookup) — chỉ trả danh mục loại hàng để dựng form, KHÔNG tính tiền.

Khác mọi provider còn lại: widget này là công cụ tương tác, mỗi lượt tra là một input mới của người dùng chứ không phải một lần làm mới theo settings — nên tiền do chính component gọi POST api/Price/CheckFee, cùng endpoint trang /tra-cuu-cuoc-phi dùng, để hai nơi không bao giờ lệch con số. Việc trả sẵn danh mục ở đây có mục đích: component khỏi gọi Category/GetTree, tức là widget không kéo thêm role Category.GetTree vào tập quyền cần có để dùng được.

Khởi tạo provider.

Service danh mục, dùng để lấy cây loại hàng vận chuyển.

Widget KPI "Doanh số cá nhân" (vai trò Kinh doanh) — tái dùng sp_GetOrderRevenueStatisticsBySale qua ISaleReportService, rồi tự lọc lấy đúng dòng của người đang xem.

Từ 2026-09-07 báo cáo trả doanh số của cả nhân sự trong phạm vi quản lý (bản thân + cấp dưới + nhân sự chi nhánh mình quản lý), nên widget này KHÔNG được cộng thẳng mọi dòng trả về — với một quản lý thì "cá nhân" sẽ hoá thành doanh số cả đội.

Widget "Đồng bộ tìm kiếm" trên trang chủ — ba con số trả lời câu hỏi thường trực của người làm nội dung: Google đã index bao nhiêu trang, còn bao nhiêu chưa, và bao nhiêu trang vừa sửa mà Google chưa đọc lại.

Vì sao envelope là list chứ không phải kpi. Kế hoạch ban đầu xếp widget này vào loại kpi, nhưng renderer KpiWidget.vue chỉ hiện được đúng một giá trị Value, trong khi widget cần ba. Ép ba số vào kpi thì phải đăng ký một renderer riêng theo mã widget — đúng thứ kế hoạch cấm ở cùng đoạn, vì nó phá luật "một loại một renderer" của cả khung dashboard. Chọn list giữ được đủ ba số mà vẫn dùng envelope chuẩn, không phải đụng vào registry của frontend. Đếm theo Verdict, không theo CoverageState. Verdict là mã ổn định (PASS / NEUTRAL / FAIL…), còn CoverageState là câu Google viết cho người đọc và đổi theo ngôn ngữ của tài khoản. Nhóm theo câu chữ thì một hôm Google đổi cách diễn đạt là con số trên trang chủ nhảy mà không ai sửa gì — CoverageState chỉ để đọc. Hai dòng đầu chỉ đếm URL đã kiểm. URL chưa từng kiểm không có Verdict nên không rơi vào dòng nào — cố ý, để số "Chưa index" ở đây bằng đúng TotalCount của widget search.not-indexed đứng cạnh nó trên cùng trang chủ; hai widget cạnh nhau mà lệch số là thứ người dùng phát hiện đầu tiên. Số "chưa kiểm" có ô riêng ở màn /dong-bo-tim-kiem. Hệ quả: tổng hai dòng đầu có thể nhỏ hơn TotalCount (tổng URL trong hàng tồn kho). Không tự kiểm quyền và không tự cache — catalog DashboardWidgetPermission đã gác trước khi dispatcher gọi tới đây, và dispatcher cũng là nơi cache (hợp đồng ).

Mã widget, trùng DashboardWidget.Code trong migration seed

Đường dẫn màn "Đồng bộ tìm kiếm" — nơi liên kết "Xem tất cả" trỏ tới

Kết luận "đã index" theo Google. Giữ nguyên chuỗi Google trả thay vì quy về enum vì Google thêm giá trị mới mà không báo trước (xem SearchIndexStatus.Verdict).

Chỉ Google có dữ liệu ở giai đoạn này. Bảng trạng thái vốn trung lập với công cụ tìm kiếm nên thêm Bing/IndexNow về sau chỉ là đổi hằng này (hoặc đọc từ settings), không phải viết lại.

Bề rộng cửa sổ so sánh của cột "7 ngày"

Giá trị hiện khi không biết, khác hẳn với số 0 nghĩa là "biết, và bằng không". Trùng ký tự mà ListWidget.vue dùng cho ô rỗng nên nhìn liền mạch với các cột khác.

Dựng cột một chỗ duy nhất để nhánh "chưa có dữ liệu" và nhánh thường không bao giờ lệch nhau.

Dựng lại số "đã index" / "chưa index" tại thời điểm ngày trước rồi trả về phần chênh lệch dưới dạng chuỗi có dấu.

Chưa đủ lịch sử thì trả , không trả 0. Bảng SearchIndexStatusHistory chỉ ghi khi trạng thái thật sự đổi, nên trên một hệ mới chạy (dev hiện có đúng một ngày dữ liệu) không có dòng nào cũ hơn mốc cắt. Hiện "0" ở đó đọc ra thành "một tuần qua không có gì thay đổi" — một câu khẳng định mà mình không có cơ sở để nói. Dòng "Vừa sửa chưa báo" không có số so sánh. Cờ đó là phép so giữa SearchUrl.SitemapLastmod và SearchIndexStatus.LastCrawlTime, mà bảng lịch sử chỉ giữ mốc thu thập chứ không giữ mốc sitemap. Dựng lại bằng mốc sitemap của hôm nay sẽ cho kết quả sai ở đúng những URL vừa đổi lastmod trong tuần — tức đúng nhóm mà dòng này nói về. Một con số sai ở chỗ nhạy cảm nhất còn tệ hơn không có con số nào.

Chênh lệch có dấu: dấu cộng phải hiện rõ vì "+5 trang được index" và "-5 trang rơi khỏi index" là hai tin trái ngược nhau mà nếu thiếu dấu thì nhìn giống hệt.

Widget "Trang chưa được index" trên trang chủ — vài URL Google chưa index kèm lý do Google đưa ra, để người làm nội dung biết phải mở trang nào trước.

Lỗi máy chủ đứng đầu danh sách. Một URL có PageFetchState = SERVER_ERROR nghĩa là Google vào trang và nhận 5xx — hỏng nặng hơn hẳn "đã thu thập nhưng chưa index", và là loại hỏng duy nhất mà sửa được ngay. Đúng dấu hiệu này đã bắt được sự cố thật ngày 15/09/2026, nên nó được ghim lên đầu thay vì trộn lẫn theo thứ tự bảng chữ cái. Chọn dòng theo Verdict, hiện lý do bằng CoverageState. Verdict là mã ổn định nên lọc được; CoverageState là câu Google viết cho người đọc (bản tiếng Việt: "Đã thu thập dữ liệu…", "Lỗi máy chủ (5xx)"…) nên chỉ dùng để hiển thị, không bao giờ để nhóm hay đếm — Google đổi cách diễn đạt lúc nào cũng được. URL chưa từng kiểm không nằm ở đây. Không có dòng trạng thái thì không có Verdict, và "chưa biết" khác "biết là chưa index". Số đó có ô riêng ở màn /dong-bo-tim-kiem. Không tự kiểm quyền và không tự cache — catalog DashboardWidgetPermission đã gác trước khi dispatcher gọi tới đây, và dispatcher cũng là nơi cache (hợp đồng ).

Mã widget, trùng DashboardWidget.Code trong migration seed

Đường dẫn màn "Đồng bộ tìm kiếm" — nơi liên kết "Xem tất cả" trỏ tới

Kết luận "đã index" theo Google — mọi thứ khác nó là ứng viên của widget này

Google vào được trang nhưng máy chủ trả 5xx — loại hỏng nặng nhất, ghim lên đầu

Chỉ Google có dữ liệu ở giai đoạn này. Bảng trạng thái vốn trung lập với công cụ tìm kiếm nên thêm Bing/IndexNow về sau chỉ là đổi hằng này, không phải viết lại truy vấn.

Widget danh sách "Xe cần bảo dưỡng" (plan bảo dưỡng xe tải §3.5, Q7): những xe trong phạm vi chi nhánh của người xem đang có bộ phận quá hạn hoặc sắp đến hạn, xếp xe nặng nhất lên đầu.

Không có truy vấn riêng: tái dùng — cùng engine realtime với màn "Tình trạng đội xe", nên số trên widget luôn khớp số của màn đó (và cố ý có thể lệch với màn tra cứu cảnh báo do job ghi trong ngày đầu, xem plan §3.3). Phạm vi dữ liệu ép ở đây bằng theo UserId mà dispatcher truyền vào — không nhận chi nhánh từ settings của client. Ai được thấy widget là việc của catalog (DashboardWidgetPermission), provider không kiểm quyền lại (hợp đồng ).

Mã widget, trùng DashboardWidget.Code trong migration seed

Đường dẫn màn "Tình trạng đội xe" — nơi liên kết "Xem tất cả" trỏ tới

Số xe tối đa nạp một lượt để tính. Đội xe hiện 26 chiếc; nếu vượt ngưỡng này thì cờ Truncated trong data bật lên để widget nói rõ là số chưa đủ, thay vì im lặng.

Preset khoảng thời gian chuẩn dùng chung cho mọi widget: today / yesterday / this_week / this_month / this_quarter / this_year / last_7d / last_30d. End là exclusive (nửa khoảng [Start, End)).

Interface for Driver App order service.

Searches for orders based on the provided parameters.

Search parameters. User ID. Search results.

Tìm kiếm đơn hàng đang hoạt động (đang lấy, lấy thất bại, đang giao, giao thất bại).

Tham số tìm kiếm. ID người dùng. Kết quả tìm kiếm.

Gets an order by its ID.

Order ID. User ID. Order item.

Picks up an order.

Pickup model. Order track result.

Pickup failed.

Fail model. Order track result.

Delivery successful.

Delivery model. Order track result.

Delivery failed.

Fail model. Order track result.

Return successful.

Return model. Order track result.

Return failed.

Fail model. Order track result.

Sắp xếp thứ tự hiển thị đơn hàng.

Danh sách đơn hàng với thứ tự mới. ID người dùng. Kết quả sắp xếp.

Implementation of the Driver App order service.

Dùng để ghép ảnh của đơn với sự kiện sinh ra nó (chi tiết đơn trên app nhóm ảnh theo track).

Dùng để tra toạ độ tâm phường/xã cho địa chỉ chưa ghim (bản đồ đơn hàng của app).

Initializes a new instance of the class.

Searches for orders based on the provided parameters.

Search parameters. User ID. Search results.

Tìm kiếm đơn hàng đang hoạt động của tài xế: đang lấy / lấy thất bại, đang giao / giao thất bại, đang trả hàng, và đơn trung chuyển (đã xuất kho, đang trên xe tới bưu cục kế tiếp).

Tham số tìm kiếm. PredicateObject.Group (pickup / delivery / return / transit) thu hẹp về một nhóm; bỏ trống là tất cả. Xem . ID người dùng. Kết quả tìm kiếm.

Ví bưu cục v2 (plan §3.8.2): điền ô "Số tiền đã thu" cho đơn đang đi lấy — máy chủ quyết, app chỉ đọc cờ. Lái xe không thuộc bưu cục nhượng quyền bật ví → không đổi gì.

Gets an order by its ID.

Order ID. User ID. Order item.

Nạp ảnh của nhiều đơn trong một lượt (ba truy vấn cố định, không phải mỗi đơn một lượt), gom theo đơn.

Toàn bộ ảnh của đơn, KHÔNG lọc theo người chụp như Search(lịch sử): lái xe giao cần xem ảnh lúc lấy hàng của người khác, lái xe trung chuyển cần xem ảnh nhập/xuất kho. Id của OrderOps trùng Id của Order (khoá chia sẻ) nên nhận thẳng Id của .

Picks up an order.

Pickup model. Order track result.

Pickup failed.

Fail model. Order track result.

Delivery successful.

Delivery model. Order track result.

Delivery failed.

Fail model. Order track result.

Return successful.

Return model. Order track result.

Return failed.

Fail model. Order track result.

Sắp xếp thứ tự hiển thị đơn hàng.

Danh sách đơn hàng với thứ tự mới. ID người dùng. Kết quả sắp xếp.

Validates the update status of an order.

Current order status. Current physical status. New order status. New physical status. True if the update is valid, otherwise false.

Lấy thông tin chấm công của người dùng

Lấy thông tin xe đang phụ trách

Lấy ODO gần nhất của xe từ các hoạt động (chấm công hoặc bàn giao xe)

ID xe tải ID người dùng ODO gần nhất

Interface cho dịch vụ quản lý tài chính của lái xe

Lấy thông tin tài chính của lái xe

ID của lái xe Thông tin tài chính của lái xe

Tìm kiếm danh sách đơn hàng tài chính của lái xe có phân trang

Tham số tìm kiếm và phân trang ID của lái xe Kết quả tìm kiếm có phân trang

Dịch vụ quản lý tài chính của lái xe

Ví bưu cục v2 (V-40): lái xe bưu cục nhượng quyền bật ví không nộp LADA tiền của đơn Ví ghi — màn "tiền cần nộp" bỏ các đơn đó, cùng luật phiếu chuyển khoản (DriverTransferSlipService). Null khi dựng không có ví (test cũ).

Lấy thông tin tài chính của lái xe

ID của lái xe Thông tin tài chính của lái xe

Tìm kiếm danh sách đơn hàng tài chính của lái xe có phân trang Bao gồm cả đơn hàng mà lái xe đã thu tiền nhưng đã nộp lại

Tham số tìm kiếm và phân trang ID của lái xe Kết quả tìm kiếm có phân trang

Lái xe thuộc bưu cục nhượng quyền đang bật ví (V-05) — null khi không phải hoặc dựng không có ví.

Đơn do Ví ghi với người cầm tiền này — cùng mốc SQL của DriverTransferSlipService: tạo từ 00:00 giờ VN ngày bắt đầu ghi Ví (), không có ngày bắt đầu = mọi đơn; người không thuộc bưu cục bật ví = không đơn nào.

Enrich thông tin địa chỉ đầy đủ (phường/quận/tỉnh) cho danh sách DriverFinOrderItem

Service quản lý tài khoản gửi email (CRUD + đặt mặc định + gửi thử). Secret (Password/SecretKey) được mã hóa qua trước khi lưu.

Bỏ cờ mặc định của tất cả tài khoản khác (chỉ 1 mặc định toàn hệ thống).

Service đọc nhật ký gửi email + báo cáo tổng hợp (chỉ đọc, phục vụ trang giám sát).

Điền tên tài khoản gửi cho danh sách log (1 truy vấn gộp).

Tìm kiếm báo lỗi

Tham số tìm kiếm Danh sách báo lỗi

Tìm kiếm báo lỗi do chính người dùng hiện tại gửi. Ai đăng nhập cũng gọi được, nên phạm vi dữ liệu phải bị chặn bằng .

Tham số tìm kiếm ID người dùng hiện tại Danh sách báo lỗi của chính người dùng

Tạo mới báo lỗi

Thông tin báo lỗi Thông tin người dùng hiện tại Kết quả tạo báo lỗi

Lấy chi tiết báo lỗi

ID báo lỗi Chi tiết báo lỗi

Lấy chi tiết một báo lỗi do chính người dùng hiện tại gửi. Không tìm thấy hoặc không phải của mình đều trả cùng một thông báo.

ID báo lỗi ID người dùng hiện tại Chi tiết báo lỗi

Cập nhật trạng thái báo lỗi (dành cho admin)

Thông tin cập nhật Thông tin người dùng hiện tại Kết quả cập nhật

Xóa báo lỗi

ID báo lỗi Kết quả xóa

Lấy danh sách báo lỗi theo trạng thái

Trạng thái Trang hiện tại Kích thước trang Danh sách báo lỗi

SystemName của nhóm thông báo báo cho người gửi biết báo lỗi đã đổi trạng thái. Seed bằng migration M202608161510 — đổi chuỗi này là thông báo im lặng ngừng gửi.

Thân chung của hai luồng tìm kiếm. khác null thì chỉ trả báo lỗi do chính người đó gửi — đây là lớp chặn duy nhất của endpoint SearchMine (chỉ yêu cầu đăng nhập, không đòi role), nên điều kiện lọc này không được phép rơi ra ngoài phương thức.

Dựng item hiển thị từ entity. Dùng chung cho tìm kiếm, chi tiết và lọc theo trạng thái để bốn chỗ không trôi lệch nhau mỗi lần thêm trường.

Wrapper đồng bộ cho GetImageUrlAsync, dùng trong LINQ projection

Báo cho người gửi biết báo lỗi của họ vừa đổi trạng thái. Lỗi gửi thông báo bị nuốt có chủ đích: trạng thái đã ghi xong, không được vì hỏng thông báo mà trả về lỗi cho người đang xử lý.

Cắt bớt mô tả để nhét vừa một dòng nội dung thông báo.

Interface cho service quản lý tài khoản ngân hàng

Tìm kiếm tài khoản ngân hàng

Lấy chi tiết tài khoản ngân hàng

Tạo hoặc cập nhật tài khoản ngân hàng

Xóa tài khoản ngân hàng

Tìm kiếm giao dịch ngân hàng

Import sao kê ngân hàng

Lấy danh sách tài khoản ngân hàng đang hoạt động

Tìm kiếm lịch sử import

Cập nhật số dư tài khoản

Cập nhật số dư tài khoản với thông tin user

Lấy tài khoản ngân hàng thu COD để hiển thị QR code cho lái xe nộp tiền

Service quản lý tài khoản ngân hàng

Helper method để convert IFormFile thành byte array

Lấy tài khoản ngân hàng thu COD (CanCollectCod = true) để hiển thị QR cho lái xe

Kết quả trả về thông tin tài khoản ngân hàng thu COD + VietQR URL

Interface cho service parse sao kê ngân hàng

Service parse sao kê ngân hàng

Interface cho parser riêng từng ngân hàng

Parser cho VPBank

Truncate string to specified length

Parser cho Techcombank

Truncate string to specified length

Parser cho Shinhan Bank

Parser cho HDBank

Parse multi-line transaction text từ HDBank Format: "Loại giao dịch: TTOAN THE TD - ATM/POS/EBANK So giao dich: 93297 Noi dung: THANH TOAN DU NO THE TIN DUNG HDBANK 9439, 7939"

Class lưu thông tin giao dịch HDBank đã parse

Parser cho VietinBank

Truncate string to specified length

Số tiền một người đang cầm trên một đơn, tách theo ba loại tiền.

Số tiền một người đang cầm trên một đơn, tách theo ba loại tiền.

Kết quả kiểm một lượt thu tiền ở màn Quỹ: hoặc một lỗi, hoặc danh sách đơn với số tiền do máy chủ tính.

Đơn sẽ thu, số tiền lấy từ OrderFin chứ không phải từ client.

Luật "ai đang cầm khoản tiền nào" dùng chung cho màn Quỹ () và phiếu chuyển khoản của lái xe ().

Hàm thuần, tách khỏi hai service vì cả hai ghi tiền thẳng qua repository/Dapper, không có cách nào kiểm chứng luật bằng test nếu luật nằm lẫn trong đó. Trước bản này CollectCashier tin hoàn toàn vào request: nhận mọi mã đơn, lấy số tiền client gửi, ghi đè người cầm và mức tiền vô điều kiện. Đo trên DB dev (3.228 phiếu thu, 20/08/2025 → 20/08/2026): 17 khoản bị thu hai lần, 10.880.000 đ ghi thừa vào ví — gồm 5 khoản phí giao ngày 10/07/2026 vừa thu tiền mặt ở màn Quỹ vừa được duyệt qua phiếu chuyển khoản.

Số mã đơn tối đa nêu trong thông báo lỗi — đủ để người thu đối chiếu.

Tiền đang cầm trên đơn mà một người thu ở mức / được phép nhận.

Cùng điều kiện với cột "đang cầm" của sp_GetCashierBalance và sp_GetCashierOrders — thứ người thu nhìn thấy phải đúng là thứ máy chủ cho thu. Tiền (lái xe đã lập phiếu chuyển khoản, đang chờ duyệt) bị loại: nó đã thuộc về phiếu, thu thêm bằng tiền mặt là ghi hai lần.

Kiểm một lượt thu tiền ở màn Quỹ trên trạng thái OrderFin hiện tại.

Danh sách đơn người thu nhìn thấy khi mở hộp thoại. Bản OrderFin đọc lại trong transaction, sau khi đã giữ khoá. Người nộp tiền. Mức phí của người thu (chi nhánh hay công ty). Mức COD của người thu. Phần tiền mặt người thu nhập; phần còn lại là chuyển khoản. Mỗi khoản client gửi (lớn hơn 0) phải khớp đúng khoản người nộp đang cầm. Lệch một khoản là từ chối cả phiếu: người thu đã đếm tiền mặt theo tổng họ nhìn thấy, âm thầm thu một số khác là tạo chênh lệch két. Khoản client không gửi thì để nguyên ở người nộp — ví dụ đơn lái xe vừa thu thêm sau lúc mở hộp thoại. Thu thiếu không làm lệch sổ; thu thừa mới làm.

Mã các đơn của phiếu chuyển khoản không còn khớp với tiền lái xe đang giữ ở trạng thái chờ chuyển khoản. Rỗng nghĩa là duyệt được.

Phiếu chụp số tiền lúc lái xe tạo. Trong lúc phiếu chờ duyệt, đơn có thể đã bị thu bằng đường khác hoặc bị sửa tiền — duyệt mà không kiểm lại là ghi vào ví một khoản không còn ở tay lái xe (đúng ca ngày 10/07/2026).

Khoá độc quyền trên tiền đang cầm, giữ tới khi transaction kết thúc. Hai tầng: theo người cầm và theo đơn.

Mọi đường chuyển tiền khỏi tay một người — thu ở màn Quỹ, lái xe tạo phiếu chuyển khoản, kế toán duyệt / từ chối, lái xe huỷ phiếu — giữ khoá người cầm trước, rồi khoá từng đơn sẽ đụng tới, rồi mới đọc lại OrderFin. Lượt sau đọc được kết quả của lượt trước và bị từ chối thay vì ghi vào ví lần hai. Khoá người cầm không đủ: một đơn thường có nhiều người cầm cùng lúc (phí lấy ở chi nhánh, phí giao và COD ở lái xe giao). Mọi đường ghi dùng DbSet.Update — ghi đè CẢ DÒNG OrderFin từ bản đã đọc — nên hai lượt khác người cầm trên cùng một đơn mà chạy song song thì lượt commit sau đè mất thay đổi của lượt trước, khoản tiền "quay lại" tay người cũ và thu được lần hai. Khoá đơn chặn đúng chỗ đó. Thứ tự cố định để không khoá chéo: người cầm trước (mỗi lượt đúng một người), rồi đơn theo Id tăng dần. Wallet.RowVersion chỉ chặn hai lượt ghi vào cùng một ví; OrderFin không có cột chống ghi đè nên các đường ghi OrderFin KHÔNG đi qua khoá này (thu tiền từ khách ở OrderFinService.Collect, đối soát, sửa đơn) vẫn có thể đè — rủi ro có từ trước.

Giữ khoá của người đang cầm tiền .

false khi chờ quá hạn — bên gọi rollback và báo người dùng thử lại.

Giữ khoá của từng đơn trong , theo Id tăng dần. Gọi SAU khoá người cầm.

false khi một khoá chờ quá hạn — bên gọi rollback và báo người dùng thử lại.

Khoá bằng sp_getapplock của SQL Server, chủ sở hữu là transaction — commit hay rollback là nhả, không có đường nào quên nhả.

Thời gian chờ mặc định cho mỗi khoá. Một lượt thu giữ khoá dưới một giây; quá mười giây là có gì đó treo, để người dùng thử lại tốt hơn là giữ request mãi.

Thời gian chờ khoá; test đặt ngắn để không phải chờ đủ mười giây.

Tên tài nguyên khoá người cầm — một người một khoá.

Tiền tố tên tài nguyên khoá đơn; SQL nối thêm Id.

Danh sách nhân sự đang cầm / sắp thu tiền, giới hạn theo phạm vi xem của — chỉ Founder và kế toán thấy toàn mạng lưới.

Đơn đang cầm tiền của một nhân sự. Nhân sự ngoài phạm vi xem của thì trả danh sách rỗng, như thể họ không cầm đơn nào.

Dịch phạm vi xem của người dùng thành hàng rào của màn Quỹ.

Hàm thuần, tách khỏi vì service gọi Dapper thẳng nên không có cách nào kiểm chứng luật phạm vi bằng test nếu luật nằm lẫn trong đó. Nguồn luật vẫn là — Founder và kế toán không giới hạn; người khác chỉ thấy bản thân, cấp dưới theo UserPreference.ManagerId và nhân sự các chi nhánh mình đứng tên quản lý (kể cả chi nhánh con). Cố ý dùng lại thay vì dựng cây phân cấp thứ ba, cùng lý do với OrderRevenueSaleScope.

Tham số @UserIds cho sp_GetCashierBalance.

Phạm vi nhân sự của người đang đăng nhập. NULL = không giới hạn; ngược lại là danh sách UserId ngăn cách dấu phẩy. false khi người này không thấy ai — bên gọi trả rỗng luôn, không gọi SP.

Người đang đăng nhập có được xem tiền đang cầm của không.

Canh đường đọc thứ hai của màn Quỹ: GetOrders nhận userId từ body, nên chỉ lọc danh sách thôi thì đổi id là vẫn đọc được đơn, địa chỉ và số điện thoại khách của lái xe chi nhánh khác.

Ví bưu cục v2 (V-05) — null khi dựng không có ví (giữ hành vi cũ).

Mã các đơn trong mà tiền người nộp đang cầm thuộc Ví bưu cục (V-05) — rỗng khi không phải người bưu cục có ví.

Enrich danh sách cashier với thông tin vi phạm nộp tiền

Cập nhật UserPreference.LastPaymentTime khi thu tiền từ lái xe

Cập nhật OrderTimeTrack với thời gian nhận tiền (chỉ khi Stage = Head)

Tạo hành trình cho các đơn hàng đã thu tiền

Model thu tiền

Ví bưu cục v2 (V-05 / V-40) — null khi dựng không có ví (giữ hành vi cũ).

Lái xe tạo phiếu chuyển tiền

Lái xe hủy phiếu (chỉ khi Pending)

Lái xe xem phiếu đang chờ duyệt

Tìm kiếm phiếu chuyển tiền (kế toán)

Chi tiết phiếu

Kế toán duyệt phiếu → logic giống CollectCashier

Kế toán từ chối phiếu → rollback Stage về Driver

Đơn lái xe đang cầm tiền ở mức Driver — nguồn của phiếu chuyển tiền. Lái xe của bưu cục nhượng quyền đã bật ví (): bỏ đơn Ví ghi (tạo từ ngày bắt đầu ghi Ví) — cùng luật SP màn Quỹ và CollectCashier.

Lái xe thuộc bưu cục nhượng quyền đang bật ví (V-05) — null khi không phải hoặc dựng không có ví.

Giữ khoá tiền đang cầm của lái xe rồi đọc lại trạng thái phiếu ngay trong khoá.

Thông báo lỗi, hoặc null khi phiếu vẫn đang chờ duyệt. Trạng thái kiểm ở đầu Approve/Reject/Cancel là đọc TRƯỚC khoá — hai lượt song song đều thấy "Pending". Phải đọc lại sau khoá, bằng phép chiếu để lấy giá trị trong DB chứ không phải bản EF đang giữ trong bộ nhớ.

Đóng một phiếu đang chờ (từ chối hoặc huỷ): trả tiền về mức Driver rồi đổi trạng thái, trong một transaction giữ khoá.

Thông báo lỗi, hoặc null khi đã đóng xong.

Rollback Stage từ InTransit về Driver cho các đơn hàng

Generate mã phiếu (DTS260704001)

Interface cho service quản lý chi phí

Tìm kiếm chi phí

Tham số tìm kiếm Người dùng hiện tại Kết quả tìm kiếm

Lấy thông tin chi tiết của chi phí

ID chi phí Người dùng hiện tại Thông tin chi tiết chi phí

Tạo mới hoặc cập nhật chi phí

Thông tin chi phí Người dùng hiện tại Kết quả tạo hoặc cập nhật

Duyệt chi phí

ID chi phí Người dùng hiện tại Kết quả duyệt

Bỏ duyệt chi phí (chuyển về trạng thái chờ duyệt)

ID chi phí Người dùng hiện tại Kết quả bỏ duyệt

Từ chối chi phí

ID chi phí Lý do từ chối Người dùng hiện tại Kết quả từ chối

Đánh dấu chi phí đã chuyển tiền

ID chi phí Người dùng hiện tại Ghi chú Kết quả đánh dấu chuyển tiền

Xóa chi phí

ID chi phí Người dùng hiện tại Kết quả xóa

Duyệt hàng loạt chi phí (chỉ dành cho Founder)

Danh sách ID chi phí cần duyệt Người dùng hiện tại Kết quả duyệt hàng loạt

Service quản lý chi phí

Khởi tạo một thể hiện của .

Đối tượng IRepository của Expense. Đối tượng IRepository của ExpenseCategory. Đối tượng IUserRepository của User. Đối tượng IRepository của Wallet. Đối tượng IRepository của Transaction. Đối tượng IRepository của UserBankAccount. Service quản lý quyền.

Tìm kiếm chi phí

Tham số tìm kiếm Người dùng hiện tại Kết quả tìm kiếm

Lấy thông tin chi tiết của chi phí

ID chi phí Người dùng hiện tại Thông tin chi tiết chi phí

Tạo mới hoặc cập nhật chi phí

Thông tin chi phí Người dùng hiện tại Kết quả của thao tác

Copy thông tin ngân hàng từ UserBankAccount vào Expense (Copy-on-Reference Pattern)

Expense entity cần cập nhật ID tài khoản ngân hàng

Tạo chi phí mới

Thông tin chi phí Kết quả của thao tác

Cập nhật chi phí (không thay đổi Status và RejectReason)

Thông tin chi phí Kết quả của thao tác

Duyệt chi phí

ID chi phí Người dùng hiện tại Kết quả của thao tác

Bỏ duyệt chi phí (chuyển về trạng thái chờ duyệt)

ID chi phí Người dùng hiện tại Kết quả của thao tác

Từ chối chi phí

ID chi phí Lý do từ chối Người dùng hiện tại Kết quả của thao tác

Đánh dấu chi phí đã chuyển tiền

ID chi phí Người dùng hiện tại Ghi chú Kết quả của thao tác

Ghi sổ cọc/tạm ứng khi chi phiếu có DepositUserId. Trả null nếu category của expense không thuộc hai danh mục cọc (không làm gì); trả BaseResult Failed nếu ghi sổ thất bại — caller phải rollback.

Duyệt hàng loạt chi phí (chỉ dành cho Founder)

Danh sách ID chi phí cần duyệt Người dùng hiện tại Kết quả duyệt hàng loạt

Xóa chi phí

ID chi phí Người dùng hiện tại Kết quả của thao tác

Tính toán các quyền cho ExpenseItem

ExpenseItem cần tính toán quyền Expense entity Người dùng hiện tại

Áp dụng filter quyền xem cho query

Query gốc Người dùng hiện tại Query đã được filter theo quyền xem

Kiểm tra quyền xem một chi phí cụ thể

Chi phí cần kiểm tra Người dùng hiện tại True nếu có quyền xem

Tạo lịch sử thay đổi trạng thái chi phí

ID của chi phí Trạng thái trước khi thay đổi Trạng thái sau khi thay đổi Người dùng hiện tại Ghi chú Lý do (dùng cho từ chối)

Kết quả duyệt hàng loạt chi phí

Số lượng chi phí duyệt thành công

Số lượng chi phí duyệt thất bại

Danh sách chi phí duyệt thất bại (kèm lý do)

Thông tin chi phí duyệt thất bại

Khởi tạo dư nợ hiện tại cho thẻ — dùng khi thêm thẻ mới vào hệ thống

Gắn danh sách giao dịch vào 1 kỳ sao kê

Lấy danh sách giao dịch chưa gắn kỳ sao kê của thẻ

Xác nhận thanh toán kỳ sao kê

Auto-generate kỳ sao kê: gom các giao dịch chưa gắn kỳ trong khoảng thời gian

Khởi tạo dư nợ cho thẻ mới thêm vào hệ thống Tạo 1 statement "snapshot" chứa dư nợ hiện tại

Gắn danh sách giao dịch vào 1 kỳ sao kê, tính lại TotalCharges

Lấy danh sách giao dịch chưa gắn kỳ sao kê

Quản trị MA TRẬN giá theo loại hàng: tuyến × lựa chọn thuộc tính trục.

Vì sao tách khỏi . Hai bảng khác hình dạng — bảng chung là tuyến × khoảng trọng lượng, bảng riêng là tuyến × option trục — nên gộp vào một service nghĩa là mọi phương thức phải rẽ nhánh theo "đang làm bảng nào". Đường bảng giá chung đã chứng minh hậu quả: một câu truy vấn thiếu vế GoodsCategoryId == null làm 13 ô giá theo loại hàng bị xoá oan mỗi lần bấm Lưu (nợ PSVC). Tách hẳn thì hai đường không thể vô tình chạm vào dữ liệu của nhau. Luật thuần nằm ở PriceMatrixRule (project Lada.Framework) để test với tới — service này chỉ lo đọc/ghi DB và dựng .

Đọc ma trận giá của một danh mục — lưới đầy đủ, phân biệt được ô có giá và ô trống.

Danh mục cần đọc. Loại giá. Khách sở hữu bảng giá. 0 = khách mặc định (mặc định cũ).

Ghi một lô ô giá (tạo / sửa / xoá mềm).

Ô vắng mặt trong payload là ô KHÔNG ĐỤNG TỚI. Xoá phải mang cờ .

Khởi tạo ma trận cho một danh mục: sinh đủ ô theo option của trục × tuyến.

Xoá bảng giá riêng của một danh mục ⇒ danh mục quay về tính theo TRỌNG LƯỢNG.

Danh mục cần xoá bảng giá riêng. Người thực hiện. Tên người thực hiện. Khách sở hữu bảng giá cần xoá. 0 = mọi khách, giữ đúng hành vi cũ. ⚠️ = 0 KHÔNG có nghĩa "khách mặc định" ở riêng phương thức này — nó nghĩa là mọi khách. Đó là hành vi vốn có và nó đúng với mục đích của thao tác: đưa danh mục về nhánh trọng lượng, mà luật chọn trục hỏi trên TOÀN BỘ dòng giá không phân biệt khách. Quy nó về khách mặc định sẽ để sót ô của khách riêng, và danh mục vẫn ở nhánh bảng giá riêng trong khi UI báo đã xoá xong.

Liệt kê các danh mục ĐÃ có bảng giá riêng, để FE đánh dấu.

Lọc theo khách sở hữu ô giá. 0 = mọi khách, giữ đúng hành vi cũ.

Triển khai quản trị ma trận giá theo loại hàng.

Đọc ma trận giá của một danh mục.

Ghi một lô ô giá.

Khởi tạo ma trận cho một danh mục.

Xoá bảng giá riêng của một danh mục.

⚠️ Đây là thao tác ĐỔI CÁCH TÍNH TIỀN: danh mục quay về nhánh trọng lượng ngay sau khi ô cuối cùng biến mất. Xoá mềm nên dữ liệu còn đó, nhưng cước của mọi đơn sau đó đổi ngay.

Liệt kê các danh mục đã có bảng giá riêng.

Nạp cấu hình danh mục kèm thuộc tính và lựa chọn (đã lọc xoá mềm).

Chọn thuộc tính trục — PHẢI cùng luật với GoodsCategoryPricingService.ResolveAsync.

Lọc đúng SingleSelect rồi DisplayOrder nhỏ nhất, rồi Id nhỏ nhất. Chọn khác engine nghĩa là người quản trị khai giá vào cột này còn đơn tra cột kia — bảng giá trông đầy đủ mà đơn vẫn báo "chưa có giá".

Quy customerId = 0 về khách mặc định. Trả 0 khi hệ thống chưa khai khách mặc định.

Chỉ dùng cho các thao tác ĐỌC/GHI một bảng giá cụ thể. DeleteMatrix và GetCategoriesWithPriceTable cố tình KHÔNG gọi hàm này: ở đó 0 nghĩa là mọi khách, xem chú thích trên interface.

Interface cho service quản lý doanh thu

Tìm kiếm doanh thu

Tham số tìm kiếm Người dùng hiện tại Kết quả tìm kiếm

Lấy thông tin chi tiết của doanh thu

ID doanh thu Người dùng hiện tại Thông tin chi tiết doanh thu

Tạo mới hoặc cập nhật doanh thu

Thông tin doanh thu Người dùng hiện tại Kết quả tạo hoặc cập nhật

Duyệt doanh thu

ID doanh thu Người dùng hiện tại Kết quả duyệt

Từ chối doanh thu

ID doanh thu Lý do từ chối Người dùng hiện tại Kết quả từ chối

Đánh dấu doanh thu đã nhận tiền

ID doanh thu Người dùng hiện tại Ghi chú Kết quả đánh dấu nhận tiền

Xóa doanh thu

ID doanh thu Người dùng hiện tại Kết quả xóa

Nộp cọc trách nhiệm — tạo Income loại cọc lái xe

Service quản lý doanh thu

Khởi tạo một thể hiện của

Tìm kiếm doanh thu

Lấy thông tin chi tiết của doanh thu

Tạo mới hoặc cập nhật doanh thu

Duyệt doanh thu

Từ chối doanh thu

Đánh dấu doanh thu đã nhận tiền

Xóa doanh thu

Nộp cọc trách nhiệm — tạo Income loại cọc lái xe

Áp dụng filter theo quyền xem

Kiểm tra quyền xem doanh thu

Kiểm tra quyền duyệt doanh thu

Kiểm tra quyền từ chối doanh thu

Tính toán permissions cho từng item

Tạo lịch sử doanh thu

Service quản lý hóa đơn VAT nội bộ (CRUD)

Tìm kiếm hóa đơn VAT

Service đồng bộ hóa đơn VAT từ API Tổng cục Thuế

Đồng bộ hóa đơn từ API Tổng cục Thuế cho một khoảng thời gian

Ngày bắt đầu Ngày kết thúc Loại đồng bộ: Manual hoặc Auto User ID nếu là manual sync Chiều hóa đơn: 1=Bán ra, 2=Mua vào

Đồng bộ hóa đơn bán ra của ngày hôm qua (dùng cho Hangfire job)

Đồng bộ hóa đơn mua vào của ngày hôm qua (dùng cho Hangfire job)

Lấy thông tin đồng bộ gần nhất

Interface cho service quản lý thời gian nhận tiền trong OrderTimeTrack

Cập nhật thời gian nhận tiền trong OrderTimeTrack

ID đơn hàng Stage của SourceFee (3=Branch, 9=Head) Stage của DestFee (3=Branch, 9=Head) Stage của TransferFee (3=Branch, 9=Head) Stage của COD (3=Branch, 9=Head) Stage của DeductCodFee (3=Branch, 9=Head) - chỉ khi PayFeeType = COD ID người cập nhật Tên người cập nhật Thời gian hiện tại (null = SYSDATETIMEOFFSET()) Kết quả cập nhật

Cập nhật thời gian nhận tiền cho nhiều đơn hàng

Danh sách cập nhật cho các đơn hàng ID người cập nhật Tên người cập nhật Thời gian hiện tại (null = SYSDATETIMEOFFSET()) Kết quả cập nhật

Model cho việc cập nhật thời gian nhận tiền của một đơn hàng

Service quản lý thời gian nhận tiền trong OrderTimeTrack

Khởi tạo một thể hiện của .

Database connection.

Cập nhật thời gian nhận tiền trong OrderTimeTrack

Cập nhật thời gian nhận tiền cho nhiều đơn hàng

Giao diện cho dịch vụ quản lý giá.

Lấy bảng giá của một PHẠM VI bất kỳ — bộ ba (customerId, goodsCategoryId, priceType).

Khách sở hữu bảng giá. 0 = khách mặc định. Loại hàng. null = bảng giá chung theo khoảng trọng lượng. Loại giá. Bảng giá của phạm vi, kèm danh sách tuyến để dựng lưới. Bản tổng quát của . Hai đường dùng CHUNG một biểu thức phạm vi () nên không thể trôi khác nhau.

Cập nhật bảng giá của một PHẠM VI bất kỳ.

Bảng giá, mang trọn bộ ba định danh phạm vi. Kết quả của thao tác. ⚠️ Dòng đã có trong database mà không còn Id trong payload sẽ bị xoá mềm. Nên phạm vi trong phải đúng bằng phạm vi mà trang đang hiển thị — nạp rộng hơn những gì người dùng nhìn thấy là xoá mất dữ liệu họ không hề đụng tới.

Liệt kê mọi phạm vi bảng giá của một khách, kèm cờ "đang mượn bảng mặc định".

Khách cần xem. 0 = khách mặc định. Danh sách phạm vi. Đây là màn hình trả lời câu "khách này đang tính tiền bằng bảng giá của ai" — xem .

Lấy danh sách giá mặc định theo loại giá.

Loại giá. Danh sách giá mặc định. Lớp bọc mỏng của với phạm vi (khách mặc định, bảng chung). Giữ lại để client hiện có không phải đổi cùng lúc với backend.

Cập nhật danh sách giá mặc định.

Thông tin danh sách giá. Kết quả của thao tác. Lớp bọc mỏng của — ép phạm vi về (khách mặc định, bảng chung) bất kể model mang gì, để một client cũ lỡ gửi GoodsCategoryId cũng không đổi được phạm vi qua đường này.

Xuất danh sách giá mặc định ra file.

Đường dẫn file. Loại giá của bảng đang mở. Kết quả của thao tác. là tham số THÊM VÀO khi vá nợ N4: trước đó hàm này nạp mọi dòng giá của khách mặc định, không lọc loại giá cũng không lọc bảng giá chung, nên file Excel trộn cả ba loại giá lẫn ô giá theo loại hàng. Xem chú thích tại nơi truy vấn.

Sao chép bảng giá từ một phạm vi nguồn sang phạm vi đích.

Nguồn, đích, loại giá và các tuỳ chọn copy. Số ô đã tạo, bỏ qua, đè — và cảnh báo nếu có. ⚠️ Không đè im lặng — mặc định OverwriteExisting = false. UI phải hiện đủ ba số và mọi .

Triển khai dịch vụ quản lý giá.

Khởi tạo một thể hiện của .

Đối tượng IRepository của Price. Đối tượng IRepository của Customer. Đối tượng IRepository của Route. Đối tượng IRepository của Category — lấy tên loại hàng cho danh sách phạm vi. Cấu hình loại hàng — kiểm trục giá khi sao chép giữa hai loại hàng khác nhau. Nguồn tham số cấu hình cước — lấy bước trọng lượng mặc định.

Lấy bảng giá của một phạm vi bất kỳ.

Khách sở hữu bảng giá. 0 = khách mặc định. Loại hàng. null = bảng giá chung. Loại giá. Bảng giá của phạm vi.

Lấy danh sách giá mặc định theo loại giá.

Loại giá. Danh sách giá mặc định.

Cập nhật bảng giá của một phạm vi bất kỳ.

Bảng giá, mang trọn bộ ba định danh phạm vi. Kết quả của thao tác.

Cập nhật danh sách giá mặc định.

Thông tin danh sách giá. Kết quả của thao tác. Ép phạm vi về (khách mặc định, bảng giá chung) rồi gọi . Ép chứ không tin model: endpoint cũ mang tên "DefaultPriceList" nên một payload lỡ kèm CustomerId hay GoodsCategoryId khác không được phép lái lần lưu này sang phạm vi khác — hậu quả là xoá mềm bảng giá của phạm vi đó.

Liệt kê mọi phạm vi bảng giá của một khách.

Khách cần xem. 0 = khách mặc định. Danh sách phạm vi, kèm cờ đang mượn bảng mặc định. Đếm theo (GoodsCategoryId, PriceType) ở phía C# sau khi đã kéo về tập tối thiểu: phép gom nhóm hai khoá kèm Count là chỗ EF hay bó tay lúc dịch câu truy vấn, và tập dòng giá của một khách vốn nhỏ. Phạm vi khách trống hẳn mà bảng mặc định có dòng thì vẫn được liệt kê với IsInherited = true — đó là phạm vi khách ĐANG tính tiền theo (QĐ-2), không hiện ra thì màn hình nói thiếu một nửa sự thật.

Đếm số dòng giá của một khách, gom theo (GoodsCategoryId, PriceType).

Điền tên loại hàng cho các phạm vi có GoodsCategoryId.

Quy customerId = 0 về khách mặc định; giá trị dương giữ nguyên.

Id khách của phạm vi. 0 = chưa khai khách mặc định nào. Quy ước "0 nghĩa là khách mặc định" nằm ở hợp đồng API, nên nó phải được phân giải ở đúng một chỗ. Việc tra khách mặc định đi qua — nó ném lỗi khi DB có nhiều hơn một khách mặc định, thay vì để đường đọc và đường lưu chọn ra hai khách khác nhau.

Xuất danh sách giá mặc định ra file.

Đường dẫn file. Loại giá của bảng đang mở. Kết quả của thao tác.

Sao chép bảng giá từ một phạm vi nguồn sang phạm vi đích.

Dựng ánh xạ lựa chọn trục nguồn → đích theo NHÃN, khi sao chép giữa hai loại hàng khác nhau.

Loại hàng nguồn. Loại hàng đích. Dòng giá nguồn — để bảo đảm mọi OptionId thật sự dùng đều ánh xạ được. Nơi ghi cảnh báo không chặn (VD hai loại áp giá khác kiểu). (map, null) khi hợp lệ — map có thể null nếu cả hai loại không chia cột; (null, câu lỗi) khi hai loại không cùng thuộc tính trục. "Cùng thuộc tính trục" nghĩa là: cùng có (hoặc cùng không có) thuộc tính IsPriceAxis kiểu chọn-một, TÊN thuộc tính trùng nhau, và mọi lựa chọn mà dòng giá nguồn đang dùng đều có lựa chọn cùng nhãn bên đích. Ánh xạ theo nhãn vì Id lựa chọn thuộc về từng loại hàng, không dùng chung được.

Thuộc tính trục giá của một cấu hình loại hàng — IsPriceAxis kiểu chọn-một, chưa xoá.

Giao diện cho dịch vụ quản lý đối soát.

Tìm kiếm khách hàng cần đối soát với phân trang.

Tham số tìm kiếm. ID người dùng hiện tại. Kết quả tìm kiếm khách hàng cần đối soát.

Tìm kiếm đơn hàng có thể đối soát với phân trang.

Tham số tìm kiếm. Id người dùng hiện tại — dùng để ép phạm vi xem. Loại đối soát (tùy chọn). Kết quả tìm kiếm đơn hàng có thể đối soát.

Tìm kiếm đối soát.

Tham số tìm kiếm. ID người dùng hiện tại. Kết quả tìm kiếm đối soát.

Lấy chi tiết đối soát.

ID đối soát. Chi tiết đối soát.

Tạo đối soát mới.

Thông tin đối soát. Kết quả của thao tác.

Xác nhận đối soát.

ID đối soát. Thông tin người dùng hiện tại. Kết quả của thao tác.

Cập nhật đã chuyển khoản.

Thông tin chuyển khoản. Kết quả của thao tác.

Hủy đối soát với thông tin chi tiết.

Thông tin hủy đối soát. Kết quả của thao tác.

Hủy đối soát (phương thức cũ - deprecated).

ID đối soát. Thông tin người dùng hiện tại. Kết quả của thao tác.

Dịch vụ quản lý đối soát.

Ví bưu cục v2: nhận ra đơn do bưu cục nhượng quyền bật ví bán — màn đối soát cũ không lập phiếu cho đơn này (§6 mục 21).

Khởi tạo dịch vụ quản lý đối soát.

Người này có được xem dữ liệu đối soát của một khách hàng hay không.

Cùng một nguồn luật với màn đối soát mới (CustomerReconciliationSlipService) — hai màn hình đọc gần như cùng một tập tiền, để chúng lệch luật là để lại đúng cái lỗ vừa vá.

Tìm kiếm khách hàng cần đối soát với phân trang.

Tìm kiếm đơn hàng có thể đối soát với phân trang.

Tham số tìm kiếm Loại đối soát (tùy chọn)

Tìm kiếm đối soát.

Lấy chi tiết đối soát.

Tạo đối soát mới.

Xác nhận đối soát.

Cập nhật đã chuyển khoản.

Hủy đối soát với thông tin chi tiết.

Hủy đối soát (phương thức cũ - deprecated).

Tạo mã đối soát tự động

Tạo giao dịch trừ tiền cho đối soát

Thông tin đối soát Model chuyển tiền

Giao diện cho dịch vụ quản lý tuyến vận tải.

Tìm kiếm tuyến vận tải.

Thông số tìm kiếm. Kết quả tìm kiếm tuyến vận tải.

Tạo mới hoặc cập nhật thông tin tuyến vận tải.

Thông tin tuyến vận tải. Kết quả của thao tác.

Lấy thông tin tuyến vận tải theo ID.

ID của tuyến vận tải. Thông tin tuyến vận tải.

Xóa tuyến vận tải theo ID.

ID của tuyến vận tải. Kết quả của thao tác.

Triển khai dịch vụ quản lý tuyến vận tải.

Khởi tạo một thể hiện của .

Đối tượng IRepository của Route.

Tìm kiếm tuyến vận tải.

Thông số tìm kiếm. Kết quả tìm kiếm tuyến vận tải.

Tạo mới hoặc cập nhật thông tin tuyến vận tải.

Thông tin tuyến vận tải. Kết quả của thao tác.

Tạo mới tuyến vận tải.

Thông tin tuyến vận tải. Kết quả của thao tác.

Cập nhật thông tin tuyến vận tải.

Thông tin tuyến vận tải. Kết quả của thao tác.

Lấy thông tin tuyến vận tải theo ID.

ID của tuyến vận tải. Thông tin tuyến vận tải.

Xóa tuyến vận tải theo ID.

ID của tuyến vận tải. Kết quả của thao tác.

Tìm kiếm giao dịch của ví. Chỉ Founder và Accountant mới được xem tất cả giao dịch, user khác chỉ xem ví của mình.

Lấy chi tiết giao dịch (chỉ cho TransactionType = 4)

Lấy thống kê giao dịch theo loại

Lấy lịch sử số dư ví

Helper method để lấy icon cho loại giao dịch

Service quản lý hóa đơn VAT nội bộ (CRUD)

Tìm kiếm hóa đơn VAT

Service đồng bộ hóa đơn VAT từ API Tổng cục Thuế

Đồng bộ hóa đơn từ API Tổng cục Thuế (tự động chia nhỏ nếu khoảng ngày > 30 ngày)

Đồng bộ hóa đơn cho một batch đơn lẻ (tối đa 30 ngày)

Đồng bộ hóa đơn của ngày hôm qua

Đồng bộ hóa đơn mua vào của ngày hôm qua

Lấy thông tin đồng bộ gần nhất

Tự động lấy Bearer Token mới từ API GDT bằng cách giải captcha và đăng nhập

Set các header phổ biến giống browser cho request tới GDT

Gọi API GDT và xử lý kết quả (insert/update hóa đơn) - hỗ trợ phân trang cursor-based

Map dữ liệu từ API sang Entity

Cập nhật entity từ API data

Parse date từ API (có thể là string hoặc long timestamp)

Exception đánh dấu token hết hạn để trigger retry logic

Lấy lãi suất năm áp dụng cho kỳ (periodNumber) dựa trên bảng giai đoạn. Nếu không có giai đoạn nào khớp → fallback về InterestRate cố định trên VehicleLoan.

Xóa các kỳ chưa thanh toán (Pending) và tạo lại dựa trên lãi suất mới. Các kỳ đã thanh toán (Paid/PaidLate) sẽ không bị ảnh hưởng. Lưu ý: Sử dụng hard-delete cho pending schedules vì bảng có unique index trên (VehicleLoanId, PeriodNumber), soft-delete sẽ conflict với bản ghi mới.

Regenerate lịch trả nợ khi cập nhật hợp đồng vay. Tránh reload loan entity (đã tracked) để không gây EF tracking conflict. Truy vấn schedules riêng, hard-delete pending, tạo lại với dữ liệu mới.

Upload tài liệu cho hợp đồng vay

Lấy danh sách tài liệu của hợp đồng vay

Xóa tài liệu

Helper lấy tên loại tài liệu

Lấy thông tin tất toán của khoản vay

Tạo hoặc cập nhật tất toán (sync danh sách phí) Lưu ý: KHÔNG tạo Expense — Expense chỉ tạo khi duyệt phí

Duyệt 1 khoản phí tất toán → Tạo Expense

Bỏ duyệt 1 khoản phí tất toán → Reject Expense liên kết Chỉ cho phép nếu Expense chưa thanh toán

Xóa 1 khoản phí tất toán (soft-delete)

Hoàn tất tất toán: đánh dấu khoản vay Completed

Hủy tất toán

Tìm kiếm ví

Điều chỉnh số dư ví (cân ví)

Lấy danh sách ví cho suggestion (select control)

Từ khóa tìm kiếm Danh sách tối đa 20 ví

Tìm kiếm ví

Tìm kiếm giao dịch của ví

Điều chỉnh số dư ví bằng cách tạo giao dịch Income hoặc Outcome

Lấy danh sách ví cho suggestion (select control)

Từ khóa tìm kiếm Danh sách tối đa 20 ví

Interface cho service chuyển tiền giữa các ví

Chuyển tiền từ ví nguồn sang ví đích

ID ví nguồn (ví của người dùng đang đăng nhập) Thông tin chuyển tiền Kết quả chuyển tiền

Service xử lý chuyển tiền giữa các ví với đảm bảo toàn vẹn giao dịch Sử dụng DB Transaction + Optimistic Concurrency (RowVersion)

Chuyển tiền từ ví nguồn sang ví đích với đảm bảo toàn vẹn

ID ví nguồn (ví của người dùng đang đăng nhập) Thông tin chuyển tiền

Thực hiện giao dịch chuyển tiền trong DB Transaction

ID ví nguồn Thông tin chuyển tiền ID nhóm giao dịch

Validate yêu cầu chuyển tiền

ID ví nguồn Thông tin chuyển tiền

Kết quả validation

Kết quả chuyển tiền

ID nhóm giao dịch (dùng để tra cứu 2 dòng transaction)

ID giao dịch bên ví nguồn

ID giao dịch bên ví đích

Số dư mới của ví nguồn sau khi chuyển

Số dư mới của ví đích sau khi chuyển

Service để seed dữ liệu ngân hàng

Seed dữ liệu ngân hàng từ danh sách cung cấp

Lấy dữ liệu ngân hàng từ danh sách được cung cấp

Service quản lý ngân hàng

Tìm kiếm ngân hàng với phân trang

Lấy tất cả ngân hàng đang hoạt động

Lấy ngân hàng theo ID (trả về model để edit)

Tạo hoặc cập nhật ngân hàng

Tạo ngân hàng mới

Cập nhật ngân hàng

Xóa ngân hàng

Gợi ý ngân hàng theo từ khóa (cho select option)

Interface cho dịch vụ xuất Excel phiếu đối soát khách hàng

Xuất Excel danh sách phiếu đối soát khách hàng

ID người dùng hiện tại — dùng để ép phạm vi xem Model xuất Excel Kết quả xuất file

Xuất Excel chi tiết phiếu đối soát khách hàng

ID phiếu đối soát Model xuất Excel Kết quả xuất file

Xuất Excel danh sách đơn hàng cần đối soát của khách hàng

ID khách hàng ID người dùng hiện tại Model xuất Excel Kết quả xuất file

Dịch vụ xuất Excel phiếu đối soát khách hàng

Xuất Excel danh sách phiếu đối soát khách hàng

Xuất Excel chi tiết phiếu đối soát khách hàng

Xuất Excel danh sách đơn hàng cần đối soát của khách hàng

Lấy dữ liệu phiếu đối soát

Lấy dữ liệu chi tiết phiếu đối soát

Tạo ExcelPackage danh sách phiếu đối soát

Tạo ExcelPackage chi tiết phiếu đối soát

Thêm thông tin công ty vào đầu worksheet

Thêm thông tin chung phiếu đối soát

Thêm chi tiết đơn hàng

Định dạng worksheet chi tiết phiếu đối soát

Thiết lập header cho danh sách phiếu đối soát

Điền dữ liệu danh sách phiếu đối soát

Định dạng worksheet danh sách phiếu đối soát

Lấy mô tả trạng thái

Tạo ExcelPackage danh sách đơn hàng cần đối soát

Thêm thông tin khách hàng và tổng hợp tài chính

Thêm bảng đơn hàng cần đối soát

Định dạng worksheet danh sách đơn hàng cần đối soát

Ví bưu cục v2 (E8 / E13, plan §3.6 + §6 mục 21): đơn COD do bưu cục nhượng quyền bật ví bán trả khách = COD − cước chính thức − nợ cước đơn hoàn cùng khách; null = không móc ví (test cũ dựng service không có ví).

Người này có được xem dữ liệu đối soát của một khách hàng hay không.

Một chỗ duy nhất trả lời câu hỏi đó cho cả bốn đường đọc chạm tới một khách cụ thể (đơn có thể đối soát, chi tiết phiếu, nhật ký phiếu, tạo phiếu). Khách được coi là trong phạm vi khi sale phụ trách hoặc một người đồng quản lý nằm trong tập nhân sự mình xem được.

Validate trạng thái phiếu trước khi hoàn thành

Lấy hoặc tạo ví Personal cho user

Tạo giao dịch ví cho phiếu đối soát (dùng chung cho cả Payable và Receivable)

Hoàn thành phiếu Payable (thu tiền)

Cập nhật đơn hàng cho phiếu Payable

Hoàn thành phiếu Receivable (chi tiền)

Cập nhật đơn hàng cho phiếu Receivable

Tạo OrderTrack cho danh sách đơn hàng (dùng chung)

Resolve ProofImageUrl (có thể chứa nhiều system paths phân cách bởi ;) thành public URLs

Interface cho service quản lý danh mục chi phí

Tìm kiếm danh mục chi phí với phân trang

Lấy danh mục chi phí theo ID

Tạo hoặc cập nhật danh mục chi phí

Xóa danh mục chi phí

Lấy danh sách tất cả danh mục chi phí (cho dropdown)

Kiểm tra tên danh mục có trùng không

Lấy danh sách danh mục chi phí theo cây phân cấp

Lấy danh sách danh mục gốc (không có ParentId)

Lấy danh sách danh mục con theo ParentId

Kiểm tra có thể xóa danh mục không (không có danh mục con)

Service quản lý danh mục chi phí

Tìm kiếm danh mục chi phí với phân trang Hỗ trợ hai chế độ hiển thị: List (danh sách) và Tree (cây phân cấp)

Lấy danh mục chi phí theo ID

Tạo hoặc cập nhật danh mục chi phí

Xóa danh mục chi phí

Lấy danh sách tất cả danh mục chi phí (cho dropdown)

Kiểm tra tên danh mục có trùng không

Lấy danh sách danh mục chi phí theo cây phân cấp

Lấy danh sách danh mục gốc (không có ParentId)

Lấy danh sách danh mục con theo ParentId

Kiểm tra có thể xóa danh mục không (không có danh mục con)

Lấy thông tin tên người duyệt cho danh sách items

Xây dựng cấu trúc cây từ danh sách phẳng

Xây dựng cây phân cấp đệ quy

Interface cho dịch vụ xuất Excel thông tin đơn hàng

Xuất Excel thông tin đơn hàng theo danh sách OrderId hoặc OrderCode

Thông tin đầu vào Kết quả xuất file

Xuất Excel thông tin đơn hàng theo danh sách OrderId

Danh sách ID đơn hàng Đường dẫn file Excel Kết quả xuất file

Xuất Excel thông tin đơn hàng theo danh sách OrderCode

Danh sách mã đơn hàng Đường dẫn file Excel Kết quả xuất file

Dịch vụ xuất Excel thông tin đơn hàng

Xuất Excel thông tin đơn hàng theo danh sách OrderId hoặc OrderCode

Thông tin đầu vào Kết quả xuất file

Xuất Excel thông tin đơn hàng theo danh sách OrderId

Danh sách ID đơn hàng Đường dẫn file Excel Kết quả xuất file

Xuất Excel thông tin đơn hàng theo danh sách OrderCode

Danh sách mã đơn hàng Đường dẫn file Excel Kết quả xuất file

Xử lý danh sách đơn hàng và tạo file Excel

Danh sách đơn hàng Danh sách ID/Code được yêu cầu Đường dẫn file Kết quả xuất file

Tạo file Excel từ danh sách đơn hàng

Danh sách đơn hàng cần xuất Đường dẫn file

Thiết lập header cho Excel

Worksheet

Điền dữ liệu vào Excel

Worksheet Danh sách đơn hàng

Định dạng Excel worksheet

Worksheet Số dòng dữ liệu

Lấy danh sách khách hàng cần đối soát (có đơn hàng chưa đối soát) Sale chỉ thấy khách hàng của mình

Lấy danh sách đơn hàng có thể đối soát của một khách hàng

Tạo phiếu đối soát mới

Tìm kiếm phiếu đối soát

Lấy chi tiết phiếu đối soát

Duyệt phiếu (Kế toán)

Từ chối phiếu (Kế toán)

Hoàn thành phiếu (Xác nhận thanh toán)

Upload ảnh chứng từ cho phiếu đối soát

Lấy lịch sử thao tác

Interface cho service quản lý danh mục doanh thu

Tìm kiếm danh mục doanh thu với phân trang

Lấy danh mục doanh thu theo ID

Tạo hoặc cập nhật danh mục doanh thu

Xóa danh mục doanh thu

Lấy danh sách tất cả danh mục doanh thu (cho dropdown)

Kiểm tra tên danh mục có trùng không

Lấy danh sách danh mục doanh thu theo cây phân cấp

Lấy danh sách danh mục gốc (không có ParentId)

Lấy danh sách danh mục con theo ParentId

Kiểm tra có thể xóa danh mục không (không có danh mục con)

Service quản lý danh mục doanh thu

Tìm kiếm danh mục doanh thu với phân trang Hỗ trợ hai chế độ hiển thị: List (danh sách) và Tree (cây phân cấp)

Lấy danh mục doanh thu theo ID

Tạo hoặc cập nhật danh mục doanh thu

Xóa danh mục doanh thu

Lấy danh sách tất cả danh mục doanh thu (cho dropdown)

Kiểm tra tên danh mục có trùng không

Lấy danh sách danh mục doanh thu theo cây phân cấp

Lấy danh sách danh mục gốc (không có ParentId)

Lấy danh sách danh mục con theo ParentId

Kiểm tra có thể xóa danh mục không (không có danh mục con)

Lấy thông tin tên người duyệt cho danh sách items

Xây dựng cấu trúc cây từ danh sách phẳng

Xây dựng cây phân cấp đệ quy

Interface service quản lý tài khoản ngân hàng người dùng

Tìm kiếm tài khoản ngân hàng người dùng

Tham số tìm kiếm Kết quả tìm kiếm

Lấy thông tin chi tiết tài khoản ngân hàng theo ID

ID tài khoản ngân hàng Thông tin chi tiết tài khoản ngân hàng

Tạo mới hoặc cập nhật tài khoản ngân hàng

Thông tin tài khoản ngân hàng Kết quả của thao tác

Xóa tài khoản ngân hàng

Thông tin tài khoản ngân hàng cần xóa Kết quả của thao tác

Lấy danh sách tài khoản ngân hàng của người dùng

ID người dùng Danh sách tài khoản ngân hàng

Tìm kiếm tài khoản ngân hàng của người dùng cụ thể

Tham số tìm kiếm ID người dùng Kết quả tìm kiếm

Lấy tài khoản ngân hàng theo ID và kiểm tra quyền sở hữu

ID tài khoản ngân hàng ID người dùng Thông tin tài khoản ngân hàng

Xóa tài khoản ngân hàng với kiểm tra quyền sở hữu

ID tài khoản ngân hàng ID người dùng ID người cập nhật Tên người cập nhật Kết quả của thao tác

Interface cho dịch vụ xuất Excel phiếu đối soát

Xuất Excel danh sách phiếu đối soát

Model xuất Excel Kết quả xuất file

Xuất Excel chi tiết phiếu đối soát

ID phiếu đối soát Model xuất Excel Kết quả xuất file

Dịch vụ xuất Excel phiếu đối soát

Xuất Excel danh sách phiếu đối soát

Xuất Excel chi tiết phiếu đối soát

Lấy dữ liệu phiếu đối soát

Lấy dữ liệu chi tiết phiếu đối soát

Tạo ExcelPackage danh sách phiếu đối soát

Tạo ExcelPackage chi tiết phiếu đối soát

Thêm thông tin công ty vào đầu worksheet

Thêm thông tin chung phiếu đối soát

Thêm chi tiết đơn hàng

Lấy địa chỉ gửi

Lấy địa chỉ nhận

Lấy thông tin sản phẩm

Lấy thông tin tài chính đơn hàng

Định dạng worksheet chi tiết phiếu đối soát

Thiết lập header cho danh sách phiếu đối soát

Điền dữ liệu danh sách phiếu đối soát

Định dạng worksheet danh sách phiếu đối soát

Lấy mô tả trạng thái

Phạm vi dữ liệu đối soát của một người dùng: hoặc không giới hạn, hoặc một tập nhân sự cụ thể.

Cố ý KHÔNG trả List<int> trần. Danh sách rỗng có hai nghĩa trái ngược nhau — "không thấy gì" và "thấy tất cả" — và mọi bên gọi sẽ phải tự nhớ nghĩa nào là nghĩa nào. Kiểu này ép bên gọi hỏi trước.

Không giới hạn phạm vi — Founder và kế toán.

Tập nhân sự xem được, chỉ có nghĩa khi là false.

Không xem được dòng nào — tài khoản không xác định được, fail-closed.

Thu hẹp phạm vi theo một nhân sự do người dùng chỉ định (bộ lọc trên giao diện).

Bộ lọc của client chỉ được **thu hẹp** tập đang xem được: truyền id của người ngoài phạm vi vào thì giao ra rỗng chứ không lấy thêm được dòng nào (chống IDOR).

Nguồn duy nhất của luật "ai xem được phiếu đối soát của ai".

Miền đối soát có bảy đường đọc cùng một tập dữ liệu — danh sách khách cần đối soát, danh sách phiếu, chi tiết phiếu, đơn có thể đối soát, nhật ký phiếu và hai đường xuất Excel. Trước bản này mỗi đường tự chép lại luật và đã lệch nhau thật: chi tiết phiếu cho qua bất kỳ ai có role CustomerReconciliationSlip.View (tức cả nhóm "Kinh doanh"), còn xuất Excel danh sách phiếu thì không nhận userId nên xuất toàn bộ phiếu của công ty. Ba cấp phạm vi, tính từ đúng hai cây phân cấp mà hệ thống đang dùng ở các miền khác (KPI, chat, bảo dưỡng) — không dựng cây thứ ba: Nhân viên: chỉ khách mình phụ trách (Customer.ManagerId hoặc đồng quản lý). Quản lý nhóm: thêm cấp dưới theo UserPreference.ManagerId, đệ quy hết cây. Quản lý chi nhánh / mạng lưới: thêm nhân sự của các chi nhánh mình đứng tên quản lý (Agency.ManagerId) và toàn bộ chi nhánh con cháu của chúng.

Phạm vi của một người dùng. Người không xác định được thì không thấy gì (fail-closed).

Founder bỏ qua mọi ràng buộc phạm vi ở tầng máy chủ.

Kế toán đối soát toàn công ty — vốn đã là luật của miền này từ trước.

Chặn vòng lặp dữ liệu khi duyệt cây quản lý nhân sự. Cây thật sâu 3–4 tầng; 10 là mức không bao giờ chạm tới trong nghiệp vụ nhưng vẫn cứu được nếu ai đó trỏ vòng A→B→A.

IUserRepository chứ không phải IRepository<User>: Repository<T> ràng buộc T : BaseEntity còn User kế thừa IdentityUser<int>, nên bản generic biên dịch xanh nhưng ném ngay khi DI dựng service.

Cấp dưới theo cây quản lý nhân sự, đệ quy hết các tầng.

Đọc UserPreference.ManagerId, KHÔNG phải User.ManagerId: cột trên User chỉ còn nghĩa cũ "sale quản lý khách hàng" và không luồng nào ghi cho nhân viên (đo trên DB 2026-08-14: 0/131 nhân viên có User.ManagerId > 0, 46 người có UserPreference.ManagerId > 0). Cùng nguồn với KpiVisibilityResolver. Khác KPI ở chỗ đi hết cây thay vì dừng ở cấp dưới trực tiếp: trưởng phòng kinh doanh quản lý trưởng nhóm, trưởng nhóm quản lý sale — dừng ở một tầng thì trưởng phòng không thấy tiền COD của chính tệp khách phòng mình.

Nhân sự thuộc các chi nhánh mà người này đứng tên quản lý, kể cả chi nhánh con cháu.

Mở theo Agency.ManagerId chứ KHÔNG theo User.AgencyId của chính người dùng: lấy theo chi nhánh của bản thân thì mọi sale ngồi cùng bưu cục cũng thấy tiền của nhau, đúng thứ bản vá này đang chữa. Chỉ người đứng tên quản lý chi nhánh mới được mở rộng. Cây chi nhánh duyệt bằng IAgencyService.GetAgencyWithDescendantIdsAsync (đệ quy đầy đủ, có cache 10 phút) — cùng hàm mà phân hệ bảo dưỡng và điều phối đang dùng.

Interface dịch vụ quản lý hóa đơn thuế

Dịch vụ quản lý hóa đơn thuế

Tạo hóa đơn thuế mới

Cập nhật trạng thái hóa đơn thuế

Lấy thông tin hóa đơn thuế theo ID

Lấy thông tin hóa đơn thuế theo ID phiếu đối soát

Xóa hóa đơn thuế (chỉ cho phép xóa khi ở trạng thái NotIssued)

Kiểm tra chuyển trạng thái hợp lệ

Map entity sang item using AutoMapper

Lấy VAT rate từ cấu hình với fallback mặc định 8%

Interface cho dịch vụ xuất Excel phiếu chuyển khoản

Xuất Excel danh sách phiếu chuyển khoản

Model xuất Excel Kết quả xuất file

Xuất Excel chi tiết phiếu chuyển khoản

ID phiếu chuyển khoản Model xuất Excel Kết quả xuất file

Xuất Excel danh sách đơn hàng nợ cước của khách hàng

Model xuất Excel Kết quả xuất file

Dịch vụ xuất Excel phiếu chuyển khoản

Xuất Excel danh sách phiếu chuyển khoản

Xuất Excel chi tiết phiếu chuyển khoản

Lấy dữ liệu phiếu chuyển khoản

Lấy dữ liệu chi tiết phiếu chuyển khoản

Tạo ExcelPackage danh sách phiếu chuyển khoản

Tạo ExcelPackage chi tiết phiếu chuyển khoản

Thêm thông tin công ty vào đầu worksheet

Thêm thông tin chung phiếu chuyển khoản

Thêm chi tiết đơn hàng

Lấy địa chỉ gửi

Lấy địa chỉ nhận

Lấy thông tin sản phẩm

Lấy thông tin tài chính đơn hàng

Định dạng worksheet chi tiết phiếu chuyển khoản

Thiết lập header cho danh sách phiếu chuyển khoản

Điền dữ liệu danh sách phiếu chuyển khoản

Định dạng worksheet danh sách phiếu chuyển khoản

Lấy mô tả trạng thái

Lấy mô tả mức độ ưu tiên

Xuất Excel danh sách đơn hàng nợ cước của khách hàng

Lấy dữ liệu đơn hàng nợ cước của khách hàng

Tạo ExcelPackage danh sách đơn hàng nợ cước của khách hàng

Thêm thông tin công ty vào đầu worksheet cho đơn hàng nợ cước

Thêm thông tin khách hàng

Thêm chi tiết đơn hàng nợ cước

Định dạng worksheet danh sách đơn hàng nợ cước

Service quản lý hóa đơn thanh toán chuyển khoản

Tìm kiếm khách hàng có đơn hàng cần tạo hóa đơn thanh toán chuyển khoản

Lấy danh sách đơn hàng có thể tạo hóa đơn thanh toán của khách hàng

Tạo hóa đơn thanh toán chuyển khoản

Tính mức độ ưu tiên dựa trên ngày tạo đơn hàng cũ nhất

Generate mã hóa đơn không trùng lặp với retry logic

Tìm kiếm danh sách hóa đơn thanh toán chuyển khoản

Lấy chi tiết hóa đơn thanh toán theo ID

Hủy hóa đơn thanh toán chuyển khoản với thông tin chi tiết

Hủy hóa đơn thanh toán chuyển khoản (phương thức cũ - deprecated)

Duyệt hóa đơn thanh toán chuyển khoản

Service quản lý tài khoản ngân hàng người dùng

Tìm kiếm tài khoản ngân hàng người dùng

Lấy thông tin chi tiết tài khoản ngân hàng theo ID

Tạo mới hoặc cập nhật tài khoản ngân hàng

Xóa tài khoản ngân hàng

Lấy danh sách tài khoản ngân hàng của người dùng

ID người dùng Danh sách tài khoản ngân hàng

Tìm kiếm tài khoản ngân hàng của người dùng cụ thể

Tham số tìm kiếm ID người dùng Kết quả tìm kiếm

Lấy tài khoản ngân hàng theo ID và kiểm tra quyền sở hữu

ID tài khoản ngân hàng ID người dùng Thông tin tài khoản ngân hàng

Xóa tài khoản ngân hàng với kiểm tra quyền sở hữu

ID tài khoản ngân hàng ID người dùng ID người cập nhật Tên người cập nhật Kết quả của thao tác

Interface cho service quản lý thẻ xăng dầu (thẻ tín dụng)

Tìm kiếm thẻ xăng dầu với phân trang

Lấy thẻ xăng dầu theo ID

Lấy thẻ xăng dầu theo QR Code

Tạo hoặc cập nhật thẻ xăng dầu

Xóa thẻ xăng dầu

Lấy danh sách thẻ đang hoạt động

Lấy tổng nợ thẻ tín dụng chưa thanh toán cho ngân hàng

Tìm kiếm thẻ xăng dầu cho autocomplete (SugFuelCard)

Lấy lịch sử thẻ xăng dầu

Lấy thẻ xăng dầu mà lái xe đang được gán (bao gồm cả PendingAccept)

Lái xe xác nhận nhận thẻ (kèm ảnh minh chứng)

Lái xe trả thẻ (kèm ảnh minh chứng)

Tính lại nợ hiện tại cho thẻ dựa trên sao kê và giao dịch chưa thanh toán. Đây là single source of truth cho công thức tính nợ. Gọi method này sau mỗi mutation (import/delete/update transaction, pay statement).

Service quản lý thẻ xăng dầu (thẻ tín dụng)

Tìm kiếm thẻ xăng dầu cho autocomplete

Tạo record bàn giao thẻ mới (PendingAccept)

Đóng handover đang active (PendingAccept/Received) cho thẻ

Upload ảnh bàn giao thẻ (pattern giống TruckActivityService.ProcessActivityMedia)

Tính lại nợ hiện tại cho thẻ dựa trên sao kê và giao dịch chưa thanh toán. Công thức: CurrentDebt = (Nợ từ các kỳ sao kê chưa trả hết) + (Chi tiêu chưa gắn kỳ sao kê chưa trả NH)

Interface cho service quản lý giao dịch thẻ tín dụng xăng dầu

Import sao kê thẻ tín dụng từ Excel

Tìm kiếm giao dịch thẻ

Lấy chi tiết giao dịch

Đối soát giao dịch thẻ với lần đổ dầu

Đánh dấu đã thanh toán cho ngân hàng

Import lịch sử giao dịch thẻ xăng dầu từ Excel. Tự động mapping thẻ dựa vào số thẻ trong file.

Lấy danh sách giao dịch chưa đối soát theo thẻ và ngày

Xóa giao dịch thẻ

Xóa nhiều giao dịch thẻ cùng lúc

Cập nhật giao dịch thẻ

Service quản lý giao dịch thẻ tín dụng xăng dầu

Import lịch sử giao dịch thẻ xăng dầu từ file Excel. Tự động mapping thẻ dựa vào cột "Tài khoản thẻ/ Số thẻ".

True nếu file dùng format VPBank (2 cột Ghi có / Ghi nợ riêng)

Parse số tiền từ 2 cột Ghi có / Ghi nợ riêng biệt (VPBank format) Ghi nợ = chi tiêu (trả về âm), Ghi có = thanh toán NH (trả về dương)

Parse số tiền từ text (xử lý VND suffix, thousand separators, etc.)

Xóa nhiều giao dịch thẻ cùng lúc

Interface cho dịch vụ xuất Excel lịch sử đổ dầu

Xuất Excel lịch sử đổ dầu

Tham số tìm kiếm và sắp xếp Kết quả xuất file

Dịch vụ xuất Excel lịch sử đổ dầu

Xuất Excel lịch sử đổ dầu

Lấy dữ liệu lịch sử đổ dầu (không phân trang)

Tạo ExcelPackage

Thiết lập header

Điền dữ liệu

Định dạng worksheet

Luật "ai thấy nút nào" của màn Lịch sử đổ dầu (/lich-su-do-dau).

Hàm thuần — không chạm database, không đọc HttpContext: nhận danh sách role đã phân giải qua IUserRoleResolver, trả các cờ. Controller thì không test được sạch vì User.GetCurrentUser() nuốt mọi ngoại lệ rồi trả UserId = 0. Mỗi cờ đọc đúng role của endpoint nó gác, cộng Founder. Đổi role trên một endpoint mà quên cờ là test FuelRefillNavPermissionsTests đỏ (đọc [Authorize(Roles)] thật bằng reflection). Cờ chỉ gác lời gọi chính của nút. Lời gọi phụ trong hộp thoại (form sửa cần Truck.GetLastRefillOdo, hộp thoại Duyệt cần FuelCard.GetUnreconciledTransactions) được cấp kèm theo nhóm quyền ở migration 202610281400 — gán role tay cho người dùng thì nhớ gán đủ bộ.

Vai bỏ qua mọi kiểm tra role của hệ thống — ẩn nút của Founder là dựng hàng rào không có thật.

Role đã phân giải qua IUserRoleResolver; null hoặc rỗng = không có role nào

Cờ hiển thị của màn Lịch sử đổ dầu — mỗi cờ gác đúng một nhóm nút (xem )

Hiện nút "Duyệt" và "Từ chối" ở phiếu chờ duyệt Hiện nút "Bỏ duyệt" ở phiếu đã duyệt Hiện nút "Đổ dầu mới" và "Cập nhật" Hiện nút "Xóa" Hiện nút "Xuất Excel"

Cờ hiển thị của màn Lịch sử đổ dầu — mỗi cờ gác đúng một nhóm nút (xem )

Hiện nút "Duyệt" và "Từ chối" ở phiếu chờ duyệt Hiện nút "Bỏ duyệt" ở phiếu đã duyệt Hiện nút "Đổ dầu mới" và "Cập nhật" Hiện nút "Xóa" Hiện nút "Xuất Excel"

Hiện nút "Duyệt" và "Từ chối" ở phiếu chờ duyệt

Hiện nút "Bỏ duyệt" ở phiếu đã duyệt

Hiện nút "Đổ dầu mới" và "Cập nhật"

Hiện nút "Xóa"

Hiện nút "Xuất Excel"

Interface cho service quản lý việc đổ dầu

Tạo hoặc cập nhật thông tin đổ dầu

Lái xe đổ dầu - Upload ảnh và tự động tính chênh lệch định mức khoán

Tìm kiếm lịch sử đổ dầu

Lấy chi tiết lần đổ dầu

Lấy lịch sử đổ dầu theo xe

Lấy lịch sử đổ dầu theo lái xe

Cập nhật thông tin đổ dầu

Xóa bản ghi đổ dầu

Đổ dầu cho lái xe trên app mobile. Tự động xác định xe từ CurrentDriverId, lấy PreviousOdo từ LastRefillOdo.

Tìm kiếm lịch sử đổ dầu theo lái xe (có phân trang, lọc ngày, từ khóa)

Duyệt phiếu đổ dầu (thực hiện reconcile + UpdateLastRefillOdo + tạo Expense nếu tiền mặt)

ID phiếu đổ dầu ID giao dịch thẻ xăng để đối soát (bắt buộc khi đổ bằng thẻ) Người dùng hiện tại (admin)

Từ chối phiếu đổ dầu

Bỏ duyệt phiếu đổ dầu đã duyệt (chưa chốt lương): đưa về chờ duyệt và gỡ đối soát giao dịch thẻ

Lái xe chỉnh sửa và gửi lại phiếu đổ dầu bị từ chối

Lái xe xóa phiếu đổ dầu (chỉ khi Pending hoặc Rejected)

Service quản lý việc đổ dầu với tính toán định mức khoán

Xác định PreviousOdo cho một phiếu đổ dầu dựa trên chuỗi phiếu của xe. Ưu tiên: CurrentOdo của phiếu gần nhất cùng xe (chưa bị từ chối, chưa xóa) có (RefillTime, Id) đứng ngay trước phiếu hiện tại. Nếu không có phiếu trước → lấy CurrentOdo của bản ghi nhận xe (CheckIn) gần nhất có thời điểm <= RefillTime. Nếu vẫn không có → 0.

ID xe Thời điểm đổ dầu của phiếu hiện tại ID phiếu hiện tại (loại khỏi truy vấn, dùng khi sửa)

Tính lại số liệu suy ra (DistanceKm, QuotaLiters, DifferenceLiters) cho một phiếu từ PreviousOdo mới. Không ghi DB — chỉ cập nhật entity in-memory.

Tính lại chuỗi phiếu đổ dầu của một xe từ một mốc thời gian trở đi. Vì PreviousOdo của mỗi phiếu phụ thuộc CurrentOdo của phiếu liền trước, nên khi thêm/sửa/xóa/từ chối một phiếu, các phiếu liền sau cần được tính lại theo dây chuyền. Quy tắc khóa lương: phiếu có IsPayrollLocked = true sẽ được BỎ QUA (không sửa), nhưng vẫn dùng CurrentOdo của nó làm mốc cho phiếu kế tiếp (theo quyết định nghiệp vụ).

ID xe cần tính lại Mốc thời gian bắt đầu tính lại (thường là RefillTime của phiếu vừa thay đổi) Người dùng thực hiện (đóng dấu UpdatedBy lên các phiếu được tính lại) ID phiếu bỏ qua khi ghi lại (phiếu vừa được tính/ghi ở nơi gọi) — vẫn dùng làm mốc

Đổ dầu cho lái xe trên app mobile. Tự động xác định xe, lái xe, PreviousOdo.

Tìm kiếm lịch sử đổ dầu theo lái xe (có phân trang, lọc ngày, từ khóa) Lái xe có thể lái nhiều xe khác nhau nên lọc theo DriverId

Cập nhật thông tin đổ dầu

Handle transaction reconciliation changes when creating or updating fuel refill

Duyệt phiếu đổ dầu: reconcile transaction, UpdateLastRefillOdo, tạo Expense nếu tiền mặt

Tạo Expense tự động cho phiếu đổ dầu tiền mặt (CreatedBy = lái xe)

Từ chối phiếu đổ dầu

Bỏ duyệt phiếu đổ dầu: đưa phiếu đã duyệt về chờ duyệt để sửa sai sót (nhầm tiền mặt / thẻ dầu, chọn nhầm giao dịch thẻ, sai ODO) rồi duyệt lại.

Gỡ đối soát giao dịch thẻ đang gắn với phiếu. Hộp thoại duyệt chỉ liệt kê giao dịch có FuelRefillId == null, và lúc duyệt giao dịch còn IsReconciled sẽ bị chặn là "đã đối soát với lần đổ dầu khác" — giữ liên kết cũ thì không chọn lại được chính giao dịch ấy, còn khi đổi sang tiền mặt thì giao dịch bị treo ở trạng thái đã đối soát với một phiếu không còn dùng thẻ. Không cần tính lại chuỗi ODO: phiếu chờ duyệt vẫn nằm trong chuỗi (chỉ phiếu từ chối bị loại), nên PreviousOdo của các phiếu liền sau không đổi. Thu nhập dầu trong kỳ lương chỉ đếm phiếu đã duyệt, nên phiếu đã chốt lương thì không được bỏ duyệt — giống quy tắc chặn sửa/xóa.

Lái xe chỉnh sửa và gửi lại phiếu đổ dầu bị từ chối → Pending

Lái xe xóa phiếu đổ dầu (chỉ khi Pending hoặc Rejected)

Công thức thuần quy đổi giờ làm của MỘT CA chấm công (giờ thô, chưa làm tròn) thành công / kíp. Nguồn sự thật duy nhất, dùng chung cho tính lương (PayrollService) và chi tiết chấm công (AttendanceService.GetAttendanceDetailByUserAsync).

Đầu vào bắt buộc là giờ THÔ của TỪNG CA. Áp ngưỡng lên số giờ đã gộp theo ngày hoặc đã làm tròn (như cột WorkingHours DECIMAL(10,1) của sp_GetAttendanceDetailByUser) sẽ cho kíp dư: các ngưỡng là bội của 0,1h với so sánh >=, nên làm tròn 0,1h chỉ có thể đẩy giá trị sát dưới ngưỡng LÊN qua ngưỡng (ví dụ thật tháng 7/2026: ca 13,4789h bị tròn thành 13,5 → hiển thị 1 kíp trong khi lương tính 0 kíp). Đây chính là lỗi lệch kíp form phiếu lương vá ngày 2026-08-20.

Quy tắc tính công theo ngưỡng số giờ làm việc của một ca: > 8h → 1.0 công; >= 3h → 0.5 công; >= 2h → 0.25 công; còn lại → 0 công.

Quy tắc tính kíp theo ngưỡng số giờ làm việc của một ca: < 13.5h → 0 kíp; < 15h → 1 kíp; < 15.5h → 1.5 kíp; >= 15.5h → 2 kíp.

Giao diện cho dịch vụ chấm công.

Xử lý chấm công (Check-in hoặc Check-out) dựa trên trạng thái hiện tại.

Mô hình CheckInOutModel chứa thông tin chấm công. Kết quả chấm công với thông tin chi tiết.

Lấy thông tin chấm công hiện tại của người dùng (chưa check-out hoặc hôm nay)

ID người dùng Thông tin chấm công hiện tại

Gợi ý giờ chấm ra cho một ca, suy ra từ thời điểm giao/lấy hàng muộn nhất của lái xe kể từ khi ca bắt đầu. Dùng cho dialog chấm bù khi lái xe quên chấm ra.

ID lái xe. Thời điểm ca bắt đầu (giờ chấm vào). Kết quả gợi ý giờ ra (HasData + SuggestedTime).

Kiểm tra trước xem khoảng thời gian ca định ghi có chồng lấp ca chấm công nào đã có của cùng nhân viên hay không. Dùng cho FE cảnh báo sớm trong dialog chấm công thủ công và chấm ra bù, trước khi người dùng bấm lưu.

ID nhân viên. Giờ vào của ca định ghi (null nếu chỉ có giờ ra). Giờ ra của ca định ghi (null nếu ca còn mở). Id bản ghi cần loại trừ (chính bản ghi đang sửa). Kết quả kiểm tra trùng ca.

Quét và tự đóng toàn bộ ca treo (quên chấm ra) đã vượt ngưỡng giờ, không giới hạn cũ đến đâu. Dùng cho Hangfire job chạy cuối ngày. Mỗi ca được đóng bằng giờ hoạt động đơn hàng muộn nhất trong cửa sổ ca; ca không suy ra được giờ sẽ để nguyên cho admin sửa tay.

Số ca đã tự đóng được.

Tìm kiếm bản ghi chấm công theo điều kiện.

Tham số SmartTableParam. Kết quả tìm kiếm bản ghi chấm công.

Tìm kiếm lịch sử chấm công của chính một lái xe (ép theo userId, không đọc UserId từ client). Dùng cho DriverApp để tránh IDOR. Vẫn cho lọc khoảng ngày qua CheckInStart/CheckInEnd.

Tham số SmartTableParam (Pagination + Sort bắt buộc). ID lái xe hiện tại (lấy từ token, ép server-side). Kết quả tìm kiếm bản ghi chấm công của lái xe đó.

Tạo mới bản ghi chấm công.

Đối tượng Attendance. Bản ghi Attendance đã tạo.

Cập nhật bản ghi chấm công.

Đối tượng Attendance cần cập nhật. Bản ghi Attendance đã cập nhật.

Xoá mềm một bản ghi chấm công (chỉ Founder được gọi — chặn ở controller). Bản ghi biến mất khỏi mọi đường đọc qua Query() (danh sách, chống trùng ca, tính lương) và khỏi hai stored procedure tổng hợp công; ảnh chấm công giữ nguyên để còn đối chiếu/khôi phục.

Id bản ghi chấm công. Id người xoá (đóng dấu UpdatedBy). Tên đăng nhập người xoá (đóng dấu UpdatedByUserName). Kết quả xử lý.

Lấy thông tin bản ghi chấm công theo Id.

Id bản ghi chấm công. Bản ghi Attendance nếu tìm thấy, ngược lại null.

Xuất danh sách chấm công ra file Excel.

Tham số SmartTableParam. Đường dẫn file Excel. Kết quả xuất file.

Lấy tổng hợp số công của tất cả nhân viên theo tháng

Tháng (1-12) Năm (ví dụ: 2025) Danh sách tổng hợp số công của nhân viên

Lấy chi tiết công từng ngày của một nhân viên theo tháng

Tháng (1-12) Năm (ví dụ: 2025) ID nhân viên Danh sách chi tiết công từng ngày

Tạo mới hoặc cập nhật bản ghi chấm công thủ công (bổ sung khi lái xe/nhân viên quên chấm vào/ra). Giờ vào và giờ ra được xử lý độc lập.

Thông tin chấm công thủ công. Kết quả xử lý.

Chấm ra bù cho một bản ghi chấm công chưa có giờ ra (admin thao tác hộ khi lái xe quên chấm ra). Cho phép đính kèm ảnh ODO bù. Hỗ trợ ca qua đêm (giờ ra có thể sang ngày hôm sau).

Thông tin chấm ra bù (kèm ảnh ODO tùy chọn). Kết quả xử lý.

Import bảng chấm công từ file Excel (máy chấm công vân tay). Map nhân viên qua mã chấm công (AttendanceCode).

Luồng dữ liệu file Excel. Tên file. ID người thực hiện import. Tên đăng nhập người thực hiện import. Kết quả import với thống kê dòng xử lý/lỗi/bỏ qua.

Triển khai dịch vụ chấm công.

Số giờ tối đa của một ca làm việc hợp lệ. Ca dài nhất theo nghiệp vụ là 8h sáng → 2h đêm hôm sau (~18h), lấy ngưỡng 20h để có biên an toàn. Nếu ca mở vượt ngưỡng này → coi như quên chấm ra. (Có thể chuyển sang appsettings/config sau nếu cần.)

Dấu vết người sửa cho ca treo được tự đóng bằng giờ hoạt động đơn hàng suy ra được.

Dấu vết người sửa cho ca treo bị đóng bằng CHÍNH GIỜ VÀO vì không có căn cứ nào để suy giờ ra. Tách khỏi để HR lọc ra đúng những ca cần chấm bù.

Xử lý chấm công (Check-in hoặc Check-out) dựa trên trạng thái hiện tại.

Chấm công vào (Check-in) với mô hình CheckInOutModel.

Chấm công ra (Check-out) với mô hình CheckInOutModel.

Tìm kiếm bản ghi chấm công theo điều kiện.

Tham số SmartTableParam. Kết quả tìm kiếm bản ghi chấm công.

Tìm kiếm bản ghi chấm công của một lái xe cụ thể (dùng cho DriverApp). UserId được ép ở tầng service, không đọc từ client để tránh IDOR.

Tham số SmartTableParam (chỉ đọc Pagination + lọc khoảng ngày CheckInStart/CheckInEnd). ID lái xe hiện tại (lấy từ token ở controller). Kết quả tìm kiếm bản ghi chấm công của chính lái xe đó.

Tạo mới bản ghi chấm công.

Đối tượng Attendance. Bản ghi Attendance đã tạo.

Cập nhật bản ghi chấm công.

Đối tượng Attendance cần cập nhật. Bản ghi Attendance đã cập nhật.

Xoá mềm một bản ghi chấm công. Xem mô tả ở .

Xoá mềm, không xoá cứng — theo nếp chung của Repository.DeleteAsync. Mọi đường đọc chấm công trong code (SearchAsync, FindOverlappingShiftAsync, PayrollService.BuildPayrollRecord, job đóng ca treo) đều đi qua Query() nên tự bỏ qua bản ghi này. Hai stored procedure sp_GetAttendanceDetailByUser / sp_GetAttendanceSummaryByMonth đọc thẳng bảng nên phải lọc IsDeleted = 0 (migration M202608191000_LocXoaMemTrongSpBaoCaoChamCong). Không chặn theo kỳ lương đã trả. EmployeePayrollRecord trạng thái Paid là ảnh chụp (CreateOrUpdate chặn ghi đè) nên tiền đã trả không đổi; kỳ Draft sẽ ra số công mới khi tính lại — đúng ý đồ của người xoá. Đường sửa () cũng không chặn, xoá không nên khắt khe hơn sửa. Tìm bằng Query() thay vì GetByIdAsync: bản ghi đã xoá mềm phải trả "không tìm thấy" (không xoá hai lần), và bệ test RecordingRepository không cài GetByIdAsync.

Lấy thông tin bản ghi chấm công theo Id.

Id bản ghi chấm công. Bản ghi Attendance nếu tìm thấy, ngược lại null.

Xuất danh sách chấm công ra file Excel.

Tham số SmartTableParam. Đường dẫn file Excel. Kết quả xuất file.

Lấy thông tin chi tiết của một bản ghi chấm công theo ID

ID của bản ghi chấm công Thông tin chi tiết của bản ghi chấm công

Lấy thông tin chấm công hiện tại của người dùng (chưa check-out hoặc hôm nay)

ID người dùng Thông tin chấm công hiện tại

Gợi ý giờ chấm ra cho một ca dựa trên thời điểm hoạt động đơn hàng (lấy/giao) muộn nhất của lái xe kể từ khi ca bắt đầu. Dùng cho dialog chấm bù công của admin.

ID lái xe. Thời điểm ca bắt đầu (giờ vào). Kết quả chứa giờ gợi ý và cờ có dữ liệu hay không.

Kiểm tra trước xem khoảng thời gian ca định ghi có chồng lấp ca chấm công nào đã có của cùng nhân viên hay không. Chỉ để FE cảnh báo sớm — hàng rào chặn thật vẫn nằm ở / / .

ID nhân viên. Giờ vào của ca định ghi (null nếu chỉ có giờ ra). Giờ ra của ca định ghi (null nếu ca còn mở). Id bản ghi cần loại trừ (chính bản ghi đang sửa). Kết quả kiểm tra trùng ca.

Cập nhật trạng thái hoạt động của xe mà người dùng đang phụ trách

ID người dùng Trạng thái hoạt động mới

Tìm thời điểm hoạt động đơn hàng (lấy/giao hàng) muộn nhất do chính lái xe thực hiện, TRONG CỬA SỔ [giờ vào ca, giờ vào ca + SHIFT_MAX_HOURS]. Dùng để suy ra giờ chấm ra khi lái xe quên chấm ra. Trả về null nếu không có hoạt động nào trong cửa sổ đó.

TRẦN THỜI GIAN LÀ HÀNG RÀO AN TOÀN, KHÔNG PHẢI TỐI ƯU TRUY VẤN. Trước 16/08/2026 hàm này chỉ chặn dưới (>= shiftStart): một ca treo từ 2025 vì thế được đóng bằng đơn hàng của 11 tháng sau, sinh ra 73 bản ghi dài tới 338 ngày trên production, tất cả mang dấu . Cửa sổ 20h chính là "thao tác đơn hàng cuối cùng của lái xe" theo đúng ý nghiệp vụ, chỉ khác ở chỗ không cắt ngang nửa đêm: đo trên 239 ca cần dọn (16/08/2026), luật theo ngày lịch suy được 196 ca còn cửa sổ 20h suy được 219 — 23 ca chênh lệch đều là ca đêm bị ngày lịch cắt đôi. ID lái xe. Thời điểm ca bắt đầu (CheckInTime). Trần cửa sổ, lấy từ .

Trần của cửa sổ suy giờ ra cho một ca: sớm hơn giữa giờ vào + SHIFT_MAX_HOURS và giờ vào của ca kế tiếp của cùng nhân viên.

VÌ SAO PHẢI CẮT TẠI CA KẾ TIẾP — nếu chỉ có trần 20h thì cửa sổ của hai ca treo liên tiếp CHỒNG NHAU, và một thao tác đơn hàng duy nhất đóng được cả hai ca. Ví dụ thật: lái xe tồn ca S1 vào 08:00 và ca S2 vào 20:00 cùng ngày, cả ngày chỉ có một lần giao hàng lúc 23:00. Không cắt thì S1 đóng lúc 23:00 (15h → 1 công + 1,5 kíp) và S2 cũng đóng lúc 23:00 (3h → thêm 0,5 công) — MỘT khối công việc được trả công hai lần. Tệ hơn, S1 (08:00–23:00) chồng lấn S2 (20:00–23:00), tức chính đường tự đóng lại đẻ ra cặp ca trùng mà đợt này đang dẹp. Đo trên DB dev 16/08/2026: 79/239 ca cần dọn có một ca kế tiếp nằm trong cửa sổ 20h, tức khoảng một phần ba. Với 6 lái xe của bảng §2.4 thì luật này KHÔNG đổi con số công/kíp nào (đã đối chiếu lại cả 12 ô), nhưng nó chặn được nguồn sinh ca chồng lấn cho phần còn lại. ID nhân viên. Giờ vào của ca đang cần suy giờ ra. Id bản ghi cần loại trừ (chính ca đang xét).

Tự đóng ca treo (quên chấm ra) bằng thời điểm hoạt động đơn hàng muộn nhất của lái xe. Nếu không suy ra được giờ nào (lái xe không có hoạt động đơn hàng sau khi vào ca) thì để nguyên ca treo cho admin xử lý thủ công. Trả về true nếu đã đóng được ca.

Bản ghi ca treo cần đóng.

Đóng DỨT ĐIỂM một ca treo theo luật chung của plan §6.6: ưu tiên giờ hoạt động đơn hàng muộn nhất trong cửa sổ ca; không có căn cứ nào thì đóng bằng CHÍNH GIỜ VÀO (ca 0 phút).

Vì sao ca 0 phút chứ không phải "độ dài ca mặc định": ca 0 phút cho 0 công và 0 kíp (PayrollService.CalculateWorkCredits / CalculateOvertimeKips) nên không bịa ra một đồng lương nào, mà bản ghi vẫn còn nguyên để HR lọc theo rồi chấm bù nếu lái xe thực sự có làm. Trước 16/08/2026, nhánh "không suy được giờ ra" để nguyên ca treo — mà vẫn mở ca mới ngay sau đó, nên ca mở tích tụ dần. Đó chính là cỗ máy sinh ra 166 ca treo / 28 người trên production, cá biệt một người tồn 33 ca mở cùng lúc. Bản ghi ca treo cần đóng.

Đóng dứt điểm MỌI ca treo (đã vượt ) của một nhân viên.

VÌ SAO ĐÓNG TẤT CẢ CHỨ KHÔNG CHỈ CA GẦN NHẤT: sau bản vá L3, hàng rào chống trùng nhìn thấy mọi ca còn mở bất kể cũ đến đâu. Chỉ cần sót lại một ca treo cũ là mọi lần chấm vào sau đó bị chặn — với người đang tồn 33 ca mở thì đóng nhỏ giọt mỗi lần bấm một ca đồng nghĩa người đó không chấm công được nữa. ID nhân viên. Số ca treo đã đóng.

Quét và tự đóng TOÀN BỘ ca treo (quên chấm ra) đã vượt ngưỡng giờ, không giới hạn cũ đến đâu. Giữ đúng một cận trên now - SHIFT_MAX_HOURS để không đụng ca đang chạy hợp lệ.

CẬN DƯỚI 48h ĐÃ BỊ BỎ (16/08/2026). Nó khiến job không bao giờ chạm được phần tồn cũ hơn 48h, nên 166 ca treo — cũ nhất từ 11/07/2025 — nằm lại vĩnh viễn. Bỏ được cận dưới là nhờ bản vá L1: giờ có trần 20h nên một ca treo từ 2025 không còn bị đóng bằng đơn hàng của năm sau. KHÁC BIỆT CÓ CHỦ ĐÍCH so với : job nền chỉ đóng ca SUY RA ĐƯỢC giờ, ca không có căn cứ thì để nguyên cho admin chấm bù. Đường chấm công thật thì buộc phải đóng hết (nếu không thì tích tụ ca mở và L3 sẽ chặn chính người đó), còn job nền không bị sức ép đó nên giữ thái độ dè dặt hơn — không tự tay tạo ca 0 phút hàng loạt sau lưng người vận hành. Số ca đã tự đóng được.

Tìm ca chấm công của cùng nhân viên bị CHỒNG LẤP thời gian với khoảng [start, end) đang muốn ghi. Đây là hàng rào chống chấm trùng dùng chung cho mọi đường ghi (chấm bù, sửa, chấm ra bù, chấm vào từ app, import Excel). Cố tình so theo khoảng thời gian thay vì theo ngày lịch: ca qua đêm (vd 20h → 4h hôm sau) nằm trên 2 ngày nên so ngày sẽ bỏ sót trùng. Hai ca giáp ranh (giờ ra ca trước == giờ vào ca sau) KHÔNG tính là trùng. Ca ĐÃ CHỐT chỉ được coi là chiếm dụng tối đa giờ kể từ giờ vào: một bản ghi rác dài 7 tháng (do nhập sai hoặc do auto-close hỏng) không được phép chặn mọi ca mới suốt 7 tháng. Ca CÒN MỞ chặn bất kể giờ vào cũ đến đâu — nhưng CHỈ khi người gọi bật , xem phần ghi chú.

TRƯỚC 16/08/2026 CẬN DƯỚI ÁP CHO CẢ HAI LOẠI, và đó là lỗi L3: ca treo cũ hơn 20h trở nên vô hình với hàng rào, nên thoải mái mở ca mới chồng lên nó. Cộng với lỗi L2 ở (không đóng nổi ca cũ mà vẫn mở ca mới), kết quả là 1.276 cặp ca chồng lấn chỉ trong tháng 7+8/2026. VÌ SAO LUẬT "CA CÒN MỞ CHẶN VÔ THỜI HẠN" CHỈ ÁP CHO . Bật nó cho mọi đường ghi thì khoá luôn công cụ dọn dẹp: một ca treo từ 11/07/2025 sẽ chặn mọi thao tác chấm bù / sửa / chấm ra bù cho người đó ở mọi ngày về sau, vì CheckInTime của nó nhỏ hơn mọi newEnd. Người đang tồn 33 ca mở còn tệ hơn — chỉ loại được đúng một bản ghi, nên 32 ca còn lại vẫn chặn chính thao tác đang định gỡ chúng. Đó là hồi quy, không phải hàng rào. thì khác: nó TẠO ca mới ở thời điểm hiện tại, đúng nơi ca treo phải giữ chỗ, và nó luôn được gọi sau khi đã dọn ca treo bằng — nên bật ở đây là hàng rào phòng thủ chiều sâu không tốn gì. Các đường của admin giữ luật trần 20h cũ: họ vẫn được cảnh báo bởi ca đã chốt và ca mở gần đây, chỉ không bị rác lịch sử khoá tay. ID nhân viên. Giờ vào của ca đang muốn ghi. Giờ ra của ca đang muốn ghi (null nếu ca còn mở). Id bản ghi cần loại trừ (chính bản ghi đang sửa). true: ca còn mở chặn bất kể cũ đến đâu — chỉ dùng cho . false (mặc định): ca còn mở cũng chỉ chiếm tối đa giờ, đúng luật trước đây — dùng cho mọi đường ghi của admin và cho API xem trước của FE. Bản ghi trùng đầu tiên tìm được, null nếu không trùng.

Dựng thông báo trùng ca theo NGÀY — đủ để người dùng biết ngày đó đã chấm công rồi. Ca qua đêm hiển thị cả 2 ngày để không gây nhầm.

Bản ghi chấm công bị trùng.

Lưu media cho attendance (check-in/check-out)

Model chứa thông tin attendance media Danh sách kết quả lưu media

Tạo mới hoặc cập nhật bản ghi chấm công thủ công (bổ sung khi quên chấm vào/ra). Giờ vào và giờ ra được xử lý độc lập. HỖ TRỢ CA QUA ĐÊM: FE gửi lên và là DateTimeOffset đầy đủ (đã ghép ngày+giờ ở FE, giờ ra có thể rơi vào ngày hôm sau). KHÔNG tự ghép giờ ra vào cùng ngày giờ vào ở backend — nếu làm vậy ca qua đêm sẽ có CheckOut < CheckIn và bị validate chặn nhầm. Validate chỉ so sánh trực tiếp 2 mốc datetime đầy đủ.

Chấm ra thủ công cho một bản ghi chưa có giờ ra (admin bổ sung hộ khi lái xe quên chấm ra), cho phép upload ảnh ODO bù. Hỗ trợ ca qua đêm (giờ ra có thể sang ngày hôm sau).

Import bảng chấm công từ file Excel (máy chấm công vân tay). Map nhân viên qua AttendanceCode. Cột: 1=Ngày (dd/MM/yyyy), 3=Họ tên, 4=Mã chấm công, 5=Giờ vào, 6=Giờ ra.

Parse chuỗi giờ dạng HH:mm:ss hoặc HH:mm sang TimeSpan.

Lấy tổng hợp số công của tất cả nhân viên theo tháng

Tháng (1-12) Năm (ví dụ: 2025) Danh sách tổng hợp số công của nhân viên

Lấy chi tiết công từng ngày của một nhân viên theo tháng

Tháng (1-12) Năm (ví dụ: 2025) ID nhân viên Danh sách chi tiết công từng ngày

Giao diện cho dịch vụ quản lý ứng viên.

Tìm kiếm ứng viên.

Thông số tìm kiếm. Kết quả tìm kiếm ứng viên.

Xóa ứng viên theo ID.

ID của ứng viên. Kết quả của thao tác.

Lấy thông tin đánh giá ứng viên theo ID.

ID của ứng viên. Thông tin đánh giá ứng viên.

Cập nhật thông tin đánh giá ứng viên.

Thông tin đánh giá ứng viên. Kết quả của thao tác.

Tạo ứng viên mới.

Thông tin ứng viên. Kết quả của thao tác.

Lấy thông tin ứng viên theo ID.

ID của ứng viên. Thông tin ứng viên.

Cập nhật thông tin ứng viên.

Thông tin ứng viên. Kết quả của thao tác.

Triển khai dịch vụ quản lý ứng viên.

Khởi tạo một thể hiện của .

Đối tượng IRepository của Candidate. Dịch vụ upload CV. Kho người dùng — tra tên người phụ trách tuyển. Hỏi kỳ KPI đã chốt chưa trước khi xoá mốc nhận việc (nợ KPI-7).

Tìm kiếm ứng viên.

Thông số tìm kiếm. Kết quả tìm kiếm ứng viên.

Gán tên người phụ trách tuyển cho từng dòng kết quả.

Candidate.RecruiterId không có navigation property tới User (bảng này chưa từng khai FK tới User), nên tra tên theo trang kết quả thay vì Include.

Gán người phụ trách tuyển cho hồ sơ. Trả về thông báo lỗi tiếng Việt nếu không gán được, null nếu hợp lệ (đã gán, hoặc cố ý không đụng tới).

Không xoá giá trị cũ khi client không gửi trường này. RecruiterId là int? nên "client không gửi" và "client muốn bỏ trống" đến service đều là null — không phân biệt được. Chọn giữ nguyên giá trị cũ, vì hướng nhầm còn lại làm mất dữ liệu. Đây không phải lo xa: bản đầu của GĐ B gán vô điều kiện candidate.RecruiterId = model.RecruiterId, mà màn đánh giá hồ sơ (review.vue) chỉ gửi {Id, Status, StatusContent} và lại là đường duy nhất trong SPA để chuyển hồ sơ sang "Nhận việc" ⇒ mỗi lần onboard là xoá trắng người phụ trách, khiến chỉ số hr.onboard-count luôn bằng 0 đúng vào lúc cần đếm. Review GĐ B bắt được (3/4 chiều độc lập cùng tìm ra), có ca test neo lại. Cũng kiểm luôn người được gán có thật và là nhân viên hay không: cột này là nguồn đếm của một chỉ số sẽ sinh tiền thưởng ở GĐ E, nhận Id rác vào thì số sai mà không ai thấy. Muốn bỏ trống người phụ trách thì làm qua một thao tác riêng, không đi bằng đường "quên gửi".

Đóng dấu mốc nhận việc khi trạng thái hồ sơ đổi.

Chỉ đóng dấu lần đầu chuyển sang : sửa hồ sơ về sau không được đẩy mốc sang kỳ khác, vì mốc này quyết định kỳ nào tính chỉ số hr.onboard-count. Chuyển ra khỏi Onboard (nhận việc hụt) thì xoá dấu để kỳ đó không còn đếm. Trừ khi kỳ chứa mốc đã chốt KPI — đây là chỗ trả nợ KPI-7. Vòng trạng thái Onboard → Rejected → Onboard xoá dấu cũ rồi đóng dấu mới theo thời điểm hiện tại, tức **dịch công của kỳ cũ sang kỳ đang chạy**. §3.4 đã chốt số kỳ đã chốt là snapshot bất biến, nên mốc nằm trong kỳ đã chốt thì đóng băng: trạng thái hồ sơ vẫn đổi bình thường, chỉ riêng cái mốc là bất động. Chốt lại kỳ trong cửa sổ cho phép vì thế ra đúng số cũ.

Xóa ứng viên theo ID.

ID của ứng viên. Kết quả của thao tác.

Lấy thông tin đánh giá ứng viên theo ID.

ID của ứng viên. Thông tin đánh giá ứng viên.

Cập nhật thông tin đánh giá ứng viên.

Thông tin đánh giá ứng viên. Kết quả của thao tác.

Tạo ứng viên mới.

Thông tin ứng viên. Kết quả của thao tác.

Lấy thông tin ứng viên theo ID.

ID của ứng viên. Thông tin ứng viên.

Cập nhật thông tin ứng viên.

Thông tin ứng viên. Kết quả của thao tác.

Cổng ghi sổ DUY NHẤT cho cọc trách nhiệm và tạm ứng lương. Mọi thay đổi UserPreference.ResponsibilityDepositPaid / SalaryAdvance phải đi qua service này (kèm Transaction vào ví Personal của lái xe) — các service khác không tự sửa hai field đó. Tiền vào đi qua luồng Income có duyệt; tiền ra (hoàn cọc, tạm ứng) đi qua Expense có duyệt.

Tạo YÊU CẦU tạm ứng lương — Expense Pending, chưa động vào số dư. Số dư chỉ thay đổi khi KT MarkAsPaid (hook gọi RecordAdvancePaidAsync).

Tạo YÊU CẦU hoàn cọc trách nhiệm — Expense Pending, chưa động vào số dư. Số dư chỉ thay đổi khi KT MarkAsPaid (hook gọi RecordRefundPaidAsync).

Ghi sổ khi Income cọc được xác nhận nhận tiền (gọi từ IncomeService.MarkAsReceived, trong DB transaction của luồng đó): Paid += amount + Transaction loại ResponsibilityDeposit.

Ghi sổ khi Expense hoàn cọc được chi tiền (gọi từ ExpenseService.MarkAsPaid, trong DB transaction của luồng đó): validate lại số dư, Paid -= amount + Transaction DepositRefund. Trả Failed nếu cọc hiện tại không đủ — caller phải rollback.

Ghi sổ khi Expense tạm ứng được chi tiền (gọi từ ExpenseService.MarkAsPaid, trong DB transaction của luồng đó): SalaryAdvance += amount + Transaction SalaryAdvance.

Ghi sổ khi NLĐ confirm phiếu lương có trừ cọc: Paid += amount + Transaction DepositFromPayroll. Gọi trong DB transaction của ConfirmPayrollAsync.

Ghi sổ khi NLĐ confirm phiếu lương có cấn trừ tạm ứng: SalaryAdvance -= amount (trừ đúng snapshot trên phiếu, KHÔNG reset về 0) + Transaction SalaryAdvanceFromPayroll. Gọi trong DB transaction của ConfirmPayrollAsync.

Hoàn tác ghi sổ của một phiếu lương đã Confirmed (khi KT sửa lại phiếu): Paid -= deposit, SalaryAdvance += advance, kèm Transaction điều chỉnh. Gọi trong DB transaction của luồng sửa phiếu.

Lấy lịch sử giao dịch cọc/tạm ứng của NV

Search giao dich cọc/tạm ứng cho trang quản trị

Lấy thông tin số dư cọc trách nhiệm + tạm ứng của NV

Cập nhật ví Personal của lái xe + ghi Transaction, dùng cho mọi giao dịch cọc/tạm ứng. Ví Personal đóng vai trò sổ phụ "tiền công ty đang giữ của lái xe": nộp cọc/trừ từ lương → Income (+), hoàn cọc/tạm ứng → Outcome (−).

Danh sách lái xe kèm trạng thái cọc (Hạn mức / Đã đóng / Đang chờ / Còn thiếu)

Số liệu tổng hợp cọc toàn công ty (theo scope agency của người xem)

Lấy tất cả cấu hình lương có hiệu lực giao cắt với kỳ lương (month/year). Dùng cho Frontend hiển thị danh sách config khi lập phiếu lương.

Giao diện cho dịch vụ quản lý bài đăng tuyển dụng.

Tìm kiếm công việc.

Thông số tìm kiếm. Kết quả tìm kiếm công việc.

Tạo hoặc cập nhật công việc.

Thông tin công việc. Kết quả của thao tác.

Lấy thông tin công việc theo ID.

ID của công việc. Thông tin công việc.

Xóa công việc theo ID.

ID của công việc. Thông tin người dùng hiện tại. Kết quả của thao tác.

Cập nhật trạng thái công việc.

Thông tin trạng thái công việc. Trạng thái mới của công việc. Kết quả của thao tác.

Gia hạn tin tuyển dụng.

Triển khai dịch vụ quản lý bài đăng tuyển dụng.

Khởi tạo một thể hiện của .

Đối tượng IRepository của JobPost. Đối tượng IRepository của Agency. Đối tượng IRepository của UrlRecord. Đối tượng IUrlRecordService. Dấu vân tay nội dung tin tuyển dụng. Hàng đợi báo URL cho công cụ tìm kiếm. Nhật ký.

Tạo hoặc cập nhật công việc.

Thông tin công việc. Kết quả của thao tác.

Tạo mới công việc.

Thông tin công việc. Kết quả của thao tác.

Xếp hàng báo URL của tin cho công cụ tìm kiếm, nếu lần sửa này đáng báo. Luật "lần sửa này đáng báo không, và báo loại gì" nằm ở — một hàm thuần, một nguồn duy nhất cho cả năm đường sửa tin (tạo, sửa, đổi trạng thái, gia hạn, xoá). Chỗ này chỉ còn việc nối luật ấy với hàng đợi. Không bao giờ làm hỏng thao tác lưu. Xếp hàng là việc phụ: một lỗi ở đây không được biến một lần lưu tin thành công thành thất bại dưới mắt người dùng.

Tin vừa lưu, đã nạp UrlRecord. Tin có đang được khai công khai trước lần sửa này không. Dấu vân tay nội dung có đổi ở lần sửa này không. Lần sửa này có phải là xoá tin không.

Cập nhật công việc.

Thông tin công việc. Kết quả của thao tác.

Xóa công việc theo ID.

ID của công việc. Thông tin người dùng hiện tại. Kết quả của thao tác.

Lấy thông tin công việc theo ID.

ID của công việc. Thông tin công việc.

Tìm kiếm công việc.

Thông số tìm kiếm. Kết quả tìm kiếm công việc.

Cập nhật trạng thái công việc.

Thông tin trạng thái công việc. Trạng thái mới của công việc. Kết quả của thao tác.

Gia hạn tin tuyển dụng: cập nhật StartDate, EndDate và chuyển về Opening.

Cập nhật thẻ bài viết

Danh sách thẻ bài viết. Người tạo. Tên người tạo. Danh sách thẻ đã cập nhật.

Trạng thái phiếu lương gần nhất của CHÍNH người gọi (userId lấy từ JWT ở controller) — thẻ "Phiếu lương tháng M" trên đầu Bảng tin (docs/plan-bang-tin-noi-bo.md §3.8, §3.16). Tách khỏi : chỉ đọc, một truy vấn, không kéo chi tiết thu nhập/khấu trừ như MyPayroll.

Phiếu kỳ mới nhất KHÁC Bản nháp (nhân sự còn đang làm — chưa gửi cho người lao động). Không ghi gì: trạng thái "đã chi" suy ra lúc đọc bằng — cùng hàm PayrollService dùng để ghi lại (trang phiếu lương mới là nơi ghi).

Lấy phiếu lương đang chờ xác nhận (PendingConfirmation) mới nhất cho NLĐ. Dùng cho Driver App — không cần truyền month/year.

KT gửi phiếu cho NLĐ xác nhận

NLĐ xác nhận → auto tạo Expense NLĐ từ chối → quay lại Draft

Khóa các phiếu đổ dầu đã dùng để tính thu nhập dầu của kỳ lương này. Gọi khi phiếu lương chuyển Confirmed — chốt cứng DifferenceLiters, tránh recalc chuỗi làm lệch snapshot FuelIncome đã trả cho NLĐ.

Mở khóa các phiếu đổ dầu đã bị kỳ lương này khóa. Gọi khi phiếu lương Confirmed bị mở lại về Draft (KT sửa) — chỉ mở đúng phiếu có LockedByPayrollId == payrollId, không đụng phiếu đã bị kỳ khác khóa. KHÔNG dùng cho phiếu lương Paid (khóa vĩnh viễn).

Preview tính lương cho 1 nhân viên — không lưu DB. Dùng cho chức năng "Tính trước" trên form lập phiếu lương. So sánh EffectiveFrom/To với kỳ lương (month/year) thay vì ngày hiện tại.

Quy tắc ở — nguồn sự thật duy nhất, dùng chung với chi tiết chấm công.

Quy tắc ở — nguồn sự thật duy nhất, dùng chung với chi tiết chấm công. Đầu vào là giờ THÔ của từng ca.

Tính doanh số ghi nhận (đã trừ VAT 8%) cho danh sách userIds trong kỳ. Dùng chung cho: cá nhân Sale, team TeamLeader, bưu cục BranchManager. Logic khớp với SP sp_GetOrderRevenueStatisticsBySale_Optimized (RecognizedRevenue).

Ranh giới kỳ đọc bằng .Month/.Year — EF dịch thành DATEPART trên chính giá trị lưu, mà cột Head*FeeTime lưu giờ Việt Nam +07:00, nên kỳ cắt đúng theo giờ Việt Nam. Đừng đổi sang so sánh với mốc DateTimeOffset dựng ở UTC: đó đúng là lỗi đã làm SP lệch 7 giờ so với hàm này (memory bay-mui-gio-cast-datetimeoffset, sửa bằng migration 202608161600).

Tính hoa hồng cá nhân dựa theo CommissionType (Flat hoặc Tiered).

Tính thuế TNCN theo biểu thuế lũy tiến từng phần 7 bậc (Luật Thuế TNCN Việt Nam). Sử dụng công thức tính nhanh (shortcut formula).

Tính số ngày hiệu lực thực tế của 1 cấu hình lương trong kỳ lương.

Tính lương pro-rata khi nhân viên có nhiều cấu hình lương trong cùng tháng. Lương CB, phụ cấp: chia theo số ngày hiệu lực của từng config. Chấm công: lọc theo khoảng ngày của từng config. Hoa hồng, doanh số: tính toàn tháng, áp dụng tỷ lệ config cuối cùng. BHXH: lấy mức cao nhất.

Lấy danh sách ID thành viên thuộc chi nhánh do userId quản lý. Ưu tiên: Agency.ManagerId → User.AgencyId. Fallback: User.ManagerId trực tiếp (khi chưa cấu hình AgencyId cho nhân viên).

Lấy chi tiết doanh số từng thành viên trong team/bưu cục. Dùng cho SaleTeamLeader (mode 4) và BranchManager (mode 5).

Luật trạng thái phiếu lương dùng chung — MỘT chỗ cho nơi ghi lại (PayrollService.SyncRecordStatusIfNeededAsync) và nơi chỉ đọc (, thẻ phiếu lương trên Bảng tin), để hai nơi không trôi khỏi nhau (review GĐ C bảng tin nội bộ).

"NLĐ đã xác nhận" mà phiếu chi tự tạo đã chi → "Đã thanh toán"; mọi trường hợp khác giữ nguyên.

Service interface for managing Permission Groups and Role assignments

Tạo Permission Group mới

Tên Permission Group Mô tả Danh sách Role ID Permission đã tạo

Cập nhật Permission Group

ID của Permission Tên mới Mô tả mới Danh sách Role ID mới Permission đã cập nhật

Xóa Permission Group

ID của Permission True nếu xóa thành công

Gán Permission cho User và tự động cập nhật UserRole

ID của User ID của Permission True nếu gán thành công

Xóa Permission khỏi User và xóa tất cả UserRole

ID của User True nếu xóa thành công

Lấy danh sách Permission

Danh sách Permission

Lấy Permission theo ID

ID của Permission Permission hoặc null

Lấy danh sách Role trong Permission

ID của Permission Danh sách Role

Kiểm tra User có quyền truy cập Role không

ID của User Tên Role cần kiểm tra True nếu có quyền

Tìm kiếm Permission với phân trang

Tham số tìm kiếm Kết quả tìm kiếm có phân trang

Lấy tất cả Roles có thể gán cho Permission

Danh sách tất cả Roles

Tạo hoặc cập nhật Permission (theo pattern AgencyController)

PermissionModel PermissionResult

Lấy Permission theo ID và chuyển về PermissionModel

ID của Permission PermissionModel

Cập nhật danh sách Role của Permission (hàm riêng biệt)

ID của Permission Danh sách Role ID mới PermissionResult

Service for migrating from old role naming convention to new Controller.Action pattern

Tạo tất cả Role mới theo pattern Controller.Action

Danh sách Role đã tạo

Tạo Permission Groups mặc định tương ứng với các vai trò cũ

Danh sách Permission đã tạo

Migration Users từ old roles sang Permission Groups

Số lượng User đã migration

Lấy danh sách Role mới cần tạo

Dictionary với key là role name, value là description

Lấy mapping từ old roles sang Permission Groups

Dictionary với key là old role, value là Permission Group name

Kiểm tra xem migration đã hoàn thành chưa

True nếu đã migration xong

Chạy full migration process

Migration result

Result of migration process

Service tái sử dụng: lấy toàn bộ Role names của user (kết hợp UserRole trực tiếp + Role từ Permission nếu có).

Service for managing Permission Groups and Role assignments

Service for migrating from old role naming convention to new Controller.Action pattern

Service tái sử dụng: lấy toàn bộ Role names của user (kết hợp UserRole trực tiếp + Role từ Permission nếu có). Kết quả được cache để giảm tải DB.

Giao diện cho dịch vụ quản lý người dùng.

Gợi ý người dùng dựa trên từ khóa và loại người dùng.

Từ khóa tìm kiếm. Loại người dùng. Tên vai trò (tùy chọn). ID người quản lý, chỉ lấy staff do manager này quản lý (tùy chọn). Danh sách Id người dùng được phép trả về (tùy chọn). Danh sách người dùng gợi ý.

Lấy phạm vi truy cập dữ liệu của người dùng.

ID của người dùng. Phạm vi truy cập dữ liệu.

Lấy Id các nhân viên do một người quản lý trực tiếp (không gồm chính người đó).

Id người quản lý. Danh sách Id nhân viên cấp dưới.

Tự động hoàn thành tìm kiếm người dùng dựa trên từ khóa và loại người dùng.

Từ khóa tìm kiếm. Loại người dùng. Danh sách người dùng gợi ý.

Tự động hoàn thành tìm kiếm người dùng dựa trên từ khóa và ID đại lý.

Từ khóa tìm kiếm. ID của đại lý. Danh sách người dùng gợi ý.

Lấy thông tin nhân viên theo ID.

ID của nhân viên. Thông tin nhân viên.

Lấy danh sách thông tin nhân viên theo danh sách ID.

Danh sách ID của nhân viên. Danh sách thông tin nhân viên.

Lấy ID của đại lý theo ID của nhân viên.

ID của nhân viên. ID của đại lý.

Lấy danh sách quyền của người dùng

ID của nhân viên. Danh sách quyền.

Lấy thông tin người dùng cần đăng nhập

Đổi mật khẩu cho người dùng

Thông tin đổi mật khẩu Kết quả đổi mật khẩu

Đặt lại mật khẩu theo quyền quản trị — KHÔNG cần biết mật khẩu cũ.

Khác : hàm đó đối chiếu cột User.Password (mật khẩu thô) làm mật khẩu hiện tại, nên chỉ chạy được với tài khoản nhân viên do backend này tạo ra. Tài khoản khách hàng đăng ký từ Lada.AppBackEnd luôn để cột đó rỗng, dùng đường kia sẽ hỏng. Ở đây sinh token đặt lại mật khẩu của Identity nên không phụ thuộc cột mật khẩu thô. Id tài khoản cần đặt lại mật khẩu. Mật khẩu mới. Người thực hiện, dùng để đóng dấu cập nhật. Kết quả đặt lại mật khẩu.

Tạo tài khoản đăng nhập kiểu khách hàng (UserType.Customer).

Tài khoản khách hàng không thuộc chi nhánh và không có nhóm quyền nội bộ, nên không dùng chung đường RegisterStaff — đường đó bắt buộc phải có AgencyId hợp lệ. Tên đăng nhập, mật khẩu và thông tin nhân thân lấy từ hồ sơ khách hàng. Người thực hiện. Kết quả tạo tài khoản, UserId là Id tài khoản vừa tạo khi thành công.

Triển khai dịch vụ quản lý người dùng.

Khởi tạo một thể hiện của .

Đối tượng IUserRepository của User.

Gợi ý người dùng dựa trên từ khóa và loại người dùng.

Từ khóa tìm kiếm. Loại người dùng. Tên vai trò (tùy chọn). Danh sách người dùng gợi ý.

Lấy phạm vi truy cập dữ liệu của người dùng.

Lấy Id các nhân viên do một người quản lý trực tiếp (không gồm chính người đó).

Tự động hoàn thành tìm kiếm người dùng dựa trên từ khóa và loại người dùng.

Từ khóa tìm kiếm. Loại người dùng. Danh sách người dùng gợi ý.

Tự động hoàn thành tìm kiếm người dùng dựa trên từ khóa và ID đại lý.

Từ khóa tìm kiếm. ID của đại lý. Danh sách người dùng gợi ý.

Lấy thông tin nhân viên theo ID.

ID của nhân viên. Thông tin nhân viên.

Lấy danh sách thông tin nhân viên theo danh sách ID.

Danh sách ID của nhân viên. Danh sách thông tin nhân viên.

Lấy ID của đại lý theo ID của nhân viên.

ID của nhân viên. ID của đại lý.

Lấy danh sách quyền của người dùng từ cả UserRole và PermissionRole

ID của nhân viên. Danh sách quyền.

Đổi mật khẩu cho người dùng

Thông tin đổi mật khẩu Kết quả đổi mật khẩu

Đổi mật khẩu cho người dùng

Thông tin đổi mật khẩu Kết quả đổi mật khẩu

Đặt lại mật khẩu theo quyền quản trị — không cần mật khẩu cũ.

Id tài khoản cần đặt lại mật khẩu. Mật khẩu mới. Người thực hiện. Kết quả đặt lại mật khẩu.

Tạo tài khoản đăng nhập kiểu khách hàng.

Tên đăng nhập, mật khẩu và thông tin nhân thân lấy từ hồ sơ khách hàng. Người thực hiện. Kết quả tạo tài khoản, UserId là Id tài khoản vừa tạo khi thành công.

Lấy tất cả roles của user từ cả UserRole và PermissionRole

User entity với UserRoles và Permission.PermissionRoles đã được Include Danh sách role names (không trùng lặp)

Service ghi và truy vấn lịch sử thao tác người dùng

Ghi 1 bản ghi lịch sử

Lấy lịch sử theo UserId

Lấy Description attribute của enum value

Người đang thao tác (đóng dấu audit + tra quyền).

Người đang thao tác (đóng dấu audit + tra quyền).

Ai được sửa bài nào: mức công ty sửa mọi bài; mức đơn vị chỉ sửa bài mình là tác giả (plan §3.4).

Chia người nhận chuông thành lô theo ĐỘ DÀI chuỗi id (Việc 0 §4.0 dòng "+"): SendToUsersAsync ghi string.Join(",", userIds) vào Notification.ScopeValue nvarchar(1024) — lô theo số người cố định (500) làm tràn cột và chuông của cả lô lỗi.

Người soạn bài Bảng tin nội bộ (plan §3.1–§3.7): thông tin bài, đối tượng, bản đang sửa, đăng / hẹn giờ / đăng lại / thu hồi / lưu trữ, ước tính người nhận, xem trước, và hai việc của job đăng theo lịch.

Hàng rào: controller gác role InternalNews.Manage | InternalNews.PublishAll; service kiểm PHẠM VI từng dòng đối tượng lúc lưu VÀ lúc đăng (§3.11 mục 4) và chỉ cho mức đơn vị sửa bài của chính mình. Bài ngoài phạm vi sửa trả 404 (không lộ tồn tại); vượt phạm vi đối tượng trả 403.

Nhóm quyền / đơn vị / loại đơn vị cho ô chọn đối tượng, đã lọc theo phạm vi người đăng.

Tìm người để chọn đích danh (≥ 2 ký tự, theo họ tên / tên đăng nhập, tối đa 20): nhân viên + người bưu cục còn sống, không đang khoá; mức đơn vị chỉ thấy người thuộc cây đơn vị mình quản lý.

Người nhận chuông của một bộ đối tượng + phạm vi bài: còn sống, không đang khoá, khớp resolver (KHÔNG cộng Founder).

Bản đang sửa đã lọc, cùng hình chi tiết người đọc — cho nút "Xem trước".

Bài hẹn giờ tới giờ → đăng (đúng đường đăng tay), cùng một phạm vi DI. Trả số bài đã đăng.

Id bài hẹn giờ đã tới giờ — job tách từng bài ra phạm vi DI riêng (một bài lỗi không kéo bài sau).

Đăng MỘT bài hẹn giờ đã tới giờ; không đủ điều kiện / mất quyền → về nháp. True = đã đăng.

Job: bài đã đăng quá ExpiresAt → lưu trữ. Trả số bài đã lưu trữ.

Người đóng dấu các lần ghi của job internal-news-schedule (đưa bài về nháp, tự lưu trữ).

Bài đang là nháp vì job tới giờ đăng mà không đăng được (người hẹn mất quyền, tệp / đích bị xoá, quá ngày tự lưu trữ) — đọc từ dấu người sửa cuối của job, tự tắt khi có người lưu bài lại (nợ BT-9: lý do cụ thể chỉ có ở log).

Người mức đơn vị không được sửa bài mà đối tượng HIỆN CÓ đã vượt phạm vi của mình (vd. người mức công ty mở rộng thành "Tất cả") — thông tin bài có hiệu lực ngay khi lưu, nên sửa tiêu đề cũng là sửa một bài toàn công ty.

Bài đang sửa (null = bài mới). Ngày tự lưu trữ chỉ bị kiểm khi người soạn ĐỔI nó — bài đã quá hạn / đã lưu trữ vẫn sửa được tiêu đề mà không phải xoá ngày cũ.

Phạm vi người đăng TRƯỚC (403), rồi mới tới đích có thật (nhóm / đơn vị / người còn sống), cuối cùng mâu thuẫn với phạm vi bài (400, §6.6): kiểm tồn tại trước thì người mức đơn vị dò được Id nào có thật ngoài phạm vi mình qua câu báo lỗi khác nhau (review GĐ A).

Đích đã tra cho luật mâu thuẫn phạm vi (§6.6): đơn vị còn sống được chọn (loại + tên) và người được chọn thuộc phía nhượng quyền — phân loại người bằng đúng của resolver, không viết lần hai.

Người nội bộ thuộc phía nhượng quyền theo luật §6.6 (khách hàng không thuộc phía nào — không thấy bài nào).

Kiểm từng khối theo hồ sơ bảng tin + tệp mà khối Video / Tài liệu tham chiếu phải THUỘC BÀI NÀY.

Kiểm lại TOÀN BỘ trước khi chụp, không tin lần lưu trước: ngày tự lưu trữ còn sau lúc lên bảng tin, đối tượng (có ≥ 1 dòng, đúng phạm vi người đăng LÚC NÀY), bộ khối (luật lưu + ≥ 1 khối + tệp còn thuộc bài), lọc HTML lần nữa.

Lúc bài lên bảng tin: bây giờ (đăng ngay / job) hoặc giờ hẹn.

Gửi chuông theo lô; lô lỗi thì DỪNG (thực thể Notification hỏng còn kẹt trong DbContext dùng chung làm mọi lô sau lỗi theo) và trả đúng số người đã nhận — nơi gọi nói được "đã gửi a/b", không nói sai là "chưa gửi".

Bộ khối đã lọc HTML lần nữa — đúng thứ sẽ vào ảnh chụp.

Dấu bản đang sửa: tính trên payload ĐÃ LƯU (không lọc lại) để hai lần đọc liền nhau luôn ra cùng dấu.

Tệp của bài mà các khối tham chiếu (người đọc chỉ nhận đúng các tệp này).

Chữ "Chỉ nhân viên LADA: Nhóm Kinh doanh · BC Hải Phòng (+đơn vị con)" / "Gồm cả bưu cục NQ: …" (512 ký tự) — tiền tố phạm vi để cột Đối tượng của danh sách nói đủ ai nhận (§6.6).

"Mọi bưu cục nhượng quyền" / "Mọi chi nhánh của LADA" — chỉ hạ chữ cái đầu của mô tả, không hạ cả chuỗi (từng ra "Mọi phòng ban của lada" ở ô chọn và tóm tắt đối tượng).

Phạm vi đăng của một người (plan §3.4, §3.13 mục 9, chốt §6.2). (role PublishAll hoặc Founder) đăng cho bất kỳ ai; chỉ thì chỉ đăng cho đơn vị trong (đơn vị đứng tên Agency.ManagerId + con cháu, cộng riêng đơn vị mình làm việc User.AgencyId) và người thuộc các đơn vị đó.

Đơn vị được chọn KÈM "gồm đơn vị con" — chỉ cây mình đứng tên. Đơn vị mình chỉ làm việc ở thì chọn được nhưng không kèm con: không có tập này thì tick "gồm đơn vị con" trên chính User.AgencyId phủ cả cây bên dưới (security review GĐ A). null = rỗng. Phạm vi bài mà người này BỊ ÉP (mức đơn vị, §5 câu 12c — ); null = được chọn. Máy chủ tự đặt lúc lưu, kiểm lại lúc đăng.

Phạm vi đăng của một người (plan §3.4, §3.13 mục 9, chốt §6.2). (role PublishAll hoặc Founder) đăng cho bất kỳ ai; chỉ thì chỉ đăng cho đơn vị trong (đơn vị đứng tên Agency.ManagerId + con cháu, cộng riêng đơn vị mình làm việc User.AgencyId) và người thuộc các đơn vị đó.

Đơn vị được chọn KÈM "gồm đơn vị con" — chỉ cây mình đứng tên. Đơn vị mình chỉ làm việc ở thì chọn được nhưng không kèm con: không có tập này thì tick "gồm đơn vị con" trên chính User.AgencyId phủ cả cây bên dưới (security review GĐ A). null = rỗng. Phạm vi bài mà người này BỊ ÉP (mức đơn vị, §5 câu 12c — ); null = được chọn. Máy chủ tự đặt lúc lưu, kiểm lại lúc đăng.

Đơn vị được chọn KÈM "gồm đơn vị con" — chỉ cây mình đứng tên. Đơn vị mình chỉ làm việc ở thì chọn được nhưng không kèm con: không có tập này thì tick "gồm đơn vị con" trên chính User.AgencyId phủ cả cây bên dưới (security review GĐ A). null = rỗng.

Phạm vi bài mà người này BỊ ÉP (mức đơn vị, §5 câu 12c — ); null = được chọn. Máy chủ tự đặt lúc lưu, kiểm lại lúc đăng.

Được chọn đơn vị này kèm "gồm đơn vị con" không.

Thấy lựa chọn phạm vi (Chỉ nhân viên LADA / Gồm cả bưu cục nhượng quyền) không.

Phạm vi thật sẽ lưu: bị ép thì lấy phạm vi ép (bỏ qua thứ gửi lên), không gửi thì giữ phạm vi đang có, bài mới mặc định LadaOnly (§5 câu 12a).

Đích đã tra từ DB cho luật mâu thuẫn phạm vi (): loại + tên các đơn vị được chọn còn sống, và các người được chọn thuộc phía nhượng quyền (tên hiển thị).

Đích đã tra từ DB cho luật mâu thuẫn phạm vi (): loại + tên các đơn vị được chọn còn sống, và các người được chọn thuộc phía nhượng quyền (tên hiển thị).

Kết quả kiểm các dòng đối tượng: = vượt phạm vi đăng (HTTP 403).

Kết quả kiểm các dòng đối tượng: = vượt phạm vi đăng (HTTP 403).

Luật đối tượng lúc LƯU và lúc ĐĂNG (plan §3.11 mục 4) — hàm thuần: kiểm từng dòng, không tin giao diện đã ẩn ô. Nháp lưu trước, đăng sau, quyền có thể đổi giữa hai lúc nên nơi gọi chạy lại khi đăng.

Chuẩn hoá: bỏ trùng, All không mang TargetId, IncludeChildren chỉ giữ cho Agency. Trả câu lỗi khi một dòng sai hình (loại lạ, thiếu đích).

Phạm vi của người đăng với TỪNG dòng, rồi với phạm vi bài (mức đơn vị bị ép — §5 câu 12c). : đơn vị của từng người được chọn đích danh (người không còn sống thì không có khoá).

Phạm vi bài bị ÉP cho người chỉ có mức đơn vị (§5 câu 12c), theo loại các đơn vị trong phạm vi đăng của họ: có cả đơn vị LADA lẫn bưu cục nhượng quyền (trưởng chi nhánh LADA có bưu cục NQ con) → được chọn (null); chỉ bưu cục NQ (chủ / trưởng bưu cục NQ) → IncludeFranchise, bài luôn đi trong bưu cục mình; chỉ LADA hoặc rỗng → LadaOnly. Mức công ty luôn được chọn.

Luật mâu thuẫn phạm vi (§6.6): bài LadaOnly mà chọn đích chỉ có ở phía nhượng quyền — đơn vị nhượng quyền, người thuộc nhượng quyền, loại đơn vị "Mọi bưu cục nhượng quyền" — thì bộ lọc phạm vi loại hết người của đích đó: báo rõ thay vì lặng lẽ gửi cho 0 người. Chạy SAU (403 trước — chống dò Id, §3.13).

Dòng đối tượng (entity) → model, để luật lúc đăng đọc đúng thứ đã lưu.

Model → dòng chưa lưu, dùng cho đếm người nhận theo đối tượng đang chọn (chưa lưu bài).

Một tệp đang tải lên — controller đóng gói từ IFormFile. phải seek được.

Một tệp đang tải lên — controller đóng gói từ IFormFile. phải seek được.

Tài liệu / video của bài bảng tin (plan §3.5, chốt §6.5): ghi vào KHO MEDIA CHUNG (Media.RootPath\Files\InternalNews\…), URL trên Media.Domain. Chỉ người sửa được bài (tác giả, hoặc mức công ty) mới tải lên / xoá tệp của bài đó.

Kiểm loại + magic bytes + kích thước, ghi đĩa RỒI MỚI ghi database; ghi database lỗi thì xoá tệp vừa ghi.

Xoá file vật lý TRƯỚC rồi mới xoá dòng: kho này công khai theo URL tới khi cổng media Enforce — file nằm lại sau khi dòng đã xoá là rò. Từ chối khi tệp đang được khối nội dung dùng (bản đang sửa hoặc bản đã đăng).

Câu từ chối khi tệp đang được khối dùng (bản đang sửa hoặc ảnh chụp người đọc đang thấy); null = xoá được.

Luật nhận tài liệu / video của bài bảng tin (plan §3.5): cùng whitelist, trần kích thước và phép nhận dạng bằng magic bytes của — GỌI LẠI chứ không chép, để hai miền không lệch nhau khi một bên vá lỗi nhận dạng. Tài liệu 30 MB pdf/xlsx/docx, video 300 MB mp4/webm.

Phần mở rộng trong whitelist của loại VÀ nội dung đúng định dạng đó; vị trí đọc trả về đầu.

Lỗi kho tệp bảng tin — là câu tiếng Việt hiển thị được.

Đường dẫn của tệp bảng tin trong KHO MEDIA CHUNG (chốt §6.5) — hàm thuần, có test chặn thoát thư mục. StoragePath lưu tương đối với Media.RootPath và LUÔN bắt đầu bằng ; URL = media domain + đúng đường dẫn đó, như mọi ảnh khác của hệ thống (ImageService.GetUrlBySystemPath).

Tiền tố cố định dưới Media.RootPath. Cổng media (đợt riêng) phải coi nó là vùng riêng tư.

Files/InternalNews/{yyyy}/{M}/{guid}.{ext} — tên do máy chủ sinh, không lấy tên gốc.

Đường dẫn tuyệt đối của một StoragePath, BẮT BUỘC nằm trong {mediaRoot}\Files\InternalNews\. Đường rỗng, tuyệt đối, có ổ đĩa, sai tiền tố hoặc thoát thư mục (..) → ném lỗi.

URL tuyệt đối trên media domain; domain trống → chuỗi rỗng (không bịa host).

Kho tài liệu / video bảng tin trên ổ đĩa, dưới Media.RootPath.

Ghi tệp mới (tên GUID); trả StoragePath tương đối + URL trên media domain. Ghi dở mà lỗi thì xoá tệp dở.

Xoá tệp vật lý. false = tệp không còn (không phải lỗi).

Lọc HTML của khối Đoạn văn bản trong bài bảng tin (plan §3.5) — chạy LÚC LƯU khối và LÚC CHỤP ảnh đăng; SPA render ảnh chụp bằng v-html nên đây là lớp duy nhất đứng giữa chữ người soạn gõ và trình duyệt người đọc.

Cho phép đúng thẻ TinyMCE của bảng tin sinh ra (đoạn, tiêu đề phụ h2–h4, danh sách, đậm/nghiêng/gạch chân, bảng, trích dẫn, xuống dòng, link http/https). Cấm hẳn img (ảnh chỉ đi qua khối Ảnh / Bộ ảnh — TinyMCE bảng tin tắt nút chèn ảnh), iframe (video đi qua khối Video), script, thuộc tính on*, style, class, data-*, scheme javascript:. Link luôn mở tab mới kèm rel="noopener noreferrer". Thẻ ngoài danh sách bị gỡ nhưng GIỮ chữ bên trong (dán từ Word ra <span style> không mất câu); thẻ chạy mã / nhúng bị bỏ cả ruột. Instance mới mỗi lượt (như ContentHtmlSanitizer) nên lớp bọc này đăng ký singleton được.

HTML đã lọc; đầu vào rỗng → chuỗi rỗng.

Payload khối ở dạng an toàn để lưu / chụp: khối Đoạn văn bản thay html bằng bản đã lọc; loại khác và payload không đọc được (validator sẽ báo lỗi) trả nguyên.

Thẻ chạy mã / nhúng: bỏ cả nội dung, không "giữ con".

Role của Bảng tin nội bộ (plan §3.4) và cờ cho giao diện — hàm thuần theo rule quyen-hien-thi: endpoint GET api/InternalNews/nav không đòi role, Founder được cộng vào mọi cờ, mặc định false.

Soạn / đăng bài cho người trong đơn vị mình quản lý (trưởng bưu cục, trưởng phòng).

Soạn / đăng bài cho bất kỳ ai (Nhân sự, Ban giám đốc).

Xem ai đã đọc / đã xác nhận (GĐ D).

Bó role gác MỌI action của InternalNewsAdminController, InternalNewsFileController và ảnh bảng tin.

Có cửa vào màn quản trị bảng tin (đúng bó , cộng Founder).

Cờ của người đang đăng nhập. là cây đơn vị người đó được đăng (chỉ có nghĩa khi CanManage mà không CanPublishAll) — giao diện dựng ô chọn đơn vị theo đây.

Phiên bản của bài mà người thao tác đã ĐỌC: trạng thái + UpdatedTime. Mọi lần ghi của store, và mọi lần lưu thông tin / khối, đều đổi UpdatedTime — nên điều kiện theo cặp này loại được cả "đọc cũ" (job chạy chồng, bấm đúp Đăng lại, hai tab) chứ không chỉ "khác trạng thái".

Phiên bản của bài mà người thao tác đã ĐỌC: trạng thái + UpdatedTime. Mọi lần ghi của store, và mọi lần lưu thông tin / khối, đều đổi UpdatedTime — nên điều kiện theo cặp này loại được cả "đọc cũ" (job chạy chồng, bấm đúp Đăng lại, hai tab) chứ không chỉ "khác trạng thái".

Ảnh chụp sắp ghi lúc đăng.

Lần đầu (ghi PublishedAt/By); ngược lại là Đăng lại (ghi RepublishedAt).

Ảnh chụp sắp ghi lúc đăng.

Lần đầu (ghi PublishedAt/By); ngược lại là Đăng lại (ghi RepublishedAt).

Lần đầu (ghi PublishedAt/By); ngược lại là Đăng lại (ghi RepublishedAt).

Ghi các cột trạng thái / xuất bản của bài bằng MỘT lệnh UPDATE … WHERE Id = @id AND Status = @s AND UpdatedTime = @t (plan §3.7): hai lần chạy chồng của job đăng theo lịch, job và người bấm tay, hay hai lần bấm đúp — chỉ một bên ghi được, bên kia nhận false và KHÔNG gửi chuông. Các cột này UpdateAsync không ghi được (InternalNewsPostMap.StateColumns). Lượt đọc cũng ghi ở đây cho nguyên tử. Tách store để service test được bằng repo giả (ExecuteUpdateAsync chỉ chạy trên EF thật), như TopicPublishStore.

Về Nháp: xoá ảnh chụp, bỏ lịch; GIỮ PublishedAt (đăng lại sau thu hồi không gửi chuông lần nữa).

Lưu trữ — chỉ theo trạng thái (job hết hạn đọc danh sách Id; lưu trữ không gửi chuông nên không sợ đọc cũ).

Ghi lượt đọc: lần đầu chèn, lần sau chỉ đổi LastReadAt; đặt AcknowledgedAt một lần và KHÔNG lần ghi nào xoá nó (hai tab đọc + xác nhận cùng lúc không mất xác nhận).

Người đọc Bảng tin nội bộ (plan §3.3, §3.8): feed, chi tiết, đánh dấu đã đọc, xác nhận "Tôi đã đọc và hiểu", số bài chưa đọc, cờ điều hướng. MỌI đường đọc đi qua đúng một lớp lọc — — và bài không được xem trả 404 (không lộ tồn tại, plan §3.11 mục 1).

Người đọc chỉ thấy bài Đã đăng (chưa quá ExpiresAt) và — khi lọc "Đã lưu trữ" — bài Đã lưu trữ; nội dung luôn là ảnh chụp lúc đăng, không bao giờ là bản đang sửa.

Feed theo : bộ lọc kind (số), unread (true), archived (true), keyword (tìm tiêu đề) trong Search.PredicateObject. Bài đang ghim lên đầu, rồi mới đăng trước.

Bài người xem được thấy — cùng một biểu thức cho feed lẫn đếm chưa đọc.

Bài đã đăng / đã lưu trữ mà người này được xem; ngược lại null (nơi gọi trả 404).

Mỗi người một dòng mỗi bài — ghi nguyên tử ở store (hai tab cùng ghi không mất xác nhận).

Giá trị hoặc lời từ chối (404 / 403 / 400) của một lời gọi thống kê.

Giá trị hoặc lời từ chối (404 / 403 / 400) của một lời gọi thống kê.

Tệp .xlsx trả thẳng cho trình duyệt — KHÔNG lưu vào kho media (site công khai theo URL).

Tệp .xlsx trả thẳng cho trình duyệt — KHÔNG lưu vào kho media (site công khai theo URL).

Bộ lọc danh sách người: status = unread (mặc định) | unacknowledged | all; agencyId 0 = "Không thuộc đơn vị".

Bộ lọc danh sách người: status = unread (mặc định) | unacknowledged | all; agencyId 0 = "Không thuộc đơn vị".

Thống kê đọc của Bảng tin nội bộ (plan §3.17, GĐ D): ai trong đối tượng hiện tại đã đọc / đã xác nhận, theo đơn vị, danh sách người chưa đọc, xuất Excel. Chỉ người có InternalNews.ViewStats (Founder cộng vào) — kiểm ở đây lần nữa dù controller đã gác role, để mọi đường gọi service đều qua cùng hàng rào.

Người nhắm KHÔNG có luật thứ hai: — cùng nguồn với chuông và "ước tính người nhận" (bỏ tài khoản xoá / đang khoá). ViewStats là quyền mức công ty: xem mọi bài đã từng đăng (PublishedAt có giá trị — gồm bài đã thu hồi về nháp); bài chưa đăng lần nào / không tồn tại → 404.

Ảnh chụp người nhắm + lượt đọc của một bài — hàng rào quyền và 404 nằm ở đây, một chỗ cho cả 3 lời gọi.

Phần tính thuần của thống kê đọc — nhóm theo đơn vị, xếp, lọc danh sách người (test không cần DB).

Theo đơn vị đang làm: nhiều người chưa đọc lên trước (người cần nhắc), cùng số thì theo tên; "Không thuộc đơn vị" cuối.

Đơn vị (không đơn vị cuối) rồi họ tên — cùng thứ tự cho màn và tệp Excel.

null = mọi đơn vị; 0 = chỉ người "Không thuộc đơn vị".

Tệp Excel của nút "Xuất Excel" ở dialog Thống kê. Hàm thuần, trả byte; mọi ô ghi dạng giá trị (không công thức) nên họ tên bắt đầu bằng = không thành công thức. Chỉ người nhắm của bài — người đọc ngoài đối tượng chỉ là con số.

Người đang xem bảng tin — dựng MỘT lần mỗi request bằng (plan §3.3). chỉ có khi đơn vị của người đó còn sống: người thiếu AgencyId hoặc có bưu cục đã xoá mềm (Việc 0 §4.0 dòng 2, 5) chỉ khớp được dòng Tất cả / Nhóm quyền / Cá nhân.

Tổ tiên của (không gồm chính nó), tối đa 10 cấp.

Người đang xem bảng tin — dựng MỘT lần mỗi request bằng (plan §3.3). chỉ có khi đơn vị của người đó còn sống: người thiếu AgencyId hoặc có bưu cục đã xoá mềm (Việc 0 §4.0 dòng 2, 5) chỉ khớp được dòng Tất cả / Nhóm quyền / Cá nhân.

Tổ tiên của (không gồm chính nó), tối đa 10 cấp.

Tổ tiên của (không gồm chính nó), tối đa 10 cấp.

Thuộc LADA theo ĐƠN VỊ (plan §6.6): nhân viên ở đơn vị LADA còn sống hoặc không có đơn vị sống. Người làm ở bưu cục nhượng quyền còn sống (tài khoản Nhân viên, BT-10) thì không; tài khoản Franchisee không bao giờ, kể cả khi mất đơn vị. Nhân viên có bưu cục NQ đã XOÁ MỀM thì coi như không đơn vị → tính là LADA (plan §3.15 mục 2 — đóng bưu cục mà không khoá tài khoản là việc của quản trị).

Cây Agency còn sống, nạp một lần mỗi request (13 đơn vị trên dev — Việc 0 §4.0 dòng 3). Duyệt giới hạn cấp và chống vòng: dữ liệu cha–con sai không được làm treo request.

Tổ tiên còn sống của , gần trước xa sau; không gồm chính nó.

Các gốc còn sống cùng mọi con cháu còn sống của chúng (tối đa cấp dưới gốc).

Luật "ai thấy bài nào" của Bảng tin nội bộ — ĐÚNG MỘT CHỖ (plan §3.3, §6.6). Viết thành biểu thức để cùng một luật chạy được cả trong SQL (feed, đếm chưa đọc: ) lẫn trong bộ nhớ (chi tiết, đánh dấu đọc, xác nhận, người nhận chuông, ước tính người nhận: / ) — không chép luật lần hai (bài học KpiVisibilityResolver).

Hai vế, cùng phải đúng (plan §6.6, thay §3.13 mục 1): khớp MỘT dòng đối tượng VÀ phạm vi bài cho qua (IncludeFranchise, hoặc người xem thuộc LADA theo đơn vị). "Tất cả" = mọi người nội bộ (Staff + Franchisee), phạm vi quyết LADA hay gồm nhượng quyền; bài LadaOnly loại người phía nhượng quyền kể cả khi họ khớp theo nhóm quyền (§5 câu 12b). Khách hàng (UserType.Customer) không bao giờ thấy bài nào. Founder thấy mọi bài đã đăng nhưng KHÔNG tự vào danh sách nhận chuông (chuông chỉ theo đúng đối tượng của bài).

Khoá so khớp của người xem, đã quy giá trị thiếu về -1: không id nào bằng -1, và tránh ngữ nghĩa so NULL của SQL. Kiểu int? để so thẳng với TargetId (nullable) trong cả SQL lẫn bộ nhớ.

LUẬT DÒNG — viết đúng một lần. Hai tham số để biên dịch MỘT lần cho fan-out, và gắn hằng người xem cho EF.

LUẬT PHẠM VI (§6.6) — không phụ thuộc dòng nên tách khỏi (trong SQL nó lọc trên bài), nhưng chỉ được dùng KÈM luật dòng, qua / .

Đơn vị (còn sống) loại này là của LADA; null = không đơn vị → tính là LADA (§6.6). Danh sách đóng: loại đơn vị mới thêm sau này mặc định KHÔNG phải LADA — bài LadaOnly không lọt sang đó khi chưa ai quyết.

Bài người xem được thấy — lối SQL DUY NHẤT (feed, đếm chưa đọc): luật phạm vi lọc trên bài, luật dòng lọc qua truy vấn con trên . Founder thấy mọi bài của .

Phạm vi cho qua VÀ có ít nhất một dòng đối tượng khớp (KHÔNG xét Founder) — tập người nhận chuông / ước tính.

Người xem đọc được bài (phạm vi + các dòng đối tượng) không. Bài không có dòng nào = chỉ Founder thấy.

Dựng người xem từ dữ liệu thô — đường duy nhất, dùng chung cho request đọc và cho fan-out chuông.

Dựng (người đọc) và (người đăng) cho Bảng tin nội bộ — đọc User + role (, role không nằm trong JWT) + cây Agency còn sống. Nơi DUY NHẤT dựng hai thứ này, để feed, chi tiết, đếm người nhận và kiểm phạm vi đăng đọc cùng một dữ liệu.

Hợp đồng tính giá trị thực (actual) của một chỉ số KPI, bám đúng pattern IWidgetDataProvider của khung Dashboard Widget.

Đăng ký DI bằng services.AddTransient<IKpiActualProvider, XxxProvider>(); resolve theo = KpiMetric.SourceCode. Provider **không** tự kiểm tra quyền — lớp gọi (service progress, job chốt kỳ) đã ép phạm vi trước khi tới đây. Provider cũng **không** tự bắt exception thành 0: ném ra để engine đánh dấu dòng lỗi, vì một chỉ số im lặng trả 0 sẽ thành "không đạt chỉ tiêu" rồi thành mất tiền thưởng.

Trùng KpiMetric.SourceCode — hằng khai ở

Loại chủ thể mà provider này phục vụ — engine chặn trước khi gọi nếu lệch

Chỉ số này là ảnh chụp tại một thời điểm hay là số cộng dồn cả khoảng.

Mặc định false — hầu hết chỉ số là số cộng dồn (đếm đơn, cộng tiền): giá trị của một khoảng dài bằng tổng các khoảng con, và chỉ tiêu quý bằng Σ chỉ tiêu các tháng. true cho chỉ số kiểu sales.active-customers: nó đếm khách hoạt động tại mốc ToDate theo cửa sổ trượt 3 tháng (§7.4), nên chạy trên khoảng quý ra "khách hoạt động tại cuối quý" chứ không phải tổng ba tháng. Với chỉ số như vậy, chỉ tiêu quý cũng KHÔNG được cộng dồn — giao 50 khách mỗi tháng thì mục tiêu quý vẫn là 50, không phải 150. Cộng dồn ở vế chỉ tiêu trong khi vế giá trị thực là ảnh chụp làm điểm quý chỉ còn khoảng 1/3 điểm thật, điểm năm còn 1/12 — sai một cách hệ thống. Đặt ở đây chứ không phải một danh sách mã cứng trong lớp tổng hợp: bản chất "ảnh chụp hay cộng dồn" là của chính cách provider tính, nên nó phải nằm cạnh phép tính đó.

Chỉ số này là tỷ lệ / bình quân (tử số ÷ mẫu số) hay là số đếm/cộng thẳng.

Mặc định false. true cho chỉ số kiểu driver.delivery-rate (đơn giao thành công ÷ đơn được giao) hay "đơn ÷ lái xe": không được cộng thẳng giá trị các tháng, cũng không lấy trung bình % — 200% trên mẫu số 10 cộng 50% trên mẫu số 1.000 không ra 125%. Tổng hợp quý/năm (§7.13) cộng tử số và mẫu số đã đóng dấu rồi chia. Provider khai true thì bắt buộc điền và — lúc chốt tháng chúng được đóng dấu vào KpiResult; thiếu thì lớp tổng hợp ghi rõ "thiếu tử/mẫu tháng X", không đoán, không coi là 0.

Tính giá trị thực của chỉ số trong khoảng ngày của ngữ cảnh

Ngữ cảnh tính giá trị thực.

Nhận **khoảng ngày** chứ không phải cặp năm/tháng (plan §3.4): kỳ tháng và màn theo dõi trong kỳ dùng khoảng ngày tuỳ ý. Tổng hợp quý/năm thì **không** gọi provider nữa (§7.13) — nó cộng từ snapshot KpiResult của các tháng đã chốt.

Loại chủ thể: nhân viên hay đơn vị

Id chủ thể — UserId khi Employee, AgencyId khi Agency

Đầu khoảng, tính cả mốc này

Cuối khoảng, tính cả mốc này (thường là cuối ngày)

Danh sách **đầy đủ** đơn vị phải gộp số khi chủ thể là đơn vị — **gồm cả chính chủ thể**.

Để trống là trường hợp thường gặp: provider agency.* tự hỏi (khu vực gộp con đệ quy, loại khác chỉ tính chính nó). Chỉ điền khi bên gọi thật sự muốn đè phạm vi, và khi đó **phải điền cả id của chính chủ thể** — điền thiếu là lặng lẽ bỏ rơi doanh số ghi thẳng vào node khu vực.

Tạo ngữ cảnh cho một kỳ tháng

Giá trị thực của một chỉ số kèm dữ liệu đối soát.

Giá trị thực đạt được trong khoảng

Breakdown để đối soát về sau — nguồn dữ liệu, khoảng ngày thật đã dùng, số thành phần. Ghi vào KpiResult.DetailJson lúc chốt kỳ.

Tử số của chỉ số dạng tỷ lệ (); null với chỉ số đếm/cộng thẳng. Đóng dấu vào KpiResult.Numerator lúc chốt tháng để tổng hợp quý/năm cộng tử–mẫu thay vì cộng %.

Mẫu số của chỉ số dạng tỷ lệ; xem

Kết quả của chỉ số dạng tỷ lệ: giá trị = tử ÷ mẫu (mẫu 0 ⇒ 0), kèm tử/mẫu để đóng dấu

Phân giải một chủ thể đơn vị thành danh sách đơn vị phải gộp số khi tính KPI.

**Nguồn duy nhất của luật gộp cây** (plan §7.2) — mọi provider agency.* hỏi lớp này thay vì tự đệ quy ParentId, để luật "khu vực gộp con, loại khác chỉ tính chính nó" chỉ tồn tại ở một chỗ. Cùng tinh thần với .

Danh sách AgencyId phải gộp cho một chủ thể đơn vị — **đã khử trùng lặp** và luôn chứa chính nó.

Ném khi không tìm thấy đơn vị: một chỉ số im lặng trả 0 sẽ thành "không đạt chỉ tiêu" rồi thành mất tiền thưởng (xem ), nên thà báo lỗi rõ ràng còn hơn trả tập rỗng.

Tổng hợp KPI quý/năm (plan §7.1) — tầng đọc của con người, không sinh tiền.

Luật §7.13 (chốt 2026-08-15, thay §3.4 cũ): điểm quý/năm CỘNG TỪ SNAPSHOT KpiResult CỦA CÁC THÁNG ĐÃ CHỐT — tuyệt đối không chạy lại provider. Hệ quả: điểm quý/năm luôn khớp với các con số tháng đã đóng dấu (thứ nghiệp vụ nhìn thấy trên phiếu lương) và bất biến khi dữ liệu gốc đổi sau khi tháng đã chốt (đơn huỷ, đơn sửa) — đúng tinh thần KpiResult là snapshot bất biến (nợ KPI-8, KPI-10). Cách "cộng" phụ thuộc bản chất chỉ số — quyết định bằng thuộc tính của chính provider (IsPointInTime, IsRatio), không phải danh sách mã cứng: Cộng dồn (số đơn, doanh số, onboard, khách mới): actual = Σ ActualValue, mục tiêu = Σ TargetValue của đúng các tháng đã chốt đó — target và actual cùng một tập tháng (bài học lỗi 2 GĐ D về lệch mẫu số). Ảnh chụp (sales.active-customers): actual và mục tiêu đều của tháng cuối cùng đã chốt trong kỳ, không Σ (bài học lỗi 1 GĐ D). Tỷ lệ / bình quân: không cộng thẳng ActualValue — cộng tử số và mẫu số đã đóng dấu rồi chia; mục tiêu = bình quân gia quyền theo mẫu số của mục tiêu các tháng (mục tiêu % cố định thì ra đúng chính nó). Tháng thiếu tử/mẫu (chốt trước khi có cột, hoặc nhập tay đè) ⇒ ghi rõ "thiếu tử/mẫu tháng X", không đoán, không coi là 0. Tháng chưa chốt không góp số — bảng chỉ mang nhãn "còn N tháng chưa chốt"; muốn xem tháng đang chạy thì dùng màn theo dõi trong kỳ. KpiPeriodicReviewService.Finalize từ chối khi UnclosedMonthCount > 0 (đóng KPI-11). ManualValue tự nhiên được tôn trọng vì KpiResult.ActualValue đã là giá trị cuối (nhập tay thắng lúc chốt).

Tổng hợp điểm KPI quý/năm của một chủ thể. Trả null khi chủ thể nằm ngoài phạm vi xem của người gọi (§3.6) — không phân biệt với "không có dữ liệu", chống dò IDOR.

Tham số tổng hợp quý/năm.

Quarter hoặc Year

Quý 1-4 khi PeriodType = Quarter; bỏ qua khi PeriodType = Year

Khoá tử/mẫu trong DetailJson cho tháng chốt trước khi có cột — provider dạng tỷ lệ ghi thêm hai khoá này vào breakdown để tổng hợp đọc lại được

Xem

Gộp target/actual của các tháng ĐÃ CHỐT theo bản chất chỉ số (§7.13).

Actual null nghĩa là chưa tính được — kèm Note nói rõ thiếu gì; không có nhánh nào trả 0 thay cho "không biết".

Tử/mẫu của một snapshot: ưu tiên cột đóng dấu; tháng chốt trước khi có cột thì đọc DetailJson theo khoá /.

Khoảng tháng của kỳ tổng hợp; trả (0, 0) khi tham số kỳ không hợp lệ

Phạm vi XEM theo §3.6 — hỏi đúng lớp , không chép luật

Tìm kiếm chỉ tiêu — không có Kpi.ViewAll/Founder thì server ép lọc về phạm vi của mình + cấp dưới trực tiếp + đơn vị mình quản lý (§3.6), không tin FE

Lấy chỉ tiêu theo Id — null nếu không tồn tại HOẶC ngoài phạm vi xem (không phân biệt, chống dò IDOR)

Giao/sửa một dòng chỉ tiêu — luật phạm vi §7.3 + validation §3.9c; Draft lưu lẻ dòng được, response kèm cảnh báo tổng trọng số (§7.8)

Xoá mềm chỉ tiêu — cùng luật phạm vi với quyền giao (§7.3), chặn khi kỳ đã chốt

Chuyển cả bộ chỉ tiêu của một chủ thể trong một kỳ sang Assigned — chặn cứng khi tổng trọng số ≠ 100%, báo rõ thiếu/thừa bao nhiêu (§7.8)

Copy bộ chỉ tiêu của một chủ thể từ kỳ nguồn sang kỳ đích (Draft) — bỏ qua metric đã có ở kỳ đích và metric đã ngừng hoạt động

Luật §7.3 — uỷ thác cho , nguồn duy nhất của luật.

Từ GĐ D luật này còn phục vụ chốt lại kỳ, nhập tay giá trị và đánh giá quý/năm; giữ một bản chép riêng ở đây là con đường để bốn đường thao tác lệch nhau dần (§3.10).

Chủ thể phải tồn tại và đang hoạt động (§3.9c): nhân viên là Staff chưa nghỉ, đơn vị ở trạng thái Hoạt động

Gán tên hiển thị cho SubjectName / AssignedByName — SubjectId đa hình nên không có navigation, tra tên theo trang kết quả (tối đa PageSize dòng)

Tên hành động ghi vào KpiAuditLog.Action — hằng để không có hai chỗ gõ khác nhau

Ghi dấu vết mọi thao tác đổi được tiền của phân hệ KPI (§3.10 — quyết định cách ghi là việc của GĐ E; chọn bảng riêng KpiAuditLog).

Ghi log không bao giờ được làm hỏng nghiệp vụ: hàm nuốt lỗi và chỉ LogError. Một dòng nhật ký không ghi được thì tiếc, nhưng để nó làm sập việc chốt kỳ của cả công ty thì tệ hơn hẳn. Ngược lại, thao tác nghiệp vụ phải ghi xong mới trả về Success — thứ tự gọi là "làm nghiệp vụ trước, ghi log sau, cùng một lượt request".

Ghi một dòng dấu vết. / là object bất kỳ, được serialize sang JSON — đừng truyền entity có navigation (vòng tham chiếu).

Quy điểm KPI tháng đã chốt thành tiền thưởng trên phiếu lương (plan §3.5, §7.14).

Không sửa công thức trong PayrollService (§3.5): chỉ thêm bản ghi PayrollAdjustment loại thưởng, phiếu lương tự cộng qua TotalBonuses như mọi adjustment khác. Bốn chốt chặn phải CÙNG đúng mới sinh tiền, thiếu một cái là không sinh gì và có lý do ghi rõ: Công tắc Kpi.EnableBonus bật (§5 GĐ E, mặc định TẮT). Kỳ chính thức — KpiResult.IsTrial = false (§7.9). Kỳ thử nghiệm không sinh gì kể cả khi công tắc bật. Nhân viên–tháng có dòng cấu hình KpiBonusSetting (§7.14). Mẫu bậc thang của dòng đó còn hiệu lực và có bậc phủ đúng điểm. Idempotent theo dòng cấu hình: adjustment mang KpiBonusSettingId, chốt lại kỳ thì CẬP NHẬT dòng cũ chứ không sinh trùng (cùng nguyên tắc KpiPeriodCloseService áp cho KpiResult theo AssignmentId). Dòng cấu hình không còn đủ điều kiện mà đã sinh tiền lần trước ⇒ gỡ khoản đó, nếu không tiền của một lần chạy cũ ở lại mãi. Bảng tính thử (dry-run) chạy được khi công tắc còn tắt — đó là thứ chủ dự án dùng để duyệt số ở §5.1 bước 4, trước khi bật công tắc.

Bảng tính thử: hiện tiền sẽ sinh cho một kỳ, KHÔNG ghi gì xuống PayrollAdjustment. Chạy được cả khi công tắc tắt.

Sinh/cập nhật PayrollAdjustment thật cho một kỳ — idempotent theo dòng cấu hình.

Tiền làm tròn tới đồng — phiếu lương không có hào

Lý do của dòng cấu hình đã bị gỡ — dùng để lọc khỏi bảng tính thử

Tính từng dòng cấu hình của kỳ ra tiền hoặc lý do không có tiền — dùng chung cho cả bảng tính thử lẫn lần sinh thật, để hai bên không bao giờ lệch nhau một đồng nào.

Bảng tính thử lọc theo phạm vi xem của người mở màn hình (§3.6). Lần sinh thật thì KHÔNG — nó chạy cho cả kỳ, và ai gọi được nó đã qua role riêng.

Kỳ thử nghiệm nếu BẤT KỲ dòng nào của chủ thể mang cờ đó — fail-closed

Điểm tháng của các chủ thể nguồn điểm = Σ WeightedScore các KpiResult ĐÃ CHỐT.

Đọc snapshot, không gọi provider — cùng nguyên tắc §7.13 và nợ KPI-8: tiền phải khớp với con số đã đóng dấu mà nghiệp vụ nhìn thấy, không phải với dữ liệu gốc lúc chạy.

Diễn giải trên phiếu lương — người nhận phải đọc là hiểu tiền ở đâu ra, không cần mở phần mềm

CRUD mẫu bậc thang thưởng KPI (§7.5, §7.14) — mẫu dùng chung, KHÔNG nói ai được bao nhiêu tiền.

Luật quan trọng nhất: các bậc phải liên tục, không chồng, không hở. Một điểm rơi vào hai bậc là hai số tiền khác nhau tuỳ thứ tự duyệt — và vì đây là đường sinh tiền, "tuỳ thứ tự duyệt" nghĩa là số tiền đổi khi ai đó thêm một bậc mới. Khoảng là nửa mở [Min, Max) nên bậc sau bắt đầu đúng tại Max của bậc trước. Cả hai ví dụ bậc thang sẵn có trong repo (SalesCommissionTier, DriverSalaryScale) không validate chồng khoảng — đây là khoảng trống có sẵn, đừng chép lại nó.

Danh sách mẫu đang hiệu lực — cho ô chọn mẫu ở màn cấu hình nhân viên–tháng

Bậc trúng với một điểm; null khi không bậc nào phủ điểm đó (không suy diễn, không lấy bậc gần nhất)

Validate mẫu và bộ bậc.

Ba luật, mỗi luật chặn một cách làm sai số tiền: Không chồng khoảng — một điểm hai số tiền. Không hở khoảng — điểm rơi vào khe thì người ta không được đồng nào mà chẳng có thông báo nào nói vì sao. Đúng loại giá trị theo Mode — mẫu kiểu hệ số mà bậc chỉ điền số tiền thì tính ra 0 đồng, im lặng.

Ảnh chụp phẳng cho nhật ký — không mang navigation để tránh vòng tham chiếu

Dòng cấu hình thưởng theo từng nhân viên–tháng (§7.14) — nơi tiền thật sự được định.

Không có dòng ⇒ không sinh tiền cho người đó tháng đó, kể cả khi công tắc bật. Đây là chốt chặn thứ tư bên cạnh công tắc, cờ IsTrial và hiệu lực của mẫu. Ai định được tiền: role KpiBonusPolicy.CreateOrUpdate — Nhân sự, Tài chính, BGĐ (§7.5, §7.14 ii). Người quản lý trực tiếp giao chỉ tiêu nhưng không tự định tiền cho cấp dưới. Phạm vi kiểm thêm ở service: chỉ cấu hình được cho người mình nhìn thấy KPI ( §3.6) — HR/Tài chính có Kpi.ViewAll nên phủ cả công ty, còn một quản lý được cấp nhầm role thưởng thì vẫn chỉ chạm được người của mình.

Gán hàng loạt cho một kỳ — sao chép tháng trước và/hoặc nhận thẳng danh sách. Idempotent: chạy lại không nhân đôi, mặc định không đè dòng đã có (§7.14).

Dựng entity từ model kèm toàn bộ validate; trả error khác null là không ghi gì.

Người cấu hình có được chạm tới nhân viên này không.

Hỏi lớp XEM (§3.6) chứ không phải lớp THAO TÁC chỉ tiêu (§7.3): người định tiền là HR/Tài chính/BGĐ — họ không phải quản lý trực tiếp của ai, nên áp §7.3 ở đây là khoá cứng chính những người §7.14 giao việc. Ngược lại, một quản lý bị cấp nhầm role thưởng vẫn chỉ chạm được người trong tầm nhìn của mình, không phải cả công ty.

Điền tên nhân viên và tên chủ thể nguồn điểm — hai truy vấn gộp, không N+1

Engine KPI: phân giải provider theo SourceCode để lấy giá trị thực, và tính điểm từ giá trị thực so với chỉ tiêu.

Mã nguồn dữ liệu của các provider đã đăng ký DI — dùng validate KpiMetric.SourceCode

Có provider nào phục vụ mã này không (không phân biệt hoa thường)

Lấy giá trị thực của một chỉ số cho một chủ thể trong một khoảng ngày. Ném nếu chỉ số cấu hình sai (không phải lỗi dữ liệu).

Tính % hoàn thành và điểm trọng số của một chỉ tiêu khi biết giá trị thực

Chỉ số này là ảnh chụp tại một thời điểm (không cộng dồn được) hay là số cộng dồn cả khoảng — hỏi chính provider, xem .

Chỉ số nhập tay hoặc chưa có provider đều trả false: giá trị nhập tay mang ngữ nghĩa của riêng tháng người ta nhập, nên cộng các tháng lại là đúng.

Chỉ số này có phải dạng tỷ lệ/bình quân không — hỏi của provider thật; chỉ số nhập tay hoặc chưa có provider thì false

Kết quả chấm điểm một chỉ tiêu.

% hoàn thành thô, chưa áp trần (đã làm tròn 2 chữ số)

% hoàn thành sau khi áp trần CapPercent — đây là số dùng để tính điểm

Điểm đã nhân trọng số: Weight/100 × CappedCompletionPercent

Lý do khi điểm bị chấm 0 vì dữ liệu chỉ tiêu không hợp lệ — null nếu chấm bình thường

Số chữ số thập phân giữ lại ở mọi bước chấm điểm

Chấm điểm một chỉ tiêu.

Công thức theo plan §3.1: điểm = trọng số × min(% hoàn thành, trần). Ba chốt an toàn, vì đây là đường dẫn tới tiền thưởng ở GĐ E: Chỉ tiêu ≤ 0 thì chấm 0, không chia. Validation §3.9c đã chặn từ đầu vào, nhưng dữ liệu cũ hoặc nhập tay vẫn lọt được. Chọn chấm 0 (fail closed) thay vì chấm đạt: một chỉ tiêu hỏng mà tự cho điểm tối đa là tiền tự sinh, còn chấm 0 thì người quản lý thấy ngay và sửa lại chỉ tiêu. % hoàn thành không bao giờ âm. Chỉ số dạng tiền có thể ra giá trị thực âm (hoàn, điều chỉnh) — kẹp sàn về 0 để một chỉ tiêu âm không ăn mòn điểm các chỉ tiêu khác. Trần áp trước khi nhân trọng số, đúng thứ tự của §3.1. Với chiều "càng thấp càng tốt", giá trị thực bằng 0 được coi là hoàn hảo và ăn trọn trần. Lưu ý cho GĐ D/E: nếu nguồn dữ liệu hỏng và trả về 0, chỉ số chiều này sẽ ăn điểm tối đa — job chốt kỳ phải đánh dấu dòng lỗi provider thay vì để nó lặng lẽ thành 0 (§3.9d).

Nguồn duy nhất của luật "ai được THAO TÁC chỉ tiêu của ai" (plan §7.3).

Khác — lớp kia trả lời "ai XEM được KPI của ai" (§3.6). Hai tập không trùng nhau và cố ý tách: người có Kpi.ViewAll xem được cả công ty nhưng không vì thế mà giao/chốt được chỉ tiêu cho người ngoài phạm vi quản lý của mình. Tách ra thành lớp riêng ở GĐ D vì từ giai đoạn này có ba đường thao tác cùng dùng một luật: giao chỉ tiêu (GĐ A), chốt lại kỳ + nhập tay giá trị, và đánh giá quý/năm. §3.10 đã chỉ đích danh rủi ro "đường thứ hai chép lại luật rồi lệch dần" — và GĐ C đã cắn phải đúng lớp lỗi đó ở phía phân quyền đọc.

Kiểm người này có được thao tác chỉ tiêu của chủ thể đó không. Trả null nghĩa là được phép; trả chuỗi là thông báo lỗi tiếng Việt để hiển thị thẳng.

Thông báo duy nhất cho mọi lý do "không thao tác được với chủ thể này" — dùng lại khi bên gọi muốn gộp ca "không tồn tại" vào cùng một câu trả lời (§3.10 chống dò).

Liệt kê các chủ thể người này giao được chỉ tiêu — nguồn của ô chọn chủ thể ở màn giao chỉ tiêu (GĐ F).

Cùng một luật với , viết một lần ở đây thay vì để màn hình tự dựng danh sách bằng User/Search: màn KPI đi hỏi danh bạ nhân sự đúng là bẫy §8 mà GĐ C đã cắn phải. Bất biến phải giữ: mọi phần tử trả về đều phải làm trả null — không bao giờ rộng hơn. Chỗ duy nhất HẸP hơn : chỉ liệt kê người dùng . Chủ thể KPI cá nhân là nhân viên, còn bảng User ôm cả khách hàng — hẹp hơn thì an toàn, rộng hơn mới là lỗi.

Trần cứng số dòng trả về, chặn cả khi bên gọi truyền số lớn

Luật §7.3: Employee → người thao tác phải là quản lý trực tiếp (UserPreference.ManagerId); Agency → phải là quản lý của node CHA trong cây Agency, node gốc chỉ Founder; Founder bypass; HR không có quyền mặc định (không nới ngầm).

Tìm kiếm danh mục chỉ số KPI

Lấy chỉ số theo Id — null nếu không tồn tại

Tạo hoặc cập nhật chỉ số — validate §3.9c: metric Auto phải có SourceCode hợp lệ, Code không trùng, không đổi Code/ApplicableTo khi đã có chỉ tiêu tham chiếu

Xoá mềm chỉ số — chặn khi đã có chỉ tiêu tham chiếu (tắt IsActive thay vì xoá)

Chốt kỳ KPI: biến số đang trôi của kỳ thành snapshot bất biến trong KpiResult (plan §3.4).

Ba điều lớp này phải đúng, vì GĐ E sẽ nhân số ở đây ra tiền: Không bao giờ quy lỗi về 0. Nguồn dữ liệu hỏng hay chỉ số nhập tay chưa nhập thì dòng đó **không chốt**: không ghi KpiResult, không đổi trạng thái chỉ tiêu, ghi lý do vào tổng kết. Một dòng chốt với giá trị 0 đọc ra là "không đạt chỉ tiêu" và sẽ thành trừ tiền thưởng của người ta vì một stored procedure hỏng (§3.9d). Một dòng lỗi không làm hỏng kỳ của người khác. Vòng lặp bắt lỗi từng dòng, không có đường nào cho một exception thoát ra làm sập cả lần chạy. Idempotent. Chốt lại kỳ **cập nhật** KpiResult cũ theo AssignmentId, không sinh bản ghi trùng — cùng nguyên tắc mà GĐ E sẽ áp cho PayrollAdjustment.

Chốt kỳ cho **toàn hệ thống** — đường của job Hangfire chạy mùng 1 hằng tháng.

Chỉ đụng chỉ tiêu đang ở trạng thái Assigned: bản nháp chưa giao thì chưa có gì để chốt, và kỳ đã chốt rồi thì chỉ đường chốt lại thủ công mới được sửa (§3.4). Không có assignment nào ⇒ no-op có log, không ném (§3.9d).

Chốt (hoặc chốt lại) kỳ của **một chủ thể** — đường thủ công, kiểm phạm vi §7.3.

Nhập tay giá trị thực cho một chỉ tiêu trước khi chốt kỳ; job không ghi đè giá trị này

Tình trạng cửa sổ chốt lại của một kỳ — để màn chốt kỳ nói được "còn N ngày" trước khi người dùng bấm, thay vì chỉ báo lỗi sau khi bấm.

Chỉ ĐỌC, không đổi gì. Truyền chủ thể thì trả thêm IsClosed, và phần đó chỉ được trả khi chủ thể nằm trong phạm vi §7.3 của người gọi — ngoài phạm vi thì để null chứ không báo lỗi khác đi, để endpoint không thành công cụ dò chủ thể (§3.10).

Vòng chốt dùng chung cho cả job lẫn đường thủ công.

Mỗi dòng là một giao dịch độc lập về mặt hậu quả: lỗi của dòng này không được chạm tới dòng khác. Vì vậy không gom UpdateAsync cả lô ở cuối — một lô có dòng hỏng thì hoặc mất hết hoặc ghi cả dòng hỏng, cả hai đều sai với §3.9d.

Chạy engine thưởng sau khi chốt xong (plan §3.5).

Đặt sau vòng chốt và bọc try/catch: tiền không được làm hỏng việc chốt kỳ. Engine tự giữ bốn chốt chặn (công tắc, IsTrial, dòng cấu hình, mẫu còn hiệu lực) nên gọi vô điều kiện ở đây là an toàn — và cần thiết, vì chạy lại chính là đường CẬP NHẬT khoản đã sinh khi chốt lại kỳ. Không chốt được dòng nào thì không gọi. Phạm vi phải khớp phạm vi của lệnh chốt: chốt một chủ thể ⇒ chỉ chạy thưởng cho dòng cấu hình lấy điểm từ chủ thể đó; chỉ job hệ thống (CloseAllAsync) mới chạy cả kỳ.

Lấy giá trị thực để chốt: ưu tiên giá trị nhập tay, sau đó mới tới engine.

Trả về error khác null nghĩa là **không chốt dòng này**. Không có nhánh nào trả về giá trị 0 thay cho lỗi — đó là toàn bộ lý do hàm này tồn tại tách khỏi vòng lặp.

Breakdown đối soát cho dòng nhập tay — dòng engine tính thì ghi nguyên văn DetailJson của provider, không chế lại (§3.4).

Một câu tiếng Việt duy nhất cho băng thông báo của màn chốt kỳ, đúng theo trạng thái.

Bản đánh giá KPI định kỳ quý/năm của người quản lý (§7.1).

Quý để **điều chỉnh cho đúng hướng**, năm làm **cơ sở tăng lương, thăng chức** — cả hai là tầng đọc + kết luận của con người, KHÔNG tự sinh tiền. Điểm hiển thị là số sống do tính lại mỗi lần mở màn hình; chỉ lúc chuyển Final mới đóng dấu vào AggregatedScore.

Tìm kiếm bản đánh giá — ép phạm vi xem §3.6 server-side như mọi đường đọc KPI khác

Lấy một bản đánh giá kèm bảng tổng hợp điểm của kỳ — null nếu không tồn tại HOẶC ngoài phạm vi xem (không phân biệt, chống dò IDOR)

Tạo/sửa bản đánh giá ở trạng thái Draft — luật phạm vi thao tác §7.3

Chuyển bản đánh giá sang Final và snapshot điểm tổng hợp tại thời điểm đó

Xoá mềm bản đánh giá còn Draft — bản đã Final là căn cứ nhân sự, không xoá

Bản đánh giá kèm bảng tổng hợp điểm của kỳ — thứ màn hình cần để người quản lý viết nhận xét.

Bảng tổng hợp SỐ SỐNG của kỳ; null khi không tính được. Bản đã Final vẫn hiện bảng này để đối chiếu, nhưng điểm chính thức là Review.AggregatedScore đã đóng dấu.

Chốt bản đánh giá và snapshot điểm tổng hợp.

Điểm được TÍNH LẠI ngay tại đây rồi mới đóng dấu, không nhận số từ client: bản đánh giá năm là căn cứ tăng lương/thăng chức (§7.1), cho gửi điểm lên là mở đường sửa căn cứ đó bằng một request.

Gán tên chủ thể và tên người đánh giá — SubjectId đa hình nên không có navigation property

Trả lời câu hỏi "kỳ này đã chốt chưa" cho các luồng NGHIỆP VỤ nằm ngoài phân hệ KPI mà lại đóng dấu mốc thời gian nuôi một chỉ số KPI.

Sinh ra để trả nợ KPI-7. Candidate.OnboardedTime bị đóng dấu lại mỗi lần hồ sơ quay vòng trạng thái (Onboard → Rejected → Onboard), nên một hồ sơ đã đếm cho kỳ tháng 7 có thể bị xoá dấu rồi đóng dấu lại vào tháng 8 — tức **dịch công của kỳ cũ sang kỳ đang chạy**. §3.4 đã chốt: số của kỳ đã chốt là snapshot bất biến. Vậy nên mốc đang nằm trong một kỳ đã chốt thì **đóng băng**, không cho luồng nghiệp vụ xoá hay dời đi nữa. Trạng thái hồ sơ vẫn đổi được bình thường — chỉ riêng cái mốc là bất động. Cố ý là một interface hẹp chứ không phải cho CandidateService phụ thuộc thẳng vào : miền tuyển dụng chỉ cần biết một sự thật ("kỳ khoá chưa"), không cần và không nên với tới được đường chốt kỳ.

Kỳ chứa thời điểm này đã chốt cho các chỉ số đếm hồ sơ nhận việc chưa (hr.onboard-count, agency.onboard-count).

Chỉ khoá khi thật sự có chỉ tiêu onboard đã chốt trong kỳ đó — không khoá theo kiểu "tháng đã qua thì cấm sửa", vì như vậy là bắt miền tuyển dụng trả giá cho một phân hệ mà họ có thể chưa dùng.

Tên khoá AppConfig của phân hệ KPI — seed bằng migration, không hardcode giá trị.

Mốc áp dụng KPI chính thức, dạng yyyy-MM-dd (§7.9)

Số ngày đầu tháng sau còn cho chốt lại kỳ vừa qua (§3.4)

Công tắc sinh thưởng thành PayrollAdjustment (§5 GĐ E) — mặc định TẮT, chỉ chủ dự án bật ở bước 4 của §5.1

Đọc hai khoá cấu hình điều khiển luồng chốt kỳ, và trả lời hai câu hỏi rút ra từ chúng.

Tách khỏi service chốt kỳ để kiểm được bằng test đơn vị mà không dựng cả engine, và để chỉ có **một** nơi diễn giải chuỗi cấu hình thành ngày/số. §3.10 xếp Kpi.EffectiveFrom vào nhóm "chuỗi cấu hình đổi được tiền" — mỗi nơi tự parse một kiểu là mỗi nơi sai một kiểu.

Mốc áp dụng KPI chính thức; null khi chưa cấu hình hoặc giá trị không đọc được

Kỳ tháng này là kỳ thử nghiệm (chốt trước mốc) hay kỳ chính thức.

Fail-closed: chưa cấu hình mốc, hoặc mốc ghi sai định dạng ⇒ coi là kỳ thử nghiệm. Nhầm về phía "thử nghiệm" chỉ làm chậm việc trả thưởng và người vận hành thấy ngay; nhầm về phía "chính thức" là tiền tự sinh ở GĐ E trước khi có ai duyệt (§5.1 bước 4).

Số ngày cửa sổ chốt lại; rơi về mặc định an toàn nếu cấu hình thiếu/sai

Công tắc sinh thưởng đang bật hay tắt.

Fail-closed: khoá thiếu, giá trị rác, hay ghi kiểu "1"/"yes" đều ra false — chỉ đúng chuỗi true (không phân biệt hoa thường, cắt khoảng trắng) mới bật. Nhầm về phía tắt thì người vận hành thấy ngay là chưa có tiền; nhầm về phía bật là tiền tự sinh trước khi có ai duyệt (§5.1 bước 4). Đọc qua đây, đừng parse chỗ khác: mỗi nơi tự diễn giải một kiểu là mỗi nơi sai một kiểu. Lưu ý AppConfig có hai lớp cache song song — đổi khoá phải làm mới cả hai, nếu không công tắc bật mà một giờ sau mới có hiệu lực (bẫy GĐ D).

Cửa sổ chốt lại mặc định khi cấu hình thiếu hoặc ghi sai (ngày)

Quy đổi kỳ KPI (năm/tháng, quý, năm) thành khoảng ngày — dùng chung cho chốt kỳ và tổng hợp.

Mọi mốc dùng offset +07:00 cứng, khớp KpiActualContext.ForMonth của GĐ B: giờ máy chủ có thể là UTC khi chạy container, còn kỳ KPI thì luôn là kỳ theo giờ Việt Nam. Để trôi theo giờ máy chủ là số của ngày mùng 1 nhảy sang kỳ trước.

Múi giờ của kỳ KPI: +07:00

Thời điểm đầu một kỳ tháng

Thời điểm cuối một kỳ tháng (tick cuối cùng)

Kỳ tháng liền trước một thời điểm — job chốt kỳ chạy mùng 1 để chốt tháng vừa qua.

Quy thời điểm về +07:00 trước khi đọc năm/tháng. Job chạy 5:15 sáng giờ Việt Nam ngày mùng 1, tức 22:15 UTC ngày cuối tháng trước. Trên máy chủ chạy giờ UTC — kiểu triển khai container thông thường — đọc thẳng moment.Month sẽ ra tháng CŨ, rồi lùi thêm một tháng nữa thành chốt nhầm kỳ trước nữa: tháng 7 bị chốt lại (ghi đè snapshot) còn tháng 8 không ai chốt.

Kỳ tháng đang chạy tại một thời điểm — cùng luật quy đổi với .

Tồn tại để nơi nào cần "kỳ hiện tại" cũng đi qua đúng một chỗ. Đọc thẳng DateTimeOffset.Now.Month trên máy chủ chạy UTC là lệch hẳn một kỳ trong 7 tiếng đầu mỗi ngày mùng 1 — cùng họ với lỗi job chốt kỳ của GĐ D.

Các tháng thuộc một quý (1-4)

Theo dõi KPI **trong kỳ**: tính giá trị thực tại thời điểm gọi, không snapshot (plan §3.4).

Khác hẳn chốt kỳ (GĐ D): ở đây không ghi gì xuống DB, số đọc lúc nào là số lúc đó. Chấp nhận chậm hơn vì mỗi dòng gọi lại stored procedure báo cáo — đổi lại số luôn khớp màn báo cáo.

Lấy tiến độ KPI của một kỳ, gộp theo chủ thể. Phạm vi xem ép server-side theo §3.6 — tham số lọc của client chỉ thu hẹp được, không nới ra.

Tham số màn theo dõi KPI.

Năm của kỳ; ≤ 0 thì lấy năm hiện tại

Tháng của kỳ (1-12); ngoài khoảng thì lấy tháng hiện tại

Lọc thêm theo loại chủ thể (tuỳ chọn)

Lọc thêm theo một chủ thể cụ thể (tuỳ chọn). Chỉ **thu hẹp** kết quả: chủ thể ngoài phạm vi xem thì trả rỗng chứ không mở thêm quyền.

Lấy giá trị thực của một dòng, quy mọi trục trặc thành ghi chú thay vì ném lỗi.

Một chỉ số hỏng không được làm sập cả màn theo dõi (§3.9d) — người quản lý vẫn phải xem được các chỉ tiêu còn lại. Dòng hỏng để ActualValue null kèm ghi chú, tuyệt đối không quy về 0. Kỳ ĐÃ CHỐT đọc thẳng KpiResult, không chạy lại provider. Đây là chốt chặn phơi nhiễm của nợ KPI-8: hai chỉ số agency.* gom nhân sự theo User.AgencyId **tại thời điểm chạy**, nên mở lại một kỳ đã qua sau khi lái xe chuyển bưu cục sẽ ra số khác lần chốt — bưu cục cũ tụt, bưu cục mới tự nhiên có thêm công của tháng mà người đó chưa thuộc về. Snapshot bất biến của §3.4 chỉ có tác dụng nếu màn hình thật sự đọc nó; gọi lại provider là vô hiệu hoá chính cái snapshot vừa ghi.

Gán tên hiển thị cho chủ thể — SubjectId đa hình nên không có navigation property

Danh sách mã nguồn dữ liệu tự động của KPI (plan §3.3).

Đây là **danh mục tên mã** để seed migration và để provider khai Code mà không gõ chuỗi rời rạc. Nó KHÔNG còn là căn cứ validate: từ GĐ B, KpiMetricService hỏi IKpiEngineService.IsSourceCodeRegistered — tức hỏi provider nào thật sự chạy được — nên mã nằm trong danh sách này mà chưa có provider thì vẫn bị từ chối lúc lưu chỉ số. Trạng thái provider tại 2026-08-14 (cuối GĐ B): đã có 6 mã cá nhân (driver.pickup-count, driver.delivery-count, sales.revenue, sales.order-count, sales.new-customers, hr.onboard-count); driver.delivery-rate tạm bỏ qua theo §7.11a (nợ KPI-6); sales.active-customers và nhóm agency.* để GĐ C.

Toàn bộ mã hợp lệ — dùng validate lúc lưu KpiMetric SourceType = Auto

Nguồn duy nhất của luật "ai xem được KPI của ai" (plan §3.6).

Tách riêng vì phân hệ KPI có nhiều đường đọc cùng một tập dữ liệu — danh sách chỉ tiêu, màn theo dõi trong kỳ, kết quả kỳ, xuất Excel — và §3.10 chỉ đích danh rủi ro: **đường đọc thứ hai quên lọc phạm vi là bài kinh điển**. Mỗi đường tự chép lại luật thì sớm muộn cũng lệch nhau, nên mọi đường phải hỏi đúng lớp này.

Người này có được phép đọc dữ liệu KPI hay không — cổng vào của cả miền.

Khác : hàm này trả lời "có được xem KPI KHÔNG", còn hàm kia trả lời "xem được của AI". Mọi đường đọc KPI **không đi qua controller** (widget dashboard, job, export) phải hỏi hàm này trước, vì lớp [Authorize(Roles = ...)] chỉ gác đường HTTP. Điều kiện chép đúng bằng cổng của GET /api/kpi/progress — đường đọc mới không bao giờ được rộng hơn đường đọc sẵn có của chính miền đó (plan §8). Widget dashboard gác bằng nhóm quyền (DashboardWidgetPermission), một trục hoàn toàn khác role; không có hàm này thì người thuộc nhóm quyền được mở widget sẽ đọc được KPI của cấp dưới trong khi màn KPI vẫn trả 403 cho họ — đúng bẫy "mượn lớp phân quyền của miền này để gác dữ liệu của miền khác" mà GĐ C và GĐ D đã cắn.

Người này xem được KPI của tất cả mọi người không (Founder hoặc có quyền Kpi.ViewAll)

Tập nhân viên người này xem được KPI: chính mình + cấp dưới trực tiếp

Tập đơn vị người này xem được KPI: đơn vị mình quản lý + đơn vị con của chúng

Quản lý trực tiếp của một nhân viên

Người này có phải Founder không (Founder bỏ qua mọi ràng buộc phạm vi)

Role gác GET /api/kpi/progress — cổng đọc KPI của cả miền

Quản lý trực tiếp của một nhân viên — đọc UserPreference.ManagerId, KHÔNG phải User.ManagerId.

Đo trên DB dev 2026-08-14: 131 nhân viên đang hoạt động, 0 người có User.ManagerId > 0, 46 người có UserPreference.ManagerId > 0. Cột User.ManagerId chỉ còn nghĩa cũ "sale quản lý khách hàng" và không luồng nào ghi cho nhân viên — dùng nhầm nó thì mọi chỉ tiêu chỉ Founder giao được. Toàn hệ thống (UserService, PayrollService, LeaveService) đều đọc UserPreference.

Phạm vi xem theo §3.6: chính mình + cấp dưới trực tiếp (theo UserPreference.ManagerId)

Phạm vi xem theo §3.6: các đơn vị mình trực tiếp quản lý **và các đơn vị con của chúng**.

Phần "đơn vị con" là bắt buộc để khớp với quyền giao §7.3: quản lý node cha giao được chỉ tiêu cho node con, nên phải xem được chính chỉ tiêu mình vừa giao. Bản đầu chỉ lấy ManagerId == userId — bấm thật 2026-08-14 lộ ra quản lý khu vực giao cho bưu cục con xong thì màn danh sách của họ trống trơn. Tập này khớp đúng tập §7.3 cho phép thao tác, không nới rộng hơn.

Năng suất lái xe của cả bưu cục / khu vực trong kỳ (agency.driver-productivity): tổng số đơn **lấy + giao** do người của đơn vị thực hiện.

**Đơn vị đo là "đơn", không phải "đơn/người"** — theo đúng danh mục chỉ số đã seed ở GĐ A. Vì là tổng chứ không phải trung bình, chỉ số này **không có mẫu số**, nên lái xe mới chưa chạy đơn nào chỉ đóng góp 0 chứ không làm lệch số của người khác. **Cách nhận diện lái xe — quyết định §7.12b.** `HrPermissionMappings` rỗng nên không tra được chức danh; thay vào đó truyền **toàn bộ nhân sự của đơn vị** vào SP báo cáo và để dữ liệu vận hành tự lọc: ai không lấy/giao đơn nào thì SP không trả dòng nào. Với một chỉ số dạng TỔNG, cách này ra **đúng cùng con số** với cách gom theo danh sách chức danh của HR — người không phải lái xe cộng vào 0. Vì vậy nợ `KPI-5` không còn chặn chỉ số này. Tái dùng đúng sp_GetDriverProductivityReportByDate mà hai chỉ số lái xe cá nhân đang gọi (§3.9a): số của bưu cục vì thế luôn bằng tổng số của từng lái xe trên màn báo cáo, không bao giờ lệch âm thầm. Một đơn vừa được người của đơn vị lấy vừa được người của đơn vị giao sẽ tính **hai công** — đúng ý nghĩa "khối lượng việc đã làm", và giống hệt cách cộng driver.pickup-count + driver.delivery-count của từng cá nhân.

Số ứng viên nhận việc trong kỳ tính cho cả bưu cục / khu vực (agency.onboard-count).

Cùng định nghĩa "nhận việc" với (trạng thái Onboard, mốc kỳ Candidate.OnboardedTime), chỉ khác ở chỗ gom theo **đơn vị của người phụ trách tuyển** thay vì theo từng người (plan §3.3). Hồ sơ chưa gán RecruiterId không tính cho đơn vị nào — giống hệt luật của chỉ số cá nhân, để tổng của các bưu cục không bao giờ vượt tổng của các cá nhân. Không đếm trùng khi gộp khu vực: một hồ sơ có đúng một người tuyển, người đó thuộc đúng một đơn vị, nên hồ sơ chỉ rơi vào một bưu cục trong phạm vi.

Doanh số của một bưu cục / khu vực trong kỳ (agency.revenue).

Nguồn: sp_GetAgencyRevenueStatistics qua , nhóm theo Order.SaleAgencyId (plan §7.7), doanh thu = OrderFin.TotalFeeAfterVat. ⚠️ **Không cộng dồn được với sales.revenue.** Chỉ số của sale cố ý dùng công thức của SP báo cáo đang chạy: thiếu 3 khoản phí và tính theo **thời điểm thu tiền** (ngoại lệ §7.11b). Chỉ số này theo **ngày lên đơn** và đủ 7 khoản. Ai cộng hai con số lại sẽ ra một số vô nghĩa. Không đếm trùng khi gộp khu vực: SP trả **một dòng cho mỗi bưu cục**, mỗi đơn chỉ thuộc đúng một SaleAgencyId, nên cộng các dòng lại không thể tính một đơn hai lần.

Nền dùng chung của mọi provider có chủ thể là đơn vị (agency.*): phân giải phạm vi gộp một lần, đúng một chỗ.

Luật gộp (plan §7.2) nằm ở chứ không ở đây — lớp này chỉ bảo đảm **mọi** provider đơn vị đều đi qua nó. Nếu để từng provider tự đệ quy cây thì chỉ cần một provider quên là khu vực ra số của riêng node cha, và không ai phát hiện vì con số vẫn "trông hợp lý". Đặt việc phân giải ở provider chứ không ở KpiEngineService để mọi đường gọi đều tự đúng: GĐ D thêm job chốt kỳ sẽ không phải nhớ tự expand cây.

Danh sách đơn vị phải gộp cho ngữ cảnh này — đã khử trùng lặp.

Nền dùng chung của hai chỉ số năng suất lái xe — cùng gọi một stored procedure.

**Tái dùng đúng SP mà màn báo cáo năng suất lái xe đang chạy** (sp_GetDriverProductivityReportByDate, qua IDriverReportService), truyền y hệt bộ tham số mà màn đó truyền. Đây là cách duy nhất bảo đảm tiêu chí §3.9a: số trên màn KPI và số trên màn báo cáo không bao giờ lệch nhau âm thầm. Viết lại query bằng EF trông sạch hơn nhưng sẽ trôi khỏi SP ngay lần đầu ai đó sửa SP. Gọi thẳng SP thay vì gọi qua IDriverReportService vì service đó nhận SmartTableParam và tự lọc theo quyền của người đang đăng nhập — hai thứ sai ngữ cảnh ở đây, nơi chủ thể là lái xe được chấm KPI chứ không phải người đang xem. Ngữ nghĩa kỳ (kế thừa từ SP, ghi lại để khỏi đoán): đơn tính vào kỳ theo OrderTimeTrack.PickupTime / DeliveryDate — mốc lái xe làm việc thật, không phải ngày tạo đơn. Không lọc trạng thái đơn, vì đã lấy hàng/giao hàng là đã có công.

Cộng cột nào của báo cáo lại thành giá trị thực

Tên cột báo cáo, ghi vào DetailJson để người đối soát biết nhìn vào đâu

Số đơn lái xe đã lấy hàng trong kỳ (driver.pickup-count).

Số đơn lái xe đã giao thành công trong kỳ (driver.delivery-count).

Số ứng viên nhận việc trong kỳ, tính cho người phụ trách tuyển (hr.onboard-count).

Đếm theo Candidate.RecruiterId (plan §7.6), **không** theo CreatedBy: đo trên DB dev 2026-08-14 thì 96% hồ sơ 6 tháng gần nhất do đúng một tài khoản nhập hộ, nên CreatedBy là dấu vết người nhập liệu chứ không phải người tuyển. Mốc kỳ là OnboardedTime — cột thêm cùng giai đoạn này. Không dùng UpdatedTime vì nó đổi theo mọi lần sửa hồ sơ, sửa một dòng ghi chú là số của cả kỳ nhảy sang kỳ khác. Hồ sơ chưa gán người tuyển (RecruiterId trống — 94/663 hồ sơ trên DB dev, phần lớn là ứng viên tự nộp) **không tính cho ai**. Đó là lý do màn Candidate có bộ lọc "chưa có người phụ trách" để nhân sự nhận hồ sơ về mình trước khi chốt kỳ.

Số khách hàng đang hoạt động của một sale tại ngày chốt kỳ (sales.active-customers).

Định nghĩa "hoạt động" chốt ở plan §7.4: có ít nhất một đơn **tạo trong 3 tháng gần nhất** tính đến ngày chốt **và** đơn đó đã giao thành công. Cửa sổ **trượt 3 tháng**, không bó theo kỳ tháng — nên chỉ số này là ảnh chụp **tại một thời điểm**, khác các chỉ số khác vốn cộng dồn cả kỳ. Mốc chụp là ToDate (cuối kỳ). Dùng **cùng một SP** với danh sách khách không hoạt động mà người quản lý nhìn thấy, để con số và danh sách không bao giờ lệch nhau — xem . ⚠️ Đây **không phải** cơ chế "nhả quản lý" khách hàng — việc đó là nợ `KPI-1`, làm ở đợt riêng (§7.4). Ở đây chỉ đếm và liệt kê, không đụng Customer.ManagerId.

Chỉ số ảnh chụp — xem . Hệ quả ở tầng tổng hợp quý/năm: chỉ tiêu quý KHÔNG cộng dồn ba tháng, mà lấy chỉ tiêu của tháng cuối kỳ.

Số khách hàng mới sale mở được trong kỳ (sales.new-customers).

Định nghĩa theo plan §3.3: khách có CreatedTime nằm trong kỳ và ManagerId là sale đang được chấm. Không có SP báo cáo tương ứng nên query bằng EF — nhẹ và đủ. Đếm theo ManagerId **hiện tại**, không phải người mở khách lúc đó: khách chuyển tay sang sale khác thì số kỳ cũ đổi theo. Chấp nhận được vì §5 đã chốt không tính KPI cho kỳ quá khứ, còn trong kỳ đang chạy thì chuyển tay là hiếm và người quản lý thấy ngay trên màn theo dõi. Repository.Query() đã lọc sẵn xoá mềm — khách đã xoá không tính cho ai, đúng ý muốn.

Nền dùng chung của hai chỉ số doanh số/sản lượng sale — cùng gọi một stored procedure.

**Quyết định chủ dự án 2026-08-14 (plan §7.11b): khớp SP báo cáo đang chạy** (sp_GetOrderRevenueStatisticsBySale_Optimized, cùng SP của màn "Thống kê doanh thu theo sale"), để số trên màn KPI khớp từng đồng với màn báo cáo mà quản lý đang dùng (tiêu chí §3.9a). Ngữ nghĩa kế thừa từ SP — phải nói rõ vì nó KHÁC nguyên tắc TotalFeeAfterVat ở §7.7/§8, và đây là ngoại lệ có chủ ý chỉ áp cho nhóm sales.*: Doanh thu = Fee + CodFee + PickupSubFee + DeliverySubFee − Discount; KHÔNG gồm GoodsAttributeFee, InsuranceFee, ReturnFee. Đơn rơi vào kỳ theo **thời điểm thu được tiền** (suy từ PayFeeType), không phải ngày tạo đơn ⇒ đơn tạo cuối tháng mà tháng sau mới thu thì tính cho kỳ sau; đơn chưa thu tiền không tính cho ai. Đơn huỷ (Status = 8) bị loại khỏi cả doanh thu lẫn sản lượng. SP nhận tham số kiểu DATE và tự cộng một ngày vào @EndDate, nên truyền thẳng phần ngày của khoảng là đúng — kỳ tính trọn cả ngày cuối.

Lấy cột nào của báo cáo làm giá trị thực

Tên cột báo cáo, ghi vào DetailJson để người đối soát biết nhìn vào đâu

Doanh số sale trong kỳ (sales.revenue).

Sản lượng đơn của sale trong kỳ (sales.order-count).

Điều kiện công bố #5 (plan §3.3): ≥ 1 ảnh bìa chụp thật, đã duyệt, có alt; mềm: < 6 ảnh đã duyệt. Chỉ tính ảnh — ảnh Branch.Manager tải lên chờ duyệt không làm hồ sơ "đủ ảnh".

Số ảnh đã duyệt khuyến nghị — dưới mức này chỉ cảnh báo.

Điều kiện công bố #6 (giới thiệu 150–400 từ, không trùng ≥ 80 % với hồ sơ khác) và #10 (cổng chặn nội dung), cùng luật "không số điện thoại trong nội dung" của đặc tả §10.3 — áp lên mọi chữ lên web: Intro, hỏi đáp, thông báo tạm ngưng, alt + chú thích của ảnh đã duyệt (plan §3.3).

Một đoạn chữ của hồ sơ bưu cục sẽ lên trang công khai, kèm tên trường để báo lỗi đúng chỗ.

Tên trường theo DTO: Intro, Faq[0].Q, PausedMessage, Media[12].Caption… Văn bản thuần (Intro đã bỏ thẻ HTML).

Một đoạn chữ của hồ sơ bưu cục sẽ lên trang công khai, kèm tên trường để báo lỗi đúng chỗ.

Tên trường theo DTO: Intro, Faq[0].Q, PausedMessage, Media[12].Caption… Văn bản thuần (Intro đã bỏ thẻ HTML).

Tên trường theo DTO: Intro, Faq[0].Q, PausedMessage, Media[12].Caption…

Văn bản thuần (Intro đã bỏ thẻ HTML).

Một số điện thoại tìm thấy trong nội dung.

Trường chứa số. Dòng (từ 1) trong văn bản thuần của trường. Ký tự (từ 1) trong dòng đó. Chuỗi số khớp, nguyên văn.

Một số điện thoại tìm thấy trong nội dung.

Trường chứa số. Dòng (từ 1) trong văn bản thuần của trường. Ký tự (từ 1) trong dòng đó. Chuỗi số khớp, nguyên văn.

Trường chứa số.

Dòng (từ 1) trong văn bản thuần của trường.

Ký tự (từ 1) trong dòng đó.

Chuỗi số khớp, nguyên văn.

"dòng 2, ký tự 15".

Một câu hỏi thường gặp của bưu cục (AgencyProfile.FaqJson = mảng [{"Q":"…","A":"…"}], chữ thuần).

Dấu vân tay trigram của một đoạn giới thiệu — tính một lần, so với mọi hồ sơ khác.

Kết quả so trùng: hồ sơ giống nhất và tỷ lệ phần trăm (làm tròn xuống).

Kết quả so trùng: hồ sơ giống nhất và tỷ lệ phần trăm (làm tròn xuống).

Bộ intro của mọi hồ sơ, nạp MỘT lần cho cả lượt (Get / SetStatus / Search lọc "thiếu điều kiện đăng") — không mỗi hồ sơ một truy vấn. Việc 0 A2: dev có 0 intro; mạng lưới vài chục bưu cục nên so từng cặp trong bộ nhớ là đủ.

Hồ sơ KHÁC có intro giống ≥ ngưỡng nhất; null nếu không có.

Luật nội dung hồ sơ bưu cục — hàm thuần, dùng chung cho kiểm lúc ghi (Update, nhân sự, ảnh) và điều kiện công bố #5/#6/#10 (docs/plan-buu-cuc.md §3.3, đặc tả §10.3).

Trần độ dài HTML của Intro (400 từ tiếng Việt kèm thẻ ≈ 3–5 nghìn ký tự) — chặn payload rác.

Trùng từ ngưỡng này trở lên là DUPLICATE_INTRO (đặc tả §9.2 "trùng ≥ 80%").

Pattern:
(?<![\\d+.,])(\\+84|0)\\s?\\d{2,4}\\)?[\\s.\\-]?\\d{3,4}[\\s.\\-]?\\d{3,4}(?![\\d]|[.,]\\d)
Explanation:
○ Zero-width negative lookbehind.
○ Match a character in the set [+,.\d] right-to-left.
○ 1st capture group.
○ Match with 2 alternative expressions.
○ Match the string "+84".
○ Match '0'.
○ Match a whitespace character atomically, optionally.
○ Match a Unicode digit greedily at least 2 and at most 4 times.
○ Match ')' atomically, optionally.
○ Match a character in the set [-.\s] greedily, optionally.
○ Match a Unicode digit greedily at least 3 and at most 4 times.
○ Match a character in the set [-.\s] greedily, optionally.
○ Match a Unicode digit greedily at least 3 and at most 4 times.
○ Zero-width negative lookahead.
○ Match with 2 alternative expressions, atomically.
○ Match a Unicode digit.
○ Match a sequence of expressions.
○ Match a character in the set [,.].
○ Match a Unicode digit.
Pattern:
<\\s*(script|style)\\b[^>]*>.*?<\\s*/\\s*\\1\\s*>
Options:
RegexOptions.IgnoreCase | RegexOptions.Singleline
Explanation:
○ Match '<'.
○ Match a whitespace character atomically any number of times.
○ 1st capture group.
○ Match a character in the set [Ss].
○ Match with 2 alternative expressions.
○ Match a sequence of expressions.
○ Match a character in the set [Cc].
○ Match a character in the set [Rr].
○ Match a character in the set [Ii].
○ Match a character in the set [Pp].
○ Match a character in the set [Tt].
○ Match a sequence of expressions.
○ Match a character in the set [Tt].
○ Match a character in the set [Yy].
○ Match a character in the set [Ll].
○ Match a character in the set [Ee].
○ Match if at a word boundary.
○ Match a character other than '>' atomically any number of times.
○ Match '>'.
○ Match any character lazily any number of times.
○ Match '<'.
○ Match a whitespace character atomically any number of times.
○ Match '/'.
○ Match a whitespace character greedily any number of times.
○ Match the same text as matched by the 1st capture group.
○ Match a whitespace character atomically any number of times.
○ Match '>'.
Pattern:
<\\s*br\\s*/?\\s*>|<\\s*/\\s*(p|div|li|h[1-6]|tr|blockquote|section|table|ul|ol|dt|dd|pre|figure|figcaption)\\s*>
Options:
RegexOptions.IgnoreCase
Explanation:
○ Match '<'.
○ Atomic group.
○ Match a whitespace character atomically any number of times.
○ Match with 2 alternative expressions, atomically.
○ Match a sequence of expressions.
○ Match an empty string.
○ Match a character in the set [Rr].
○ Match a whitespace character greedily any number of times.
○ Match '/' atomically, optionally.
○ Match a whitespace character atomically any number of times.
○ Match '>'.
○ Match a sequence of expressions.
○ Match an empty string.
○ Match a whitespace character atomically any number of times.
○ 1st capture group.
○ Match with 15 alternative expressions.
○ Match a character in the set [Pp].
○ Match a sequence of expressions.
○ Match a character in the set [Dd].
○ Match a character in the set [Ii].
○ Match a character in the set [Vv].
○ Match a sequence of expressions.
○ Match a character in the set [Ll].
○ Match a character in the set [Ii].
○ Match a sequence of expressions.
○ Match a character in the set [Hh].
○ Match a character in the set [1-6].
○ Match a sequence of expressions.
○ Match a character in the set [Tt].
○ Match a character in the set [Rr].
○ Match a sequence of expressions.
○ Match a character in the set [Bb].
○ Match a character in the set [Ll].
○ Match a character in the set [Oo].
○ Match a character in the set [Cc].
○ Match a character in the set [Kk\u212A].
○ Match a character in the set [Qq].
○ Match a character in the set [Uu].
○ Match a character in the set [Oo].
○ Match a character in the set [Tt].
○ Match a character in the set [Ee].
○ Match a sequence of expressions.
○ Match a character in the set [Ss].
○ Match a character in the set [Ee].
○ Match a character in the set [Cc].
○ Match a character in the set [Tt].
○ Match a character in the set [Ii].
○ Match a character in the set [Oo].
○ Match a character in the set [Nn].
○ Match a sequence of expressions.
○ Match a character in the set [Tt].
○ Match a character in the set [Aa].
○ Match a character in the set [Bb].
○ Match a character in the set [Ll].
○ Match a character in the set [Ee].
○ Match a sequence of expressions.
○ Match a character in the set [Uu].
○ Match a character in the set [Ll].
○ Match a sequence of expressions.
○ Match a character in the set [Oo].
○ Match a character in the set [Ll].
○ Match a sequence of expressions.
○ Match a character in the set [Dd].
○ Match a character in the set [Tt].
○ Match a character in the set [Dd] exactly 2 times.
○ Match a sequence of expressions.
○ Match a character in the set [Pp].
○ Match a character in the set [Rr].
○ Match a character in the set [Ee].
○ Match a sequence of expressions.
○ Match a character in the set [Ff].
○ Match a character in the set [Ii].
○ Match a character in the set [Gg].
○ Match a character in the set [Uu].
○ Match a character in the set [Rr].
○ Match a character in the set [Ee].
○ Match a sequence of expressions.
○ Match a character in the set [Ff].
○ Match a character in the set [Ii].
○ Match a character in the set [Gg].
○ Match a character in the set [Cc].
○ Match a character in the set [Aa].
○ Match a character in the set [Pp].
○ Match a character in the set [Tt].
○ Match a character in the set [Ii].
○ Match a character in the set [Oo].
○ Match a character in the set [Nn].
○ Match a whitespace character atomically any number of times.
○ Match '>'.
Pattern:
<[^>]*>
Explanation:
○ Match '<'.
○ Match a character other than '>' atomically any number of times.
○ Match '>'.
Pattern:
[^a-z0-9]+
Explanation:
○ Match a character in the set [^0-9a-z] atomically at least once.


HTML (TinyMCE) → văn bản thuần để đếm từ, dò số, chạy cổng chặn: thẻ khối và <br> thành xuống dòng (vị trí "dòng n" khớp đoạn văn người dùng thấy), bỏ mọi thẻ khác, giải mã entity, &nbsp; thành khoảng trắng, Unicode FormC. Số bị cắt bởi thẻ inline (0912 <b>345</b> 678) vẫn liền lại.

Số từ = số cụm cách nhau bởi khoảng trắng có ít nhất một chữ hoặc số (tiếng Việt: mỗi âm tiết một từ, như bộ đếm TinyMCE).

Mọi số điện thoại trong , kèm dòng/ký tự.

Câu tiếng Việt cho một số điện thoại tìm thấy.

Tập trigram theo cách pg_trgm (đặc tả gốc viết cho PostgreSQL): bỏ dấu, viết thường, mọi ký tự ngoài [a-z0-9] thành ranh giới từ, mỗi từ đệm hai khoảng trắng đầu và một khoảng trắng cuối rồi lấy mọi cụm 3 ký tự. Trigram KÝ TỰ chứ không phải cụm 3 từ: đổi 10 % số từ rải đều làm mất ~30 % cụm 3 từ, nên "giống 90 %" theo cụm từ chỉ còn ~55 % — lọt ngưỡng.

|A ∩ B| và |A ∪ B|.

Jaccard ≥ 80 % — so bằng số nguyên (giao × 100 ≥ hợp × 80) để 4/5 không lệch vì dấu phẩy động.

Dấu vân tay của một intro HTML.

Đọc FaqJson: null/rỗng → danh sách rỗng; không phải mảng các object có Q, A là chuỗi (không phân biệt hoa thường tên khoá) → null.

Lỗi tiếng Việt nếu danh sách hỏi đáp sai luật; null nếu hợp lệ.

Hỏi đáp dạng chuẩn để lưu: [{"Q":"…","A":"…"}] đã cắt khoảng trắng.

Các đoạn chữ của hỏi đáp: Faq[i].Q, Faq[i].A.

Các đoạn chữ của một ảnh lên web: Media[id].AltText, Media[id].Caption (id = 0 khi chưa lưu).

Số điện thoại trong nhiều đoạn chữ.

Lỗi CỨNG của cổng chặn nội dung () trên nhiều đoạn chữ; luật mềm bỏ qua.

"[GATE_01_HOTLINE_CU] Intro (dòng 2): Hotline cũ…".

Vị trí file ảnh hồ sơ bưu cục trên đĩa (nợ BC-14, BC-16 — plan §3.12).

BC-14 — chọn "chỉ file đã duyệt nằm trong thư mục phục vụ + xoá file vật lý khi gỡ". Ảnh chờ duyệt nằm ở thư mục riêng KHÔNG được site media phục vụ (Network:PendingMediaRoot, trống = <Media.RootPath>-cho-duyet, cùng cấp chứ không lồng bên trong gốc media); duyệt → dời sang Media.RootPath cùng đường dẫn tương đối; bỏ duyệt → dời ngược lại; gỡ ảnh → xoá file ở cả hai nơi. Lý do chọn phương án này thay vì chỉ xoá khi gỡ: ảnh Branch.Manager tải lên chưa ai duyệt mà đã có URL công khai thì ai cầm URL (chính họ, hoặc bất kỳ ai họ gửi) đều mở được — "chờ duyệt" chỉ là cờ trong DB. Portal vẫn cần xem ảnh chờ duyệt để duyệt → cấp URL qua API ký HMAC, hết hạn sau , nên SPA không phải đổi gì (vẫn đọc Url vào <img>). BC-16 — ảnh Open Graph JPEG sinh lúc ảnh vào thư mục phục vụ (tải lên đã duyệt / duyệt), không lúc công bố hay lúc render: ảnh OG có thể đổi sau khi công bố (tab SEO chọn ảnh khác), còn website là tiến trình khác, có thể khác máy, không có quyền ghi thư mục media. Sinh cho mọi ảnh đã duyệt (≤ 60 ảnh/bưu cục) thì ảnh nào được chọn làm OG cũng đã có sẵn bản {tên}-og.jpg đúng quy ước AgencyPublicMedia.OgUrl; bỏ duyệt/gỡ thì xoá theo.

Ảnh vừa xử lý (đang ở thư mục phục vụ): đã duyệt → sinh bản OG; chờ duyệt → dời sang thư mục chờ duyệt. Trả câu lỗi tiếng Việt nếu không dời được — khi đó ảnh KHÔNG được ghi nhận.

Đổi vị trí theo trạng thái duyệt mới. Ném khi dời lỗi — service trả lỗi trước khi ghi DB.

Xoá file ở cả hai nơi + bản OG. Không ném (dọn file là việc phụ, DB đã đúng).

Đường dẫn tuyệt đối của file đang tồn tại (thư mục chờ duyệt trước, rồi thư mục phục vụ); null nếu không thấy.

URL xem trước ảnh chờ duyệt qua API, ký HMAC, hết hạn sau .

Kiểm vé xem trước: đúng ảnh, đúng bưu cục, chưa hết hạn, chữ ký khớp.

Khoá HMAC ngẫu nhiên theo tiến trình khi appsettings trống — vé mất hiệu lực khi API khởi động lại (portal Get lại là có vé mới).

Thư mục chờ duyệt: Network:PendingMediaRoot, trống thì cùng cấp gốc media kèm hậu tố.

{tên}.webp → {tên}-og.jpg (quy ước của ImageService.GenerateOgImageFromWebpAsync).

(tuyệt đối trong thư mục phục vụ, tuyệt đối trong thư mục chờ duyệt). SystemPath lưu tương đối dưới Media.RootPath; đường dẫn tuyệt đối cũ (cấu hình lạ) coi như đã nằm trong thư mục phục vụ.

true = đường ĐẶT file vào thư mục chờ duyệt / dời giữa hai nơi — kiểm hai gốc tách rời.

Mã lỗi máy của API hồ sơ bưu cục và HTTP status tương ứng (docs/plan-buu-cuc.md §3.3).

Tên giữ đúng đặc tả §9.2 (BRANCH_NOT_FOUND, VERSION_CONFLICT…); các mã INVALID_*, FORBIDDEN, PROFILE_ALREADY_EXISTS, STAFF_NOT_FOUND, VALIDATION_ERROR là mã thêm khi code A1 để lỗi kiểm dữ liệu có tên máy thay vì chỉ có câu tiếng Việt.

Id ảnh không có trong bưu cục này (kể cả khi là ảnh của bưu cục khác — không lộ tồn tại).

Số phiên bản không có trong lịch sử của bưu cục này.

File tải lên không phải JPEG/PNG/WebP thật, quá 10 MB, quá nhiều điểm ảnh, hoặc xử lý ảnh thất bại.

Slug không khớp ^[a-z0-9-]{3,120}$.

Id đề xuất không có (hoặc thuộc bưu cục ngoài phạm vi — không lộ tồn tại). GĐ D.

Đề xuất đã duyệt / từ chối / bị thay bằng đề xuất mới — kể cả khi người khác vừa xử lý cùng lúc. GĐ D.

Đề xuất không đổi gì so với hồ sơ hiện tại — không tạo đề xuất rỗng cho người duyệt. GĐ D.

HTTP status của một mã lỗi; mã lạ rơi về 400.

Vỏ trả lời của API hồ sơ bưu cục: kế thừa (FE vẫn đọc Result === 1) và thêm mã lỗi máy để controller đổi ra 403/404/409/422 — plan §3.3 "Làm rõ khi code A1".

Mã lỗi máy (); null khi thành công.

Dữ liệu khi thành công.

Tên nhóm trường / trường gây lỗi (FORBIDDEN_FIELD, lỗi kiểm dữ liệu).

Mã điều kiện công bố cứng còn thiếu (PUBLISH_PRECONDITION_FAILED).

Mã điều kiện mềm chưa đạt — không chặn.

Bản hiện tại của hồ sơ khi VERSION_CONFLICT.

Câu tiếng Việt báo phần server đã tự xử lý dù thao tác thành công: HTML Intro bị lọc bớt thẻ (Update), dòng dữ liệu cũ vi phạm luật hiện hành bị bỏ qua khi khôi phục (Versions/Restore).

Branch.Manager (AgencyProfile.ManageOwn) được làm gì với một nhóm trường của bưu cục mình.

Không được sửa — 403.

Sửa trực tiếp.

Không sửa thẳng (ghi trực tiếp vẫn 403 FORBIDDEN_FIELD) mà gửi đề xuất ChangeRequest/Create, người có ChangeRequestReview duyệt thì mới áp vào hồ sơ (GĐ D) — xem .

Ảnh (GĐ A2): tải lên luôn thành chờ duyệt + sắp xếp thư viện ảnh (Gallery). Không sửa/xoá/duyệt ảnh, không sắp xếp vai khác — xem , .

Một dòng của bảng chính sách nhóm trường.

Nhóm trường. Role nào (một trong) được sửa trực tiếp nhóm này trong phạm vi của người đó. Quyền của Branch.Manager trên bưu cục của mình. Nhóm ghi qua POST Update (true) hay qua endpoint riêng (Hours, Routes, Staff, Media, SetStatus).

Một dòng của bảng chính sách nhóm trường.

Nhóm trường. Role nào (một trong) được sửa trực tiếp nhóm này trong phạm vi của người đó. Quyền của Branch.Manager trên bưu cục của mình. Nhóm ghi qua POST Update (true) hay qua endpoint riêng (Hours, Routes, Staff, Media, SetStatus).

Nhóm trường.

Role nào (một trong) được sửa trực tiếp nhóm này trong phạm vi của người đó.

Quyền của Branch.Manager trên bưu cục của mình.

Nhóm ghi qua POST Update (true) hay qua endpoint riêng (Hours, Routes, Staff, Media, SetStatus).

Chính sách ghi theo nhóm trường của hồ sơ bưu cục — bảng hằng đúng plan §3.4, mỗi dòng một ca test (T7). Server là nơi quyết định; cờ Permissions.CanEditGroups trả cho SPA tính từ cùng bảng này.

Người dùng (đã phân giải phạm vi) có được ghi trực tiếp nhóm trường này trên bưu cục trong phạm vi của họ không. Không kiểm bưu cục cụ thể — đó là việc của .

Tải ảnh lên được: có quyền ghi nhóm Media, hoặc Branch.Manager ở chế độ "tải lên chờ duyệt".

Ảnh tải lên có được tự lên web ngay không. Chỉ người phạm vi toàn mạng lưới có quyền ghi nhóm Media — người phạm vi Own (Branch.Manager, kể cả khi được gán thêm role Media) tải gì cũng chờ duyệt: ManageOwn là role giới hạn.

Sắp xếp ảnh của vai : quyền ghi nhóm Media → mọi vai; Branch.Manager → chỉ Gallery.

Gửi được đề xuất sửa nhóm này (GĐ D): Branch.Manager (phạm vi Own) với nhóm ở chế độ mà KHÔNG ghi thẳng được — ai ghi thẳng được (kể cả Branch.Manager được gán thêm role của nhóm) thì dùng Lưu, không đi đường vòng qua người duyệt.

Các nhóm trường người dùng gửi đề xuất được — nguồn của Permissions.CanProposeGroups.

Các nhóm trường người dùng được ghi — nguồn của Permissions.CanEditGroups.

Tên hiển thị, tên đầy đủ và slug của hồ sơ bưu cục (đặc tả §10.3, plan §3.3 "Slug").

và phải cho cùng kết quả với script SeedHoSoBuuCucChoChiNhanhDangHoatDong.sql — đổi luật ở một bên thì đổi cả bên kia.

Tiền tố thương hiệu — một nguồn với trang công khai ().

Cụm cấm trong tên hiển thị, so trên dạng không dấu viết thường (bắt cả khi gõ không dấu).

Pattern:
^[a-z0-9-]{3,120}$
Explanation:
○ Match if at the beginning of the string.
○ Match a character in the set [-0-9a-z] atomically at least 3 and at most 120 times.
○ Match if at the end of the string or if before an ending newline.
Pattern:
[^a-z0-9]+
Explanation:
○ Match a character in the set [^0-9a-z] atomically at least once.
Pattern:
\\s+
Explanation:
○ Match a whitespace character atomically at least once.


"LADA Express – {DisplayName}".

Đoạn đường dẫn cố định của website dưới /buu-cuc/ (GĐ C: tinh/{slug}, gan-toi, tim, su-kien) — hồ sơ mang slug này sẽ không bao giờ mở được trang chi tiết.

Gợi ý tên hiển thị từ tên Agency: lặp bỏ tiền tố "LADA Express"/"LADA"/"Chi nhánh"/"Bưu cục"/"Trung tâm" (không phân biệt hoa thường) khi theo sau là khoảng trắng, "-", "–" hoặc ":"; bỏ dấu phân cách dính đầu; không bỏ nếu tiền tố là toàn bộ tên; rỗng thì dùng mã. "Trung tâm Hải Phòng" → "Hải Phòng".

Lỗi tiếng Việt nếu tên hiển thị không hợp lệ; null nếu hợp lệ.

Slug từ tên hiển thị: ConvertToUnsign → viết thường → mọi chuỗi ký tự ngoài [a-z0-9] thành "-" → tối đa 120 ký tự → cắt "-" hai đầu → ngắn hơn 3 ký tự thì buu-cuc-{agencyId}.

Slug thứ n khi trùng: cắt gốc cho vừa 120 ký tự rồi thêm "-n".

Cờ mức trang cho SPA (rule quyen-hien-thi): SPA không biết role, chỉ đọc cờ === true. Mỗi cờ đọc ĐÚNG bó role của endpoint nó gác — test AgencyProfilePermissionFlagsTests đối chiếu bằng reflection với [Authorize(Roles)].

Trang danh sách — POST Search. Mở chi tiết một hồ sơ — GET Get/{agencyId}. Tách khỏi CanSearch: người chỉ có Search thấy danh sách nhưng Get trả 403. Nút "Tạo hồ sơ" — POST CreateProfile (hộp thoại đọc Lookups, cũng mở cho Update). Trang báo cáo bưu cục + menu — GET Report [Report, ManageOwn] (Branch.Manager xem bưu cục mình). Nút "Ngoại lệ giờ hàng loạt" — POST Hours/Exceptions/BulkUpsert [Hours, ManageOwn]. Hàng động "Tạm ngưng / Mở lại" trên danh sách — POST SetStatus tới Paused/Published đòi role SetStatus (role Close mở được endpoint nhưng chỉ để đóng). SmartTableResult không có chỗ cho cờ từng dòng nên cờ ở mức trang; trạng thái nguồn không hợp lệ thì server trả INVALID_TRANSITION — đó là lời từ chối theo đối tượng, không phải theo quyền (rule quyen-hien-thi §Ranh giới). Link "Sửa ở Quản lý chi nhánh" — màn /quan-ly-chi-nhanh lúc mở gọi Agency/GetTree rồi Agency/Search KHÔNG khai boQuaChuyenHuong403: thiếu một trong hai role là bị đá sang trang "không có quyền". Link "Sửa vùng phủ" — màn /cap-nhat-vung-phu lúc mở gọi AgencyLocation/GetAvailableLocationsTree + GetAgencyCoverage, nút Lưu gọi AddLocation/RemoveLocation; không lời gọi nào khai boQuaChuyenHuong403 — link tên "Sửa" nên cờ gác cả thao tác sửa, không chỉ phần đọc. (searchCityFilter gọi Location/LoSug trong coverage.vue là code chết — template không có ô lọc tỉnh.) Role AgencyLocation.* chưa từng seed (nợ BC-13) ⇒ hôm nay chỉ Founder thấy link. Nút "Xuất CSV" của trang báo cáo — GET Report/Export [Export, ManageOwn]. Dải "N đề xuất chờ duyệt" + hộp thoại hàng đợi — GET ChangeRequest/List [ChangeRequestReview, ManageOwn]: người duyệt thấy mọi bưu cục, Branch.Manager thấy đề xuất của bưu cục mình (trạng thái, lý do từ chối). Nút Duyệt / Từ chối trong hàng đợi — POST ChangeRequest/Approve|Reject [ChangeRequestReview]. Người phạm vi Own (Branch.Manager được gán thêm role duyệt) KHÔNG duyệt được — kể cả đề xuất của chính bưu cục mình (tự duyệt là lách đường duyệt), cùng luật .

Cờ mức trang cho SPA (rule quyen-hien-thi): SPA không biết role, chỉ đọc cờ === true. Mỗi cờ đọc ĐÚNG bó role của endpoint nó gác — test AgencyProfilePermissionFlagsTests đối chiếu bằng reflection với [Authorize(Roles)].

Trang danh sách — POST Search. Mở chi tiết một hồ sơ — GET Get/{agencyId}. Tách khỏi CanSearch: người chỉ có Search thấy danh sách nhưng Get trả 403. Nút "Tạo hồ sơ" — POST CreateProfile (hộp thoại đọc Lookups, cũng mở cho Update). Trang báo cáo bưu cục + menu — GET Report [Report, ManageOwn] (Branch.Manager xem bưu cục mình). Nút "Ngoại lệ giờ hàng loạt" — POST Hours/Exceptions/BulkUpsert [Hours, ManageOwn]. Hàng động "Tạm ngưng / Mở lại" trên danh sách — POST SetStatus tới Paused/Published đòi role SetStatus (role Close mở được endpoint nhưng chỉ để đóng). SmartTableResult không có chỗ cho cờ từng dòng nên cờ ở mức trang; trạng thái nguồn không hợp lệ thì server trả INVALID_TRANSITION — đó là lời từ chối theo đối tượng, không phải theo quyền (rule quyen-hien-thi §Ranh giới). Link "Sửa ở Quản lý chi nhánh" — màn /quan-ly-chi-nhanh lúc mở gọi Agency/GetTree rồi Agency/Search KHÔNG khai boQuaChuyenHuong403: thiếu một trong hai role là bị đá sang trang "không có quyền". Link "Sửa vùng phủ" — màn /cap-nhat-vung-phu lúc mở gọi AgencyLocation/GetAvailableLocationsTree + GetAgencyCoverage, nút Lưu gọi AddLocation/RemoveLocation; không lời gọi nào khai boQuaChuyenHuong403 — link tên "Sửa" nên cờ gác cả thao tác sửa, không chỉ phần đọc. (searchCityFilter gọi Location/LoSug trong coverage.vue là code chết — template không có ô lọc tỉnh.) Role AgencyLocation.* chưa từng seed (nợ BC-13) ⇒ hôm nay chỉ Founder thấy link. Nút "Xuất CSV" của trang báo cáo — GET Report/Export [Export, ManageOwn]. Dải "N đề xuất chờ duyệt" + hộp thoại hàng đợi — GET ChangeRequest/List [ChangeRequestReview, ManageOwn]: người duyệt thấy mọi bưu cục, Branch.Manager thấy đề xuất của bưu cục mình (trạng thái, lý do từ chối). Nút Duyệt / Từ chối trong hàng đợi — POST ChangeRequest/Approve|Reject [ChangeRequestReview]. Người phạm vi Own (Branch.Manager được gán thêm role duyệt) KHÔNG duyệt được — kể cả đề xuất của chính bưu cục mình (tự duyệt là lách đường duyệt), cùng luật .

Trang danh sách — POST Search.

Mở chi tiết một hồ sơ — GET Get/{agencyId}. Tách khỏi CanSearch: người chỉ có Search thấy danh sách nhưng Get trả 403.

Nút "Tạo hồ sơ" — POST CreateProfile (hộp thoại đọc Lookups, cũng mở cho Update).

Trang báo cáo bưu cục + menu — GET Report [Report, ManageOwn] (Branch.Manager xem bưu cục mình).

Nút "Ngoại lệ giờ hàng loạt" — POST Hours/Exceptions/BulkUpsert [Hours, ManageOwn].

Hàng động "Tạm ngưng / Mở lại" trên danh sách — POST SetStatus tới Paused/Published đòi role SetStatus (role Close mở được endpoint nhưng chỉ để đóng). SmartTableResult không có chỗ cho cờ từng dòng nên cờ ở mức trang; trạng thái nguồn không hợp lệ thì server trả INVALID_TRANSITION — đó là lời từ chối theo đối tượng, không phải theo quyền (rule quyen-hien-thi §Ranh giới).

Link "Sửa ở Quản lý chi nhánh" — màn /quan-ly-chi-nhanh lúc mở gọi Agency/GetTree rồi Agency/Search KHÔNG khai boQuaChuyenHuong403: thiếu một trong hai role là bị đá sang trang "không có quyền".

Link "Sửa vùng phủ" — màn /cap-nhat-vung-phu lúc mở gọi AgencyLocation/GetAvailableLocationsTree + GetAgencyCoverage, nút Lưu gọi AddLocation/RemoveLocation; không lời gọi nào khai boQuaChuyenHuong403 — link tên "Sửa" nên cờ gác cả thao tác sửa, không chỉ phần đọc. (searchCityFilter gọi Location/LoSug trong coverage.vue là code chết — template không có ô lọc tỉnh.) Role AgencyLocation.* chưa từng seed (nợ BC-13) ⇒ hôm nay chỉ Founder thấy link.

Nút "Xuất CSV" của trang báo cáo — GET Report/Export [Export, ManageOwn].

Dải "N đề xuất chờ duyệt" + hộp thoại hàng đợi — GET ChangeRequest/List [ChangeRequestReview, ManageOwn]: người duyệt thấy mọi bưu cục, Branch.Manager thấy đề xuất của bưu cục mình (trạng thái, lý do từ chối).

Nút Duyệt / Từ chối trong hàng đợi — POST ChangeRequest/Approve|Reject [ChangeRequestReview]. Người phạm vi Own (Branch.Manager được gán thêm role duyệt) KHÔNG duyệt được — kể cả đề xuất của chính bưu cục mình (tự duyệt là lách đường duyệt), cùng luật .

Cờ trên một hồ sơ cụ thể — ẩn/hiện tab, ô nhập, nút trạng thái.

Nhóm trường được ghi ().

Đích SetStatus vừa có quyền vừa hợp lệ từ trạng thái hiện tại.

Nút tải ảnh — POST Media/Upload. Branch.Manager: true (ảnh thành chờ duyệt).

Ảnh tải lên có được chọn "lên web ngay" không — false thì FE ẩn ô chọn, ảnh nào cũng chờ duyệt.

Kéo sắp xếp thư viện ảnh (Gallery) — POST Media/Reorder. Sắp xếp vai khác, sửa, gỡ ảnh đòi nhóm Media trong .

Duyệt / từ chối đề xuất của bưu cục này — ChangeRequest/Approve|Reject: role ChangeRequestReview VÀ phạm vi toàn mạng lưới (người phạm vi Own không tự duyệt đề xuất của bưu cục mình).

Nhóm trường gửi được đề xuất thay vì Lưu (GĐ D, ) — thẻ nhóm hiện nút "Gửi đề xuất" thay nút Lưu. Không giao với .

Tính cờ quyền bằng hàm thuần từ phạm vi đã phân giải — mỗi cờ một ca test (nợ NavPermissions 9/11 của kho nội dung).

Cờ mức trang — mỗi cờ đọc đúng bó role [Authorize(Roles)] của endpoint nó gác (reflection test).

Role mà màn /quan-ly-chi-nhanh cần ngay lúc mở (AgencyController.GetTree, .Search).

Role mà màn /cap-nhat-vung-phu cần để đọc VÀ sửa (AgencyLocationController.GetAvailableLocationsTree, .GetAgencyCoverage, .AddLocation, .RemoveLocation).

Duyệt đề xuất: role ChangeRequestReview + phạm vi toàn mạng lưới. Service ép cùng hàm này (AgencyProfileService.ApproveChangeRequest) — cờ và hàng rào không thể lệch nhau.

Cờ trên hồ sơ đang ở . Người ngoài phạm vi không bao giờ tới được đây (403 trước).

Bộ lọc danh sách hồ sơ bưu cục, đọc từ SmartTableParam.Search.PredicateObject.

Tỉnh bộ 2 cấp — so với Agency.CityId (bưu cục còn địa chỉ bộ 3 cấp sẽ không khớp, nợ BC-10).

Node khu vực (AgencyType.Region) — lọc theo con cháu trong cây ParentId.

Chỉ hồ sơ còn thiếu điều kiện công bố cứng.

Khoá hỗ trợ: globalSearch, provinceId, publishStatus, agencyType, regionId, missingPublishCondition. Giá trị sai kiểu bị bỏ qua (coi như không lọc) thay vì ném.

Dòng thô của truy vấn danh sách (trước khi gắn điều kiện công bố).

Cha của chi nhánh — tra khu vực bắt đầu từ đây (chi nhánh xoá mềm không có trong cây sống).

Một node của cây chi nhánh (bảng Agency cỡ chục dòng — nạp cả cây vào bộ nhớ).

Một trang tuyến dịch vụ.

Số dòng gộp theo bưu cục (xã vùng phủ, tuyến).

Hình truy vấn EF của phân hệ hồ sơ bưu cục, tách khỏi service để test dịch SQL bằng ToQueryString() (T8) — repository giả chạy LINQ to Objects nên không bắt được lỗi dịch (memory bay-test-in-memory-khong-bat-loi-dich-ef).

Danh sách hồ sơ sau lọc — phạm vi Own ép AgencyId NGAY trong truy vấn, không lọc sau. nên gồm cả chi nhánh đã xoá mềm (QueryAll) để hồ sơ của chúng không biến khỏi danh sách.

Sắp theo Sort.Predicate (không phân biệt hoa thường), mặc định tên hiển thị; luôn thêm AgencyId cho ổn định.

Số xã bộ 2 cấp (Level 3, LevelType 2) trong vùng phủ của từng bưu cục.

Số tuyến (sống) của từng bưu cục.

Trang tuyến = Product có UrlRecord.Slug bắt đầu dich-vu/ (cùng luật ContentServicePageService). UrlRecord.ProductId là int? nên khoá nối ép kiểu tường minh.

Node Region gần nhất đi ngược cây từ (cha của chi nhánh — không xét chính chi nhánh); null nếu lên tới gốc mà không gặp khu vực nào. Chống vòng như .

Node gốc cùng mọi con cháu trong cây ParentId — chống vòng như KpiAgencyScopeResolver.

Tên role của miền hồ sơ bưu cục — một chỗ duy nhất, controller và policy đọc cùng hằng.

Đủ 18 role seed ở SeedRoleHoSoBuuCuc.sql.

Loại phạm vi bưu cục một người dùng được thao tác.

Không bưu cục nào — mọi lời gọi 403.

Chỉ bưu cục của chính mình (User.AgencyId).

Mọi bưu cục.

Người dùng bị từ chối vì bưu cục nằm ngoài phạm vi — service đổi thành 403 FORBIDDEN.

Hai lần ghi cùng lúc từ một phiên bản: DB từ chối người sau (concurrency token VersionNo hoặc unique (AgencyId, VersionNo)) — service đổi thành 409 VERSION_CONFLICT.

Phạm vi đã phân giải của một người dùng: loại phạm vi, bưu cục của họ và danh sách role (đọc từ DB).

User.AgencyId khi = Own; 0 với loại khác.

Có role (Founder coi như có mọi role — cùng luật ServerRoleAuthorizationHandler).

Branch.Manager đúng nghĩa: ManageOwn VÀ phạm vi Own. Chỉ vai này được ManageOwn thay cho role báo cáo / xuất file / đọc hàng đợi (GĐ D, review): người có ManageOwn + Update mang phạm vi toàn mạng lưới — để ManageOwn thay role ở đó là cho họ đọc số và CSV của MỌI bưu cục dù chưa từng được gán Report/Export.

Ném nếu bưu cục ngoài phạm vi. Gọi ở MỌI method nhận agencyId.

Ném nếu người dùng không có phạm vi nào (dùng cho lời gọi không nhận agencyId như Search/Lookups).

Dựng phạm vi bưu cục của người dùng cho phân hệ hồ sơ bưu cục (docs/plan-buu-cuc.md §3.4).

Phạm vi của một người dùng — fail-closed: không xác định được thì .

Luật, theo thứ tự ưu tiên: Founder → mọi bưu cục. AgencyProfile.Update → mọi bưu cục (Network.Admin/Editor). AgencyProfile.ManageOwn → chỉ User.AgencyId; không có AgencyId thì không gì cả. ManageOwn là role GIỚI HẠN: người có nó mà không có Update thì vẫn bị giới hạn kể cả khi được gán thêm role khác của miền (Hours, Routes, Report…) — nếu không, Branch.Manager có sẵn Search/Get sẽ đọc được mọi bưu cục (IDOR). Có bất kỳ role AgencyProfile.* nào khác → mọi bưu cục (người xem/báo cáo toàn mạng lưới). Còn lại → không gì cả. Plan §3.4 chỉ ghi ba nhánh (Update / chỉ ManageOwn / không gì); nhánh 4 là làm rõ khi code A1, ghi ở plan §3.4.

Ngoại lệ giờ cho nhiều bưu cục một lần — nghỉ lễ, đổi giờ cả mạng lưới (docs/plan-buu-cuc.md §3.5 Hours/Exceptions/BulkUpsert, GĐ D; đặc tả §14 ca 11). Cùng luật với Hours/Exceptions/Upsert một ngày.

Đề xuất–duyệt (docs/plan-buu-cuc.md §3.4 cột "đề xuất", §3.14, GĐ D): Branch.Manager không sửa thẳng các nhóm Geo / Content / Routes / ServiceArea / Staff mà gửi đề xuất; người có ChangeRequestReview (phạm vi toàn mạng lưới) duyệt thì đề xuất được áp vào hồ sơ qua ĐÚNG đường ghi sẵn có (UpdateCoreAsync, SetRoutesCoreAsync, UpsertStaffCoreAsync, DeleteStaffCoreAsync) — cùng chuẩn hoá, lọc HTML, luật số điện thoại / cổng chặn / trùng intro, chạy LẠI lúc duyệt vì dữ liệu có thể đã cũ — và sinh một phiên bản mới; từ chối thì hồ sơ không đổi.

Chia file partial cùng thư mục: file này (đọc, sửa hồ sơ, trạng thái, giờ/tuyến/nhân sự, helper ghi), AgencyProfileService.Media.cs (ảnh), AgencyProfileService.Versions.cs (slug, lịch sử, khôi phục), AgencyProfileService.ChangeRequests.cs (đề xuất–duyệt, GĐ D), AgencyProfileService.BulkExceptions.cs (ngoại lệ giờ hàng loạt, GĐ D).

Ảnh hồ sơ bưu cục (plan §3.5 dòng Media, §3.12 "Upload") — theo mẫu TruckMaintenanceMediaService: kiểm phạm vi bưu cục → đọc magic bytes → IUnifiedMediaService.ProcessImageAsync (WebP, bỏ EXIF/GPS) → ghi bảng riêng miền.

Khác mẫu có chủ đích: tự giữ SystemPath/Url/Width/Height, không qua bảng Media dùng chung (plan §3.2); mỗi thao tác ghi qua CommitAsync nên có phiên bản + nhật ký như mọi nhóm trường khác. Mọi mediaId tra kèm AgencyId (bài học nhân sự A1): Id ảnh của bưu cục khác coi như không tồn tại → 404 MEDIA_NOT_FOUND, không lộ, không sửa chéo.

Slug (plan §3.3 "Slug") và lịch sử phiên bản / khôi phục (plan §3.5 dòng Versions, T12–T13).

Tối đa bưu cục một lần áp (mạng lưới hôm nay 5, trần rộng cho nhượng quyền sau này).

Tối đa số ngày một lần áp (Tết dài nhất ~9 ngày; trần một tháng).

Một lượt ghi đi qua luồng đề xuất. : chỉ kiểm dữ liệu và đo "có đổi gì" lúc GỬI đề xuất (không ghi gì, không kiểm khoá phiên bản — đề xuất không phải một lần ghi). Còn lại: áp đề xuất đã duyệt, chạy trong cùng transaction với phiên bản mới.

Ghi chú phiên bản khi áp.

Ghi thêm trong transaction áp (đánh dấu đề xuất đã duyệt + nhật ký); nhận hồ sơ đã tăng phiên bản.

Kết quả: đề xuất có đổi gì so với hồ sơ hiện tại không (lượt kiểm) / đã ghi (lượt áp).

Payload nhóm ghi qua Update sau chuẩn hoá (toạ độ làm tròn, Intro đã lọc HTML, hỏi đáp dạng chuẩn).

Nội dung một đề xuất, lưu JSON ở AgencyChangeRequest.PayloadJson — chỉ các trường của nhóm đề xuất.

Nội dung đề xuất lấy từ model — chỉ các trường của nhóm; chữ đã cắt khoảng trắng.

Lưu bản đã chuẩn hoá (Intro đã lọc HTML, toạ độ làm tròn) — người duyệt thấy đúng thứ sẽ được ghi.

Chạy nội dung đề xuất qua đường ghi của nhóm (kiểm hoặc áp tuỳ ).

Đọc được hàng đợi: người duyệt (role ChangeRequestReview) hoặc Branch.Manager (ManageOwn, phạm vi ép ở truy vấn). Cùng bó role với [Authorize] của ChangeRequest/List và cờ CanViewChangeRequests.

Lưu đề xuất đã xử lý mà không đụng hồ sơ (từ chối / đã có sẵn giá trị) + nhật ký, một transaction. Người khác vừa xử lý cùng lúc (concurrency token Status) → trả 409 CHANGE_REQUEST_CLOSED; thành công → null.

Đọc lại trạng thái từ DB (không qua entity đang theo dõi) — sau một lần ghi hỏng vì ghi đồng thời.

Dòng hàng đợi kèm bảng so sánh. "Hiện tại" đọc từ hồ sơ ĐANG lưu (không phải lúc gửi) — người duyệt so với thứ sắp bị ghi đè. Một lượt nạp cho cả trang.

Một dòng tóm tắt cho hàng đợi và thẻ nhóm ("Đổi toạ độ", "Thêm nhân sự Nguyễn Văn A"…).

Bảng so sánh chữ thuần theo nhóm — FE hiện bằng nội suy văn bản (không v-html).

Chuyển kết quả của đường ghi sang vỏ của luồng đề xuất. Bỏ Current (review GĐ D): 409 của đường ghi kèm hồ sơ đầy đủ (số nội bộ, email, vé xem ảnh chờ duyệt) — người chỉ có role duyệt không gọi được Get thì cũng không được đọc vòng qua Approve. Hàng đợi tự nạp lại bằng ChangeRequest/List.

Cờ bật trang công khai /buu-cuc (migration ChenCauHinhBuuCuc, mặc định false — plan §3.6).

Thân của Update. null = người gọi sửa thẳng (kiểm quyền nhóm, khoá phiên bản). Khác null = luồng đề xuất (GĐ D) đã tự kiểm quyền: chỉ kiểm dữ liệu lúc gửi đề xuất (không ghi); ngược lại áp đề xuất đã duyệt — CÙNG chuẩn hoá, lọc HTML, luật số điện thoại / cổng chặn / trùng intro như sửa thẳng (dữ liệu có thể đã cũ từ lúc gửi), ghi kèm trong cùng transaction.

Ghi các trường của một nhóm từ (đã chuẩn hoá + kiểm) vào hồ sơ; trường đổi giá trị thì ghi vào dạng { From, To }. Dùng chung cho Update và Versions/Restore.

Chuẩn bị nhóm Content trước khi kiểm: Intro qua (cùng lớp Ganss của bài viết, chính sách chữ định dạng: giữ chữ, không thuộc tính/link/ảnh — số điện thoại không giấu được vào href="tel:"/title, luật số chạy trên chữ thuần mới đủ). Hồ sơ LƯU bản đã lọc, không lưu HTML thô. FaqJson hợp lệ thì ghi lại dạng chuẩn [{"Q","A"}] (chữ thuần — trang công khai phải encode). Trả câu báo nếu bộ lọc đã cắt bớt thứ gì.

Thân của Routes/Set — như .

Thân của Staff/Upsert — như .

Thân của Staff/Delete — như .

Sắp lại thứ tự nhân sự hiển thị — một lần ghi, một phiên bản (khuôn ). Phải gửi đủ đúng tập nhân sự hiện có; id lạ (kể cả của bưu cục khác) → STAFF_NOT_FOUND, không lộ tồn tại.

Bản đã chuẩn hoá của payload: chuỗi cắt khoảng trắng (rỗng → null), số điện thoại về E.164, toạ độ 6 chữ số.

Câu DUPLICATE_INTRO có nêu tên + Id + % của hồ sơ trùng không. False cho người phạm vi Own (review GĐ D): từ GĐ D Branch.Manager chạy được luật trùng intro trên chữ TỰ GÕ (lượt kiểm đề xuất, không giới hạn số lần) — nêu tên/% là cho họ dò nội dung intro chưa công bố của bưu cục ngoài phạm vi.

Số điện thoại (PHONE_IN_CONTENT, đặc tả §10.3) và luật cứng cổng chặn (CONTENT_GATE) trên các đoạn chữ.

Nạp một lượt dữ liệu điều kiện công bố cho nhiều bưu cục.

Dấu vân tay intro của mọi hồ sơ chưa xoá — một truy vấn, tính trigram trong bộ nhớ.

Lượt bấm gọi 30 ngày gần nhất tính tới hết hôm qua (giờ Việt Nam) — nguồn AgencyWebEventDaily; hôm nay chưa gộp (job 01:10). Một truy vấn cho cả trang danh sách.

Một lần ghi thành công: VersionNo++, (tuỳ) ContentUpdatedAt, ghi bảng con, lưu hồ sơ, snapshot phiên bản mới và nhật ký — trong MỘT transaction (plan §3.3 "Khoá lạc quan").

Phần ghi của KHÔNG mở transaction — người gọi giữ transaction. Tách ra cho ngoại lệ giờ hàng loạt (GĐ D): nhiều hồ sơ, mỗi hồ sơ một phiên bản + nhật ký, tất cả trong MỘT transaction (áp đủ hoặc không gì).

Ghép phần ghi bảng con của một thao tác với phần ghi của luồng duyệt đề xuất (đánh dấu đề xuất đã duyệt + nhật ký) — cả hai chạy trong transaction của , sau khi VersionNo đã tăng.

Kết quả lượt kiểm đề xuất: không dựng hồ sơ (không ai đọc), chỉ mang câu báo lọc HTML.

Bản sao các trường ghi — để lượt kiểm đề xuất đo "có đổi gì" mà không sửa entity đang theo dõi.

Lần ghi bị DB từ chối vì người khác vừa ghi cùng phiên bản: DbUpdateConcurrencyException (concurrency token VersionNo, Repository.UpdateAsync giữ nó làm inner) hoặc trùng UX_AgencyProfileVersion_AgencyId_VersionNo (Repository.InsertAsync chỉ giữ chuỗi lỗi nên phải dò theo tên index).

Slug chưa bị hồ sơ khác (sống) hay lịch sử slug (kể cả dòng xoá mềm) chiếm; trùng thì thêm "-2", "-3"…

Ngày theo lịch Việt Nam của một giá trị DateTime nhận từ JSON. "2026-09-02" (Unspecified) giữ nguyên ngày; "2026-09-01T17:00:00Z" — cách JSON.stringify ghi 00:00 ngày 02/09 giờ VN — là ngày 02/09, không phải 01/09.

Trần dung lượng một ảnh (plan §3.5). [RequestSizeLimit] controller chỉ chặn cả request.

Trần điểm ảnh đọc từ header TRƯỚC khi giải mã: 10 MB PNG nén tốt có thể bung ra hàng tỷ điểm ảnh (bom giải nén). 64 MP phủ ảnh chụp điện thoại ở chế độ mặc định (12–50 MP).

Số ảnh tối đa một bưu cục (chưa xoá) — chặn tải lên vô hạn.

File để API trả cho GET Media/Preview/{mediaId} (ảnh chờ duyệt không có URL công khai — BC-14). Vé ký HMAC do Get cấp cho người đã qua phạm vi bưu cục; sai vé / hết hạn / ảnh đã gỡ → null (controller 404, không lộ gì).

Vai, alt (bắt buộc), chú thích; số điện thoại + cổng chặn trên alt và chú thích — chữ này lên web.

Loại ảnh theo chữ ký đầu file; null nếu không phải JPEG/PNG/WebP.

Đọc header bằng Magick (không giải mã điểm ảnh): định dạng phải khớp chữ ký, kích thước khác 0 và không vượt . Trả câu lỗi hoặc null.

Đường dẫn lưu vào AgencyMedia.SystemPath: tương đối dưới AppConfig Media.RootPath (đổi ổ đĩa không phải sửa dữ liệu); nằm ngoài gốc (cấu hình lạ) thì giữ nguyên đường dẫn tuyệt đối.

Nhóm trường khôi phục được — đúng tám nhóm ghi qua Update; trạng thái công bố thì không.

Đọc ảnh chụp cũ: thuộc tính lạ bỏ qua, thuộc tính thiếu mang giá trị mặc định.

Slug mới trùng hồ sơ sống khác, hoặc trùng AgencySlugHistory của bưu cục KHÁC (kể cả dòng xoá mềm) → 409 SLUG_TAKEN: link cũ ngoài internet đang 301 về bưu cục đó, cấp lại là đổi đích của link. Quay về đúng một slug cũ của CHÍNH bưu cục này: cho phép (chốt A2 2026-09-17, plan §3.3) — link cũ vốn trỏ chính bưu cục này nên sống lại không đổi đích của link nào; cấm thì một lần gõ nhầm là mất vĩnh viễn slug đẹp. Dòng lịch sử của slug đó bị xoá mềm (slug đang sống không còn là "slug cũ"); đổi đi lần nữa thì dòng được dựng lại — không chèn dòng mới vì unique OldSlug không lọc xoá mềm.

Các lần ghi AgencySlugHistory chờ chạy trong transaction của CommitAsync.

Đưa slug đang dùng vào lịch sử để 301: chưa có dòng → chèn; có dòng (kể cả xoá mềm) của chính bưu cục → dựng lại và đóng dấu giờ đổi mới; dòng thuộc bưu cục khác (không xảy ra nếu dữ liệu đúng bất biến) → giữ nguyên, không cướp.

Tạo phiên bản MỚI từ nội dung phiên bản cũ (T13: đang ở 3, khôi phục 2 → phiên bản 4 = nội dung 2); lịch sử cũ giữ nguyên. Khôi phục: tám nhóm trường của hồ sơ, giờ tuần, ngoại lệ giờ, tuyến, nhân sự hiển thị. KHÔNG khôi phục — có chủ đích: PublishStatus, PublishedAt, ClosedAt, RedirectToAgencyId: trạng thái chỉ đổi qua máy trạng thái — khôi phục mà đưa hồ sơ về Published là lách điều kiện công bố. Slug: chỉ đổi qua ChangeSlug để slug cũ vào lịch sử 301; khôi phục âm thầm đổi slug là làm gãy link. Ảnh: dòng ảnh có file vật lý và quyết định duyệt riêng — ảnh đã gỡ/bỏ duyệt có thể vì lý do nhạy cảm, khôi phục không được đưa nó quay lại web. ContentUpdatedAt: là dấu thời gian hệ thống — lần khôi phục chính là một lần đổi nội dung mới. Dữ liệu cũ vi phạm luật hiện hành (tên có chữ "LADA", số sai đầu số, intro có số điện thoại, tuyến trỏ trang đã xoá, nhân sự thiếu tên…) không làm hỏng cả lượt: nhóm trường / dòng đó giữ nguyên hiện tại và có một câu trong Notices. Ảnh chụp thiếu hẳn một phần (thuộc tính hay mảng vắng mặt trong JSON cũ) → phần đó giữ nguyên hiện tại chứ không bị coi là "rỗng".

Ảnh chụp đã đọc kèm JSON gốc — để biết phần nào VẮNG MẶT (khác với "rỗng").

Ảnh chụp đã đọc kèm JSON gốc — để biết phần nào VẮNG MẶT (khác với "rỗng").

Tám nhóm trường: dựng payload như một lần Update từ ảnh chụp (thuộc tính vắng mặt lấy giá trị hiện tại), kiểm TỪNG nhóm bằng đúng ValidateUpdateAsync; nhóm vi phạm luật hiện hành giữ nguyên + một câu báo.

Giờ tuần: ngày có trong ảnh chụp và hợp lệ → ghi; ngày không có → gỡ; ngày sai luật → giữ hiện tại.

Ngoại lệ giờ theo ngày: có trong ảnh chụp và hợp lệ → ghi; không có → gỡ; sai luật → giữ hiện tại.

Tuyến: dòng trỏ trang không còn là trang tuyến dich-vu/ (đã xoá, đổi slug) bị bỏ kèm câu báo.

Nhân sự hiển thị: ảnh chụp không lưu Id nên ghép theo (họ tên, chức danh) không phân biệt hoa thường — đúng khoá chống trùng của UpsertStaff. Dòng thiếu tên/chức danh hoặc có số điện thoại bị bỏ; ảnh chân dung đã gỡ → bỏ ảnh.

Truy vấn hàng đợi đề xuất — hàm tĩnh trả IQueryable để service và test ToQueryString() chạy CÙNG một truy vấn (review GĐ D: test dựng lại tay không bắt được biểu thức không dịch được sang SQL).

Đề xuất trong phạm vi: (phạm vi Own) ép trước, rồi lọc bưu cục nếu có.

Lọc trạng thái (status ≤ 0 = mọi trạng thái).

Một trang: đề xuất chờ lên đầu, rồi mới nhất trước.

Hồ sơ công khai của bưu cục (docs/plan-buu-cuc.md §3.3–§3.5, GĐ A1). Mọi method nhận agencyId đều ép phạm vi qua ngay đầu hàm — không trông vào controller.

Danh sách hồ sơ trong phạm vi; phạm vi Own chỉ trả bưu cục của mình.

Chi tiết hồ sơ + Agency lõi (chỉ đọc) + giờ + tuyến + nhân sự + điều kiện đăng + cờ quyền.

Tạo hồ sơ nháp cho Agency LadaBranch/Franchise chưa có hồ sơ; sinh slug từ tên hiển thị.

Sửa theo nhóm trường với khoá lạc quan.

Công bố / tạm ngưng / đóng.

Mở lại hồ sơ đã đóng về nháp.

Ghi giờ làm việc đủ 7 ngày.

File ảnh cho vé xem trước (BC-14); null khi vé sai/hết hạn hoặc ảnh không còn.

Thêm/sửa/gỡ ngoại lệ giờ một ngày.

Thay toàn bộ tuyến.

Thêm/sửa nhân sự hiển thị.

Gỡ nhân sự hiển thị.

Tải một ảnh lên (JPEG/PNG/WebP thật, ≤ 10 MB). Branch.Manager tải lên thì ảnh chờ duyệt.

Sửa vai / alt / chú thích / cờ ảnh thật / thứ tự của một ảnh.

Gỡ một ảnh (xoá mềm) và gỡ tham chiếu Open Graph / chân dung nhân sự tới nó.

Sắp lại thứ tự ảnh của một vai. Branch.Manager chỉ sắp được thư viện ảnh.

Duyệt / bỏ duyệt một ảnh.

Đổi slug; slug cũ vào lịch sử cho 301.

Lịch sử phiên bản (không kèm ảnh chụp), mới nhất trước.

Một phiên bản kèm ảnh chụp.

Khôi phục nội dung một phiên bản cũ thành phiên bản mới.

Danh mục chọn: tỉnh bộ 2 cấp, trang tuyến, loại hàng, chi nhánh chưa có hồ sơ.

Cờ mức trang — trả cho mọi người đã đăng nhập, không gác role.

Ngoại lệ giờ cho nhiều bưu cục một lần (GĐ D) — mỗi bưu cục một phiên bản, tất cả một transaction.

Branch.Manager gửi đề xuất sửa một nhóm trường (GĐ D).

Hàng đợi đề xuất trong phạm vi người gọi, kèm bảng so sánh hiện tại ↔ đề xuất.

Duyệt: áp đề xuất vào hồ sơ qua đúng đường ghi sẵn có, một phiên bản mới.

Từ chối: hồ sơ không đổi, lý do trả cho Branch.Manager.

Khuôn JSON của AgencyProfileVersion.SnapshotJson (Newtonsoft mặc định: PascalCase, enum là số).

Script SeedHoSoBuuCucChoChiNhanhDangHoatDong.sql dựng phiên bản 1 của hồ sơ seed bằng FOR JSON theo đúng khuôn này — thêm/đổi tên thuộc tính ở đây thì đổi cả script (hoặc để khôi phục GĐ A2 chịu được thuộc tính thiếu).

Máy trạng thái công bố (đặc tả §10.2, plan §3.3) — hàm thuần, 7 chuyển hợp lệ: Draft→Published, Published→Paused, Paused→Published, Draft/Published/Paused→Closed (qua SetStatus) và Closed→Draft (chỉ qua Reopen).

Chuyển qua SetStatus có hợp lệ không (không gồm Reopen).

Mở lại chỉ từ Closed.

Các đích SetStatus hợp lệ từ một trạng thái.

Kiểm số điện thoại, toạ độ, link — dùng chung cho Update (chặn sớm) và điều kiện công bố (plan §3.3 #2, #3).

Khung lãnh thổ Việt Nam thô cho điều kiện #2.

Khung lãnh thổ Việt Nam thô cho điều kiện #2.

Khung lãnh thổ Việt Nam thô cho điều kiện #2.

Khung lãnh thổ Việt Nam thô cho điều kiện #2.

Pattern:
^\\+84[1-9]\\d{7,9}$
Explanation:
○ Match if at the beginning of the string.
○ Match the string "+84".
○ Match a character in the set [1-9].
○ Match a Unicode digit atomically at least 7 and at most 9 times.
○ Match if at the end of the string or if before an ending newline.
Pattern:
[\\s.\\-()]
Explanation:
○ Match a character in the set [()-.\s].
Pattern:
^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$
Explanation:
○ Match if at the beginning of the string.
○ Match a character in the set [^@\s] atomically at least once.
○ Match '@'.
○ Match a character in the set [^@\s] greedily at least once.
○ Match '.'.
○ Match a character in the set [^@\s] atomically at least once.
○ Match if at the end of the string or if before an ending newline.


Chuẩn hoá số người dùng gõ về E.164: bỏ khoảng trắng/dấu chấm/gạch/ngoặc, "0…" → "+84…", "84…" → "+84…", tổng đài "1900…"/"1800…" → "+841900…"/"+841800…", và bỏ số 0 gõ thừa ngay sau mã nước ("+84 0912…" → "+84912…"). Không đoán gì thêm — kết quả vẫn phải qua .

Số 1900/1800 lưu dạng "+841900…" cho đồng nhất cột và cho luật đầu số; khi hiển thị/dựng tel: (GĐ C) phải đổi về dạng quốc nội "1900…" vì nhiều nhà mạng không gọi được tổng đài qua +84.

E.164 Việt Nam: ^\+84[1-9]\d{7,9}$.

Tách danh sách đầu số AppConfig Network.AllowedPhonePrefixes (phẩy, chấm phẩy, khoảng trắng).

Đầu số có nằm trong danh sách cho phép không. Danh sách rỗng = không hạn chế. Một đầu số khớp khi số dạng quốc nội (0…) hoặc phần sau +84 bắt đầu bằng nó — để "0225" và "1900" đều viết được tự nhiên.

Link tuyệt đối http/https.

Ghi chú mặc định của một phiên bản hồ sơ khi người sửa không ghi gì. Ghi chú hiện NGUYÊN VĂN ở lịch sử phiên bản trên portal — trước bấm thật B2 nó là tên thao tác nội bộ (UpsertHours, ReorderStaff…). Tên thao tác tiếng Anh vẫn đi vào nhật ký (AgencyProfileAuditLog.Action) cho máy đọc; ở đây chỉ là chữ cho người đọc.

Mọi tên thao tác đã có nhãn — test đối chiếu với các lời gọi CommitAsync trong service.

Nhãn tiếng Việt của thao tác; thao tác chưa có nhãn thì trả lại chính tên (không nuốt thông tin).

"Sửa: Liên hệ; Toạ độ" — nhãn nhóm lấy từ [Description] của enum (cùng nguồn với Lookups.FieldGroups).

"Chuyển sang «Tạm ngưng»".

Dữ liệu đã nạp sẵn để chạy điều kiện công bố của một hồ sơ.

Agency lõi (đã lọc xoá mềm) — null nếu đã xoá.

Location mà Agency.CityId trỏ tới (null nếu không có hoặc đã xoá).

Location mà Agency.WardId trỏ tới.

Số xã bộ 2 cấp thuộc vùng phủ (Location.AgencyId, Level 3, LevelType 2).

AppConfig Network.AllowedPhonePrefixes đã tách; rỗng = không hạn chế.

Mọi ảnh chưa xoá của bưu cục — cả ảnh chờ duyệt; điều kiện tự lọc .

Intro của mọi hồ sơ (kể cả chính nó) — nạp một lần cho cả lượt, dùng cho DUPLICATE_INTRO.

Một điều kiện chưa đạt.

Mã máy — tên trường/khối để tab SEO trỏ tới (vd Latitude, Hours).

Câu tiếng Việt cho người dùng.

true = điều kiện cứng, chặn công bố.

Trường chứa lỗi khi mã là lỗi nội dung (Intro, Faq[1].A, Media[12].Caption…); null nếu không áp dụng.

Vị trí trong trường ("dòng 2, ký tự 15"); null nếu không áp dụng.

Mã luật cổng chặn (GATE_01_HOTLINE_CU…) khi mã là CONTENT_GATE.

Bưu cục có intro trùng khi mã là DUPLICATE_INTRO.

Kết quả "Kiểm tra điều kiện đăng".

Thêm một issue dựng sẵn (lỗi nội dung có trường/vị trí/luật).

Một nhóm điều kiện công bố. Service nhận IEnumerable các điều kiện qua DI — GĐ A2 thêm #5 (ảnh), #6 (intro), #10 (cổng chặn nội dung) bằng cách đăng ký thêm lớp, không sửa hàm công bố.

Điều kiện công bố làm được ở GĐ A1: #1 (Agency + địa chỉ bộ 2 cấp + tên hiển thị), #2 (toạ độ), #3 (số chính), #4 (≥ 5 ngày có giờ), #7 (vùng phủ), #8 mềm (tuyến), #9 mềm (độ dài meta). Plan §3.3.

Tỉnh là Location sống Level 1 LevelType 2; xã là Location sống Level 3 LevelType 2 thuộc đúng tỉnh đó. Bộ 2 cấp không có Level 2 và ParentId của xã trỏ thẳng tỉnh (Việc 0 Đ6).

Dựng CSV cho báo cáo bưu cục (GĐ D) — repo chưa có tiền lệ CSV server-side (Việc 0 D3). Excel đọc đúng tiếng Việt nhờ BOM UTF-8; ô chữ theo RFC 4180, luôn bọc nháy kép (nháy bên trong nhân đôi); ô số ghi thẳng.

Chống CSV/formula injection: nguồn truy cập (utm_source, host referrer) và đường dẫn trang của AgencyWebEvent là chữ TỰ DO do trình duyệt khách gửi. Ô chữ bắt đầu bằng = + - @, tab hay CR bị Excel/LibreOffice hiểu là công thức (=HYPERLINK(...), =cmd|...) ⇒ thêm dấu ' ở đầu (khuyến nghị OWASP). Áp cho MỌI ô chữ, kể cả tên bưu cục — một hàm duy nhất, không phân biệt nguồn "tin được". Ô số ghi thẳng.

Một ô chữ đã chống công thức + thoát theo RFC 4180. Luôn bọc nháy kép (review GĐ D): máy đặt dấu phân cách danh sách là ; (vùng de/fr… hoặc tự chỉnh) mở CSV thì Excel tách ô tại ; — ô không bọc nháy x;=cmd|… thành ô mới bắt đầu bằng =. Trong nháy kép, mọi dấu phân cách là chữ.

Một ô số (không bao giờ bị hiểu là công thức — chỉ chữ số).

Ghép các dòng (mỗi dòng là các ô ĐÃ thoát) thành file CSV UTF-8 có BOM, xuống dòng CRLF.

Nguồn đọc hai bảng sự kiện trang bưu cục. Hai bảng cố ý không kế thừa BaseEntity (bảng ghi thô / số dẫn xuất) nên không có IRepository<T> (Repository<T> where T : BaseEntity) — lớp mỏng này cho service đọc qua mà test vẫn thay được bằng dữ liệu bộ nhớ.

Sự kiện thô (giữ 13 tháng).

Số gộp theo ngày (job network-gop-su-kien-ngay).

Số sự kiện của một bưu cục × một loại trong một khoảng thời gian.

Một phiên (SessionHash) có sự kiện loại — thời điểm đầu tiên để biết ngày.

Số sự kiện theo nguồn × loại × phiên — gom nhãn nguồn ở C# mà vẫn đếm phiên khác nhau đúng.

Số sự kiện theo một khoá chữ (nguồn truy cập / đường dẫn trang) × loại.

Truy vấn và quy ước ngày của số đo trang bưu cục (GĐ D). Hàm tĩnh trả IQueryable để test hình SQL bằng ToQueryString() (bẫy "test bộ nhớ không bắt lỗi dịch EF").

Số ngày job gộp tính lại mỗi lần chạy: hôm qua + 2 ngày trước (phòng lần chạy bị lỡ vì máy chủ tắt).

Giữ sự kiện thô bấy nhiêu tháng (plan §3.2).

Ngày hiện tại theo giờ Việt Nam.

Khoảng [00:00, 00:00 hôm sau) giờ Việt Nam của một ngày. AgencyWebEvent.CreatedAt là DateTimeOffset.Now của máy chủ web (Việc 0 D2) — so datetimeoffset trên SQL Server là so thời điểm tuyệt đối nên đúng với mọi offset đã lưu; CAST(CreatedAt AS date) thì lấy ngày theo offset LƯU, sai khi máy chủ không chạy giờ Việt Nam.

Mốc cắt giữ sự kiện thô: 00:00 giờ Việt Nam của ngày cách hôm nay tháng — job dọn xoá mọi sự kiện trước mốc; báo cáo tháng bắt đầu trước mốc thì không còn bảng nguồn truy cập / trang.

Đếm lượt + phiên theo bưu cục × loại trong [from, to) — nguồn của một ngày AgencyWebEventDaily.

Lượt bấm gọi theo bưu cục trong các ngày [fromDate, toDate] (cột "Gọi 30n" của danh sách portal).

Dòng gộp ngày của các bưu cục trong [fromDate, toDate] — nguồn chính của báo cáo.

Đếm theo SourceJson nguyên chuỗi × loại × phiên; gom thành nhãn nguồn ở C# (, SQL Server của repo không dùng hàm JSON). Giữ phiên trong khoá để phiên khác nhau của MỘT nhãn đếm đúng khi nhiều chuỗi JSON ra cùng nhãn (cùng utm_source, khác utm_campaign/referrer) — cộng COUNT DISTINCT từng chuỗi là đếm lặp (review GĐ D).

Mỗi (loại, phiên) một dòng kèm thời điểm đầu — số phiên khác nhau trên CẢ phạm vi (không cộng theo bưu cục: một khách xem 2 bưu cục là 1 phiên). Hash phiên có ngày giờ VN trong công thức nên mọi sự kiện của một hash cùng một ngày.

Đếm theo đường dẫn trang × loại.

Nhãn nguồn của một SourceJson ({"referrer": host, "utm_source": …} do website ghi): utm_source nếu có, không thì host referrer, không thì "(trực tiếp)". Chữ do trình duyệt khách gửi — người hiển thị phải mã hoá (portal nội suy văn bản, CSV qua ).

Nhãn cho sự kiện không mang utm lẫn referrer.

File báo cáo đã dựng.

Báo cáo bưu cục theo tháng (docs/plan-buu-cuc.md §3.5 Report, Report/Export, GĐ D; đặc tả §6.4): lượt + phiên theo bưu cục × loại sự kiện từ AgencyWebEventDaily; nguồn truy cập / trang từ sự kiện thô. Phạm vi ép ở câu truy vấn — Branch.Manager chỉ có bưu cục của mình, kể cả khi xuất file.

CSV của một bảng: agencies (mặc định), daily, sources, pages.

Số dòng tối đa của bảng nguồn truy cập / trang.

Xem báo cáo: role Report, hoặc Branch.Manager phạm vi Own (ép về bưu cục mình). ManageOwn không thay role ở phạm vi toàn mạng lưới ().

Xuất file: role Export, hoặc Branch.Manager phạm vi Own (ép về bưu cục mình).

Tháng yyyy-MM → ngày đầu tháng; trống = tháng hiện tại giờ Việt Nam.

Top nguồn: gom các chuỗi SourceJson ra cùng nhãn; lượt cộng, phiên đếm hash KHÁC NHAU của nhãn (không cộng số phiên từng chuỗi — một phiên có thể mang hai chuỗi cùng nhãn).

Top trang: mỗi đường dẫn là một nhãn riêng nên COUNT DISTINCT của SQL đã đúng.

Trang "Quản trị nhượng quyền" (/mang-luoi/quan-tri-nhuong-quyen) gộp bốn màn cũ thành bốn tab: Bảng giá · Quản trị bảng giá · Nội dung cổng · Trợ lý AI. Chủ dự án 2026-10-23: "Trang mới chỉ có quản lý mạng lưới hoặc founder mới được xem".

"Quản lý mạng lưới" là một NHÓM quyền (bó role, SeedNhomQuyenQuanLyMangLuoi.sql), không phải role — máy chủ chỉ đọc role phẳng. Role phân biệt nhóm đó với "Mạng lưới 2" là : GĐ L rút nó khỏi "Mạng lưới 2" (RutQuyenQuanLyKhoiNhomMangLuoi2.sql), trong khi "Mạng lưới 2" vẫn giữ FranchisePrice.Manage và FranchisePortal.Content — gác bằng role của từng tab là để lọt đúng nhóm phải chặn. Cờ của từng tab = cờ trang AND cờ sẵn có của màn cũ (, ) — một luật sống ở một chỗ. Đây là hàng rào HIỂN THỊ (menu + trang); [Authorize] của các API bên dưới giữ nguyên.

Vai bỏ qua mọi kiểm tra role của hệ thống — ẩn trang của Founder là dựng hàng rào không có thật.

Role chỉ nhóm "Quản lý mạng lưới" có — vào được trang.

Role đã phân giải qua IUserRoleResolver; null = không có role nào

Cờ hiển thị của trang "Quản trị nhượng quyền"; CanView = false thì mọi cờ con đều tắt.

Cờ hiển thị của trang "Quản trị nhượng quyền"; CanView = false thì mọi cờ con đều tắt.

Màn tham số mục "Kế hoạch kinh doanh" của cổng nhượng quyền /mang-luoi/bang-gia-nhuong-quyen/ke-hoach (GĐ M, plan cổng §3.13, §6.24): xem + tính thử (FranchisePrice.Export / Manage), sửa cả bộ (Manage). Không thêm / xoá bậc — năm dòng bậc và một dòng tham số seed bằng migration.

Cả bộ tham số; null = không có quyền xem.

Tính thử với số phường mỗi bậc do người dùng gõ + tham số đang sửa (chưa lưu). Không ghi gì, không đọc phường của bất kỳ mã truy cập nào.

Dấu phiên bản của cả bộ — đổi khi bất kỳ bậc nào hay dòng tham số được lưu.

Chép bản nháp vào dòng thật; true = có ô đổi.

Một cột thời gian chờ: số ngày kể từ lần cập nhật gần nhất nằm trong [MinDays, MaxDays].

Một cột thời gian chờ: số ngày kể từ lần cập nhật gần nhất nằm trong [MinDays, MaxDays].

Một đăng ký rút gọn cho báo cáo — LastActivity = UpdatedTime ?? CreatedTime.

Một đăng ký rút gọn cho báo cáo — LastActivity = UpdatedTime ?? CreatedTime.

Báo cáo tồn đọng đăng ký nhượng quyền (POST api/FranchiseLead/backlog) — hàm thuần, theo khuôn backlog đơn hàng nhưng nhóm theo tỉnh đăng ký thay cho bưu cục. Thời gian chờ = số NGÀY LỊCH (giờ Việt Nam) từ lần cập nhật gần nhất (UpdatedTime: đổi trạng thái, ghi chú, sửa, giao người, cổng tự đổi trạng thái; chưa có thì CreatedTime) tới hôm nay. Đang xử lý = mọi trạng thái trừ Đã ký hợp đồng và Không phù hợp — chỉ chúng có thời gian chờ; bảng theo tỉnh vẫn đếm cả hai trạng thái đã đóng. Bấm vào ô thì giao diện gọi search với đúng khoá của ô (status, provinceCode, idleMinDays/idleMaxDays, openOnly) — các khoá đó lọc bằng , , ở đây, nên số trong ô và số dòng danh sách là một phép đếm.

Khoá lọc của đăng ký không có mã tỉnh (dữ liệu chuyển từ bảng Lead cũ).

Đăng ký nhượng quyền đi chậm hơn đơn hàng: ba ngày đầu tách riêng, sau đó gộp theo tuần / nửa tháng / tháng.

Trạng thái còn phải xử lý — mọi trạng thái trừ hai trạng thái sale đã chốt xong.

Khoá tỉnh của một đăng ký: mã rỗng gộp vào .

Số ngày lịch (giờ Việt Nam) từ tới hôm nay; mốc tương lai tính 0, không có mốc tính là cũ nhất.

Vị trí cột của một số ngày chờ trong .

Lọc đăng ký có số ngày chờ trong [, ] — cùng phép tính với , dịch ra mốc giờ để SQL so được: ngày chờ ≥ a ⇔ mốc < đầu ngày (hôm nay − a + 1); ngày chờ ≤ b ⇔ mốc ≥ đầu ngày (hôm nay − b).

Lọc theo khoá tỉnh của .

Lọc các trạng thái đang xử lý ().

Phép chiếu đọc từ DB — chỉ bốn cột cần cho hai bảng, không kéo dữ liệu cá nhân của đăng ký về.

Tỉnh trong vùng phủ trước, rồi "Tỉnh, thành khác", cuối cùng là đăng ký không có tỉnh.

Tên theo danh mục nếu có; không thì tên người gửi thấy lúc chọn (lấy tên gặp nhiều nhất), cuối cùng là mã.

File Excel của nút Xuất ở màn "Đăng ký nhượng quyền". Hàm thuần: nhận dòng đã lọc theo phạm vi, trả byte — mọi ô ghi dạng giá trị (không công thức), nên chuỗi người gửi bắt đầu bằng = không thành công thức.

Dòng đã lọc theo phạm vi, đúng thứ tự xuất. Lần khách vào xem cổng gần nhất theo FranchiseLead.Id (); đăng ký không có trong đây = khách chưa vào cổng, ô để trống. null = để trống cả cột.

Màn "Đăng ký nhượng quyền": nút nào được hiện (rule quyen-hien-thi) và mỗi người thấy những đăng ký nào. Hàm thuần cùng khuôn : nhận role đã phân giải qua IUserRoleResolver — để luật "ai thấy gì" có ca test gọi thẳng vào nó.

Vai bỏ qua mọi kiểm tra role của hệ thống — ẩn nút của Founder là dựng hàng rào không có thật.

Role xem/sửa/đổi trạng thái đăng ký MÌNH phụ trách và nhập tay đăng ký mới: search, {id}, {id}/history, update-status, create, update.

Role quản lý: thấy tất cả + assign, assignees, export.

Role đã phân giải qua IUserRoleResolver; null = không có role nào

Phạm vi dữ liệu — MỘT hàm cho Search, GetById, GetHistory, Update, UpdateStatus và Export: Manage/Founder thấy tất cả; chỉ có Search thì chỉ thấy đăng ký mình phụ trách (PicId = mình); không role thì không thấy gì.

Cờ hiển thị của màn "Đăng ký nhượng quyền".

Cờ hiển thị của màn "Đăng ký nhượng quyền".

Bộ lọc màn "Đăng ký nhượng quyền", đọc từ Search.PredicateObject. Khoá (không phân biệt hoa thường): globalSearch — NQ000123 tìm theo mã (cả mã cũ theo LegacyLeadId của dòng chuyển từ Lead); toàn chữ số tìm trong SĐT; còn lại tìm họ tên, SĐT, khu vực. status — số của . provinceCode — Location.Code, khac, hoặc chua-ro (đăng ký không có mã tỉnh — ô của báo cáo tồn đọng, ). picId — người phụ trách; 0 = chưa giao. channel — số của . fromDate, toDate — ngày gửi, tính theo giờ Việt Nam, gồm cả hai đầu. Nhận yyyy-MM-dd hoặc chuỗi ISO có giờ (...Z, ...+07:00 — kiểu JSON.stringify(Date)): quy về ngày theo giờ Việt Nam. updatedFromDate, updatedToDate — ngày cập nhật gần nhất (UpdatedTime: đổi trạng thái, ghi chú, sửa thông tin, giao người, hoặc cổng tự đổi trạng thái), cùng cách đọc với fromDate/toDate. portalSeenFromDate, portalSeenToDate — ngày khách vào xem Cổng nhượng quyền gần nhất (), cùng cách đọc; đăng ký khách chưa vào cổng không bao giờ khớp. Cần portal ở . idleMinDays, idleMaxDays — số ngày chờ kể từ lần cập nhật gần nhất, gồm cả hai đầu () — cột của báo cáo tồn đọng gửi lại nguyên văn. openOnly — true = chỉ trạng thái đang xử lý (). appointmentFromDate, appointmentToDate — ngày hẹn gặp / khảo sát (AppointmentAt, plan cổng §6.29), cùng cách đọc với fromDate/toDate; đăng ký chưa từng ghi lịch không bao giờ khớp. Không lọc trạng thái: lịch của đăng ký đã sang Đã ký / Không phù hợp vẫn hiện để biết cuộc hẹn dẫn tới đâu. appointmentOverdue — true = đang "Đã hẹn gặp/khảo sát" mà giờ hẹn đã qua (chưa cập nhật kết quả). appointmentMissing — true = đang "Đã hẹn gặp/khảo sát" mà chưa ghi lịch (đăng ký có trước §6.29). Giá trị sai kiểu bị bỏ qua, không ném lỗi (cùng lệ AgencyProfileSearchFilter).

Truy vấn đã qua phạm vi của người gọi. Mốc "hôm nay" của idleMinDays/idleMaxDays — báo cáo tồn đọng truyền đúng mốc nó đếm; null = bây giờ. Nguồn phiên cổng cho portalSeenFromDate/portalSeenToDate. Có khoá đó mà thiếu nguồn là lỗi lập trình (ném) — không được lặng lẽ bỏ qua bộ lọc rồi trả thừa dòng.

Sắp xếp theo danh sách cột cho phép (Sort.Predicate); mặc định mới gửi trước. Cột lạ rơi về mặc định — không sắp theo tên property tuỳ ý từ client. portallastseenat (lần khách vào xem cổng gần nhất) cần ; giảm dần = vào gần đây nhất trước, đăng ký khách chưa vào cổng (null) xuống cuối.

true (JSON) hoặc chuỗi "true"; mọi giá trị khác là false.

Ngày (theo giờ Việt Nam) của một giá trị lọc. Newtonsoft đổi chuỗi ISO có giờ thành với Kind Utc/Local tuỳ hậu tố — dựng thẳng DateTimeOffset(+07) từ DateTime Utc là ném lỗi, nên quy mọi dạng về một thời điểm rồi mới lấy ngày ở múi +07.

Utc/Local là một thời điểm → đổi sang +07 rồi lấy ngày; Unspecified coi như giờ Việt Nam.

Lần khách vào xem Cổng nhượng quyền gần nhất của một đăng ký (plan cổng §6.28) = LastSeenAt lớn nhất của mọi phiên () trên mọi mã gắn đăng ký đó (FranchisePortalAccessCode.FranchiseLeadId), kể cả mã đã thu hồi / hết hạn. KHÔNG dùng FranchisePortalAccessCode.LastAccessAt: cột đó chỉ ghi lúc khách NHẬP MÃ, mà cookie phiên của cổng sống tới 7 ngày (FranchisePortal.SessionDays) — khách quay lại trong khoảng đó không nhập mã lại, chỉ phiên được chạm (FranchisePortalStore.TouchLastSeenAsync, tối đa một lần mỗi phút). Không gác theo role cổng: việc khách đã vào cổng vốn lộ qua trạng thái "Đã xem thông tin nhượng quyền" và người cập nhật "website" trên dòng đăng ký; mã rõ vẫn chỉ ở FranchiseLeadService.AttachAccessCodesAsync. Hai nguồn là truy vấn ĐÃ lọc xoá mềm (IRepository.Query()) cùng DbContext với truy vấn đăng ký — EF chèn chúng thành truy vấn con tương quan; repository giả in-memory chạy được cùng biểu thức.

Đăng ký có lần vào xem gần nhất từ trở đi (chưa vào cổng: MAX là null → không khớp).

Đăng ký có lần vào xem gần nhất TRƯỚC (chưa vào cổng: không khớp).

Giảm dần: vào gần đây nhất trước, chưa vào cổng (null) cuối; tăng dần thì ngược lại. Cùng mốc thì theo Id.

Lần vào xem gần nhất theo FranchiseLead.Id cho một trang dòng; đăng ký khách chưa vào cổng không có trong kết quả.

Danh mục cho giao diện (GET api/FranchiseLead/filter-options), lấy từ enum và , không chép tay: Statuses/Provinces/Channels là đúng các giá trị nhận (ô lọc, hộp thoại đổi trạng thái); BusinessStatuses chỉ là nhãn — bộ lọc chưa có khoá cho nó. Form nhập tay đọc Provinces, BusinessStatuses và ManualChannels — đúng các giá trị FranchiseLeadService nhận khi tạo/sửa.

Kênh nhân viên chọn được khi nhập tay: mọi kênh trừ Website (chỉ form website ghi kênh đó).

Người đang thao tác — controller đóng gói từ User.GetCurrentUser().

Người đang thao tác — controller đóng gói từ User.GetCurrentUser().

Màn quản trị "Đăng ký nhượng quyền" (docs/plan-nhuong-quyen-website.md §3.1, §3.4, §3.6). chứa dữ liệu cá nhân: mọi đường đọc/sửa đi qua — người chỉ có FranchiseLead.Search chỉ chạm được đăng ký mình phụ trách; ngoài phạm vi trả "không tìm thấy". Mọi đường GHI kèm một dòng trong cùng transaction.

null khi không có hoặc ngoài phạm vi của .

Lịch sử cập nhật của một đăng ký, mới nhất trước, kết thúc bằng dòng "Tạo đăng ký"; null khi không có hoặc ngoài phạm vi của .

Nhập tay một đăng ký cho người nhắn tin hoặc gọi tổng đài. Số điện thoại đã có đăng ký thì từ chối kèm mã của đăng ký đó. Người chỉ có FranchiseLead.Search tự phụ trách đăng ký mình nhập.

Sửa thông tin người đăng ký; không có trường nào đổi thì không ghi gì.

Đổi trạng thái và/hoặc ghi chú; giữ nguyên trạng thái mà đổi ghi chú là thêm một dòng tiến độ. Trạng thái đích "Đã hẹn gặp/khảo sát" bắt buộc kèm lịch hẹn; giữ trạng thái đó mà đổi lịch là một dòng "Đổi lịch hẹn" (§6.29). Trạng thái đích "Không phù hợp" thu hồi mọi mã truy cập cổng chưa thu hồi của đăng ký trong cùng transaction.

Giao người phụ trách — người được giao phải còn làm việc và giữ Search hoặc Manage.

Giao cùng một người phụ trách cho nhiều đăng ký trong MỘT transaction — cùng luật với , mỗi đăng ký đổi người một dòng lịch sử riêng. Id ngoài phạm vi bị bỏ qua và đếm vào NotFoundCount.

Người giao được: giữ FranchiseLead.Search hoặc FranchiseLead.Manage, còn làm việc.

Xuất Excel theo cùng bộ lọc với danh sách; tối đa dòng.

Báo cáo tồn đọng (trạng thái × thời gian chờ theo tỉnh, tỉnh × trạng thái) trong phạm vi người gọi, theo cùng bộ lọc với danh sách ().

Các đoạn trạng thái theo thời gian () của các đăng ký được hỏi — thanh của biểu đồ Gantt trang lịch hẹn. Id ngoài phạm vi của bị bỏ qua (không có trong kết quả).

Trang lịch hẹn gộp ba khối, mỗi khối tối đa 200 dòng ().

Giao hàng loạt chạy trên các dòng đang chọn của MỘT trang — tối đa một trang lớn nhất ().

Khớp lựa chọn lớn nhất của bộ phân trang FE (pageSizeOptions tới 200).

Ba trần dưới đây khớp form website (FranchiseRegisterModel).

Lịch hẹn cách hôm nay quá khoảng này là gõ nhầm năm — vẫn nhận lịch đã qua để ghi lại cuộc hẹn vừa diễn ra.

Rộng hơn form website (chỉ nhận di động): người gọi tổng đài có thể gọi từ số bàn 11 chữ số.

Nguồn "lần khách vào xem cổng gần nhất" (§6.28) cho bộ lọc, phép sắp và cột — mã + phiên đã lọc xoá mềm.

Phạm vi dữ liệu của người thao tác — MỘT chỗ cho Search, GetById, GetHistory, Update, UpdateStatus, Export.

Gắn lần khách vào xem cổng gần nhất (§6.28, ) vào các dòng — một truy vấn gom theo đăng ký cho cả trang; không gác role cổng (xem lý do ở lớp nguồn).

Gắn mã truy cập gần nhất + cờ "tạo được mã" vào các dòng đăng ký (plan cổng §6.23). Người gọi không có role cổng thì để trống cả hai — role cổng là hàng rào của mã, kể cả bản tóm tắt. Mã đọc qua ĐÚNG phạm vi mã (): người giữ role chéo (vd. FranchiseLead.Manage + FranchisePortal.Sale) thấy mọi đăng ký nhưng chỉ thấy tóm tắt mã của đăng ký mình phụ trách — không hiện một mã mà mở ra lại 404.

Thu hồi các mã truy cập cổng của đăng ký vừa lưu "Không phù hợp" — đúng cách ghi của nút Thu hồi (FranchisePortalAccessCodeService.RevokeAsync): đổi trạng thái mã, đóng phiên đang mở để request kế tiếp của khách bị đẩy về trang nhập mã, một dòng lịch sử của mã. Gọi TRONG transaction đổi trạng thái; mã người khác vừa thu hồi trước (store trả false) thì bỏ qua, không đè người/lý do của họ. Trả số mã thu hồi được.

Thông tin người đăng ký đã chuẩn hoá và qua kiểm tra.

Thông tin người đăng ký đã chuẩn hoá và qua kiểm tra.

Kiểm form nhập tay. Giá trị KHÔNG ĐỔI so với (số điện thoại, tỉnh, tình trạng doanh nghiệp) được giữ nguyên dù không còn qua luật — dòng chuyển từ bảng Lead cũ và tỉnh ngoài danh sách hiện tại vẫn sửa được các trường khác.

Đăng ký đang sửa; null khi nhập mới.

Lịch hẹn của form đổi trạng thái khi trạng thái đích là (plan cổng §6.29): bắt buộc, quy về giờ Việt Nam và bỏ giây (độ mịn của ô chọn giờ), trong vòng quanh .

Lịch hẹn như dòng lịch sử hiển thị: dd/MM/yyyy HH:mm giờ Việt Nam; chưa có lịch = null.

Id của đăng ký khác đang giữ số này (mới nhất), null khi chưa có. CỐ Ý tìm ngoài phạm vi của người thao tác: trùng số với đăng ký người khác phụ trách vẫn là trùng — câu từ chối chỉ lộ mã NQ, không lộ thông tin nào khác.

Tên hiển thị của người nhận phụ trách, hoặc câu từ chối: phải còn làm việc và xem được đăng ký nhượng quyền.

Ghi thay đổi của đăng ký và dòng lịch sử của nó trong MỘT transaction — không có thay đổi nào thiếu dấu vết, không có dấu vết nào của thay đổi không xảy ra. chạy SAU khi lưu đăng ký để đọc được Id vừa sinh của bản ghi mới.

Thêm dòng Nhãn: cũ → mới khi hai giá trị khác nhau (rỗng và null là một).

Nhãn tình trạng doanh nghiệp; mã lạ (dòng cũ) hiện nguyên mã thay vì biến mất khỏi dòng lịch sử.

Các đoạn trạng thái theo thời gian của một đăng ký — thanh của biểu đồ Gantt trang lịch hẹn (plan cổng §6.30). Hàm thuần, dựng từ các dòng (sale đổi tay, cổng tự đặt "Đã xem", tạo mã tự đặt "Đã cấp mã" — mọi đường đổi trạng thái đều ghi dòng đó).

Dữ liệu cũ không khớp lịch sử vẫn ra một dải liền, không lỗ hổng: đăng ký có trước bảng lịch sử không có dòng nào → một đoạn trạng thái hiện tại từ lúc gửi; trạng thái bị đổi ngoài đường ghi lịch sử (DataFix, sửa tay DB) → thêm đoạn trạng thái hiện tại từ UpdatedTime. Mốc lùi (giờ máy lệch) kẹp về mốc trước đó, đoạn dài 0 bỏ.

Một lần đổi trạng thái đọc từ lịch sử.

Một lần đổi trạng thái đọc từ lịch sử.

Lúc gửi / nhập đăng ký — đầu dải. Lần cập nhật gần nhất — mốc của đoạn bù khi trạng thái hiện tại không khớp lịch sử. Trạng thái hiện tại của đăng ký — đoạn cuối luôn mang trạng thái này. Mọi lần đổi trạng thái của đăng ký, thứ tự bất kỳ. Các đoạn liền nhau theo thời gian; đoạn cuối To = null (còn đang ở trạng thái đó).

Đóng đoạn tại ; đoạn dài 0 (đổi hai lần cùng lúc) bỏ.

Kết quả một lần đối chiếu Ví.

Người cầm tiền thuộc bưu cục nhượng quyền đã bật ví (V-05): tiền người đó thu trên đơn Ví ghi đã nằm trong ví bưu cục, không nộp Quỹ LADA.

Bưu cục nhượng quyền của người cầm tiền. Ngày bắt đầu ghi Ví (AppConfig FranchiseWallet.StartDate); null = mọi đơn.

Kết quả một lần đối chiếu Ví.

Người cầm tiền thuộc bưu cục nhượng quyền đã bật ví (V-05): tiền người đó thu trên đơn Ví ghi đã nằm trong ví bưu cục, không nộp Quỹ LADA.

Bưu cục nhượng quyền của người cầm tiền. Ngày bắt đầu ghi Ví (AppConfig FranchiseWallet.StartDate); null = mọi đơn.

Bưu cục nhượng quyền của người cầm tiền.

Ngày bắt đầu ghi Ví (AppConfig FranchiseWallet.StartDate); null = mọi đơn.

Đơn tạo lúc có do Ví ghi không (cùng luật RunAsync và SP màn Quỹ).

Mốc 00:00 giờ VN của để lọc trong truy vấn: đơn tạo TRƯỚC mốc không do Ví ghi (lái xe vẫn nộp LADA); null = mọi đơn do Ví ghi. Dùng chung cho phiếu chuyển khoản lái xe và màn "tiền cần nộp" của app (V-40).

Kết quả kiểm số thực thu khi lấy (E1) TRƯỚC SP lấy hàng: ≠ null → từ chối lấy; = số sẽ ghi vào OrderFin.SourceFeeCollectedAmount SAU khi SP thành công (V-29); null = không áp.

Kết quả kiểm số thực thu khi lấy (E1) TRƯỚC SP lấy hàng: ≠ null → từ chối lấy; = số sẽ ghi vào OrderFin.SourceFeeCollectedAmount SAU khi SP thành công (V-29); null = không áp.

Không áp (bên lấy không bật ví, đơn không thu người gửi, đơn trước ngày ghi Ví).

E8 — chỉ có khi lượt chạy là đối soát với khách của đơn COD giao thành công có bên bán bật ví.

Yêu cầu xuất kho một đơn cho bưu cục phát (plan v2 §3.3 "Xuất kho").

Chi nhánh của người được gán — bên phát P.

Yêu cầu xuất kho một đơn cho bưu cục phát (plan v2 §3.3 "Xuất kho").

Chi nhánh của người được gán — bên phát P.

Chi nhánh của người được gán — bên phát P.

Kết quả kiểm xuất kho MỘT đơn — hợp đồng API gán đổi từ "Failed cả lô" sang từng đơn (FE GĐ D đọc).

Đơn được xuất (đã ghi khoản giữ E2 / E3 nếu có). Ví không đủ nhưng công tắc chặn tắt — đã đi, đã ghi "sẽ chặn" vào sổ vấn đề.

Kết quả kiểm xuất kho MỘT đơn — hợp đồng API gán đổi từ "Failed cả lô" sang từng đơn (FE GĐ D đọc).

Đơn được xuất (đã ghi khoản giữ E2 / E3 nếu có). Ví không đủ nhưng công tắc chặn tắt — đã đi, đã ghi "sẽ chặn" vào sổ vấn đề.

Đơn được xuất (đã ghi khoản giữ E2 / E3 nếu có).

Ví không đủ nhưng công tắc chặn tắt — đã đi, đã ghi "sẽ chặn" vào sổ vấn đề.

Không có gì phải kiểm (bên phát không bật ví).

Kết quả chốt cước chính thức khi nhập kho LADA.

Đơn thuộc phạm vi v2 (có chi nhánh bật ví tham gia, người quét không bật ví, đang trên đường đi). Vừa chốt ở lần này (false khi đã chốt trước đó). Đơn COD có tiền thu hộ nhỏ hơn cước chính thức — đã đặt cờ giữ, không chặn nhập. Lý do từ chối nhập kho đơn này (thiếu ô cân thật khi cờ bắt buộc bật); null = nhập được.

Kết quả chốt cước chính thức khi nhập kho LADA.

Đơn thuộc phạm vi v2 (có chi nhánh bật ví tham gia, người quét không bật ví, đang trên đường đi). Vừa chốt ở lần này (false khi đã chốt trước đó). Đơn COD có tiền thu hộ nhỏ hơn cước chính thức — đã đặt cờ giữ, không chặn nhập. Lý do từ chối nhập kho đơn này (thiếu ô cân thật khi cờ bắt buộc bật); null = nhập được.

Đơn thuộc phạm vi v2 (có chi nhánh bật ví tham gia, người quét không bật ví, đang trên đường đi).

Vừa chốt ở lần này (false khi đã chốt trước đó).

Đơn COD có tiền thu hộ nhỏ hơn cước chính thức — đã đặt cờ giữ, không chặn nhập.

Lý do từ chối nhập kho đơn này (thiếu ô cân thật khi cờ bắt buộc bật); null = nhập được.

Dự kiến phí của một đơn (màn Đơn hàng bưu cục, plan §3.8.1).

Mã đơn. Chi nhánh tham gia đơn: bán, lấy (thật / dự kiến), phát (gán / đã giao / dự kiến), phát hoàn (dự kiến / thật). Dòng dự kiến; null = chưa bật ví nào hoặc đơn tạo trước ngày bắt đầu ghi Ví.

Dự kiến phí của một đơn (màn Đơn hàng bưu cục, plan §3.8.1).

Mã đơn. Chi nhánh tham gia đơn: bán, lấy (thật / dự kiến), phát (gán / đã giao / dự kiến), phát hoàn (dự kiến / thật). Dòng dự kiến; null = chưa bật ví nào hoặc đơn tạo trước ngày bắt đầu ghi Ví.

Mã đơn.

Chi nhánh tham gia đơn: bán, lấy (thật / dự kiến), phát (gán / đã giao / dự kiến), phát hoàn (dự kiến / thật).

Dòng dự kiến; null = chưa bật ví nào hoặc đơn tạo trước ngày bắt đầu ghi Ví.

Ghi Ví bưu cục theo sự kiện đơn (Ví v2 — Docs "Yêu cầu kỹ thuật Ví bưu cục v2", plan docs/plan-vi-buu-cuc-v2.md). Móc vào các chỗ đơn đổi trạng thái NGAY SAU khi nghiệp vụ đã thành công (SP trả Success) hoặc CÙNG GIAO DỊCH (xuất kho, nhập kho, mở hoàn — §3.3) qua .

Móc sự kiện không bao giờ ném lỗi ra nơi gọi (SPEC M19): mọi lỗi được log, ghi sổ vấn đề FranchiseLedgerIssue, và job đêm franchise-ledger-recheck đối chiếu lại. Ngoại lệ duy nhất là — điểm chặn: lỗi kỹ thuật = từ chối đơn đó (hàng không rời kho khi chưa giữ được tiền). Luật nằm ở (thuần, idempotent): móc và job cùng một luật.

Đóng dấu bưu cục bán / bưu cục tạo / bản giá mua đơn / dải cự ly ngay sau khi tạo đơn (không ghi dòng).

Một sự kiện đơn vừa xảy ra (sau SP đã commit) — đối chiếu và ghi Ví của đơn. Không ném lỗi.

Như trên nhưng CÙNG GIAO DỊCH của nơi gọi: đọc / ghi qua connection + transaction của . Gọi SAU khi nơi gọi đã ghi trạng thái mới của đơn (chưa commit) — Ví đọc được trạng thái đó. Không ném lỗi (lỗi → sổ vấn đề, job đêm bù).

Đối chiếu một đơn theo trạng thái (không sự kiện) — dùng cho job và nút "đối chiếu lại".

Job đêm: đối chiếu đơn có cập nhật gần đây dính tới chi nhánh bật ví + đơn còn vấn đề mở.

Bản giá đã được dùng (dòng Ví / đơn neo) chưa.

Chi nhánh đã bật ví (đệm 2 phút) — nơi gọi dùng để biết đơn / người có thuộc phạm vi v2 không.

Đơn có dính chi nhánh bật ví không (người thao tác, S / L / P / chủ khách, hoặc đã có dòng Ví).

Chi nhánh là bưu cục NHƯỢNG QUYỀN (AgencyType = Franchise). Chi nhánh LADA bật ví để đo (§6 mục 15) vẫn là "kho LADA" ở mốc chốt cước và nhận lại hàng hoàn — không dùng cờ bật ví để nhận diện kho LADA. 0 / không có = LADA.

V-05: người dùng thuộc bưu cục NHƯỢNG QUYỀN đang bật ví → bưu cục + ngày bắt đầu ghi Ví (để màn Quỹ không thu tiền của đơn Ví ghi); không thì null. Chi nhánh LADA bật ví để đo trả null — lái xe LADA vẫn nộp Quỹ (§6 mục 15).

Ngày bắt đầu ghi Ví (AppConfig FranchiseWallet.StartDate); null = mọi đơn. Đơn tạo trước ngày này đi luồng LADA cũ.

Điểm chặn xuất kho (plan §3.4, Docs §5): trong giao dịch của nơi gọi — khoá ví bên phát, đọc số dư SAU khoá, quyết định bằng ; được thì gọi (nơi gọi đổi trạng thái + ghi AgencyDeliveryAssignedId + track, chưa commit) rồi ghi E2 / E3 cùng giao dịch. Không được → trả Ok = false kèm số thiếu, chưa đụng đơn. Lỗi kỹ thuật NÉM ra để nơi gọi rollback đơn đó.

Cổng ví cho đường "bưu cục bật ví QUÉT NHẬN hàng chưa qua gán" (§4.0 #9 B2) — cùng luật điểm chặn xuất kho: bưu cục quét là bên phát () và chưa được gán → khoá ví, đọc số dư sau khoá, . Không ghi gì: nơi gọi từ chối quét khi Ok = false, còn lại đi tiếp rồi gọi để planner ghi E2 / E3. Review bảo mật GĐ B (26/10/2026): thiếu cổng này, bưu cục có role nhập kho tự quét đơn đang ở kho LADA → E2 / E3 ghi không kiểm số dư, rồi gán lái xe mình không qua điểm chặn (bên giữ = bên phát). Lỗi kỹ thuật NÉM ra để nơi gọi từ chối đơn đó.

E1 bước 1 — kiểm số lái xe thực thu của người gửi khi lấy, gọi TRƯỚC SP lấy hàng, KHÔNG ghi gì: chỉ áp khi bên lấy bật ví, đơn do Ví ghi và hình thức GỬI-TRẢ / Thu 2 đầu; thiếu số = ; biên 0–150 % cước tạm tính. (app lái xe): ô "Số tiền đã thu" đang bật () mà thiếu số → từ chối. Lỗi kỹ thuật → không áp + ghi vấn đề (không chặn lấy hàng).

E1 bước 2 — ghi số đã kiểm vào OrderFin.SourceFeeCollectedAmount SAU khi SP lấy hàng thành công, trước móc PickupConfirmed (V-29: SP thất bại thì đơn không mang số của lần lấy hỏng). Không ném lỗi: lỗi → vấn đề, planner dùng cước thu người gửi.

Ô "Số tiền đã thu" cho các đơn lái xe sắp lấy (plan §3.8.2) — cùng luật với . Lái xe không thuộc bưu cục nhượng quyền bật ví → rỗng (một lần đọc tập ví đã cache). Đơn lỗi kỹ thuật bị bỏ qua (app hiện màn cũ, máy chủ vẫn kiểm lúc lấy).

Cổng tạo đơn (T06 / T23): chỉ kiểm khi đơn có chi nhánh bật ví tham gia (bên bán theo Q16, chi nhánh tạo). Trả thông điệp lỗi hoặc null (hợp lệ / không áp). Lỗi kỹ thuật → null + log (V-17 bắt lại ở sự kiện đầu).

Chốt cước chính thức CC khi kho LADA (chi nhánh không bật ví) nhập đơn có chi nhánh bật ví tham gia, lần đầu, trong giao dịch nhập kho (plan §3.3). Cân thật ≠ Σ cân kiện → tính lại bằng FeeQuoteEngine; không thì CC = cước tạm tính. Đơn COD có tiền thu hộ nhỏ hơn CC → cờ giữ + báo bên bán, KHÔNG chặn nhập. Không ném lỗi (trừ khi thiếu ô cân bắt buộc → Error).

Mở hoàn trước khi nhập kho LADA (§6 mục 2): CC = cước tạm tính lúc huỷ nếu chưa chốt — trong giao dịch mở hoàn. Không ném lỗi.

E8 / E13 tại mốc hoàn thành phiếu đối soát khách (plan §3.6), CÙNG GIAO DỊCH chuyển tiền của phiếu: planner tính tiền trả khách gửi của đơn COD (E8, ngoài ví) và ghi E13 + ví bưu cục sale cho từng đơn hoàn trong (khoản đã giữ chỗ lúc lập phiếu). NÉM lỗi khi không ghi được hoặc khi số planner tính lệch (số đã đưa vào phiếu) — nơi gọi rollback cả phiếu: không trả khách số tiền mà ví bưu cục sale chưa được cộng tương ứng.

Xem trước E8 của một đơn khi lập phiếu đối soát khách — CÙNG planner với nhưng không ghi gì. null = đơn không theo luật ví (không phải COD giao thành công có bưu cục NHƯỢNG QUYỀN bật ví bán, hoặc tạo trước ngày bắt đầu ghi Ví) → phiếu giữ công thức cũ (plan §1.3).

Dự kiến dòng ví nếu đơn giao thành công từ trạng thái hiện tại (planner Forecast, không ghi gì) — màn Đơn hàng bưu cục (plan §3.8.1). null = đơn không có / hệ thống chưa bật ví nào / đơn tạo trước ngày bắt đầu ghi Ví. Kèm các chi nhánh tham gia đơn (bán / lấy / phát / phát hoàn, kể cả dự kiến) để nơi gọi kiểm phạm vi bưu cục.

Cảnh báo số dư thấp (plan §3.4 "Cảnh báo"): với mỗi bưu cục NHƯỢNG QUYỀN có ví bật mà số dư < ngưỡng, báo một lần mỗi ngày (bưu cục + quản lý khu vực). Chi nhánh LADA bật ví để đo không áp ngưỡng (§6 mục 15). Không ném lỗi.

Khoá AppConfig ngày bắt đầu ghi Ví.

Khoá AppConfig số ngày job đêm nhìn lại.

Tên người ghi trên cột audit của dòng Ví do hệ thống sinh.

Bộ dấu trên đơn dùng cho một lần lập kế hoạch.

Bộ dấu trên đơn dùng cho một lần lập kế hoạch.

V-22 (job đêm): đơn có bưu cục nhượng quyền bật ví tham gia, ĐÃ NHẬP kho LADA (Inbound — không tính Outbound: đó là hàng đang trên đường từ bưu cục về kho, chốt lúc đó là mất lần cân thật khi nhập — review GĐ C) mà chưa có cước chính thức — lỗi kỹ thuật lúc nhập kho, hoặc nhập kho trước khi bưu cục bật ví — chốt CC = TT (nguồn "nhập kho") + ghi chú cho kế toán kiểm cân thật. Cùng điều kiện "tham gia" với chốt cước lúc nhập kho; đơn tạo trước ngày bắt đầu ghi Ví không đụng.

T17 (lượt đối chiếu không trigger — job đêm / nút đối chiếu lại) cho đơn đã kết thúc: dòng ví thực có so với dựng lại từ đầu theo luật (, plan §6 mục 22). Lệch → vấn đề loại bất biến + báo kế toán MỘT lần (vấn đề mới); hết lệch → lần kiểm sau tự đóng. Trả true khi lệch.

Phần chung của hai cổng (xuất kho, quét nhận thẳng): ảnh chụp đơn trong giao dịch (không ghi dấu lên Order — nơi gọi sắp UpdateAsync cả dòng), khoản E2 / E3 phải giữ cho bên phát (đã giữ đúng khoản → 0), khoá ví rồi mới đọc số dư (mẫu SqlCashHolderLock — hai lô song song xếp hàng ở đây), quyết định bằng .

Điều kiện áp cổng tính trên trạng thái hiện tại (trước khi coi là bên phát); null = luôn áp. Quyết định (null khi không thoả — chưa khoá ví) và ảnh chụp đơn.

Tập chi nhánh bật ví thu hẹp về bưu cục nhượng quyền (bỏ chi nhánh LADA bật ví để đo).

Chi nhánh là bưu cục nhượng quyền (Agency.AgencyType = Franchise); chi nhánh LADA bật ví để đo (plan §6 mục 15) không phải.

"Bên bán có ví" theo nghĩa Docs = bưu cục nhượng quyền ĐANG bật ví. Review GĐ B F3: chi nhánh LADA bật ví để đo không chịu cổng T06 / T23 và chuyển khoản của nó vẫn là CK kế toán — nếu không, sau 18/12 nhân viên LCHN tạo đơn CK + thu hộ sẽ bị từ chối.

Hình thức Ví v2 + đơn có do Ví ghi không + ô "Số tiền đã thu" của một đơn. = bên lấy là bưu cục nhượng quyền bật ví — người gọi tính một lần cho cả lô (không truy vấn lại loại chi nhánh từng đơn).

V-60 (anh Thắng 27/10/2026): khoản còn ở "Lái xe đang cầm" mà người cầm thuộc bưu cục nhượng quyền bật ví → "Bưu cục giữ" — đơn đã qua cổng ngày bắt đầu ghi Ví ở , tức đúng luật mà màn Quỹ / phiếu chuyển khoản / job phạt đang loại. Chi nhánh LADA bật ví để đo không chuyển: lái xe chi nhánh vẫn nộp Quỹ. Mỗi khoản chỉ chuyển khi chi nhánh của người cầm có dòng ví chưa đảo cho ĐÚNG khoản đó (cước lấy ↔ E1, cước giao ↔ E2, COD / phí trừ COD ↔ E3) — review H2: lái xe LADA đang cầm tiền đơn có bưu cục tham gia rồi chuyển sang bưu cục bật ví không được kéo tiền LADA chưa thu sang "Bưu cục giữ" (Quỹ không thu được nữa, doanh thu / lương tính như đã thanh toán).

Ảnh chụp DB → đầu vào planner.

Bên bán theo SPEC Q16: chủ khách nếu bật ví; chủ khách = 0 → LADA; khách chưa gán → bưu cục tạo nếu bật ví; không thì LADA (0).

Bên bán + bưu cục tạo của một đơn, KHÔNG ghi dấu (dùng trước khi nơi gọi ghi đơn trong giao dịch).

Tính bộ dấu (bưu cục bán / tạo / bản giá mua / dải) và cho biết có cột NULL cần ghi không — KHÔNG ghi.

Đóng dấu còn thiếu (chỉ cột NULL) và trả bộ giá trị dùng cho lần lập kế hoạch này.

Luật T06 / T23 trên đơn ĐÃ tồn tại (V-17 ở sự kiện đầu; COD < CC sau cân khi nhập kho): vi phạm → cờ giữ hàng CodBelowFeeHold (chặn ở xuất kho) + vấn đề + báo bên bán; hết vi phạm (bên bán đã sửa) → bỏ cờ. Trả cờ sau khi kiểm. Chỉ áp với đơn có bên bán / bưu cục tạo bật ví.

Có tính lại được cước bằng một con số cân không: đơn giá theo cân (không phụ phí thuộc tính, không kiện khai loại hàng, không đối tác).

Các khoản đã thu của đơn kèm bưu cục người thu thực tế; đóng dấu cột bưu cục người thu còn NULL.

Tham số luật Ví v2 từ AppConfig FranchiseWallet.* (thiếu khoá → mặc định, không ném lỗi).

Cờ bool trong AppConfig ("true" / "1"); thiếu hoặc không đọc được = false.

Ghi vấn đề lỗi kỹ thuật, không ném lỗi. Có (giao dịch của nơi gọi còn mở): chèn thẳng trên connection riêng, không đọc sổ vấn đề của đơn — đọc sẽ chờ khoá dòng mà giao dịch kia vừa ghi tới hết hạn lệnh (V-26). Ghi ngoài giao dịch để nơi gọi rollback thì vấn đề vẫn còn để soát.

Ảnh chụp thô một đơn (đọc mới từ DB, không qua bản EF đang theo dõi của request).

Σ cân kiện (gram) — cân tạm tính lúc tạo đơn.

Đơn đã từng giao thất bại (OrderTrack 153 hoặc trạng thái hiện tại) — E11 (V-19, GĐ B việc 5).

Có kiện khai loại hàng riêng (giá theo loại hàng) — không tính lại cước theo cân thật được bằng một con số cân.

Kiện như lúc tạo (cân khai, kích thước mm, số lượng, cân tính cước đã lưu) — cân thể tích khi chốt cước theo cân thật (review GĐ B F1).

V-60: các khoản của một đơn sẽ chuyển sang "Bưu cục giữ", mỗi khoản kèm người đang cầm (null = không đổi khoản đó). Phí trừ COD đi theo người cầm của nó.

Một kiện của đơn: cân khai (gram), kích thước (mm), số lượng, cân tính cước đã lưu (OrderPackage.SubTotalWeight).

Một kiện của đơn: cân khai (gram), kích thước (mm), số lượng, cân tính cước đã lưu (OrderPackage.SubTotalWeight).

Phạm vi "cùng giao dịch" của nơi gọi (xuất kho, nhập kho, mở hoàn — plan v2 §3.3): bọc của IRepository.BeginTransaction(); tầng lưu Ví đọc / ghi qua một RIÊNG dựng trên ĐÚNG connection + transaction đó — đọc được trạng thái đơn vừa ghi chưa commit, không chạm change tracker của service đang gọi, và commit / rollback của nơi gọi quyết định cả dòng Ví.

Dispose scope chỉ đóng context bọc, KHÔNG đụng transaction (nơi gọi sở hữu).

Giao dịch của nơi gọi.

Context bọc cùng connection + transaction (tạo lần đầu dùng).

Số dư một ví (không khoá) kèm ngưỡng cảnh báo — đầu vào cảnh báo số dư thấp (plan §3.4 "Cảnh báo").

Số dư một ví (không khoá) kèm ngưỡng cảnh báo — đầu vào cảnh báo số dư thấp (plan §3.4 "Cảnh báo").

Ví đã khoá trong giao dịch kèm số dư đọc SAU khoá (plan §3.4 "Xuất kho").

Số dư = Σ dòng vào số dư (cùng luật ).

Ví đã khoá trong giao dịch kèm số dư đọc SAU khoá (plan §3.4 "Xuất kho").

Số dư = Σ dòng vào số dư (cùng luật ).

Số dư = Σ dòng vào số dư (cùng luật ).

Tầng đọc / ghi của Ví — tách để luật lập kế hoạch và service test được không cần DB.

Mọi method nhận tuỳ chọn: null = context riêng, tự commit (móc ngay sau SP, job đêm); có scope = đọc / ghi trong giao dịch của nơi gọi (xem ).

Đọc một đơn (null = không có / đã xoá).

Mọi dòng Ví của một đơn.

Chi nhánh ĐÃ BẬT VÍ (FranchiseWallet Active, có EnabledAt) — chỉ chúng sinh dòng Ví v2 (plan v2 §1.1). Không theo Agency.AgencyType: bưu cục nhượng quyền chưa bật ví và chi nhánh LADA chưa bật ví đều là "vai trò LADA". Nhớ đệm 2 phút; bật ví gọi .

Đơn có dính chi nhánh bật ví nào không (người thao tác, đơn vị giữ hàng, lấy, giao, dự kiến giao, bưu cục bán / tạo, chủ khách) hoặc đã có dòng Ví — đường tắt để móc sự kiện gần như không tốn gì với đơn của LADA.

V-65 (review H2): đơn đã từng được kho LADA quét nhập kho — track "Nhập vào kho" của người thuộc chi nhánh không phải bưu cục nhượng quyền. Đơn như vậy không phải đơn nội vùng dù lần nhập kho đó không chốt được cước (lỗi, hoặc bưu cục bật ví sau khi hàng vào kho).

Bưu cục hiện tại của người dùng (0 = không có).

Bưu cục sở hữu khách (null = chưa gán; 0 = LADA).

Loại chi nhánh (nhượng quyền / LADA) của các chi nhánh — thiếu = không có trong bảng.

Đóng dấu bên phát P lúc bưu cục bật ví quét nhận hàng chưa qua gán (§4.0 #9 đường B2) — chỉ khi cột còn NULL.

Xoá dấu bên phát khi kho LADA nhận lại hàng (ReturnedToHub) — lần đối chiếu sau không giữ lại E2 / E3 cho bưu cục phát cũ (review GĐ B F2 / F4).

Dải cự ly theo khoảng cách hai phường đã đo (null = chưa đo / không có dải).

Bản giá nội bộ đã duyệt kèm phạm vi và ô — nguồn giá cho bộ lập kế hoạch.

Đóng dấu các cột Ví trên đơn — chỉ ghi vào cột đang NULL, không bao giờ đè.

Đóng dấu bưu cục người thu thực tế trên OrderFin — chỉ cột đang NULL.

Ghi số lái xe thực thu của người gửi khi lấy (E1) — ghi đè lần lấy sau cùng.

V-60: khoản tiền người của bưu cục nhượng quyền bật ví đang cầm trên đơn Ví ghi → "Bưu cục giữ" (FranchiseHeld). Chỉ đổi từng khoản có tên trong , khi khoản đó còn ở "Lái xe đang cầm" của đúng người ghi ở đó (không đè người khác đã thu). Trả số khoản đã đổi.

Đặt / bỏ cờ giữ hàng đơn COD có tiền thu hộ nhỏ hơn cước (chặn ở xuất kho).

Chốt cước chính thức — CHỈ khi OfficialFee còn NULL (chốt một lần, mota §1 (a)). Trả true nếu vừa chốt, false nếu đã có người chốt trước (hai máy quét cùng lúc).

Khoá ví của chi nhánh (sp_getapplock theo WalletId, chủ khoá = giao dịch của ) rồi đọc số dư SAU khoá — mẫu SqlCashHolderLock. null = chi nhánh chưa bật ví. Quá hạn chờ khoá → ném .

Ghi kế hoạch (chèn dòng, đổi trạng thái, cập nhật người thu) trong MỘT giao dịch (giao dịch riêng, hoặc của nơi gọi khi có scope). Chi nhánh thiếu ví → ném lỗi, không tự mở ví.

Ghi sổ vấn đề của đơn: thêm / tăng đếm vấn đề còn gặp; = tự đóng vấn đề không còn (lần đối chiếu đầy đủ), false = chỉ thêm (lỗi kỹ thuật giữa chừng không chứng minh vấn đề cũ đã hết). Vấn đề mới mang / (V-24); tự đóng chỉ chạm nhóm của . Trả số vấn đề MỚI ghi (để nơi gọi chỉ báo một lần).

Chèn THẲNG một vấn đề trên connection riêng tự commit, không đọc vấn đề đang mở (V-26): dùng ở nhánh lỗi khi giao dịch của nơi gọi còn mở — đọc sổ vấn đề của đơn đó sẽ chờ khoá dòng giao dịch kia vừa ghi tới hết hạn lệnh. Có thể trùng nội dung; lượt đối chiếu đầy đủ sau đó đóng.

Đơn cần đối chiếu lại: có cập nhật từ và dính tới chi nhánh bật ví, cộng đơn còn vấn đề mở.

Có dòng Ví hoặc đơn nào tham chiếu bản giá này không (để chặn huỷ bản đã dùng — SPEC §3.3 mục 7).

Số dư hiện tại + ngưỡng cảnh báo của ví đang bật của chi nhánh (null = chưa bật ví). Có scope: đọc trong giao dịch của nơi gọi (thấy dòng vừa ghi chưa commit), KHÔNG khoá ví — chỉ để cảnh báo, không để quyết định tiền.

Đánh dấu ví đã được báo "số dư dưới ngưỡng" hôm nay (giờ Việt Nam) — UPDATE có điều kiện chưa báo hôm nay, trả true nếu lần này là lần đánh dấu (nơi gọi gửi thông báo). LUÔN chạy trên connection riêng tự commit, không qua giao dịch của nơi gọi: giữ khoá dòng FranchiseWallet tới cuối giao dịch xuất kho sẽ chặn chính truy vấn danh sách ví bật (context riêng) của cùng request.

Không có scope: mỗi lời gọi dùng một RIÊNG dựng từ options: (1) đọc được trạng thái mới nhất mà SP vừa ghi — DbContext dùng chung của request đang giữ bản OrderOps cũ nạp trước SP; (2) SaveChanges của Ví không vô tình lưu thay đổi dở dang của service đang gọi. Có scope: dùng context bọc của scope (cùng connection + transaction của nơi gọi).

Tên track giao thất bại do SP_UpdateOrderDeliveryFail ghi. App lái xe trước GĐ B2 (26/10/2026) không truyền @TrackActionType nên SP ghi mặc định 7 (= trong enum) — dev có 59.995 dòng mã 7, 0 dòng 153 — vì vậy dấu vết "đã từng giao thất bại" (V-19) phải đọc cả dòng cũ theo tên.

Context mượn: của scope (không dispose) hoặc mới (dispose khi xong).

Xoá đệm danh sách chi nhánh bật ví — gọi ngay sau khi bật / tắt ví để móc sự kiện thấy ngay.

Tên tài nguyên khoá ví trong sp_getapplock (cùng họ "lada:" với khoá người cầm tiền).

Số dư = Σ dòng vào số dư của ví (cùng luật ).

Nguồn bản giá nội bộ nạp sẵn vào bộ nhớ — một lần cho cả lượt đối chiếu.

Thông báo cho bưu cục nhượng quyền (SPEC §3.11, GĐ5): bản giá nội bộ vừa duyệt / sắp áp dụng, phiếu đối soát vừa phát hành / tới hạn tự xác nhận. Người nhận = user THUỘC bưu cục có role tương ứng + Agency.ManagerId nếu có.

Không bao giờ ném lỗi ra nơi gọi: thông báo hỏng không được làm hỏng thao tác duyệt / phát hành. Bưu cục nhận bản giá do tính (bản riêng của bưu cục thắng bản toàn mạng — bưu cục đó không nhận tin bản toàn mạng không áp cho mình).

Bản giá vừa duyệt — gửi cho bưu cục mà bản này áp vào ngày bắt đầu; trả số người nhận.

Nhắc bản sắp áp dụng sau ngày; trả số người nhận.

Phiếu tháng vừa phát hành; trả số người nhận.

Nhắc phiếu có hạn xác nhận là hôm nay (job hằng ngày); trả số người nhận.

Ví v2: đơn bị giữ hàng (tiền thu hộ nhỏ hơn cước / hình thức trả cước không hợp lệ) — báo bưu cục BÁN sửa trước khi xuất kho; tối đa một lần mỗi đơn mỗi ngày. Trả số người nhận.

Ví v2 GĐ C: bưu cục vừa tạo lệnh rút (ví đã trừ) — báo mọi người có role kế toán quỹ (FranchiseWallet.Treasury). Trả số người nhận.

Ví v2 GĐ C: lệnh rút đã chuyển tiền / bị từ chối / tự huỷ — báo bưu cục chủ ví (role View hoặc Withdraw + quản lý bưu cục). Trả số người nhận.

Ví v2 GĐ C: kế toán vừa ghi nhận tiền nạp — báo bưu cục chủ ví kèm số dư sau nạp. Trả số người nhận.

Ví v2 GĐ C: số dư dưới ngưỡng cảnh báo — báo bưu cục (role View + quản lý bưu cục) và quản lý khu vực (chi nhánh cha loại Region). Nơi gọi chống nhắc trùng theo ngày (FranchiseWallet.LastLowBalanceNotifiedAt). Trả số người nhận.

Ví v2 GĐ C2 (T17): job đêm thấy đơn đã kết thúc lệch bất biến — báo kế toán (role FranchiseWallet.Manage và, từ V-68 — anh Thắng 27/10/2026, cả FranchiseWallet.Config của kế toán trưởng; người của LADA nên không lọc chi nhánh). Nơi gọi chỉ báo khi vấn đề mới ghi lần đầu. Trả số người nhận.

Người nhận cảnh báo lệch T17: kế toán quản lý ví + kế toán trưởng (cấu hình ví). V-68 bấm G1: chỉ Manage thì production không ai giữ role là không ai biết lệch, kế toán trưởng không nhận.

"1.250.000 đ" — số âm giữ dấu (ví âm).

"Vietcombank · 0123456789 · NGUYEN VAN A" — thiếu phần nào bỏ phần đó; trống hết = "tài khoản chưa khai".

Lời nhắc này (loại + bản / phiếu) đã gửi trong hôm nay (giờ Việt Nam) chưa. Job nhắc chạy lại trong ngày — bấm "Chạy ngay", Hangfire thử lại sau lỗi — không được nhắc trùng (bấm thử 19/10/2026: hai lần kích job → hai tin giống hệt).

Hai chuỗi nhận ra một lời nhắc trong Notification.ActionData — JSON của / do NotificationService ghi bằng System.Text.Json.

User thuộc các bưu cục và có một trong các role (UserRole ∪ nhóm quyền), cộng Agency.ManagerId — đã loại trùng.

Dữ liệu điền mẫu thông báo bản giá. Không nêu bưu cục khác cùng phạm vi (QUYET-DINH-TAM T14).

Dữ liệu điền mẫu thông báo phiếu; số ròng ghi rõ chiều trả tiền.

"1.250.000 đ (LADA trả bưu cục)" / "(bưu cục trả LADA)" / "0 đ".

Màn tham số bốn bậc gói vùng phủ /mang-luoi/bang-gia-nhuong-quyen/goi (GĐ K, plan cổng §6.16, §6.17): xem (FranchisePrice.Export / Manage) và sửa cả bộ (Manage). Không thêm / xoá bậc — bốn dòng seed bằng migration. Gói không gắn tay cho mã nữa: mã chỉ mang phường/xã, bậc tự xếp bằng .

Mọi bậc theo thứ tự ngưỡng; null = không có quyền xem.

Bậc → dòng hiển thị; dùng chung cho màn tham số và ô chọn phường của sale.

Dấu phiên bản của cả bộ — đổi khi bất kỳ bậc nào được lưu.

Chép bản nháp vào dòng thật; true = có ô đổi.

Trạng thái hiển thị của một mã truy cập, tính tại lúc đọc (hết hạn không phải cột — plan §3.1). Bốn mã dưới đây cũng là giá trị bộ lọc status của danh sách.

Bộ lọc của `POST search` (ô chọn mã "Hỏi thử" ở màn Cấu hình trợ lý — màn Mã truy cập đã bỏ ở GĐ L, plan §6.23), đọc từ Search.PredicateObject. Khoá (không phân biệt hoa thường): globalSearch — cả mã NQ-XXXX-XXXX tìm đúng mã đó (so băm có khoá); gõ dở NQ-AB… tới NQ-ABCD-234 tìm theo tối đa 4 ký tự đầu; dãy số (kể cả có dấu cách/chấm/gạch) tìm trong SĐT khách; còn lại tìm tên khách, SĐT. status — active (còn hạn, gồm cả sắp hết hạn) · expiring (còn ≤ 2 ngày) · expired · revoked. provinceCode — mã có giới hạn tỉnh chứa đúng tỉnh này (mã không giới hạn tỉnh không khớp). priceScope — none (chưa gắn phường nào) · below (có phường nhưng chưa đủ gói vùng phủ — ít hơn ngưỡng của bậc đầu, khách thấy câu "cần từ 3 phường…"). fromDate, toDate — ngày tạo, theo giờ Việt Nam, gồm cả hai đầu. Giá trị sai kiểu bị bỏ qua, không ném lỗi (cùng lệ ).

Giá trị bộ lọc priceScope: mã chưa gắn phạm vi giá nào.

Giá trị bộ lọc priceScope: mã có phường nhưng chưa đủ gói vùng phủ.

Băm có khoá để tìm theo CẢ mã; máy chủ chưa có khoá thì tìm cả mã không ra dòng nào. Dòng phạm vi giá của các mã — cho bộ lọc priceScope. Chỉ dòng PHƯỜNG được tính: dòng gói "Toàn tỉnh / Cấp 1" cũ để ngủ (GĐ K) không còn là phạm vi giá. Ngưỡng phường của bậc gói đầu (POINT) — cho priceScope = below; null = bảng bậc trống, không mã nào "chưa đủ gói".

Sắp xếp theo danh sách cột cho phép (Sort.Predicate); mặc định mới tạo trước. Cột lạ rơi về mặc định — không sắp theo tên property tuỳ ý từ client.

Phần so được với CodePrefix khi người dùng gõ dở mã (NQ-AB, NQ-ABCD-2); null khi không phải dạng đó. Database chỉ giữ rõ 4 ký tự đầu của thân mã nên gõ tới ký tự thứ 5–7 vẫn chỉ khớp theo 4 ký tự đầu — ra mọi mã cùng đầu, đủ 8 ký tự mới tìm đúng một mã (so băm).

Một dòng tổng theo mục của dấu vết — kết quả .

Truy vấn dấu vết của MỘT mã truy cập — hàm thuần trên IQueryable để có ca test dịch SQL thật (test in-memory không bắt được lỗi dịch GroupBy). Phạm vi (mã có thuộc người gọi không) kiểm ở service TRƯỚC khi gọi vào đây.

Dòng thời gian, mới nhất trước.

Tổng theo mục: thời gian xem = tổng DurationSec của các lần rời mục (SectionLeave), số lần mở = số sự kiện SectionOpen.

Màn quản trị "Mã truy cập" của Cổng nhượng quyền (docs/plan-cong-nhuong-quyen.md §3.2, §3.10). là chìa vào nội dung riêng tư và chứa dữ liệu cá nhân của khách: MỌI đường đọc/ghi đi qua — người chỉ có FranchisePortal.Sale chỉ chạm được mã của đăng ký nhượng quyền mình phụ trách (plan §6.23); ngoài phạm vi trả "không tìm thấy". Mọi đường GHI kèm một dòng trong cùng transaction.

Dòng mã đã có KHÔNG BAO GIỜ ghi bằng UpdateAsync của repository (UPDATE mọi cột từ ảnh chụp lúc đọc — hồi sinh mã vừa thu hồi, đè bộ đếm website ghi): mọi thay đổi đi qua .

Chi tiết kèm mã rõ, trạng thái mở/khoá từng mục, lịch sử gần nhất; null khi không có hoặc ngoài phạm vi.

Tạo mã cho khách của một đăng ký nhượng quyền (plan §6.23): chỉ người phụ trách đăng ký, và đăng ký chưa có mã chưa thu hồi. Mã sinh ở máy chủ, trả rõ trong kết quả; database giữ băm + bản mã hoá. Mặc định chưa mở mục nào.

Mở các mục cho mã — chỉ mục đang bật; mục đang tắt/không có bị bỏ qua.

Mở mọi mục đang bật.

Khoá lại các mục.

Gia hạn +7 ngày theo ; mã đã thu hồi không gia hạn được.

Thu hồi mã ngay lập tức và đóng mọi phiên đang mở của nó.

Lịch sử thao tác, mới nhất trước; null khi không có hoặc ngoài phạm vi.

Gắn phạm vi giá cho mã: các phường/xã 2 cấp ở một hay nhiều tỉnh CÓ GIÁ ở phiên bản giá hiện hành (§6.17, §6.26 — không đòi vùng phủ); không phường = gỡ. Khách mở mục "Bảng giá vùng phủ" của cổng chỉ thấy đúng thứ đã gắn (plan cổng §6.10).

Dấu vết của khách: một trang sự kiện + tổng thời gian theo mục; null khi không có hoặc ngoài phạm vi.

Transcript hỏi-đáp với trợ lý AI của một mã (tab Hỏi đáp, GĐ G): một trang tin nhắn mới trước + bộ đếm câu hỏi; null khi mã không có hoặc ngoài phạm vi.

Khớp lựa chọn lớn nhất của bộ phân trang FE (pageSizeOptions tới 200).

Phạm vi mã truy cập của người thao tác — MỘT chỗ cho mọi đường đọc/ghi của service này.

Mã theo Id TRONG phạm vi của người thao tác; ngoài phạm vi trả null như không tồn tại. Ảnh chụp chỉ để ĐỌC (không theo dõi) — ghi thì qua .

Tóm tắt phạm vi giá của một mã cho cột "Phạm vi giá" của danh sách.

Tóm tắt phạm vi giá của một mã cho cột "Phạm vi giá" của danh sách.

Bốn bậc gói vùng phủ theo thứ tự ngưỡng (GĐ K).

"7 phường, xã · HUB" / "2 phường, xã · chưa đủ gói"; bảng bậc trống thì chỉ số phường.

Tóm tắt phạm vi giá của MỘT TRANG mã — ba truy vấn cho cả trang (dòng phường, tỉnh, bậc gói), không theo từng dòng. Mã không có trong kết quả = chưa gắn gì. Chỉ gọi với Id đã qua .

Tên các tỉnh theo thứ tự xuất hiện đầu tiên, cách nhau dấu phẩy.

Phạm vi giá đang gắn cho mã — null khi chưa gắn phường nào.

Câu từ chối khi người tạo không phải người phụ trách đăng ký (plan §6.23 mục 3 — kể cả quản lý); null = được tạo. Một hàm cho lần kiểm sớm và lần kiểm sau khi khoá dòng đăng ký.

Mã chưa thu hồi (kể cả đã hết hạn) của một đăng ký, mới nhất trước; null khi không có.

Chọn trong các mục ĐANG BẬT — mục đang tắt không bao giờ được mở thêm.

Mã mới chưa trùng băm với mã nào (kể cả mã đã xoá). 2^40 khả năng nên trùng gần như không xảy ra.

Danh sách mã tỉnh đã chuẩn hoá thành chuỗi 01,31 (null = mọi tỉnh), hoặc câu từ chối.

Ghi thay đổi của mã và dòng lịch sử của nó trong MỘT transaction. chạy SAU khi lưu để đọc được Id vừa sinh của mã mới. trả false (không dòng nào khớp điều kiện ghi) thì hoàn tác, KHÔNG ghi lịch sử và trả false.

Điều kiện WHERE của từng đường ghi lên một mã truy cập — MỘT nguồn cho store thật và store giả của test, để bỏ một điều kiện ở đây là đỏ ở cả hai nơi.

Gia hạn: mã chưa thu hồi VÀ hạn vẫn đúng như lúc đọc — hai lần bấm song song chỉ cộng một lần.

Thu hồi: chỉ mã chưa thu hồi — lần thu hồi thứ hai không đè người/lúc/lý do của lần đầu.

Đóng dấu sửa lên mã CHƯA thu hồi — đổi phạm vi giá của mã đã thu hồi thì không dòng nào khớp.

Đổi trạng thái đăng ký khi cấp mã: trạng thái vẫn là trạng thái vừa đọc — không đè thứ sale vừa chọn.

Phiên đang mở của một mã.

Ghi lên dòng bằng MỘT lệnh UPDATE chỉ chạm đúng cột của thao tác, điều kiện nằm ở WHERE (review GĐ A, mục 1). Repository.UpdateAsync ghi MỌI cột từ ảnh chụp lúc đọc: "Gia hạn" chạy song song với "Thu hồi" ghi lại Status = Active — mã vừa thu hồi sống lại; và từ GĐ B website tăng AccessCount/LastAccessAt/QuestionCount trên cùng dòng, thao tác của sale đè số cũ lên. Tách thành store riêng để service test được bằng repo giả (ExecuteUpdateAsync chỉ chạy trên EF thật) — cùng khuôn ITopicPublishStore.

Mọi hàm trả false/0 khi không dòng nào khớp điều kiện — người gọi coi là "đã bị người khác đổi".

Ghi hạn mới. Chỉ chạm ExpiresAt + cột audit.

Thu hồi. Chỉ chạm Status, nhóm cột Revoked* + cột audit.

Khoá dòng đăng ký nhượng quyền tới hết transaction đang mở bằng một lệnh UPDATE không đổi giá trị nào (Status = Status) — gọi ở ĐẦU transaction tạo mã: hai lần tạo mã song song cho cùng một đăng ký chạy lần lượt, lần sau đọc được mã lần trước vừa tạo (luật một mã chưa thu hồi mỗi đăng ký, plan §6.23). Không đụng cột audit của đăng ký — cột "Cập nhật" của màn Đăng ký không đổi. false khi đăng ký không còn (đã xoá).

Đăng ký vừa được cấp mã → trạng thái kèm MỘT dòng lịch sử "Đổi trạng thái" (plan §6.23 mục 8). Chỉ chạm Status + cột audit của đăng ký — StatusNote của sale giữ nguyên; điều kiện ở WHERE là "vẫn là ". Gọi TRONG transaction tạo mã (sau ); false khi không dòng nào khớp — không ghi lịch sử.

Đóng mọi phiên đang mở của mã (chỉ chạm EndedAt + cột audit); trả số phiên vừa đóng.

Đóng dấu "vừa sửa" lên mã chưa thu hồi — chỉ chạm cột audit. Gọi ở ĐẦU transaction của thao tác thay cả bộ dòng con (phạm vi giá): lệnh UPDATE giữ khoá dòng mã tới khi commit, nên hai người cùng đổi phạm vi giá của một mã chạy lần lượt thay vì để lại bộ dòng trộn của cả hai; mã vừa bị thu hồi thì trả false.

Màn "Cấu hình trợ lý" của Cổng nhượng quyền (plan §3.6, GĐ G — đóng CNQ-50 phía API): đọc / ghi các khoá FranchisePortal.Ai.* và "Hỏi thử" trợ lý với ngữ cảnh của một mã. Chỉ người có cờ CanConfigure (FranchisePortal.Manage; Founder) — kiểm lần hai ở đây ngoài [Authorize].

null khi người gọi không có cờ CanConfigure.

Hỏi trợ lý một câu với ngữ cảnh của một mã TRONG PHẠM VI người gọi — đúng ngữ cảnh khách cầm mã đó sẽ có. Không lưu vào transcript, không trừ lượt hỏi của khách.

Lưu với dấu của bản form đã cũ — câu khác : trợ lý chưa chắc đang tắt (review FE G2b).

Id model từ danh sách đã đồng bộ của nhà cung cấp (SyncedModelsJson: mảng AiModelInfo).

Một tệp đang tải lên — controller đóng gói từ IFormFile. phải seek được.

Một tệp đang tải lên — controller đóng gói từ IFormFile. phải seek được.

Định dạng tệp đã nhận ra từ NỘI DUNG (magic bytes), không phải từ tên hay Content-Type trình duyệt gửi.

Định dạng tệp đã nhận ra từ NỘI DUNG (magic bytes), không phải từ tên hay Content-Type trình duyệt gửi.

Luật nhận tệp riêng tư của Cổng nhượng quyền (plan §3.4, §3.10) — hàm thuần: whitelist phần mở rộng và trần kích thước theo loại, nhận dạng bằng magic bytes.

Phần mở rộng nhận theo loại; loại không tải lên được (audio thuyết minh do hệ thống sinh) → rỗng.

Nhận dạng tệp: phần mở rộng phải thuộc whitelist của VÀ nội dung phải đúng định dạng đó. Trả định dạng, hoặc câu từ chối. Vị trí đọc của được trả về đầu.

Tệp Office Open XML: là ZIP, có phần tài liệu chính của đúng loại, và KHÔNG mang macro (vbaProject.bin — tệp .docm/.xlsm đổi đuôi).

Tệp riêng tư của Cổng nhượng quyền (docs/plan-cong-nhuong-quyen.md §3.4, §6.5): tải lên, liệt kê, xoá. Nội dung nằm trên ổ đĩa qua ; khách chỉ đọc được qua đường /tep của website sau khi kiểm mục của tệp đã mở cho mã.

Kiểm loại + magic bytes + kích thước, ghi đĩa RỒI MỚI ghi database; ghi database lỗi thì xoá tệp vừa ghi. PDF được trích văn bản cho trợ lý AI — trích lỗi vẫn lưu tệp.

Tệp của một mục (hoặc mọi tệp khi null), theo thứ tự.

Xoá mềm bản ghi rồi xoá tệp vật lý. Từ chối khi tệp đang là audio thuyết minh của một mục, hoặc đang được khối nội dung của mục dùng — trong bản đã xuất bản (khách đang thấy) hay bản đang sửa (CNQ-32).

Trần số trang PDF đem trích trong request tải lên — PDF scan phải OCR từng trang.

Câu từ chối khi tệp đang nằm trong khối nội dung của mục nó thuộc về; null = không khối nào dùng. Bản đã xuất bản xét TRƯỚC: xoá tệp khách đang thấy là trang của khách mất tài liệu / video mà không ai được báo (website tự gỡ lúc đọc). Bản đang sửa: xoá xong thì lần lưu / xuất bản kế tiếp bị từ chối vì tham chiếu treo. Khối chỉ tham chiếu được tệp của ĐÚNG mục (TopicService.CheckFileRef) nên chỉ cần soát topic của mục đó.

Văn bản của PDF cho trợ lý AI; trích lỗi hoặc không có chữ → null, không chặn việc lưu tệp.

Tên gốc để hiển thị: bỏ đường dẫn và ký tự điều khiển, cắt cho vừa cột, giữ phần mở rộng đã nhận dạng.

Cổng nhượng quyền: nút nào được hiện (rule quyen-hien-thi) và mỗi người thấy những mã truy cập nào. Hàm thuần cùng khuôn : nhận role đã phân giải qua IUserRoleResolver — để luật "ai thấy gì" có ca test gọi thẳng vào nó.

Vai bỏ qua mọi kiểm tra role của hệ thống — ẩn nút của Founder là dựng hàng rào không có thật.

Role biên tập: mục cổng, khối, tệp riêng tư, xuất bản (plan §6.8).

Role sale: mã truy cập của các đăng ký nhượng quyền MÌNH phụ trách (plan §6.23).

Role quản lý: mọi mã, cấu hình, và mọi việc của .

Cờ của màn "Nội dung cổng" và "Cấu hình trợ lý".

Role đã phân giải qua IUserRoleResolver; null = không có role nào

Cờ của khối "Mã truy cập" trong màn Đăng ký nhượng quyền (màn Mã truy cập riêng bỏ ở GĐ L, plan §6.23).

Role đã phân giải qua IUserRoleResolver; null = không có role nào

Phạm vi mã truy cập — MỘT hàm cho mọi đường đọc/ghi: Manage/Founder thấy tất cả; chỉ có Sale thì chỉ thấy mã của đăng ký mình đang phụ trách (FranchiseLead.PicId = mình — plan §6.23: mã đi theo đăng ký, giao đăng ký là mã đi theo; mã chưa gắn đăng ký chỉ quản lý thấy); không role thì không thấy gì. Cột SaleUserId để ngủ, KHÔNG đọc ở đây (CNQ-80).

Đăng ký nhượng quyền (IRepository<FranchiseLead>.Query() — đã lọc xoá mềm, nên mã của đăng ký đã xoá chỉ quản lý thấy).

Cờ hiển thị của màn "Nội dung cổng" / "Cấu hình trợ lý".

Cờ hiển thị của màn "Nội dung cổng" / "Cấu hình trợ lý".

Cờ hiển thị của khối "Mã truy cập" (màn Đăng ký nhượng quyền).

Cờ hiển thị của khối "Mã truy cập" (màn Đăng ký nhượng quyền).

Nguồn tra cứu của khối "Phạm vi giá" ở màn Mã truy cập (docs/plan-cong-nhuong-quyen.md §3.9, CNQ-39): tỉnh CÓ GIÁ và phường/xã CÓ GIÁ ở phiên bản giá hiện hành — không đòi tỉnh thuộc vùng phủ (§6.26) — và bốn bậc gói vùng phủ (GĐ K) để drawer báo gói theo số phường đang chọn.

Gác bằng role của CỔNG (cờ CanSetPriceScope), không bằng FranchisePrice.*: sale là người báo giá cho khách của mình (plan §6.10, CNQ-45) và chỉ đọc được đúng thứ POST {id}/price-scope cho gắn — phường chưa có giá không ra ở đây. Đừng nới role của api/FranchisePrice / api/FranchisePackageTier để lấy dữ liệu cho màn này.

Tỉnh/thành phố có giá ở phiên bản giá hiện hành.

Bốn bậc gói vùng phủ theo thứ tự ngưỡng.

Phường/xã 2 cấp của một tỉnh có giá ở phiên bản giá hiện hành.

Cửa của cả ba nguồn — kiểm lần hai sau [Authorize]: người không gắn được giá thì không đọc được gì.

Người đang thao tác trên Cổng nhượng quyền — controller đóng gói từ User.GetCurrentUser().

Người đang thao tác trên Cổng nhượng quyền — controller đóng gói từ User.GetCurrentUser().

Màn quản trị "Nội dung cổng" (docs/plan-cong-nhuong-quyen.md §3.1, §3.4): danh sách mục, siêu dữ liệu, thứ tự, bật/tắt. Khối nội dung của mục nằm ở topic vật chủ FranchisePortal.<Code> — service này không chạm khối.

Mọi mục chưa xoá, theo thứ tự hiển thị (cả mục đang tắt).

null khi không có.

Tạo một mục nội dung kèm topic vật chủ của nó, trong MỘT transaction. Mã mục sinh từ slug và không đổi về sau. Mục mới xếp cuối, đang bật, và khoá với mọi mã truy cập như mọi mục.

Sửa tiêu đề, slug, tóm tắt, icon — không đổi mã, loại, thứ tự, trạng thái bật.

Sắp lại thứ tự; phải là đúng toàn bộ mục đang có, mỗi mục một lần.

Bật/tắt mục. Tắt = ẩn với MỌI mã truy cập, kể cả mã đã được mở mục này; dòng mở khoá giữ nguyên.

Chuẩn hoá và kiểm đầu vào; lỗi trả câu tiếng Việt hiển thị được.

Mã mục chưa từng dùng, sinh từ slug. Kiểm cả mục và topic ĐÃ XOÁ: mã không tái dùng, vì topic FranchisePortal.<Code> cũ vẫn còn và dấu vết/hội thoại cũ tham chiếu mã đó.

Danh mục cho form mục cổng — lấy từ và , không chép tay.

Tham số của một phiên bản bảng giá cần cho phần tổng — tách khỏi entity để hàm tính là hàm thuần.

Tham số của một phiên bản bảng giá cần cho phần tổng — tách khỏi entity để hàm tính là hàm thuần.

Giá và cọc của một phường/xã đã chọn.

Giá và cọc của một phường/xã đã chọn.

Phần tổng của bảng giá nhượng quyền — hàm thuần, số nguyên đồng, không float. Mọi mức tiền lấy từ (dữ liệu đã upload), không ghi cứng trong mã.

Công thức theo đặc tả: Tổng phí nhượng quyền (gồm VAT) = Σ giá. Giá chưa VAT = làm tròn nửa lên (tổng ÷ (1 + thuế suất)); tiền VAT = tổng − giá chưa VAT. Tiền bảo đảm theo vùng = min(tối đa, max(tối thiểu, Σ cọc theo sản lượng)). Bảo đảm xe thuê = số xe × bảo đảm mỗi xe; tổng tiền bảo đảm = theo vùng + xe thuê. Tổng nộp khi ký = tổng phí nhượng quyền + tổng tiền bảo đảm.

Chia rồi làm tròn nửa lên về số nguyên đồng — 41.666.666,67 → 41.666.667.

Một phường/xã của file mẫu — phần hệ thống điền sẵn.

Một phường/xã của file mẫu — phần hệ thống điền sẵn.

Dữ liệu đầu trang + bảng chi tiết + phần tổng của bảng giá xuất cho khách.

Null khi xuất cả tỉnh (không tích chọn) — không có phần tổng.

Dựng hai file Excel của chức năng: file mẫu cho quản trị điền giá, và bảng giá xuất cho khách. Hàm thuần — nhận dữ liệu đã nạp, trả byte[].

Ba câu ghi chú cuối file, đúng nguyên văn đặc tả. Hai câu đầu dùng chung với mục bảng giá của cổng ().

Tên cột hiển thị của bảng chi tiết trong file xuất — cùng sáu cột với cổng nhượng quyền.

Cột "Giá nhượng quyền" — số của phần tổng cũng nằm ở cột này để thẳng hàng với giá.

Hai nút của chức năng Bảng giá nhượng quyền mà máy chủ gác bằng quyền có được hiện cho một người hay không (rule quyen-hien-thi). Hàm thuần cùng khuôn : nhận role đã phân giải qua IUserRoleResolver, trả cờ — để luật "ai thấy gì" có ca test gọi thẳng vào nó.

Vai bỏ qua mọi kiểm tra role của hệ thống — ẩn nút của Founder là dựng hàng rào không có thật.

Role của trang quản trị: template, preview, import, versions; và thêm/sửa tay từng dòng (lines/*) ngay trên trang xuất.

Role của trang xuất: current, export/provinces, export/wards, export.

Role đã phân giải qua IUserRoleResolver; null = không có role nào

Cờ của màn tham số bốn bậc gói vùng phủ (api/FranchisePackageTier, GĐ K). Cùng hai role với bảng giá phường: xem, xem và sửa.

Role đã phân giải qua IUserRoleResolver; null = không có role nào

Cờ của màn tham số kế hoạch kinh doanh (api/FranchiseBusinessPlan, GĐ M — §6.24 mục 5). Cùng hai role với bảng giá phường: xem + tính thử, xem, tính thử và sửa.

Role đã phân giải qua IUserRoleResolver; null = không có role nào

Cờ hiển thị của chức năng bảng giá nhượng quyền.

Cờ hiển thị của chức năng bảng giá nhượng quyền.

Cờ hiển thị của màn tham số gói vùng phủ.

Cờ hiển thị của màn tham số gói vùng phủ.

Người đang thao tác — controller đọc từ User.GetCurrentUser() rồi truyền xuống.

Người đang thao tác — controller đọc từ User.GetCurrentUser() rồi truyền xuống.

Bảng giá nhượng quyền bưu cục: quản trị tải mẫu và upload phiên bản giá; sale chọn tỉnh, phường/xã rồi xuất. Dữ liệu nội bộ — chỉ phục vụ SPA quản trị, không đưa lên website, app khách, app lái xe hay API công khai.

Mọi tỉnh/thành phố 2 cấp, cờ IsDefault cho tỉnh thuộc vùng phủ hiện tại.

File mẫu gồm toàn bộ phường/xã của các tỉnh được chọn.

Kiểm toàn bộ file. Có lỗi → báo theo dòng; không lỗi → bản xem trước. Không ghi gì.

Kiểm lại toàn bộ file rồi lưu thành phiên bản mới, đặt làm hiện hành. Có lỗi thì không ghi gì.

Lịch sử phiên bản, mới nhất trước.

Phiên bản đang dùng để xuất; null khi chưa upload lần nào.

Các tỉnh có ít nhất một phường/xã có giá trong phiên bản hiện hành.

Phường/xã có giá của một tỉnh, tìm theo tên có dấu hay không dấu.

Xuất bảng giá Excel. Không tích phường/xã nào → cả tỉnh, không phần tổng.

Chi tiết một dòng giá của phiên bản hiện hành; null khi phường/xã không có giá.

Phường/xã 2 cấp của một tỉnh CHƯA có giá trong phiên bản hiện hành — để thêm dòng.

Thêm tay một dòng giá vào phiên bản hiện hành, tính lại số dòng và tổng giá của phiên bản.

Sửa tay một dòng giá của phiên bản hiện hành, tính lại tổng giá của phiên bản.

Gắn thông tin sửa tay vào phiên bản. Dòng của file upload mang UpdatedTime đúng bằng UploadedAt (cùng một now trong , cùng kiểu datetimeoffset(7)) — dòng nào muộn hơn là đã được thêm hoặc sửa tay sau đó. Thường chỉ vài dòng nên gom trong bộ nhớ.

Trần của decimal(12,3) — cột AreaKm2.

Ghi dòng và tính lại số dòng + tổng giá của phiên bản trong cùng một giao dịch. Tổng đếm lại từ DB chứ không cộng dồn chênh lệch, để hai quản trị sửa song song vẫn hội tụ về đúng số ở lần ghi sau.

Cùng luật với sheet BangGia của file upload ().

Điểm lẻ là bình thường (mô hình giá chấm theo trọng số) — lưu 2 chữ số thập phân như lúc upload.

Dấu của dòng = UpdatedTime tính tới tick — datetimeoffset(7) giữ đủ độ chính xác đó.

Loại phường/xã: Prefix (Phường/Xã); 14 đặc khu trong danh mục để trống Prefix và ghi "Đặc khu X" vào Name.

Tên phường/xã không kèm loại — "Đặc khu Cát Hải" với Prefix trống → "Cát Hải".

Bỏ dấu, chữ thường — dùng chung cho lúc lưu và lúc tìm để hai bên luôn khớp.

Một phường/xã trong danh mục 2 cấp — phần parser cần để kiểm id.

Một phường/xã trong danh mục 2 cấp — phần parser cần để kiểm id.

Một dòng sheet BangGia đã qua kiểm, chưa ghép tên từ danh mục.

Một dòng sheet BangGia đã qua kiểm, chưa ghép tên từ danh mục.

Sheet ThamSo đã qua kiểm.

Sheet ThamSo đã qua kiểm.

Kết quả đọc file: có lỗi thì rỗng và null.

Bố cục file mẫu bảng giá nhượng quyền (tên sheet, tên cột, mã tham số) và bộ đọc kiểm toàn bộ file trước khi ghi. Hàm thuần trên — không chạm database; danh mục phường/xã truyền vào dưới dạng từ điển.

Tên cũ / tên bị EPPlus cắt vẫn được nhận, để file điền tay theo tên cũ không bị bác oan.

Thứ tự cột của sheet BangGia trong file mẫu.

Cột bắt buộc phải có trong sheet BangGia để đọc được file.

7 dòng của sheet ThamSo, đúng thứ tự in trong file mẫu.

Kiểm toàn bộ file. Mọi lỗi gom lại theo dòng, không dừng ở lỗi đầu — quản trị sửa một lần cho xong.

File đã mở. Phường/xã 2 cấp còn hiệu lực trong danh mục, khoá theo Location.Id. Mã phiên bản đã có — trùng thì báo lỗi ở sheet ThamSo.

Hàng 1 → tên cột chuẩn hoá → chỉ số cột. Chấp nhận viết hoa/thường, dấu cách thay gạch dưới, có dấu.

Thuế suất chấp nhận 0.08, 8, "8%" — lưu dạng tỉ lệ 0 ≤ t < 1.

Kế hoạch E8 của một đơn COD theo luật ví trong phiếu đối soát khách.

Cước chính thức (gồm phí thu hộ) — "phí" của dòng phiếu. Cước nợ đơn hoàn cấn vào đơn này. Tiền trả khách của đơn (E8).

Kế hoạch E8 của một đơn COD theo luật ví trong phiếu đối soát khách.

Cước chính thức (gồm phí thu hộ) — "phí" của dòng phiếu. Cước nợ đơn hoàn cấn vào đơn này. Tiền trả khách của đơn (E8).

Cước chính thức (gồm phí thu hộ) — "phí" của dòng phiếu.

Cước nợ đơn hoàn cấn vào đơn này.

Tiền trả khách của đơn (E8).

Kế hoạch ví của một phiếu đối soát khách: chỉ các đơn theo luật ví (đơn khác giữ công thức cũ).

Tổng cước nợ đơn hoàn cấn trong phiếu.

Phiếu không dính đơn theo luật ví.

Khoản khách nợ cước đơn hoàn (dòng NO-CUOC) và E8 / E13 ở đối soát khách (Ví v2 — plan §3.6, mota L2-4): danh sách đơn nợ cước theo bưu cục sale, "đã thu ngoài", và móc vào phiếu đối soát khách (CustomerReconciliationSlip — luồng đối soát đang dùng, §6 mục 21): lập phiếu = tính E8 + giữ chỗ khoản nợ; từ chối = trả chỗ; hoàn thành = E13 + đóng nợ CÙNG giao dịch chuyển tiền.

Danh sách đơn nợ cước — bưu cục bị ép về ví mình; LADA lọc theo bưu cục / khách. Mặc định: còn nợ + đang giữ chỗ.

Kế toán (role Manage) ghi nhận bưu cục sale đã tự thu khoản nợ của khách ngoài ví — đóng nợ, KHÔNG có E13.

Lập phiếu đối soát khách: với từng đơn COD có bưu cục nhượng quyền bật ví bán (giao thành công) tính E8 bằng planner và phân bổ khoản nợ còn mở của khách (). Đơn không theo luật ví vắng mặt.

Giữ chỗ các khoản nợ đã phân bổ cho phiếu (UPDATE có điều kiện còn nợ). Có khoản vừa bị phiếu khác giữ → trả chỗ đã giữ + NÉM lỗi.

Phiếu bị từ chối / huỷ lập: trả mọi khoản nợ phiếu đang giữ về "còn nợ".

Hoàn thành phiếu (CÙNG giao dịch chuyển tiền của phiếu): mỗi đơn theo luật ví → planner ghi E13 cho khoản nợ đã giữ, kiểm tiền trả khách đúng số trên phiếu, rồi đóng nợ (Offset). NÉM lỗi khi lệch — nơi gọi rollback.

Đơn nào trong danh sách có bên bán là bưu cục nhượng quyền đang bật ví (để màn đối soát cũ từ chối — §6 mục 21).

Khoản nợ cước đơn hoàn một phiếu đối soát khách đang giữ chỗ / đã cấn (V-37 — chi tiết phiếu + Excel). KHÔNG kiểm quyền: nơi gọi đã kiểm quyền xem phiếu.

Dòng NO-CUOC còn hiệu lực (không xoá / huỷ / từ chối).

Bưu cục NHƯỢNG QUYỀN đang bật ví ("bên bán có ví", §6 mục 20) — chi nhánh LADA bật ví để đo không tính.

Khoản nợ còn mở (chưa giữ chỗ) của khách — của mọi bưu cục sale NHƯỢNG QUYỀN đang bật ví. Ví bưu cục đã tắt / chi nhánh LADA bật ví để đo: không cấn (không có ví nào nhận E13 thì cấn là trừ tiền khách mà không trả ai — review GĐ C); bưu cục tự thu.

Đầu vào dựng bảng kê một phiếu tháng.

Đầu vào dựng bảng kê một phiếu tháng.

Một đơn nội vùng của kỳ (V-65, anh Thắng 27/10/2026): bưu cục tự lấy, tự giao, cước chính thức = cước tạm tính — liệt kê riêng kèm cân khai để kế toán kiểm xác suất cân.

Một đơn nội vùng của kỳ (V-65, anh Thắng 27/10/2026): bưu cục tự lấy, tự giao, cước chính thức = cước tạm tính — liệt kê riêng kèm cân khai để kế toán kiểm xác suất cân.

Bảng kê Excel của phiếu tháng = biên bản đối chiếu (Ví v2 plan §3.6): (1) chiều 1 LADA → bưu cục (E4 / E4h), (2) chiều 2 bưu cục → LADA (E6 / E7 / E10 / E11 / E12) — mỗi mã một dòng, tổng gồm VAT, tách chưa VAT / VAT làm tròn đồng sau cùng; (3) chiều 3 bưu cục sale → khách (E5, CK-THẲNG, đơn hoàn); (4) chi tiết mọi dòng của kỳ + biên bản Đầu kỳ / Phát sinh / Nạp / Rút / Cuối kỳ. Hàm THUẦN trả byte[] — không lưu file ra đĩa (khuôn FranchisePrice: tiền nội bộ không nằm ở URL công khai).

In theo giờ Việt Nam dù thời điểm lưu kèm offset nào (máy chủ / SQL chạy UTC).

Dựng workbook. : 0 = đủ 5 sheet, 1–5 = một sheet (5 = đơn nội vùng, V-65).

Bó role của phiếu đối soát tháng (SPEC §3.10) và luật THUẦN đổi role thành cờ.

Founder.

Kế toán LADA: lập nháp, phát hành, khoá, đánh dấu hoá đơn, xuất bảng kê.

Chủ bưu cục xác nhận phiếu của mình.

Mọi đường xem phiếu (bưu cục có Confirm hoặc xem ví được xem phiếu của mình).

Đổi role thành cờ.

Cờ role thô của phiếu tháng.

Tạo được điều chỉnh tay Ví (bó quyền của POST api/FranchiseWallet/adjustments).

Cờ role thô của phiếu tháng.

Tạo được điều chỉnh tay Ví (bó quyền của POST api/FranchiseWallet/adjustments).

Tạo được điều chỉnh tay Ví (bó quyền của POST api/FranchiseWallet/adjustments).

Phạm vi truy cập phiếu tháng của một người dùng (fail-closed).

Phạm vi truy cập phiếu tháng của một người dùng (fail-closed).

Bưu cục xem phiếu của mình.

Bưu cục xác nhận phiếu của mình.

Được xem phiếu của bưu cục này không.

Phiếu đối soát tháng + bảng kê hai chiều + phụ lục K1 (SPEC §3.6, GĐ4): Nháp → Chờ bưu cục xác nhận → Đã xác nhận (bấm, hoặc tự xác nhận sau 3 ngày làm việc) → Đã khoá (dòng Ví → đã đối soát) → Đã lập hoá đơn.

Bưu cục nhượng quyền để lọc / lập phiếu (kế toán LADA) — không mượn danh sách ví của màn Ví.

Khoá AppConfig số ngày làm việc để xác nhận.

Cước chính thức của đơn CK-THẲNG cho chiều 3 (Ví v2); null = chiều 3 ghi 0 cho đơn CK-THẲNG (test cũ dựng không có).

Dòng thuộc phiếu: đã khoá thì theo SettlementId; còn mở thì theo luật BelongsTo.

Chiều 3 của phiếu (Ví v2 plan §3.6): dòng E4 / E4h / E5 của phiếu + dòng thông tin NO-CUOC chốt trong kỳ (dòng thông tin không thuộc phiếu nên lọc theo thời điểm chốt), cước chính thức của đơn CK-THẲNG đọc từ đơn.

V-65 (anh Thắng 27/10/2026): đơn có dòng trong phiếu mà cước chính thức chốt theo nguồn "nội vùng" (= cước tạm tính) — liệt kê riêng kèm cân khai để kế toán kiểm xác suất cân. Chỉ đơn CHỐT trong kỳ của phiếu (review H2): đơn có dòng ở hai kỳ chỉ lên một phiếu, và phiếu đã phát hành / khoá không tự thêm đơn chốt sau kỳ.

Nạp tiền ví bưu cục (Ví v2 — plan §3.5 đường 1): kế toán quỹ ghi nhận khoản bưu cục đã chuyển vào tài khoản LADA → khoản nạp Confirmed + dòng NAP (+, đã chốt, EventAt = ngày tiền vào) cùng giao dịch khoá ví. KHÔNG có đường cho bưu cục tự nạp.

Đường 2 (import sao kê khớp tài khoản ảo → khoản nạp Pending chờ kế toán xác nhận một nút) chỉ để chỗ — chờ ngân hàng cấp tài khoản ảo (V-12, Q118 kế toán): bảng và trạng thái đã có, chưa code import. Nạp xong đơn bị chặn không tự xuất — điều phối bấm gán lại (mota L3).

Kế toán quỹ ghi nhận một khoản nạp (role Treasury).

Danh sách khoản nạp — bưu cục bị ép về ví mình; LADA lọc theo bưu cục hoặc xem mọi ví.

Kiểm một yêu cầu ghi nhận nạp (thuần — ngày tính theo giờ Việt Nam).

Tên trạng thái khoản nạp.

Bó role của Ví bưu cục (SPEC §3.10) và luật THUẦN đổi tập role thành cờ.

Founder.

Bưu cục xem ví mình.

Kế toán LADA: mọi ví, tạo điều chỉnh, duyệt lần 1, đối chiếu lại.

Duyệt lần 2 điều chỉnh từ ngưỡng.

Chủ bưu cục tạo / huỷ lệnh rút của bưu cục mình (Ví v2, migration M202610251501; service GĐ C).

Kế toán quỹ: ghi nhận nạp, chuyển / từ chối lệnh rút, nhập sao kê (Ví v2).

Bật ví cho chi nhánh, tham số theo bưu cục, tài khoản nhận tiền rút (Ví v2).

Gán bưu cục sở hữu khách (role sẵn có của màn khách hàng).

Đọc bưu cục sở hữu khách.

Mọi đường xem dòng Ví.

Đường của LADA (mọi ví).

Danh sách ví (V-47): LADA xem sổ, kế toán trưởng mở cấu hình, kế toán quỹ chọn bưu cục khi ghi nạp.

Xem lệnh rút / khoản nạp: bưu cục (ví mình), kế toán (mọi ví), kế toán quỹ (mọi ví).

Đổi tập role thành cờ. Rỗng = mọi cờ tắt.

Cờ role thô của Ví.

Bật ví cho chi nhánh, sửa tham số theo bưu cục (Ví v2 — role hoặc Founder). Tạo / huỷ lệnh rút của ví bưu cục mình (role ) — service còn đòi người gọi thuộc đúng bưu cục nhượng quyền có ví, Founder không có ví nên cũng không rút được. Kế toán quỹ: ghi nhận nạp, chuyển / từ chối lệnh rút của mọi ví (role ) — không kèm quyền rút.

Cờ role thô của Ví.

Bật ví cho chi nhánh, sửa tham số theo bưu cục (Ví v2 — role hoặc Founder). Tạo / huỷ lệnh rút của ví bưu cục mình (role ) — service còn đòi người gọi thuộc đúng bưu cục nhượng quyền có ví, Founder không có ví nên cũng không rút được. Kế toán quỹ: ghi nhận nạp, chuyển / từ chối lệnh rút của mọi ví (role ) — không kèm quyền rút.

Bật ví cho chi nhánh, sửa tham số theo bưu cục (Ví v2 — role hoặc Founder).

Tạo / huỷ lệnh rút của ví bưu cục mình (role ) — service còn đòi người gọi thuộc đúng bưu cục nhượng quyền có ví, Founder không có ví nên cũng không rút được.

Kế toán quỹ: ghi nhận nạp, chuyển / từ chối lệnh rút của mọi ví (role ) — không kèm quyền rút.

Thấy mọi ví.

Phạm vi truy cập Ví của một người dùng (fail-closed).

Phạm vi truy cập Ví của một người dùng (fail-closed).

Xem mọi ví.

Xem ví của bưu cục mình (role View + thuộc bưu cục nhượng quyền).

Được xem ví này không.

Tạo / huỷ lệnh rút của ví bưu cục mình (role Withdraw + thuộc bưu cục nhượng quyền) — Ví v2 §3.5.

Kế toán quỹ (Treasury) hoặc Founder: ghi nhận nạp, chuyển / từ chối lệnh rút của mọi ví.

Xem lệnh rút / khoản nạp / đơn nợ cước của ví này: LADA (Manage / Approve / Treasury) mọi ví; bưu cục (View hoặc Withdraw) chỉ ví mình.

Thấy lệnh rút / khoản nạp của mọi ví.

Đọc dòng Ví / tóm tắt / đơn nợ cước / dự kiến phí: ví mình (bưu cục) hoặc mọi ví (LADA) — plan §3.8.1.

Danh sách ví: LADA xem sổ, kế toán trưởng (Config) mở cấu hình, kế toán quỹ (Treasury) chọn bưu cục khi ghi nạp (V-47).

API Ví bưu cục (SPEC §3.8 api/FranchiseWallet): xem dòng, tóm tắt, điều chỉnh tay duyệt hai người.

Bật ví cho một chi nhánh (Ví v2 §1.1) — role Config / Founder; chi nhánh LADA BlockOutbound = false.

Sổ vấn đề (LADA). Không lọc = vấn đề đang mở. / lọc; gồm cả vấn đề đã tự đóng (số đo "sẽ chặn" tuần đầu); / theo ngày gặp gần nhất (giờ VN, ngày cuối tính trọn).

Sửa tham số + tài khoản của ví (role Config, plan §3.8.1); ghi lịch sử khi có giá trị đổi.

Lịch sử đổi cấu hình của một ví (role Config), mới nhất trước.

Dự kiến phí nếu đơn giao thành công từ trạng thái hiện tại (planner Forecast, không ghi sổ). LADA thấy mọi dòng; bưu cục chỉ dòng của mình và chỉ khi bưu cục mình tham gia đơn (bán / lấy / phát / phát hoàn) — đơn khác 403.

Khoá AppConfig ngưỡng duyệt hai người.

Lệnh rút — để từ chối khoản hoàn lệnh rút (RUT-HOAN chờ duyệt) mở lại lệnh (review GĐ C); null = dựng không có rút.

Lịch sử đổi cấu hình ví (GĐ D); null = dựng không ghi lịch sử (test cũ).

Dòng danh sách ví (Các ví + Cấu hình ví) — số dư / thống kê do nơi gọi cộng sẵn.

Tên loại vấn đề (V-24).

Dòng giữ tiền (E1 / E2 / E3 giữ cước, COD bưu cục đang cầm; E9 trả lại phần giữ) — tiền mặt bưu cục cầm hộ LADA, không phải lãi / lỗ: lãi gộp dự kiến không tính chúng (bấm thật D2: đơn GỬI-TRẢ 110.000 đ hiện "lãi gộp −48.000 đ" thay vì +62.000 đ).

Tên vai của bưu cục trên đơn (plan §3.8.1) — S / L / P / PH.

Cơ sở tính đọc được của một dòng (plan §3.8.1): tiền thu hộ giữ / đảo theo COD, phần phí thu hộ theo phí thu hộ, còn lại theo cước — kèm "chính thức" (đã chốt khi nhập kho) hay "tạm tính". null khi dòng không ghi cơ sở (nạp, rút, điều chỉnh tay, mã cũ). E1 và E5 của đơn người gửi trả ghi cơ sở = số lái xe THỰC thu khi lấy (V-58) — không phải cước: bấm thật F2 đơn thu 120.000 / cước 130.000 từng hiện "Cước tạm tính 120.000 đ".

Tên sự kiện.

Lệnh rút tiền ví bưu cục (Ví v2 — plan docs/plan-vi-buu-cuc-v2.md §3.4 "Rút", §3.5; Docs §4 "Rút tiền"): chủ bưu cục tạo lệnh, ví trừ NGAY (dòng RUT) trong cùng giao dịch khoá ví; kế toán quỹ chuyển tiền rồi xác nhận, hoặc từ chối (hoàn RUT-HOAN, từ ngưỡng duyệt hai người thì chờ người thứ hai); chủ bưu cục huỷ lệnh còn chờ (hoàn ngay).

Ví = bưu cục của người gọi, tài khoản nhận = chụp từ do kế toán khai — request không mang bưu cục hay tài khoản (chống IDOR). Khoá ví bằng (sp_getapplock chủ khoá = giao dịch) rồi mới đọc số dư / số lệnh hôm nay: hai lệnh rút song song xếp hàng, lệnh sau thấy lệnh trước.

Chủ bưu cục tạo lệnh rút từ ví của bưu cục mình (role Withdraw).

Chủ bưu cục huỷ lệnh còn chờ của ví mình → hoàn ví ngay (RUT-HOAN đã chốt).

Kế toán quỹ xác nhận đã chuyển tiền (role Treasury).

Kế toán quỹ từ chối → RUT-HOAN; từ ngưỡng duyệt hai người thì RUT-HOAN chờ người duyệt thứ hai (role Approve) mới vào số dư.

Danh sách lệnh rút — bưu cục bị ép về ví mình; LADA (Manage / Approve / Treasury) lọc theo bưu cục hoặc xem mọi ví.

Huỷ (chủ bưu cục) / từ chối (kế toán quỹ) một lệnh còn chờ: khoá ví, đọc lại lệnh trong giao dịch, ghi RUT-HOAN (+) trỏ dòng RUT gốc. = RUT-HOAN chờ người duyệt thứ hai (chưa vào số dư); không thì chốt ngay và RUT gốc đánh dấu đã đảo.

Khoá ví của lệnh rồi đọc lại lệnh (đang theo dõi) trong giao dịch — xác nhận / huỷ / từ chối song song xếp hàng ở khoá ví.

Thông điệp từ chối luôn nêu số tối đa rút được ngay lúc này (plan §3.4 "Rút").

Đầu ngày hôm nay theo giờ Việt Nam — "1 lệnh / ngày" không lệch 7 giờ khi máy chủ chạy UTC (bẫy plan §7).

Tên trạng thái lệnh rút.

Đầu vào xuất Excel một phiên bản bảng giá nội bộ.

Đầu vào xuất Excel một phiên bản bảng giá nội bộ.

Xuất Excel bảng giá nội bộ (SPEC §3.8 GET versions/{id}/export, GĐ5): đúng khung ma trận (hàng = dải cự ly, cột = nấc cân) và mã phiên bản ở đầu trang. Hàm THUẦN trả byte[], không lưu ra đĩa.

Dựng workbook một sheet.

Bó role của bảng giá nội bộ (SPEC Q26, §3.10) và luật THUẦN đổi tập role thành cờ hiển thị.

Mỗi cờ tương ứng đúng bó role của endpoint nó gác (rule quyen-hien-thi). Founder vượt ở tầng attribute (ServerRoleAuthorizationHandler) nhưng hàm cờ và service phải tự cộng Founder.

Founder — vượt mọi kiểm tra role.

Soạn nháp, sửa, sao chép, sinh theo %, xem mọi bản, kiểm tra cân đối.

Duyệt, huỷ, đặt ngày ngừng áp dụng.

Bưu cục xem bản đang / sắp áp dụng cho chính mình.

Đường quản trị (xem danh sách, chi tiết, cân đối, danh sách bưu cục).

Đường xem bản áp dụng.

Đổi tập role thành cờ. Rỗng / null = mọi cờ tắt (fail-closed).

Cờ role thô (chưa xét bưu cục của người dùng).

Cờ role thô (chưa xét bưu cục của người dùng).

Thấy mọi phiên bản / mọi bưu cục.

Người thao tác — controller dựng từ User.GetCurrentUser().

Người thao tác — controller dựng từ User.GetCurrentUser().

Phạm vi truy cập của một người dùng: cờ role + bưu cục của họ. Fail-closed — không role, không bưu cục nhượng quyền thì không thấy gì.

Phạm vi truy cập của một người dùng: cờ role + bưu cục của họ. Fail-closed — không role, không bưu cục nhượng quyền thì không thấy gì.

Thấy mọi phiên bản / mọi bưu cục (Manage, Approve, Founder).

Xem bản áp cho bưu cục mình: có role View VÀ thuộc một bưu cục nhượng quyền (SPEC Q29).

Được xem bảng giá áp cho bưu cục này không.

Bảng giá nội bộ cho bưu cục nhượng quyền: phiên bản / phạm vi / ô, sinh theo %, duyệt, cân đối, tra bản áp dụng (docs/bang-gia-noi-bo/SPEC.md §3.2–§3.3, §3.8). Luật thuần nằm ở Lada.Framework/.../Network/InternalPrice*.

Phạm vi truy cập của người dùng.

Danh sách phiên bản (SmartTable). Khoá lọc: kind, status (trạng thái hiển thị), agencyId, effectiveAt, keyword.

Chi tiết một phiên bản (header, phạm vi, ô, lệch khung, quyền thao tác, xem trước điều kiện duyệt).

Tạo nháp từ khung niêm yết hiện tại hoặc sao chép bản khác.

Sửa nháp.

"Sinh theo %".

Duyệt.

Huỷ (nháp: người soạn hoặc người duyệt; bản đã duyệt: người duyệt).

Đặt / bỏ ngày ngừng áp dụng của bản đã duyệt.

Kiểm tra cân đối tại một ngày cho một bưu cục (null = toàn mạng), có thể thay một bảng bằng bản nháp.

Ba bảng đang áp + sắp áp cho một bưu cục (bưu cục: chỉ bưu cục của mình).

Gợi ý mã phiên bản theo mẫu InternalPrice.VersionCodePattern.

Bưu cục nhượng quyền để chọn phạm vi.

Bản áp dụng kèm ô (không kiểm quyền — dùng nội bộ cho Ví bưu cục).

Xuất Excel một phiên bản (SPEC §3.8 GET versions/{id}/export, GĐ5) — cùng luật xem như .

Nhắc bưu cục về các bản bắt đầu áp dụng sau đúng InternalPrice.ReminderDaysBefore ngày (job 08:00, SPEC §3.11); trả số người nhận.

Khoá AppConfig ngưỡng % giữ lại.

Khoá AppConfig mẫu mã phiên bản.

Câu trả khi bản đã bị người khác sửa sau lúc mở.

Khoá AppConfig: số ngày trước ngày hiệu lực thì nhắc bưu cục (seed 3, migration M202610171200).

Mọi điều kiện duyệt (SPEC §3.3 mục 4, 6, 7): người duyệt, ngày, phạm vi, lệch khung, giá ô, chồng hiệu lực.

Bưu cục nhượng quyền (chưa xoá) mà bản này là bản áp dụng vào chính ngày bắt đầu của nó: bản toàn mạng không tính bưu cục đang có bản riêng phủ ngày đó (phạm vi hẹp thắng, SPEC §3.3).

Bản có đang áp hoặc sắp áp cho bưu cục này không (luật xem của role View).

Hàng = dải (hoặc một hàng cho phí lấy / giao), cột = nấc cân — khuôn ma trận của priceList.vue.

Bản đã được sửa sau dấu thời gian màn hình đang giữ (lệch quá 1 ms — JS cắt tới ms).

Tính lại cước theo cân thật khi kho LADA nhập kho (chốt cước chính thức, plan v2 §3.3) — bọc + sau một mặt cắt nhỏ để tầng service test được bằng stub (review GĐ B F5, 26/10/2026: nhánh tính lại là nhánh duy nhất làm cước chính thức khác tạm tính, sống ở production mà không có test nào chạy qua).

Cân thể tích (gram) của một kiện × số lượng — cùng luật với cân khai = 0. Kho cân cả đơn một số nên cân tính cước = max(cân bàn, Σ cân thể tích) (review GĐ B F1).

Cước (gồm VAT, phí thu hộ, phụ phí) theo cân tính cước mới, cùng pipeline tạo đơn (OrderService.GetOrderFin); null = engine báo lỗi.

Service chính cho hệ thống thông báo. Xử lý gửi, nhận, quản lý thông báo.

Gửi thông báo bằng SystemName (dynamic category). Tự động dùng template từ NotificationCategory.

SystemName của NotificationCategory User ID nhận thông báo Data để replace template placeholders (VD: OrderCode, OrderId...) Override tiêu đề (null = dùng template) Override nội dung (null = dùng template)

Gửi thông báo cho nhiều users cùng lúc

Gửi thông báo theo role

Gửi broadcast cho tất cả users

Gửi thông báo từ Admin (manual send)

Lấy danh sách thông báo của user (phân trang)

Đếm số thông báo chưa đọc

Đánh dấu 1 thông báo đã đọc

Đánh dấu tất cả thông báo đã đọc

Xóa (archive) 1 thông báo

Lấy danh sách cấu hình thông báo của user

Cập nhật cấu hình thông báo

Đăng ký device token cho push notification

Xóa device token

Seed data mặc định cho NotificationCategory. Chạy khi ứng dụng khởi động để đảm bảo các category cơ bản tồn tại.

Implementation chính cho NotificationService. Xử lý logic gửi thông báo + push qua SignalR + lưu DB.

Replace {{placeholder}} trong template bằng giá trị thực.

Uỷ quyền cho — cùng luật với kênh app khách, và có lưới dọn placeholder mà nơi gọi quên truyền dữ liệu (bản cũ để lọt nguyên văn ra giao diện).

Interface quản lý lý do thất bại lấy/giao hàng

Tìm kiếm lý do thất bại

Tạo hoặc cập nhật lý do thất bại

Lấy thông tin lý do thất bại theo ID

Xóa lý do thất bại (soft delete)

Lấy danh sách lý do thất bại theo loại (cho Driver App) Chỉ trả về Active = true

Service quản lý lý do thất bại lấy/giao hàng

Tìm kiếm lý do thất bại

Tạo hoặc cập nhật lý do thất bại

Lấy thông tin lý do thất bại theo ID

Xóa lý do thất bại (soft delete)

Lấy danh sách lý do thất bại theo loại (cho Driver App)

Interface cho template xuất Excel đơn hàng

Loại DTO export

Tên template

Mô tả template

Tên worksheet mặc định

Chuyển đổi danh sách Order thành danh sách DTO export

Danh sách đơn hàng Danh sách DTO export

Thiết lập header cho Excel

Worksheet

Điền dữ liệu vào Excel

Worksheet Danh sách DTO export Task

Định dạng Excel worksheet

Worksheet Số dòng dữ liệu

Validate dữ liệu trước khi xuất

Danh sách đơn hàng Kết quả validation

Lấy tên file mặc định

Prefix tên file Tên file

Abstract base class cho Order Export Template

Loại DTO export

Validation mặc định - có thể override

Danh sách đơn hàng Kết quả validation

Tạo tên file mặc định

Prefix tên file Tên file

Thiết lập style chung cho header

Range header

Thiết lập style chung cho dữ liệu

Range dữ liệu

Định dạng cột tiền tệ

Worksheet Index cột Dòng bắt đầu Dòng kết thúc

Định dạng cột số thập phân

Worksheet Index cột Dòng bắt đầu Dòng kết thúc Số chữ số thập phân

Interface cho dịch vụ xuất Excel đơn hàng (Generic)

Xuất Excel đơn hàng với template được chỉ định

Model xuất Excel Kết quả xuất file

Xuất Excel đơn hàng với filter nâng cao

Model xuất Excel với filter Kết quả xuất file

Lấy danh sách template có sẵn

Danh sách template

Kiểm tra template có tồn tại không

Loại template True nếu tồn tại

Dịch vụ xuất Excel đơn hàng (Generic)

Xuất Excel đơn hàng với template được chỉ định

Model xuất Excel Kết quả xuất file

Xuất Excel đơn hàng với filter nâng cao

Model xuất Excel với filter Kết quả xuất file

Lấy danh sách template có sẵn

Danh sách template

Kiểm tra template có tồn tại không

Loại template True nếu tồn tại

Query đơn hàng theo model cơ bản

Model xuất Excel Danh sách đơn hàng

Query đơn hàng với filter nâng cao

Model xuất Excel với filter Danh sách đơn hàng

Xuất Excel với template được chỉ định

Loại template Danh sách đơn hàng Đường dẫn file Kết quả xuất Kết quả xuất đã cập nhật

Tạo file Excel với template

Loại DTO export Template xuất Danh sách items Đường dẫn file

Tạo tên file

Model xuất Excel Tên file

Lấy đường dẫn thư mục

Đường dẫn tùy chọn Đường dẫn thư mục

Lấy template theo loại

Loại template Template

Thông tin về template xuất Excel

Template xuất Excel cơ bản cho đơn hàng

Template xuất Excel cho mục đích tài chính (TransferPaymentBill)

Giao diện cho dịch vụ quản lý địa chỉ đơn hàng.

Lấy thông tin địa chỉ đơn hàng theo ID.

ID của địa chỉ đơn hàng. Thông tin địa chỉ đơn hàng.

Cập nhật thông tin địa chỉ đơn hàng.

Thông tin địa chỉ đơn hàng. Kết quả của thao tác.

Cập nhật riêng định vị (Lat/Long) của một địa chỉ đơn hàng.

Toạ độ mới (để null cả hai để xoá định vị). Kết quả của thao tác.

Bóc toạ độ từ một link Google Maps (kể cả link rút gọn maps.app.goo.gl).

Link người dùng dán vào. Toạ độ bóc được hoặc thông báo lỗi.

Triển khai dịch vụ quản lý địa chỉ đơn hàng.

Nơi DUY NHẤT giữ luật "ai được sửa đơn này". Đừng kiểm quyền tại chỗ.

Khởi tạo một thể hiện của .

Đối tượng IRepository của OrderAddress. Đối tượng ILocationService. Đối tượng IOrderTrackService. Đối tượng IOrderFinService.

Lấy thông tin địa chỉ đơn hàng theo ID.

ID của địa chỉ đơn hàng. Thông tin địa chỉ đơn hàng.

Cập nhật thông tin địa chỉ đơn hàng.

Thông tin địa chỉ đơn hàng. Kết quả của thao tác.

Cập nhật riêng định vị (Lat/Long). Không đụng tới tỉnh/phường nên KHÔNG tính lại cước và KHÔNG đổi bưu cục dự kiến — khác hẳn .

Toạ độ mới (null cả hai = xoá định vị). Kết quả của thao tác.

Bóc toạ độ từ link Google Maps. Link đầy đủ đã được frontend tự parse, phần server lo là link RÚT GỌN (maps.app.goo.gl): browser không đọc được Location header của redirect nên phải nhờ server đi theo redirect rồi parse URL cuối.

Link người dùng dán vào. Toạ độ bóc được hoặc thông báo lỗi.

Đọc tối đa byte đầu của body dưới dạng chuỗi.

Loại hành trình tương ứng với loại địa chỉ.

Câu mô tả hành trình cho thao tác cập nhật định vị.

Nhóm đơn trên màn "Đơn hàng bưu cục" — đơn nào được coi là "của bưu cục mình".

Giá trị đi qua API dạng số (khoá Scope trong Search.PredicateObject) — đừng đánh số lại. Năm nhóm theo sơ đồ vai "Chủ bưu cục (nhà đầu tư)": lấy hàng (dự kiến / đã lấy), giao hàng (dự kiến / đã nhận từ kho tổng), đơn do nhân sự bưu cục tạo.

Đơn lấy hàng — bưu cục mình dự kiến lấy (OrderOps.ExpectAgencyPickupId, suy từ phường lấy hàng).

Đơn lấy hàng — bưu cục mình đã lấy (OrderOps.AgencyPickedupId, SP lấy hàng ghi theo chi nhánh người bấm).

Đơn giao hàng — bưu cục mình dự kiến giao (OrderOps.ExpectAgencyDeliveryId, suy từ phường giao hàng).

Đơn giao hàng — bưu cục mình đã nhận từ kho tổng: có lượt nhập kho () tại bưu cục mình, kể cả khi bưu cục dự kiến giao là nơi khác.

Đơn sale hàng — do nhân sự bưu cục mình tạo.

Luật lọc đơn theo — một chỗ duy nhất, test được bằng LINQ trên bộ nhớ.

Lọc theo nhóm của bưu cục .

≤ 0 trả rỗng, không bao giờ lọc "bằng 0": AgencyPickedupId = 0 là mọi đơn chưa lấy, CreatedAgencyId = 0 là mọi đơn từ app khách — người chưa gắn bưu cục sẽ thấy cả hệ thống. Nhận từ kho tổng quy lượt nhập kho về bưu cục đúng như AnalyticsHubEventFactBuilder: lấy OrderTrack.AgencyId nếu có, không thì lấy chi nhánh hiện tại của người bấm (CreatedBy) — WarehouseService.Inbound không ghi AgencyId vào dòng lịch sử (đo dev 20/10/2026: 39.294 / 59.995 lượt nhập kho có AgencyId). Bưu cục nhượng quyền chỉ nhập kho ở chiều giao, nên Ví bưu cục cũng gọi sự kiện này là "Nhận hàng từ kho tổng" (WalletEventType.InboundAtBranch). Nhân sự tạo tin Order.CreatedAgencyId trước (Ví bưu cục đóng dấu, giữ đúng bưu cục lúc tạo dù nhân sự chuyển chỗ sau này); dấu đó chỉ có khi job Ví đã chạy qua đơn, nên còn trống thì tra chi nhánh hiện tại của người tạo. Tập đơn gốc. Nhóm cần lọc. Bưu cục của người xem. Bảng người dùng — để biết ai là nhân sự của bưu cục. Lịch sử đơn — để tìm lượt nhập kho.

Đọc khoá Scope từ PredicateObject; thiếu hoặc lạ thì về (tab đầu tiên của màn).

Cờ hiển thị của màn "Đơn hàng bưu cục".

Có role xem đơn bưu cục (hoặc Founder) và tài khoản đã gắn một bưu cục. Có role xem đơn bưu cục (hoặc Founder) — tách riêng để màn nói đúng lý do khi chưa gắn bưu cục.

Cờ hiển thị của màn "Đơn hàng bưu cục".

Có role xem đơn bưu cục (hoặc Founder) và tài khoản đã gắn một bưu cục. Có role xem đơn bưu cục (hoặc Founder) — tách riêng để màn nói đúng lý do khi chưa gắn bưu cục.

Có role xem đơn bưu cục (hoặc Founder) và tài khoản đã gắn một bưu cục.

Có role xem đơn bưu cục (hoặc Founder) — tách riêng để màn nói đúng lý do khi chưa gắn bưu cục.

Luật "ai xem được màn Đơn hàng bưu cục" — hàm thuần nhận danh sách role đã phân giải (rule quyen-hien-thi).

Role gác POST api/Order/SearchByAgency.

Vai bỏ qua mọi kiểm tra role của hệ thống.

Tính cờ từ role và bưu cục của người xem.

Role đã phân giải qua IUserRoleResolver; null = không có role nào. Bưu cục của người xem (User.AgencyId), 0 = chưa gắn.

Interface để định nghĩa các phương thức xử lý tài chính đơn hàng.

Cập nhật tài chính đơn hàng không đồng bộ.

ID của đơn hàng. ID của người cập nhật. Tên người cập nhật. Kết quả của hoạt động cập nhật.

Lấy thông tin tài chính đơn hàng dựa trên ID.

ID của tài chính đơn hàng. Thông tin tài chính đơn hàng.

Cập nhật thông tin tài chính đơn hàng.

Model chứa thông tin tài chính đơn hàng. Kết quả của hoạt động cập nhật.

Thu tiền

Lớp triển khai các phương thức xử lý tài chính đơn hàng.

⚠️ Lớp này đang được bóc tách dần sang Lada.Framework. Nợ N18 từng sống được nhiều tháng vì luật tiền ở đây không có ca test nào canh. Phần đã bóc: ba luật quyết định tiền (áp giá cố định, phí thu hộ, phân bổ theo loại trả cước) nay ở và được canh bởi OrderFinCalculationServiceTests. Phần còn ở đây: truy vấn database, gọi engine tính cước, ghi hành trình — còn cần IRepository và DTO của project API. Đừng thêm luật tiền mới vào file này; thêm vào service ở Framework rồi gọi sang, để nó có test. Đính chính 2026-08-07. Ghi chú cũ nói "Ladaer.BackEnd.Tests chỉ tham chiếu Lada.Framework ⇒ không test được lớp này" là SAI: csproj test tham chiếu cả hai project, nên dựng thẳng với repository giả được. Update nay đã có OrderFinUpdateRecalculateFeeTests canh hành trình "sửa loại hàng thì tính lại cước" (7 ca, đã qua 3 mật thử lật cờ). Các method còn lại vẫn chưa có test — không phải vì không viết được, mà vì chưa viết.

Nơi DUY NHẤT giữ luật "ai được sửa đơn này". Đừng tự kiểm quyền tại chỗ: luật cũ từng được dán tay ở 6 service và cả 6 đều so sai property nên người quản lý khách hàng chưa từng sửa được đơn.

Khởi tạo một instance mới của lớp .

Tùy chọn cấu hình ứng dụng. Kho lưu trữ đơn hàng. Dịch vụ tính phí. Kho lưu trữ tài chính đơn hàng. Kho lưu trữ kiện hàng. Dịch vụ theo dõi đơn hàng. Dịch vụ người dùng. Dịch vụ snapshot thuộc tính loại hàng của đơn. Dịch vụ áp giá theo loại hàng (resolve giá từ DB). Lớp quyết định tiền đã bóc sang Lada.Framework — nơi duy nhất giữ ba luật: áp giá cố định, phí thu hộ, phân bổ theo loại trả cước. Có test canh nên đừng viết lại luật ở đây. Nơi duy nhất giữ luật "ai được sửa đơn này" (người quản lý khách hàng, sale phụ trách, Founder).

Lấy thông tin tài chính đơn hàng dựa trên ID.

ID của tài chính đơn hàng. Thông tin tài chính đơn hàng.

Cập nhật thông tin tài chính đơn hàng.

Model chứa thông tin tài chính đơn hàng. Kết quả của hoạt động cập nhật.

Cập nhật tài chính đơn hàng không đồng bộ.

ID của đơn hàng. ID của người cập nhật. Tên người cập nhật. Kết quả của hoạt động cập nhật.

Tra cước tuyến hiện tại cho một đơn ĐÃ LƯU: nạp địa chỉ + kiện hàng từ database, tính trọng lượng tính cước, rồi hỏi engine.

Id đơn hàng (cũng là Id của OrderFin). Danh mục hàng hoá dùng để tra cước. Truyền tường minh vì có thể ĐANG đổi danh mục — đọc Order.GoodsCategoryId lúc này sẽ ra giá trị cũ. Cước tuyến, hoặc null khi không tra được (đơn thiếu địa chỉ / thiếu kiện / tuyến chưa có bảng giá). Trả null chứ không trả 0: 0 là một mức cước hợp lệ, còn "không tra được" là chuyện khác — nhập nhèm hai cái này sẽ zero hoá cước của đơn có thật. Tách riêng khỏi vì hàm đó còn ghi database, ghi hành trình và cập nhật SubTotalWeight — chỉ cần con số cước. Dùng chung luật trọng lượng ở để hai đường không lệch nhau.

Dựng lại danh sách lựa chọn thuộc tính loại hàng của một đơn ĐÃ LƯU, từ snapshot OrderGoodsAttributes, để truyền xuống engine tính cước.

Vì sao cần: tính lại cước cho đơn đã tồn tại nên không có payload client. Engine cần OptionId của thuộc tính TRỤC GIÁ để tra ô bảng giá đặc thù; không truyền thì engine rơi về trục trọng lượng và cước tụt xuống giá cân. Chỉ chuyển lại LỰA CHỌN (AttributeId / OptionId / ValueText / ValueNumber), KHÔNG chuyển Price đã snapshot: giá luôn resolve lại từ DB, đúng nguyên tắc "không tin giá client gửi". Hệ quả phải biết: cước tính lại dùng giá HIỆN TẠI của cấu hình, không phải giá lúc lên đơn — đó là đúng ý của chức năng "tính lại cước". MultiSelect lưu mỗi lựa chọn một dòng snapshot, nên gom theo AttributeId và dồn vào OptionIds; nếu chỉ có một dòng thì điền cả OptionId để SingleSelect (kiểu của trục giá) đọc được.

Cước tuyến của đơn khai loại hàng THEO KIỆN — tra giá từng loại rồi cộng.

Đơn đã nạp sẵn Packages. Phường gửi. Phường nhận. null khi không kiện nào khai loại hàng — nơi gọi giữ nguyên đường tính cũ. Ngược lại trả kết quả có Fee là tổng cước, hoặc Result != Success kèm thông báo nêu tên món hỏng. Gộp kiện cùng loại + cùng thuộc tính trước khi tra (): bảng giá theo cân là bậc thang, tra riêng từng kiện rồi cộng sẽ ra số khác với tra trên tổng trọng lượng. ⚠️ Khác engine lúc tạo đơn ở một điểm đã có từ trước: hàm này KHÔNG áp QĐ-1 (điền loại mặc định cho dòng không khai) vì nó gọi thẳng IFeeService. Dòng không khai loại vẫn tra bảng giá chung theo cân, đúng như hành vi cũ của chính hàm này với order.GoodsCategoryId rỗng.

Dựng lựa chọn thuộc tính của TỪNG KIỆN từ snapshot, cho đơn khai loại hàng theo kiện.

Từ điển theo OrderPackageId. Rỗng khi đơn không có snapshot gắn kiện nào. Chỉ lấy dòng có OrderPackageId: dòng để trống là thuộc tính CẤP ĐƠN của đơn cũ, gán bừa vào một kiện sẽ làm kiện đó mọc thêm phụ phí không phải của nó.

Gom snapshot thành lựa chọn thuộc tính — phần dùng chung của hai hàm dựng ở trên.

Thu tiền

Model chứa thông tin thu tiền của đơn hàng. Kết quả của hoạt động cập nhật.

Ghi / đọc snapshot thuộc tính loại hàng của đơn (bảng OrderGoodsAttributes). Giá LUÔN resolve từ DB qua IGoodsCategoryPricingService, không tin giá client gửi.

Ghi snapshot thuộc tính cho một đơn. Khi sửa đơn: xóa CỨNG các dòng cũ rồi ghi lại theo payload mới (snapshot lấy giá hiện tại). Đơn không chọn danh mục / không có thuộc tính: không ghi gì, trả về phí = 0.

Id đơn hàng Danh mục hàng hóa, null = không phân loại Lựa chọn của client Id người thực hiện Tên người thực hiện True khi sửa đơn — xóa cứng dòng cũ trước khi ghi lại Kết quả áp giá của danh mục (phí thuộc tính, có phải giá cố định hay không)

Ghi snapshot thuộc tính cho TỪNG KIỆN của một đơn nhiều loại hàng.

Dùng cho đơn khai loại hàng theo kiện (1 xe máy + 1 kiện hàng): mỗi kiện có loại riêng nên có bộ thuộc tính riêng, snapshot phải gắn OrderPackageId để chi tiết đơn hiện đúng thuộc tính của từng món. Cố ý KHÔNG gộp vào bằng tham số thêm: hàm kia trả về của một danh mục và nơi gọi đang dùng kết quả đó để lấy phí thuộc tính; đơn nhiều loại thì phí ấy đến từ engine cước, không phải từ một lời gọi resolve đơn lẻ. Trộn hai việc vào một hàm là mời gọi lấy nhầm số. ⚠️ Xoá cứng dòng cũ theo đơn (không theo kiện) khi bật: sửa đơn có thể xoá hẳn một kiện, xoá theo kiện sẽ để lại thuộc tính mồ côi. Id đơn hàng Danh sách kiện kèm loại hàng và lựa chọn thuộc tính của từng kiện Id người thực hiện Tên người thực hiện True khi sửa đơn — xóa cứng dòng cũ của cả đơn trước khi ghi lại

Lấy snapshot thuộc tính của đơn để hiển thị chi tiết đơn

Lấy snapshot thuộc tính của nhiều đơn (gom theo OrderId) — dùng cho danh sách đơn

Lựa chọn thuộc tính của từng kiện, dạng client gửi lên ().

Id đơn hàng Từ điển OrderPackageId → lựa chọn; bỏ qua snapshot cấp đơn (không có kiện). Đây là chiều NGƯỢC của : dựng lại lựa chọn để màn sửa kiện mở ra đúng những gì đã chọn, và để đường tính lại cước biết từng kiện chọn gì.

Một kiện hàng cần ghi snapshot thuộc tính: kiện nào, loại hàng gì, khách chọn những gì.

Id kiện hàng đã lưu — phải > 0, kiện chưa có Id thì không ghi được snapshot.

Loại hàng của kiện, null = không khai.

Lựa chọn thuộc tính của kiện.

Triển khai ghi / đọc snapshot thuộc tính loại hàng của đơn

Ghi snapshot thuộc tính cho một đơn

Ghi snapshot thuộc tính cho từng kiện của một đơn nhiều loại hàng

Lấy snapshot thuộc tính của đơn

Lấy snapshot thuộc tính của nhiều đơn

Lựa chọn thuộc tính của từng kiện (chiều ngược của SaveForPackagesAsync)

Gom snapshot của MỘT kiện thành lựa chọn: mỗi thuộc tính một dòng, chọn nhiều thì gom OptionIds

Map entity snapshot sang item hiển thị

Giao diện cho dịch vụ quản lý kiện hàng trong đơn hàng.

Lấy thông tin kiện hàng theo ID đơn hàng.

ID của đơn hàng. Thông tin kiện hàng.

Lấy thông tin kiện hàng theo ID đơn hàng với thông tin đơn vị đo.

ID của đơn hàng. Thông tin kiện hàng với đơn vị đo.

Cập nhật thông tin kiện hàng.

Model chứa thông tin kiện hàng. Kết quả của thao tác.

Triển khai dịch vụ quản lý kiện hàng trong đơn hàng.

Snapshot thuộc tính loại hàng theo kiện — nguồn để màn sửa mở đúng lựa chọn cũ và ghi lại lựa chọn mới. Giá luôn resolve từ DB trong service này, không tin số client gửi.

Lớp quyết định tiền ở Lada.Framework — dùng cho luật trọng lượng tính cước (có test canh). Đừng viết lại công thức trọng lượng tại chỗ: đó là cách hai đường tạo đơn / sửa kiện lệch số.

Nơi DUY NHẤT giữ luật "ai được sửa đơn này". Đừng kiểm quyền tại chỗ.

Khởi tạo một thể hiện của .

Đối tượng IRepository của Order. Đối tượng IRepository của OrderPackage. Đối tượng IOrderTrackService. Đối tượng IOrderFinService. Lớp quyết định tiền ở Lada.Framework.

Lấy thông tin kiện hàng theo ID đơn hàng.

ID của đơn hàng. Thông tin kiện hàng.

Đổ loại hàng + thuộc tính CẤP ĐƠN xuống từng kiện, cho đơn khai theo đường cũ.

Id đơn hàng Kiện của đơn, sẽ được điền tại chỗ Đơn tạo trước khi loại hàng chuyển xuống cấp kiện có snapshot KHÔNG mang OrderPackageId, nên tra theo kiện ra rỗng. Không đổ xuống thì màn sửa mở ra trống trơn, và người dùng bấm Lưu là XOÁ SẠCH thuộc tính của đơn (đường ghi xoá theo đơn rồi ghi lại theo kiện) — cước tính lại ngay sau đó mất phụ phí thuộc tính hoặc tụt khỏi bảng giá riêng. Điền cho MỌI kiện chứ không riêng kiện đầu: engine gộp các kiện cùng loại + cùng thuộc tính (GoodsLineGrouper.Merge) nên chúng lại thành đúng một dòng cước như đường cũ. Điền cho một kiện thôi sẽ tách đơn thành hai dòng khác nhau ⇒ ĐỔI TIỀN.

Lấy thông tin kiện hàng theo ID đơn hàng với thông tin đơn vị đo.

ID của đơn hàng. Thông tin kiện hàng với đơn vị đo.

Cập nhật thông tin kiện hàng.

Model chứa thông tin kiện hàng. Kết quả của thao tác.

Nơi DUY NHẤT trả lời câu hỏi "người này có được sửa đơn hàng này không".

Vì sao tồn tại. Luật này trước đây được dán tay ở 6 chỗ — OrderFinService.Update, OrderAddressService (2 chỗ), OrderPackageService, OrderService.Cancel và OrderService.RemoveCancel — mỗi chỗ một bản manager.Id != userId && order.SaleId != userId giống hệt nhau. Sáu bản sao của một luật quyền hạn nghĩa là: đổi luật thì phải nhớ đủ 6 nơi, sót một nơi là lỗ phân quyền hoặc chặn oan người có quyền. Đây đúng loại lặp vừa gây ra lệch số ở luật trọng lượng tính cước. 🐞 Và việc lặp đã che một bug thật suốt thời gian dài: cả 6 bản sao đều so sai property nên điều kiện "là người quản lý khách hàng" chưa từng đúng một lần nào — xem . Một chỗ sai thì dễ thấy; sáu chỗ sai giống nhau thì trông như đúng. ⚠️ Chưa có test tự động, và đây là lý do — không phải sự bỏ sót. Service này cần + , cả hai đều nằm ở project Ladaer.BackEnd mà Ladaer.BackEnd.Tests chỉ tham chiếu Lada.Framework. Phần luật ở đây không bóc thuần được như đã làm với OrderFinCalculationService: nó chính là việc đi lấy dữ liệu rồi hợp lại, chứ không có phép tính nào để tách. Bóc một phép OR ba biến sang Framework chỉ để "có test" là tự lừa mình. ⇒ Sửa luật ở đây thì phải bấm thật để xác minh.

Người dùng có quyền sửa đơn hàng này hay không.

Đơn hàng cần sửa — chỉ đọc CustomerId và SaleId. Id người đang thao tác.

Người dùng có quyền sửa đơn của khách hàng này hay không — dùng khi trong tay chỉ có CustomerId / SaleId chứ không có cả entity .

Khách hàng của đơn. Sale phụ trách đơn, null nếu đơn không gán sale. Id người đang thao tác.

Khởi tạo một thể hiện của .

Dùng để tìm người quản lý khách hàng của đơn. Nguồn duy nhất để biết vai trò người dùng (đọc DB, có cache). Role không nằm trong JWT nên User.IsInRole(...) luôn trả false — đừng dùng. Thứ tự kiểm tra là cố ý: hai điều kiện rẻ (so sánh id) chạy trước, chỉ khi cả hai trượt mới hỏi vai trò — vì có thể phải đọc database. Đừng đảo lại thành hỏi vai trò trước cho "dễ đọc". 🐞 Đây là chỗ sửa một BUG PHÂN QUYỀN có thật, phát hiện 2026-08-05. Cả 6 bản sao cũ đều so manager.Id != userId, nhưng chưa bao giờ gán result.Id — nó chỉ gán ManagerId / ManagerUserName / ManagerFullName. Nên manager.Id luôn bằng 0 và điều kiện "là người quản lý" chưa từng đúng một lần nào: thực tế chỉ sale phụ trách sửa được đơn. Đo trên DB: 3.054 / 27.853 đơn có người quản lý khác sale ⇒ đúng số đơn mà người quản lý bị chặn oan. Ở đây so manager.ManagerId — đúng ý định mà tên biến và câu thông báo lỗi ("không do mình tạo / quản lý") vẫn luôn nói tới.

Giao diện cho dịch vụ quản lý đơn hàng.

Tạo mới đơn hàng.

Thông tin đơn hàng. API key. Kết quả của thao tác.

Tìm kiếm đơn hàng.

Thông số tìm kiếm. Kết quả tìm kiếm đơn hàng.

Tìm đơn của bưu cục người đang đăng nhập theo nhóm (khoá Scope, xem ) — màn "Đơn hàng bưu cục". Bưu cục luôn lấy từ tài khoản, không nhận từ tham số.

Thông số tìm kiếm — cùng bộ lọc với , thêm khoá Scope. Người đang đăng nhập.

Cờ hiển thị + bưu cục + option bộ lọc cho màn "Đơn hàng bưu cục".

Người đang đăng nhập.

Lấy chi tiết đơn hàng theo mã đơn hàng.

Mã đơn hàng. Thông tin chi tiết đơn hàng.

Lấy chi tiết đơn hàng theo mã đơn hàng với thông tin đơn vị đo.

Mã đơn hàng. Thông tin chi tiết đơn hàng với đơn vị đo.

Cập nhật trạng thái đơn hàng khi lấy hàng.

Thông tin cập nhật trạng thái. Kết quả của thao tác.

Hủy đơn hàng.

Thông tin cập nhật trạng thái. Kết quả của thao tác.

Gỡ bỏ trạng thái hủy của đơn hàng.

Thông tin cập nhật trạng thái. Kết quả của thao tác.

Xuất Excel danh sách đơn hàng.

Model xuất Excel. Kết quả xuất file.

Lấy đơn hàng theo ID.

ID của đơn hàng. Thông tin đơn hàng.

Lấy thông tin chi tiết đơn hàng.

ID của đơn hàng. Thông tin chi tiết đơn hàng.

Lấy thông tin chi tiết đơn hàng theo mã đơn hàng.

Mã đơn hàng. Thông tin chi tiết đơn hàng.

Chuẩn bị dữ liệu bộ lọc danh sách đơn hàng

Filter đầu vào để lấy thêm dữ liệu liên quan Các danh sách option

Triển khai dịch vụ quản lý đơn hàng.

Lớp quyết định tiền ở Lada.Framework — dùng cho luật trọng lượng tính cước (có test canh, đã vá bug tràn số int32). Đừng viết lại công thức trọng lượng tại chỗ.

Nơi DUY NHẤT giữ luật "ai được sửa đơn này". Đừng kiểm quyền tại chỗ.

Cấu hình giá loại hàng — ở đây chỉ dùng để lấy trọng lượng quy ước theo lựa chọn thuộc tính.

Người dùng — để biết ai là nhân sự của một bưu cục (màn "Đơn hàng bưu cục").

Chi nhánh / bưu cục — lấy tên bưu cục cho màn "Đơn hàng bưu cục".

Khởi tạo một thể hiện của .

Đối tượng IDbConnection. Đối tượng IFeeService. Đối tượng IRepository của Order. Đối tượng IRepository của OrderTrack. Đối tượng IRepository của Media. Đối tượng ILocationService. Đối tượng IUserService. Đối tượng IOrderTrackService. Đối tượng IUnifiedMediaService. Đối tượng IVatInfoService. Engine báo giá theo dòng phí — thay thế OrderFeeCalculationHelper cũ (Việc 3). Dịch vụ ghi snapshot thuộc tính loại hàng của đơn. Cấu hình giá loại hàng — nguồn trọng lượng quy ước. Người dùng — nhân sự của bưu cục. Chi nhánh / bưu cục.

Lấy đơn hàng theo ID.

ID của đơn hàng. Thông tin đơn hàng.

Tạo mới đơn hàng.

Thông tin đơn hàng. API key. Kết quả của thao tác.

Tạo mới đơn hàng.

Thông tin đơn hàng. Số lần thử lại. Kết quả của thao tác.

Tìm kiếm đơn hàng.

Thông số tìm kiếm. Kết quả tìm kiếm đơn hàng.

Phần chung của và : áp bộ lọc của PredicateObject lên tập đơn đã giới hạn phạm vi, rồi phân trang. Phạm vi (ai được thấy đơn nào) là việc của nơi gọi.

Lấy chi tiết đơn hàng theo mã đơn hàng.

Mã đơn hàng. Thông tin chi tiết đơn hàng.

Lấy chi tiết đơn hàng theo mã đơn hàng với thông tin đơn vị đo.

Mã đơn hàng. Thông tin chi tiết đơn hàng với đơn vị đo.

Cập nhật trạng thái đơn hàng khi lấy hàng.

Thông tin cập nhật trạng thái. Kết quả của thao tác.

Hủy đơn hàng.

Thông tin cập nhật trạng thái. Kết quả của thao tác.

Gỡ bỏ trạng thái hủy của đơn hàng.

Thông tin cập nhật trạng thái. Kết quả của thao tác.

Cập nhật trạng thái đơn hàng.

Thông tin cập nhật trạng thái. Kết quả của thao tác.

Kiểm tra tính hợp lệ của việc cập nhật trạng thái đơn hàng.

Trạng thái hiện tại của đơn hàng. Trạng thái vật lý hiện tại của đơn hàng. Trạng thái mới của đơn hàng. Trạng thái vật lý mới của đơn hàng. True nếu việc cập nhật trạng thái hợp lệ, ngược lại false.

Tạo mã đơn hàng ngẫu nhiên.

Giá trị ngẫu nhiên. Mã đơn hàng.

Trọng lượng quy ước (kg) của một kiện, lấy từ lựa chọn thuộc tính đã khai.

Kiện hàng client gửi — nguồn loại hàng và lựa chọn thuộc tính. Cân quy ước, hoặc 0 khi không được phép can thiệp / lựa chọn chưa khai cân. Cân nằm ở GoodsAttributeOption.Weight vì mỗi lựa chọn một số riêng (xe số ≠ xe phân khối lớn), không phải một số chung cho cả danh mục. Ranh giới an toàn, đừng nới: CHỈ áp cho danh mục áp giá cố định hoặc bảng giá riêng theo tuyến. Hai mode còn lại (Surcharge, None) VẪN tra bảng giá theo bậc trọng lượng, ghi đè cân khách khai ở đó là ĐỔI TIỀN của đơn.

Ghép kiện hàng đã lưu với loại hàng / thuộc tính client gửi, để ghi snapshot theo kiện.

Đơn client gửi lên — nguồn của loại hàng và lựa chọn thuộc tính. Đơn đã lưu — nguồn của OrderPackage.Id. Danh sách kiện kèm loại hàng, hoặc null khi không ghép được. Ghép theo thứ tự: order.Packages dựng từ model.Packages qua ToEntity() nên hai danh sách cùng số lượng và cùng thứ tự. Trả null khi số lượng lệch thay vì ghép bừa — ghép lệch một nhịp là gán thuộc tính xe máy cho kiện quần áo, sai âm thầm và chỉ lộ ra khi khách nhìn hoá đơn.

Tính toán thông tin tài chính của đơn hàng.

Thông tin đơn hàng. Tổng trọng lượng. API key. Dòng hàng theo loại (đã gộp) khi đơn khai loại hàng theo kiện. null = đơn một loại hàng, engine dùng + loại hàng cấp đơn đúng như trước. Thông tin tài chính của đơn hàng.

Lấy thông tin chi tiết đơn hàng.

ID của đơn hàng. Thông tin chi tiết đơn hàng.

Lấy thông tin chi tiết đơn hàng theo mã đơn hàng.

Mã đơn hàng. Thông tin chi tiết đơn hàng.

Lấy danh sách media theo Order ID

ID của đơn hàng Danh sách media items

Lấy danh sách media theo Order ID - tối ưu hóa để tránh timeout

ID của đơn hàng Danh sách media items

Nạp toạ độ tâm đơn vị hành chính cho một loạt địa chỉ đơn hàng. Dùng chung cho trang tra cứu (OrderDetailByCode / ...WithUnits) để hai hàm đó không lệch nhau về cách xác định "đã định vị hay chưa".

Comparer để so sánh Media entities

Phục vụ cho cả 2 method Search để thêm thông tin địa chỉ và tên người bán

Danh sách OrderItem cần thêm thông tin. Task.

Chuẩn bị dữ liệu bộ lọc danh sách đơn hàng

Xuất Excel danh sách đơn hàng.

Model xuất Excel. Kết quả xuất file.

Tạo ExcelPackage danh sách đơn hàng

Thiết lập header cho danh sách đơn hàng

Điền dữ liệu danh sách đơn hàng

Định dạng worksheet danh sách đơn hàng

Giao diện cho dịch vụ quản lý hành trình đơn hàng.

Tạo mới hành trình đơn hàng.

Thông tin hành trình đơn hàng. Kết quả của thao tác.

Tạo mới danh sách hành trình đơn hàng.

Danh sách thông tin hành trình đơn hàng. Kết quả của thao tác.

Triển khai dịch vụ quản lý hành trình đơn hàng.

Khởi tạo một thể hiện của .

Đối tượng IRepository của OrderTrack.

Tạo mới hành trình đơn hàng.

Thông tin hành trình đơn hàng. Kết quả của thao tác.

Tạo mới danh sách hành trình đơn hàng.

Danh sách thông tin hành trình đơn hàng. Kết quả của thao tác.

Kết quả auto-apply

Tìm chương trình auto-apply tốt nhất cho đơn hàng

Background service chạy các job định kỳ cho module khuyến mãi: - Kiểm tra hết hạn chương trình (mỗi ngày) - Cảnh báo ngân sách (mỗi ngày) - Tính hoàn thưởng cuối kỳ (ngày 1 hàng tháng)

Kết quả validate mã khuyến mãi

Kiểm tra và tính toán giảm giá cho mã khuyến mãi

Ghi nhận sử dụng khuyến mãi khi đơn được tạo thành công

Hoàn lại lượt sử dụng khi đơn bị hủy

Lấy log sử dụng theo chương trình

Company header with logo + title (rows 1-3)

Recursively write a row and its children

Interface cho service báo cáo tài chính

Lấy báo cáo kiểm soát chi phí theo khoảng thời gian

Ngày bắt đầu Ngày kết thúc Kết quả báo cáo dạng cây

Backfill PaymentsDate từ ExpenseHistory cho các expense đã Paid nhưng chưa có PaymentsDate

Số lượng bản ghi đã cập nhật

Lấy báo cáo dòng tiền tổng hợp (Cash Flow Dashboard)

Lấy báo cáo nợ ngắn hạn (thẻ dầu + vay xe)

Lấy báo cáo công nợ phải thu khách hàng (cước CK kế toán chưa thanh toán)

Drill-down: danh sách đơn hàng thu cước (theo HeadTime) trong khoảng thời gian

Drill-down: danh sách đơn hàng thu COD từ shipper trong khoảng thời gian

Service báo cáo tài chính

Báo cáo Công nợ phải thu khách hàng Lấy các đơn hàng có PayFeeType = BankTransfer(3) mà TransferFeeStage chưa thanh toán

Row trả về từ sp_GetCashFlowFeeInflow

Row trả về từ sp_GetCashFlowCodInflow

Interface cho service báo cáo thu chi

Lấy báo cáo thu chi theo khoảng thời gian

Thông tin khoảng thời gian ID người dùng Báo cáo thu chi

Service báo cáo thu chi

Khởi tạo một thể hiện của .

Kết nối cơ sở dữ liệu.

Lấy báo cáo thu chi theo khoảng thời gian

Tạo danh sách các cột ngày

Xây dựng ma trận dữ liệu báo cáo

Xây dựng các dòng THU

Xây dựng các dòng CHI

Xây dựng dòng cho một danh mục đơn

Xây dựng cây chi phí vận hành

Tạo dòng tổng

Tạo dòng tổng rỗng

Tạo dòng chênh lệch (Thu - Chi)

Tính tổng thu, tổng chi, chênh lệch

Interface cho dịch vụ xuất Excel báo cáo đổ dầu

Xuất Excel báo cáo đổ dầu theo lái xe (nhóm theo ngày)

Tham số tìm kiếm và sắp xếp Kết quả xuất file

Xuất Excel báo cáo đổ dầu theo ngày

Tham số tìm kiếm và sắp xếp Kết quả xuất file

Xuất Excel báo cáo đổ dầu theo xe (nhóm theo xe, chi tiết lái xe bên trong)

Tham số tìm kiếm và sắp xếp Kết quả xuất file

Dịch vụ xuất Excel báo cáo đổ dầu

Xuất Excel báo cáo đổ dầu theo lái xe (nhóm theo ngày)

Xuất Excel báo cáo đổ dầu theo ngày

Xuất Excel báo cáo đổ dầu theo xe (nhóm theo xe, chi tiết lái xe bên trong)

Lấy dữ liệu chi tiết báo cáo đổ dầu theo ngày, lái xe và xe

Lấy dữ liệu chi tiết báo cáo đổ dầu theo xe và lái xe

Tạo ExcelPackage báo cáo theo xe (nhóm theo xe, chi tiết lái xe bên trong)

Thiết lập header cho báo cáo theo xe

Điền dữ liệu nhóm theo xe (chi tiết lái xe bên trong)

Ghi dòng subtotal/tổng cho báo cáo theo xe. Bố cục cột từ startCol: Số lần đổ | Km | Lít thực tế | Tiền thực tế | Đơn giá BQ | Tiền thẻ | Tiền mặt

Parse mảng ID từ dynamic object

Tên trạng thái phiếu đổ dầu

Tạo ExcelPackage báo cáo theo lái xe (nhóm theo ngày)

Tạo ExcelPackage báo cáo theo ngày

Thiết lập header cho báo cáo theo lái xe

Thiết lập header cho báo cáo theo ngày

Điền dữ liệu nhóm theo ngày (cho báo cáo theo lái xe)

Điền dữ liệu theo ngày (cho báo cáo theo ngày - có cột Status)

Ghi dòng subtotal/tổng cho cả 2 kiểu báo cáo. Bố cục cột từ startCol: Số lần đổ | Km | Lít thực tế | Tiền thực tế | Tiền thẻ | Tiền mặt

Định dạng worksheet

DTO để map kết quả từ stored procedure theo ngày

DTO để map kết quả từ stored procedure chi tiết theo xe và lái xe

Interface cho dịch vụ báo cáo đổ dầu

Lấy báo cáo đổ dầu theo lái xe từ stored procedure

Tham số bảng thông minh Danh sách báo cáo đổ dầu theo lái xe

Lấy báo cáo đổ dầu theo ngày từ stored procedure

Tham số bảng thông minh Danh sách báo cáo đổ dầu theo ngày

Lấy báo cáo đổ dầu theo xe từ stored procedure

Tham số bảng thông minh Danh sách báo cáo đổ dầu theo xe

Dịch vụ báo cáo đổ dầu

Lấy báo cáo đổ dầu theo lái xe từ stored procedure

Tham số bảng thông minh Danh sách báo cáo đổ dầu theo lái xe

Lấy báo cáo đổ dầu theo ngày từ stored procedure

Tham số bảng thông minh Danh sách báo cáo đổ dầu theo ngày (nhóm theo ngày, chi tiết bên trong)

Lấy báo cáo đổ dầu thực tế theo xe từ stored procedure

Tham số bảng thông minh Danh sách báo cáo đổ dầu theo xe (nhóm theo xe, chi tiết lái xe bên trong)

Parse tham số tìm kiếm từ SmartTableParam

Parse mảng ID từ dynamic object (hỗ trợ cả JArray và IEnumerable)

DTO tạm để map kết quả từ stored procedure chi tiết lái xe + xe

DTO tạm để map kết quả từ stored procedure theo ngày

DTO tạm để map kết quả từ stored procedure chi tiết xe + lái xe

Báo cáo cấp bưu cục / chi nhánh.

File này từng rỗng 0 byte; hồi sinh ở GĐ C của đợt KPI để phục vụ chỉ số agency.revenue (plan §7.7). Service **không tự lọc theo quyền của người đang đăng nhập** — khác các service báo cáo có màn hình đi kèm. Lý do: người gọi đầu tiên là provider KPI, nơi chủ thể là bưu cục **được chấm điểm** chứ không phải người đang xem. Bên nào gắn màn hình vào đây sau này phải tự ép phạm vi trước khi truyền agencyIds.

Doanh số theo bưu cục bán hàng trong một khoảng ngày.

Đầu khoảng, tính cả mốc này Cuối khoảng, tính cả mốc này Giới hạn ở các bưu cục này; rỗng/null = mọi bưu cục

Interface cho dịch vụ báo cáo lái xe

Lấy báo cáo năng suất lái xe theo từng ngày

Tham số bảng thông minh ID người dùng Kết quả báo cáo năng suất lái xe theo ngày

Dịch vụ báo cáo lái xe

Khởi tạo một thể hiện của .

Kết nối cơ sở dữ liệu. Service quản lý người dùng.

Interface service thống kê tồn đọng đơn hàng

Lấy thống kê tồn đọng đơn hàng theo trạng thái và thời gian

Lấy thống kê tồn đọng đơn hàng phân nhóm theo Agency

Lấy danh sách chi tiết đơn hàng drill-down theo trạng thái + số ngày

Service thống kê tồn đọng đơn hàng sử dụng Stored Procedure và Dapper

Parse danh sách AgencyIds từ SmartTableParam.Search.PredicateObject

Parse SourceCityId và DestCityId từ SmartTableParam.Search.PredicateObject

Giao diện cho dịch vụ báo cáo tài chính đơn hàng

Lấy thống kê chuyển khoản ngân hàng theo sale

Tham số bảng thông minh ID người dùng hiện tại Trang dữ liệu thống kê chuyển khoản theo sale

Lấy dòng Tổng toàn cục (summary cards) cho báo cáo CK theo sale — tính trên toàn bộ sale khớp bộ lọc, không phụ thuộc trang đang xem.

Tham số bảng thông minh (dùng cùng bộ lọc với search) ID người dùng hiện tại Dòng tổng toàn cục

Lấy thống kê chuyển khoản ngân hàng theo khách hàng (phân trang server-side)

Tham số bảng thông minh ID người dùng hiện tại Trang dữ liệu thống kê chuyển khoản theo khách hàng

Lấy dòng Tổng toàn cục (summary cards) cho báo cáo CK theo khách hàng — tính trên toàn bộ khách hàng khớp bộ lọc, không phụ thuộc trang đang xem.

Tham số bảng thông minh (dùng cùng bộ lọc với search) ID người dùng hiện tại Dòng tổng toàn cục

Lấy danh sách đơn CK kế toán chi tiết theo ô số liệu (metric), phân trang server-side. Dùng cho dialog danh sách chi tiết khi click vào từng ô số liệu trên báo cáo tổng hợp.

Tham số lọc + phân trang + sắp xếp, bổ sung SaleId/CustomerId và Metric ID người dùng hiện tại Trang dữ liệu đơn chi tiết

Dịch vụ báo cáo tài chính đơn hàng

Khởi tạo một thể hiện của .

Kết nối cơ sở dữ liệu. Dịch vụ quản lý người dùng.

Lấy thống kê chuyển khoản ngân hàng theo sale

Tham số bảng thông minh ID người dùng hiện tại Danh sách thống kê chuyển khoản theo sale

Lấy thống kê chuyển khoản ngân hàng theo sale (phân trang server-side, synchronous)

Lấy dòng Tổng toàn cục cho báo cáo CK theo sale (synchronous).

Lấy thống kê chuyển khoản ngân hàng theo khách hàng

Tham số bảng thông minh ID người dùng hiện tại Danh sách thống kê chuyển khoản theo khách hàng

Bộ lọc đã chuẩn hóa cho báo cáo CK theo khách hàng (dùng chung search + totals).

Đọc & chuẩn hóa bộ lọc từ SmartTableParam + áp dụng scope phân quyền (không phải Founder/Accountant chỉ được xem dữ liệu của chính mình).

Thêm 6 tham số lọc chung vào command (dùng cho cả SP search & SP totals).

Lấy thống kê chuyển khoản ngân hàng theo khách hàng (phân trang server-side, synchronous)

Lấy dòng Tổng toàn cục cho báo cáo CK theo khách hàng (synchronous).

Map metric (ô số liệu) -> danh sách stage tương ứng (CSV). Tổng đơn / Phí CK => tất cả stage hợp lệ (null => SP tự dùng 1,4,9).

Xuất Excel danh sách đơn CK kế toán chi tiết theo sale + theo ô số liệu (metric)

Lấy thống kê đơn hàng theo ngày từ stored procedure

Tham số bảng thông minh ID người dùng Danh sách thống kê đơn hàng theo ngày

Lấy báo cáo công nợ theo sale từ stored procedure

Tham số bảng thông minh ID người dùng Danh sách báo cáo công nợ theo sale

Lấy báo cáo số lượng đơn và doanh số theo tuyến

Tham số bảng thông minh ID người dùng Danh sách báo cáo theo tuyến và trạng thái

Dịch vụ báo cáo đơn hàng

Lấy thống kê đơn hàng theo ngày từ stored procedure

Tham số bảng thông minh ID người dùng Danh sách thống kê đơn hàng theo ngày

Lấy báo cáo công nợ theo sale từ stored procedure

Tham số bảng thông minh ID người dùng Danh sách báo cáo công nợ theo sale

Lấy báo cáo số lượng đơn và doanh số theo tuyến

Tham số bảng thông minh ID người dùng Danh sách báo cáo theo tuyến và trạng thái

Xuất Excel ba báo cáo doanh số theo chiều (plan §3.3).

Dữ liệu lấy qua CHÍNH — đã ép phạm vi người xem — không gọi SP riêng, để đường Excel và đường màn hình không bao giờ lệch hàng rào. Tên trong dòng "Bộ lọc" cũng lấy từ ô lọc đã ép phạm vi của service đó, nên id ngoài phạm vi không có tên nào để lộ.

Bộ lọc trỏ tới một bưu cục / nhóm không nằm trong ô lọc của người xuất — file khi đó không có dòng nào.

Bộ lọc của MỘT chiều (chỉ những khoá chiều đó thật sự dùng) để ghi lên file.

Bộ lọc của MỘT chiều (chỉ những khoá chiều đó thật sự dùng) để ghi lên file.

Cùng bộ đọc tham số với service đọc — chỉ để ghi loại địa chỉ và bộ lọc lên file. Tham số sai thì service đọc đã từ chối trước khi file được dựng.

Dòng "Bộ lọc" của file — xem .

Bộ lọc của ba báo cáo doanh số theo chiều + drill-down, đọc từ SmartTableParam.Search.PredicateObject và đã kiểm miền giá trị — giá trị sai bị chặn ở đây với một câu tiếng Việt, không để SQL THROW thành HTTP 500.

Kỳ tính theo NGÀY giờ Việt Nam: = 00:00 +07:00 ngày đầu, = 23:59:59 +07:00 ngày cuối, luôn mang offset — SP quy về +07:00 rồi lấy ngày, nên mốc UTC kiểu axios toISOString cũng đúng ngày. Không bao giờ chuyển sang DateTime: SqlClient coi DateTime không offset là UTC và mốc 23:59:59 sang ngày hôm sau. Thiếu mốc nào thì lấy theo tháng hiện tại (Q8); khoảng dài hơn 12 tháng bị từ chối. Khoá đọc không phân biệt hoa thường; giá trị không đọc được coi như không gửi.

Giờ Việt Nam — múi duy nhất của kỳ báo cáo.

Trần số đơn một trang drill-down — bằng trần của SP.

00:00 giờ Việt Nam của ngày đầu kỳ.

23:59:59 giờ Việt Nam của ngày cuối kỳ.

Bưu cục client chọn (báo cáo bưu cục, phường/xã, drill-down chiều 3) — chỉ thu hẹp.

Nhóm client chọn (báo cáo nhóm); 0 = "Chưa có quản lý trực tiếp", -1 = "Đơn không có sale" — chỉ thu hẹp. Nhỏ hơn -1 hoặc không gửi = không lọc.

1 điểm lấy (mặc định), 2 điểm giao.

Tỉnh 2 cấp; null = mọi tỉnh.

Từ khoá tên xã, có dấu hay không dấu.

Chiều của drill-down (1/2/3); null khi không gửi.

Khoá dòng của drill-down (AgencyId / ManagerId / WardId); null khi không gửi.

Cột của drill-down: 0 = Tổng (mọi nhóm), 1–4 = OrderStatusGroup.

Trang drill-down, đánh từ 1.

Cỡ trang drill-down, trần .

Đọc và kiểm bộ lọc.

Tham số client gửi. Thời điểm hiện tại — để tính kỳ mặc định. Bộ lọc đã kiểm; null khi trả false. Câu báo lỗi tiếng Việt khi trả false.

Ngày giờ Việt Nam chứa mốc client gửi. Newtonsoft có thể đã đổi chuỗi ngày thành DateTime (theo giờ máy chủ hoặc UTC) — vẫn đúng thời điểm, đổi sang +07:00 rồi lấy ngày. Chuỗi không có offset hiểu là giờ Việt Nam.

Báo cáo doanh số theo bưu cục / nhóm / phường xã × 4 nhóm trạng thái đơn + drill-down (docs/plan-bao-cao-doanh-so-theo-chieu.md §3.3).

Mọi đường đọc — kể cả drill-down và Excel (Excel gọi lại chính các hàm này) — ép phạm vi người xem ở đây qua . Phạm vi rỗng ⇒ trả rỗng, KHÔNG gọi stored procedure.

Doanh số theo bưu cục bán (Order.SaleAgencyId).

Doanh số theo nhóm (quản lý trực tiếp của sale).

Doanh số theo phường/xã của điểm lấy hoặc điểm giao.

Danh sách đơn của một ô. Kiểm role của chiều ngay trong service (action chỉ đòi đăng nhập), rồi dùng CÙNG hàm phạm vi với báo cáo của chiều đó.

Bưu cục và nhóm trong phạm vi người xem, kèm tỉnh/thành phố bộ 2 cấp, cho ô lọc của ba trang.

Tên dòng nhóm — trùng tên SP đặt.

Nguồn luật "ai xem được doanh số của ai" và luật Founder/kế toán không giới hạn — dùng lại, không dựng cây phân cấp thứ ba.

IUserRepository chứ không phải IRepository<User> — xem ghi chú ở ReconciliationVisibilityResolver.

Phạm vi bưu cục đã thu hẹp theo bộ lọc, kèm cờ gom đơn không có bưu cục bán.

Phạm vi bưu cục đã thu hẹp theo bộ lọc, kèm cờ gom đơn không có bưu cục bán.

Phạm vi bưu cục: Founder/kế toán → mọi bưu cục kể cả đã xoá mềm; người đứng tên bưu cục → các bưu cục đó + con cháu; còn lại rỗng (plan §6.3). Bộ lọc chỉ thu hẹp; node Region mở thành con cháu trên cây ĐẦY ĐỦ (kể cả bưu cục đã xoá).

Phạm vi sale: nguyên ; Founder/kế toán → mọi user kể cả đã xoá mềm.

Quản lý trực tiếp của từng sale — đúng nguồn cột ManagerId của vw_OrderRevenueFact (UserPreference chưa xoá, ManagerId > 0).

Gắn cờ bưu cục đã xoá mềm — giao diện ghi "(đã ngừng)".

Kiểm người dùng + bộ lọc, ghi kỳ thực dùng vào kết quả. False = kết quả đã mang lỗi.

Kỳ truyền xuống SP — luôn DateTimeOffset +07:00. DateTime bị SqlClient coi là UTC, mốc 23:59:59 khi đó sang ngày hôm sau.

Ghi log đầy đủ, trả người dùng một câu chung — không lộ chi tiết lỗi SQL.

Một tập id phạm vi (bưu cục hoặc sale) truyền xuống @AgencyIds / @SaleIds của sp_GetOrderRevenueBy*.

Không có trạng thái "không giới hạn": bốn SP doanh số theo chiều không có nhánh "tất cả", nên Founder/kế toán cũng mang danh sách tường minh. Tập rỗng = false = KHÔNG gọi SP.

Id đã lọc > 0, không trùng, tăng dần.

Có dòng nào để đọc. False thì service trả rỗng và không gọi stored procedure.

Danh sách ngăn cách dấu phẩy cho tham số SP — chỉ gọi khi .

Phạm vi của một lần đọc báo cáo doanh số theo nhóm (hoặc drill-down chiều nhóm), đã tính bộ lọc nhóm.

Có dòng nào để đọc. False thì không được gọi stored procedure.

@SaleIds — không bao giờ rỗng khi .

@ManagerIds: null = không thu hẹp theo nhóm. Không bao giờ là chuỗi rỗng — SP hiểu '' là "0 dòng", nhưng hàng rào phải ở đây chứ không trông vào SP.

@IncludeUnassigned: thêm dòng "Đơn không có sale" — chỉ Founder/kế toán (plan §6.3).

Dữ kiện để tính phạm vi bưu cục — service đọc từ DB, áp luật.

Founder / kế toán (cùng luật ). Mọi Agency KỂ CẢ đã xoá mềm — chỉ đọc khi . Bưu cục người xem đứng tên Agency.ManagerId, đã mở con cháu. Node AgencyType.Region — node gộp, không bao giờ là một dòng.

Dữ kiện để tính phạm vi bưu cục — service đọc từ DB, áp luật.

Founder / kế toán (cùng luật ). Mọi Agency KỂ CẢ đã xoá mềm — chỉ đọc khi . Bưu cục người xem đứng tên Agency.ManagerId, đã mở con cháu. Node AgencyType.Region — node gộp, không bao giờ là một dòng.

Founder / kế toán (cùng luật ).

Mọi Agency KỂ CẢ đã xoá mềm — chỉ đọc khi .

Bưu cục người xem đứng tên Agency.ManagerId, đã mở con cháu.

Node AgencyType.Region — node gộp, không bao giờ là một dòng.

Một nút của cây bưu cục ĐẦY ĐỦ (kể cả đã xoá mềm) — để mở con cháu khi lọc theo khu vực.

Một nút của cây bưu cục ĐẦY ĐỦ (kể cả đã xoá mềm) — để mở con cháu khi lọc theo khu vực.

Dịch phạm vi xem của người dùng thành tham số của bốn SP doanh số theo chiều (plan-bao-cao-doanh-so-theo-chieu §3.3, quyết định §6.3).

Hàm thuần cùng khuôn , và cùng lý do: service gọi Dapper thẳng nên luật phạm vi chỉ kiểm chứng được bằng test khi nằm riêng ở đây. Hai phạm vi: Bưu cục (báo cáo bưu cục, phường/xã, drill-down chiều 1 và 3): Founder/kế toán → mọi bưu cục kể cả đã xoá mềm (để tổng = tổng KPI); người đứng tên Agency.ManagerId → các bưu cục đó + con cháu; còn lại → rỗng. Cố ý KHÔNG mở theo User.AgencyId: role báo cáo cấp cho cả nhóm "Kinh doanh", mở theo bưu cục của bản thân thì một sale ngồi HQ thấy danh sách đơn (kèm tên khách) của cả HQ — đúng điều ReconciliationVisibilityResolver đã chữa. Sale (báo cáo nhóm, drill-down chiều 2): nguyên — bản thân + cấp dưới đệ quy + nhân sự bưu cục mình đứng tên; Founder/kế toán → mọi user kể cả đã xoá mềm (sale đã nghỉ vẫn có đơn — thiếu họ là tổng báo cáo nhóm hụt). Bộ lọc của client chỉ được thu hẹp: id ngoài phạm vi bị bỏ im lặng, lọc xong không còn id nào thì rỗng — không bao giờ lấy thêm được dòng nào (chống IDOR, §3.8).

Khoá nhóm "Đơn không có sale" (SaleId không trỏ User nào — đơn khách tự tạo qua Lada.App ghi cứng SaleId = 0). Chỉ Founder/kế toán thấy, để tổng báo cáo nhóm = tổng view (plan §6.3).

Phạm vi bưu cục của người xem.

Thu hẹp phạm vi bưu cục theo bộ lọc của client.

Phạm vi của người xem. Bưu cục client chọn, đã mở con cháu nếu là node Region (lọc theo khu vực = lọc theo con cháu). null = không lọc; tập rỗng = lọc ra không gì.

Báo cáo phường/xã (và drill-down chiều 3) có gồm đơn không có bưu cục bán thật (SaleAgencyId = 0, trỏ bưu cục không tồn tại hoặc node khu vực) hay không: chỉ Founder/kế toán, và chỉ khi KHÔNG lọc bưu cục — đơn đó không thuộc bưu cục nào nên lọc theo bưu cục là phải mất.

Chính nó + mọi con cháu trên cây bưu cục ĐẦY ĐỦ, kể cả nút đã xoá mềm và nhánh nằm dưới chúng — để Founder lọc theo khu vực vẫn thấy bưu cục đã ngừng (DS-7). Khác IAgencyService.GetAgencyWithDescendantIdsAsync (chỉ cây đang sống, dùng cho phạm vi người đứng tên). Có chặn vòng lặp dữ liệu.

Phạm vi sale của người xem.

Kết quả IReconciliationVisibilityResolver.ResolveAsync. Mọi User.Id kể cả đã xoá mềm — chỉ đọc khi Unrestricted.

Phạm vi báo cáo nhóm sau bộ lọc nhóm của client.

Phạm vi sale của người xem. UserPreference.ManagerId > 0 theo sale (dòng chưa xoá) — đúng nguồn cột ManagerId của view. Sale vắng mặt = nhóm 0 "Chưa có quản lý trực tiếp". Chỉ cần khi có . Nhóm client chọn; 0 = "chưa có quản lý"; = "Đơn không có sale"; null hoặc nhỏ hơn = không lọc. Founder/kế toán — người duy nhất thấy nhóm "Đơn không có sale". Lọc theo nhóm thu hẹp luôn @SaleIds xuống các sale của nhóm đó trong phạm vi: nhóm ngoài phạm vi (không sale nào của mình thuộc nhóm ấy) ra rỗng ngay ở đây, không gọi SP. Người bị giới hạn xin nhóm "Đơn không có sale" cũng rỗng.

Các nhóm (quản lý trực tiếp, kể cả 0) có ít nhất một sale trong phạm vi — cho ô lọc nhóm.

Một cột chiều (cột đứng trước 4 cặp số) của file Excel doanh số theo chiều.

Một cột chiều (cột đứng trước 4 cặp số) của file Excel doanh số theo chiều.

File Excel của báo cáo doanh số theo chiều — đúng bảng trên màn hình: cột chiều + 4 cặp (số đơn, doanh số) theo nhóm trạng thái + tổng, dòng "Tổng cộng" cuối.

Hàm thuần: nhận dòng ĐÃ ép phạm vi, trả byte. Mọi ô ghi dạng giá trị (không công thức), nên tên bắt đầu bằng = không thành công thức.

Dòng tiêu đề nhóm cột (dòng dưới nó là "Số đơn" / "Doanh số").

Dòng dữ liệu đầu tiên.

4 nhóm trạng thái theo thứ tự cột, rồi "Tổng".

Tên sheet. Dòng tiêu đề (dòng 1). Dòng kỳ báo cáo (dòng 2). Dòng bộ lọc đang áp (dòng 3) — dựng bằng . Dòng người xuất (dòng 4). Cột chiều. Các dòng đã ép phạm vi. Dòng tổng cộng.

Dòng "Bộ lọc" của file. File tách khỏi màn hình ngay khi tải về: không ghi bộ lọc thì dòng "Tổng cộng" của một file đã lọc theo bưu cục / nhóm / tỉnh bị đọc thành tổng cả kỳ, và hai lần xuất khác bộ lọc ra hai file không phân biệt được (review GĐ C2).

Từng bộ lọc đang áp dạng (nhãn, giá trị hiển thị); rỗng = không lọc.

Phạm vi nhân sự của một lần đọc báo cáo doanh số theo Sale, đã tính cả bộ lọc người dùng chọn.

Có dòng nào để đọc hay không. False thì không được gọi stored procedure.

Danh sách nhân sự truyền xuống @SaleIds, ngăn cách dấu phẩy. null nghĩa là không giới hạn (Founder / kế toán). Không bao giờ là chuỗi rỗng — stored procedure hiểu chuỗi rỗng là "mọi sale", nên rỗng phải đi đường .

Dịch phạm vi xem của người dùng thành tham số của sp_GetOrderRevenueStatisticsBySale_Optimized.

Hàm thuần, tách khỏi SaleReportService vì service gọi Dapper thẳng nên không có cách nào kiểm chứng luật phạm vi bằng test nếu luật nằm lẫn trong đó. Nguồn luật "ai xem được doanh số của ai" vẫn là IReconciliationVisibilityResolver — bản thân + cấp dưới theo UserPreference.ManagerId (đệ quy hết cây) + nhân sự các chi nhánh mình đứng tên quản lý. Tên kiểu còn mang tiền tố Reconciliation vì miền đối soát là nơi luật này ra đời; cố ý dùng lại thay vì dựng cây phân cấp thứ hai.

Tính phạm vi cho một lần đọc.

Phạm vi nhân sự của người đang đăng nhập. Sale mà người dùng chọn trên bộ lọc, nếu có. Bộ lọc của client chỉ được thu hẹp: chọn một người ngoài phạm vi thì kết quả rỗng chứ không lấy thêm được dòng nào (chống IDOR).

Ba báo cáo doanh số theo chiều, nút Xuất Excel và link mã đơn của drill-down có được hiện cho một người hay không (rule quyen-hien-thi).

Hàm thuần cùng khuôn FranchisePriceNavPermissions: nhận role đã phân giải qua IUserRoleResolver, trả cờ — để luật "ai thấy gì" có ca test gọi thẳng vào nó, và để drill-down kiểm role theo chiều bằng CÙNG một luật (). Bốn role riêng tiền tố RevenueReport., không mượn role miền khác (plan §3.6). Đổi role ở đây thì sửa cả [Authorize] của RevenueReportController, script seed role và script menu — test reflection canh cờ ↔ [Authorize]. Riêng là role của MIỀN ĐƠN HÀNG: cờ phải đọc đúng bó quyền của thứ nó gác (trang tra cứu đơn), không phải bó quyền của báo cáo.

Vai bỏ qua mọi kiểm tra role (ServerRoleAuthorizationHandler) — ẩn nút của Founder là dựng hàng rào không có thật.

Báo cáo doanh số theo bưu cục.

Báo cáo doanh số theo nhóm.

Báo cáo doanh số theo phường/xã.

Xuất Excel — đi KÈM role của chiều (hai [Authorize] trên action Export là phép AND).

Role của GET Order/TrackingWithUnits — lời gọi duy nhất của trang tra cứu đơn mà link mã đơn trong hộp thoại drill-down mở ra. Người xem báo cáo mà thiếu role này bấm link là cả SPA bị đá sang trang "không có quyền" (bấm thật GĐ C2, vai kế toán).

Chiều 1 bưu cục, 2 nhóm, 3 phường/xã — đúng @Dimension của sp_GetOrderRevenueDetail.

Role đã phân giải qua IUserRoleResolver; null = không có role nào. So khớp phân biệt hoa thường — đúng như ServerRoleAuthorizationHandler (roles.Contains).

Người có cờ này có được đọc chiều không — luật kiểm role của drill-down.

Cờ hiển thị của ba báo cáo doanh số theo chiều — FE đọc bằng === true, mặc định false, ẩn hẳn phần tử.

Cờ hiển thị của ba báo cáo doanh số theo chiều — FE đọc bằng === true, mặc định false, ẩn hẳn phần tử.

Interface dịch vụ báo cáo bán hàng

Lấy thống kê doanh thu theo sale từ stored procedure

Tham số bảng thông minh ID người dùng Kết quả thống kê doanh thu

Lấy thống kê đơn hàng và doanh thu theo ngày từ stored procedure

Tham số bảng thông minh ID người dùng Danh sách thống kê đơn hàng và doanh thu theo ngày

Lấy thống kê doanh thu theo ngày nhận tiền từ stored procedure

Tham số bảng thông minh ID người dùng Danh sách thống kê doanh thu theo ngày nhận tiền

Lấy thống kê doanh thu theo Sale (chỉ thống kê tài chính) từ stored procedure

Trả về doanh số của mọi nhân sự trong phạm vi quản lý của người gọi, không chỉ của riêng người đó: bản thân + cấp dưới theo cây quản lý + nhân sự các chi nhánh mình đứng tên quản lý; Founder và kế toán xem toàn công ty. Bên gọi cần đúng doanh số cá nhân thì phải tự lọc theo SaleId — xem SalesPersonalRevenueProvider. Tham số bảng thông minh ID người dùng Danh sách thống kê theo Sale

Lấy thống kê doanh thu theo khách hàng từ stored procedure

Tham số bảng thông minh ID người dùng Kết quả thống kê doanh thu theo khách hàng

Lấy thông tin quyền của user cho báo cáo doanh thu theo khách hàng

ID người dùng Thông tin quyền

Dịch vụ báo cáo bán hàng

Nguồn luật "ai xem được doanh số của ai" — xem .

Lấy cấu hình đang hiệu lực

Cập nhật cấu hình (tạo version mới)

Tạm dừng / Mở lại

Tìm kiếm danh sách cấu hình

Lấy chi tiết cấu hình theo ID

Tạo mới hoặc cập nhật cấu hình

Xóa cấu hình

Tìm kiếm danh sách cấu hình

Lấy chi tiết cấu hình theo ID

Tạo mới hoặc cập nhật cấu hình

Xóa cấu hình (soft delete)

Tìm kiếm phiếu thưởng/phạt

Tạo biên bản vi phạm nộp tiền trễ từ trang Cashier

Đọc số lượt bot cho màn hình. Không gọi ra ngoài lần nào — mọi con số đã nằm sẵn trong BotVisitDaily, do middleware của website ghi. Con số ở đây là theo User-Agent TỰ KHAI. Không reverse-DNS, không đối chiếu dải IP của Google (nợ SC-11). Mọi màn hình đọc service này phải nói câu đó ra, vì con số trông y hệt một con số đã xác minh.

Các con số tổng hợp đầu tab, kèm câu trả lời cho "vì sao đang là 0".

Độ dài khoảng ngày Lọc theo một bot; null là mọi bot

Xếp hạng đường dẫn theo số lượt bot trong khoảng ngày.

Độ dài khoảng ngày Lọc theo một bot; null là mọi bot Số dòng tối đa Chỉ lấy đường dẫn có lượt trả mã từ 400 trở lên

Trần số dòng trả về một lượt, chống ?take=999999 kéo cả bảng.

Trần số ngày hỏi được một lượt. Đặt bằng 400 chứ không bằng hạn giữ dữ liệu (90): hạn giữ là một khoá cấu hình có thể bị nâng lên, còn đây là hàng rào chống một lời gọi quét cả bảng.

Gắn cờ "đường dẫn này hệ thống có biết không" cho từng dòng.

So giữa hai dạng ĐÃ chuẩn hoá, không so thẳng hai cột. SearchUrl.Path được ghi bằng Uri.AbsolutePath nên giữ nguyên chữ hoa và giữ nguyên dạng mã hoá phần trăm; BotVisitDaily.Path thì đã hạ chữ thường và bỏ / cuối. So thẳng là cách chắc chắn ra kết quả sai — đúng cái bẫy đã cắn ở giai đoạn E (nối UrlNormalized với SearchUrl.Url thô) và lặp lại ở giai đoạn F. Cả hai bên vì thế cùng đi qua UrlRedirectHelper.NormalizeLookupPath. Nạp trọn hàng tồn kho vào bộ nhớ vì phép chuẩn hoá là một hàm C#, không dịch được sang SQL. Đo 2026-09-17 trên DB dev: 148 dòng — không đáng để đổi lấy một phép so sai.

Rổ gộp của bộ đếm khi chạm trần số khoá — khớp BotVisitCounter.PathTran bên website.

Lớp duy nhất biết giao thức đọc số liệu hiệu suất tìm kiếm. Tách khỏi dù cùng tên miền và cùng phạm vi OAuth webmasters, vì hình dạng việc khác hẳn: đây là lời gọi phân trang, trả về hàng nghìn dòng, và có một khái niệm riêng — dataState — mà ba endpoint kia không có. Nhét nó vào giao diện kia sẽ làm mọi cài đặt giả trong test phải cài thêm một phương thức chúng không dùng.

Công cụ tìm kiếm mà cài đặt này nói chuyện.

Đọc một trang kết quả. Trả kết quả bị chặn (và không có lời gọi nào đi ra) khi công tắc đọc còn tắt.

Khoảng ngày, các chiều, và vị trí phân trang. Thẻ huỷ.

Một lời gọi đọc số liệu — đúng một trang kết quả.

Ngày đầu khoảng (bao gồm).

Ngày cuối khoảng (bao gồm).

Các chiều, theo đúng chữ của Google (date, page, query). Chiều date luôn đứng đầu ở mọi lời gọi của giai đoạn này, và đó là một quyết định đo được: thêm nó vào thì một lời gọi phủ trọn một khoảng ngày mà vẫn giữ nguyên độ mịn theo ngày. Đối chứng 2026-09-16 cho ngày 13/09: date+page trả 117 dòng, gọi riêng ngày ấy với page cũng trả đúng 117. Nhờ vậy job hằng ngày gọi 3 lần thay vì 30, và lượt kéo bù 16 tháng gọi ~51 lần thay vì ~1.500.

Dòng bắt đầu — phân trang. Google trả tối đa dòng mỗi lượt.

Số dòng tối đa mỗi lượt. Trần của Google là 25.000.

Trần Google cho phép cho rowLimit.

Một trang kết quả đã đọc xong.

Các dòng của trang này.

Còn trang sau hay không. Google không nói ra điều này; suy từ việc trang hiện tại đầy đúng bằng rowLimit. Suy sai theo chiều thừa chỉ tốn một lời gọi trả về rỗng; suy sai theo chiều thiếu là mất dữ liệu im lặng, nên chọn chiều thừa.

Một dòng số liệu thô như Google trả về.

Các giá trị chiều, đúng thứ tự đã hỏi trong .

Vị trí trung bình của dòng này. Chưa nhân trọng số — xem chỗ lưu.

Cài đặt cho Google Search Analytics (searchanalytics.query của Search Console API). dataState viết cứng là final, không để thành tham số. Đây là hàng rào duy nhất chống việc ghi vào DB một con số Google chưa chốt — mà số chưa chốt thì ghi rồi là sai vĩnh viễn, vì lượt kéo sau sẽ không bao giờ quay lại ngày đó nữa nếu nó đã ra khỏi cửa sổ trượt. Mở nó thành tham số là để lại đúng một chỗ cho ai đó truyền all vào rồi không ai biết. Đo thật 2026-09-16: final trả tới T-3, all trả tới T-1, và với 13 ngày trùng nhau thì hai bên cho số giống hệt — nghĩa là final không làm mất gì, nó chỉ từ chối trả những ngày chưa xong. Cách xử lý lỗi giống hệt hai client kia, cố ý: 403 là lỗi quyền nên không thử lại; 429 ném để lượt chạy dừng hẳn; 5xx và lỗi mạng thử lại tối đa ba lần, giãn cách 2^lần giây.

Tên named client riêng — để đo và cấu hình tách khỏi hai đường gọi kia.

Chỉ nhận số đã chốt. Xem XML-doc của lớp về việc vì sao đây không phải tham số.

Đọc phản hồi. Google bỏ hẳn khoá rows khi không có dòng nào (chứ không trả mảng rỗng), nên "không có rows" là một kết quả hợp lệ chứ không phải lỗi đọc.

Google trả clicks và impressions dưới dạng số thực trong JSON (ví dụ 44.0), nên đọc thẳng bằng GetInt64 sẽ ném. Đọc qua double rồi làm tròn.

Gửi một lời gọi, thử lại khi lỗi tạm thời, rồi đọc kết quả. Hàm dựng request truyền vào dưới dạng factory vì chỉ gửi được một lần.

Rút gọn phản hồi lỗi để ghi nhật ký. Cắt ngắn vì phản hồi lỗi của Google có thể rất dài, và cột nhật ký có trần.

Lớp duy nhất biết giao thức của một công cụ tìm kiếm. Đây là điểm cắm cho công cụ thứ hai: thuộc tính cho phép phân giải theo enum đúng như IWidgetDataProvider phân giải theo Code. Hôm nay chỉ có một cài đặt (Google) — quyết định Q6c là chuẩn bị mô hình dữ liệu, không dựng sẵn đường gọi Bing/IndexNow.

Công cụ tìm kiếm mà cài đặt này nói chuyện.

Hỏi trạng thái index của một URL.

Đọc trạng thái một tệp sitemap.

Nộp một tệp sitemap. Chỉ chạy khi cả hai công tắc bật; công tắc ghi tắt thì trả về kết quả bị chặn và không có lời gọi nào đi ra.

Thử kết nối bằng một lời gọi đọc nhẹ nhất (liệt kê sitemap của property). Chỉ trả về được hay không được kèm lý do — không trả về email service account hay bất cứ mẩu nào của khoá, vì kết quả này hiện lên giao diện quản trị.

Cài đặt cho Google Search Console, gọi REST qua . Vì sao gọi REST thẳng thay vì dùng gói Google.Apis.SearchConsole.v1. Đã kiểm 2026-09-15: gói đó cài chung với Google.Ads.GoogleAds 26.1.0 không xung đột (build 0 lỗi) — nên lý do không phải xung đột. Lý do là kiểm thử: gói chính chủ tự dựng và tự giữ HttpClient bên trong, muốn chặn lời gọi trong test phải luồn một ConfigurableMessageHandler mà repo chưa có mẫu nào. Gọi REST qua IHttpClientFactory thì dùng lại được FakeHttpClientFactory sẵn có (đang dùng cho Zalo và Facebook), và kiểm được đúng thứ quan trọng nhất của đợt này: công tắc tắt thì có đúng 0 lời gọi đi ra. Phần ký JWT — chỗ dễ sai và nguy hiểm nhất — vẫn giao cho thư viện chính chủ Google.Apis.Auth. Công tắc được canh ở đây, không chỉ ở job. Job cũng đọc công tắc để quyết định chạy thử hay chạy thật, nhưng hàng rào cuối cùng đặt trong client: một đường gọi mới thêm về sau (nút bấm tay, một job khác) sẽ không tự biết phải kiểm công tắc, còn client thì luôn nằm trên đường đi. Cách xử lý lỗi, theo hậu quả chứ không theo mã. 403: lỗi quyền — service account chưa phải owner của property, hoặc SiteUrl sai dạng. Thử lại bao nhiêu lần cũng vẫn 403, nên báo thẳng. 429: hết hạn mức — không thử lại, ném để job dừng hẳn. Cố ý khác chữ trong kế hoạch (ở đó 429 nằm trong nhóm "lỗi tạm thời"): thử lại 429 chính là đốt thêm hạn mức đang hết, mâu thuẫn với yêu cầu "429 dừng job, không đốt quota" trong cùng kế hoạch. 5xx, lỗi mạng, hết giờ chờ: lỗi tạm thời — thử lại tối đa 3 lần, giãn cách 2^lần giây theo mẫu GoogleAdsAdapter.ExecuteWithRetryAsync.

Tên named client — theo nếp ZaloApiService.HttpClientName.

Trần độ dài phần JSON thô lưu vào DB. Phản hồi của Google thường dưới 4 KB; phần vượt quá 64 KB không mang thêm thông tin nào mà chỉ làm nặng bảng và nặng cả màn xem chi tiết.

Dựng endpoint cho một tệp sitemap. Cả định danh property lẫn địa chỉ tệp đều phải mã hoá: property Domain chứa dấu hai chấm (sc-domain:ladaexpress.vn) và địa chỉ tệp chứa dấu gạch chéo — để nguyên thì chúng bị hiểu thành phân đoạn đường dẫn và Google trả 404.

Gửi một lời gọi, thử lại khi lỗi tạm thời, rồi đọc kết quả. Hàm dựng request được truyền vào dưới dạng factory vì chỉ gửi được một lần — lần thử lại phải có một đối tượng mới.

Lỗi tạm thời: mạng trục trặc hoặc hết giờ chờ. Hết hạn mức và lỗi quyền không nằm ở đây.

Rút thông báo lỗi của Google về một dòng đọc được, có cắt ngắn: thân lỗi đôi khi là cả trang HTML, nhét nguyên vào cột ErrorMessage thì vừa tràn vừa không ai đọc.

Cắt JSON thô về trần lưu trữ.

Đọc một con số mà Google có thể trả dưới dạng chuỗi hoặc số — hai kiểu này lẫn lộn ngay trong cùng một phản hồi.

Lấy access token để gọi Search Console. Vì sao tách khỏi client. Lấy token là việc chạm đĩa (đọc tệp khoá) và chạm mạng (đổi JWT lấy token) — trộn vào client thì không lớp test nào kiểm được client mà không có khoá thật. Tách ra thì test bơm một token giả, còn phần ký JWT giao hẳn cho thư viện chính chủ của Google.

Access token dùng cho header Authorization. Ném khi chưa cấu hình đường dẫn khoá hoặc tệp khoá không đọc được.

Access token cho một phạm vi cụ thể. Vì sao phải có tham số phạm vi. Cùng một service account, nhưng Search Console và Indexing API là hai API khác nhau với hai phạm vi khác nhau (auth/webmasters và auth/indexing). Một token xin cho phạm vi này gọi API kia sẽ bị từ chối, và thông báo lỗi của Google không nói rằng nguyên nhân là sai phạm vi.

Phạm vi OAuth đầy đủ, ví dụ https://www.googleapis.com/auth/indexing. Thẻ huỷ.

Lấy access token từ tệp khoá JSON của một service account Google Cloud. Tệp khoá nằm ngoài repo và ngoài wwwroot, đường dẫn khai ở Search:Google:ServiceAccountKeyPath trong appsettings hoặc biến môi trường — cùng nếp với Security:SecretKey. Cố ý không cất vào DB: đổi khoá là việc vận hành, và một khoá nằm trong DB sẽ theo mọi bản sao lưu đi khắp nơi. Nội dung khoá không bao giờ được ghi log, kể cả khi lỗi: thông báo lỗi chỉ nói đường dẫn và triệu chứng. Token cũng vậy — nó nằm ở header và không đi vào nhật ký lời gọi. Service account phải được thêm làm delegated owner của property trong Search Console. Quyền Full hay Restricted đều trả 403 ở mọi lời gọi, và thông báo lỗi của Google không nói rằng nguyên nhân là mức quyền.

Phạm vi đủ cho cả đọc (kiểm tra URL, đọc sitemap) lẫn ghi (nộp sitemap). Bản webmasters.readonly không nộp được sitemap.

Phạm vi của Indexing API — khác phạm vi Search Console và phải xin riêng. Ngoài phạm vi, Indexing API còn phải được bật riêng trên project Google Cloud. Đo thật 2026-09-16 trên project lada-ads-manager: lấy token phạm vi này thành công, và lời gọi đọc đầu tiên vẫn trả 403 SERVICE_DISABLED kèm câu "Web Search Indexing API has not been used in project … before or it is disabled", trong khi cùng khoá ấy gọi Search Console vẫn 200. Nghĩa là khoá và quyền không phải nguyên nhân — cái thiếu là một nút bật trên bảng điều khiển Google Cloud.

Khoá cấu hình chứa đường dẫn tới tệp khoá JSON.

Lớp duy nhất biết giao thức báo chủ động một URL cho công cụ tìm kiếm. Tách khỏi vì đây là một API khác: khác tên miền, khác phạm vi OAuth, khác hạn mức, và phải bật riêng trên project Google Cloud. Gộp hai thứ vào một giao diện sẽ tạo ra một lớp mà nửa số phương thức chạy được còn nửa kia trả 403, tuỳ vào một nút bật ở nơi khác. Đây cũng là điểm cắm cho IndexNow về sau — cùng hình dạng "gửi một URL, nhận một kết quả", chỉ khác giao thức bên dưới. Thuộc tính cho phép phân giải theo enum.

Công cụ tìm kiếm mà cài đặt này nói chuyện.

Báo một URL. Trả kết quả bị chặn (và không có lời gọi nào đi ra) khi công tắc còn tắt.

URL tuyệt đối của trang. Báo cập nhật hay báo đã gỡ. Thẻ huỷ.

Cài đặt cho Google Indexing API. Google chỉ chấp nhận hai loại trang: tin tuyển dụng (JobPosting) và sự kiện phát trực tiếp (BroadcastEvent). Website này chỉ có loại thứ nhất, nên hàng rào "URL nào được báo" nằm ở chỗ xếp hàng đợi () chứ không ở đây — client thì gửi đúng thứ nó được đưa. Cách xử lý lỗi giống hệt client Search Console, cố ý: 403 là lỗi quyền hoặc API chưa bật nên không thử lại; 429 ném để job dừng hẳn thay vì đốt thêm hạn mức đang cạn; 5xx và lỗi mạng thử lại tối đa ba lần, giãn cách 2^lần giây. Hai client nói cùng một ngôn ngữ lỗi thì job không phải nhớ hai bộ quy tắc.

Tên named client riêng — để đo và cấu hình tách khỏi lời gọi Search Console.

Tên loại thông báo theo đúng chữ của Google. Cố ý viết tường minh thay vì suy từ tên enum: đổi tên một giá trị enum trong C# là việc bình thường, còn đổi chuỗi gửi lên Google thì không — tách ra thì trình biên dịch không im lặng cho qua.

Rút thông báo lỗi của Google về một dòng đọc được, có nói thêm cách sửa cho hai nguyên nhân hay gặp nhất mà lời của Google không chỉ ra được.

Xếp một URL vào hàng đợi báo cho công cụ tìm kiếm. Chỉ ghi vào bảng, không gọi ra ngoài. Đây là ranh giới cố ý: thao tác lưu của người dùng không được phụ thuộc vào một dịch vụ bên ngoài. Việc gửi thật là của SearchUrlNotifyJob.

Xếp hàng một thông báo cho tin tuyển dụng vừa đổi.

Tin tuyển dụng, đã nạp UrlRecord. Báo cập nhật hay báo đã gỡ. Thẻ huỷ. Dòng vừa ghi, hoặc null nếu không dựng nổi URL để báo.

Xếp hàng một URL bất kỳ. Mọi hàng rào nằm ở đây, và URL không đạt hàng rào vẫn được ghi một dòng kèm lý do — im lặng bỏ đi thì không ai biết hệ thống vừa suýt báo nhầm cái gì.

Khoá AppConfig chứa địa chỉ gốc của website công khai.

Tiền tố đường dẫn của nhóm URL duy nhất được phép báo chủ động. Google chỉ nhận Indexing API cho trang mang dữ liệu có cấu trúc JobPosting hoặc BroadcastEvent; website này chỉ có loại thứ nhất, và toàn bộ nó nằm dưới /tuyen-dung/. Báo một trang ngoài nhóm này là dùng sai API — Google nêu thẳng đó là lý do rút quyền gọi.

Ghi một dòng "cố ý không báo" kèm lý do, rồi ghi cảnh báo.

Cảnh báo ở mức Warning chứ không phải Information: mọi lời gọi tới đây đều xuất phát từ code của chính mình, nên một URL bị chặn nghĩa là có một đường sinh sự kiện đang gọi sai chỗ — thứ cần sửa, không phải thứ để ghi nhận rồi quên.

Kéo số liệu hiệu suất tìm kiếm về SearchMetricDaily. Một lớp duy nhất phục vụ cả hai đường chạy — job hằng ngày (cửa sổ trượt) và lượt kéo bù lịch sử (bấm tay, từng lô 30 ngày). Hai đường ấy chỉ khác nhau ở khoảng ngày truyền vào; gộp logic lại thì không có chuyện lượt kéo bù ghi kiểu này còn job hằng ngày ghi kiểu khác.

Kéo trọn một khoảng ngày, cả bốn mức, rồi ghi đè-hoặc-chèn vào bảng.

Công cụ tìm kiếm. Ngày đầu (bao gồm). Ngày cuối (bao gồm). Thẻ huỷ.

Ngày gần nhất đã có số trong bảng, ở mức . null nghĩa là chưa kéo lần nào — khác hẳn "đã kéo và bằng không".

Ngày sớm nhất đã có số — để biết lượt kéo bù đã đi ngược tới đâu.

Kết quả một lượt kéo, đủ để ghi nhật ký và để job in ra.

Số lời gọi API đã đi ra (gồm cả lời gọi phân trang).

Số dòng Google trả về, trước khi lọc ngưỡng.

Số dòng bị ngưỡng AnalyticsMinImpressions loại.

Số dòng mới chèn vào bảng.

Số dòng đã có và được ghi đè.

Lời gọi bị công tắc chặn nên chưa hề đi ra.

Lý do bị chặn, hoặc lý do thất bại.

Có lỗi thật (khác với bị chặn) hay không.

Google trả 429 — hết hạn mức. Tách khỏi vì hai thứ đòi hai phản ứng khác nhau ở phía job: một lỗi thật thì nên báo Failed để Hangfire thử lại, còn hết hạn mức thì thử lại là đốt thêm hạn mức đang cạn — Hangfire thử tới 10 lần. Phải dừng êm.

Có mức nào chạm trần phân trang mà vẫn còn dòng chưa lấy không. Dữ liệu bị cắt cụt mà không báo gì là cách hỏng tệ nhất của một bảng số liệu: nó trông vẫn đầy đủ.

Số ngày khác nhau có ít nhất một dòng ở mức toàn site.

Tên việc ghi vào SearchEngineApiLog cho mọi lời gọi đọc số liệu — cả job hằng ngày lẫn lượt kéo bù. Phải khác SearchIndexInspectJob.ActionName. Cột Action của bảng nhật ký chính là sổ đếm hạn mức dùng chung (ISearchApiLogger.CountTodayAsync), và hạn mức kiểm URL Search.Google.InspectDailyBudget đếm theo đúng tên ấy. Đặt trùng tên thì một lượt kéo bù 16 tháng sẽ ăn hết hạn mức kiểm URL của ngày hôm đó, và trang dashboard sẽ báo "đã dùng 51/300 lượt kiểm" trong khi chưa kiểm URL nào. Ngược lại, job hằng ngày và lượt kéo bù cố ý dùng CHUNG một tên. Chúng tiêu cùng một hạn mức thật của Google, nên tách tên sẽ làm con số đọc ra thấp hơn mức thật.

Trần số trang phân trang cho một mức trong một khoảng ngày. Đây là dây an toàn chống vòng lặp vô tận, không phải một giới hạn nghiệp vụ: đo 2026-09-16 thì lô 30 ngày nhiều dòng nhất (05/2025) trả 13.657 dòng — chưa tới một trang. 20 trang = 500.000 dòng.

Bốn mức và các chiều tương ứng, theo đúng chữ của Google. Chiều date đứng đầu ở cả bốn — nhờ vậy một lời gọi phủ trọn khoảng ngày mà vẫn giữ độ mịn theo ngày. Đối chứng 2026-09-16: date+page cho một ngày trả đúng bằng số dòng của lời gọi chỉ có page cho ngày ấy (117 = 117).

Kéo một mức. Trả null khi chạy xong bình thường; trả kết quả đã đánh dấu khi bị chặn hoặc gặp lỗi để chỗ gọi dừng hẳn.

Ghi đè-hoặc-chèn các dòng của một mức trong một khoảng ngày. Chỉ ghi đè, không xoá dòng cũ không còn thấy. Google lọc bớt truy vấn quá hiếm để giữ ẩn danh, nên một dòng có mặt hôm qua mà vắng hôm nay chưa chắc đã là "số ấy không còn đúng" — nó có thể chỉ rơi xuống dưới ngưỡng ẩn danh của Google. Xoá đi là đổi một con số đúng lấy một khoảng trống.

Vị trí × lượt hiển thị. Quy về ở đúng một chỗ để mọi dòng làm tròn giống nhau.

Băm cặp chiều thành khoá duy nhất. Băm trên chuỗi GỐC, không phải chuỗi đã chuẩn hoá. Đo 2026-09-16: 31/239 URL Google trả về mang neo #… và chúng thuộc chỉ 9 trang gốc — băm sau khi bỏ neo sẽ làm 38 dòng đè lên nhau, và con số đè sau thắng chứ không phải cộng lại. Mất số im lặng. Ký tự '\n' ngăn giữa hai chiều để cặp ("a", "b") không băm ra cùng giá trị với ("ab", null). Dùng \n vì URL và truy vấn đều không chứa nó.

Cắt truy vấn cho vừa cột. Truy vấn dài hơn 500 ký tự gần như chắc chắn là rác.

Luật chuẩn hoá URL của miền số liệu tìm kiếm — đúng một bản, dùng chung cho cả chỗ ghi lẫn chỗ đọc. Tách ra thành lớp tĩnh riêng vì bài học của giai đoạn trước: hai nơi cùng nói về một URL mà mỗi nơi tự chuẩn hoá theo cách của mình thì chúng sẽ không bao giờ khớp, và triệu chứng là một bảng trống chứ không phải một lỗi. Chỗ ghi dựng cột UrlNormalized bằng hàm này; chỗ đọc nối sang SearchUrl cũng phải bằng đúng hàm này.

Trần độ dài của cột Url và UrlNormalized.

Bỏ neo #… và dấu / ở cuối. Chỉ hai phép ấy, cố ý không làm gì hơn. Không hạ chữ thường (đường dẫn phân biệt hoa thường trên máy chủ này), không giải mã phần trăm (đo 2026-09-16 thấy có URL như /bang-gia-gui-xe-m%E1%BA%A3i-… — một slug gõ nhầm dấu; giải mã nó ra là đổi danh tính của một trang), không bỏ www. (property này không có URL www. nào). Mỗi phép thêm vào là một cách nữa để hai URL khác nhau bị gộp thành một. Neo là phần Google thêm khi kết quả có mục "nhảy tới phần" — đo 2026-09-16: 31 dòng thuộc 9 trang gốc. Giữ neo trong Url (đó là sự thật Google báo) nhưng gộp theo bản không neo, vì người đọc hỏi "trang này có bao nhiêu lượt bấm" chứ không hỏi từng mục lục.

Cắt cho vừa cột. URL dài nhất đo được là 176 ký tự nên đây là dây an toàn.

Ghi nhật ký lời gọi ra công cụ tìm kiếm — gồm cả lượt chạy thử không gửi đi thật. Gom về một lớp vì ba job đều phải ghi giống nhau, và vì đây là chỗ duy nhất biết luật cắt ngắn: nhật ký không bao giờ được chứa token, khoá, hay một thân phản hồi dài vô hạn.

Ghi một dòng nhật ký. Không tự lưu — chỗ gọi quyết định khi nào lưu.

Đếm số lượt gọi của một việc trong ngày hôm nay — cơ sở để dừng ở hạn mức. Chỉ đếm lượt đã đi ra ngoài: lượt chạy thử không tốn hạn mức nào.

Trần độ dài phần tóm tắt request/response lưu vào nhật ký.

Ba nút bấm tay của dashboard đồng bộ công cụ tìm kiếm — đây là đường duy nhất mà một người dùng có thể làm phát sinh lời gọi ra Google. Vì sao tách hẳn khỏi service đọc dashboard. Service đọc chỉ chạm 5 bảng đã có sẵn và không bao giờ gọi ra ngoài; ba hàm ở đây thì có. Nhìn danh sách DI là biết ngay cái nào tiêu hạn mức, cái nào không — và mọi ràng buộc an toàn (công tắc, hàng tồn kho, sổ hạn mức) chỉ phải canh ở đúng một lớp. Bấm tay tiêu hạn mức y hệt job. Không có sổ đếm riêng, không có đường gọi riêng: cả job lẫn nút bấm đều đếm trên cùng một bảng SearchEngineApiLog với cùng tên việc . Dựng sổ thứ hai là cách chắc chắn nhất để hai bên cùng tưởng mình còn hạn mức rồi cùng vượt trần của Google.

Kiểm ngay trạng thái index của một URL đã có trong hàng tồn kho. URL lạ bị từ chối trước khi có bất kỳ lời gọi nào đi ra.

Nộp lại tệp sitemap đang cấu hình. Không nhận tham số — địa chỉ tệp luôn lấy từ Search.Google.SitemapUrl, để không ai nộp hộ Google một tệp của miền khác.

Thử kết nối bằng một lời gọi đọc nhẹ nhất, để người vận hành biết khoá và quyền đã đúng chưa.

Endpoint ghi vào nhật ký cho lượt kiểm URL — giữ đúng chuỗi mà đang ghi, để lọc nhật ký theo endpoint là ra cả lượt tự động lẫn lượt bấm tay.

Câu đánh dấu lượt bấm tay trong nhật ký. Tên việc (Action) bắt buộc phải giống job vì nó là khoá của sổ đếm hạn mức; nếu đánh dấu lượt bấm tay bằng một tên việc mới thì nó không còn bị trừ vào hạn mức nữa. Nên chỗ để phân biệt "ai gây ra lời gọi này" là phần tóm tắt, không phải tên việc.

Kiểm ngay một URL rồi trả về đúng dòng mà bảng chính đang hiển thị, để giao diện thay dòng tại chỗ thay vì nạp lại cả trang.

Bốn cửa phải qua trước khi có lời gọi nào đi ra, theo đúng thứ tự rẻ tiền trước: (1) URL không rỗng; (2) công tắc đọc đang bật; (3) URL có thật trong bảng SearchUrl; (4) hạn mức hôm nay còn chỗ. Cửa thứ ba làm hai việc cùng lúc: nó chặn SSRF (không ai gửi được một địa chỉ tự do cho máy chủ gọi hộ) và chặn đường đốt hạn mức (danh sách kiểm được là hữu hạn và do chính website sinh ra, không do người bấm gõ vào). Không lọc theo InSitemap dù job có lọc: một URL vừa rơi khỏi sitemap chính là URL người vận hành cần kiểm tay nhất — để biết Google đã bỏ nó ra chưa. Job thì khác, job chia hạn mức cho hàng trăm URL nên phải ưu tiên những trang còn đang phục vụ. Trả số hạn mức trong mọi nhánh, kể cả nhánh từ chối: người bấm phải thấy ngay còn bao nhiêu lượt, nếu không họ sẽ bấm lại vài lần nữa để thử.

Ghi đè trạng thái index hiện tại và ghi thêm một dòng lịch sử chỉ khi CoverageState hoặc Verdict đổi.

Cố ý lặp lại nguyên luật của SearchIndexInspectJob.ApplyStatus: một lượt bấm tay và một lượt tự động phải để lại dữ liệu giống hệt nhau, nếu không thì đường xu hướng dựng từ SearchIndexStatusHistory sẽ gãy đúng ở chỗ có người bấm tay. Luật ấy đang nằm trong một hàm private của job nên không gọi lại được — sửa một bên thì phải sửa cả hai bên. true nếu trạng thái vừa đổi.

Nộp lại tệp sitemap đang cấu hình và đóng mốc "lần nộp gần nhất".

Không nhận tham số là một ràng buộc an toàn, không phải sự tiện tay. Nhận địa chỉ tệp từ người bấm nghĩa là cho phép nộp một tệp bất kỳ dưới danh nghĩa property của LADA — Google sẽ đi tải đúng địa chỉ đó. Địa chỉ tệp chỉ đổi được bằng cách sửa khoá AppConfig, tức là qua một migration. Từ chối khi công tắc ghi còn tắt. Client cũng tự canh công tắc, nhưng chặn ngay từ đây thì người bấm nhận được đúng câu giải thích (BlockReason) thay vì một lỗi kỹ thuật.

Hỏi Google trạng thái tệp sitemap rồi ghi đè dòng trạng thái — cùng việc mà làm ở đầu mỗi lượt chạy.

Lỗi ở đây không làm hỏng lượt nộp. Tệp đã nộp xong rồi; đọc lại chỉ để màn hình có số thật. Đọc không được thì dòng trạng thái giữ RawJson rỗng, và màn hình sẽ nói "chưa đọc được trạng thái từ Google" thay vì in số 0 như thể đã đo.

Đóng mốc "LADA vừa nộp" lên dòng trạng thái tệp sitemap — giống hệt việc làm sau một lượt nộp thành công.

Thiếu bước này thì màn hình vẫn hiện mốc nộp cũ ngay sau khi vừa bấm nộp, và người vận hành sẽ bấm lại lần nữa vì tưởng lần đầu không ăn.

Thử kết nối tới công cụ tìm kiếm và ghi lại kết quả vào nhật ký lời gọi.

Chặn trước bằng công tắc đọc để không ghi một dòng nhật ký cho lời gọi chưa hề đi ra: client cũng trả về BlockReason trong trường hợp này, nhưng từ ngoài nhìn vào thì "bị công tắc chặn" và "gọi rồi nhưng hỏng" giống nhau, mà sổ nhật ký phải phân biệt được. Ghi dưới tên việc chứ không phải một tên mới: lời gọi này đúng là một lượt đọc danh sách sitemap. Quan trọng hơn, nó không được ghi dưới tên việc kiểm URL, vì như vậy mỗi lần thử kết nối lại ăn mất một suất trong hạn mức kiểm URL của ngày hôm đó. Dòng nhật ký không có mã HTTP và thời gian gọi: TestConnectionAsync cố ý chỉ trả được/không được kèm lý do, vì câu trả lời của nó hiện thẳng lên giao diện quản trị và không được để lộ chi tiết của khoá hay của service account.

Đếm lại sổ hạn mức rồi điền vào kết quả.

Đếm lại sau khi lưu chứ không cộng thêm 1 vào số đã đọc: job theo lịch có thể đang chạy song song và cũng đang tiêu vào cùng sổ ấy, nên con số duy nhất đáng tin là con số vừa đọc từ DB.

Điền số hạn mức đã biết, kẹp phần còn lại về tối thiểu 0 để giao diện không hiện số âm.

Cắt một chuỗi về đúng độ dài cột; null giữ nguyên là null.

Đọc số cho dashboard đồng bộ công cụ tìm kiếm. Chỉ đọc. Mọi con số ở đây lấy từ 5 bảng đã có sẵn trong DB, không lời gọi nào đi ra ngoài — tách hẳn khỏi service nút-bấm-tay để nhìn danh sách phụ thuộc là biết ngay cái nào có thể tiêu hạn mức của Google.

Bảng chính: một dòng cho mỗi URL trong hàng tồn kho kèm trạng thái index.

Các con số tổng, bảng đếm theo nhóm và tình trạng công tắc/hạn mức.

Trạng thái tệp sitemap; trả HasData = false khi chưa đo lần nào.

Những lời gọi gần nhất đã đi ra công cụ tìm kiếm, mới nhất trước.

Một dòng của bảng chính theo khoá SearchUrl — dùng để trả trạng thái mới ngay sau một lượt "kiểm ngay", bằng đúng phép chiếu của bảng.

Dùng thẳng LadaDbContext chứ không qua IRepository. Mọi câu hỏi của màn hình này đều là phép nối SearchUrl với SearchIndexStatus — một bảng trung lập với công cụ tìm kiếm nối với một bảng theo từng công cụ. Không có entity nào là "chủ" của dòng kết quả, nên repository theo một entity chỉ thêm một lớp trung gian mà không che giấu được gì. Cùng lý do với SearchIndexInspectJob.

Kết luận "đã lập chỉ mục" của Google — mã ổn định duy nhất được phép dùng để đếm.

Cách Google diễn đạt "trang có lệnh chuyển hướng" trong CoverageState — bản tiếng Việt, là thứ property của LADA đang trả về (đo thật 2026-09-15).

Đây là phép dò theo chuỗi, và phải biết là mình đang làm thế. urlInspection không có trường riêng nào cho việc này; CoverageState là câu hiển thị trên giao diện Search Console nên nó đổi theo ngôn ngữ của property và Google có thể đổi cách diễn đạt mà không báo trước. Giữ cụm ngắn nhất còn mang nghĩa để cách diễn đạt đổi vài chữ vẫn khớp.

Cụm tương ứng khi property đổi sang tiếng Anh ("Page with redirect").

Số dòng nhật ký trả về khi chỗ gọi không nói rõ.

Trần số dòng nhật ký một lượt — bảng nhật ký để soi vài chục dòng gần nhất, không phải để tải cả sổ.

Những cột được phép sắp xếp. Phải là danh sách trắng, không phải kiểm tra qua loa. ToSmartTableResultAsync sắp xếp bằng OrderByName — phản chiếu theo tên property, phân biệt hoa thường, và ném ArgumentException khi không tìm thấy. Một khoá sort lạ (hay chỉ sai một chữ hoa) từ giao diện sẽ thành lỗi 500. Nguy hiểm hơn: GroupName, Clicks, Impressions có tồn tại trên DTO nhưng không nằm trong phép chiếu SQL, nên phản chiếu tìm thấy chúng rồi EF mới vỡ lúc chạy. Khoá ngoài danh sách được đưa về sắp mặc định.

Cố ý không đi qua AutoMapper .ToItem() như quy ước chung của tầng service (skill service-search-patterns §2). Một dòng ở đây là phép LEFT JOIN hai bảng chứ không phải một entity, nên không có Entity → Item nào để ánh xạ. Quan trọng hơn: ToSmartTableResultAsync sắp xếp bằng OrderByName trên chính kiểu đang truy vấn, nên khoá sắp xếp mặc định ChangedNotRecrawled — vốn là một biểu thức, không phải cột — chỉ tồn tại nếu phép chiếu ra SearchUrlStatusItem xảy ra trước lúc sắp xếp, tức là ngay trong IQueryable. Ánh xạ sau khi lấy dữ liệu về thì cột đó không có gì để sắp. Bộ lọc cũng đặt trên phép chiếu chứ không trên hai bảng gốc, để công thức ChangedNotRecrawled chỉ được viết đúng một lần: viết lại nó ở tầng lọc là mở đường cho con số trong bảng lệch với con số trên thẻ tổng.

Đếm, sắp xếp và cắt trang — có khoá phụ cố định là Url.

Vì sao không dùng thẳng ToSmartTableResultAsync: nó sắp xếp bằng đúng một khoá rồi OFFSET/FETCH từng trang. Khoá mặc định ở đây là một cờ bool, nên trên 148 dòng thì khoảng 138 dòng có khoá bằng nhau — SQL Server không hứa thứ tự giữa những dòng bằng khoá, và mỗi trang là một lượt sắp xếp riêng. Hậu quả: một URL có thể hiện ở cả trang 3 lẫn trang 4, hoặc không hiện ở trang nào, trong khi tổng số vẫn báo đủ. Người vận hành lật trang tìm một URL có thể không bao giờ thấy nó. Url là khoá phụ đúng nghĩa: nó có ràng buộc duy nhất trên bảng nên mọi dòng đều tách được, và nó cũng là thứ người đọc dùng để định vị. Cùng một luật mà SearchNotIndexedProvider đã áp cho widget.

Sắp xếp theo tên cột đã qua danh sách trắng.

Viết tay từng nhánh thay vì phản chiếu theo tên: mọi cột sắp được đều phải là cột có thật trong phép chiếu SQL. Phản chiếu thì GroupName, Clicks, Impressions — những property chỉ tồn tại trên DTO — vẫn tìm thấy được, rồi vỡ lúc chạy chứ không phải lúc dịch. Đếm trong bộ nhớ trên chính phép chiếu của bảng, thay vì viết một loạt câu COUNT riêng. Lý do là tính nhất quán: con số trên thẻ tổng và con số người dùng đếm được khi bấm lọc trong bảng phải luôn bằng nhau, mà cách chắc chắn nhất để chúng bằng nhau là chúng dùng đúng một công thức. Hàng tồn kho cỡ 150 dòng (đo 15/09/2026) nên một lượt đi DB rẻ hơn chín lượt COUNT; nếu về sau vượt vài chục nghìn dòng thì chuyển phần này sang GROUP BY phía SQL. Đếm theo Verdict, không đếm theo CoverageState. CoverageState là câu Google viết theo ngôn ngữ của property ("Đã được gửi và lập chỉ mục"); đổi ngôn ngữ là mọi con số đếm theo nó vỡ im lặng. vẫn có mặt nhưng chỉ để trả lời "vì sao" và để người dùng bấm lọc theo đúng câu chữ họ nhìn thấy trong Search Console. Chưa đo lần nào là trạng thái hợp lệ, không phải lỗi — bảng SearchSitemapStatus đang rỗng trên dev vì job đọc sitemap chưa chạy lần nào ngoài test. Khi đó vẫn trả SitemapUrl đọc từ cấu hình kèm HasData = false: màn hình nói được "đang theo dõi tệp nào, chưa đo" thay vì bày ra 0 lỗi / 0 cảnh báo như thể đã đo và mọi thứ đều tốt. Bản ghi được lọc theo đúng tệp đang cấu hình. Đổi Search.Google.SitemapUrl sang tệp khác thì số đo của tệp cũ không còn nói gì về tệp mới, nên thà trả "chưa đo" còn hơn trả một con số đúng của một câu hỏi khác.

Phép chiếu dùng chung của cả màn hình: LEFT JOIN hàng tồn kho với trạng thái index của một công cụ tìm kiếm, ra thẳng . Phải là LEFT JOIN. URL chưa từng được kiểm vẫn phải xuất hiện — "không biết gì về trang này" là tình trạng đáng lo hơn "biết là chưa index", và INNER JOIN sẽ giấu đúng nhóm đó đi. URL đã rơi khỏi sitemap vẫn hiện. Bộ lọc chỉ bỏ dòng xoá mềm, không bỏ dòng InSitemap = false: một trang biến mất khỏi sitemap có thể là cố ý, cũng có thể là lỗi sinh sitemap (sự cố 15/09/2026 mất 13 URL danh mục) — giấu nó đi là bỏ mất đúng loại sự cố mà bảng này sinh ra để phát hiện.

Điền hai cờ đối chiếu ghép — chúng cần đọc hai cờ gốc nên không tính được trong phép chiếu.

giữ null khi chưa hỏi Google về URL đó: "chưa biết Google nghĩ gì" không được phép trông giống "đã kiểm và không có vấn đề".

Lọc theo nhóm tình trạng mà người dùng bấm trên đầu bảng. Mọi vế đều dựa trên Verdict — mã ổn định — chứ không dựa trên CoverageState. Riêng "error" gom cả Verdict = FAIL lẫn các PageFetchState chứa ERROR (SERVER_ERROR, INTERNAL_ERROR...): với người vận hành thì "trang lỗi" là một nhóm việc phải sửa, còn việc lỗi nằm ở kết luận tổng hay ở lượt tải trang là chi tiết kỹ thuật họ không cần phân biệt để bắt đầu.

Đưa khoá sắp xếp của giao diện về đúng tên property trong danh sách trắng; null nghĩa là "dùng sắp xếp mặc định".

Ép mã công cụ tìm kiếm về một giá trị có thật. Mã lạ rơi về Google thay vì ném lỗi: giao diện chỉ có Google để chọn, nên một giá trị lạ là lỗi gõ chứ không phải ý định — và trả về bảng rỗng của một công cụ không tồn tại thì khó hiểu hơn nhiều so với trả về đúng thứ người dùng đang xem.

Kết quả một lượt kiểm URL, đã rút từ phản hồi của công cụ tìm kiếm về đúng những trường bảng SearchIndexStatus cần.

Công cụ tìm kiếm có thấy URL này trong tệp sitemap đang theo dõi hay không.

Phản hồi thô, đã cắt ngắn.

Trạng thái một tệp sitemap theo lời công cụ tìm kiếm.

Mốc nộp gần nhất theo ghi nhận của công cụ tìm kiếm — bất kể ai nộp.

Lần công cụ tìm kiếm thật sự tải tệp về đọc.

Số URL công cụ tìm kiếm đếm được trong tệp.

Kết quả một lời gọi ra công cụ tìm kiếm: dữ liệu, mã HTTP và thời gian — ba thứ cần để vừa dùng kết quả vừa ghi nhật ký mà không phải gọi hai lần.

Kiểu dữ liệu trả về khi thành công.

Lời gọi bị chặn bởi công tắc nên chưa hề đi ra ngoài. Khác hẳn thất bại: không tốn hạn mức, không phải lỗi, và là trạng thái bình thường cho tới khi người vận hành bật công tắc.

Công cụ tìm kiếm trả 429 — hạn mức đã hết. Vì sao là một ngoại lệ riêng chứ không phải một mã lỗi trong kết quả. Mọi lỗi khác chỉ làm hỏng đúng một URL và job nên đi tiếp; 429 làm hỏng mọi URL còn lại, nên job phải dừng hẳn vòng lặp. Kiểu riêng buộc chỗ gọi phải xử lý khác đi, thay vì trông chờ ai đó nhớ so mã 429.

Kết quả một lượt dựng lại hàng tồn kho URL.

Số URL đọc được từ tệp sitemap (sau khi bỏ trùng).

Số dòng URL mới thêm.

Số dòng được cập nhật (mốc sitemap, nhóm, liên kết nội dung).

Số URL vừa rơi khỏi sitemap ở lượt này.

Số URL đã từng rơi khỏi sitemap và nay quay lại.

Số URL trùng nhau trong chính tệp sitemap — lớn hơn 0 là một lỗi cần sửa.

Số URL không khớp được với bản ghi nội dung nào.

Dựng lại hàng tồn kho URL từ chính tệp sitemap.xml mà công cụ tìm kiếm đọc.

Tải sitemap, đối chiếu với bảng SearchUrl rồi ghi lại chênh lệch.

Cài đặt . Nguồn là tệp sitemap công khai, không phải database. Việc này không gọi tới công cụ tìm kiếm nào nên chạy được cả khi mọi công tắc còn tắt — và đó là chủ ý: hàng tồn kho phải dựng xong, đọc được, đối chiếu được bằng mắt trước khi có lời gọi đầu tiên đi ra ngoài. Vì sao khớp ngược về UrlRecord bằng slug. Phần lớn URL của website là slug một đoạn (/gui-hang-lien-tinh) nên không suy ra được loại nội dung từ hình dạng đường dẫn. Khớp slug cho cả ba thứ cùng lúc: nhóm để thống kê, khoá thực thể để mở màn sửa, và khoá UrlRecord để nối sang mốc ContentChangedAt của giai đoạn trước. URL biến mất không bị xoá mà được đánh RemovedAt. Một trang rơi khỏi sitemap có thể là cố ý, cũng có thể là hỏng — sự cố 15/09/2026 làm 13 URL danh mục biến mất vì DB thiếu một cột. Xoá dòng đi là mất luôn dấu vết của đúng loại sự cố mà bảng này sinh ra để phát hiện.

Tên named client dùng để tải sitemap — tách khỏi client gọi Google.

Đọc tệp sitemap thành danh sách URL. URL trùng chỉ lấy bản đầu — bảng SearchUrl có chỉ số duy nhất nên trùng sẽ làm hỏng cả lượt ghi, mà đó lại đúng là tình trạng sitemap production đang có (3 URL trùng, tính tới 15/09/2026).

Độ dài tối đa của cột SearchUrl.Url và SearchUrl.Path.

Gốc của một URL: scheme + host + cổng, hoặc chuỗi rỗng nếu không phân giải được.

URL có cùng gốc với tệp sitemap không. Gốc rỗng (không phân giải được địa chỉ sitemap) thì coi như không xét URL nào — thà bỏ sót một URL đã rơi còn hơn đánh dấu nhầm cả bảng.

Đọc priority bằng . Bắt buộc: máy chạy culture Việt đọc "0.8" theo culture máy sẽ ra 8 — đúng loại bẫy đã cắn ở giai đoạn trước, chỉ khác chiều (ở đó là chỗ ghi).

Dựng bảng tra từ slug về bản ghi nội dung. Nạp một lần cho cả lượt: mỗi URL tra riêng sẽ là hơn 150 lượt truy vấn cho một việc chạy đêm.

Khớp một đường dẫn về bản ghi nội dung đứng sau nó.

Đọc số liệu hiệu suất tìm kiếm cho màn hình. Không gọi ra Google lần nào — mọi con số ở đây đã nằm sẵn trong SearchMetricDaily. Tách khỏi (đọc trạng thái index) vì hai thứ trả lời hai câu hỏi khác nhau — "Google đã thấy trang của mình chưa" và "người ta có bấm vào không" — và vì từ danh sách DI phải thấy ngay lớp nào có thể phát sinh lời gọi ra ngoài.

Các con số tổng hợp đầu tab, kèm câu trả lời cho "vì sao đang là 0".

Xếp hạng trang theo lượt bấm trong khoảng ngày.

Xếp hạng truy vấn theo lượt bấm trong khoảng ngày.

Các truy vấn đưa người dùng tới đúng một trang.

Độ trễ chốt số của Google, tính bằng ngày. Đo 2026-09-16: ngày final gần nhất là hôm nay − 3. Dùng để phân biệt "chưa kéo về" với "Google chưa chốt" — hai nguyên nhân cùng cho ra một bảng trống nhưng đòi hai phản ứng khác nhau.

Trần số dòng trả về một lượt, chống ?take=999999 kéo cả bảng.

Trần số ngày hỏi được một lượt — 16 tháng, đúng bằng phần Google giữ.

Gộp một mức theo chiều của nó rồi xếp hạng. Gộp theo UrlNormalized chứ không theo Url. Đo 2026-09-16: 31 dòng mang neo #… thuộc chỉ 9 trang gốc — xếp hạng theo chuỗi gốc sẽ chia một trang thành năm dòng con và đẩy nó khỏi bảng xếp hạng dù tổng lượt bấm của nó cao.

Khoảng ngày để đọc: lùi ngày từ ngày có số mới nhất, không phải từ hôm nay — xem lý do ở .

Dựng một dòng, tính lại CTR và vị trí từ tổng. Đây là chỗ duy nhất làm phép đó — để không có hai công thức trong hệ thống.

Cấu hình đồng bộ công cụ tìm kiếm, đã đọc và đã ép kiểu từ AppConfig. Đây là luật "khi nào được phép gọi ra công cụ tìm kiếm", cố ý gom về đúng một chỗ — cùng lý do với ContentFingerprint.Stamp ở giai đoạn trước: mọi đường gọi (ba job, nút bấm tay trên dashboard sau này) phải cư xử giống hệt nhau, và khi cần đổi luật thì chỉ có một chỗ để sửa. Thiếu khoá thì mặc định là TẮT. Một khoá bị xoá nhầm, một DB chưa chạy migration, một lỗi đọc cache — mọi trường hợp "không biết" đều phải dẫn tới "không gọi". Chiều ngược lại (không đọc được thì cứ gọi) là cách hỏng nguy hiểm: nó đốt hạn mức và có thể báo cho Google thứ không thật.

Công tắc ĐỌC: kiểm tra URL, đọc trạng thái sitemap.

Công tắc GHI: nộp sitemap. Tách khỏi vì hậu quả khác hẳn.

Định danh property: sc-domain:ladaexpress.vn (Domain) hoặc https://ladaexpress.vn/ (URL-prefix). Sai dạng thì Google trả 403 không kèm lý do.

Tệp sitemap dùng để dựng hàng tồn kho và để nộp.

Trần số lượt kiểm URL mỗi ngày dành cho job.

Số ngày giữ nhật ký lời gọi.

Công tắc thứ ba: báo chủ động một URL cho Google qua Indexing API. Tách khỏi vì đây là loại lời gọi ghi nhắm vào từng trang, có hạn mức riêng (200 lượt/ngày) và có luật dùng riêng của Google: chỉ hợp lệ cho trang mang dữ liệu có cấu trúc JobPosting. Nộp sitemap sai thì cùng lắm Google đọc lại một tệp; báo sai một URL là một tín hiệu sai nhắm đúng vào một trang.

Trần số URL được báo chủ động mỗi ngày.

Ngưỡng lượt hiển thị tối thiểu để giữ một dòng ở mức "trang × truy vấn". Mặc định 1 — tức là không lọc gì. Kế hoạch §3.6 từng đề xuất 5, nhưng Việc 0 ngày 2026-09-16 đo ra ngưỡng ấy vứt mất 30,3 % số lượt bấm (10 dòng có lượt bấm thật mà lượt hiển thị dưới 5), trong khi nỗi lo "bảng phình" không thành sự thật: mức mịn nhất chỉ sinh trung bình 127 dòng/ngày. Vẫn để thành khoá để nâng được khi website lớn lên, mà không phải deploy.

Độ rộng cửa sổ trượt (số ngày) của job kéo số liệu hằng ngày: mỗi lượt kéo lại [T-N, T-1]. Các lượt chạy cố ý chồng lên nhau: Google còn sửa số của vài ngày gần nhất sau khi chốt, nên kéo một lần rồi thôi là giữ lại một con số tạm thời. Khoá upsert làm cho việc kéo lại an toàn.

Số tháng lượt kéo bù lịch sử đi ngược về. 17 chứ không phải 16, dù Google nói là "16 tháng". Đo thật 2026-09-16: ngày sớm nhất còn số là 2025-05-04 — tức 16,4 tháng lịch. Đặt 16 thì lượt kéo bù dừng ở 2025-05-16 và bỏ lại 12 ngày cũ nhất, đúng phần dễ mất nhất vì Google xoá chúng trước tiên. Đã cắn thật một lần ở phiên GĐ F trước khi sửa. Đặt cao hơn mức cần thì job tự dừng sau hai lô liền nhau không có dòng nào, nên phần thừa nhiều nhất là hai lời gọi.

Số ngày giữ dữ liệu lượt bot trong bảng BotVisitDaily; job dọn xoá cứng dòng cũ hơn. Ngược hẳn với số liệu hiệu suất tìm kiếm. Bảng kia càng cũ càng quý — Google xoá bản gốc sau 16 tháng nên không lấy lại được. Lượt bot thì hết giá trị nhanh: câu hỏi luôn là "tháng này bot nào đang ghé", không phải "năm ngoái ghé bao nhiêu". Mặc định 90 ngày, đủ để so một quý với quý trước.

Website có đang đếm lượt bot không (Search.BotVisit.Enabled). Mặc định BẬT — khác mọi công tắc khác của miền này, và có chủ đích: những công tắc kia gác các lời gọi ra Google, còn việc đếm lượt bot không gọi ra ngoài lần nào. Cái giá của việc để tắt thì rất thật: deploy xong không ai nhớ bật, rồi tới lúc cần số thì không có đường cơ sở nào để so. Lưu ý: khoá này do website đọc để quyết định có ghi hay không. API đọc nó chỉ để màn hình giải thích được vì sao bảng đang rỗng.

Được phép gọi lời gọi ĐỌC hay không. Ngoài công tắc còn đòi có — không có định danh property thì lời gọi chắc chắn trả 403, gọi đi chỉ để nhận lỗi là vô ích.

Được phép gọi lời gọi GHI hay không. Đòi cả hai công tắc: bật riêng công tắc ghi mà quên công tắc đọc là một trạng thái vô nghĩa, và cho phép nó sẽ tạo ra đường gửi dữ liệu đi mà không đường nào đọc lại được kết quả.

Được phép báo chủ động một URL hay không. Đòi cả lẫn , cùng lý do với : bật đường ghi mà tắt đường đọc là một trạng thái không ai kiểm được kết quả. Cố ý không đòi — nộp sitemap và báo từng URL là hai việc khác nhau, buộc chúng đi kèm sẽ làm người vận hành không bật được việc này mà không bật việc kia. Cũng không đòi : Indexing API nhận thẳng URL của trang, không cần định danh property. Hàng rào tương ứng của nó là "URL phải thuộc chính website này", và hàng rào ấy đặt ở lúc xếp hàng đợi chứ không ở đây.

Lý do khi công tắc đọc đang tắt — dùng chung cho cả hai câu giải thích bên dưới, để đổi chữ một nơi không làm hai màn hình nói hai giọng về cùng một việc.

Câu giải thích vì sao chưa được phép báo chủ động — hiện trên nhật ký chạy thử, nên phải nói đúng khoá nào đang chặn thay vì một câu chung chung.

Câu giải thích vì sao chưa được phép gọi — để ghi log và hiện lên dashboard.

Đọc từ AppConfig.

Đọc cấu hình hiện hành. Giá trị đi qua cache AppConfig nên đổi công tắc có độ trễ tối đa 1 giờ.

Tên các khoá AppConfig. Đặt hằng để không có chuỗi rời rạc nào lệch chính tả.

Đọc một khoá kiểu bool. Khoá thiếu, rỗng hay ghi sai chính tả đều cho false — "không đọc được" phải dẫn tới "không gọi".

Đọc một khoá kiểu bool mặc định BẬT: chỉ giá trị đọc được và bằng false mới cho tắt. Dùng cho công tắc không gác lời gọi ra ngoài — xem .

Đọc một khoá kiểu số. Khoá thiếu hay không phải số thì lấy mặc định; số âm bị kéo về 0 để không có hạn mức âm biến thành vòng lặp vô tận ở chỗ so sánh.

Lấy thông tin CallPath theo Id.

Id của CallPath. Thông tin CallPath.

Tạo mới CallPath.

Thông tin CallPath cần tạo. Kết quả của thao tác.

Xóa CallPath.

Id của CallPath cần xóa. Kết quả của thao tác.

Tìm kiếm CallPath theo điều kiện lọc và phân trang.

Tham số phân trang và điều kiện lọc. Kết quả phân trang chứa danh sách CallPath.

Lấy tất cả CallPath theo version/build. Nếu không truyền, lấy danh sách từ phiên bản mặc định.

Số phiên bản (optional) Số build (optional)

Copy tất cả CallPath từ một version sang một version khác.

Id của CallPathVersion nguồn. Id của CallPathVersion đích. Id người thực hiện. Tên người thực hiện. Kết quả của thao tác.

Triển khai dịch vụ quản lý CallPath.

Copy tất cả CallPath từ một version sang một version khác.

Lấy thông tin CallPathVersion theo Id.

Tạo mới hoặc cập nhật CallPathVersion.

Xóa CallPathVersion.

Tìm kiếm CallPathVersion theo điều kiện lọc và phân trang.

Lấy tất cả CallPathVersion (dùng cho dropdown).

Triển khai dịch vụ quản lý CallPathVersion.

Đọc trạng thái hàng đợi Hangfire (tác vụ nền) để hiển thị trên SPA quản trị, thay cho dashboard /hangfire vốn không dùng được với JWT của SPA.

Số liệu tổng quan theo trạng thái + server + queue.

Danh sách tác vụ định kỳ: mọi job trong lịch Hangfire gộp với danh mục RecurringJobCatalog (job trong danh mục nhưng chưa đăng ký / đã tạm dừng vẫn hiện để bấm Đăng ký).

Kích hoạt chạy ngay một tác vụ định kỳ, không đợi tới lịch.

Tạm dừng: gỡ job khỏi lịch Hangfire và ghi cờ để khởi động lại API không tự đăng ký lại. Chỉ áp dụng cho job trong danh mục (có cách đăng ký lại).

Đăng ký (lại) một job trong danh mục với lịch mặc định, gỡ cờ tạm dừng nếu có.

Xoá hẳn một job KHÔNG nằm trong danh mục khỏi lịch Hangfire (job mồ côi do code cũ để lại). Job trong danh mục thì dùng Tạm dừng — xoá xong khởi động lại API nó sẽ sống dậy.

Liệt kê job theo trạng thái, phân trang bằng from/count.

Chi tiết một job kèm lịch sử trạng thái; null nếu không tìm thấy.

Đưa job (thường là job thất bại) trở lại queue để chạy lại.

Xoá một job (chuyển sang trạng thái Deleted, không chạy nữa).

Các trạng thái có API liệt kê. "Enqueued" gom mọi queue.

Hangfire lưu mọi mốc thời gian theo UTC; trả về giờ Việt Nam cho SPA hiển thị thẳng. Cùng múi giờ mà GeneralRegister dùng khi đăng ký RecurringJob.

Tên hiển thị "Lớp.PhươngThức"; khi Hangfire không nạp được kiểu (đã đổi tên/xoá class) thì báo lý do.

Đọc/ghi cấu hình màn hình chặn truy cập bằng điện thoại của app khách hàng (Lada.App). Dữ liệu nằm rải ở nhiều khoá MobileApp.* trong bảng AppConfig (DB dùng chung với Lada.AppBackEnd).

Lấy cấu hình hiện tại; khoá chưa có thì trả giá trị mặc định.

Lưu cấu hình. Trường bỏ trống vẫn được ghi (để xoá giá trị cũ).

Cài đặt . Ghi thẳng qua repository thay vì IAppConfigManagementService.CreateOrUpdate vì hàm đó từ chối Value rỗng — ở đây các trường như ảnh QR hay lời nhắn được phép để trống, và phải ghi được chuỗi rỗng thì quản trị mới xoá được giá trị đã đặt trước đó.

Khoá AppConfig — trùng với hằng số bên Lada.AppBackEnd, đổi thì phải đổi cả hai nơi.

Ghi một khoá AppConfig và đồng bộ lại cache của khoá đó.

Bảng đầu vào của phép tính trạng thái sẵn sàng — mọi thứ cần biết về một người, đã đọc sẵn khỏi database.

Tài khoản đã nghỉ việc (User.IsDeleted) hoặc không tồn tại

Quản lý tạm ngưng chia khách đến khi nào (ChatAgentPresence.SuspendedUntil). null = không bị ngưng.

Trạng thái người này tự khai (ChatAgentPresence.SelfStatus). Không có dòng presence thì là .

Trạng thái tự khai có hạn đến khi nào (ChatAgentPresence.UntilTime).

Luật "sale này có sẵn sàng nhận khách mới lúc này không" — hàm thuần, viết đúng một lần, không chạm database. Cùng khuôn với ChatRealtimeAudience.Resolve của giai đoạn A: bảng đầu vào → kết luận, nên kiểm được bằng bảng ca thẳng thay vì phải dựng cả kho dữ liệu giả. Đây cũng là điều kiện lọc số 2 của máy phân phối §3.3, nên giai đoạn D sẽ đọc thẳng hàm này.

Trạng thái hiệu lực của một người tại một thời điểm.

Thứ tự ưu tiên, cao thắng thấp — mỗi bậc có lý do riêng, không phải xếp theo cảm tính: — người không còn làm việc thì không có trạng thái nào khác đáng bàn. — quyết định của quản lý, sale không tự gỡ được, nên nó phải thắng mọi thứ sale tự khai. — đứng TRÊN "ngoài giờ làm việc" có chủ ý: một lời khai nghỉ nhiều ngày mang nhiều thông tin hơn hẳn "bây giờ là 8 giờ tối". Xếp ngược lại thì người nghỉ cả tuần hiện là "ngoài giờ làm" mỗi tối, và bảng thời lượng của giai đoạn F mất luôn lý do thật. — đứng TRÊN Bận / Ra ngoài, vì đây là nguồn chính (xem ) còn lời tự khai ngắn hạn là nguồn yếu nhất theo số đo C0. / — lời tự khai còn hạn. — mặc định. Quyết định fail-open, và vì sao. Prompt giai đoạn C bắt phải chọn có ý thức giữa fail-open và fail-closed rồi viết lý do vào code. Ở đây chọn fail-open: mọi thứ không đọc được, không có, hoặc vô lý đều rơi về . Ba lý do: "Không có dòng" là trạng thái BÌNH THƯỜNG, không phải trạng thái lỗi. Số đo C0 cho thấy chưa sale nào có lý do dùng menu đổi trạng thái, nên tuyệt đại đa số người sẽ không bao giờ có dòng ChatAgentPresence. Fail-closed ở đây nghĩa là cả đội vĩnh viễn không nhận được khách — chính xác cái bẫy PP-12 đã ghi về chấm công. Hai hướng hỏng không cân nhau. Fail-closed khi một truy vấn hỏng làm cả đội ngừng nhận khách và khách ngồi chờ — một sự cố nhìn thấy được từ phía khách hàng. Fail-open thì tệ nhất là chia khách cho người đang bận, và người đó bấm "Nhả" là xong. Đây KHÔNG phải hàng rào quyền xem. Hàng rào (§3.7) fail-closed, và điều đó không đổi. Hàm này chỉ quyết định chia việc; đọc nhầm nó thành một quyết định bảo mật rồi siết theo là siết nhầm chỗ. Ngoại lệ duy nhất của fail-open là : người gọi phải đặt cờ này khi không tra được tài khoản, vì một mã nhân viên không tồn tại thì fail-open nghĩa là giao khách cho người không có thật. Bảng đầu vào đã đọc sẵn khỏi database Thời điểm cần biết. Truyền vào chứ không hỏi đồng hồ — repo không có abstraction đồng hồ. Cửa sổ giờ làm việc đã dựng từ cấu hình

Chỉ trạng thái mới nhận khách mới (§3.5). Mọi trạng thái khác không miễn cho sale nghĩa vụ trả lời khách đang cầm — bận nghĩa là "không nhận thêm", không phải "được im lặng".

Giá trị này có được phép lưu vào ChatAgentPresence.SelfStatus không — tức người dùng (hoặc quản lý) có khai được nó không. không nằm ở đây vì nó là SuspendedUntil; và không nằm ở đây vì chúng suy ra lúc chạy.

Giá trị này có được phép ghi vào ChatAgentPresenceLog.Status không — tức nó là trạng thái khai báo (1–5) chứ không phải trạng thái suy ra (6–7).

Trả lời câu hỏi "sale này có nhận khách mới lúc này không" — đầu vào thứ hai của máy phân phối (§3.3 điều kiện lọc số 2, §3.5). Gộp ba nguồn còn dùng được sau số đo C0: tài khoản còn làm việc không, quản lý có tạm ngưng không, và người đó tự khai gì — cộng với giờ làm việc riêng của từng người (KC-18, 2026-09-27; trước đó là một cấu hình chung áp cho cả đội). Không đọc LeaveRequest (chủ dự án chốt 2026-08-29: trạng thái "Nghỉ" ở đây là trạng thái hỗ trợ tự khai, không liên quan nghỉ phép nhân sự — sổ nợ PP-11) và không đọc Attendance (chỉ 20/40 sale chấm công, dùng nó là một nửa đội vĩnh viễn "ngoài ca" mà không ai hiểu vì sao — sổ nợ PP-12). Toàn bộ luật nằm ở hàm thuần ; lớp này chỉ đi lấy dữ liệu cho nó. Nhờ tách như thế, mọi ca test về thứ tự ưu tiên chạy trên bảng ca thẳng, không cần kho dữ liệu giả.

Trạng thái hiệu lực của một người tại một thời điểm.

Mã nhân viên (User.Id) Thời điểm cần biết. Truyền vào chứ không hỏi đồng hồ bên trong: repo không có abstraction thời gian, nên đây là cách duy nhất để test được luật hết hạn.

Trạng thái hiệu lực của một loạt người, ba lần đọc cho cả lô chứ không phải ba lần đọc mỗi người: cấu hình chung (chỉ còn lấy múi giờ), tài khoản còn làm việc, và dòng ChatAgentPresence. Giai đoạn D sẽ hỏi "ai trong kênh này đang sẵn sàng" cho mỗi tin inbound, mà một kênh có thể có hàng chục sale — gọi bản một-người trong vòng lặp là nhân số truy vấn lên đúng bằng số sale, trên đường chạy nóng nhất của cả hệ thống. Giờ làm riêng (KC-18) không tốn truy vấn thứ tư: bảy cột giờ nằm ngay trên dòng presence đã nạp, nên giờ của từng người dựng lại từ chính các dòng ấy (). Đây là lý do thiết kế đặt giờ riêng thành cột thay vì bảng con — plan khoá học chat §6 "Phiên 4" mục 1.

Từ điển đủ mọi mã được hỏi (mã không tra được cũng có mặt, mang ) — người gọi không phải xử lý khoá thiếu.

Trạng thái tự khai đang lưu của một người, kèm cờ tạm ngưng — dùng cho màn hình đổi trạng thái (nó phải hiện đúng thứ người dùng đã chọn, không phải kết luận sau khi gộp với giờ làm việc). Trả null khi người này chưa có dòng nào.

Giờ làm việc của riêng người này đang có hiệu lực — để màn hình giải thích được vì sao "Ngoài giờ làm việc", và để hộp "Đặt giờ làm việc" hiện đúng giờ đã lưu.

Trước KC-18 hàm này không nhận tham số và trả cấu hình chung — một câu trả lời cho mọi người. Nay cấu hình chung không còn áp cho ai (§8.7 câu 5), nên hàm hỏi theo người và đi cùng một đường dựng với : chữ "Ngoài giờ" trên chip và lời giải thích bên cạnh không thể đọc hai định nghĩa khác nhau. Không bao giờ trả null; người chưa đặt mang với cửa sổ "luôn trong ca".

Giờ làm riêng của một loạt người trong một truy vấn — bản nhiều-người của , cùng đường dựng. Dùng cho cột "Giờ làm việc" của bảng trạng thái sale (KC-20, §8.7 câu 6): quản lý phải thấy ca bất thường để đặt hộ lại.

Từ điển đủ mọi mã hợp lệ được hỏi; người chưa đặt mang .

Định nghĩa duy nhất của "còn đang đi làm" — phủ định của trạng thái : tài khoản nhân viên, không bị khoá tại mốc . Mã không lọt qua (kể cả mã không tồn tại) là đã nghỉ việc.

Công khai vì đồng hồ hàng chờ (, KC-18) cũng phải loại người đã nghỉ việc khỏi tập "vào ca", và chép điều kiện LockoutEnd sang đó là dựng định nghĩa thứ hai — ngày ai đó sửa luật khoá tài khoản ở một chỗ, chỗ kia vẫn cho một người đã nghỉ "giữ đồng hồ chạy". Biểu thức chứ không phải hàm để EF dịch được sang SQL. Mốc so LockoutEnd — hiện tại, không phải mốc quá khứ đang hỏi

Đọc và đổi trạng thái sẵn sàng của sale, và đường uỷ quyền tạm đi kèm (giai đoạn C).

Tách khỏi SocialChatService (constructor đã 12 tham số) và khỏi ChatChannelStaffService vì đây là một miền riêng: trạng thái của người, không phải của hội thoại hay của kênh. Giai đoạn D sẽ đọc chứ không đọc lớp này — lớp này là đường GHI. Mọi lần đổi người phụ trách đều đi qua IChatAssignmentJournal.ApplyChangeAsync (§1 mục 4). Uỷ quyền tạm không phải ngoại lệ, và cũng không được tự ghi thẳng vào repository hội thoại.

Trạng thái của một người, dựng đủ cho màn hình (hiệu lực + tự khai + cấu hình + giờ làm riêng và giờ gợi ý)

Trạng thái của một người khác, đã chấm phạm vi. Trả null khi người gọi không quản lý được người này.

Phải là một cửa riêng, không dùng chung : đường đọc không có hàng rào biến cặp endpoint này thành máy tra tên và ghi chú theo mã tuỳ ý cho bất kỳ ai qua được [Authorize] — đúng hình dạng finding F-4 của giai đoạn A (POST staff + GET {id}/staff thành máy tra họ tên theo mã). Ngoài phạm vi trả null chứ không ném: một thông điệp duy nhất, không phân biệt "không tồn tại" với "ngoài phạm vi".

Đặt trạng thái tự khai cho chính mình.

Đặt dài từ Chat.Presence.DelegateOnLeaveDays ngày trở lên sẽ kéo theo uỷ quyền tạm mọi hội thoại đang cầm. Đó là một thao tác đổi người phụ trách hàng loạt chạy đồng bộ trong chính lời gọi này — chậm nhưng hiếm, và tách sang job nền thì người dùng bấm xong không biết chuyện gì đã xảy ra.

Đặt trạng thái tự khai hộ người khác (quyền ChatAgentPresence.ManageOthers).

Đặt, sửa hoặc xoá giờ làm việc riêng của chính mình (KC-18). Giờ bắt đầu và giờ kết thúc cùng trống = xoá, về "chưa đặt" (luôn trong ca).

Chỉ ghi bảy cột giờ trên dòng ChatAgentPresence: không đụng trạng thái tự khai và hạn của nó, không ghi ChatAgentPresenceLog — nhật ký chỉ dành cho trạng thái khai báo, còn "Ngoài giờ" là trạng thái suy ra lúc đọc.

Đặt, sửa hoặc xoá giờ làm việc riêng hộ người khác — cùng quyền (ChatAgentPresence.ManageOthers) và cùng phạm vi với đặt trạng thái hộ (§8.7 câu 4).

Tạm ngưng chia khách cho một người, hoặc gỡ lệnh tạm ngưng

Uỷ quyền tạm bằng tay: chuyển hội thoại của một người đang không sẵn sàng sang người khác cùng kênh.

Bảng thời lượng theo trạng thái, một dòng mỗi nhân viên

Dọn những trạng thái đã hết hạn mà chưa ai bấm gì: hạ về Sẵn sàng, đóng dòng nhật ký đang mở, và trả lại hội thoại đã uỷ quyền tạm cho người vừa hết hạn nghỉ (giai đoạn E — đóng PP-26 và PP-27).

Vì sao cần: ChatAgentAvailability.Resolve đã coi trạng thái hết hạn là Sẵn sàng ngay lúc đọc, nên không có gì sai về mặt phân phối. Nhưng đường trả lại hội thoại nằm ở lời gọi GHI, mà lời gọi ấy chỉ chạy khi có người bấm — người nghỉ xong không bấm gì thì hội thoại ở lại vĩnh viễn với người giữ hộ (PP-26). Và dòng nhật ký đang mở không bao giờ đóng, làm bảng đọc thẳng bằng SQL trông sai dù bảng thời lượng vẫn đúng nhờ cột ExpiresAt (PP-27). Gọi kèm trong lượt quét hạn phản hồi — chỗ rẻ nhất, vì lượt ấy đã chạy mỗi 2 phút. Chạy độc lập với công tắc Chat.Sla.Enabled: đây là dọn dẹp trạng thái, không phải tự động thu hồi của ai, nên nó không nằm trong cái mà công tắc kia bảo vệ. Mốc quét — tham số để test được mà không phụ thuộc đồng hồ máy

Kết quả một lượt dọn trạng thái hết hạn — dùng cho log và cho test.

Số dòng nhật ký đang mở đã quá hạn, tìm thấy ở lượt này

Số nhân viên vừa được hạ về trạng thái Sẵn sàng

Số hội thoại vừa trả lại cho người hết hạn nghỉ

Bỏ qua mọi ràng buộc phạm vi

Quản trị phân phối toàn hệ thống — chạm được nhân viên của mọi kênh

Cửa sổ mặc định của bảng thời lượng khi client không gửi khoảng nào — hôm nay

Trần số nhân viên một lượt xem báo cáo. Bảng thời lượng nạp nhật ký của từng người, nên nó phải là một trang chứ không phải cả bảng lương.

Trần số dòng nhật ký quá hạn dọn trong một lượt. Lượt dọn chạy kèm job hạn phản hồi (mỗi 2 phút) nên nó phải kết thúc gọn; phần dư sang lượt sau, và vì sắp theo mã nhân viên nên thứ tự ổn định chứ không bỏ sót ai. Cắt bao nhiêu thì log ra bấy nhiêu.

Tên người thao tác ghi vào nhật ký khi chính hệ thống tự dọn

Kiểm hợp lệ rồi ghi bảy cột giờ làm riêng — dùng chung cho hai đường "của tôi" và "đặt hộ".

Luật hợp lệ là — cùng luật mà đường dựng từ cột (ChatWorkingHours.ForStaff) dùng, nên dòng nào ghi được ở đây thì máy chia đọc được đúng như thế, không có dòng "API nhận mà máy chia coi là hỏng". Không đụng SelfStatus/UntilTime và không ghi ChatAgentPresenceLog: nhật ký chỉ ghi trạng thái khai báo, còn "Ngoài giờ" là trạng thái suy ra lúc đọc (chốt chặn GhiNhatKyDuoc). Giờ riêng cũng không có lịch sử — giới hạn đã chấp nhận ở thiết kế §6 "Phiên 4".

Số mã ngày tối đa một lần đặt giờ làm được gửi lên — bảy ngày trong tuần

Thông báo sau khi bỏ giờ làm riêng — dùng cho cả hai đường, cả khi chưa từng đặt.

Ghép mảng mã ngày từ giao diện thành chuỗi "2,3,4" mà hàm kiểm hợp lệ và cột WorkingDays dùng. null/rỗng giữ nguyên rỗng — hàm kiểm hợp lệ tự báo "chọn ít nhất một ngày" khi đang đặt giờ, và bỏ qua khi đang xoá.

Trạng thái nào của người đang giữ thì cho phép uỷ quyền tạm bằng tay.

CHỈ ba trạng thái mang nghĩa "vắng mặt đã được khai báo hoặc đã bị quản lý ra lệnh": , , . Cố ý KHÔNG nhận , dù nó cũng là "không sẵn sàng". Ngoài 08:00–17:30 và cả ngày Chủ Nhật thì mọi người đều OffShift — lấy nó làm điều kiện là dựng một hàng rào rỗng nghĩa: 18 giờ tối, người có ChatAgentPresence.ManageOthers nhưng KHÔNG có ChatConversation.Transfer vẫn chuyển được hội thoại của đồng nghiệp cùng kênh đi bất cứ đâu. Cùng lý lẽ với /: chúng có trần 120 phút, không phải lý do để bàn giao việc. Đường TỰ ĐỘNG (đặt Nghỉ dài) không đi qua hàm này, và không cần: ở đó chính người đang giữ là người bấm, nên không có ai giành việc của ai.

Giao hội thoại đang mở của cho người khác cùng kênh.

Người nhận. 0 = tự chọn người ít việc nhất đang sẵn sàng, theo từng kênh. Chỉ đụng tới hội thoại thuộc những kênh này. null = không giới hạn. Đây là hàng rào, không phải một bộ lọc tiện tay. Thẩm quyền đưa người gọi tới đây là thẩm quyền theo kênh: cho họ chạm tới một nhân viên vì hai người cùng ở một kênh mà họ làm Leader/Owner. Không giới hạn lại ở đây thì trưởng nhóm kênh K đụng được nhân viên B qua kênh K, rồi chuyển luôn hội thoại của B ở kênh L, M, N — những kênh họ không có vai trò nào. Đó đúng hình dạng finding F-1 đã vá một lần ở giai đoạn A ("quyền cấu hình MỘT kênh gỡ được người phụ trách của MỌI kênh"), và đúng lý do ChatChannelStaffService.NhaHoiThoaiKhiThoiPhuTrachAsync phải lọc theo cặp (kênh, người). Đường TỰ PHỤC VỤ truyền null, và phải thế: tôi nghỉ thì hội thoại của tôi ở mọi kênh đều cần bàn giao. Chính người đang giữ là người bấm nên không có ai giành việc của ai. Không chọn người này làm người nhận ở nhánh tự chọn. Dùng để chặn người thao tác tự nhận việc về mình — đã chặn đường CHỈ ĐỊNH, nhưng nhánh TỰ CHỌN cũng phải chặn, nếu không thì chỉ cần đặt mọi đồng nghiệp sang "Bận" là bản thân thành ứng viên duy nhất và cùng một kết quả xảy ra qua một cửa khác. (số hội thoại đã giao, số hội thoại không giao được)

Nhận lại những hội thoại đã uỷ quyền tạm đi khi người nghỉ quay lại (CH-7).

Không có cột nào đánh dấu "hội thoại này đang được giữ hộ" — và cố ý không thêm, vì ChatConversationAssignment đã kể đủ câu chuyện: một lượt đang mở với lý do nhận UyQuyenTam, mà lượt ngay trước nó của cùng hội thoại là của người vừa quay lại và đóng bằng lý do NguoiPhuTrachNghi. Thêm một cột cờ là dựng nguồn sự thật thứ hai cho một việc mà nhật ký đã trả lời được.

Chọn người nhận trong một kênh: người chỉ định (nếu hợp lệ), hoặc người ít việc nhất đang sẵn sàng.

Không bao giờ chọn người này ở nhánh TỰ CHỌN. 0 = không loại trừ ai. Có mặt vì chặn đường CHỈ ĐỊNH thôi thì chưa đủ. Người có ChatAgentPresence.ManageOthers đặt được trạng thái cho mọi nhân viên trong kênh mình làm trưởng nhóm — nên họ chỉ cần đặt tất cả đồng nghiệp sang "Bận", đặt mình "Sẵn sàng", rồi đặt nạn nhân sang "Nghỉ 2 ngày": nhánh tự chọn lúc ấy chỉ còn đúng một ứng viên là chính họ, và toàn bộ hội thoại của nạn nhân về tay họ mà không cần ChatConversation.Transfer. Cùng một kết quả với đường chỉ định, qua một cửa khác. Đường TỰ PHỤC VỤ truyền 0: ở đó người bấm chính là người đang giữ, nên máy chọn trúng ai cũng là luật xác định chứ không phải một lựa chọn của họ.

Đổi người phụ trách một hội thoại qua sổ phân công, rồi phát realtime đúng thứ tự.

Nạp dòng presence, hoặc dựng mới nếu chưa có. "Chưa có dòng" là trạng thái bình thường của gần như mọi sale, không phải lỗi.

Đóng dòng nhật ký đang mở và mở dòng mới, nếu trạng thái khai báo thật sự đổi.

Trạng thái khai báo là Suspended khi đang bị tạm ngưng, còn lại là SelfStatus — một giá trị tại một thời điểm, nên đúng một dòng đang mở. Không tách khoảng khi trạng thái không đổi (ví dụ chỉ sửa ghi chú): tách ra là bảng thời lượng đầy những khoảng một phút không nói lên điều gì.

Người thao tác có được đặt trạng thái / tạm ngưng / uỷ quyền cho nhân viên này không.

Hàng rào ở đây là phạm vi KÊNH, không phải DataAccessScope: Quản trị phân phối toàn hệ thống (Founder hoặc ChatDistribution.Manage) chạm được mọi nhân viên chat. Người khác chỉ chạm được nhân viên của những kênh chính mình đang là Leader/Owner — cùng đúng tập mà CanAdministerChannelAsync cho họ cấu hình danh sách phụ trách. Chính mình thì luôn được. Vì sao không dùng DataAccessScope như IsStaffInScopeAsync: số đo §2.4 cho thấy 77/85 dòng UserPreference đang ở SelfOnly, kể cả của người quản lý. Gác đường này bằng DataAccessScope nghĩa là nhóm 7 "Quản lý chi nhánh" — nhóm được cấp ChatAgentPresence.ManageOthers ở PP-17 — không đặt được trạng thái cho một ai, và giao diện lại dịch điều đó thành "không tìm thấy nhân viên". Đó đúng hình dạng lỗi FB-1/L12: trang vô dụng với chính vai nó phục vụ, và không ai thấy vì mọi lần thử tay đều bằng Founder. Nới hơn IsStaffInScopeAsync nhưng không mở thêm đường nào: hàm kia gác một phép tra danh bạ (cặp POST staff + GET {id}/staff từng thành máy tra họ tên theo mã — finding F-4), còn hàm này gác thao tác quản lý trên những người mà người gọi đã nhìn thấy sẵn trong danh sách phụ trách kênh của chính họ. Và tự nâng mình lên Leader để lách thì không được: đặt vai Leader/Owner đòi ChatDistribution.Manage hoặc Founder từ bản vá F-1.

Tập nhân viên mà người này quản lý được trạng thái. Trả null nghĩa là không giới hạn (quản trị phân phối toàn hệ thống) — phân biệt rõ với một danh sách rỗng, vốn nghĩa là "không quản lý được ai".

Những kênh mà người này thật sự có thẩm quyền quản lý. Trả null nghĩa là không giới hạn (quản trị phân phối toàn hệ thống) — phân biệt rõ với danh sách rỗng, vốn nghĩa là "không quản lý kênh nào".

Tách riêng khỏi vì hai hàng rào cần cùng một nguồn: "được chạm tới AI" và "được đụng hội thoại của họ Ở KÊNH NÀO". Trước khi tách, chỉ có hàng rào thứ nhất tồn tại — nên trưởng nhóm kênh K chạm được nhân viên B qua kênh K rồi chuyển luôn hội thoại của B ở kênh L, M, N. Hai câu hỏi khác nhau đọc từ một chỗ thì chúng không lệch nhau được. Đặt vai Leader/Owner đòi ChatDistribution.Manage hoặc Founder từ bản vá F-1, nên đường "tự nâng mình lên trưởng nhóm để mở rộng phạm vi" không tồn tại.

Đọc bộ lọc của bảng thời lượng: khoảng thời gian, kênh, từ khoá.

FromDate/ToDate gửi lên là ngày theo giờ Việt Nam, nên phải dựng lại mốc bằng của cửa sổ giờ làm chứ không dùng offset của máy chủ. Không làm thế thì báo cáo "hôm nay" trên một máy chủ chạy UTC bắt đầu từ 7 giờ sáng — đúng lớp lỗi lệch múi giờ đã cắn ở đợt bảo dưỡng xe (axios ép toISOString()).

Tập nhân viên đưa vào bảng thời lượng: người đang phụ trách kênh chat.

Chỉ một kênh; 0 = mọi kênh

Thứ tự ngày trong tuần theo cách người Việt đọc lịch: Thứ Hai trước, Chủ Nhật cuối.

Câu mô tả giờ làm riêng cho chip trạng thái, ví dụ "08:00–17:30, Thứ Hai–Thứ Bảy, nghỉ trưa 12:00–13:00".

Ca kéo tới hết ngày in "đến hết ngày" chứ không in giờ kết thúc: trong bộ nhớ nó là 24:00, và định dạng hh\:mm sẽ in thành "00:00" — "08:00–00:00" đọc như ca không có phút nào. In "23:59" cũng sai theo kiểu khác: người đọc hiểu phút cuối không tính, trong khi nó có tính.

Gom ngày làm thành cụm cho gọn chip: đủ bảy ngày là "cả tuần"; chuỗi liên tiếp từ ba ngày trở lên viết "Thứ Hai–Thứ Sáu"; ngắn hơn thì liệt kê.

Một cửa sổ giờ làm ở dạng giao diện đọc và gửi lại được nguyên văn: hết ngày in 23:59 (giá trị người dùng chọn), ngày làm là mã 2..8 tăng dần.

DayOfWeek → mã ngày của cấu hình: 2 = Thứ Hai … 7 = Thứ Bảy, 8 = Chủ Nhật.

Một lần đổi người giữ hội thoại, mô tả đủ để ghi được nhật ký.

Gộp thành một lớp thay vì tám tham số rời: đường ghi này được gọi từ bốn chỗ khác nhau (phân công tay, nhả, chuyển tay, và máy phân phối ở giai đoạn D), và tám tham số cùng kiểu int?/bool đứng cạnh nhau là chỗ để hoán vị nhầm mà trình biên dịch không kêu.

Hội thoại đổi người

Người sắp nhận. null = gỡ phân công, hội thoại về hàng chờ.

Vì sao người mới nhận. Bỏ qua khi để trống.

Vì sao người cũ thôi giữ — thứ quyết định người cũ còn đọc được hội thoại không (§6.2). Bỏ qua khi trước đó không ai giữ.

Máy quyết hay người quyết

Người bấm nút. null = máy quyết.

Tên người bấm nút, ghi vào cột audit

Ghi chú của người thao tác

Sổ phân công hội thoại — đường ghi duy nhất vào .

Tách khỏi SocialChatService vì bảng này quyết định phạm vi dữ liệu chứ không chỉ ghi nhật ký: mức Self của hàng rào đọc KeepReadAccess ở đây (§6.2, PP-10). Mọi đường đổi người — phân công tay hôm nay, máy phân phối ở giai đoạn D, thu hồi quá hạn ở giai đoạn E — đều phải đi qua đúng lớp này. Chép luật ghi ra chỗ thứ hai là để hai chỗ đó lệch nhau, và một chỗ lệch nghĩa là một lượt giữ không ai đọc được hoặc hai lượt cùng mở. Không chấm phạm vi. Người gọi đã nạp hội thoại qua SocialChatService.LoadConversationInScopeAsync; lớp này tin điều đó và chỉ lo ghi đúng. Đặt thêm một lớp chấm quyền ở đây là dựng hàng rào thứ hai để nó lệch với hàng rào thật.

Ghi một lần đổi người: đóng lượt đang mở của người cũ (nếu có) và mở một lượt mới cho người mới (nếu có).

Đóng mọi lượt đang mở chứ không chỉ lượt của người cũ đã biết: nếu vì bất kỳ lý do nào dữ liệu có hai lượt cùng mở, lần đổi người kế tiếp phải khép chúng lại chứ không bỏ mặc — một lượt mở treo lơ lửng là một người giữ quyền đọc mãi mãi.

Ghi cột AssignedStaffId trên hội thoại và dòng lịch sử tương ứng, trong một giao dịch.

Hai lượt ghi này phải cùng sống hoặc cùng chết: nhật ký hỏng giữa chừng là người cũ giữ quyền đọc vĩnh viễn và không đường nào đối soát được (finding FB-5 của giai đoạn B). Giao dịch vốn nằm ở SocialChatService.GhiDoiNguoiAsync — nhưng giai đoạn C mở đường ghi thứ ba vào cột ấy (uỷ quyền tạm khi nghỉ dài, và nhả hội thoại khi gỡ người khỏi kênh — sổ nợ PP-18), mà cả hai chạy từ service khác. Chép lại khối giao dịch sang chỗ thứ hai là để hai chỗ đó lệch nhau, nên nó chuyển hẳn về đây. Bản đẩy realtime cố ý KHÔNG nằm trong hàm này, và người gọi phải tự gọi nó sau khi hàm này trả về: gửi đi rồi rollback là báo cho mọi màn hình một sự thật chưa từng xảy ra. Thứ tự bắt buộc vẫn là thu hồi phạm vi trước, đẩy cập nhật sau.

So sánh rồi đặt: chỉ gán hội thoại khi nó còn chưa có ai giữ. Trả true nếu lượt này giành được, false nếu người khác đã giữ trước.

Máy phân phối chạy trên webhook, và hai tin của cùng một khách đến cách nhau vài chục mili-giây là chuyện bình thường. Đọc rồi ghi thì hai luồng cùng đọc thấy null và cùng ghi — khách được giao cho hai người, mỗi người thấy một nửa sự thật. Điều kiện AssignedStaffId IS NULL vì thế phải nằm trong chính câu lệnh ghi, để database phân xử chứ không phải code. Cố ý không dùng khuôn RowVersion + retry của WalletTransferService: ở đó nhiều cột đổi cùng lúc và lượt thua phải thử lại trên dữ liệu mới; ở đây đúng một cột chuyển từ null sang có giá trị, và lượt thua không có gì để thử lại — hội thoại đã có người, việc đã xong. Thử lại chỉ sinh ra một lần đổi người mà không ai yêu cầu. Hàm này ghi cả cột trên hội thoại lẫn dòng lịch sử trong một giao dịch, y như ; và cũng y như thế, bản đẩy realtime nằm ngoài. Thực thể hội thoại. Khi giành được, hàm cập nhật luôn các cột trên thực thể này để bản đẩy realtime và mọi lời gọi phía sau nhìn thấy đúng người vừa nhận. Lượt đổi người, phải có NewStaffId Mốc gán. Truyền vào thay vì đọc đồng hồ để bản phát lại đặt được mốc lịch sử.

Thu hồi quyền xem của một người trên một hội thoại, kể cả khi họ đã thôi giữ từ lâu.

Cờ KeepReadAccess chỉ được ghi lúc đóng một lượt đang mở (§6.2), nên có một khe hở mà chính người sắp bị cắt điều khiển được: họ tự nhả trước với một lý do hành chính, lượt của họ đóng lại với cờ giữ quyền, hội thoại về hàng chờ — và từ đó không còn lượt nào để quản lý đóng. Chú thích của ChatReleaseReasonRules đã gọi tên đúng mối lo này ("người bấm nút chuyển hội thoại thường chính là người có động cơ giữ lại quyền xem") nhưng mới bịt đường sửa cờ trên giao diện, chưa bịt đường tự chọn lý do. Không sửa dòng lịch sử cũ — lịch sử là append-only. Thay vào đó ghi THÊM một dòng đã đóng sẵn mang cờ cắt; luật gộp theo cặp (người, hội thoại) của ChatVisibilityResolver đòi MỌI lượt còn quyền đọc, nên đúng một dòng như vậy là đủ cắt. Bắt buộc là lý do CẮT quyền xem; lý do khác bị từ chối

Nhả hội thoại quá hạn khỏi người đang giữ, có so-sánh-rồi-đặt: chỉ nhả khi hội thoại vẫn đang ở tay và khách vẫn đang chờ. Trả false khi thua — hội thoại đã đổi tay, hoặc vừa được trả lời.

Cùng khuôn với , chỉ ngược chiều: một câu UPDATE có điều kiện để database phân xử lượt tranh chấp, dòng nhật ký chỉ ghi khi câu ấy thắng, và cả hai nằm trong một giao dịch. Bản đầu của giai đoạn E dùng — nó ghi lại cả dòng từ ảnh chụp đầu lượt quét và xoá mất câu trả lời mà sale vừa kịp gửi.

Lịch sử phân công của một hội thoại, mới nhất lên đầu — dùng cho màn "ai từng cầm hội thoại này".

Tên ghi vào cột audit; máy quyết thì nói thẳng là máy

Ghi chú đến từ client — cắt đúng bề rộng cột để một chuỗi dài không làm hỏng cả lượt ghi

Kết quả lưu một ảnh đính kèm của khung chat.

Lưu được hay không

Lý do đọc được cho nhân viên khi không lưu được

Đường dẫn tệp trên đĩa máy chủ — do MÁY CHỦ sinh, không bao giờ nhận từ client

Đường dẫn công khai để khung chat hiển thị lại ảnh

Lưu ảnh nhân viên đính kèm vào tin nhắn chat.

Kiểm tra và lưu một ảnh, trả về đường dẫn đĩa + đường dẫn công khai.

Tệp ảnh nhận từ multipart Thư mục con dưới Images/Chat. Luôn là hằng số của máy chủ (ví dụ ), không bao giờ lấy từ request. null (mặc định) = đường cũ Images/Chat/{năm}/{tháng}/{ngày} của ảnh gửi kèm tin nhắn; có giá trị thì ghi vào Images/Chat/{subFolder}/{năm}/{tháng}. Vì sao không dùng thẳng IUnifiedMediaService.ProcessImageAsync như các phân hệ khác: hàm đó tối ưu mọi ảnh sang WebP rồi xoá bản gốc, mà Zalo chỉ nhận jpg/png — tệp vừa lưu sẽ không gửi đi được. Ở đây tệp gốc được giữ nguyên định dạng. Không mất gì về dung lượng vì giới hạn 1 MB của Zalo đã chặn sẵn ảnh lớn. Tên tệp do máy chủ sinh. Thư mục media được một site riêng phục vụ, ngoài pipeline .NET, nên không có bất kỳ lớp chấm quyền nào — ai biết đường dẫn là xem được. Giữ tên tệp người dùng đặt là để lộ tên gốc và làm đường dẫn đoán được. Cùng lý do với TruckMaintenanceMediaService.ProcessPdfAsync.

Trần kích thước ảnh. Bằng đúng giới hạn Zalo công bố cho API tải ảnh lên — chặn tại đây thì nhân viên biết ngay, thay vì gửi xong mới nhận một mã lỗi của Zalo.

Thư mục con của ảnh mẫu tin nhắn nhanh (docs/plan-tin-nhan-nhanh-chat.md §2.2). Nằm riêng khỏi ảnh gửi kèm tin nhắn vì hai loại có vòng đời khác nhau: ảnh mẫu được nhiều tin trỏ tới và không bao giờ bị xoá khi xoá mẫu (nguyên tắc 1.4), nên việc dọn tệp mồ côi sau này (sổ nợ TN-5) phải quét được đúng thư mục của nó mà không đụng ảnh hội thoại.

Thư mục con dưới gốc media

Tên thư mục con hợp lệ. Hẹp tới mức không chứa được dấu phân cách đường dẫn hay ..: tham số này hôm nay chỉ nhận hằng số, nhưng hàm ghi tệp xuống đĩa không được phép tin điều đó.

Phần mở rộng suy từ chữ ký nội dung, hoặc null nếu không phải JPG/PNG.

Kết quả một lần nạp phủ sóng — dùng chung cho một lượt quét hoặc một trang.

Không kênh nào, không ai — kết quả của một lần hỏi rỗng.

Phủ sóng theo ChatChannelId — có mặt mọi kênh được hỏi (mã > 0). Kênh không có ứng viên nào mang tập khoảng rỗng: không ai vào ca, đồng hồ không chạy.

Giờ làm riêng của mọi người đã nạp (ứng viên + người gọi xin thêm), theo StaffId — đi ra từ cùng một truy vấn ChatAgentPresence.

Nạp dữ liệu cho đồng hồ hàng chờ (KC-18, §8.7 câu 3 + 3b) — hàng loạt, rồi giao cho hàm thuần .

Hai nơi hỏi cùng một câu "khách ở hàng chờ đã chờ bao nhiêu phút có người trực": lượt quét báo trưởng nhóm () và cột "chờ bao lâu" trên giao diện (). Một lớp nạp chung là để hai con số ấy không bao giờ khác nhau — cùng bài học của . Số truy vấn không phụ thuộc số hội thoại hay số kênh: một câu ứng viên cho mọi kênh, một câu giờ riêng (qua ), một câu nhật ký Nghỉ / Tạm ngưng, một câu trạng thái nghỉ việc. Lượt quét chạy mỗi 2 phút với tới 200 hội thoại — hỏi theo từng hội thoại là N+1 trên đúng job nóng nhất.

Phủ sóng của các kênh trong [from, to].

Kênh cần phủ sóng — người gọi đã lọc AutoDistribute Mốc chờ sớm nhất trong các hội thoại cần đếm; dài quá thì bị cắt và ghi log "Bây giờ" Những người mà người gọi cần giờ riêng nhưng không phải ứng viên của kênh nào được hỏi — cột "chờ bao lâu" xin thêm người đang cầm hội thoại để đi chung một truy vấn giờ làm.

Quản lý các kênh chat đã kết nối: luồng cấp quyền, giữ token, bật/tắt, xoá. Đây là nơi DUY NHẤT trong hệ thống ghi và đọc token của kênh, và token luôn đi qua — không có đường nào lưu thô. Luồng cấp quyền khác nhau theo nền tảng (Zalo dùng OAuth v4, Facebook dùng dán user token rồi tra /me/accounts) nên các phương thức ở đây gọi thẳng tên nền tảng. Đó là chủ ý: lõi độc lập nền tảng là SocialChatService, không phải lớp này.

Danh sách kênh, mới nhất trước. Không trả token dưới bất kỳ dạng nào.

Chi tiết một kênh. Không trả token dưới bất kỳ dạng nào.

Dựng đường dẫn để admin của Zalo OA bấm vào và cấp quyền cho ứng dụng, kèm tham số state đã ký để nhận ra callback do LADA khởi tạo.

Xử lý callback Zalo gọi về sau khi admin OA đồng ý cấp quyền: kiểm state, đổi code lấy token, tạo hoặc cập nhật kênh.

Dựng đường dẫn Facebook Login for Business để quản trị viên bấm vào và tự cấp quyền, kèm tham số state đã ký và buộc vào chính người bấm. Chuỗi state trả về cũng là thứ giao diện giữ lại để hỏi danh sách Page ở bước sau — token không bao giờ đi qua trình duyệt.

Xử lý lần chuyển hướng Facebook gọi về sau khi quản trị viên cấp quyền: kiểm state, đổi code lấy token, đổi tiếp sang bản dài hạn rồi giữ tạm trong bộ nhớ máy chủ để bước chọn Page dùng lại. KHÔNG tạo kênh ở đây: quản trị viên còn phải chọn Page nào trong số Page họ quản lý.

Danh sách Facebook Page mà quản trị viên đang quản lý. Kết quả KHÔNG chứa token của Page nào — xem . Hai nguồn token, truyền đúng một trong hai: của một phiên Facebook Login vừa xong (đường chuẩn), hoặc dán tay từ Graph API Explorer (đường dự phòng khi chưa cấu hình xong ứng dụng Facebook).

Kết nối một Facebook Page thành kênh chat: lấy Page access token của đúng Page được chọn, mã hoá rồi lưu. Nguồn token giống . Phiên cấp quyền sống 10 phút và dùng được nhiều lần trong khoảng đó — kết nối liền mấy Page không phải đăng nhập lại.

Đăng ký lại webhook (subscribed_apps) cho một kênh Facebook đã lưu, bằng chính Page access token đang giữ (SC-20). Dành cho kênh kết nối trước bản vá này, hoặc khi bước đăng ký lúc kết nối thất bại.

Bật hoặc tắt một kênh. Kênh tắt thì webhook bỏ qua tin của nó và không gửi ra được.

Xoá mềm một kênh.

Làm mới token của mọi kênh sắp hết hạn. Job Hangfire gọi định kỳ. Trả về số kênh đã làm mới thành công.

Khoá cấu hình dùng để ký tham số state của luồng OAuth

Thời hạn của tham số state. Authorization code của Zalo sống 10 phút, nhưng admin còn phải chọn OA và bấm đồng ý trước đó nên cửa sổ phải rộng hơn thế.

Tiền tố khoá của token Facebook đang chờ chọn Page. Cố ý KHÔNG khai vào CacheKeys và cố ý KHÔNG đi qua ICacheService: controller /api/Cache/GetEntries in thẳng giá trị thô của mọi mục đi qua đường đó ra HTTP.

Tiền tố khoá của sổ state đã phát hành cho luồng Facebook, ánh xạ sang mã người dùng đã bấm nút. Chữ ký HMAC một mình KHÔNG đủ: nó chứng minh state do LADA sinh ra, nhưng không nói state đã được tiêu chưa. Mà state thì nằm trên URL — trong nhật ký truy cập, trong lịch sử trình duyệt. Ai nhặt được một chuỗi còn hạn có thể tự chạy lại lượt cấp quyền bằng tài khoản Facebook của họ và ghi đè token đang chờ của quản trị viên. Sổ này khoá điều đó lại: state chỉ tiêu được đúng một lần (RFC 6749 §10.12).

Hạn của một state đã phát hành nhưng chưa dùng. Ngắn hơn hẳn (con số của luồng Zalo) nhưng vẫn đủ rộng cho một lượt đăng nhập Facebook có xác thực hai bước và màn chọn Trang, chọn Doanh nghiệp.

Token chờ chọn Page sống 10 phút — đủ để nhìn danh sách rồi bấm kết nối vài Page liền nhau, ngắn hơn hẳn 60 ngày tuổi thọ thật của nó.

Điền tên bưu cục và số nhân viên phụ trách cho một trang danh sách kênh — hai lượt tra cho cả trang, không tra từng dòng (cùng cách SearchConversationsAsync điền tên người phân công).

Lấy user access token dài hạn từ một trong hai nguồn. Đường chuẩn là của phiên Facebook Login vừa xong: token đã được đổi sang bản dài hạn ngay lúc callback và nằm trong bộ nhớ máy chủ, nên ở đây chỉ việc lấy ra — đổi lần nữa là thừa một lượt gọi Graph API. Đường dự phòng là token dán tay. Bước đổi dài hạn khi đó là bắt buộc chứ không phải tối ưu: Page access token thừa hưởng tuổi thọ của user token sinh ra nó. Lấy Page token từ một user token ngắn hạn thì vài giờ sau kênh chết im lặng, và không có job nào làm mới được vì Facebook không có refresh token.

User access token dài hạn đang chờ quản trị viên chọn Page, buộc vào người đã cấp quyền. Chỉ nằm trong RAM và chỉ sống .

User access token dài hạn đang chờ quản trị viên chọn Page, buộc vào người đã cấp quyền. Chỉ nằm trong RAM và chỉ sống .

Lấy user token dài hạn rồi hỏi danh sách Page.

Làm mới token của một kênh. Refresh token của Zalo chỉ dùng được MỘT LẦN: gọi xong là bản cũ chết, và access token cũ cũng hết hiệu lực ngay. Vì vậy cặp mới phải được ghi xuống trong một transaction — mất nó là kênh chết im lặng, không có lỗi nào báo cho tới khi nhân viên gửi tin và bị từ chối. Lời gọi HTTP nằm NGOÀI transaction có chủ ý: giữ transaction mở suốt một lượt gọi mạng là khoá bảng lâu vô ích. Cặp token là hai cột của cùng một dòng nên một lệnh cập nhật đã đủ nguyên tử; transaction ở đây là để lời hứa đó tường minh và kiểm được bằng test.

Mã hoá một token và CHỨNG MINH nó đã được mã hoá. cố ý lưu thô khi thiếu Security:SecretKey (chấp nhận được với mật khẩu email trên dev), nhưng Page access token không có hạn dùng và refresh token Zalo sống ba tháng — để chúng nằm thô trong database là để bất kỳ ai đọc được bảng hay bản backup nhắn tin thay LADA. Thiếu khoá thì hỏng ồn ào ngay lúc kết nối, còn hơn hở im lặng cho tới lúc bị phát hiện.

Tìm kênh theo nền tảng + định danh nền tảng, bản mới nhất trước. Không lọc theo IsActive: cấp quyền lại cho một kênh đang tắt vẫn phải cập nhật đúng bản ghi đó chứ không sinh bản ghi thứ hai.

Chuỗi state = "{giây epoch}.{nonce}.{chữ ký HMAC}". Chỉ callback do LADA khởi tạo mới ký đúng, và chữ ký phủ luôn dấu thời gian nên không kéo dài hạn của một state cũ được.

Kiểm chữ ký và hạn dùng của một chuỗi state, trả ra phần nonce để bên gọi đọc tiếp nếu cần. Cả hai luồng cấp quyền dùng chung hàm này — thuật toán ký của repo đã bị chép thành hai bản (ở đây và AdsConnectionService), đừng thêm bản thứ ba.

Bản state có buộc thêm mã người dùng: nonce mang dạng "{userId}-{GUID}". Dấu nối là gạch ngang chứ không phải dấu chấm — dấu chấm là ký tự tách của chính chuỗi state, thêm một dấu nữa là hàm kiểm thấy 4 phần rồi từ chối sạch. Luồng Zalo không cần thứ này vì callback của nó tạo kênh xong ngay trong một lần gọi; luồng Facebook thì còn một bước chọn Page ở phiên đăng nhập khác, nên phải biết token đang chờ là của ai.

Kiểm state rồi đọc ra mã người dùng đã khởi tạo luồng cấp quyền.

Ký payload của tham số state. Chuỗi kết nối DB là đường lui — vẫn là bí mật chỉ máy chủ biết. Nhưng KHÔNG có đường lui nào là hằng số trong mã nguồn: khoá HMAC nằm trong repo thì ai đọc được repo cũng ký được state hợp lệ, tức là lớp chống CSRF duy nhất của endpoint công khai này biến mất. Thiếu cả hai nguồn thì ném lỗi, để hỏng ồn ào lúc cấu hình sai còn hơn hở im lặng.

Kết quả bước hỏi danh sách Page trước khi kết nối kênh Facebook.

Hỏi được danh sách hay không

Danh sách Page, không kèm token

Lý do đọc được cho quản trị viên khi hỏi không được

Kết quả một lượt job làm mới token.

Số kênh tới ngưỡng phải làm mới

Số kênh đã làm mới thành công

Số kênh làm mới thất bại — cần cấp quyền lại bằng tay

Danh sách nhân viên phụ trách từng kênh chat, và cấu hình phân phối của kênh. Đây là nguồn của quan hệ kênh ↔ sale mà cả hàng rào quyền xem () lẫn máy phân phối (giai đoạn D) đều đọc. Một bảng, một service, một luật — kênh nhiều sale và kênh một chủ dùng chung (§2.3, §6.4).

Danh sách nhân viên phụ trách một kênh, kể cả người đã thôi phụ trách

Người này có được cấu hình danh sách phụ trách của kênh đã cho không. Quyền hạt ChatChannel.StaffAssign chỉ nói "được cấu hình sale phụ trách kênh", không nói kênh nào. Đường đọc danh sách phải hỏi thêm câu này, còn hai đường ghi tự hỏi lại bên trong — một quyền không kèm phạm vi là lỗ IDOR, đúng bài học của docs/security-audit-2026-07-11.md.

Thêm hoặc sửa một dòng phụ trách

Gỡ một người khỏi danh sách phụ trách — xoá mềm và đóng mốc LeftAt. Không xoá cứng: dòng này là bằng chứng "ai từng phụ trách kênh nào", và ở giai đoạn sau nó còn là căn cứ đối chiếu của nhật ký phân phối.

Đổi bưu cục sở hữu và chế độ phân phối của một kênh

Một nhân viên có được phép nhận phân công hội thoại của kênh này không. Kênh còn ở chế độ thì luôn true: ở đó phân công vẫn chỉ là nhãn và danh sách phụ trách thường còn trống, siết vào là phá luồng đang chạy thật (nguyên tắc số 1). Kênh đã bật hàng rào thì bắt buộc có tên trong danh sách phụ trách, vì phân công quyết định ai đọc được hội thoại.

Mã những nhân viên đang phụ trách một kênh (đang hoạt động, chưa thôi phụ trách)

Những nhân viên đang phụ trách một kênh kèm trọng số — điều kiện lọc số 1 của máy phân phối §3.3.

Cùng phép lọc với (IsActive và chưa LeftAt) và gọi thẳng vào đây, để định nghĩa "đang phụ trách kênh" chỉ tồn tại ở một chỗ. Hai truy vấn viết riêng cùng một phép lọc là hai truy vấn sẽ lệch nhau ở lần sửa thứ ba. Không lọc theo . §3.3 chỉ đòi "có dòng ChatChannelStaff của kênh đó" — trưởng nhóm và chủ kênh cũng nhận khách, và trên dev họ đúng là những người có mặt. Muốn một trưởng nhóm không nhận khách thì hạ IsActive hoặc đặt WeightOverride nhỏ, chứ không phải bằng một luật ngầm trong máy phân phối.

Trưởng nhóm và chủ của một kênh — những người nhận cảnh báo về kênh ấy.

Gộp cả lẫn , đúng như hai hàng rào phạm vi kênh đang có (CanAdministerChannelAsync ở lớp này và KenhQuanLyDuocAsync ở dịch vụ trạng thái sẵn sàng). Có mặt vì giai đoạn D suýt thêm bản sao thứ ba và thứ tư của cùng một truy vấn: định nghĩa "ai quản trị được kênh này" mà nằm ở bốn chỗ thì đến lần sửa thứ hai chúng đã lệch nhau.

Tập nhân viên mà một kênh giới hạn phân công vào — dùng để thu hẹp ô gợi ý nhân viên. Trả null khi kênh không giới hạn ai (kênh , hoặc không truyền kênh nào): người gọi giữ nguyên danh sách của mình. Trả danh sách — kể cả danh sách rỗng — nghĩa là kênh có hàng rào và chỉ những người này được chọn.

Những người cùng phụ trách kênh của một hội thoại cụ thể — tập mà một người mức DataAccessScope.SelfOnly được phép chọn khi phân công hoặc chuyển khách (sổ nợ PP-38, kế hoạch §6.6, chốt 2026-08-30).

Cố ý KHÔNG hỏi và cũng không hỏi . Hàm thứ nhất trả true vô điều kiện cho kênh Shared, hàm thứ hai trả null ("không giới hạn ai") cho đúng kênh ấy — dùng cái nào ở đây cũng biến ô chọn của một sale thành danh bạ nhân sự cả công ty trên mọi kênh chưa bật hàng rào, tức trên TOÀN BỘ hệ thống trong lúc còn dry-run. Ở đây "cùng kênh" luôn có nghĩa là có dòng phụ trách đang hoạt động, bất kể chế độ. Ruột gọi lại đúng mà staff/suggest dùng — một luật, một truy vấn, hai hình dạng. Hội thoại tra không ra → danh sách rỗng, không ai chọn được. Fail-closed.

Bỏ qua mọi ràng buộc phạm vi

Quản trị phân phối chat của toàn hệ thống — quyền duy nhất mở được vai trò "Trưởng nhóm"/"Chủ kênh" và đổi được chế độ phân phối của một kênh.

Định nghĩa duy nhất của "dòng phụ trách này là một ứng viên phân phối" — điều kiện lọc của .

Công khai vì đồng hồ hàng chờ (, KC-18 thiết kế mục 5) đòi "đúng tập ứng viên của kênh" nhưng không gọi được hàm trên: lớp này phụ thuộc bản đẩy realtime, bản đẩy realtime phụ thuộc bối cảnh cột "chờ bao lâu", và bối cảnh ấy lại cần tập ứng viên — một vòng phụ thuộc mà DI chỉ báo lúc chạy. Nên bên kia truy vấn bảng trực tiếp (một câu cho mọi kênh), và dùng chung biểu thức này thay vì chép điều kiện.

Một thông điệp duy nhất cho mọi ca "bạn không quản trị được kênh này" — không phân biệt kênh không tồn tại với kênh ngoài phạm vi.

Quản trị phân phối chat của toàn hệ thống: Founder hoặc ChatDistribution.Manage.

Người này có quản trị được danh sách phụ trách của kênh đã cho không. Quyền hạt ChatChannel.StaffAssign nói "được cấu hình sale phụ trách kênh", nó KHÔNG nói "kênh nào". Thiếu bước thu hẹp theo kênh thì bất kỳ ai có quyền ấy cũng ghi được vào mọi kênh của mọi bưu cục — chính là finding F-1 của cổng chất lượng giai đoạn A. Hai đường được đi qua: quản trị phân phối toàn hệ thống, hoặc đang là trưởng nhóm / chủ của chính kênh đó. Kênh chưa ai phụ trách thì chỉ đường thứ nhất mở — người đầu tiên của một kênh phải do quản trị đặt, không tự nhận.

Mã nhân viên gửi lên có nằm trong phạm vi nhân sự của người gọi không — cùng luật với ô gợi ý staff/suggest và với đường phân công hội thoại.

Founder đi thẳng qua nhánh không ràng buộc, đúng luật chung của hệ thống. Người quản trị phân phối bình thường vẫn bị DataAccessScope của chính họ giới hạn — hệ quả bắt buộc: tài khoản làm việc này phải được đặt phạm vi All hoặc ManagedTeam cho đúng, và điều đó nằm trong checklist production của kế hoạch.

Gỡ (hoặc ngừng) dòng phụ trách này có làm kênh mất người không — trả về câu giải thích khi có, null khi gỡ được. Chỉ chặn trên kênh đã bật hàng rào. Kênh Shared giữ nguyên hành vi hôm nay: ở đó danh sách phụ trách mới chỉ là nhãn, làm rỗng nó không giấu hội thoại của ai (nguyên tắc số 1).

Nhả về hàng chờ những hội thoại mà người vừa thôi phụ trách kênh còn đang giữ trên chính kênh đó (sổ nợ PP-18).

Trước bản vá này, gỡ một sale khỏi kênh chỉ đóng dòng phụ trách; ChatConversation.AssignedStaffId giữ nguyên, nên nhánh Self của hàng rào vẫn cho họ ĐỌC và GHI những hội thoại ấy — kể cả gửi tin cho khách qua OA/Page của công ty. Cổng chất lượng giai đoạn B kết luận đây không phải lỗ mở rộng phạm vi (tập hội thoại đóng băng đúng lúc gỡ và chỉ co lại), nhưng khoảng trống quy trình thì có thật, và bằng chứng là ChatReleaseReason.ThoiPhuTrachKenh = 9 khai từ giai đoạn B mà không đường nào phát ra. Lọc theo CẶP (kênh, người), không chỉ theo người. Một sale phụ trách nhiều kênh; lọc theo mỗi StaffId là gỡ họ khỏi một kênh lại nhả sạch hội thoại của kênh khác. Người cũ vẫn ĐỌC được: KeepsReadAccess(ThoiPhuTrachKenh) trả true theo §6.2 — thôi phụ trách kênh là chuyện hành chính, không phải lỗi của họ, và họ cần tra lại việc mình đã làm. Cái bị cắt là quyền GHI, vì phạm vi ghi không có nhánh "từng giữ" (BuildWritableConversationFilter). Chạy trong một giao dịch cho mỗi hội thoại qua IChatAssignmentJournal.ApplyChangeAsync — đường ghi duy nhất. Không tự UpdateAsync hội thoại rồi ghi nhật ký riêng: hỏng giữa chừng là người cũ giữ quyền vĩnh viễn mà không đường nào đối soát (FB-5). Số hội thoại đã nhả

Số hội thoại chưa đóng mà từng người trong danh sách còn đang giữ trên một kênh.

Dùng cho giao diện /kenh-chat: nút Gỡ phải nói trước "người này còn giữ N hội thoại, gỡ đi thì chúng về hàng chờ" — yêu cầu tối thiểu của PP-18. Một lời gọi cho cả danh sách, không phải một lời gọi mỗi dòng.

Sổ kết nối SignalR đang mở của phân hệ chat: ai đang nối bằng những kết nối nào, và mỗi kết nối đang ở trong những nhóm nào. SignalR không cho liệt kê thành viên của một nhóm, mà thu hồi phòng thì bắt buộc phải biết ConnectionId. Đó là lý do lớp này tồn tại: không có nó thì hàng rào quyền xem chỉ chặn được REST, còn một kết nối đã mở vẫn tiếp tục nhận nguyên văn tin của khách cho tới khi người dùng đóng tab (finding F-3 của cổng chất lượng giai đoạn A). Giới hạn đã biết — sổ nợ PP-16. Sổ này nằm trong bộ nhớ của một tiến trình. Khi API chạy nhiều bản sau Redis backplane, mỗi bản chỉ biết kết nối của chính mình, nên thu hồi chỉ chắc chắn cho những kết nối đang bám vào bản xử lý lời gọi. Bản đầy đủ cần đưa sổ này xuống Redis; ghi rõ ở đây để không ai đọc nhầm rằng thu hồi đã kín trong mọi cấu hình triển khai. Mọi đường REST vẫn chặn đúng trong mọi trường hợp — đây là lớp phòng thủ thứ hai.

Ghi nhận một kết nối vừa mở của một người

Xoá một kết nối vừa đóng

Ghi nhận kết nối vừa vào một nhóm

Ghi nhận kết nối vừa rời một nhóm

Những kết nối đang mở của một người, kèm nhóm mà từng kết nối đang ở trong

Mọi người đang có kết nối mở — dùng khi một thay đổi chạm phạm vi của tất cả

Đăng ký singleton: vòng đời của nó là vòng đời tiến trình, không phải vòng đời một lời gọi. Dùng vì OnConnectedAsync và OnDisconnectedAsync chạy song song trên nhiều luồng.

Kết nối → người sở hữu và các nhóm nó đang ở trong

Những câu UPDATE ghi thẳng vào ChatConversation, không đi qua bộ theo dõi thay đổi của EF: giành hội thoại có điều kiện, và đóng dấu đã-báo hàng chờ.

Tách thành interface riêng vì đúng một lý do, và nói thẳng ra để người sau không tưởng đây là một tầng trừu tượng vô cớ: ExecuteUpdateAsync là một tính năng của trình dịch truy vấn EF Core, không phải của IQueryable. Kho dữ liệu giả của bộ test dựng trên EnumerableQuery nên nó ném lỗi ở đó. Không có seam này thì mọi ca test chạm tới máy phân phối đều chết vì hạ tầng, và cách chữa duy nhất còn lại là đọc-rồi-ghi — tức là bỏ đúng cái ràng buộc đang cần kiểm. Bản giả phải giữ nguyên ràng buộc của bản thật — chỉ nhận khi AssignedStaffId còn null và hội thoại chưa xoá. Một bản giả bỏ qua đúng cái giới hạn mà bản thật có là một bản giả mời lỗi đi qua (bài học FakeChatStaffDirectory ở L9). Nhưng bản giả không chứng minh được tính nguyên tử — việc đó chỉ có database thật làm được, nên ca tranh chấp thật chạy trên SQL Server.

Trả về số dòng đổi được: 1 nếu giành được hội thoại, 0 nếu người khác đã giữ trước hoặc hội thoại đã bị xoá.

Đóng dấu "đã báo trưởng nhóm về hội thoại này", chạm đúng hai cột.

Phải là một câu UPDATE chạm đúng cột cần chạm, không được là UpdateAsync(conversation). Thực thể mà job quét đang cầm được nạp ở đầu lượt, và UpdateAsync ghi lại cả dòng theo ảnh chụp lúc ấy. Giữa lúc nạp và lúc ghi, một webhook có thể đã giao hội thoại cho ai đó — mà đường giao ấy cũng là một câu UPDATE không qua bộ theo dõi, nên thực thể trong tay lượt quét vẫn mang AssignedStaffId = null. Ghi cả dòng là xoá mất lượt gán vừa thắng: khách đã có người, rồi lại không có ai, trong khi nhật ký phân công vẫn ghi là đã giao.

Đóng dấu "đã nhắc người đang giữ về hạn phản hồi", chạm đúng hai cột (giai đoạn E).

Cùng lý do với , và ở đây rủi ro còn cụ thể hơn: lượt quét hạn phản hồi nạp thực thể rồi mới gửi thông báo, mà trong quãng ấy chính sale có thể vừa trả lời khách — tức LastMessageAt, LastStaffReplyAt và FirstResponseAt vừa đổi. Ghi cả dòng theo ảnh chụp cũ là xoá mất câu trả lời ấy khỏi mọi phép đo của giai đoạn F.

Cộng một lượt quá hạn vào SlaBreachCount và xoá mốc đã-nhắc, chạm đúng ba cột (giai đoạn E).

Cộng tại database (c.SlaBreachCount + 1) chứ không đọc-rồi-ghi: hai lượt quét chồng nhau, hoặc một lượt quét chạy cùng lúc với một lời gọi khác đang sửa hội thoại, thì đọc-rồi-ghi làm mất một lượt đếm. Đây là con số duy nhất của cả đợt mà giai đoạn F sẽ dùng để chấm tiêu chí chat.sla-breach-rate. Xoá mốc đã-nhắc cùng lúc là để lượt giữ của người mới bắt đầu sạch. Luật đã tự bảo vệ được nhờ so với mốc bắt đầu đếm, nhưng ghi rõ ra thì nhật ký đọc bằng SQL không còn mang một mốc của lượt đã kết thúc.

Nhả hội thoại quá hạn khỏi và cộng một lượt quá hạn — một câu UPDATE có điều kiện. Trả về số dòng đổi được: 1 nếu thắng, 0 nếu hội thoại đã đổi tay hoặc đã được trả lời trong lúc lượt quét đang chạy.

Vì sao KHÔNG dùng ApplyChangeAsync(conversation, …) như bản đầu. Đường ấy gọi UpdateAsync(entity) → DbSet.Update(), đánh dấu mọi cột là đã đổi, nên câu UPDATE ghi lại cả dòng theo ảnh chụp lúc đầu lượt quét. Giữa lúc nạp và lúc ghi, chính sale có thể vừa trả lời khách — và ghi cả dòng sẽ kéo LastMessageAt, LastStaffReplyAt, FirstResponseAt, UnreadCount, Status, LastMessage lùi về trước câu trả lời ấy, xoá luôn nó khỏi mọi phép đo của giai đoạn F. Và vì sao phải có vế AssignedStaffId = @expected. Bản đầu cố chặn tranh chấp bằng cách nạp lại thực thể rồi chấm lại — một câu lệnh vô tác dụng: Repository.Query() là truy vấn CÓ theo dõi và cả lượt quét dùng chung một DbContext (đăng ký Scoped), nên EF phân giải định danh và trả về chính thực thể cũ, không ghi đè giá trị bằng dữ liệu dưới database. Hàng rào ấy là code chết. Chỉ database mới phân xử được lượt tranh chấp này — đúng lý lẽ đã áp cho , chỉ khác chiều. Vế "khách còn đang chờ" cũng nằm trong câu lệnh (WaitingSinceAt IS NOT NULL): đường nhận tin xoá cột ấy ở mọi tin đi ra, nên nếu sale vừa kịp trả lời thì câu lệnh này đổi 0 dòng và lượt thu hồi tự huỷ.

Một khoảng thời gian nửa mở [From, To) — mốc đầu thuộc khoảng, mốc cuối không.

Nửa mở vì cùng quy ước với ([Start, End)) và với cách nhật ký trạng thái cắt hiệu lực: "Nghỉ tới 09:00" nghĩa là 09:00 đã hết nghỉ.

Một khoảng thời gian nửa mở [From, To) — mốc đầu thuộc khoảng, mốc cuối không.

Nửa mở vì cùng quy ước với ([Start, End)) và với cách nhật ký trạng thái cắt hiệu lực: "Nghỉ tới 09:00" nghĩa là 09:00 đã hết nghỉ.

Độ dài khoảng tính bằng phút; khoảng rỗng hoặc ngược chiều bằng 0.

Một ứng viên của kênh, đủ dữ liệu để biết họ "vào ca" lúc nào — đầu vào của .

Mã nhân viên — chỉ để đọc log và bảng ca, luật không dùng tới Giờ làm riêng của người này; người chưa đặt (hoặc giờ hỏng) mang cửa sổ "luôn trong ca" () — đúng giá trị mà trả. Các dòng ChatAgentPresenceLog của người này giao với khoảng đang tính. Truyền cả dòng Sẵn sàng / Bận / Ra ngoài cũng được — luật tự lọc lấy Nghỉ và Tạm ngưng. Đã nghỉ việc — không bao giờ vào ca

Một ứng viên của kênh, đủ dữ liệu để biết họ "vào ca" lúc nào — đầu vào của .

Mã nhân viên — chỉ để đọc log và bảng ca, luật không dùng tới Giờ làm riêng của người này; người chưa đặt (hoặc giờ hỏng) mang cửa sổ "luôn trong ca" () — đúng giá trị mà trả. Các dòng ChatAgentPresenceLog của người này giao với khoảng đang tính. Truyền cả dòng Sẵn sàng / Bận / Ra ngoài cũng được — luật tự lọc lấy Nghỉ và Tạm ngưng. Đã nghỉ việc — không bao giờ vào ca

Mã nhân viên — chỉ để đọc log và bảng ca, luật không dùng tới

Giờ làm riêng của người này; người chưa đặt (hoặc giờ hỏng) mang cửa sổ "luôn trong ca" () — đúng giá trị mà trả.

Các dòng ChatAgentPresenceLog của người này giao với khoảng đang tính. Truyền cả dòng Sẵn sàng / Bận / Ra ngoài cũng được — luật tự lọc lấy Nghỉ và Tạm ngưng.

Đã nghỉ việc — không bao giờ vào ca

"Có ít nhất một ứng viên của kênh đang vào ca" — tập khoảng đã hợp, cho đồng hồ hàng chờ (KC-18, §8.7 câu 3 + 3b). Hàm thuần: không chạm database, không đọc đồng hồ.

Một ứng viên vào ca tại mốc t (plan §6 Phiên 4, thiết kế mục 5) khi đồng thời: không ở Nghỉ / Tạm ngưng (nhật ký trạng thái, cắt hiệu lực bằng ), không ngoài giờ riêng (chưa đặt = luôn trong giờ), không đã nghỉ việc. Bận và Ra ngoài vẫn là vào ca: chủ dự án chọn "theo trạng thái" — người đang bận vẫn là người có mặt, trưởng nhóm được báo để điều phối. Vì sao hợp khoảng chứ không đếm theo phút. Một hội thoại bị bỏ quên vài tuần là vài chục nghìn phút; lặp từng phút cho từng ứng viên của từng kênh trong một job chạy mỗi 2 phút là đúng thứ đã tránh. Ở đây sinh khoảng ca theo ngày (nhiều nhất hai khoảng một ngày), trừ khoảng vắng, rồi hợp — số khoảng tỉ lệ với số ngày, không với số phút. Giới hạn biết trước (plan §6 Phiên 4): giờ riêng và tập ứng viên lấy theo hiện tại cho cả quá khứ; "đã nghỉ việc" theo LockoutEnd hiện tại. Cùng giới hạn cấu hình chung đã có.

Độ dài tối đa của một lần tính. Khách chờ lâu hơn thế chỉ được đếm phần cuối cùng.

62 ngày = hai tháng dài nhất: đủ rộng để một hội thoại chờ qua kỳ nghỉ Tết vẫn đếm đúng, đủ hẹp để một bản ghi lệch một năm (đã có trên dev, số đo Đ5 §2.4 plan chat) không biến một lượt quét thành hàng nghìn khoảng mỗi ứng viên. Ngưỡng báo trưởng nhóm tính bằng phút nên phần bị cắt không đổi quyết định báo hay không — chỉ đổi con số hiển thị.

Kéo phép dựng quá to một chút để câu hỏi "lúc này" (t = to) có câu trả lời: khoảng nửa mở [a, to) không chứa to, nên cắt đúng ở to là mọi mốc "bây giờ" đều đọc thành "không ai vào ca".

Tổng phút phủ của mọi khoảng đứng TRƯỚC khoảng thứ i — để đếm không phải lặp.

Mốc đầu người gọi hỏi — khác khi đã bị cắt.

Mốc đầu thật sự đã tính (sau khi cắt ở ).

Mốc cuối — thường là "bây giờ" của lượt quét / của trang.

Các khoảng "có người vào ca", đã sắp và đã hợp (không chồng, không kề nhau). Khoảng cuối có thể vượt quá một chút — xem .

Khoảng hỏi dài hơn và đã bị cắt — người gọi phải ghi log.

Mốc đầu sau khi áp trần . Tách thành hàm để lớp nạp dữ liệu truy vấn nhật ký đúng khoảng mà sẽ tính — hai phép cắt lệch nhau là thiếu dòng.

Mốc cuối mà lớp nạp dữ liệu phải lấy nhật ký tới — gồm cả phần nhìn quá để trả lời được "lúc này".

Không ai vào ca suốt khoảng — kênh không có ứng viên nào.

Dựng tập khoảng "có ít nhất một ứng viên vào ca" trong [from, to].

Đúng tập ứng viên phân phối của kênh (GetDistributionCandidatesAsync) Mốc chờ sớm nhất cần đếm; dài quá thì bị cắt "Bây giờ"

Số phút "có người vào ca" trong [a, b], cắt vào [From, To]. Trả 0 khi không muộn hơn — cùng quy ước với .

Tại mốc có ít nhất một ứng viên vào ca không. Trả lời được cho From <= at <= To; ngoài đó là false (không có dữ liệu để nói có).

Tổng phút phủ từ tới — đơn điệu không giảm.

Chỉ số khoảng cuối cùng có From <= at, hoặc -1. Tìm nhị phân.

Khoảng Nghỉ / Tạm ngưng từ nhật ký. Hiệu lực cắt ở mốc sớm hơn giữa lúc đóng dòng và lúc hết hạn tự khai — dùng lại đúng , không viết bản thứ hai: "Nghỉ tới 11:00" mà hôm sau mới bấm về Sẵn sàng thì 11:00 đã hết nghỉ.

Sắp theo mốc đầu rồi gộp mọi khoảng chồng hoặc kề nhau.

Phần của không nằm trong . Cả hai đã sắp và không chồng nhau trong nội bộ.

Điều đã xảy ra sau khi một hội thoại được gắn khách hàng.

Hội thoại vừa được chuyển sang sale của khách

Khách chưa có ai phụ trách, vừa được gán cho người đang cầm hội thoại

Sale của khách không phụ trách kênh, người đang cầm được thêm làm đồng phụ trách

Câu mô tả cho người bấm; rỗng khi không có gì đổi

Giữ cho chat và CRM không nói hai chuyện khác nhau về "sale của khách" (§3.4).

Nguyên tắc gói gọn: Customer.ManagerId là nguồn sự thật về sale của khách, ChatConversation.AssignedStaffId là nguồn sự thật về người đang cầm hội thoại. Khi hai cái lệch nhau, chat nhường CRM. Vì sao là một service riêng chứ không nằm trong SocialChatService. Luật này có hai đầu: một đầu ở miền chat (vừa gắn khách vào hội thoại) và một đầu ở miền CRM (vừa đổi người phụ trách khách). Đặt ở giữa thì cả hai đầu gọi được cùng một luật; đặt trong một trong hai miền thì miền kia hoặc phải chép lại luật, hoặc phải phụ thuộc ngược. Cố ý KHÔNG inject ICustomerService. Chiều ngược lại đã tồn tại — CustomerService.AssignManager gọi vào đây cho tình huống 3 — nên inject nó là dựng một vòng phụ thuộc. Vì thế dòng đồng phụ trách được chèn thẳng qua repository, kèm phép dò trùng đúng bằng chỉ số duy nhất của bảng.

Tình huống 1 và 2 của §3.4 — vừa gắn hội thoại với một khách hàng.

Tình huống 3 của §3.4 — Customer.ManagerId vừa đổi, kéo hội thoại đang mở của khách đó theo.

true khi lần đổi này đến từ yêu cầu của khách (duyệt CustomerManagerChangeRequest): người cũ mất luôn quyền xem, đúng quyết định §6.2. false cho lần gán hành chính bình thường — người cũ vẫn đọc được lịch sử. Số hội thoại đã chuyển

Đổi người phụ trách một hội thoại qua sổ phân công, rồi phát realtime đúng thứ tự.

Kênh này có đang ở chế độ tự phân phối không. Không tra được thì coi là KHÔNG.

Fail-closed, và đây là chiều an toàn duy nhất: không chạy luật §3.4 thì hội thoại nằm đúng chỗ nó đang nằm; chạy nó trên một kênh không biết chế độ là tự bật một hành vi mà không ai bật, đúng thứ nguyên tắc số 1 cấm.

Những người còn đọc được hội thoại này nhờ một lượt giữ cũ, trừ người sắp nhận.

Nhả hội thoại về hàng chờ với lý do cắt quyền xem, rồi phát realtime đúng thứ tự.

Ghi người đang cầm hội thoại vào danh sách đồng phụ trách của khách. Trả true nếu vừa thêm mới.

Chèn thẳng qua repository thay vì gọi ICustomerService.AddCoManager vì lý do vòng phụ thuộc đã ghi ở XML-doc của interface. Phép dò trùng dưới đây khớp đúng chỉ số duy nhất (CustomerId, UserId) của bảng — bỏ nó đi là để database ném lỗi giữa một thao tác gắn khách hoàn toàn hợp lệ.

Báo trưởng nhóm của kênh khi chat và CRM nói hai chuyện khác nhau mà máy không tự khớp được.

Đọc nhật ký quyết định phân phối cho màn /dieu-phoi-chat (giai đoạn D).

Chỉ ĐỌC. Bảng là append-only — không có đường sửa hay xoá một dòng, chỉ có job dọn theo tuổi.

Tìm trong nhật ký quyết định, đã thu hẹp theo phạm vi kênh của người đọc.

Điền tên người và tên kênh cho cả trang bằng ba truy vấn, không phải ba truy vấn cho mỗi dòng.

Kết quả một lượt chạy máy phân phối trên một hội thoại.

Máy có chạy không. false = kênh không ở chế độ tự phân phối, hoặc hội thoại đã có người.

Có ghi AssignedStaffId thật không. Luôn false ở chế độ thử chạy.

Người được chọn (hoặc sẽ được chọn nếu bật, khi đang thử chạy)

Không chạy vì lý do gì — chỉ để log, không hiển thị cho người dùng.

Máy phân phối khách chat — luật §3.3 nối vào database (giai đoạn D).

Chia đôi có chủ ý với : mọi luật nằm ở hàm thuần bên đó, lớp này chỉ lo nạp bảng đầu vào, ghi nhật ký và giành hội thoại. Nhờ thế bảng ca của luật kiểm được mà không cần một dòng dữ liệu nào, đúng yêu cầu §3.10. Chỉ chạy trên kênh . Kênh Shared giữ nguyên hành vi hôm nay (§6.3), còn FixedOwner là kênh một chủ của đợt Zalo cá nhân — dựng nhánh cho nó bây giờ, khi chưa có kênh nào ở chế độ ấy, là dựng thêm một nhánh chết đúng bài học PP-11.

Chạy máy cho một hội thoại. Không chạm gì nếu kênh không tự phân phối hoặc hội thoại đã có người giữ.

Hội thoại vừa nhận tin inbound Mốc quyết định — tham số chứ không đọc đồng hồ, để bản phát lại đặt được mốc lịch sử Máy chạy thật hay bản phát lại lịch sử

Dựng bảng ứng viên và chọn người, không ghi gì cả. Dùng cho bản phát lại, vốn tự quản lý trạng thái tải trong bộ nhớ thay vì đọc lại database sau từng lượt.

Cách viết CandidatesJson. camelCase đúng như §3.2 đặc tả ({staffId, weight, openCount, todayCount, score, excludedReason}) — đây là một tài liệu dữ liệu, không phải một phản hồi REST, nên nó không theo lệ PascalCase của API.

Nhân trọng số phân phối suy từ điểm chất lượng vào bảng ứng viên — chỉ khi công tắc Chat.Quality.AffectsDistribution bật (giai đoạn F).

Đây là chỗ duy nhất giai đoạn F chạm vào đường phân phối; mọi thứ khác của giai đoạn ấy chỉ đọc. Công tắc tắt thì hàm này thoát ngay và bảng ứng viên giữ nguyên trọng số của giai đoạn D — máy chia đều y hệt trước, đúng mục 3 của nguyên tắc số 1: "Điểm chất lượng không được ảnh hưởng phân phối trước khi có dữ liệu." Người có WeightOverride KHÔNG bị nhân. §3.2 định nghĩa cột ấy là *"bỏ qua điểm, ép trọng số; dùng khi sale mới cần kèm"* — nhân điểm chồng lên một giá trị đã ép là làm hỏng đúng công cụ mà quản lý dùng để can thiệp bằng tay. Đây là lý do tồn tại: Weight một mình không phân biệt được "không ai ép nên lấy 1,0" với "ép đúng 1,0". Chưa có dòng điểm thì giữ nguyên trọng số, không rơi về sàn 0,4. Một sale vừa được thêm vào kênh hôm nay chưa được job 03:20 chấm; cho họ trọng số sàn là phạt họ vì job chưa chạy. Cùng lý lẽ với sàn 0,4 của chính công thức: một người không được chia khách là một người không bao giờ có dữ liệu để cải thiện điểm. Bản phát lại không đi qua đây — ChatDistributionReplayService gọi thẳng GetDistributionCandidatesAsync chứ không qua máy. Cố ý: điểm trong ChatQualitySummary là ảnh chụp của hôm nay, còn bản phát lại dựng lại quyết định của ba ngày trước. Áp điểm hôm nay lên lịch sử là trộn hai thời điểm vào một bảng đối chiếu, cùng họ giới hạn với PP-28, PP-29 và với tập loại trừ rỗng của §15.5.

Những người đã bị thu hồi quyền xem hội thoại này — họ không bao giờ được chọn lại.

Đặt ở đây, trong cửa chung EvaluateAsync, chứ không ở riêng đường thu hồi quá hạn: cả ba đường gọi máy chia (tin của khách đến, lượt quét hàng chờ, lượt thu hồi quá hạn) đều phải chịu hàng rào này. Vá riêng một đường là để nguyên hai đường kia — đúng hình dạng F-5 đã cắn ở giai đoạn C. ChatAgentPresenceService.TraLaiUyQuyenAsync đã có hàng rào đối xứng từ giai đoạn C. Đường của máy thì chưa, và /security-review của giai đoạn E tìm ra — vì E biến đường ấy thành tự động, chạy mỗi 2 phút.

Số hội thoại chưa đóng mỗi người đang giữ — toàn hệ thống, không theo kênh.

Trần MaxOpenPerStaff nói về sức chứa của một con người, và một sale phụ trách ba kênh vẫn chỉ có một cái đầu. Đếm theo kênh là cho phép người ấy giữ ba lần trần.

Số lượt nhận từ 00:00 hôm nay và lần nhận gần nhất — hai số của luật 2, lấy trong một truy vấn.

Đếm trên sổ phân công chứ không trên hội thoại đang giữ: "phần việc hôm nay của tôi" là số khách tôi đã nhận, không phải số khách tôi còn đang cầm. Đếm theo cái đang cầm thì người xử lý nhanh, đóng hội thoại sớm, sẽ liên tục bị chia thêm — tức là hệ thống phạt người làm tốt. Cửa sổ đếm là ngày hiện tại theo múi giờ cấu hình, không phải 7 ngày trượt: sale nghỉ nửa ngày quay lại sẽ không bị dồn bù, và "phần của tôi hôm nay" là đơn vị sale hiểu. Múi giờ lấy từ chính cấu hình giờ làm việc, nếu không thì nửa đêm của phép đếm lệch với nửa đêm của người dùng.

Tải hôm nay ở chế độ thử chạy, đếm trên nhật ký quyết định thay vì trên sổ phân công.

Vì sao phải đếm ở nguồn khác, và vì sao thiếu nó thì cả bước 5 của trình tự lên production trở nên vô nghĩa. Chế độ thử chạy cố ý KHÔNG ghi lượt giữ nào, nên sổ phân công đứng im. Đếm tải ở đó thì TodayCount của mọi người luôn bằng 0, luật 2 hoà tuyệt đối ở mọi lượt, và phép xử hoà rơi xuống "mã nhỏ nhất" — tức là một người duy nhất được ghi là người sẽ nhận cho mọi quyết định trong ngày. Bảng đối chiếu đọc từ nhật ký ấy sẽ báo 100 % / 0 % / 0 % và người vận hành kết luận thuật toán chia lệch — trong khi cái lệch là do chính phép đo. Vòng phản hồi phải khép: ở chế độ thử, "người này đã nhận bao nhiêu hôm nay" chính là "máy đã CHỌN người này bao nhiêu lần hôm nay". Chỉ đếm dòng : bản phát lại có bộ đếm riêng trong bộ nhớ, và trộn hai nguồn vào một phép đếm là đúng thứ cột Source sinh ra để ngăn.

Ai vừa nhả chính hội thoại này trong quãng nghỉ.

Sale đang phụ trách hồ sơ khách của hội thoại — nguồn của luật 1.

Customer.ManagerId là nguồn sự thật về sale của khách; khi nó lệch với AssignedStaffId thì chat nhường CRM (§3.4). Ở đây chỉ đọc, không bao giờ ghi.

00:00 của ngày chứa , tính theo múi giờ cấu hình.

Ghi một dòng . Gọi ở mọi nhánh — kể cả nhánh không ai nhận và nhánh thua tranh chấp.

Dòng quyết định gần nhất của hội thoại này có phải cũng là "không ai đủ điều kiện" không.

Vì sao phải có phép này. Job quét chạy mỗi 2 phút trên mọi hội thoại còn nằm hàng chờ. Không có nó thì một hội thoại khách nhắn lúc 22 giờ sinh ra một dòng nhật ký giống hệt nhau mỗi 2 phút suốt đêm — khoảng 435 dòng cho một hội thoại, và ở chế độ thử chạy thì con số ấy là 720 dòng mỗi ngày cho mọi hội thoại chưa ai nhận. Màn nhật ký sinh ra để trả lời "sao tôi không được chia khách"; một bảng ngập những dòng lặp không trả lời được câu nào. Điều này KHÔNG làm mất thông tin nào. Lượt VÀO hàng chờ vẫn có đúng một dòng, và mọi lần kết quả đổi — có người nhận, hoặc thua tranh chấp — đều được ghi. Cái bị bỏ là những lượt thử lại cho ra đúng kết quả cũ, tức là những lượt không mang tin gì mới. Đúng lý lẽ của cột QueueAlertedAt ở tầng thông báo, chỉ khác chỗ áp dụng. Đánh đổi đã biết: nếu LÝ DO không ai nhận đổi (cả đội ngoài giờ → cả đội bận) mà vẫn là "không ai nhận", lần đổi ấy không được ghi. Chấp nhận: câu hỏi màn này phục vụ là "có ai nhận không", không phải "vì sao không ai nhận, theo từng phút".

Phát lại tin inbound lịch sử qua máy phân phối để dựng bảng đối chiếu "nếu bật thì ai nhận bao nhiêu" — bằng chứng của cổng D2.

Vì sao phát lại thay vì chờ ba ngày. Plan có một mâu thuẫn đã được chốt trước khi viết dòng code này: "Xong khi" của giai đoạn D đòi dry-run ba ngày trên dữ liệu thật, trong khi trình tự lên production xếp dry-run là bước 5 — sau khi đã chạy migration và bật hàng rào trên production. Bật hàng rào production chỉ để lấy số là làm đúng thứ mà sổ nợ PP-16 bảo đừng làm (sổ kết nối SignalR còn là bộ nhớ một tiến trình). Lối ra đã chốt là phát lại lịch sử trên dev, và nó khả thi vì §3.3 đã chốt thuật toán là xác định: cùng đầu vào cho cùng kết quả, nên phát lại cho ra đúng bảng mà ba ngày chờ sẽ cho. Không bao giờ ghi AssignedStaffId. Mọi dòng nhật ký nó sinh ra mang Source = Replay và IsDryRun = true. Cột Source tồn tại chính vì lượt phát lại và lượt chạy thật ở chế độ thử cùng ghi IsDryRun = 1 — trộn hai thứ là đọc một bảng phân bố pha hai hiệu ứng mà không biết.

Chạy một lượt phát lại và trả về bảng đối chiếu.

Đầu cửa sổ (bao gồm) Cuối cửa sổ (không bao gồm) Chỉ một kênh; 0 = mọi kênh đang tự phân phối

Trần độ dài cửa sổ phát lại.

Một lượt phát lại ghi một dòng nhật ký cho mỗi quyết định; không có trần thì một lời gọi nhỡ tay quét cả năm lịch sử và sinh ra một bảng không ai đọc nổi. 31 ngày đủ rộng cho mọi cửa sổ đối chiếu có nghĩa (plan chỉ đòi 3 ngày).

Số lượt quét giả lập mỗi ngày, đặt ở đầu buổi sáng và đầu buổi chiều.

Job thật chạy mỗi 2 phút, nhưng mô phỏng 720 lượt quét mỗi ngày chỉ để chứng minh cùng một điều là 720 lần đọc trạng thái sẵn sàng cho một con số không đổi. Hai mốc này bắt đúng thứ cần bắt: hội thoại rơi vào hàng chờ vì đến ngoài giờ làm sẽ được giao lại vào đầu ca kế tiếp. Sai số so với job thật là vài phút, và bảng đối chiếu đo ai nhận bao nhiêu chứ không đo nhận lúc mấy giờ.

Một tin của khách trong cửa sổ phát lại.

Một tin của khách trong cửa sổ phát lại.

Một mốc trên tuyến thời gian phát lại.

Một mốc trên tuyến thời gian phát lại.

Trộn tin inbound với các mốc quét giả lập, theo đúng thứ tự thời gian.

Trạng thái tải trong lúc phát lại — đếm trong bộ nhớ, không đọc database.

Phải đếm trong bộ nhớ vì database mang trạng thái hôm nay: hỏi nó "người này đã nhận bao nhiêu khách hôm 26/08" thì nó trả lời bằng số của hôm nay, và bảng đối chiếu thành ra vô nghĩa. Giới hạn đã biết: hội thoại trong bản mô phỏng không bao giờ đóng, nên số đang giữ chỉ tăng. Với cỡ mẫu của dev (62 hội thoại, 3 người) con số cao nhất vẫn dưới trần 30 nên nó không đổi kết quả; ở cửa sổ dài hơn thì trần sẽ chạm sớm hơn thực tế và bảng đối chiếu sẽ báo thừa lượt "không ai đủ điều kiện". Nói ra thay vì giấu.

Trạng thái tải trong lúc phát lại — đếm trong bộ nhớ, không đọc database.

Phải đếm trong bộ nhớ vì database mang trạng thái hôm nay: hỏi nó "người này đã nhận bao nhiêu khách hôm 26/08" thì nó trả lời bằng số của hôm nay, và bảng đối chiếu thành ra vô nghĩa. Giới hạn đã biết: hội thoại trong bản mô phỏng không bao giờ đóng, nên số đang giữ chỉ tăng. Với cỡ mẫu của dev (62 hội thoại, 3 người) con số cao nhất vẫn dưới trần 30 nên nó không đổi kết quả; ở cửa sổ dài hơn thì trần sẽ chạm sớm hơn thực tế và bảng đối chiếu sẽ báo thừa lượt "không ai đủ điều kiện". Nói ra thay vì giấu.

Lượt quyết định gần nhất của hội thoại này có phải cũng là "không ai nhận" không.

Hội thoại này còn cần một quyết định không (chưa ai nhận trong bản mô phỏng).

Cửa sổ đếm của luật 2 là NGÀY, nên qua nửa đêm là đặt lại về 0.

Lệch lớn nhất giữa hai người cùng trọng số, tính bằng phần trăm trên người nhận nhiều hơn — đúng con số mà ngưỡng 20 % của cổng D2 nói tới.

So theo cặp cùng trọng số chứ không so với một trung bình chung: hai người trọng số 1,0 và 0,5 lệch nhau 50 % là đúng thiết kế, không phải lỗi. Ngưỡng của cổng chỉ có nghĩa khi hai vế thật sự đáng bằng nhau.

Câu cảnh báo về độ tin cậy. Rỗng nghĩa là bảng đọc được như một bảng phân bố.

Bắt buộc phải có vì dev đúng là chỗ mà cảnh báo này áp dụng: số đo D0-4 đếm được kênh 2 chỉ có 2 người và 3 hội thoại. Trình bày một tỉ lệ ở đó như thể nó chắc chắn là nói dối bằng một con số đúng.

Xoá mọi dòng phát lại cũ của những kênh sắp phát lại, để chạy lại không cộng đôi.

Chỉ chạm dòng . Dòng của máy chạy thật là append-only và không đường nào ở đây xoá được chúng — đó là lý do cột Source tồn tại. Cố ý KHÔNG kẹp theo cửa sổ ngày. Bản đầu tiên có kẹp, và nó để lọt đúng thứ nó định dọn: DecidedAt của một dòng phát lại lấy từ mốc tin nhắn, mà dev có tin đề ngày 2025-08-26 — sớm hơn hội thoại sớm nhất đúng một năm. Dòng sinh ra từ tin ấy nằm ngoài mọi cửa sổ hợp lý nên phép dọn không bao giờ với tới, và nó cộng thêm một bản sao sau mỗi lần chạy lại. Dọn theo KÊNH thì đúng cả về nghĩa: một lượt phát lại sở hữu nhật ký phát lại của những kênh nó phát. Để bản phát lại của cửa sổ này nằm cạnh bản của cửa sổ khác là đúng thứ "trộn hai hiệu ứng vào một bảng" mà cột Source sinh ra để ngăn.

Một người đang phụ trách kênh, kèm trọng số — kết quả của IChatChannelStaffService.GetDistributionCandidatesAsync.

Nhân viên (User.Id)

ChatChannelStaff.WeightOverride, hoặc 1,0 khi không ai ép

Trọng số này do người vận hành ép bằng WeightOverride, không phải giá trị mặc định.

Cần một cờ riêng vì một mình không phân biệt được "không ai ép nên lấy 1,0" với "có người ép và họ ép đúng 1,0". Giai đoạn F đọc cờ này: §3.2 định nghĩa WeightOverride là *"bỏ qua điểm, ép trọng số; dùng khi sale mới cần kèm"*, nên điểm chất lượng không được nhân chồng lên một giá trị đã ép — ép là ép.

Một ứng viên của lượt phân phối, đã kèm sẵn lý do bị loại mà chỉ tầng chạm database mới biết (trạng thái sẵn sàng, tải đang giữ, vừa nhả hội thoại này).

Nhân viên (User.Id)

Trọng số. Hôm nay là ChatChannelStaff.WeightOverride ?? 1.0; giai đoạn F sẽ nhân thêm trọng số điểm chất lượng sau công tắc Chat.Quality.AffectsDistribution.

Số hội thoại đang giữ chưa đóng — dùng cho trần, không dùng cho phép chọn

Số hội thoại đã nhận từ 00:00 hôm nay — tử số của phép chọn

Lần gần nhất người này nhận một hội thoại. null = chưa nhận bao giờ.

Lý do bị loại mà tầng gọi đã xác định được. nghĩa là chưa có lý do nào — luật vẫn có thể tự loại thêm vì trọng số ≤ 0.

Bảng đầu vào của một lượt quyết định. Không có gì ở đây chạm database.

Mọi người đã cân nhắc, kể cả người bị loại

Sale đang phụ trách hồ sơ khách của hội thoại này (Customer.ManagerId). null = hội thoại chưa gắn khách, hoặc khách chưa có người phụ trách.

Hội thoại ẩn danh — nền tảng không cấp định danh bền vững cho khách

Hội thoại đã gắn CustomerId

Ảnh chụp một ứng viên đúng như luật đã nhìn thấy — chính là một phần tử của ChatAssignmentDecision.CandidatesJson.

Điểm chọn todayCount / weight. null khi trọng số ≤ 0.

Kết quả một lượt quyết định, đủ để ghi thẳng thành một dòng nhật ký.

Câu giải thích nhánh mà bảng ứng viên không nói được (chủ yếu là luật 1)

Bảng ứng viên đúng như luật đã nhìn. Trả ra từ đây thay vì để tầng gọi tự dựng lại, vì hai bản dựng độc lập là hai bản sẽ lệch nhau — và lúc đó nhật ký nói một đằng, máy làm một nẻo.

Luật phân phối §3.3 — hàm thuần: bảng đầu vào cho ra người được chọn, không chạm database, không đọc đồng hồ. Vì sao tách thuần. Đây là đoạn code quyết định sale nào được chia bao nhiêu khách, tức là quyết định thu nhập của người ta. Nó phải kiểm được bằng một bảng ca đọc hết trong một màn hình, và phải tái dựng được từ nhật ký: cùng đầu vào thì cùng kết quả, không đồng hồ, không ngẫu nhiên, không con trỏ vòng quay phải lưu ở đâu đó. Trọng tâm là luật 2, không phải luật 1. Số đo Đ2 đếm được chỉ 3,17 % hội thoại gắn CustomerId, và số đo D0-6 của giai đoạn D còn mạnh hơn: trên toàn bộ lịch sử dev, luật 1 chạy 0 lần, vì hai hội thoại có khách đều trỏ về một người không phụ trách kênh nào. Luật 1 vẫn là luật nghiệp vụ quan trọng hơn (quyết định §6.1, đừng bàn lại), nhưng thứ quyết định gần như toàn bộ lưu lượng thật là luật 2 — nên nó là thứ phải được kiểm kỹ hơn, ngược với cảm giác về thứ tự ưu tiên.

Luật 1 — khách quen về đúng sale đang phụ trách hồ sơ khách (§6.1)

Luật 2 — ít việc nhất so với trọng số

Không ai đủ điều kiện — hội thoại vào hàng chờ

Có người khác giữ hội thoại trước khi lượt này ghi kịp

Trọng số dùng khi không ai đặt WeightOverride

Chọn người nhận hội thoại theo §3.3.

Thứ tự: lọc người đủ điều kiện → luật 1 (khách quen) → luật 2 (ít việc nhất so với trọng số) → không ai thì no-candidate. Hoà thì xử thế nào và vì sao. Hoà điểm thì ưu tiên người có cũ nhất, và người chưa nhận bao giờ đứng trước tất cả — đó là ý nghĩa của việc coi null là cũ nhất. Vẫn hoà thì mã nhỏ nhất, để kết quả xác định hoàn toàn. Không có bước cuối cùng ấy thì hai lần chạy trên cùng dữ liệu có thể ra hai người khác nhau tuỳ thứ tự database trả về, và bảng đối chiếu của cổng D2 mất ý nghĩa.

Điểm chọn của luật 2: số hội thoại nhận hôm nay chia cho trọng số. Trọng số ≤ 0 thì phép chia không có nghĩa và trả null — người đó đã bị loại bằng .

Bốn điều kiện lọc của §3.3 gộp thành một lý do duy nhất — hàm thuần, dùng chung cho máy chạy thật và cho bản phát lại lịch sử.

Thứ tự chấm là cố định và có ý nghĩa: điều kiện 1 (phụ trách kênh) trước điều kiện 2 (sẵn sàng), rồi 3 (trần) và 4 (vừa nhả). Người vừa nghỉ việc hiện ra là "đã nghỉ việc" chứ không phải "quá trần hội thoại", vì lý do đầu mới là lý do người đọc cần biết. Dùng chung ở hai nơi là điều kiện để bảng đối chiếu của cổng D2 nói về đúng cái máy sẽ chạy. Hai bản chép tay là hai bản sẽ lệch, và lúc đó cổng D2 nghiệm thu một thuật toán không tồn tại. Mã người có mặt trong bảng ứng viên chỉ vì họ là sale của khách, chứ không phụ trách kênh. 0 khi không có ai như thế.

Luật 1. Trả về người được chọn (nếu áp dụng được) kèm câu giải thích cho nhật ký.

Ba nhánh "không áp dụng" đều phải nói ra được lý do, vì trên dữ liệu thật chúng là nhánh thường gặp chứ không phải nhánh hiếm: hội thoại ẩn danh (sổ nợ PP-4), hội thoại chưa gắn khách (96,8 % theo Đ2), và khách quen không đủ điều kiện (đúng 100 % số ca có khách trên dev, theo D0-6).

Mốc so hoà. Chưa nhận bao giờ thì đứng đầu hàng — DateTimeOffset.MinValue chính là cách nói "cũ nhất có thể".

Mô tả tiếng Việt của một lý do loại, dùng trong câu giải thích của nhật ký.

Quy trạng thái sẵn sàng hiệu lực (§3.5) về lý do bị loại của nhật ký phân phối. Chỉ mới nhận khách mới — đúng luật ChatAgentAvailability.NhanKhachMoiDuoc. Hàm này chỉ dịch vì sao không sang ngôn ngữ của nhật ký, không định nghĩa lại luật đó.

Tên khoá AppConfig của máy phân phối — seed bằng migration M202608291610, không hardcode giá trị ở nơi khác. Theo đúng khuôn của giai đoạn C: hằng tên khoá ở một chỗ, một lớp duy nhất diễn giải chuỗi, InvariantCulture, giá trị hỏng rơi về mặc định đã biết đúng thay vì ném lỗi giữa một webhook của khách.

Chế độ thử chạy: máy chạy đủ, ghi đủ nhật ký, không ghi AssignedStaffId. true / false. Mặc định bật — mục 2 của nguyên tắc số 1.

Trần số hội thoại chưa đóng mà một sale được giữ cùng lúc

Vừa nhả một hội thoại thì bấy nhiêu phút sau máy không giao lại chính hội thoại đó cho người ấy. 0 = tắt hẳn quãng nghỉ.

Chờ trong hàng chờ quá bấy nhiêu phút thì báo trưởng nhóm của kênh

Đọc và diễn giải các khoá cấu hình của máy phân phối.

Tách riêng khỏi vì hai nhóm khoá có hai vòng đời khác nhau: giờ làm việc là thứ người vận hành đặt một lần rồi quên, còn DryRun và các trần phân phối là thứ họ sẽ chỉnh trong tuần đầu chạy thật. Gộp vào một interface thì mọi lời gọi đọc giờ làm cũng kéo theo phụ thuộc vào những khoá chưa tồn tại lúc nó được viết.

Có đang ở chế độ thử chạy không. Mặc định true: khoá đọc không ra thì coi như đang thử, chứ không coi như đã bật.

Chiều rơi của giá trị hỏng ở đây là một quyết định an toàn, không phải tuỳ tiện. Hai hướng hỏng không cân nhau: rơi về "đang thử" thì tệ nhất là khách nằm hàng chờ thêm một lúc và có người bấm tay; rơi về "đã bật" thì máy bắt đầu tự chia khách trên một hệ thống mà không ai định bật, và đó đúng là thứ nguyên tắc số 1 cấm.

Trần hội thoại đang giữ mỗi sale (mặc định 30 — đề xuất CH-5)

Quãng nghỉ sau khi nhả, tính bằng phút (mặc định 30). 0 = tắt.

Ngưỡng báo trưởng nhóm khi hội thoại nằm hàng chờ, tính bằng phút (mặc định 15)

Thử chạy hay không khi khoá đọc không ra. Xem để biết vì sao chiều này.

Trần hội thoại mỗi sale — CH-5 đề xuất 30

Quãng nghỉ sau khi nhả. 30 phút là điểm khởi đầu chứ không phải hằng số: chưa có số đo nào về việc sale nhả rồi nhận lại, vì trước giai đoạn D chưa có máy nào giao lại. Ngắn hơn thì vô nghĩa (nhả xong hai phút sau nhận lại đúng hội thoại vừa nhả), dài hơn thì khách nằm chờ trong khi kênh chỉ có vài người.

Ngưỡng báo hàng chờ. Lấy đúng ngưỡng nhắc SLA đã chốt từ số đo Đ5 (N = 206, trong giờ làm): 15 phút nằm giữa p75 (4,3′) và p90 (35,4′).

Kéo các tin gần nhất của hội thoại từ nền tảng về để bù tin webhook không chở tới. Ca gốc (2026-10-24): Page tự trả lời riêng từ bình luận "Ib" của khách (private reply) lúc 15:01, khách trả lời bằng số điện thoại lúc 15:18. LADA chỉ có con số; hộp thư Meta Business Suite có cả câu hỏi đứng trước. Facebook không cam kết bắn message_echoes cho private reply, nên chờ webhook là không đủ — phải chủ động hỏi API hội thoại. Hai đường vào: job chat-history-sync tự kéo cho hội thoại MỚI, và nút "Đồng bộ lại" trên khung chat cho hội thoại bất kỳ. Cả hai đi qua đúng một hàm chèn, chỉ khác cách chọn hội thoại. Lớp này không biết nền tảng nào — hỏi . Tách khỏi SocialChatService vì lớp đó đã quá to, và việc này không dính gì tới gửi tin hay phân công.

Lượt quét của job: kéo lịch sử cho hội thoại mới chưa kéo lần nào.

Nút "Đồng bộ lại": kéo lịch sử cho một hội thoại trong phạm vi ĐỌC của người bấm. Phạm vi đọc chứ không phải phạm vi ghi: việc này chỉ chép lại thứ đã có trên nền tảng vào đúng hội thoại người đó đang được xem, không gửi gì cho khách và không đổi người phụ trách — cùng lý lẽ với nút Lịch sử phân công vẫn còn ở hội thoại chỉ-đọc.

Tổng kết một lượt quét của job.

Số hội thoại đã hỏi nền tảng

Tổng số tin còn thiếu đã chèn vào

Hội thoại nền tảng từ chối hẳn — đã đánh dấu, không thử lại

Hội thoại gặp lỗi tạm — để nguyên, lượt sau thử lại

Tên ghi vào cột audit cho tin và hội thoại do lớp này ghi

Job chỉ tự kéo hội thoại tạo trong khoảng này. Hội thoại cũ hơn thì để nút bấm lo: lượt đầu sau deploy không được quét ngược cả kho, và một hội thoại hỏng mạng mãi không được thử lại vô hạn.

Đợi hội thoại "lắng" một phút rồi mới kéo. Webhook tạo hội thoại và lưu tin đầu trong cùng một request, nhưng Facebook hay gom vài tin sát nhau thành nhiều request — kéo ngay giây đầu là đua với chính các request đó.

Cửa sổ nhận hai bản ghi là một tin khi mã tin không khớp nhau — cùng độ rộng với cửa sổ đối chiếu tiếng vọng của lõi (SocialChatService.OutboundEchoWindow).

Số hội thoại tối đa mỗi lượt quét — mỗi hội thoại là một lời gọi nền tảng

Kết quả kéo một hội thoại

Kết quả kéo một hội thoại

Chèn những tin nền tảng có mà LADA chưa có, theo thứ tự thời gian.

Nhận diện trùng hai lượt. Lượt 1 theo mã tin — đường chính, vì webhook, Send API và API hội thoại của Facebook cùng dùng mã m_…. Lượt 2 theo nội dung trong cửa sổ hai phút, cho phòng khi mã hai nguồn lệch nhau: thiếu lượt này thì mỗi lần kéo nhân đôi cả khung chat. Mỗi bản ghi có sẵn chỉ được nhận MỘT lần, để khách gõ "ok" hai lần thì vẫn ra hai tin. Tin rỗng (tin mẫu có nút của công cụ tự động, tin chia sẻ bài viết) bị bỏ: không đọc được nội dung thì chèn vào chỉ thêm một bong bóng trống.

Hai bản ghi có phải cùng một tin không, khi mã tin không giúp được.

Tin chữ kéo về có phải chú thích của một bản ghi ảnh LADA đã gửi không. LADA gửi ảnh kèm chú thích thành MỘT bản ghi, còn Facebook giữ thành HAI tin (ảnh + chữ) — chèn tin chữ là mọc thêm một bong bóng lặp lại đúng câu chú thích dưới tấm ảnh.

Cùng chiều, cùng khoảng thời gian, và bản ghi có sẵn đã thật sự tới nền tảng.

Cập nhật dòng xem trước và mốc tin khách sau khi chèn.

Cố ý KHÔNG đụng UnreadCount, WaitingSinceAt, trạng thái hay máy phân phối: tin kéo về là tin CŨ đã xảy ra, không phải việc mới. Cộng chưa đọc là bắt nhân viên đọc lại thứ họ có thể đã thấy trên Business Suite; mở lượt chờ là bấm đồng hồ hạn phản hồi cho một câu khách nói từ trước. LastInboundAt thì có nâng nếu tin khách kéo về MỚI hơn — đó là sự thật về cửa sổ trả lời của nền tảng, giữ mốc cũ là cảnh báo sai.

Tải tệp đính kèm chat (ảnh, video, tin thoại, tệp) từ CDN của Zalo / Facebook về máy chủ LADA rồi thay ChatMessage.AttachmentUrl bằng URL LADA (sổ nợ SC-9). Lý do phải làm: URL nền tảng trả về CÓ HẠN. Đo 2026-10-23 trên DB dev: ảnh khách gửi qua Zalo ngày 08/10 15:28 đã 404, ngày 09/10 20:39 còn sống — tức sống khoảng 14 ngày, không phải 30. Tệp, video, tin thoại cùng nhịp. Ảnh OA gửi (brcast-msg-photo.zadn.vn), nhãn dán và gif thì còn sống sau 46 ngày. Facebook: ảnh 8 ngày tuổi còn sống, chưa đo được mốc chết. Chạy bằng job quét (chat-media-archive), KHÔNG trên đường webhook: Zalo đòi trả lời trong 2 giây và Facebook trong 5 giây, còn một video vài chục MB tải mất cả chục giây. Trễ vài phút không mất gì vì URL nền tảng còn sống cả tuần. Cũng nhờ vậy mà tin nhân viên gửi thẳng từ app Zalo / Messenger (echo — 101 trên 103 ảnh/tệp chiều ra của DB dev) được lưu luôn, không cần một đường riêng. Tệp lưu xuống cùng chỗ với ảnh LADA gửi đi (Media.RootPath), nên cũng mang đúng rủi ro của chỗ đó: site media phục vụ tĩnh, KHÔNG chấm quyền — ai có URL là xem được. Tên tệp là GUID nên không đoán được, nhưng URL lọt ra ngoài thì không thu hồi được (giống mọi ảnh trong Media.RootPath hôm nay).

Lưu một lượt các tin còn chờ, cũ trước mới sau (tệp cũ gần mốc chết hơn). Một tệp hỏng không làm dừng cả lượt.

Tên HttpClient đã đăng ký ở DependencyRegister

Tên ghi vào UpdatedByUserName — cùng tên job để tra ngược được từ dòng dữ liệu.

Trần số lần thử. Lỗi tạm (mạng, 5xx, quá hạn chờ) được thử lại ở các lượt sau, năm lượt là khoảng 25 phút — đủ qua một lần CDN chập chờn, mà tệp hỏng vĩnh viễn thì không bị gọi mãi.

Số tin mỗi lượt. Lượt 5 phút một lần → ~8.600 tin/ngày, dư cho tồn đọng lúc mới bật.

Chỉ quét tin trong 90 ngày — phủ trọn lịch sử chat hiện có (bắt đầu 2026-09-07). Không lấy 30: tệp khách gửi qua Zalo chết sau ~14 ngày, nhưng ảnh OA gửi, nhãn dán và gif còn sống sau 46 ngày (đo 2026-10-23), cửa sổ hẹp là bỏ rơi đúng nhóm còn cứu được. Một link đã chết chỉ tốn một lời gọi 404 rồi bị đặt mức trần, nên cửa sổ rộng không làm job chạy nặng hơn về lâu dài.

Ngân sách thời gian một lượt — dưới chu kỳ 5 phút của job, để lượt sau không phải xếp hàng chờ khoá [DisableConcurrentExecution] của lượt trước.

Trần dung lượng một tệp. Video mẫu trên DB dev nặng 4,2 MB; 100 MB dư cho video dài mà vẫn chặn được một tệp bất thường lấp đầy ổ đĩa. Quá trần thì không lưu, ghi lý do.

Loại tin mang tệp do nền tảng lưu hộ. Không có Link / Location / BusinessCard: ba loại đó không có tệp nào để giữ.

Host được phép tải (kể cả tên miền con). Đây là hàng rào SSRF: AttachmentUrl đến từ payload webhook, và lần tải chạy từ chính máy chủ LADA. Danh sách lấy từ dữ liệu thật trên DB dev 2026-10-23: Zalo dùng zdn.vn (ảnh, tin thoại, gif), zadn.vn (ảnh OA gửi, nhãn dán), dlfl.vn (tệp), dlmd.me (video); Facebook dùng fbcdn.net, cộng fbsbx.com là CDN tệp của Messenger. Host mới xuất hiện thì tin bị đánh dấu không tải được kèm tên host — đọc lý do là biết phải thêm gì vào đây.

Tải về , đọc luôn 16 byte đầu để nhận dạng định dạng. Tự đi theo chuyển hướng thay vì để HttpClient đi (client đăng ký AllowAutoRedirect = false): đi tự động thì một host hợp lệ chuyển hướng sang địa chỉ nội bộ là lọt qua hàng rào SSRF. Mỗi bước chuyển phải lại nằm trong danh sách host.

Phần mở rộng suy từ CHỮ KÝ NỘI DUNG, hoặc null nếu không thuộc định dạng được lưu. Không tin Content-Type: gif của Zalo về với image/jpeg trong khi nội dung là GIF89a (đo 2026-10-23). Không tin đuôi tệp trên URL trừ đúng một chỗ — phân biệt docx/xlsx/pptx/zip (cùng là ZIP) và doc/xls/ppt (cùng là OLE) — và ở đó đuôi chỉ được CHỌN trong danh sách đóng. Tệp văn bản (txt, csv, html…) không lưu: không có chữ ký để phân biệt với một trang HTML, mà site media phục vụ tĩnh.

Thư mục gốc theo loại tệp. Images là chỗ ảnh chat LADA gửi đi đang nằm, Videos là chỗ VideoService đang dùng — hai thư mục site media đã phục vụ. Files là thư mục MỚI cho tin thoại và tài liệu.

URL đã là của LADA (tin LADA gửi đi trước bản vá ghi AttachmentSystemPath) thì không tải lại. Trả kèm đường dẫn đĩa nếu tệp còn đó.

Nạp lại tin NGAY trước khi ghi rồi chỉ sửa các cột của việc lưu tệp — khoảng hở với webhook còn vài mili giây thay vì cả lượt (xem chú thích ở ). Trả false nếu tin đã bị xoá, hoặc đã có đường dẫn đĩa (lượt khác lưu trước), hoặc URL đã đổi khỏi URL vừa tải.

Ba cột lượt quét cần — cố ý không phải entity, xem .

Ba cột lượt quét cần — cố ý không phải entity, xem .

Kết quả xử lý một tin trong lượt lưu.

Đã tải về và thay URL

URL đã là của LADA — chỉ ghi lại đường dẫn đĩa

Hỏng tạm, lượt sau thử lại

Hỏng vĩnh viễn (tệp đã chết, định dạng không lưu, host lạ) — thôi thử

Tổng kết một lượt của job lưu tệp đính kèm.

Các liên kết điều hướng và khối cấu hình của miền chat có được hiện cho một người hay không (sổ nợ PP-39, PP-46).

Hàm thuần — không chạm database, không đọc HttpContext: nhận danh sách role đã phân giải, trả các cờ. Tách ra đúng cách tách khỏi lớp đẩy tin, và vì đúng một lý do: hai khuôn cùng họ đang chạy trong sản phẩm — CanViewTeam ở ChatQualityController và CanReplay ở ChatDistributionController — đều tính thẳng trong controller và vì thế không có một ca test nào. Một luật quyết định ai thấy gì thì phải có ca test gọi thẳng vào nó. Vì sao cần cờ từ máy chủ. SPA cố ý không nhận danh sách role vào router (xem routers/socialChat.js), nên meta.roles là tài liệu chứ không phải hàng rào — thứ duy nhất ẩn được một liên kết là một cờ như thế này. Chép tên role sang JavaScript là dựng nguồn sự thật thứ hai, và cái lệch chỉ lộ ra khi một sale bấm vào rồi ăn 403. Đây là lần thứ bảy và tám của họ lỗi "route mở cho vai A nhưng API đòi vai B" trong cùng một đợt.

Vai bỏ qua mọi kiểm tra role của hệ thống.

Role đã phân giải qua IUserRoleResolver; null = không có role nào

Kết quả của .

Được thấy liên kết "Điều phối" → /dieu-phoi-chat Được thấy liên kết "Kênh chat" → /kenh-chat, tức dùng được ít nhất một khối trên trang đó Được cấp quyền OAuth / bật-tắt / xoá kênh — hẹp hơn Được thấy khối "Cấu hình kênh" (bưu cục sở hữu + chế độ phân phối) — đòi cả hai ChatChannel.StaffAssign và ChatDistribution.Manage, hoặc Founder; độc lập với Được thấy nút "Tin nhắn nhanh" ở ô soạn tin, nạp danh sách chọn và gửi từ mẫu — ChatConversation.Send hoặc Founder Được thấy nút Thêm/Sửa/Xoá mẫu dùng chung ở /tin-nhan-nhanh — ChatQuickReply.ManageShared hoặc Founder Được thấy nút "Tạo khách hàng mới" trong ô gắn khách — đòi cả hai Customer.CreateOrUpdate và ChatConversation.LinkCustomer, hoặc Founder Được thấy nút "Tạo đơn" của hội thoại đã gắn khách — Order.CreateOrder hoặc Founder

Kết quả của .

Được thấy liên kết "Điều phối" → /dieu-phoi-chat Được thấy liên kết "Kênh chat" → /kenh-chat, tức dùng được ít nhất một khối trên trang đó Được cấp quyền OAuth / bật-tắt / xoá kênh — hẹp hơn Được thấy khối "Cấu hình kênh" (bưu cục sở hữu + chế độ phân phối) — đòi cả hai ChatChannel.StaffAssign và ChatDistribution.Manage, hoặc Founder; độc lập với Được thấy nút "Tin nhắn nhanh" ở ô soạn tin, nạp danh sách chọn và gửi từ mẫu — ChatConversation.Send hoặc Founder Được thấy nút Thêm/Sửa/Xoá mẫu dùng chung ở /tin-nhan-nhanh — ChatQuickReply.ManageShared hoặc Founder Được thấy nút "Tạo khách hàng mới" trong ô gắn khách — đòi cả hai Customer.CreateOrUpdate và ChatConversation.LinkCustomer, hoặc Founder Được thấy nút "Tạo đơn" của hội thoại đã gắn khách — Order.CreateOrder hoặc Founder

Được thấy liên kết "Điều phối" → /dieu-phoi-chat

Được thấy liên kết "Kênh chat" → /kenh-chat, tức dùng được ít nhất một khối trên trang đó

Được cấp quyền OAuth / bật-tắt / xoá kênh — hẹp hơn

Được thấy khối "Cấu hình kênh" (bưu cục sở hữu + chế độ phân phối) — đòi cả hai ChatChannel.StaffAssign và ChatDistribution.Manage, hoặc Founder; độc lập với

Được thấy nút "Tin nhắn nhanh" ở ô soạn tin, nạp danh sách chọn và gửi từ mẫu — ChatConversation.Send hoặc Founder

Được thấy nút Thêm/Sửa/Xoá mẫu dùng chung ở /tin-nhan-nhanh — ChatQuickReply.ManageShared hoặc Founder

Được thấy nút "Tạo khách hàng mới" trong ô gắn khách — đòi cả hai Customer.CreateOrUpdate và ChatConversation.LinkCustomer, hoặc Founder

Được thấy nút "Tạo đơn" của hội thoại đã gắn khách — Order.CreateOrder hoặc Founder

Một khoảng nhật ký trạng thái, đã tách khỏi entity để hàm dựng bảng thời lượng là hàm thuần.

Trạng thái khai báo trong khoảng Bắt đầu khoảng Kết thúc khoảng, null = đang mở Thời hạn trạng thái tự hết, null = không có hạn

Một khoảng nhật ký trạng thái, đã tách khỏi entity để hàm dựng bảng thời lượng là hàm thuần.

Trạng thái khai báo trong khoảng Bắt đầu khoảng Kết thúc khoảng, null = đang mở Thời hạn trạng thái tự hết, null = không có hạn

Trạng thái khai báo trong khoảng

Bắt đầu khoảng

Kết thúc khoảng, null = đang mở

Thời hạn trạng thái tự hết, null = không có hạn

Dựng bảng "trạng thái nào bao nhiêu phút" từ nhật ký trạng thái — hàm thuần, không chạm database, không hỏi đồng hồ. Đây là hàm mà tiêu chí "xong khi" của giai đoạn C nói tới: bảng thời lượng một ngày dựng lại từ ChatAgentPresenceLog khớp từng phút. Và cũng là nơi tiêu chí chấm điểm chat.availability của giai đoạn F sẽ đọc.

Tổng thời lượng từng trạng thái trong cửa sổ [from, to).

Hai phép cắt, và cả hai đều bắt buộc: Cắt theo cửa sổ. Khoảng bắc qua hai đầu cửa sổ chỉ được tính phần nằm trong. Không có phép cắt này thì xem báo cáo của một ngày lại cộng cả thời lượng của hôm trước. Cắt theo hạn. Trạng thái tự khai có hạn thì tự hết lúc ExpiresAt — phần từ đó tới khi dòng thật sự đóng là , không phải trạng thái cũ. Bỏ phép cắt này là đếm một lượt "Bận 30 phút" lúc 9 giờ sáng thành "Bận cả ngày", vì dòng nhật ký chỉ đóng khi người ta bấm đổi trạng thái lần sau. Cách chữa khác duy nhất là một job quét, mà job thì chỉ chính xác tới đúng chu kỳ của nó — "khớp từng phút" sẽ không bao giờ đúng. Không lấp khoảng trống giữa hai dòng nhật ký. Người chưa từng đổi trạng thái lần nào không có dòng nào, và trả về một bảng rỗng là câu trả lời đúng — coi khoảng trống là ở đây nghĩa là bịa ra thời lượng cho người chưa bao giờ dùng tính năng. Ai cần "phần còn lại của ngày" thì tự lấy độ dài cửa sổ trừ đi tổng của bảng này — phép trừ đó nằm ở người gọi vì chỉ họ biết cửa sổ nào có nghĩa (cả ngày hay chỉ giờ làm việc). Các khoảng nhật ký, không cần sắp xếp trước Đầu cửa sổ (tính vào) Cuối cửa sổ (không tính vào) "Bây giờ", dùng làm điểm kết cho khoảng đang mở. Truyền vào chứ không hỏi đồng hồ.

Ba đường GHI của hộp thoại quản lý trạng thái sale có mở cho một người hay không (sổ nợ PP-36, chỗ (b)).

Hàm thuần, cùng lý do và cùng khuôn với . Vì sao BA cờ chứ không một. Ba tab của hộp thoại gọi ba endpoint khác nhau, và bó quyền của chúng không giống nhau: POST presence/staff và POST presence/suspend chỉ nhận ChatAgentPresence.ManageOthers, còn POST presence/delegate nhận thêm ChatDistribution.Manage. Một cờ dùng chung sẽ hoặc ẩn tab "Uỷ quyền tạm" khỏi người điều phối được phép dùng nó, hoặc mở hai tab kia cho người chắc chắn ăn 403 — tức chính lỗi đang chữa, chỉ đổi vai người chịu. Đường ĐỌC không có cờ, và đó là chủ ý. GET presence/staff/{id} cùng POST presence/report mở rộng hơn hẳn — thêm ChatDistribution.Manage và ChatConversation.ViewChannel — nên một trưởng nhóm kênh đọc được bảng thời lượng mà không đặt được trạng thái hộ. Chính khoảng lệch đó là PP-36 (b): hộp thoại mở cho người chỉ có ViewChannel và cả ba tab đều chắc chắn 403. Cờ chỉ phản ánh ROLE, không phản ánh PHẠM VI. Ba đường ghi còn một hàng rào thứ hai theo từng nhân viên đích ("Không tìm thấy nhân viên trong phạm vi quản lý của bạn"), và cố ý không đưa vào đây. Ranh giới: cái gì không bao giờ chạy được thì ẩn đi; cái gì chạy được với người này mà không với người kia thì để nút đó, và để máy chủ trả lời bằng một câu nói đúng lý do. Ẩn theo phạm vi còn cần một cờ cho mỗi dòng nhân viên, mà dòng ấy đi trong SmartTableResult — kiểu không có chỗ cho trường phụ. Role đã phân giải qua IUserRoleResolver

Kết quả của .

Đặt trạng thái hộ — POST presence/staff Tạm ngưng nhận khách — POST presence/suspend Uỷ quyền tạm — POST presence/delegate

Kết quả của .

Đặt trạng thái hộ — POST presence/staff Tạm ngưng nhận khách — POST presence/suspend Uỷ quyền tạm — POST presence/delegate

Đặt trạng thái hộ — POST presence/staff

Tạm ngưng nhận khách — POST presence/suspend

Uỷ quyền tạm — POST presence/delegate

Tên khoá AppConfig của trạng thái sẵn sàng — seed bằng migration M202608291530, không hardcode giá trị ở nơi khác. Đây là những khoá tiền tố Chat. đầu tiên của repo: cấu hình chat trước nay nằm ở appsettings (SocialChat:Zalo:*). Chọn AppConfig có chủ ý — giờ làm việc là thứ người vận hành phải đổi được từ màn quản trị mà không cần deploy lại.

Giờ vào làm, dạng HH:mm

Giờ tan làm, dạng HH:mm

Giờ bắt đầu nghỉ trưa, dạng HH:mm

Giờ kết thúc nghỉ trưa, dạng HH:mm

Ngày làm trong tuần, ngăn cách bằng dấu phẩy, 2 = Thứ Hai … 8 = Chủ Nhật

Trần thời hạn cho trạng thái tự khai Bận / Ra ngoài, tính bằng phút

Trần thời hạn cho trạng thái Nghỉ, tính bằng ngày

Nghỉ từ bấy nhiêu ngày trở lên thì tự uỷ quyền tạm; 0 = tắt hẳn uỷ quyền tự động

Múi giờ ứng dụng, đã được seed sẵn từ migration M202608161200 của đợt chấm công nhưng chưa có dòng code nào đọc cho tới giai đoạn này.

Đọc và diễn giải các khoá cấu hình của trạng thái sẵn sàng.

Tách riêng để chỉ có một nơi diễn giải chuỗi cấu hình — mỗi nơi tự parse một kiểu là mỗi nơi sai một kiểu (bài học phân hệ KPI). Cũng nhờ tách mà test chạy được lớp này thật trên FakeAppConfigService thay vì giả lập chính nó.

Cửa sổ giờ làm việc, đã dựng xong từ 6 khoá cấu hình. Không bao giờ trả null và không bao giờ ném lỗi — giá trị hỏng rơi về .

Trần thời hạn cho Bận / Ra ngoài, tính bằng phút (mặc định 120)

Trần thời hạn cho Nghỉ, tính bằng ngày (mặc định 30)

Ngưỡng ngày nghỉ để tự uỷ quyền tạm (mặc định 1). Trả 0 nghĩa là tắt hẳn uỷ quyền tự động — quản lý vẫn bấm tay được.

Trần mặc định cho Bận / Ra ngoài — §3.5 đề xuất 120 phút

Trần mặc định cho Nghỉ

Ngưỡng uỷ quyền tạm mặc định — CH-7 chốt "nghỉ từ 1 ngày trở lên"

Múi giờ mặc định khi khoá App.TimeZoneOffsetHours đọc không ra

Số thô của một tiêu chí kèm cỡ mẫu — thứ mọi provider phải trả về.

Sample không phải trường tuỳ chọn. Nó là thứ duy nhất phân biệt "điểm 100 vì làm tốt" với "điểm 100 vì có đúng một mẫu", và số đo F-0 làm điều đó thành vấn đề sống còn chứ không phải cẩn thận thừa: trên dev, hai người duy nhất có tin quy được về mình (#251, #1) không giao một phần tử nào với danh sách sale phụ trách kênh (#252…#255).

Số thô — trung vị phút, tỉ lệ phần trăm…

Số quan sát đứng sau . 0 nghĩa là không chấm được, khác hẳn "chấm được và ra 0".

Không có mẫu nào — tiêu chí bị loại khỏi cả tử số lẫn mẫu số của điểm tổng.

Một tiêu chí đã chấm xong: số thô, cỡ mẫu, điểm chuẩn hoá.

Điểm 0–100. null khi cỡ mẫu bằng 0 — không chấm được.

Tiêu chí này có góp vào điểm tổng không

Kết quả gộp điểm của một người.

Điểm tổng 0–100

Trọng số phân phối suy từ

Điểm chưa đủ căn cứ — mang điểm mặc định thay vì số tính ra

Câu tiếng Việt nói vì sao tạm tính; rỗng khi không tạm tính

Tổng cỡ mẫu của mọi tiêu chí chấm được

Số tiêu chí thật sự chấm được

Ngưỡng và chiều của một tiêu chí — phần cần để chấm.

Luật chấm điểm chất lượng chat (giai đoạn F) — hàm thuần: không chạm database, không đọc đồng hồ, không đọc cấu hình.

Cùng khuôn của giai đoạn D và của giai đoạn E, và vì cùng một lý do: đây là phần người ta sẽ đi khiếu nại, nên nó phải kiểm được bằng một bảng ca đầu-vào → đầu-ra mà không cần dựng database. Mượn công thức của KpiEngineService.CalculateScore, không mượn bảng (§3.6): nội suy tuyến tính giữa hai ngưỡng, kẹp hai đầu, rồi nhân trọng số. Chỗ khác duy nhất là mẫu số — KPI chia cho hằng số 100 vì nó ép tổng trọng số phải đúng 100 % mới cho giao chỉ tiêu; ở đây mẫu số là tổng trọng số của những tiêu chí thật sự chấm được. Bốn trong năm tiêu chí rỗng dữ liệu lúc mở màn (số đo F-0), nên chia cho 100 là bắt một tiêu chí duy nhất gánh cả điểm và mọi sale sẽ ra dưới 25 điểm.

Điểm thấp nhất và cao nhất sau chuẩn hoá

Điểm cao nhất sau chuẩn hoá

Sàn trọng số phân phối. 0,4 là cố ý — xem .

Trần trọng số phân phối

Hệ số nhân của điểm trong công thức trọng số

Số chữ số thập phân giữ lại ở mọi bước — khớp KpiEngineService.ScoreDecimals

Chuẩn hoá một số thô về thang 0–100 bằng nội suy tuyến tính giữa và , kẹp hai đầu.

Kẹp chứ không ngoại suy: một sale trả lời trung vị 0,3 phút không được 400 điểm, và một sale trung vị 300 phút không bị âm điểm kéo tụt cả điểm tổng. Đây đúng là điều CapPercent của KPI làm ở đầu trên; đầu dưới thì KPI không cần vì % hoàn thành vốn không âm. Hai ngưỡng bằng nhau là cấu hình hỏng, không phải ca biên hợp lệ — không có phép nội suy nào giữa hai điểm trùng nhau. Trả null (không chấm được) thay vì chia cho 0 hay đoán một giá trị: cho 0 điểm là phạt người dùng vì người vận hành gõ sai cấu hình, cho 100 điểm là thưởng họ vì cùng lý do.

Gộp điểm của các tiêu chí thành điểm tổng và trọng số phân phối.

Điểm từng tiêu chí — cả những cái không chấm được Số ngày sale đã phụ trách kênh; dưới là tạm tính Ngưỡng Chat.Quality.MinDays Ngưỡng Chat.Quality.MinSamples Điểm mặc định Chat.Quality.DefaultScore khi tạm tính Điểm tổng = Σ(trọng số × điểm chuẩn hoá) / Σ trọng số, chỉ trên những tiêu chí có cỡ mẫu > 0. Tiêu chí không chấm được bị loại khỏi cả tử số lẫn mẫu số — cho nó 0 điểm rồi vẫn chia cho tổng trọng số đầy đủ là phạt sale vì hệ thống chưa có dữ liệu về họ. Không tiêu chí nào chấm được thì kết quả là tạm tính mang điểm mặc định, không phải 0. Đây là trạng thái của mọi sale trên dev hôm nay theo số đo F-0.

Từ điểm sang trọng số phân phối: clamp(0,4 + 0,9 × score/100 , 0,4 , 1,3).

Sàn 0,4 là cố ý (§3.6), và đây là chỗ dễ bị đề nghị "cho về 0 cho dứt khoát" nhất nên lý do phải nằm ngay cạnh công thức. Đẩy một sale về 0 khách là đẩy họ vào chỗ không bao giờ cải thiện được điểm nữa — mọi tiêu chí ở đây đều cần có khách mới đo được, nên 0 khách là 0 mẫu là điểm đứng yên vĩnh viễn. Đó là một vòng lặp chết, không phải một hình phạt. Và về quản lý nhân sự, cắt hẳn một người phải là quyết định của con người có tên chịu trách nhiệm: muốn cắt thì quản lý bấm tạm ngưng (ChatAgentPresence.SuspendedUntil).

Vì sao điểm này là tạm tính — null nghĩa là đủ căn cứ.

Bốn lý do, và cả bốn đều nói được thành một câu cho người dùng đọc. Trả về câu chữ chứ không trả về mã lý do vì đây là thứ hiện thẳng lên trang "điểm của tôi": một sale mới không cần biết mã, họ cần biết còn thiếu gì.

Kẹp một giá trị vào đoạn [can, tran]

Làm tròn về chữ số, làm tròn nửa lên

Trung vị của một dãy số. Dãy rỗng trả null — không trả 0.

Trung vị chứ không phải trung bình (§3.6): một hội thoại quên 6 tiếng không được phép xoá sổ cả tháng làm tốt. Số đo Đ5 cho thấy đuôi phân bố dài đến mức trung bình vô nghĩa — trung vị 0,82 phút trong khi max là 525.808 phút. Dãy chẵn phần tử lấy trung bình cộng hai phần tử giữa, theo định nghĩa chuẩn.

Tên khoá AppConfig của điểm chất lượng (giai đoạn F) — seed bằng migration, không hardcode giá trị ở nơi khác.

Theo đúng khuôn của giai đoạn E và của giai đoạn D: hằng tên khoá ở một chỗ, một lớp duy nhất diễn giải chuỗi, InvariantCulture, giá trị hỏng rơi về phía an toàn thay vì ném lỗi giữa một lượt tính điểm.

Công tắc duy nhất để điểm chạm vào đường phân phối. true / false. Mặc định TẮT.

Đây là mục 3 của nguyên tắc số 1: "Điểm chất lượng không được ảnh hưởng phân phối trước khi có dữ liệu." Tắt thì máy phân phối không đọc tới ChatQualitySummary.DistributionWeight và mọi người mang trọng số 1,0 — y hệt trước giai đoạn F. Bật nó là bước 8 của trình tự lên production: sau ≥ 30 ngày có dữ liệu, và phải báo đội sale trước vì nó đổi số lượng việc họ nhận. Bước 6 (tắt Chat.Distribution.DryRun) đổi cách họ nhận việc; bước này đổi bao nhiêu.

Dưới bấy nhiêu ngày phụ trách kênh thì điểm là tạm tính

Dưới bấy nhiêu quan sát thì điểm là tạm tính

Điểm gán cho người chưa đủ dữ liệu

Đọc và diễn giải các khoá cấu hình của điểm chất lượng.

Điểm có được nhân vào trọng số phân phối không. Mặc định false.

Cùng khuôn rơi-về-phía-an-toàn của , và cùng chiều với nó: hai hướng hỏng không cân nhau. Không bật thì tệ nhất là máy chia đều như hôm nay; bật nhầm là đổi số lượng việc của người thật dựa trên một bảng điểm mà số đo F-0 cho thấy 4/5 tiêu chí đang rỗng dữ liệu.

Ngưỡng số ngày phụ trách kênh để hết tạm tính (mặc định 14)

Ngưỡng cỡ mẫu để hết tạm tính (mặc định 20)

Điểm mặc định của người tạm tính (mặc định 70)

Bật hay tắt khi khoá đọc không ra. Xem để biết vì sao chiều này.

Số ngày tối thiểu — 14, theo §3.6

Cỡ mẫu tối thiểu — 20, theo §3.6

Điểm mặc định của sale mới — 70, theo §3.6. Cho trọng số phân phối 1,03: nhỉnh hơn mức trung bình một chút, đúng tinh thần không phạt người mới vì họ mới.

Kết quả một lượt quét hàng chờ — dùng cho log và cho test.

Số hội thoại còn nằm hàng chờ lúc quét

Số hội thoại vừa giao được cho người

Số hội thoại vừa báo cho trưởng nhóm

Số hội thoại không được xét báo vì lúc quét không có ứng viên nào của kênh vào ca (KC-18, §8.7 câu 3b) — chúng chờ lượt quét đầu ca kế tiếp, không bị đánh dấu đã báo.

Số đếm riêng để log của job phân biệt được "hàng chờ im vì chưa tới ngưỡng" với "hàng chờ im vì cả kênh đang Nghỉ" — hai tình huống giống hệt nhau nếu chỉ nhìn .

Quét hàng chờ: thử phân phối lại những hội thoại chưa ai nhận, và báo trưởng nhóm khi khách chờ quá lâu (giai đoạn D).

Máy phân phối chạy ngay khi tin của khách đến, nên hàng chờ chỉ sinh ra khi lúc đó không ai đủ điều kiện — ngoài giờ làm, cả đội bận, hoặc chưa ai được xếp phụ trách kênh. Lượt quét này là thứ đưa hội thoại ra khỏi hàng chờ khi điều kiện đổi mà khách không nhắn thêm gì. Không có nó thì một khách nhắn lúc 22 giờ nằm chờ tới khi họ tự nhắn lại.

Chạy một lượt quét.

Mốc quét — tham số để test được mà không phụ thuộc đồng hồ máy

Trần số hội thoại xử lý trong một lượt quét.

Job chạy mỗi 2 phút; một lượt quét ôm cả nghìn hội thoại là một lượt quét chạy quá 2 phút rồi chồng lên lượt sau. Cắt trần thì phần dư sang lượt kế tiếp — hàng chờ được xếp theo tin đến sớm nhất nên người chờ lâu nhất luôn nằm trong mẻ đầu. Cắt bao nhiêu thì log ra bấy nhiêu: một phép cắt im lặng đọc thành "đã xử lý hết". Khi vượt trần, kênh đang có người vào ca đứng trước kênh không ai trực (KC-18, bản vá sau review) — xem LayMeKhiVuotTranAsync.

Hội thoại chưa ai nhận, chưa đóng, trên các kênh cho trước.

Người chờ lâu nhất đứng đầu — cùng thứ tự mà màn hàng chờ đang hiện, để người điều phối và máy không bao giờ nhìn hai thứ tự khác nhau.

Lấy mẻ khi hàng chờ vượt trần: hội thoại của kênh lúc này có người vào ca đứng trước, rồi mới tới kênh không ai trực — mỗi nhóm vẫn xếp theo thứ tự chờ.

Bản vá sau review KC-18. Trần "phần dư sang lượt sau" chỉ đúng khi đầu mẻ rồi cũng vơi đi. Từ khi mỗi người một giờ làm, một kênh chỉ có người ca ngày dồn hàng chờ suốt đêm — không ai nhận được, không ai bị báo () — và vì cũ nhất nên chiếm trọn mẻ 200 mỗi lượt. Hội thoại của một kênh có người trực đêm đứng sau vị trí 200 thì cả đêm không được thử chia lại, trưởng nhóm của nó cũng không được báo. Xếp sau chứ không loại hẳn, dù kênh không ai trực thì thử chia cũng không ra ai: "có người vào ca" đọc từ nhật ký trạng thái, còn máy chia đọc dòng trạng thái hiện tại — hai nguồn có thể lệch (dòng nhật ký treo, PP-27). Loại hẳn thì một lần lệch là hội thoại ấy không bao giờ được thử; xếp sau thì nó vẫn lấp chỗ trống còn lại của mẻ. Chỉ chạy khi vượt trần nên đường thường không tốn thêm truy vấn nào. Khi chạy, nó nạp phủ sóng tại đúng mốc (một lần cho mọi kênh), tách khỏi lần nạp cho đồng hồ báo trưởng nhóm ở vì lần ấy cần khoảng tính từ mốc chờ sớm nhất của mẻ — thứ chưa biết trước khi có mẻ. Nạp lỗi thì rơi về thứ tự cũ.

Lượt xét báo của một hội thoại kết thúc thế nào.

Không báo — đã báo rồi, chưa tới ngưỡng, không có mốc chờ, hoặc kênh chưa có trưởng nhóm

Không báo vì lúc này không ứng viên nào của kênh vào ca — chờ đầu ca kế tiếp

Vừa gửi thông báo

Nạp phủ sóng cho các kênh có hội thoại còn có thể phải báo (chưa đánh dấu đã báo, có mốc chờ). Trả null khi không nạp được — lượt này khi đó không báo ai.

Khoảng nạp là [mốc chờ sớm nhất, now] của đúng những hội thoại ấy: hội thoại đã báo không bao giờ báo lại nên không cần đếm, và bỏ chúng đi giữ khoảng nạp ngắn — một hội thoại bị bỏ quên nhiều tháng đã báo từ lâu không được kéo cả lượt quét về tận lúc đó. Lỗi nạp không được giết cả lượt: phần thử phân phối lại vẫn phải chạy cho mọi người trong hàng chờ. Nuốt lỗi, log, và không báo ai — không biết ai đang vào ca thì im lặng còn hơn đánh thức trưởng nhóm theo một phỏng đoán; và vì không đánh dấu đã báo nên lượt sau báo lại được.

Báo trưởng nhóm của kênh khi một hội thoại chờ quá Chat.Queue.AlertMinutes phút có người vào ca (KC-18). Trả nếu vừa gửi.

Gửi bằng SendToUsersAsync với người nhận tự tra, không bằng SendToRoleAsync: bản theo role gửi cho mọi người có role đó trên toàn hệ thống, không lọc kênh cũng không lọc chi nhánh — tức là trưởng nhóm của một Page ở Hải Phòng nhận thông báo về khách của một OA ở Hà Nội. Cùng lý lẽ đã ghi ở TruckMaintenanceNotifier. Mỗi hội thoại báo một lần cho mỗi lượt vào hàng chờ (cột QueueAlertedAt). Job chạy mỗi 2 phút, nên không có mốc ấy thì một hội thoại chờ nửa buổi sinh ra mười lăm thông báo giống hệt nhau và người nhận sẽ tắt hết thông báo của cả hệ thống.

Ghi mốc đã-báo bằng một câu UPDATE chạm đúng một cột.

Không được dùng UpdateAsync(hoiThoai) ở đây. Thực thể này được nạp ở đầu lượt quét, và UpdateAsync ghi lại cả dòng theo ảnh chụp lúc ấy. Giữa lúc nạp và lúc ghi, một webhook có thể đã giao hội thoại cho ai đó — mà đường giao ấy là một câu UPDATE đi thẳng xuống database, không qua bộ theo dõi thay đổi, nên thực thể trong tay lượt quét vẫn mang AssignedStaffId = null. Ghi cả dòng là xoá mất lượt gán vừa thắng: khách đã có người, rồi lại không có ai, và nhật ký phân công thì vẫn ghi là đã giao. Đây đúng là mặt trái của lựa chọn ở EfChatConversationClaim — cùng một sự thật (câu UPDATE không qua bộ theo dõi) đọc theo hai chiều. Ở đó nó bắt sổ phân công phải đồng bộ lại thực thể; ở đây nó cấm ghi lại cả dòng từ một ảnh chụp cũ.

Trưởng nhóm và chủ của một kênh — đọc từ cửa chung, không chép lại truy vấn.

Mẫu tin nhắn nhanh ở ô soạn tin của khung chat đa kênh (docs/plan-tin-nhan-nhanh-chat.md §3.2, §3.3).

Hàng rào phạm vi nằm ở đây, không nằm ở controller. Hai luật, mỗi luật đúng một chỗ: VisibleTo — người này đọc/gửi được mẫu nào (mẫu dùng chung + mẫu cá nhân của chính mình); WritableIn — một endpoint ghi được bản ghi nào (đúng phạm vi của endpoint, và đúng chủ với mẫu cá nhân). Không tham số nào từ client chọn được chủ hay phạm vi. Founder bỏ qua role nhưng không bỏ qua luật chủ nhân (§3.2, quyết định §6.9). Mọi trường hợp "không có quyền với bản ghi này" — mã của người khác, mã thuộc phạm vi kia, mã không tồn tại, mẫu đã xoá — trả cùng một câu "không tìm thấy". Phân biệt được chúng là nói cho người dò mã biết mã nào đang tồn tại.

Danh sách gọn cho ô chọn ở ô soạn tin: mẫu dùng chung đang bật + mẫu cá nhân đang bật của tôi, sắp theo lượt dùng giảm dần, rồi thứ tự, rồi tiêu đề.

Bảng ở trang quản lý. → chỉ mẫu của tôi, mọi trạng thái; → có quyền quản lý thì mọi trạng thái, không thì chỉ mẫu đang bật.

Người gọi có quyền quản lý mẫu dùng chung — controller lấy từ , cùng nguồn với cờ CanManageSharedQuickReplies mà giao diện đọc

Một mẫu để mở form sửa; null khi không thấy được — cùng luật với .

Tạo/sửa mẫu cá nhân — chủ luôn là , bất kể client gửi gì

Tạo/sửa mẫu dùng chung — endpoint gọi hàm này đã gác bằng role ChatQuickReply.ManageShared

Xoá mềm mẫu cá nhân của chính mình; tệp ảnh giữ nguyên

Xoá mềm mẫu dùng chung; tệp ảnh giữ nguyên

Gửi một tin vào hội thoại, xuất phát từ một mẫu (send-quick-reply).

Bên trong gọi đúng — hàm mà send và send-image dùng, không đổi chữ ký hay hành vi của nó (nguyên tắc 1.1). Vì thế hàng rào phạm vi ghi của hội thoại, kiểm kênh còn gửi được, luật "chỉ tin văn bản mới trích dẫn được" và việc lưu tin trước khi gọi nền tảng đều là của đường gửi sẵn có; ở đây không chép lại luật nào trong số đó. Hàm này chỉ thêm hai điều: mẫu phải thấy được với người gửi và đang bật; và ảnh gửi đi là ảnh của mẫu, tra theo mã mẫu. Gửi thành công mới cộng lượt dùng. Vì sao nằm ở đây, không nằm trong ISocialChatService như prompt GĐ A đề xuất (plan §3.3): đặt vào lõi chat là thêm một phụ thuộc vào constructor 15 tham số mà sáu chỗ trong năm file test đang dựng tay, và kéo luật "mẫu nào thấy được" ra khỏi lớp giữ luật ấy. Đặt ở đây thì SocialChatService.cs không bị sửa dòng nào.

Bề rộng cột Title

Bề rộng cột Content — giới hạn một tin nhắn của Zalo

Trần cỡ trang của bảng quản lý. Cỡ trang đến từ client.

Phím tắt sau khi chuẩn hoá — khớp đúng lời gợi ý ở biểu mẫu: không dấu, không khoảng trắng.

Hàng rào ĐỌC — nguồn duy nhất của "người này thấy được mẫu nào": mẫu dùng chung, và mẫu cá nhân của chính mình. Không tính trạng thái bật/tắt; mỗi đường gọi tự quyết định có cần lọc thêm hay không.

Người gọi không xác định (userId ≤ 0) không thấy gì cả, kể cả mẫu dùng chung — thiếu tham số phải dẫn tới thấy ÍT hơn, không bao giờ nhiều hơn.

Hàng rào GHI — bản ghi mà một endpoint của chạm được: đúng phạm vi ấy, và với mẫu cá nhân thì đúng chủ. Endpoint cá nhân không bao giờ chạm bản ghi dùng chung và ngược lại (§3.2).

Vế OwnerUserId == userId là thứ duy nhất đứng giữa một sale và mẫu của người ngồi cạnh — mật thử (a) của GĐ A bỏ đúng vế này để chứng minh ca test IDOR đỏ.

Chuẩn hoá rồi kiểm phím tắt. Trả (null, null) khi bỏ trống.

Chỉ làm hai phép mà người gõ coi là "cùng một phím tắt": bỏ dấu / gõ kèm và hạ chữ thường. Không sửa hộ gì thêm (bỏ dấu tiếng Việt, thay khoảng trắng) — sửa hộ là lưu một phím tắt người dùng không hề gõ, rồi họ gõ đúng chữ của mình mà không ra mẫu.

Lỗi ghi có phải do một trong hai unique index phím tắt của migration M202609151000 không.

Soi tên index trong thông điệp của cả chuỗi exception, không soi kiểu. Hai đường ghi của Repository ném hai hình dạng khác nhau: InsertAsync ném new Exception(exception.ToString()) KHÔNG kèm inner — tên index chỉ còn trong chuỗi thông điệp; UpdateAsync bọc DbUpdateException vào inner — tên index nằm ở SqlException sâu hơn. Bản đầu của GĐ A lần theo kiểu DbUpdateException nên đường TẠO MỚI không bao giờ khớp và trả 500 (review GĐ A). Chỉ hai index này. Lỗi ghi khác phải nổi lên như một sự cố thật, không được dịch thành "phím tắt vừa bị trùng". Hai tên dưới đây phải khớp migration từng ký tự — đổi tên index là phải sửa ở đây.

Ghi một lượt dùng mẫu tin nhắn nhanh — một câu UPDATE chạm đúng hai cột UseCount và LastUsedAt.

Vì sao không UpdateAsync(mẫu). Lượt gửi nạp mẫu trước một vòng gọi mạng ra Zalo/Facebook, mà UpdateAsync gọi DbSet.Update nên ghi lại cả dòng theo ảnh chụp lúc nạp. Chủ mẫu sửa nội dung, hay người quản lý tắt một mẫu dùng chung, trong đúng khe ấy thì sửa đổi của họ bị đè mất không dấu vết. Nạp lại rồi mới ghi cũng không chữa được: Repository.Query() có theo dõi, và trong cùng một DbContext Scoped EF trả lại chính thực thể cũ — bài học đã ghi ở . Cộng tại database (UseCount + 1) còn giữ đúng số đếm khi hai người gửi cùng một mẫu dùng chung cùng lúc; đọc-rồi-ghi thì mất một lượt. Tách interface vì đúng lý do của : ExecuteUpdateAsync là tính năng của trình dịch truy vấn EF Core, kho dữ liệu giả của bộ test không có.

Cộng một lượt dùng và đóng dấu thời điểm. Mẫu đã xoá mềm thì không đổi gì.

Tra nội dung tin gốc của những tin trả lời trích dẫn. Phải tra ở MÁY CHỦ chứ không để phía trình duyệt tự dò trong mẻ tin đã nạp: cả hai nền tảng chỉ gửi MÃ tin gốc, không gửi nội dung (§8 SC-27), mà khách rất hay trích một câu từ hôm trước — tin đó nằm ngoài 50 tin gần nhất. Dò ở trình duyệt thì trường hợp thường gặp nhất lại là trường hợp hỏng, và khối trích dẫn hiện ra rỗng. Dùng chung cho CẢ HAI đường ra DTO (REST và SignalR) vì đúng lý do của : thiếu ở một đường thì khối trích dẫn biến mất ngay khi tin nhận được một cập nhật giao nhận, do phía trình duyệt thay nguyên phần tử bằng bản mới.

Tra đoạn trích của một tin. Trả null khi tin này không phải tin trả lời trích dẫn. Tin gốc không còn trong database thì vẫn trả về một đoạn trích rỗng nội dung — giao diện cần biết "đây là câu trả lời cho một tin cũ" ngay cả khi không dựng lại được nó.

Tra đoạn trích cho cả một mẻ tin bằng MỘT lời gọi database. Trả về bảng tra theo ChatMessage.Id, chỉ chứa những tin có trích dẫn.

Độ dài tối đa của đoạn trích. Khối trích dẫn là gợi nhớ ngữ cảnh, không phải chỗ đọc lại cả tin — dài quá thì nó át chính câu trả lời nằm ngay dưới.

Đoạn trích của một tin gốc không dựng lại được.

Đưa các phòng realtime của một người về đúng phạm vi hiện tại của họ — gỡ phòng đã mất quyền, vào phòng vừa mở. Đây là mặt thứ ba của hàng rào quyền xem, sau REST và sau luật chọn nhóm khi phát tin. Hai mặt kia chỉ đúng ở thời điểm gọi; một kết nối SignalR thì sống hàng giờ, và nó giữ nguyên danh sách nhóm từ lúc mở. Chuyển hội thoại cho người khác mà không thu hồi là người cũ vẫn nghe được nguyên văn tin của khách cho tới khi họ đóng tab (finding F-3).

Chấm lại phạm vi của một người và sửa các phòng của mọi kết nối họ đang mở

Phạm vi liên quan tới một nhân viên vừa đổi: chấm lại cho chính họ và cho mọi người nhìn thấy họ. Vì sao cần vế thứ hai: phạm vi của một hội thoại không chỉ gồm người đang giữ nó. Mức cho người quản lý xem hội thoại của cấp dưới, nên khi hội thoại bị chuyển khỏi cấp dưới thì người quản lý cũng vừa mất quyền — mà mã của họ không xuất hiện ở bất kỳ đầu nào của lượt phân công. Thu hồi đúng hai người trực tiếp là để lại nguyên một lỗ cùng hình dạng với finding F-3, chỉ khác nạn nhân.

Chấm lại phạm vi của mọi người đang kết nối — dùng khi bật/tắt hàng rào của một kênh, vì thao tác đó đổi phạm vi của tất cả cùng lúc.

Việc mà lượt quét phải làm với một hội thoại.

Không làm gì

Nhắc người đang giữ

Thu hồi khỏi người đang giữ rồi chia lại

Ảnh chụp một hội thoại, đủ để chấm hạn phản hồi mà không phải đọc bảng tin nhắn.

Đây là lý do §3.2 đặt các mốc thời gian lên ChatConversation chứ không tính từ ChatMessage: bảng tin sẽ lên hàng chục nghìn dòng mỗi ngày ở quy mô đích, và một job chạy mỗi 2 phút không được phép quét nó.

Người đang giữ. null = hội thoại nằm hàng chờ.

Lúc người hiện tại nhận hội thoại

Tin mở đầu lượt chờ hiện tại (ChatConversation.WaitingSinceAt). null = khách không đang chờ ai.

Lần gần nhất lượt quét đã nhắc về hội thoại này

Chế độ phân phối của kênh chứa hội thoại

Đủ dữ liệu để giao diện hiện được "khách đã chờ bao lâu" — bằng đúng phép đếm mà hai lượt quét dùng để quyết định nhắc, thu hồi, báo trưởng nhóm.

Dựng một lần cho cả một trang từ chính các hội thoại của trang () rồi truyền vào từng dòng: dựng cho từng dòng là N+1 truy vấn giờ làm và nhật ký trạng thái trên màn được mở nhiều nhất. KC-18 — hai loại dòng, hai cách đếm (plan §6 Phiên 4, thiết kế mục 4), trước đó là một cửa sổ giờ làm chung cho mọi dòng: Dòng có người cầm: phút trong giờ riêng của người cầm (), so ngưỡng — cùng nghĩa với trong lượt quét hạn phản hồi. Dòng hàng chờ: phút có ít nhất một ứng viên của kênh vào ca (), so ngưỡng — cùng nghĩa với lượt quét hàng chờ. Ngưỡng nhắc của hạn phản hồi (Chat.Sla.RemindMinutes) Ngưỡng báo trưởng nhóm (Chat.Queue.AlertMinutes)

Đủ dữ liệu để giao diện hiện được "khách đã chờ bao lâu" — bằng đúng phép đếm mà hai lượt quét dùng để quyết định nhắc, thu hồi, báo trưởng nhóm.

Dựng một lần cho cả một trang từ chính các hội thoại của trang () rồi truyền vào từng dòng: dựng cho từng dòng là N+1 truy vấn giờ làm và nhật ký trạng thái trên màn được mở nhiều nhất. KC-18 — hai loại dòng, hai cách đếm (plan §6 Phiên 4, thiết kế mục 4), trước đó là một cửa sổ giờ làm chung cho mọi dòng: Dòng có người cầm: phút trong giờ riêng của người cầm (), so ngưỡng — cùng nghĩa với trong lượt quét hạn phản hồi. Dòng hàng chờ: phút có ít nhất một ứng viên của kênh vào ca (), so ngưỡng — cùng nghĩa với lượt quét hàng chờ. Ngưỡng nhắc của hạn phản hồi (Chat.Sla.RemindMinutes) Ngưỡng báo trưởng nhóm (Chat.Queue.AlertMinutes)

Ngưỡng nhắc của hạn phản hồi (Chat.Sla.RemindMinutes)

Ngưỡng báo trưởng nhóm (Chat.Queue.AlertMinutes)

Giờ làm riêng của người đang cầm, theo StaffId. Người không có mặt ở đây được đếm bằng cửa sổ "luôn trong ca" — đúng cách lượt quét hạn phản hồi xử lý người giữ không tra được.

Phủ sóng "có người vào ca" theo ChatChannelId, dựng tới "bây giờ" của trang. Kênh không có mặt ở đây thì dòng hàng chờ của nó không nói gì về việc chờ — cùng chiều với lượt quét hàng chờ, vốn không báo khi không biết ai đang vào ca.

Giờ làm dùng để đếm cho người cầm .

Kết luận cho một hội thoại, kèm con số và câu giải thích để ghi log.

Số phút giờ làm khách đã chờ, tính từ

Mốc bắt đầu đếm; null khi hội thoại không trong diện chấm

Vì sao ra kết luận này — đọc được bằng mắt người, dùng cho log

true khi hội thoại bị bỏ qua chỉ vì người đang giữ đang ngoài giờ làm của chính họ (KC-18) — khách vẫn đang chờ, chỉ là chưa tới lúc chấm.

Cờ riêng chứ không để lượt quét so chuỗi : câu chữ là để người đọc, sửa một chữ trong đó không được phép làm bộ đếm của log lặng lẽ về 0.

Luật hạn phản hồi của giai đoạn E — hàm thuần: không chạm database, không đọc đồng hồ, không gửi gì đi đâu.

Tách khỏi đúng cách tách khỏi ở giai đoạn D: nhờ thế kiểm được bằng bảng ca (ảnh chụp hội thoại + thời điểm → việc phải làm) mà không cần dựng kho dữ liệu giả, không cần bản giả thông báo, và không cần một hội thoại thật nào. Đây là đường tự động đổi người phụ trách — thứ mà §3.12 xếp vào nhóm phải qua workflow review-giai-doan cộng /security-review. Mọi điều kiện chặn nằm ở đây, ở một chỗ, chứ không rải thành if trong lớp chạm dữ liệu.

Lý do ghi log khi người đang giữ đang ngoài giờ làm của chính họ (KC-18). Hằng công khai để bảng ca so đúng câu mà log in ra, không chép lại một bản.

Từ lúc nào khách bắt đầu chờ được trả lời — hoặc null nếu họ không đang chờ.

Tách thành hàm công khai riêng vì có hai chỗ cần đúng câu trả lời này: lượt quét (để chấm hạn) và giao diện (để hiện cột "chờ trả lời"). Viết hai bản là dựng hai định nghĩa của cùng một khái niệm, và cái lệch chỉ lộ ra khi một sale hỏi vì sao màn hình nói 5 phút mà hệ thống vừa thu hồi hội thoại của họ. Nguồn là ChatConversation.WaitingSinceAt — tin MỞ ĐẦU lượt chờ, không phải tin cuối cùng của khách. Đường nhận tin mở nó ở tin đến đầu tiên (??=) và đóng nó ở mọi tin đi ra, kể cả tin admin gõ thẳng trên ứng dụng Zalo OA / Facebook Page — 91,9 % tin chiều ra trên dữ liệu thật thuộc loại đó (số đo E0-5, nợ PP-13) và chúng không cập nhật LastStaffReplyAt, nên chấm bằng cột kia là thu hồi hội thoại của một người đã trả lời khách, chỉ vì họ trả lời ở cửa khác. Vì sao không dùng LastInboundAt. Cột ấy tiến lên mỗi lần khách nhắn thêm, nên đo bằng nó là biến việc khách giục thành việc hoãn đồng hồ: nhắn 09:00, 09:12, 09:25, 09:38, 09:52 mà không ai trả lời thì không lượt quét nào chấm quá 13 phút. Và nó làm hai định nghĩa trôi khỏi nhau — ngưỡng 15/45 suy từ Đ5 theo cách đo (c), nguyên văn "chỉ tin mở đầu một lượt chờ". Mốc là cái muộn hơn giữa lúc lượt chờ mở và lúc người hiện tại nhận việc: người vừa được giao một hội thoại đã chờ 40 phút không chịu trách nhiệm cho quãng chờ của người trước.

Chấm một hội thoại: có phải nhắc, phải thu hồi, hay không làm gì.

Thứ tự các cửa, cửa trước thắng: Kênh không ở chế độ tự phân phối ⇒ bỏ qua. Chưa ai giữ ⇒ bỏ qua (hàng chờ có lượt quét riêng). Khách không đang chờ ( trả null) ⇒ bỏ qua. Người đang giữ ngoài giờ làm của chính họ tại ⇒ bỏ qua, = true (KC-18). So số phút giờ làm với hai ngưỡng — thu hồi trước, nhắc sau. Cửa thứ tư (KC-18, §8.7 câu 1b). Trước KC-18 lượt quét có một cổng toàn cục: ngoài giờ làm chung thì dừng hẳn cả lượt. Nay mỗi người một giờ làm, nên "ngoài giờ" là chuyện của từng hội thoại chứ không của cả lượt — cổng chuyển vào đây, theo người đang giữ. Nó giữ đúng điều kiện nghiệm thu cũ "không thông báo nào gửi ngoài giờ làm", nay đọc là "ngoài giờ làm của người nhận". Không có nó thì một hội thoại chạm ngưỡng lúc 16:59 của người làm tới 17:00 sẽ bị lượt quét 17:01 nhắc — phép đếm phút đã dừng đúng, nhưng thông báo vẫn đi ra ngoài giờ; tệ hơn là lượt quét chết một giờ rồi sống lại lúc người đó đã về. Cửa này đứng sau phép đếm phút (dù đứng trước phép so ngưỡng) để kết luận bỏ qua vẫn mang đúng số phút và mốc bắt đầu — cùng con số mà cột "chờ bao lâu" của giao diện hiện cho cùng hội thoại. Phép đếm là hàm thuần, không tốn gì thêm. Người chưa đặt giờ riêng nhận cửa sổ từ lớp gọi: luôn trong ca, đếm phút đồng hồ thật — hàm này không phân biệt, nó chỉ hỏi cửa sổ. Ảnh chụp hội thoại Thời điểm quét Cửa sổ giờ làm của người đang giữ hội thoại này (KC-18) — không phải cấu hình chung. Lớp gọi nạp hàng loạt qua . Ngưỡng nhắc, tính bằng phút giờ làm Ngưỡng thu hồi, tính bằng phút giờ làm

Người đang giữ có đang trong ca của chính họ tại không — cửa thứ tư của , tách thành hàm công khai để có đúng một định nghĩa cho hai chỗ dùng.

Chỗ dùng thứ hai là : nó phải gạt hội thoại của người đang ngoài ca ra trước khi cắt mẻ . Để phép gạt ấy cho Decide lo (cắt mẻ trước, chấm sau) thì các hội thoại cũ nhất của người đã hết ca — không bị nhắc, không bị thu hồi, nên không bao giờ rời mẻ — chiếm trọn mẻ suốt đêm, và hội thoại của người đang trong ca đứng sau chúng không bao giờ được chấm. Lượt quét hỏi đúng hàm này nên hai chỗ không thể trả lời khác nhau cho cùng một người ở cùng một mốc. Cửa sổ giờ làm của người đang giữ (chưa đặt = luôn trong ca) Thời điểm quét

Tên khoá AppConfig của hạn phản hồi (giai đoạn E) — seed bằng migration, không hardcode giá trị ở nơi khác. Theo đúng khuôn của giai đoạn D: hằng tên khoá ở một chỗ, một lớp duy nhất diễn giải chuỗi, InvariantCulture, giá trị hỏng rơi về phía an toàn thay vì ném lỗi giữa một lượt quét.

Công tắc của cả giai đoạn E. true / false. Mặc định TẮT.

Khoá này tồn tại vì một lý do rất cụ thể, ghi ở §4 Bản đồ phiên: cổng D2 đo máy phân phối chia có đều không. Nếu hạn phản hồi đồng thời thu hồi và chia lại thì bảng đối chiếu trộn hai hiệu ứng — một người "nhận nhiều" có thể là vì thuật toán chia lệch, mà cũng có thể vì họ liên tục nhận lại việc người khác bị thu hồi. Không tách được hai thứ đó ra khỏi cùng một con số. Nên trong trình tự lên production, bật khoá này là bước sau bước tắt , không phải cùng lúc.

Quá bấy nhiêu phút giờ làm chưa trả lời thì nhắc người đang giữ

Quá bấy nhiêu phút giờ làm chưa trả lời thì thu hồi và chia lại

Đọc và diễn giải các khoá cấu hình của hạn phản hồi.

Tách riêng khỏi theo đúng lý do đã viết ở đó: hai nhóm khoá hai vòng đời. Ngưỡng hạn phản hồi là thứ §2.4 đã hẹn đo lại sau 2 tuần chạy thật, còn DryRun thì tắt một lần rồi thôi.

Hạn phản hồi có đang bật không. Mặc định false: khoá đọc không ra thì coi như chưa bật.

Cùng khuôn rơi-về-phía-an-toàn của , nhưng chiều ngược lại vì hai cờ mang nghĩa ngược nhau: ở đó "hỏng thì cứ thử chạy", ở đây "hỏng thì đừng tự thu hồi của ai". Hai hướng hỏng không cân nhau — không bật thì tệ nhất là khách chờ lâu như hôm nay, còn bật nhầm là máy tự lấy hội thoại khỏi tay người đang làm.

Ngưỡng nhắc lần 1, tính bằng phút giờ làm (mặc định 15)

Ngưỡng thu hồi, tính bằng phút giờ làm (mặc định 45)

Bật hay tắt khi khoá đọc không ra. Xem để biết vì sao chiều này.

Nhắc lần 1. 15 phút lấy từ số đo Đ5 (§2.4, N = 206, cách đo (c) — chỉ tin mở đầu một lượt chờ, chỉ trong giờ làm): nằm giữa p75 (4,3′) và p90 (35,4′), tức nhắc khoảng 10–15 % lượt chậm nhất, không nhắc oan phần lớn. Không phải hằng số vĩnh viễn: Đ5 chỉ có 3 ngày dữ liệu và phần lớn phát sinh trong lúc đội đang bấm thử, tức nhanh hơn vận hành thật. §2.4 đã hẹn đo lại sau 2 tuần chạy thật — đó là lý do con số này nằm trong AppConfig chứ không nằm trong code.

Thu hồi. 45 phút lấy từ số đo Đ5: trên p90 (35,4′), dưới p95 (156,4′). Cùng cảnh báo về độ tin cậy như .

Dựng bối cảnh "khách đã chờ bao lâu" cho một trang hội thoại, thành một phụ thuộc.

Tồn tại vì một lý do rất cụ thể, nói ra để người sau không tưởng đây là một tầng trừu tượng vô cớ: SocialChatService cần hai ngưỡng cộng cách đếm phút chờ, tức nhiều interface cấu hình và nạp dữ liệu. Nhét cả vào hàm dựng của một service vốn đã có 14 tham số là làm nặng thêm đúng chỗ đã nặng, trong khi chúng luôn đi cùng nhau và luôn được đọc cùng một lúc. KC-18: cách đếm nay phụ thuộc chính các dòng của trang — giờ riêng của người đang cầm, và ứng viên của kênh chứa hội thoại hàng chờ — nên hàm nhận danh sách hội thoại thay vì không nhận gì. Đọc một lần cho cả trang, không đọc lại cho từng dòng.

Dựng bối cảnh cho đúng các hội thoại sắp được hiện — số truy vấn không phụ thuộc số dòng.

Các hội thoại của trang (hoặc một hội thoại, ở màn chi tiết và bản đẩy realtime) "Bây giờ" — phải là đúng giá trị người gọi truyền tiếp cho ChatDtoMapper.ToItem: phủ sóng hàng chờ dựng tới mốc này và không đếm được quá nó.

Kết quả một lượt quét hạn phản hồi — dùng cho log và cho test.

Công tắc Chat.Sla.Enabled có đang bật không

Số hội thoại đã chấm ở lượt này — chỉ gồm hội thoại của người đang trong ca, tối đa . Hội thoại của người ngoài ca không vào mẻ chấm, chúng nằm ở .

Số hội thoại khách đang chờ nhưng bị bỏ qua vì người đang giữ đang ngoài giờ làm của chính họ (KC-18) — không nhắc, không thu hồi. Đếm trên cả diện chấm, không bị trần cắt, và không nằm trong .

Thay cho cờ WithinWorkingHours cũ. Cờ ấy trả lời "lượt quét có rơi vào giờ làm chung không" — câu hỏi hết nghĩa khi mỗi người một giờ làm: cùng một lượt, người này trong ca còn người kia đã về. Giữ lại cờ là để log in "trong giờ làm" cho một lượt vừa bỏ qua nửa số hội thoại vì người giữ đã hết ca. Con số này mới là thứ người vận hành cần khi hỏi "sao khách chờ 2 tiếng mà không ai bị nhắc". Không còn là "trong số đã chấm": từ bản vá sau review, hội thoại của người ngoài ca bị gạt khỏi mẻ trước khi cắt trần (xem ), nên chúng không được chấm từng cái — con số đến từ một câu đếm riêng.

Số hội thoại vừa nhắc người đang giữ

Số hội thoại vừa thu hồi

Trong số vừa thu hồi, bao nhiêu hội thoại tìm được người mới ngay

Kết quả dọn trạng thái hết hạn chạy kèm (PP-26, PP-27)

Quét hạn phản hồi: nhắc người đang giữ khi khách chờ quá lâu, rồi thu hồi và chia lại khi chờ lâu hơn nữa (giai đoạn E).

Giai đoạn D dựng máy tự chia khách, nhưng chia xong rồi thì không ai canh nữa — một hội thoại giao cho người đang bận rồi để đó ba tiếng thì hệ thống hoàn toàn im lặng. Lượt quét này là cái đồng hồ đếm ngược cho mỗi hội thoại đã chia. Chỉ đếm trong giờ làm việc — của người đang giữ. Xem : hạn phản hồi không phải hiệu số hai mốc thời gian, nó là số phút giờ làm đã trôi qua. Từ KC-18 (§8.7 câu 1b) đó là giờ làm riêng của người đang giữ hội thoại; người chưa đặt thì luôn trong ca, đếm phút đồng hồ thật. Cấu hình chung Chat.WorkingHours.* không còn chạm tới lượt quét này.

Chạy một lượt quét.

Mốc quét — tham số để test được mà không phụ thuộc đồng hồ máy

Trần số hội thoại chấm trong một lượt quét.

Cùng lý lẽ với ChatQueueSweepService.TranMoiLuot: job chạy mỗi 2 phút, một lượt ôm cả nghìn hội thoại là một lượt chồng lên lượt sau. Xếp theo tin của khách cũ nhất nên người chờ lâu nhất luôn nằm trong mẻ đầu. Cắt bao nhiêu thì log ra bấy nhiêu — một phép cắt im lặng đọc thành "đã chấm hết". Trần chỉ áp lên hội thoại của người đang TRONG ca (KC-18, bản vá sau review). "Phần dư sang lượt sau" chỉ đúng khi mọi dòng đầu mẻ rồi cũng rời mẻ — bị nhắc rồi thu hồi. Dòng của người đã hết ca riêng thì không: không nhắc, không thu hồi, nằm yên cả đêm, cả Chủ Nhật. Cắt mẻ trước rồi mới bỏ qua chúng là để 500 hội thoại cũ nhất của ca ngày chiếm trọn mẻ mỗi lượt, và hội thoại của người trực tối không bao giờ được chấm.

Chỉ nhìn lại bấy nhiêu ngày (đồng hồ thường) kể từ tin gần nhất của khách.

Cửa sổ này là thứ giữ cho không bị lấp đầy bởi hội thoại cũ đã trả lời từ lâu. Nó rộng hơn luật ở chứ không lặp lại luật ấy: phép chấm "khách còn đang chờ hay không" nằm ở đúng một chỗ, trong hàm thuần. Chép nó xuống câu truy vấn là dựng hai bản của cùng một hàng rào, và lúc ấy gỡ bản nào đi cũng không có ca test nào đỏ — đúng họ lỗi số 2 mà đợt mật thử giai đoạn D bắt được bốn lần. Đánh đổi đã biết: một hội thoại mà khách nhắn hơn 30 ngày trước và chưa ai trả lời sẽ rơi ra khỏi diện chấm. Nó đã bị thu hồi ít nhất một lần trước đó (mỗi lần cách nhau 45 phút giờ làm), nên cái còn lại không phải việc của một job — mà là việc của người. Nếu log cắt trần bắt đầu kêu ở production thì cách chữa là một filtered index trên (AssignedStaffId, Status, LastInboundAt) rồi đẩy vế "còn đang chờ" xuống SQL — và lúc ấy phải kèm một ca *SqlTests đối chiếu câu truy vấn với hàm thuần, chứ không chép ngầm.

Cửa sổ giờ làm của người đang giữ hội thoại, tra trong từ điển đã nạp cho cả mẻ.

Từ điển có đủ mọi mã hợp lệ đã hỏi (hợp đồng của ), và nó được nạp cho cả diện chấm trước khi cắt mẻ (người giữ vừa đổi tay thì được nạp bù), nên nhánh dự phòng chỉ gặp khi chưa ai giữ — lúc ấy đã bỏ qua trước khi hỏi cửa sổ — hoặc khi mã giữ <= 0. Dự phòng là "luôn trong ca" cho cùng nghĩa với người chưa đặt, không phải cấu hình chung: cấu hình chung từ KC-18 chỉ còn là giờ gợi ý (§8.7 câu 5).

Dựng ảnh chụp hội thoại cho hàm thuần.

Bọc lượt dọn trạng thái hết hạn: nó là việc trả nợ, không phải việc chính, nên một lỗi ở đó không được làm cả lượt quét hạn phản hồi không chạy.

Nhắc chính người đang giữ. Trả true nếu vừa gửi.

Không gửi cho trưởng nhóm ở bậc này, và đó là một quyết định chứ không phải một chỗ quên: trưởng nhóm không phải người phải trả lời khách. Báo họ ngay từ phút thứ 15 là biến một lời nhắc thành một lời mách, và sau vài ngày họ sẽ tắt nhóm thông báo này. Trưởng nhóm chỉ nghe ở bậc thu hồi — lúc đã có việc cần họ xử lý.

Kết quả một lượt thu hồi — hai vế tách rời vì chúng hỏng độc lập nhau.

Kết quả một lượt thu hồi — hai vế tách rời vì chúng hỏng độc lập nhau.

Thu hồi hội thoại khỏi người đang giữ rồi chia lại.

Đi qua sổ phân công và máy phân phối sẵn có, không viết đường thứ hai: hai bản chọn người là hai bản sẽ lệch nhau. Quãng nghỉ ChatCandidateExclusion.ReleaseCooldown đã lo sẵn việc "vừa thu hồi của ai thì đừng giao lại ngay cho chính họ" — nó tính theo mọi lý do nhả, kể cả . Chia lại không tìm được ai thì hội thoại ở lại hàng chờ, và lượt quét hàng chờ tiếp quản. Trả nó về đúng người vừa bị thu hồi là biến cả việc thu hồi thành một câu lệnh không có tác dụng gì.

Báo trưởng nhóm của kênh và chính người vừa bị thu hồi.

Người vừa bị thu hồi nằm trong danh sách nhận có chủ ý, dù §4 chỉ nói "thu hồi mới báo trưởng nhóm": hội thoại biến khỏi danh sách của họ trong im lặng là cách chắc chắn nhất để họ tưởng hệ thống hỏng, và tệ hơn — họ vẫn đang soạn câu trả lời cho một khách không còn là của mình. Gửi bằng SendToUsersAsync với người nhận tự tra, không bằng SendToRoleAsync: bản theo role gửi toàn hệ thống, không lọc kênh cũng không lọc chi nhánh.

Tra tên nhân viên theo mã, phục vụ trường "đang phân công" trên khung chat. Phải là một dịch vụ riêng chứ không phải một Include: cột ChatConversation.AssignedStaffId cố ý KHÔNG có khoá ngoại sang bảng người dùng (xem migration M202608261600), nên không có navigation nào để nạp kèm. Thêm khoá ngoại chỉ để lấy một cái tên là sửa lược đồ của bảng nghiệp vụ — trái với nguyên tắc số 1 của đợt này. Dùng chung cho CẢ HAI đường ra DTO (REST và SignalR). Đây là bài học đắt nhất của giai đoạn C: một trường thiếu ở một đường ghi làm cả tính năng hỏng im lặng, và vì phía trình duyệt thay nguyên dòng trong danh sách bằng bản vừa nhận nên tên sẽ biến mất khỏi màn hình ngay khi có tin mới.

Tên hiển thị của một loạt nhân viên. Mã không tra được (tài khoản đã xoá) thì không có mặt trong kết quả — người gọi tự lùi về chuỗi rỗng.

Tên hiển thị của một nhân viên, chuỗi rỗng khi không tra được hoặc chưa phân công

Danh sách nhân viên có thể nhận phân công hội thoại, lọc theo từ khoá. Chỉ lấy tài khoản kiểu nhân viên và chưa bị khoá — phân công cho một tài khoản đã khoá là để việc rơi vào chỗ không ai nhìn. Người gọi PHẢI truyền phạm vi đúng theo DataAccessScope của tài khoản đang đăng nhập, y như UserController.SugStaff làm. Mặc định của phạm vi ấy là SelfOnly, nên gọi hàm này không kèm ràng buộc là biến một tài khoản chỉ được thấy chính mình thành một tài khoản đọc được danh bạ nhân sự của cả công ty.

Từ khoá theo tên hoặc tên đăng nhập Chỉ lấy nhân viên do người này quản lý trực tiếp Chỉ lấy đúng tài khoản này Danh sách phụ trách của kênh, khi kênh đó đã bật hàng rào. Truyền vào ĐÂY chứ đừng lọc kết quả trả về: hàm này cắt ở SuggestLimit dòng, nên lọc sau là lọc trên một lát cắt bảng chữ cái chứ không phải trên tập nhân viên của kênh.

Một mã nhân viên có nằm trong tập mà sẽ trả về với cùng ràng buộc không — tức là tài khoản nhân viên, chưa khoá, và trong phạm vi. Dùng để đối chiếu mã gửi lên ở endpoint phân công bằng CHÍNH luật của đường gợi ý, giống link-customer đối chiếu lại qua ICustomerService.Suggest. Không có bước này, phân công nhận mã tuỳ ý là một máy tra tên/tên đăng nhập theo mã cho toàn bộ bảng người dùng, kể cả tài khoản khách hàng (finding security review GĐ F, luật §6.10).

Danh sách được phép chọn — cùng tham số, cùng nghĩa với . Cần cho nhánh SelfOnly của đường phân công/chuyển: ở đó "phạm vi" KHÔNG phải một mức DataAccessScope mà là danh sách phụ trách của một kênh (sổ nợ PP-38). Danh sách rỗng → không ai khớp → false, fail-closed.

Tiền tố khoá bộ nhớ đệm. Tên nhân viên gần như không đổi, mà đường đẩy realtime thì chạy trên luồng xử lý webhook — nơi Zalo chỉ cho 2 giây để trả lời.

Thời gian sống của một mục đệm. Đổi tên nhân viên thì chậm nhất 10 phút là hiện đúng.

Số nhân viên tối đa một lần gợi ý trả về — ô chọn, không phải danh sách nhân sự

Tập nhân viên nhận phân công được: tài khoản kiểu nhân viên, chưa khoá, trong phạm vi. Cả gợi ý lẫn đối chiếu mã đều đi qua đúng truy vấn này.

Nguồn duy nhất nạp giờ làm riêng của sale (KC-18) — hàng loạt, một truy vấn cho cả lô. Bốn nơi cần giờ riêng của nhiều người cùng lúc: lượt quét hạn phản hồi (người đang cầm của mọi hội thoại), lượt quét hàng chờ và cột "chờ bao lâu" (ứng viên của kênh), job chấm tiêu chí 5 (mọi sale). Mỗi nơi tự nạp và tự dựng là mỗi nơi một định nghĩa "chưa đặt" và "hỏng" — bài học phân hệ KPI; và nạp theo từng người trong vòng lặp là N+1 trên job chạy mỗi 2 phút. Luật dựng nằm ở hàm thuần ; lớp này chỉ đi lấy dữ liệu, lấy múi giờ từ cấu hình chung và ghi log cảnh báo cho dòng hỏng (hàm thuần không log được).

Giờ làm riêng của một loạt người: một lần đọc cấu hình (múi giờ) + một truy vấn ChatAgentPresence.

Từ điển đủ mọi mã hợp lệ được hỏi (mã <= 0 bị bỏ). Người không có dòng mang — người gọi không phải xử lý khoá thiếu, và phân biệt "chưa đặt" bằng .

Giờ làm riêng của một người — bản một-người của .

Dựng giờ riêng từ các dòng ChatAgentPresence người gọi đã nạp sẵn — không truy vấn gì. Dành cho nơi đã có dòng trong tay (máy chia nạp cả lô ở ChatAgentAvailabilityResolver) để không phải đọc lại bảng, mà vẫn đi đúng một đường dựng và một đường log.

Các mã cần kết quả; mã không có trong là "chưa đặt" Dòng đã nạp, khoá theo StaffId Múi giờ cấu hình — người gọi thường đã có nó từ

Dòng hỏng vẫn được dùng như "luôn trong ca" (fail-open), nhưng phải để lại dấu vết: không log thì một người lặng lẽ nhận khách cả đêm mà không ai biết giờ làm họ đặt đã mất tác dụng.

Các cột giờ của một dòng ChatAgentPresence — chiếu thẳng từ truy vấn.

Các cột giờ của một dòng ChatAgentPresence — chiếu thẳng từ truy vấn.

Phạm vi chọn người nhận của mức DataAccessScope.SelfOnly — "cùng danh sách phụ trách kênh của chính hội thoại đang mở" (sổ nợ PP-38, kế hoạch §6.6, chốt 2026-08-30).

Hàm thuần, tách khỏi controller vì đây là một quyết định PHÂN QUYỀN và repo này chưa từng có ca test nào dựng SocialChatController: User.GetCurrentUser() bắt mọi ngoại lệ rồi trả UserId = 0, nên một ca test controller dựng thiếu claim sẽ XANH vì lý do sai (rơi vào nhánh staffId <= 0) thay vì đỏ. Cùng lý do và là hàm thuần. Luật cố ý hai chiều. Xem XML-doc của SocialChatController.IsStaffInMyScopeAsync để biết vì sao vế "người chuyển cũng phải ở trong danh sách" không phải trang trí.

Hai người có cùng nằm trong một danh sách phụ trách kênh không.

Danh sách phụ trách đang hoạt động của kênh chứa hội thoại — luôn là kết quả của IChatChannelStaffService.GetChannelPeerIdsOfConversationAsync. Rỗng nghĩa là không tra được kênh hoặc kênh chưa có ai phụ trách: khi đó không ai được chọn. Người đang thực hiện việc chuyển / phân công Người được chọn làm người nhận

Mức phạm vi hội thoại chat của một người dùng, theo §3.7 của kế hoạch phân phối khách chat. Giá trị số chỉ dùng để so mức cao thấp trong bộ nhớ, KHÔNG lưu xuống database.

Chỉ hội thoại mình đang giữ — mặc định của mọi tài khoản

Hội thoại của mình và của cấp dưới trực tiếp (DataAccessScope.ManagedTeam)

Mọi hội thoại của những kênh mình là trưởng nhóm hoặc chủ kênh

Mọi hội thoại của toàn hệ thống

Phạm vi hội thoại chat của một người dùng tại một thời điểm — kết quả của . Lớp này giữ một điều kiện lọc duy nhất () dùng lại ở mọi đường đọc. Chép luật lọc ra 13 chỗ là cách chắc chắn nhất để chúng lệch nhau, và một chỗ lệch trên bề mặt này là một lỗ IDOR (bài học docs/security-audit-2026-07-11.md).

Mức phạm vi cao nhất người này đạt được

Người dùng mà phạm vi này thuộc về

Những kênh có hàng rào — kênh mà quản trị đã chuyển khỏi . Cố ý liệt kê kênh CÓ hàng rào chứ không đọc AssignmentMode qua navigation ChatConversation.ChatChannel: điều kiện lọc phải chạy đúng cả khi lời gọi không Include navigation đó. Danh sách này rất nhỏ (đo trên dev 2026-08-28: 3 kênh).

Những kênh người này xem được TOÀN BỘ hội thoại — kênh mình là trưởng nhóm () hoặc chủ kênh ().

Những nhân viên mà người này xem được hội thoại của họ: luôn có chính mình, thêm cấp dưới trực tiếp khi DataAccessScope = ManagedTeam.

Những hội thoại người này từng giữ và còn được đọc — quyết định §6.2, sổ nợ PP-10 đã đóng ở giai đoạn B. Nạp sẵn thành một danh sách mã thay vì lồng một Any() vào biểu thức lọc, vì hai lý do. Thứ nhất, biểu thức phải dịch được sang SQL ở mọi đường đọc cùng lúc, và một EXISTS lồng đòi navigation collection trên ChatConversation — thêm một navigation vào entity đang phục vụ khách thật chỉ để phục vụ hàng rào là cái giá đắt hơn cần thiết. Thứ hai, và quan trọng hơn: danh sách nạp sẵn chạy giống hệt nhau trên database thật và trên kho dữ liệu giả của bộ test, còn navigation collection thì rỗng trong test trừ khi từng ca tự dựng nó — nghĩa là ca test sẽ xanh vì lý do sai. Cỡ danh sách: đo trên dev 2026-08-28, toàn hệ thống 21 hội thoại/ngày. Một sale làm tròn năm tích khoảng vài trăm mã. Nếu con số này lớn lên tới mức phải cắt, chỗ sửa là chứ không phải lớp này.

Phạm vi "thấy tất cả" — dùng cho Founder, quyền ChatConversation.ViewAll, và các luồng máy chạy (webhook, job)

Điều kiện lọc dùng chung cho MỌI đường đọc hội thoại. Đọc thành lời: hội thoại thuộc kênh chưa bật hàng rào (giữ nguyên hành vi hôm nay, §6.3) hoặc thuộc kênh mình phụ trách toàn bộ hoặc đang giao cho người trong phạm vi của mình. Hệ quả có chủ ý: hội thoại chưa giao cho ai ở một kênh đã bật hàng rào thì sale thường KHÔNG thấy — nó là hàng chờ, thuộc về trưởng nhóm và người điều phối. Ở giai đoạn A chưa có máy phân phối nên kênh vừa bật AutoDistribute sẽ có hàng chờ không ai ngoài trưởng nhóm nhìn thấy; đó là lý do giao diện phải cảnh báo rõ khi đổi chế độ, và là lý do trình tự production bật thử đúng một kênh trước. Mức chấm cả người đang giữ lẫn người từng giữ hội thoại với KeepReadAccess = true (§6.2, PP-10 đóng ở giai đoạn B). Nhánh "từng giữ" chỉ MỞ RỘNG phạm vi, không bao giờ thu hẹp — nên một hội thoại đang trong phạm vi vẫn ở trong phạm vi dù lịch sử nói gì.

Điều kiện lọc cho các đường GHI: giống nhưng bỏ nhánh "từng giữ".

Quyết định §6.2 viết nguyên văn: sale cũ "còn xem chỉ đọc". Hai chữ chỉ đọc là ranh giới này. Không có nó thì việc mở phạm vi ở giai đoạn B (PP-10) đồng thời mở cả mười đường ghi: người từng giữ hội thoại ba tháng trước vẫn gửi tin cho khách của người đang giữ, gỡ liên kết khách hàng, đổi trạng thái, thậm chí phân công lại hội thoại đó cho chính mình. Đó không phải một lỗ do sơ suất — nó là hệ quả trực tiếp và bắt buộc của việc nới một hàng rào, đúng bài học F-7 của giai đoạn A: mỗi lần nới phạm vi phải soi lại xem những đường nào vừa được nới theo mà không ai định thế. Biểu thức này chính là biểu thức của giai đoạn A, giữ nguyên từng nhánh. Người ĐANG giữ, trưởng nhóm của kênh, người xem-tất-cả và kênh Shared ghi được như cũ.

Chấm một hội thoại đã nạp sẵn — phạm vi đọc. Dùng CHÍNH biểu thức của đã biên dịch — không có luật thứ hai để lệch.

Chấm một hội thoại đã nạp sẵn — phạm vi ghi, tức có được thay đổi hội thoại này không. Xem .

Nguồn duy nhất của luật "ai xem được hội thoại chat của ai" (kế hoạch phân phối khách chat §3.7). Tách riêng vì phân hệ chat có 13 đường đọc/ghi cùng chạm một tập dữ liệu, và bài học của KpiVisibilityResolver đã chỉ đích danh rủi ro: đường thứ hai quên lọc phạm vi là lỗ IDOR kinh điển. Mọi đường phải hỏi đúng lớp này.

Phạm vi hội thoại của một người dùng. ≤ 0 (luồng máy chạy: webhook, job nền) trả về phạm vi rỗng nhất có thể — mọi đường máy chạy phải tự truyền khi thật sự cần toàn quyền, chứ không được hưởng nó nhờ thiếu một tham số.

Phạm vi dùng RIÊNG cho màn điều phối hàng chờ.

Khác đúng một điểm: người có ChatDistribution.Manage được mức All. Lý lẽ: sau bản vá F-1, quyền ấy là quyền duy nhất đổi được chế độ phân phối của một kênh và đặt được vai trò Owner/Leader — người giữ nó đã có thể tự ghi mình làm chủ kênh bất kỳ rồi đọc tất cả. Cho họ nhìn hàng chờ không mở thêm cửa nào; giấu đi chỉ khiến họ đi đường vòng bằng cách tự nâng vai trò, và đường vòng đó mới là thứ không ai rà được. Chỉ dùng cho hàng chờ. Người gọi phải lọc thêm AssignedStaffId == null; dùng phạm vi này ở một đường đọc thường là biến quyền quản trị phân phối thành quyền đọc mọi hội thoại của mọi sale — đúng thứ §3.7 cố ý KHÔNG cho, khi nó tách ChatConversation.ViewAll ra thành một quyền riêng.

Bỏ qua mọi ràng buộc phạm vi

Xem hội thoại của toàn hệ thống

Xem toàn bộ hội thoại của kênh mình là trưởng nhóm

Quản trị phân phối toàn hệ thống — xem ResolveForQueueAsync

Những hội thoại mà người này (hoặc cấp dưới của họ) từng giữ và còn được đọc — quyết định §6.2, đóng sổ nợ PP-10.

Lấy theo cả chứ không riêng người đang hỏi, để nhánh "từng giữ" đi cùng luật với nhánh "đang giữ" ngay cạnh nó trong biểu thức lọc: quản lý mức Team xem được hội thoại cấp dưới đang cầm thì cũng xem được hội thoại cấp dưới từng cầm. Hai nhánh lệch nhau ở điểm này là thứ không ai giải thích nổi cho người dùng, và cũng không ai nhớ nổi khi sửa lần sau. Chỉ MỞ RỘNG. Truy vấn hỏng hay trả rỗng thì phạm vi trở về đúng bằng giai đoạn A — hẹp hơn, chưa bao giờ rộng hơn. Query() chứ không QueryAll(): đây là điều kiện MỞ RỘNG phạm vi nên đọc bản ghi đã xoá mềm vào đây là dùng dữ liệu chết để cấp quyền — ngược hẳn ngoại lệ có chủ ý của guardedChannelIds ở trên, nơi bản ghi đã xoá chỉ làm phạm vi hẹp lại.

Đọc của một tài khoản — một luật, một chỗ cho cả hàng rào quyền xem lẫn đường cấu hình sale phụ trách kênh. Nguồn là UserPreference.DataAccessScope, KHÔNG phải User. Tài khoản chưa có dòng cấu hình nào thì mặc định — cùng giá trị mà KpiVisibilityResolver dùng. Đọc thẳng repository thay vì gọi IUserService.GetDataAccessScopeAsync để hai chỗ này dựng được trong test mà không phải giả lập một interface 54 method.

Kho cấu hình người dùng Tài khoản cần tra; ≤ 0 trả về phạm vi hẹp nhất

Cửa sổ giờ làm việc của đội sale — hàm thuần, không chạm database, không đọc AppConfig, không hỏi đồng hồ hệ thống. Tách ra khỏi phần chạm hạ tầng đúng cách ChatRealtimeAudience.Resolve đã làm ở giai đoạn A: nhờ thế kiểm được bằng bảng ca (thời điểm vào → trong hay ngoài giờ làm) mà không cần dựng kho dữ liệu giả nào. Repo không có abstraction đồng hồ (không ISystemClock, không TimeProvider) nên "bây giờ" phải là tham số, đúng khuôn IComponentConditionEvaluator.Evaluate(input, asOf). Vì sao giờ làm việc quan trọng đến thế ở giai đoạn C: số đo Việc 0 loại bỏ hai trong bốn nguồn mà §3.5 dự kiến (nghỉ phép — bảng rỗng, PP-11; chấm công — chỉ 20/40 sale dùng, PP-12), và chủ dự án trả lời "chưa ai" cho câu hỏi bao nhiêu sale sẽ dùng menu tự đổi trạng thái. Nên đây là nguồn chính quyết định ai đang nhận khách, không phải nguồn phụ. KC-18 (2026-09-27) đảo tiền đề trên: chủ dự án chốt nhận khách theo trạng thái sale đặt, không theo giờ làm (plan khoá học chat §8.6–§8.7). Lớp này nay có ba đường dựng: cho cấu hình chung (giữ nguyên nghĩa cũ — chỉ còn là giờ gợi ý, múi giờ và bộ lọc tiêu chí "trả lời đầu tiên"), cho giờ riêng một sale tự đặt, và cho người chưa đặt.

Cửa sổ mặc định, dùng khi cấu hình thiếu hoặc không đọc được: 08:00–17:30, Thứ Hai đến Thứ Bảy, nghỉ trưa 12:00–13:00, múi giờ +07:00. Đây là giờ làm chính thức đã xác nhận với chủ dự án 2026-08-29, không phải một con số tròn bịa ra. Rơi về đây là fail-safe, không phải fail-open: cấu hình hỏng không được biến cả tuần thành giờ làm (chia khách lúc 2 giờ sáng) mà cũng không được biến cả tuần thành ngoài giờ (cả đội ngừng nhận khách).

Giờ kết thúc mà người dùng chọn để nói "làm tới hết ngày" (KC-18, thiết kế mục 3). Cột SQL time không chứa được 24:00, ô chọn giờ trên trình duyệt cũng không cho chọn 24:00 — nên 23:59 là cách duy nhất người dùng nói được ý đó. Đường giờ RIÊNG () đổi nó thành 24:00 trong bộ nhớ. Đường cấu hình chung () không đổi — giữ nguyên nghĩa cũ để bảng ca cũ không đổi.

Một ngày tròn — giờ kết thúc "hết ngày" trong bộ nhớ (24:00).

Cửa sổ luôn trong ca ở múi giờ mặc định +07:00 — xem . Người gọi có múi giờ cấu hình trong tay thì dùng với múi giờ đó thay vì thuộc tính này.

Mốc gốc để quy một thời điểm về "tổng số phút giờ làm đã trôi qua kể từ mốc gốc". 0001-01-01 là Thứ Hai, nên số ngày kể từ mốc này chia 7 ra đúng số tuần tròn mà không phải chỉnh lệch pha.

Số phút làm việc của một ngày làm trọn vẹn (đã trừ nghỉ trưa)

Số phút làm việc của một tuần trọn vẹn

Giờ bắt đầu làm việc (giờ địa phương theo )

Giờ kết thúc làm việc. Khoảng làm việc là nửa mở [Start, End). Với giờ riêng chọn 23:59 và với , giá trị này là 24:00 (1.00:00:00) — định dạng nó bằng hh\:mm sẽ ra 00:00. Hiển thị thì hỏi trước.

Ca kéo tới hết ngày ( là 24:00) — để lớp hiển thị in "23:59" hoặc "hết ngày" thay vì "00:00".

Cửa sổ "luôn trong ca" (): mọi thời điểm đều là giờ làm, số phút giờ làm bằng số phút đồng hồ thật.

Giờ bắt đầu nghỉ trưa, null = không có nghỉ trưa

Giờ kết thúc nghỉ trưa, null = không có nghỉ trưa. Giờ riêng nghỉ tới 23:59 trong ca kết thúc 23:59 mang giá trị 24:00 ở đây — cùng luật với ; hiển thị thì hỏi .

Nghỉ trưa kéo tới hết ngày ( là 24:00) — để lớp hiển thị không in 00:00.

Múi giờ áp cho cửa sổ này (Việt Nam = +07:00)

Các ngày làm việc trong tuần

Dựng cửa sổ giờ làm việc từ các chuỗi cấu hình thô. Không bao giờ ném lỗi: mọi giá trị không đọc được đều rơi về vế tương ứng của .

Giờ vào, dạng HH:mm Giờ ra, dạng HH:mm Giờ bắt đầu nghỉ trưa, dạng HH:mm; rỗng = không nghỉ trưa Giờ kết thúc nghỉ trưa, dạng HH:mm; rỗng = không nghỉ trưa Danh sách ngày làm, ngăn cách bằng dấu phẩy, đánh số theo cách gọi tiếng Việt: 2 = Thứ Hai … 7 = Thứ Bảy, 8 = Chủ Nhật. Chọn cách đánh số này thay vì DayOfWeek của .NET (0 = Chủ Nhật) vì người vận hành sẽ sửa ô này trên màn quản trị, và ở đó "2" phải có nghĩa là Thứ Hai. Múi giờ, tính bằng giờ so với UTC

Cửa sổ luôn trong ca (KC-18, thiết kế mục 2): luôn đúng, bằng số phút đồng hồ thật.

Đây là cửa sổ của mọi sale chưa tự đặt giờ làm — chủ dự án chốt 2026-09-27 (§8.6, §8.7): nhận hay không nhận khách là do trạng thái sale đặt, không do giờ làm. Cấu hình chung Chat.WorkingHours.* không còn áp cho ai nữa, chỉ còn là giờ gợi ý. Vì sao không dựng bằng Parse("00:00", "23:59", …) như production đang làm: khoảng làm việc là nửa mở [Start, End), nên cấu hình ấy để hở đúng phút 23:59 mỗi đêm — khách nhắn lúc 23:59:30 rơi vào "Ngoài giờ". Cửa sổ này có End = 24:00 và đi đường tắt riêng nên không có lỗ đó. // vẫn mang giá trị nhất quán (00:00–24:00, cả bảy ngày, không nghỉ trưa) để lớp nào lỡ đọc chúng cũng không thấy rác. Múi giờ cấu hình (App.TimeZoneOffsetHours, lấy qua cấu hình chung). Vẫn cần dù đồng hồ không dừng: phép đếm tải trong ngày và phát lại quyết định chia ngày theo nó.

Dựng giờ làm riêng của một sale từ dòng ChatAgentPresence đã nạp sẵn — không có dòng nghĩa là chưa đặt.

Dòng trạng thái của người đó; null = chưa từng có dòng Múi giờ cấu hình

Dựng giờ làm riêng của một sale từ bốn cột giờ và cột ngày làm (KC-18, thiết kế mục 2–3). Không bao giờ ném lỗi và không bao giờ trả null.

Chưa đặt ( và cùng null) ⇒ , trạng thái . Hợp lệ ⇒ cửa sổ riêng, trạng thái . từ trở lên nghĩa là "hết ngày" và thành 24:00 trong bộ nhớ; cũng vậy (nghỉ tới hết ca "hết ngày" thì phút 23:59 cũng là giờ nghỉ, không phải giờ làm). Hỏng ⇒ vẫn , trạng thái , kèm câu mô tả để người gọi ghi log (hàm thuần không log được). Vì sao dữ liệu hỏng rơi về "luôn trong ca" chứ không về 08:00–17:30 như : rơi về là âm thầm đẩy một người ra "Ngoài giờ" từ 17:30 tới sáng hôm sau và cả Chủ Nhật, trong khi người đó chưa từng chọn giờ ấy. Cùng triết lý fail-open của : hỏng thì tệ nhất là chia khách cho người không muốn nhận lúc ấy, và họ đổi trạng thái là xong. Luật hợp lệ dùng chung với — dòng nào API nhận được thì hàm này dựng được, không có vùng xám giữa hai định nghĩa.

Kiểm hợp lệ giờ làm riêng mà sale (hoặc quản lý đặt hộ) gửi lên — hàm thuần, trả danh sách lỗi tiếng Việt để trả thẳng cho người dùng, kèm giá trị đã chuẩn hoá để ghi xuống cột.

Giờ bắt đầu và giờ kết thúc cùng trống ⇒ yêu cầu xoá giờ riêng, về "chưa đặt" (); các ô còn lại bị bỏ qua. Giờ dạng HH:mm (hoặc H:mm); giờ bắt đầu phải sớm hơn giờ kết thúc — ca qua đêm chưa hỗ trợ, cùng lý do với . Giờ kết thúc 23:59 nghĩa là hết ngày; gõ 24:00 được hiểu là 23:59. Nghỉ trưa: đủ cả hai đầu hoặc trống cả hai; đầu trước sớm hơn đầu sau; nằm trong [giờ bắt đầu, giờ kết thúc]; không phủ kín cả ca (phủ kín là một người vĩnh viễn "Ngoài giờ" mà không ai hiểu vì sao). Trong ca kết thúc 23:59, nghỉ tới 23:59 (hay 24:00) là nghỉ tới hết ngày — dựng đúng nghĩa ấy. Ngày làm: tập con khác rỗng của mã 2 (Thứ Hai) … 8 (Chủ Nhật), cùng cách đánh số với Chat.WorkingHours.WorkingDays. Mã lặp được gộp, không coi là lỗi. Khác có chủ ý: đọc cấu hình người vận hành đã lưu nên phải nuốt mọi thứ và rơi về mặc định; hàm này đứng ở cửa API nên phải từ chối và nói rõ vì sao — nhận bừa rồi rơi về một giá trị khác là lưu một thứ người dùng không hề chọn.

Thời điểm có nằm trong giờ làm việc không.

Quy về múi giờ trước khi hỏi thứ mấy và mấy giờ. Không làm bước này thì cùng một thời điểm cho hai câu trả lời khác nhau tuỳ máy chủ chạy ở UTC hay ở giờ Việt Nam — đúng lớp lỗi lệch múi giờ đã cắn ở đợt bảo dưỡng xe.

Số phút giờ làm trôi qua giữa hai thời điểm. Trả 0 khi không muộn hơn .

Đây là phép đo mà giai đoạn E đứng lên: "quá hạn phản hồi" không phải hiệu số hai mốc thời gian. Khách nhắn 17:20 Thứ Sáu, sale trả lời 08:10 Thứ Hai — đồng hồ thường nói 62 giờ, đồng hồ giờ làm nói 60 phút. Đo bằng đồng hồ thường là biến mọi tin đến buổi tối thành một lượt vi phạm ngay khi trời sáng, và đó đúng là điều §4 GĐ E cấm ("tin nhắn 2 giờ sáng không được làm hỏng điểm của ai"). Không lặp vòng từng phút, cũng không lặp từng ngày. Một hội thoại bị bỏ quên ba tháng sẽ làm một vòng lặp theo phút chạy 130 nghìn bước trong một job quét 2 phút — và dữ liệu dev đã có sẵn một bản ghi lệch một năm (Đ5 §2.4). Cách làm ở đây quy mỗi thời điểm về "tổng phút giờ làm kể từ " rồi lấy hiệu: số tuần tròn tính bằng một phép nhân, phần dư nhiều nhất 6 ngày. Chưa trừ ngày lễ — nợ PP-25, cố ý. Bảng Holiday đo được 0 dòng trên dev (2026-08-29), nên dựng nhánh ấy bây giờ là dựng thêm một nhánh chết, đúng bài học PP-11. Khi nhân sự bắt đầu điền bảng đó thì phép trừ nằm ở lớp gọi, không nằm trong hàm thuần này.

Các khoảng trong ca nằm lọt trong [from, to), đã sắp theo thời gian và không chồng nhau — mỗi ngày làm nhiều nhất hai khoảng (trước và sau nghỉ trưa).

Tồn tại cho phép hợp khoảng của đồng hồ hàng chờ (KC-18, thiết kế mục 5): "có ít nhất một ứng viên vào ca" là hợp của nhiều cửa sổ giờ làm khác nhau, mà hợp thì phải có khoảng trong tay — chỉ trả một con số, cộng số của hai người là đếm đôi phút cả hai cùng trong ca. Cùng một định nghĩa với : một thời điểm nằm trong khoảng trả về khi và chỉ khi nói đúng, và tổng độ dài các khoảng bằng (bảng ca đối chiếu ở ChatCoverageTests). Viết lại luật nghỉ trưa theo một cách khác ở đây là dựng định nghĩa thứ hai của "trong ca". Lặp theo ngày, không theo phút — người gọi phải tự giới hạn độ dài khoảng (đồng hồ hàng chờ cắt ở ).

Ca của một ngày làm, tính bằng giờ trong ngày: [Start, End) trừ nghỉ trưa [BreakStart, BreakEnd). Đúng điều kiện mà kiểm — nghỉ trưa thiếu một đầu hoặc ngược chiều thì coi như không có.

Tổng số phút giờ làm từ tới . Hàm đơn điệu không giảm, nên hiệu của hai lần gọi chính là số phút giờ làm giữa chúng.

Số phút làm việc của trọn một ngày, theo thứ trong tuần.

Số phút làm việc đã trôi qua trong một ngày, tính từ 00:00 tới .

Số phút nghỉ trưa nằm lọt trong khoảng [windowStart, windowEnd) của một ngày. Không có nghỉ trưa, hoặc nghỉ trưa nằm ngoài khoảng, thì bằng 0.

2 = Thứ Hai … 7 = Thứ Bảy, 8 = Chủ Nhật; mã khác trả null.

Đọc một ô giờ người dùng gửi lên. Nhận thêm 24:00 như 23:59 — cả hai đều là "hết ngày", và bắt người dùng hiểu cột SQL time để gõ đúng là vô lý.

Đọc chuỗi mã ngày làm theo luật chặt — khác của cấu hình chung (bỏ qua mã lạ, rỗng thì rơi về mặc định). Mã lạ hay rỗng ở đây là lỗi. Trả tập mã đã sắp xếp tăng dần, không lặp.

Kiểm thứ tự các mốc. Chỉ so khi đã đọc được đủ các vế liên quan — so trên một vế hỏng chỉ đẻ thêm lỗi thứ hai cho cùng một nguyên nhân. là giá trị người dùng thấy (23:59 = hết ngày), chưa đổi sang 24:00.

chỉ nhận múi giờ tròn phút trong ±14 giờ — ngoài khoảng đó nó ném lỗi. Múi giờ lạ rơi về +07:00 như đang làm.

Giờ làm riêng của một sale đang ở tình trạng nào (KC-18).

Chưa đặt — không có dòng ChatAgentPresence, hoặc giờ bắt đầu và giờ kết thúc cùng trống. Đây là trạng thái BÌNH THƯỜNG của gần như mọi sale (§8.6: mặc định ẩn giờ làm). Cửa sổ là "luôn trong ca"; tiêu chí 5 coi là chưa có mẫu (§8.7 câu 2).

Đã tự đặt (hoặc được quản lý đặt hộ) và dữ liệu hợp lệ.

Có dữ liệu nhưng hỏng (sửa tay trong DB, hoặc luật hợp lệ siết lại sau này). Cửa sổ vẫn là "luôn trong ca" — fail-open; người gọi phải ghi log cảnh báo để có người sửa.

Kết quả dựng giờ làm riêng của một sale: cửa sổ để dùng ngay, kèm tình trạng để người gọi phân biệt "chưa đặt" với "đã đặt" (tiêu chí 5, giao diện) và biết khi nào phải log.

Cửa sổ để dùng — không bao giờ null. Chưa đặt hoặc hỏng thì là "luôn trong ca". Tình trạng của giờ riêng Mô tả lỗi dữ liệu bằng tiếng Việt khi là ; còn lại null

Kết quả dựng giờ làm riêng của một sale: cửa sổ để dùng ngay, kèm tình trạng để người gọi phân biệt "chưa đặt" với "đã đặt" (tiêu chí 5, giao diện) và biết khi nào phải log.

Cửa sổ để dùng — không bao giờ null. Chưa đặt hoặc hỏng thì là "luôn trong ca". Tình trạng của giờ riêng Mô tả lỗi dữ liệu bằng tiếng Việt khi là ; còn lại null

Cửa sổ để dùng — không bao giờ null. Chưa đặt hoặc hỏng thì là "luôn trong ca".

Tình trạng của giờ riêng

Mô tả lỗi dữ liệu bằng tiếng Việt khi là ; còn lại null

Người này có giờ làm riêng dùng được không. Hỏng tính như chưa đặt: chấm tỉ lệ sẵn sàng trên một giờ làm mà chính dữ liệu của nó đã sai là chấm trên cát.

Chưa đặt giờ riêng — dùng cửa sổ "luôn trong ca".

Giờ riêng hợp lệ.

Giờ riêng hỏng — dùng cửa sổ "luôn trong ca", kèm lý do để log.

Kết quả của : danh sách lỗi tiếng Việt, hoặc các giá trị đã chuẩn hoá để ghi thẳng xuống bốn cột giờ và cột ngày làm.

Yêu cầu xoá giờ riêng, về "chưa đặt" — mọi cột giờ và ngày làm ghi null.

Lỗi tiếng Việt, trả thẳng cho người dùng. Rỗng = hợp lệ.

Hợp lệ (kể cả trường hợp xoá)

Giờ bắt đầu và giờ kết thúc cùng trống — xoá giờ riêng

Giờ bắt đầu đã chuẩn hoá; null khi xoá hoặc không hợp lệ

Giờ kết thúc đã chuẩn hoá, dạng lưu: hết ngày là 23:59 (cột time không chứa được 24:00); null khi xoá hoặc không hợp lệ.

Giờ bắt đầu nghỉ trưa; null = không nghỉ trưa

Giờ kết thúc nghỉ trưa; null = không nghỉ trưa

Mã ngày làm đã sắp xếp, không lặp, dạng "2,3,4,5,6,7"

Lớp duy nhất trong hệ thống biết giao thức của Facebook Graph API / Messenger Platform. Mọi số liệu dưới đây lấy nguyên văn từ tài liệu thật ngày 2026-08-27 tại developers.facebook.com (Messenger Platform → Send API, Attachment Upload API, User Profile API; Facebook Login → Long-lived tokens; Pages API → Getting Started). Lớp này KHÔNG chạm tới database và KHÔNG biết gì về ChatChannel: nó nhận token đã giải mã sẵn và trả về kết quả thô. Việc lấy/lưu token là của ChatChannelService, việc ghép vào lõi chat là của FacebookMessenger.

Dựng đường dẫn hộp thoại cấp quyền để quản trị viên bấm vào và tự cấp quyền — đúng luồng Facebook Login for Business mà Pancake và các nền tảng khác dùng, thay cho việc dán tay user access token lấy từ Graph API Explorer. Có khai SocialChat:Facebook:LoginConfigId thì đi bằng config_id (danh sách quyền cố định, khai sẵn trên cổng nhà phát triển); không khai thì lui về Facebook Login thường với tham số scope. Cả hai đều trả code về RedirectUri.

Đổi code Facebook gửi kèm lần chuyển hướng về lấy user access token. Token trả về ở đây ngắn hạn — phải đưa tiếp qua trước khi lấy Page token, nếu không Page token thừa hưởng tuổi thọ vài giờ rồi kênh chết im lặng.

Đổi user access token ngắn hạn (dán từ Graph API Explorer, sống ~1-2 giờ) lấy bản dài hạn (~60 ngày). Page access token lấy từ bản dài hạn thì không có hạn dùng.

Danh sách Page mà chủ tài khoản đang quản lý, kèm Page access token của từng Page (GET /me/accounts). Kết quả có chứa bí mật — không bao giờ ghi nhật ký, không trả thẳng ra API.

Gửi tin nhắn văn bản qua Send API. là mid của tin mà tin này TRẢ LỜI TRÍCH DẪN, bỏ trống thì gửi tin thường. Nó đi vào thân request ở cấp gốc — reply_to.mid nằm ngang hàng với recipient và message, KHÔNG nằm trong message. Chiều nhận webhook thì ngược lại: ở đó reply_to nằm trong message (xem FacebookWebhookParser.ReadRepliedMessageId). Hai chiều lệch chỗ nhau là chỗ dễ viết sai nhất; đã đối chiếu tài liệu Send Messages ngày 2026-08-28.

Tải một tệp ảnh lên máy chủ Facebook để lấy attachment_id dùng lại được.

Gửi tin nhắn ảnh. Truyền một trong hai: (đã tải lên) hoặc (đường dẫn công khai). Không có tham số chú thích: một tin Messenger mang hoặc text hoặc attachment, không mang cả hai. Chú thích là một tin văn bản riêng, do FacebookMessenger gửi tiếp sau.

Thả (hoặc gỡ) một biểu tượng cảm xúc lên tin nhắn của khách. Đi qua sender_action của chính Send API chứ không phải một endpoint riêng — đó là lý do nó dễ bị kết luận nhầm là "Facebook không cho Page thả cảm xúc" khi chỉ đọc trang Send API. Facebook nhận emoji tuỳ ý, không phải một tập mã cố định như Zalo. Tài liệu chốt hai ràng buộc: request sender_action chỉ được mang recipient + sender_action (+ payload), không kèm message; và khi gỡ thì bỏ hẳn trường reaction khỏi payload.

Lấy tên và ảnh đại diện của một người dùng đã nhắn tin cho Page (tra theo PSID). Facebook từ chối hồ sơ bằng 100/33 (thiếu Advanced Access của Business Asset User Profile Access, sổ nợ SC-23) thì lui về đọc tên người tham gia hội thoại — đường này chỉ cần pages_messaging, nhưng không có ảnh đại diện.

Kéo tối đa 20 tin gần nhất của hội thoại Messenger giữa Page và một khách (GET /me/conversations?platform=messenger&user_id={PSID}&fields=messages…). Cùng endpoint mà đường dự phòng đọc tên khách (SC-23) đã gọi được bằng Page token hiện có (đo 2026-10-23), chỉ xin thêm trường messages. Tài liệu Conversations API ghi đòi pages_manage_metadata + pages_read_engagement + pages_messaging — thiếu quyền thì Facebook trả lỗi và lỗi ấy đi nguyên ra cho nhân viên.

Đăng ký Page với App để webhook của Page bắt đầu chảy về (POST /{page-id}/subscribed_apps, sổ nợ SC-20). Hai tầng đăng ký là HAI việc khác nhau và cần cả hai: subscription cấp App (/{app-id}/subscriptions, khai một lần trên cổng/Graph API) và bước này cho TỪNG Page. Thiếu bước này thì webhook im lặng tuyệt đối — không đến thì không có gì để ghi nhật ký. E3 đã phải làm tay hai lần, mỗi Page một lần.

Tên HttpClient đã đăng ký ở DependencyRegister

Phiên bản Graph API cố định trong mã nguồn. Meta gỡ từng phiên bản sau khoảng hai năm, nên đây là thứ phải rà lại định kỳ — ghim số ở một chỗ để lúc nâng chỉ sửa một dòng. v25.0 là phiên bản tài liệu ngày 2026-08-27 đang dùng trong mọi ví dụ.

Hộp thoại cấp quyền nằm ở www.facebook.com chứ không phải graph.facebook.com — đây là trang người dùng nhìn thấy, không phải endpoint API.

Bộ quyền xin khi KHÔNG khai LoginConfigId. Giữ đúng bốn quyền mà luồng kết nối kênh thật sự dùng, không xin thừa: pages_show_list để liệt kê Page, pages_messaging để nhắn tin, pages_manage_metadata để đăng ký webhook, và business_management vì Page nằm trong Business Portfolio sẽ KHÔNG hiện trong /me/accounts nếu thiếu nó — đo được bằng loại trừ ngày 2026-08-27 (sổ nợ SC-22).

Giới hạn tài liệu ghi cho nội dung tin nhắn văn bản của Send API

Trần dung lượng ảnh tải lên. Trùng đúng trần của vì đó là nguồn DUY NHẤT sinh ra tệp đi qua đây — đặt rộng hơn chỉ tạo ra một con số không ai kiểm được. Facebook cho phép lớn hơn; muốn nới thì nới ở đầu vào, không nới ở đây.

Khoá bí mật của ứng dụng Facebook. Đây vừa là khoá ký webhook (X-Hub-Signature-256) vừa là client_secret của luồng đổi token — khác Zalo, nơi hai việc đó dùng hai khoá khác nhau.

Đường dẫn công khai Facebook chuyển hướng về sau khi quản trị viên cấp quyền. Phải TRÙNG KHÍT chuỗi đã khai ở Valid OAuth Redirect URIs trên cổng nhà phát triển — lệch một dấu gạch chéo là Facebook từ chối cả lần dựng hộp thoại lẫn lần đổi token, và cùng chuỗi đó phải được gửi lại ở bước đổi code (bẫy Zalo đã cắn một lần).

Mã cấu hình đăng nhập của Facebook Login for Business (App Dashboard → Facebook Login for Business → Configurations). Để trống thì lui về Facebook Login thường với ; cả hai đều chạy, nhưng bản có config_id mới là thứ hồ sơ App Review đòi quay trong screencast.

Các field mà parser đang có nhánh xử lý. KHÔNG thêm field nào vào đây khi parser chưa có nhánh (nguyên tắc F1-1 của plan): bật là tin thật chảy vào, và một nhánh Ignore mới chỉ đổi chỗ vấn đề. Muốn thêm message_reads (SC-3) thì bật ở CẢ subscription cấp App rồi mới thêm vào đây, và đo lưu lượng thật trước khi lật SupportsReadReceipt. 🔴 Đăng ký webhook Facebook có HAI TẦNG, và tầng dưới nằm ở đúng dòng này. Tầng trên là subscription cấp App (tick trên cổng nhà phát triển); tầng dưới là subscribed_fields của từng Page — do code đặt, không phải do cổng. Tick trên cổng mà quên dòng này thì Facebook không gửi field đó về, và không có thao tác nào trên cổng sửa được. Đây chính là bẫy đã cắn với message_reactions ở GĐ G: parser có nhánh, cổng đã tick, mà chuỗi này vẫn còn ba field cũ. Thứ tự bắt buộc khi thêm field: bật ở subscription cấp App TRƯỚC, rồi mới deploy code này. Làm ngược thì Graph có thể từ chối cả lời gọi subscribed_apps và mọi lần kết nối Page mới đều báo "chưa đăng ký được webhook". Và sau khi deploy, các Page đang chạy vẫn giữ bộ field cũ — hàm này chỉ chạy lúc kết nối hoặc lúc bấm "Đăng ký lại webhook", nên phải bấm lại cho từng kênh Facebook.

Kiểu MIME suy từ đuôi tệp. Tệp đi qua đây đã được ChatAttachmentService nhận diện bằng chữ ký nội dung rồi đặt lại đuôi, nên đuôi ở đây là do máy chủ sinh chứ không phải do người dùng khai.

Mã lỗi Facebook trả cho GET /{PSID} khi App chưa có Advanced Access của Business Asset User Profile Access: "Object ... does not exist, cannot be loaded due to missing permissions". Đây là tín hiệu DUY NHẤT bật đường dự phòng.

Đọc tên khách từ danh sách người tham gia hội thoại Messenger của Page (GET /me/conversations?platform=messenger&user_id={PSID}&fields=participants{id,name}). Đường này chỉ cần pages_messaging — quyền kênh đã có sẵn để nhắn tin — nên chạy được ngay khi App Review chưa nộp. Đo 2026-10-23 trên Page LADA Express: khách thật bị 100/33 ở GET /{PSID} vẫn ra đúng tên ở đây, 1 hội thoại, 700-765 ms. Không có ảnh đại diện: participants chỉ mang id, name, email. Đi bằng /me thay vì /{page-id}: với Page access token thì /me CHÍNH là Page (thử trên Graph API Explorer 2026-10-23 — cùng kết quả với /{page-id}). Lợi hơn hẳn việc truyền page id vào: Page được suy ra từ chính token nên không thể lệch token, và chữ ký hàm cùng IPlatformMessenger giữ nguyên. Danh sách người tham gia có CẢ chính Page (cùng name "LADA Express"), nên phải lọc đúng id == PSID — lấy phần tử đầu là ghi tên Page vào hội thoại của khách.

Gọi một API đọc của Graph API và trả về phần tử gốc của JSON. Trả kèm mô tả lỗi tiếng Việt để luồng kết nối Page nói được lý do cho quản trị viên. Token đi ở header Authorization, KHÔNG ở tham số access_token trên query string — dù tài liệu Facebook dùng cách thứ hai trong mọi ví dụ. Lý do: đường dẫn request bị ghi vào nhật ký ở mức Information bởi chính IHttpClientFactory (danh mục System.Net.Http.HttpClient.*), mà cấu hình của repo để Logging:LogLevel:Default = Information — nghĩa là token sẽ nằm nguyên văn trong tệp log. Page access token thì KHÔNG có hạn dùng, nên một dòng log là một chìa khoá vĩnh viễn. Failure là cặp mã Facebook trả về, null khi lời gọi không tới được Facebook (quá hạn chờ, lỗi mạng, phản hồi không đọc được) — hai trường hợp phải tách được nhau để đường dự phòng của chỉ chạy khi bị TỪ CHỐI.

Đọc khối error của Graph API. Mọi lỗi của Facebook đều về dưới hình dạng này, kể cả khi mã HTTP là 200.

Đường dẫn hộp thoại cấp quyền Facebook, kèm những gì giao diện cần nói cho quản trị viên.

Dựng được đường dẫn hay không

Đường dẫn để mở trong cửa sổ mới

Lý do đọc được cho quản trị viên khi dựng không được

Chuỗi redirect đang dùng — để đối chiếu với ô khai trên cổng nhà phát triển

Chuỗi state đã ký của lần cấp quyền này. Giao diện phải giữ lại để hỏi danh sách Page sau khi cửa sổ đóng — đây là thứ thay cho việc cầm token trong trình duyệt.

true khi đi bằng config_id (Facebook Login for Business), false khi lui về Facebook Login thường với scope.

Danh sách quyền đang xin; chỉ có giá trị khi KHÔNG dùng config_id

Token Facebook trả về sau khi đổi bản dài hạn.

Hạn dùng; null nghĩa là token không hết hạn (Page token dài hạn).

Một Page mà tài khoản đang quản lý.

Page access token — BÍ MẬT, không bao giờ đi ra khỏi tầng service.

Kết quả một lần hỏi danh sách Page.

Kết quả một lần gửi tin.

Kết quả đăng ký Page với App (subscribed_apps, SC-20).

Kết quả tải ảnh lên máy chủ Facebook.

Hồ sơ rút gọn của một người dùng Messenger.

Dịch mã lỗi của Facebook Graph API ra tiếng người. Nội dung lấy từ tài liệu "Error Codes" và "Send API" đọc ngày 2026-08-27. Chỉ giữ những mã một nhân viên chăm sóc khách hàng có thể gặp — mã lạ thì trả nguyên văn thông điệp của Facebook kèm số hiệu, tuyệt đối không nuốt. Khác Zalo, Facebook phân biệt bằng CẶP mã chính + mã phụ: cùng mã 10 nhưng mã phụ khác nhau là hai nguyên nhân hoàn toàn khác. Tra cặp trước, rồi mới lùi về mã chính.

Trả về mô tả tiếng Việt của một mã lỗi Facebook, kèm số hiệu để tra cứu lại tài liệu.

Đọc phản hồi của API hội thoại Messenger (GET /me/conversations?platform=messenger&user_id={PSID}&fields=messages…) thành — cùng kiểu với tin đi qua webhook, để lõi đối chiếu được hai nguồn với nhau. Hình dạng tin ở đây KHÁC hẳn webhook, đừng chép logic bên FacebookWebhookParser sang: nội dung chữ nằm ở message (webhook là message.text), tệp đính kèm mang mime_type + image_data.url / video_data.url / file_url (webhook là type + payload.url), nhãn dán là một trường chuỗi sticker riêng, thời gian là chuỗi created_time dạng 2026-10-19T08:01:23+0000 (webhook là số mili giây). Vai không đảo như webhook: tin nào from.id là khách thì là tin vào, còn lại là tin Page gửi ra.

Trường xin Graph API. Chỉ xin những trường đã có trong tài liệu Message / Message Attachment — một trường sai tên là Facebook từ chối CẢ lời gọi (lỗi 100), không phải bỏ qua trường đó. limit(20) vì Facebook chỉ trả chi tiết của 20 tin gần nhất mỗi hội thoại; tin cũ hơn trả về là lỗi "message has been deleted" (Conversations API, đọc 2026-10-24).

Dòng HỆ THỐNG của hộp thư Meta Business Suite mà API hội thoại trả về lẫn như tin thường. Đo trên Page LADA Express 2026-10-24: chúng mang đúng from, to và tags (inbox,read,sent,source:web) như một tin nhân viên gõ tay — không trường nào phân biệt được, chỉ có câu chữ. Khách chưa bao giờ nhận những dòng này; chèn vào là khung chat hiện "ngoài LADA" cho một câu không ai gửi, và dòng nhãn tự động còn đè luôn dòng xem trước của hội thoại (đã xảy ra ở lượt nghiệm thu đầu, hội thoại 902). Câu chữ theo ngôn ngữ của Page. Thêm biến thể mới khi gặp — để lọt chỉ là một bong bóng thừa, còn lọc nhầm một tin thật thì không ai biết mà tìm lại.

Phía KHÁCH: "<tên> đã trả lời về một bài viết. Xem bài viết(https://…)" — dấu vết khách trả lời một bài viết của Trang, không phải câu khách gõ (đo được 2 lần).

Đọc toàn bộ tin trong phản hồi, xếp từ cũ tới mới.

Gốc JSON của phản hồi Graph API Page của kênh — ghi vào Khách của hội thoại — tin có from.id trùng mã này là tin vào

Câu này có phải dòng hệ thống của hộp thư chứ không phải tin ai đó gửi không

Loại nội dung và đường dẫn tệp. Không có gì đọc được (tin mẫu có nút bấm của công cụ tự động, tin chia sẻ bài viết…) thì ra rỗng — lõi bỏ qua loại đó thay vì chèn một bong bóng trống.

Graph API trả created_time kiểu 2026-10-19T08:01:23+0000 — độ lệch múi giờ KHÔNG có dấu hai chấm, dạng mà DateTimeOffset.TryParse không chắc nhận. Chèn dấu hai chấm trước rồi mới đọc. Đổi về giờ máy chủ cho cùng quy ước với webhook.

Kênh đẩy sự kiện chat về giao diện quản trị theo thời gian thực. Giai đoạn A đăng ký bản rỗng để lõi chat gọi được ngay; giai đoạn C chỉ thay bản hiện thực bằng SignalR, KHÔNG sửa tầng service.

Một hội thoại vừa thay đổi (tin mới, đổi trạng thái, đổi số tin chưa đọc)

Có tin nhắn mới trong hội thoại

Trạng thái giao nhận của một tin gửi đi vừa đổi

Phạm vi xem của một người vừa đổi — thu hồi những phòng realtime họ không còn được ở, và cho vào những phòng vừa mở ra. Hàng rào REST chặn ngay lần gọi kế tiếp, nhưng một kết nối SignalR đã mở thì ở lại trong nhóm cho tới khi đóng tab. Không có bước thu hồi này thì người vừa bị chuyển hội thoại đi vẫn nhận nguyên văn tin của khách theo thời gian thực — chặn cửa trước, mở cửa sau (finding F-3).

Người có phạm vi vừa đổi

Phạm vi của cả một kênh vừa đổi — dùng khi bật/tắt hàng rào phân phối, vì thao tác ấy đổi phạm vi của mọi người cùng lúc chứ không của riêng ai.

Bản rỗng dùng cho tới khi có ChatHub ở giai đoạn C. Không làm gì, không lỗi.

Bản cài đặt Facebook Messenger của . Cố ý mỏng như : chỉ giải mã token của kênh rồi chuyển tiếp sang . Mọi hiểu biết về Graph API nằm ở đó, mọi hiểu biết về hội thoại nằm ở SocialChatService. Lớp này ra đời mà lõi không đổi một dòng nào — đó chính là phép thử mà cả đợt này dựng lên để kiểm.

Hạn chờ khi hỏi hồ sơ người dùng — ngân sách CHUNG cho cả lời gọi hồ sơ lẫn đường dự phòng đọc tên qua hội thoại (sổ nợ SC-23) nối đuôi nó. Hàm này chạy trên đường webhook, và controller chỉ trả 200 sau khi xử lý xong. Hạn của Facebook là 5 giây (Messenger Platform → Webhooks, đọc 2026-10-23: "respond to all notifications with a 200 OK HTTPS response within 5 or less seconds"); hỏng thì Meta gửi lại, hỏng liên tục một giờ thì App bị gỡ đăng ký webhook khỏi Page. Mức 2 giây là của Zalo, không phải của Facebook. Đo 2026-10-23: 100/33 về sau ~300 ms, hội thoại thêm 700-765 ms — cộng lại sát mức 1,2 giây cũ, tức đường dự phòng sẽ bị cắt thường xuyên. 2,5 giây là gấp đôi số đo và vẫn chừa một nửa hạn của Meta cho phần ghi tin + đẩy SignalR. Không gọi hội thoại TRƯỚC để gọn một lời gọi, vì làm thế thì App Review có duyệt cũng không bao giờ lấy lại được ảnh đại diện. Cái giá chỉ trả khi hội thoại chưa có tên — lõi bỏ qua bước này khi đã có tên — nên thực tế mỗi khách tốn một lần ở tin đầu. Chỗ còn hở: một gói webhook gom nhiều khách MỚI cùng lúc mà Facebook lại treo thì các lượt cộng dồn; trùng tin khi Meta gửi lại đã được chặn theo mã tin.

Hạn chờ khi kéo lịch sử hội thoại. Rộng hơn hẳn hạn hỏi hồ sơ vì lời gọi này KHÔNG chạy trên đường webhook — nó chạy trong job chat-history-sync hoặc khi nhân viên bấm nút đồng bộ, nơi không có hạn 5 giây của Meta. 20 tin kèm tệp đính kèm nặng hơn một dòng tên.

Facebook cho trả lời tự do trong 24 giờ kể từ tương tác cuối của khách — bằng nửa cửa sổ của Zalo. Ngoài khung này Facebook đòi message tag (sổ nợ SC-2) và trả lỗi 10/2018278; lỗi ấy được lưu vào tin và hiện nguyên văn cho nhân viên. Đây là chỗ DUY NHẤT trong hệ thống khai con số 24 giờ: lõi lấy nó ra để tính "còn bao nhiêu giờ", giao diện chỉ diễn đạt lại. Không có một số 24 nào viết cứng ở frontend.

Trả false, dù Facebook CÓ webhook message_reads. Không phải vì nền tảng thiếu tín hiệu, mà vì tín hiệu ấy chưa đi hết được đường ống: Facebook báo "đã xem" bằng một MỐC THỜI GIAN (read.watermark — mọi tin gửi trước mốc này đã được xem), trong khi hợp đồng chuẩn hoá của lõi (DeliveryStatusUpdate) mang đúng một mã tin cho một lần cập nhật. Diễn đạt được mốc thời gian là phải mở rộng lõi, mà giai đoạn E cố ý không sửa lõi — nên FacebookWebhookParser bỏ qua sự kiện đó, và ở đây phải nói thật rằng mức "đã xem" sẽ không bao giờ tới. Đây đúng nguyên tắc §6.9: giao diện không được hứa hẹn một dấu hiệu chết, vì nhân viên sẽ diễn giải nó thành "khách chưa đọc" rồi ngồi chờ. Mở lại là việc của sổ nợ SC-3 — và khi làm thì phải đo trên lưu lượng Facebook THẬT trước, đúng bài học SC-8 của Zalo: một sự kiện có trong tài liệu không có nghĩa là nền tảng thật sự gửi nó.

Send API nhận reply_to.mid ở cấp gốc thân request, và tài liệu nói rõ trích dẫn được cả tin của khách lẫn tin của Page. Messenger không có khái niệm khách ẩn danh nên câu trả lời không phụ thuộc người nhận.

Mảng rỗng — Facebook không giới hạn. Tài liệu Sender Actions nhận thẳng ký tự emoji ở payload.reaction chứ không phải một tập mã như Zalo, nên giao diện được phép cho chọn biểu tượng bất kỳ.

Thả hoặc gỡ biểu tượng cảm xúc qua sender_action của chính Send API. 🔴 Chưa đo bằng lưu lượng thật. Bằng chứng đến từ trang hướng dẫn Sender Actions (đọc 2026-08-28, xác minh trên hai đường dẫn tài liệu độc lập), không phải từ một lần gọi thật. Và câu hỏi "Page tự thả thì có webhook về không" thì tài liệu im lặng — nghĩa là sau khi gọi thành công, LADA vẫn phải tự ghi nhớ cảm xúc mình vừa thả chứ không chờ nền tảng xác nhận. Đúng hình dạng bẫy SC-25 đã cắn một lần.

Gửi ảnh, và nếu có chú thích thì gửi tiếp một tin văn bản riêng. Lý do phải tách làm hai: một tin Messenger mang hoặc text hoặc attachment, không mang cả hai — khác Zalo, nơi chú thích đi kèm ngay trong tin ảnh. Khung chat của LADA lưu chú thích vào nội dung tin, nên bỏ qua nó là nhân viên tưởng khách đã đọc một câu chưa bao giờ được gửi đi. Ảnh gửi trước để mã tin trả về là mã của ảnh — đó là tin mang phần nội dung chính, và trạng thái giao nhận bám theo nó. Chú thích gửi hụt thì cả tin bị đánh Failed kèm lý do: thà nhân viên gửi lại còn hơn tưởng khách đã đọc.

Bật vì có một loại tin mà webhook không chở tới: tin Page trả lời riêng từ bình luận (private reply) đi ra TRƯỚC khi khách mở Messenger, và Facebook không cam kết bắn message_echoes cho nó. Khách trả lời bằng số điện thoại thì khung chat LADA chỉ có con số, mất câu hỏi đứng trước — trong khi hộp thư Meta Business Suite có đủ.

Giải mã Page access token của kênh, hoặc trả về lý do đọc tiếng Việt nếu không dùng được. Không bao giờ đưa giá trị token vào thông điệp lỗi hay nhật ký. Khác Zalo ở một điểm: Page access token lấy từ user token dài hạn không có hạn dùng, nên TokenExpiredAt của kênh Facebook thường là rỗng và nhánh kiểm hạn dưới đây không chạy. Vẫn giữ nhánh đó vì token vẫn có thể bị thu hồi (đổi mật khẩu, gỡ ứng dụng, đổi quyền Page) — lúc đó Facebook trả lỗi 190 và nhân viên đọc được lý do thật.

Kết quả một lần gửi tin ra nền tảng.

Nền tảng đã nhận tin hay chưa

Định danh tin nhắn nền tảng trả về, dùng để đối chiếu trạng thái giao nhận sau này

Mô tả lỗi khi gửi thất bại — hiển thị cho nhân viên, không chứa token

Gửi thành công

Gửi thất bại

Hồ sơ rút gọn của một người dùng trên nền tảng, đã chuẩn hoá về dạng lõi chat hiểu được.

Tên hiển thị của khách trên nền tảng

Ảnh đại diện

Kết quả một lần kéo các tin gần nhất của hội thoại từ nền tảng về.

Nền tảng trả lời được hay không

Các tin nền tảng đang giữ, đã chuẩn hoá về dạng lõi hiểu — cùng kiểu với tin đi qua webhook để lõi đối chiếu được hai nguồn với nhau.

Lý do đọc được khi thất bại — hiển thị cho nhân viên, không chứa token

Lỗi tạm (mạng, quá hạn chờ, vượt hạn mức gọi): lượt sau thử lại có thể được. false với lỗi mà lượt sau vẫn y nguyên (thiếu quyền, token hỏng) — thử lại chỉ đốt hạn mức.

Kéo được

Kéo không được

Địa chỉ nhận tin trên nền tảng — thứ duy nhất tầng nền tảng cần biết về một hội thoại. Sinh ra ở giai đoạn F1 vì tin nhắn ẩn danh của Zalo: API gửi cho người ẩn danh (POST /v2.0/oa/message) đòi CẢ HAI mã anonymous_id và conversation_id, trong khi hợp đồng cũ SendTextAsync(channel, recipientId, text) chỉ mang một. Đây là chỗ thứ hai trong cả đợt mà trừu tượng của giai đoạn A không phủ được (chỗ đầu là watermark, §6.11) — và lần này thì nới, vì SC-27 dù sao cũng buộc phải viết migration nên chi phí thật nhỏ hơn hẳn. Lý do đầy đủ ở §6.12 của kế hoạch. Truyền một địa chỉ chứ KHÔNG truyền cả ChatConversation: tầng nền tảng không có việc gì với khách hàng đã gắn hay nhân viên được phân công, và nền tảng thứ ba cần một mã thứ ba thì mở rộng lớp này chứ không đổi chữ ký giao diện lần nữa.

Định danh người dùng phía nền tảng (Zalo user id / PSID / anonymous_id)

Định danh hội thoại phía nền tảng, chỉ có với nền tảng đòi hai mã. null với mọi hội thoại thường — bản cài đặt nào cần nó mà thấy null thì phải trả lỗi đọc được, đừng gửi đi một nửa địa chỉ.

Người nhận là khách ẩn danh. Bản cài đặt dùng cờ này để chọn endpoint, thay vì đoán theo việc có rỗng hay không.

Lấy địa chỉ nhận tin từ một hội thoại.

Điểm mở rộng chiều GỬI TIN. Mỗi nền tảng hiện thực đúng một lớp này. Giai đoạn A chỉ định nghĩa giao diện; bản Zalo nằm ở giai đoạn B, bản Facebook ở giai đoạn E.

Nền tảng mà lớp này phụ trách

Khoảng thời gian kể từ tin nhắn cuối của khách mà nền tảng còn cho phép trả lời tự do (Zalo 48 giờ, Facebook 24 giờ). Đây là luật riêng của từng nền tảng nên nó nằm ở đây chứ không nằm trong lõi. Lõi chỉ lấy con số này để tính ra "còn bao nhiêu giờ" cho giao diện cảnh báo — và đó là CẢNH BÁO, không phải chốt chặn: quyết định cuối cùng thuộc về nền tảng, hết cửa sổ thì nó trả lỗi và lỗi ấy được lưu vào tin.

Nền tảng có báo về việc khách đã XEM tin hay không. Đây là câu trả lời cho một câu hỏi đã đo được chứ không phải một giả định: giai đoạn C đếm 53 request thật qua tunnel và không có sự kiện user_seen_message nào của Zalo (sự kiện duy nhất thuộc loại đó đến từ IPv6 dân dụng — chính là bản mô phỏng của giai đoạn B). Với nền tảng trả false, thang giao nhận dừng ở Delivered và giao diện KHÔNG được hứa hẹn một mức "đã xem" không bao giờ tới. Lưu ý cho ai kiểm lại: phân biệt sự kiện thật với sự kiện tự dựng bằng X-Forwarded-For, KHÔNG bằng User-Agent — chuỗi đó do bên gửi tự khai nên bản mô phỏng cũng mang đúng ZaloWebhook.

Nền tảng có nhận tham số trích dẫn khi gửi tin văn bản hay không. Cùng khuôn với và cùng lý do: giao diện phải biết được điều này để ẩn nút "Trả lời" ở nơi bấm vào cũng không gửi được, thay vì để nhân viên soạn xong một câu trả lời rồi mới nhận lỗi. Không có cờ này thì phía trình duyệt buộc phải viết if (platform === …) — đúng thứ mà ghi chú đầu SocialChatService cấm, vì nó rải kiến thức riêng của nền tảng ra khắp nơi. Đây là câu trả lời cho một câu hỏi đã tra tài liệu chứ không phải giả định (sổ nợ SC-33, tra ngày 2026-08-28): Zalo có message.quote_message_id ở tin tư vấn v3.0, Facebook có reply_to.mid ở Send API. Riêng luồng ẩn danh của Zalo thì KHÔNG — tài liệu endpoint v2.0 không có trường nào cho trích dẫn. Vì thế đây là một hàm nhận người nhận chứ không phải một thuộc tính: câu trả lời khác nhau giữa hai hội thoại của cùng một nền tảng. Để nó là thuộc tính thì cái điều kiện "trừ khách ẩn danh" sẽ phải nằm ở tầng dựng DTO — tức là kiến thức riêng của Zalo leo vào lõi, đúng thứ §6.12 đã cẩn thận đẩy xuống đây bằng .

Nền tảng có cho phép LADA thả biểu tượng cảm xúc lên tin nhắn của người nhận này hay không. Cũng là hàm chứ không phải thuộc tính, cùng lý do với . Tách hẳn khỏi việc nền tảng có báo về cảm xúc khách thả — hai chiều độc lập nhau, và chiều nhận đi bằng webhook nên không có cờ ở đây.

Bộ biểu tượng cảm xúc mà nền tảng chấp nhận, theo đúng thứ tự hiển thị. Mảng rỗng nghĩa là nền tảng không giới hạn — giao diện được phép cho chọn biểu tượng bất kỳ. Hai nền tảng khác nhau thật ở điểm này nên không gộp được: Zalo chỉ nhận sáu mã cố định và trả lỗi với mọi thứ ngoài bảng, còn Facebook nhận emoji tuỳ ý. Danh sách đi từ máy chủ ra giao diện chứ không để phía trình duyệt tự chép — hai bảng song song là hai bảng sẽ lệch, và cái lệch chỉ lộ ra khi nền tảng từ chối một biểu tượng đã bấm được.

Gửi tin nhắn văn bản. là mã tin gốc phía nền tảng mà tin này trả lời trích dẫn, null với tin thường. Lõi đã tra mã này từ database theo cặp (hội thoại, tin) nên tầng nền tảng cứ dùng thẳng. Bản cài đặt của nền tảng không hỗ trợ trích dẫn phải trả lỗi chứ không được âm thầm bỏ tham số: nhân viên sẽ tưởng khách nhìn thấy ngữ cảnh mà thật ra không.

Thả hoặc gỡ một biểu tượng cảm xúc lên một tin nhắn đã có. là mã tin phía nền tảng; là ký tự emoji thật (bỏ qua khi bật). Lõi luôn nói chuyện bằng emoji — việc đổi sang mã riêng của nền tảng là việc của bản cài đặt, vì mã ấy mà rò lên tới lõi là nó sẽ rò tiếp ra màn hình (bẫy SC-34).

Gửi tin nhắn hình ảnh. Nhận cả hai dạng vì mỗi nền tảng đòi một kiểu: Zalo phải tải tệp lên trước (), Facebook nhận thẳng đường dẫn công khai (). Bản hiện thực dùng cái nào hợp với nền tảng của mình và trả lỗi rõ ràng nếu thiếu. là chú thích đi kèm ảnh. Bắt buộc có trong giao diện vì lõi chat lưu nó vào nội dung tin: khung chat hiện chú thích mà nền tảng không nhận được nó thì nhân viên tưởng khách đã đọc một câu chưa bao giờ được gửi đi.

Lấy tên hiển thị và ảnh đại diện của một người dùng trên nền tảng. Đây là đường PHỤ TRỢ, không phải đường nghiệp vụ: webhook của Zalo không gửi kèm tên khách nên hội thoại sinh ra từ webhook không có tên, và danh sách hội thoại sẽ là một cột trống nếu không hỏi lại nền tảng. Hỏng thì trả null chứ không ném — mất tên khách là khó chịu, mất tin nhắn mới là hỏng việc. Bản cài đặt phải TỰ đặt hạn chờ ngắn: hàm này được gọi trên đường xử lý webhook, mà Zalo đòi phản hồi trong 2 giây, quá hạn thì nó gửi lại và cuối cùng vô hiệu hoá webhook.

Nền tảng có cho kéo lại các tin gần nhất của một hội thoại hay không — để lõi bù những tin webhook không chở tới (tin Page trả lời riêng từ bình luận Facebook là ca gốc). Có cài đặt mặc định false ngay trong giao diện: đây là năng lực THÊM, chỉ nền tảng nào đã đo được API lịch sử mới bật. Zalo có API hội thoại nhưng chưa ai đo nó trên OA thật.

Kéo các tin gần nhất của hội thoại với từ nền tảng về. Chỉ ĐỌC — không gửi gì ra nền tảng. Không ném lỗi: mọi hỏng hóc đi ra bằng , kèm cờ lỗi tạm để job biết có nên thử lại.

Tìm bản gửi tin ứng với một nền tảng.

Lấy bản gửi tin của nền tảng, trả null nếu chưa nền tảng nào đăng ký

Gom mọi đã đăng ký DI thành một bảng tra theo nền tảng. Thêm nền tảng mới chỉ cần đăng ký thêm một — KHÔNG sửa lớp này.

Bản cài đặt Zalo của . Cố ý mỏng: chỉ giải mã token của kênh rồi chuyển tiếp sang . Mọi hiểu biết về giao thức Zalo nằm ở đó, mọi hiểu biết về hội thoại nằm ở SocialChatService. Thêm nền tảng mới là thêm một lớp như lớp này — không sửa lõi, không sửa resolver.

Hạn chờ khi hỏi hồ sơ người dùng. Ngắn hơn hẳn 2 giây Zalo cho phép webhook phản hồi, để phần còn lại của việc xử lý tin vẫn kịp.

Zalo cho trả lời tự do trong 48 giờ kể từ tương tác cuối của khách. Ngoài khung này tin trừ vào hạn mức của gói OA (LADA đang dùng gói Nâng cao, 2.000 tin/tháng) và Zalo trả mã lỗi -232 khi không còn gửi được.

Zalo KHÔNG báo khách đã xem tin. Sự kiện user_seen_message có trong tài liệu và đã được bật trên cổng, nhưng đo thật ở giai đoạn C thì trong 53 request qua tunnel không có lấy một sự kiện nào của Zalo thuộc loại đó — cái duy nhất thấy được là bản mô phỏng do chính giai đoạn B gửi (nhận ra bằng X-Forwarded-For, không phải bằng User-Agent). Vì thế thang trạng thái của kênh Zalo dừng ở "Đã nhận". Trả false ở đây là để giao diện nói thẳng điều đó với nhân viên, thay vì để họ chờ một dấu hiệu chết. Nếu về sau Zalo bật lại sự kiện này thì chỉ cần đổi đúng dòng dưới — đường xử lý user_seen_message phía sau vẫn còn nguyên và đã được kiểm chứng chạy đúng.

Zalo nhận trích dẫn ở tin tư vấn thường (message.quote_message_id, tài liệu "Gửi tin tư vấn trích dẫn" đọc 2026-08-28) nhưng không ở luồng ẩn danh: endpoint v2.0 dành cho khách widget web không có trường nào cho việc này. Trả false cho khách ẩn danh để giao diện ẩn hẳn nút, thay vì để nhân viên soạn xong rồi mới nhận lỗi.

Cùng ranh giới với : API thả cảm xúc nhận recipient.user_id, mà khách ẩn danh không có mã ấy — họ chỉ có cặp (anonymous_id, conversation_id).

Giải mã access token của kênh, hoặc trả về lý do đọc tiếng Việt nếu không dùng được. Không bao giờ đưa giá trị token vào thông điệp lỗi hay nhật ký.

Chỗ DUY NHẤT trong phân hệ biết nền tảng nào ứng với trường liên hệ nào trên hồ sơ khách hàng. Hồ sơ khách hàng có sẵn hai cột văn bản tự do ZaloContact và FacebookContact từ trước đợt này, nên gắn hội thoại không cần thêm cột nào. Nhưng "Zalo thì ghi vào ZaloContact" là kiến thức về nền tảng, mà lõi chat cố ý không được biết điều đó — nên nó nằm ở đây, tách hẳn ra, thay vì thành một switch giữa SocialChatService. Thêm nền tảng mới thì thêm một nhánh ở đây; lõi không đổi một dòng nào.

Độ dài tối đa của hai cột liên hệ trên hồ sơ khách hàng

Giá trị hiện có của trường liên hệ ứng với nền tảng

Ghi thêm một dấu vết liên hệ vào hồ sơ khách hàng, KHÔNG đè thứ đang có. Cột này là văn bản tự do do người dùng nhập từ nhiều năm nay — đè lên là xoá dữ liệu của người khác. Đã có định danh nền tảng trong đó rồi thì không ghi lần hai.

true khi có thay đổi thật sự cần lưu

Tiêu chí chat.availability — tỉ lệ phần trăm thời gian giờ làm riêng của từng sale ở trạng thái sẵn sàng.

Nguồn duy nhất là ChatAgentPresenceLog, đúng như §3.2 đã ghi: *"không có bảng này thì tiêu chí đó là số bịa"*. Đo bằng phút giờ làm (WorkingMinutesBetween) ở cả tử số lẫn mẫu số — khác hẳn chat.first-response, và có lý do: ở đây câu hỏi là *"trong khoảng thời gian đáng lẽ bạn phải trực, bạn trực bao nhiêu"*, nên đơn vị bắt buộc phải là giờ làm. Ngoài giờ làm mà bật "Bận" thì không ai quan tâm. "Giờ làm" ở đây là giờ RIÊNG người đó tự đặt (KC-18), không phải cấu hình chung. Chủ dự án chốt ở §8.7 câu 1: mỗi người chỉ có một định nghĩa "đang trong ca", và nó vừa quyết định "Ngoài giờ", vừa dừng đồng hồ hạn phản hồi, vừa là mẫu số của tiêu chí này. Mẫu số theo cấu hình chung là thứ gây ra §7.9: production đặt 00:00–23:59 cả tuần để "nhận khách theo trạng thái" (§8.6), nên sale đặt "Nghỉ" từ tối tới sáng — đúng điều bài giảng muốn dạy — bị chấm như vắng mặt 15 giờ mỗi ngày và tỉ lệ rơi về khoảng 35–40 %. Chấm trên giờ của chính họ thì Nghỉ ngoài ca không trừ phút nào. Vì vậy lớp này không đọc — trường đó vẫn giữ cấu hình chung cho chat.first-response (điều cấm "không đổi bốn tiêu chí còn lại"). Người CHƯA đặt giờ làm thì chưa có mẫu () — kể cả khi họ có nhật ký trạng thái. Đây là lựa chọn "Bỏ tiêu chí 5" của chủ dự án ở §8.7 câu 2, và nó là lựa chọn duy nhất không bịa số: người chưa đặt mặc định "luôn trong ca" (), lấy đó làm mẫu số là quay lại đúng mẫu số 24 giờ của §7.9; lấy cấu hình chung làm mẫu số thì là chấm người ta trên một giờ làm họ chưa từng chọn — mà §8.7 câu 5 đã hạ cấu hình chung xuống thành "giờ gợi ý". Không mẫu thì ChatQualityRules.Gop loại tiêu chí khỏi cả tử lẫn tổng trọng số, nên điểm của người đó không bị kéo xuống. Giờ riêng hỏng cũng tính như chưa đặt (): chấm trên một giờ làm mà chính dữ liệu của nó đã sai là chấm trên cát. Giới hạn biết trước (plan phiên 4): giờ riêng không có lịch sử, nên cả cửa sổ 30 ngày được chấm bằng giờ hiện tại của người đó — cùng giới hạn cấu hình chung đã có từ trước. Bảng rỗng KHÔNG phải là 100 % sẵn sàng. Đây là quyết định đáng ghi vì cái sai ngược lại rất dễ viết ra: nhật ký chỉ sinh dòng khi ai đó đổi trạng thái, nên "không có dòng nào" đọc được theo hai nghĩa — sẵn sàng suốt, hoặc chưa ai từng dùng menu. Số đo C0-3 đã phân xử: chủ dự án trả lời *"Chưa ai — chưa có gì buộc họ"*, và F0-3 đo được bảng 0 dòng. Nên không có dòng = không đo được (Sample = 0), chứ không phải 100 điểm. Cho 100 điểm vì thiếu dữ liệu là thưởng người không dùng hệ thống, và nó sẽ nâng điểm tổng của mọi sale bằng một tiêu chí không quan sát gì cả. Cỡ mẫu là số ngày có ít nhất một dòng nhật ký, không phải số dòng: một người bấm đổi trạng thái 20 lần trong một buổi không có nhiều dữ liệu hơn người bấm 2 lần trong 10 ngày.

Một khoảng trạng thái hết hiệu lực ở mốc sớm hơn giữa "lúc đóng dòng nhật ký" và "lúc hết hạn tự khai"; không có mốc nào thì kéo tới hết cửa sổ.

Tách thành hàm riêng để nó kiểm được bằng một bảng ca thuần, và để định nghĩa này nằm ở một chỗ — nó phải khớp với ChatPresenceDurations.Build của giai đoạn C, vốn dựng bảng thời lượng mà quản lý đọc trên /trang-thai-sale. Hai phép cắt lệch nhau là hai con số khác nhau cho cùng câu hỏi "người này bận bao lâu".

Tiêu chí chat.conversion — tỉ lệ phần trăm hội thoại phát sinh đơn hàng trong 14 ngày.

Đường nối chat → đơn hàng CÓ tồn tại, và F-0 đã kiểm trước khi viết dòng code đầu tiên đúng như prompt dặn: ChatConversation.CustomerId → Order.CustomerId, cộng Order.CreatedTime để kẹp cửa sổ 14 ngày. Không phải suy đoán — đã chạy thật trên dev. Nhưng cỡ mẫu gần như bằng không, và lý do nằm ở một số đo cũ. Chỉ 2/63 hội thoại trên dev có CustomerId (số đo Đ2: 3,17 %), cả hai trỏ về cùng một khách, và cả hai ra 0 đơn trong cửa sổ 14 ngày — dù khách ấy có 24 đơn, chúng nằm ngoài cửa sổ. Nên tiêu chí này là tiêu chí rỗng thứ tư trên năm, ngoài ba cái prompt đã cảnh báo. Chỉ hội thoại ĐÃ GẮN KHÁCH mới vào mẫu. Hội thoại chưa gắn khách không phải "không chốt được đơn" — nó là "không biết có chốt hay không", và hai thứ đó khác nhau. Đưa chúng vào mẫu với giá trị 0 là chấm điểm kém cho một sale vì hệ thống không quan sát được họ. Đây cũng là lý do câu gợi ý của tiêu chí nói thẳng *"gắn khách hàng vào hội thoại ngay khi biết họ là ai"* — tỉ lệ gắn khách 3,17 % tự nó là chỉ số §2.4 đã hẹn đưa vào báo cáo quản lý giai đoạn G.

Cửa sổ tính chuyển đổi kể từ lúc nhận hội thoại — 14 ngày, theo §3.6

Tiêu chí chat.first-response — trung vị thời gian phản hồi lần đầu, tính bằng phút.

Đo đúng cách (c) của số đo Đ5 (§2.4), từng chi tiết một, và điều đó là bắt buộc chứ không phải tuỳ chọn: ngưỡng Good = 2 / Bad = 35 phút được suy ra từ chính phép đo ấy (trung vị 0,82′ và p90 35,40′ trên N = 206). Đo bằng một cách khác rồi áp ngưỡng của cách này là lỗi đắt nhất của giai đoạn E lặp lại — ở đó luật chấm từ LastInboundAt (tin cuối) trong khi ngưỡng suy từ tin mở đầu một lượt chờ, và *"con số ấy không còn nghĩa gì"*. Ba chi tiết của cách (c), và cả ba đều có mặt trong code dưới: Chỉ tin inbound MỞ ĐẦU một lượt chờ — tin liền trước nó không phải tin đến. Trong cách (a), một khách gửi 5 tin liên tiếp thì tin thứ 5 chỉ cách câu trả lời vài giây còn tin thứ 1 gánh cả cụm, làm lệch cả hai đầu phân bố. Chỉ tin đến trong giờ làm — đúng tinh thần *"tin nhắn 2h sáng không được làm hỏng điểm của ai"*. Lọc theo giờ đến của tin khách, không lọc theo giờ trả lời. Đo bằng đồng hồ thường, không bằng phút giờ làm. Đây là chỗ tiêu chí này cố ý khác hạn phản hồi của giai đoạn E, nên phải nói rõ kẻo người sau tưởng là quên: giai đoạn E đếm phút giờ làm vì nó thu hồi hội thoại, còn ở đây mọi con số phải so được với Đ5 — mà Đ5 lấy hiệu hai mốc đồng hồ thường rồi mới lọc theo giờ tin đến. Đổi đơn vị đo là làm ngưỡng 2/35 mất căn cứ. Ghi thành nợ PP-32: lượt đo lại sau 2 tuần chạy thật (§2.4 đã hẹn) nên đo cả hai cách rồi chốt một. Và một lọc mà Đ5 không có: chỉ tin trả lời quy được về người. Tin outbound không mang SenderStaffId là tin admin gõ thẳng trên ứng dụng Zalo OA / Facebook Page ngoài LADA — số đo E0-5 và F0-1 đều đo được 91,9 % tin chiều ra thuộc loại đó. Không quy được về ai thì không tính cho ai (sổ nợ PP-13). Hệ quả đã đo và phải nói ra: trên dev, hai người duy nhất có tin quy được về mình (#251, #1) không giao một phần tử nào với danh sách sale phụ trách kênh (#252…#255), nên cỡ mẫu thật của tiêu chí này hiện là 0 cho mọi sale — và đó chính là lý do Sample phải đi kèm mọi con số.

Trần khoảng cách inbound → outbound, tính bằng phút. 24 giờ, theo đúng chỉ dẫn của §2.4.

Không phải để làm đẹp số: dev có bản ghi ChatMessage đề ngày 2025-08-26 trong khi hội thoại sớm nhất là 2026-08-26 — sớm hơn đúng một năm. Nó đã làm hỏng max của Đ5 (525.808 phút ≈ 365 ngày) và đã kéo lùi đồng hồ của bản phát lại ở giai đoạn D. Đây là rác dữ liệu, không phải hành vi; một bản ghi như thế lọt vào dãy là đủ để đẩy trung vị của một sale ít mẫu sang phía sai.

Duyệt một hội thoại theo thứ tự thời gian và gom khoảng cách của từng lượt chờ.

Một hội thoại sinh ra nhiều quan sát, không phải một: khách hỏi buổi sáng được trả lời, chiều hỏi tiếp lại được trả lời — đó là hai lượt chờ và cả hai đều nói lên chất lượng. Chỉ lấy lượt đầu tiên là vứt bỏ phần lớn dữ liệu của đúng những hội thoại dài nhất.

Bốn cột duy nhất phép đo cần — không kéo cả Content của hàng chục nghìn tin.

Đọc điểm chất lượng cho giao diện — trang /diem-chat-cua-toi và bảng điểm đội.

Điểm của chính người đang đăng nhập. Không đòi quyền gì — xem điểm của mình thì ai cũng xem được (chốt CH-8).

Người đang đăng nhập Mốc "hôm nay" để chặn dòng điểm mang ngày TƯƠNG LAI (sổ nợ PP-41). Truyền từ ngoài vào chứ không đọc đồng hồ trong thân hàm — cùng khuôn với IChatQualityRecomputeService.RecomputeAsync, và là điều kiện để có ca test.

Điểm của những người mà được xem — đòi quyền ChatQuality.ViewTeam ở tầng controller, và thu hẹp phạm vi ở tầng này.

Điểm từng tiêu chí của lần chốt gần nhất — không tính lần chốt mang ngày tương lai.

Chặn trên là bản vá PP-41. Không có nó thì một dòng ChatQualityScore mang ngày mai thắng phép sắp xếp và bảng điểm từng tiêu chí đọc theo lần chốt chưa từng xảy ra. Trên dev nguyên nhân là rác của ChatQualitySqlTests (đồng hồ dựng sẵn); trên production thì cần một máy lệch giờ hoặc một lượt chèn tay — xác suất thấp, nhưng chốt chặn rẻ đúng một điều kiện, và bước 8 bật Chat.Quality.AffectsDistribution là lúc bảng điểm bắt đầu chia việc, không còn chỉ để xem. Mốc chặn là nửa đêm của hôm nay, đúng biểu thức mà lượt tính dùng khi GHI (ChatQualityRecomputeService: new DateTimeOffset(now.Year, now.Month, now.Day, 0, 0, 0, now.Offset)). Hai bên phải dùng chung một cách dựng mốc, nếu không dòng ghi lúc 00:00 hôm nay sẽ rơi vào hoặc ra khỏi phạm vi tuỳ theo giờ người dùng mở trang.

Thứ hạng trong nhóm người cùng phụ trách ít nhất một kênh với mình.

Nhóm so sánh là đồng nghiệp cùng hộp thư, không phải toàn công ty: xếp một sale của kênh Zalo cạnh một sale của kênh Facebook là so hai khối lượng việc khác nhau. Chỉ trả về THỨ HẠNG, không trả điểm của ai khác — chốt CH-9. Người tạm tính không vào bảng xếp hạng: điểm của họ là điểm mặc định, và xếp một điểm mặc định cạnh những điểm đã đo là dựng ra một thứ hạng không có nghĩa.

Diện người mà được xem điểm.

Kết quả một lượt tính lại điểm — để job ghi log và để test đọc.

Số sale đã chấm

Số dòng ChatQualityScore đã ghi

Số sale ra kết quả tạm tính

Số tiêu chí đang bật

Mã những tiêu chí bị loại khỏi lượt này vì nguồn dữ liệu lỗi — rỗng là lượt sạch.

Có mặt vì khối catch quanh mỗi provider là đúng nhưng nguy hiểm nếu im lặng: một nguồn hỏng rút hẳn một tiêu chí khỏi điểm của MỌI sale, mà lượt tính vẫn kết thúc "thành công" và Hangfire vẫn xanh. Với chat.first-response (trọng số 25) thì đó là một phần tư điểm biến mất mà không ai được báo.

Đầu cửa sổ trượt

Cuối cửa sổ trượt

Tính lại điểm chất lượng chat cho toàn bộ sale đang phụ trách kênh (giai đoạn F).

Chạy một lượt tính lại trên cửa sổ trượt kết thúc tại .

Lượt tính này KHÔNG chạm đường phân phối. Nó chỉ ghi hai bảng điểm; việc điểm có được dùng hay không nằm ở công tắc Chat.Quality.AffectsDistribution mà máy phân phối đọc. Tách như thế có chủ ý: điểm phải được tính và quan sát được trước khi nó có hiệu lực, nếu không thì không có cách nào đối chiếu trước lúc bật — đúng bài học của bước 5 trong trình tự lên production.

Cửa sổ trượt — 30 ngày, theo §3.6

Gọi từng provider một lần cho cả lô và gom kết quả theo mã tiêu chí.

Provider hỏng không được làm hỏng cả lượt tính: một nguồn dữ liệu lỗi thì tiêu chí ấy thành "không chấm được" (cỡ mẫu 0) và bị loại khỏi điểm tổng, còn bốn tiêu chí kia vẫn ra điểm. Nuốt-và-ghi-log ở đây là đúng vì hậu quả của việc ném lên là mọi sale mất điểm vì một bảng lỗi — cùng lý lẽ với khối catch quanh máy phân phối trên đường tin đến.

Ghi đè điểm của đúng ngày chốt ấy — job chạy lại trong ngày không cộng thêm dòng.

Một dòng tổng mỗi người — ghi đè, không thêm dòng.

Tiêu chí chat.reclaim-rate — tỉ lệ phần trăm lượt phân công kết thúc vì lỗi của người giữ.

Ba lý do vào tử số, và ranh giới của chúng là một quyết định nghiệp vụ chứ không phải một danh sách tiện tay — xem . Tiêu chí duy nhất trong năm có mẫu thật trên dev theo số đo F0-6: 10 dòng ChatConversationAssignment, ReleaseReason trải trên 4 giá trị. Vẫn là tài khoản thử, nhưng ít nhất phép tính chạy qua dữ liệu chứ không chạy qua một bảng rỗng.

Ba lý do nhả tính là "bị thu hồi" — và ba lý do không tính, quan trọng ngang nhau.

Tính: (máy thu hồi vì để khách chờ quá hạn), (khách đòi đổi người), (quản lý chuyển đi vì chăm sóc kém). Đây đúng là ba lý do mà §6.2 đã tách riêng ra: hai trong ba cái đặt KeepReadAccess = false, tức chính hệ thống đã coi chúng là lỗi của người giữ. Không tính: — và đây là chỗ dễ làm sai nhất. Tính cả tự nhả là phạt đúng hành vi mình muốn khuyến khích: sale biết mình không kịp chăm mà chủ động trả hội thoại về hàng chờ đang làm điều tốt cho khách. Phạt nó là dạy họ ôm hội thoại tới lúc bị máy thu hồi — tệ hơn cho khách, và vẫn tính vào tiêu chí này qua ngả QuaHanPhanHoi. Câu gợi ý của tiêu chí nói thẳng điều đó với người dùng. Cũng không tính: , , , , — đều là việc của tổ chức hoặc của luật CRM §3.4, không phải chất lượng chăm sóc.

Tiêu chí chat.sla-breach-rate — tỉ lệ phần trăm hội thoại từng vi phạm hạn phản hồi.

Mẫu là lượt phân công (ChatConversationAssignment) chứ không phải hội thoại: một hội thoại đổi tay ba lần là ba phần việc của ba người, và tính nó một lần là bỏ sót hai. Một xấp xỉ đã biết, ghi ra thay vì giấu. SlaBreachCount nằm trên ChatConversation, tức nó là tổng của mọi người từng giữ hội thoại ấy — không có cột nào ghi "lượt vi phạm này thuộc về ai". Nên một sale vừa nhận một hội thoại đã có sẵn 2 lần vi phạm dưới tay người trước sẽ bị tính là "có vi phạm". Sai số này nghiêng về phía khắt khe, và nó chỉ chạm những hội thoại đã đổi tay sau khi quá hạn — mà đó đúng là diện giai đoạn E thu hồi. Đóng được bằng một cột StaffId trên một bảng nhật ký vi phạm riêng; ghi thành nợ PP-33 thay vì dựng thêm một bảng cho một tiêu chí đang có 0 mẫu (số đo F0-5: SlaBreachCount 63/63 = 0, và nó chỉ tăng khi Chat.Sla.Enabled bật thật).

Cửa sổ thời gian mà một tiêu chí được tính trên đó, kèm cửa sổ giờ làm để lọc.

Đầu cửa sổ trượt (bao gồm)

Cuối cửa sổ trượt (không bao gồm)

Giờ làm việc chung (Chat.WorkingHours.*) — nay chỉ tiêu chí trả lời đầu tiên (chat.first-response) dùng để lọc theo cách đo (c) của Đ5.

Từ KC-18 cấu hình chung không còn áp cho ai (plan khoá học chat §8.7 câu 5). Tiêu chí tỉ lệ sẵn sàng (chat.availability) không đọc trường này mà đọc giờ riêng của từng người — người chưa đặt thì chưa có mẫu. Tiêu chí mới cần "giờ làm của một người" thì đọc IChatStaffWorkingHoursProvider, đừng đọc ở đây.

Một tiêu chí điểm chất lượng biết tự đi lấy số thô của mình (giai đoạn F).

Nhận cả LÔ nhân viên, không nhận một người. Đây là bài học gộp lô của giai đoạn D viết thẳng vào chữ ký: gọi bản một-người trong vòng lặp là nhân số truy vấn lên đúng bằng số sale, và với 40 sale × 5 tiêu chí thì đó là 200 lượt quét thay vì 5. Trả kèm cỡ mẫu, luôn luôn. không phải trường tuỳ chọn — xem lý do ở chính nó. Người nào không có mặt trong từ điển trả về được hiểu là .

Mã tiêu chí mà lớp này phục vụ — khớp ChatQualityCriterion.ProviderCode.

Lấy số thô của cả lô nhân viên trên một cửa sổ thời gian.

Bản đẩy realtime thật, thay cho của giai đoạn A. Chỉ đổi đăng ký DI là xong — tầng SocialChatService không biết gì về SignalR, đúng như thiết kế ban đầu. BẮT BUỘC đẩy DTO phẳng, không đẩy entity EF. Bộ tuần tự của SignalR là System.Text.Json và nó KHÔNG kế thừa ReferenceLoopHandling.Ignore mà tầng MVC cấu hình cho Newtonsoft — đẩy ChatConversation thẳng ra sẽ ném lỗi vòng tham chiếu qua navigation ChatChannel/Customer. Mọi lỗi đẩy tin đều bị nuốt sau khi ghi nhật ký: đây là đường thông báo, không phải đường dữ liệu. Redis backplane hỏng thì tin nhắn vẫn phải được lưu và webhook vẫn phải trả 200, nếu không Zalo sẽ gửi lại rồi vô hiệu hoá webhook.

Dựng DTO hội thoại cho bản đẩy — kể cả tên nhân viên đang phân công. Đường đẩy realtime PHẢI dựng DTO đầy đủ y như đường REST: phía trình duyệt thay nguyên dòng trong danh sách bằng bản vừa nhận, nên trường nào thiếu ở đây là trường đó biến mất khỏi màn hình ngay khi hội thoại có thay đổi. Đúng hình dạng lỗi đã cắn ở giai đoạn C với tên kênh và tên khách hàng.

Chế độ phân phối của kênh chứa hội thoại. null = không tra được kênh. Hai chỗ cần đúng câu trả lời này trong cùng một lượt đẩy: nhóm nào được nhận () và cổng nhãn "Quá hạn" trong DTO (PP-34). Tra một lần rồi truyền đi — hỏi hai lần là mở đường cho hai câu trả lời khác nhau về cùng một hội thoại trong cùng một lượt.

Gửi và nuốt lỗi. Xem ghi chú ở đầu lớp về lý do không được để lỗi đẩy tin nổi lên.

Luật "bản đẩy realtime của một hội thoại đi tới những nhóm nào". Đây là mặt thứ hai của hàng rào quyền xem, và là mặt dễ quên: bản đẩy ConversationUpdated mang theo LastMessage — nguyên văn tin của khách. Chặn ở 13 endpoint REST mà vẫn phát nội dung ấy vào nhóm phẳng là chặn cửa trước rồi mở cửa sau. Tách thành hàm thuần (không SignalR, không database) để kiểm được bằng test đơn giản — một luật quyết định ai đọc được tin của khách thì phải có ca test gọi thẳng vào nó.

Chế độ phân phối của kênh; null nghĩa là không tra được kênh — khi đó coi như có hàng rào (fail-closed), vì đoán nhầm chiều còn lại là phát nội dung khách ra nhóm phẳng. Kênh của hội thoại Người đang giữ hội thoại, null khi còn trong hàng chờ

Lõi chat, dùng chung cho mọi nền tảng. Lớp này KHÔNG BIẾT nó đang xử lý Zalo hay Facebook. Nếu thấy cần viết if (platform == …) ở đây thì logic đó đang nằm sai chỗ — nó thuộc về (chiều nhận) hoặc IPlatformMessenger (chiều gửi).

Tìm hội thoại theo cặp (kênh, người dùng), chưa có thì tạo mới. Hội thoại đã đóng mà khách nhắn lại thì tự mở lại.

Lưu một tin nhắn khách gửi vào và cập nhật hội thoại tương ứng. Tin đã lưu rồi (nền tảng gửi lại webhook) thì bỏ qua, không tạo bản sao.

Cập nhật trạng thái giao nhận của một tin đã gửi đi trên MỘT kênh. Chỉ tiến, không lùi. Bắt buộc truyền kênh: nếu tra tin theo mỗi định danh nền tảng thì một người ngoài chỉ cần đoán trúng định danh là đổi được trạng thái tin của kênh bất kỳ.

Nâng trạng thái giao nhận theo MỐC THỜI GIAN: mọi tin chiều ra của hội thoại (kênh, người dùng) có SentAt trước hoặc bằng mốc lên trạng thái đích (SC-25 / SC-3). Khác cập nhật đích danh ở một điểm cố ý: tin Failed KHÔNG được mốc nào cứu — tin gửi hỏng chưa bao giờ đi nên không mốc giao nhận nào xác nhận được nó. Cập nhật đích danh thì được phép (nền tảng gọi tên đúng tin đó là bằng chứng trực tiếp).

Ghi nhận một lần thả/gỡ biểu tượng cảm xúc do nền tảng báo về (SC-29). Cũng bắt buộc truyền kênh, cùng lý lẽ với : tra tin theo mỗi mã nền tảng là mở đường cho một payload đoán được mã gắn cảm xúc vào tin của kênh khác.

Nhân viên thả hoặc gỡ một biểu tượng cảm xúc lên một tin nhắn. Gọi nền tảng TRƯỚC rồi mới ghi — ngược hẳn thứ tự của , và đó là chủ ý: một tin gửi hỏng vẫn phải để lại dấu vết đọc được trong khung chat, còn một cảm xúc thả hỏng thì không có gì để lưu lại cả. Ghi trước rồi nền tảng từ chối là màn hình hiện một cảm xúc mà khách không bao giờ thấy.

Luồng xử lý webhook dùng chung cho mọi nền tảng: đọc payload, tra kênh trong DB, lưu tin hoặc cập nhật trạng thái giao nhận.

Nhân viên trả lời một hội thoại. Lưu tin trước rồi mới gọi nền tảng, để một lần gửi hỏng vẫn để lại dấu vết đọc được trong khung chat thay vì biến mất.

Danh sách hội thoại cho cột trái của khung chat, đã lọc theo phạm vi của . Kênh còn ở chế độ Shared thì không lọc gì cả — hành vi y hệt trước đợt phân phối (§6.3). Kênh đã bật hàng rào thì đi qua .

Tham số phân trang, sắp xếp, bộ lọc của client Người đang đăng nhập. Bỏ trống (0) là luồng máy chạy và chỉ thấy kênh chưa bật hàng rào — thiếu tham số phải dẫn tới thấy ÍT hơn, không bao giờ nhiều hơn.

Chi tiết một hội thoại kèm tin gần nhất. Trả null khi hội thoại không tồn tại, đã xoá mềm, hoặc nằm ngoài phạm vi của — ba trường hợp trả về giống hệt nhau, cố ý: phân biệt được chúng là nói cho người dò biết hội thoại đó có tồn tại.

Đưa số tin chưa đọc của một hội thoại về 0 và báo cho mọi màn hình đang mở

Tổng số tin chưa đọc trong phạm vi của người đang đăng nhập — badge trên thanh điều hướng. Trước đợt này hàm cộng toàn bảng, tức một nhân viên đọc được tổng khối lượng việc của cả công ty. Đường này không nhận mã hội thoại nào nên rất dễ bị bỏ sót khi rà hàng rào.

Hỏi trước xem một hội thoại có gửi tin ra được không, KHÔNG gửi gì cả. Dùng cho đường gửi ảnh: ở đó tệp phải nằm trên đĩa trước khi gọi (nền tảng cần đường dẫn tệp), nên nếu không hỏi trước thì mỗi lần hội thoại đã xoá hay kênh đang tắt sẽ để lại một tệp ảnh không ai tham chiếu trên đĩa — và không có việc nào dọn nó.

Nạp thêm tin CŨ HƠN một tin đã có trên màn hình (nút "xem thêm tin cũ"). Phân trang theo mốc chứ không theo số trang: hội thoại vẫn đang chạy, khách nhắn thêm giữa hai lần bấm là mọi số trang lệch đi một nhịp và nhân viên sẽ thấy tin lặp lại hoặc mất một khúc giữa.

Hội thoại Chỉ lấy tin có mã nhỏ hơn giá trị này; 0 nghĩa là lấy từ cuối Số tin lấy thêm; bỏ trống là 50, trần 200

Gắn hội thoại với một khách hàng trong hệ thống.

Hội thoại Khách hàng Có ghi thêm dấu vết liên hệ vào hồ sơ khách hàng không (ghi THÊM, không đè). Người thực hiện Tên người thực hiện, ghi vào cột audit

Gỡ liên kết khách hàng khỏi hội thoại (gắn nhầm người)

Phân công hội thoại cho một nhân viên, hoặc gỡ phân công khi để trống. Với kênh còn ở chế độ Shared đây vẫn CHỈ là nhãn để lọc. Với kênh đã bật hàng rào, phân công là thứ quyết định ai đọc được hội thoại — nên đường này siết hai đầu: chỉ gán được hội thoại trong phạm vi mình thấy, và chỉ gán cho người có tên trong ChatChannelStaff của chính kênh đó (§3.11).

Đổi trạng thái vòng đời của hội thoại (đang xử lý / chờ khách / đóng / mở lại).

Nhả hội thoại về hàng chờ — không giao cho ai. Lý do bắt buộc, và nó không phải một dòng ghi chú: lý do quyết định người vừa nhả còn đọc được hội thoại nữa không (§6.2). Xem .

Hội thoại Vì sao nhả — quyết định phạm vi dữ liệu của người cũ Ghi chú bắt buộc; một mã lý do trơ trọi thì tháng sau không ai đọc lại được Người thực hiện Tên người thực hiện

Chuyển hội thoại sang một nhân viên khác. Đường này không được trở thành đường đọc trộm ("chuyển về cho mình rồi đọc", §3.11). Ba lớp chặn: hội thoại phải nằm trong phạm vi ghi của người thực hiện (nên một sale chỉ chuyển được hội thoại mình đang cầm), người nhận phải nằm trong phạm vi nhân sự của người thực hiện (controller), và người nhận phải có tên trong danh sách phụ trách của chính kênh đó.

Lịch sử phân công của một hội thoại — "ai từng cầm hội thoại này, vì sao thôi cầm". Trả danh sách rỗng khi hội thoại nằm ngoài phạm vi đọc của người hỏi.

Thu hồi quyền xem của một người đã thôi giữ hội thoại.

Bịt khe hở mà chính người sắp bị cắt điều khiển được: cờ KeepReadAccess chỉ ghi lúc đóng một lượt đang mở, nên sale tự nhả trước với một lý do hành chính là lượt của họ đóng lại với cờ giữ quyền và quản lý không còn lượt nào để đóng. Đường này ghi thêm một dòng thu hồi, không sửa lịch sử cũ.

Hàng chờ: hội thoại chưa giao cho ai — màn điều phối (sổ nợ PP-14). Tồn tại vì hàng rào §3.7 có một hệ quả cố ý: hội thoại chưa giao cho ai trên kênh đã bật hàng rào thì sale thường không thấy, nên trước giai đoạn B chỉ trưởng nhóm và người xem-tất-cả biết là có việc đang chờ. Đường này cho người điều phối nhìn thấy nó.

Tham số gửi một tin đi. Cố ý KHÔNG phải model bind thẳng từ request: là đường dẫn tệp trên máy chủ, để client tự đặt giá trị cho nó là mở đường đọc tệp bất kỳ của máy chủ rồi gửi ra ngoài.

Nội dung văn bản, hoặc chú thích của ảnh

Đường dẫn tệp ảnh trên đĩa máy chủ (nền tảng nào cần tải tệp lên thì dùng)

Đường dẫn ảnh công khai (nền tảng nào nhận URL thì dùng)

Mã tin trong LADA mà tin này trả lời trích dẫn; null với tin thường. Cố ý là mã nội bộ chứ không phải mã tin của nền tảng. Nhận mã nền tảng từ client thì không có cách nào kiểm nó thuộc hội thoại nào — và một chuỗi trích dẫn tin của khách khác sẽ đi thẳng ra ngoài. Máy chủ tra mã nền tảng từ mã này theo CẶP (tin, hội thoại), đúng cách ChatQuoteResolver đã cẩn thận làm ở chiều ngược lại.

Tên ghi vào cột audit cho bản ghi do webhook tạo (không có người dùng đăng nhập)

Số tin nạp sẵn khi mở một hội thoại

Độ dài tối đa của một biểu tượng cảm xúc, tính bằng đơn vị UTF-16 — khớp đúng bề rộng cột ChatMessage.CustomerReactionEmoji / StaffReactionEmoji (migration M202608281500). Đủ cho mọi chuỗi emoji ghép quan sát được.

Trần số tin một lần gọi được phép lấy. Có trần vì tham số này đến từ client — không có nó thì một yêu cầu đủ lớn kéo cả hội thoại nghìn tin ra khỏi database.

Cửa sổ đối chiếu tin do OA gửi ra nhận lại qua webhook với tin LADA vừa gửi đi. Cần vì tin nhân viên bấm gửi trong SPA cũng làm Zalo bắn oa_send_* về. Bình thường mã tin nền tảng trả về đã đủ để nhận ra bản trùng, nhưng có một khe hẹp: giữa lúc lưu tin và lúc ghi được mã đó xuống, webhook có thể đã về. Trong khe ấy phải nhận nhau bằng nội dung, nếu không mỗi câu trả lời hiện thành hai bong bóng.

Chạy máy phân phối cho hội thoại vừa nhận tin của khách — đúng thời điểm duy nhất mà §3.3 cho phép máy chạy (giai đoạn D).

Đặt ở đây chứ không sau bản đẩy realtime: người vừa nhận hội thoại phải được vào phòng SignalR trước khi tin của khách được đẩy đi, nếu không họ nhận được hội thoại nhưng không nhận được chính tin đã sinh ra nó. Máy tự lo phần cấp phạm vi rồi đẩy cập nhật; lượt ConversationUpdatedAsync ngay sau đây là một bản đẩy trùng, và trùng là chiều an toàn — thiếu mới là chiều hỏng. Nuốt mọi lỗi. Tin của khách đã lưu xong trước khi hàm này chạy; một máy phân phối hỏng không được phép làm mất tin nhắn hay làm webhook trả lỗi cho nền tảng — Zalo sẽ gửi lại và sinh ra bản trùng. Máy hỏng thì hội thoại nằm hàng chờ, và job chat-queue-sweep hai phút sau thử lại.

Đổi "trả lời tin số mấy trong LADA" thành mã tin phía nền tảng, và chặn mọi trường hợp không trích dẫn được. Trả (null, null) khi tin này không phải câu trả lời trích dẫn. Mọi lỗi ở đây đều trả về một câu đọc được thay vì âm thầm bỏ phần trích dẫn: một câu trả lời mất ngữ cảnh trông y hệt một câu trả lời có ngữ cảnh ở phía nhân viên, nên hỏng im lặng ở đây là hỏng đúng chỗ không ai phát hiện được.

Map một trang thực thể đã phân trang sang DTO, giữ nguyên mọi con số phân trang.

Có mặt vì bối cảnh "chờ bao lâu" phải dựng từ chính các dòng của trang (KC-18): trước đó hai màn danh sách map ngay trong ToSmartTableResultAsync, lúc chưa có trang nào trong tay. Chép đủ sáu trường của chứ không riêng ba trường mà hàm phân trang đang điền — thiếu trường nào là trường đó về 0 trên giao diện mà không ai báo.

Nạp một hội thoại trong phạm vi của người đang thao tác, kèm hai navigation BẮT BUỘC cho bản đẩy realtime. Đây là cửa duy nhất mà 11 trong 13 đường dùng để lấy một hội thoại theo mã. Trả null cho cả ba trường hợp "không tồn tại" / "đã xoá mềm" / "ngoài phạm vi" — người gọi không được phép phân biệt chúng, vì phân biệt được là trả lời hộ câu hỏi "hội thoại số N có tồn tại không". Về Include: xem ghi chú ở — thiếu nó thì bản đẩy mang tên kênh / tên khách rỗng, và phía trình duyệt thay nguyên dòng bằng bản vừa nhận. là ranh giới "còn xem chỉ đọc" của §6.2. Từ giai đoạn B, phạm vi ĐỌC gồm cả hội thoại mình từng giữ (PP-10) — nhưng người từng giữ không được gửi tin cho khách của người đang giữ, không được gỡ khách hàng, không được phân công lại. Đường ghi nào cũng phải truyền true; quên một chỗ là chỗ đó nhận nguyên phạm vi đọc rộng hơn mà không ai định thế.

Hội thoại cần nạp Người đang thao tác; 0 = luồng máy chạy, chỉ thấy kênh chưa bật hàng rào true khi lời gọi sắp THAY ĐỔI hội thoại — bỏ nhánh "từng giữ" khỏi phạm vi.

Như nhưng trả kèm đối tượng phạm vi đã phân giải.

Tồn tại vì ba đường chi tiết cần chấm cờ chỉ-đọc CanWrite (sổ nợ PP-36) trên đúng hội thoại vừa nạp, và phân giải phạm vi lần thứ hai chỉ để hỏi lại là thêm một lượt đọc ChatChannelStaff + ChatConversationAssignment cho mỗi lần mở một hội thoại — mà tệ hơn thế, nó mở đường cho hai câu trả lời khác nhau về cùng một hội thoại trong cùng một request.

Chấm hai thứ mà cả ba đường đổi người đều đòi: lý do có thật, và ghi chú không rỗng.

Enum.IsDefined không phải thủ tục hình thức. Lý do đến từ client, và nó là đầu vào của — một số lạ rơi vào nhánh _ => true của hàm đó, nghĩa là người gửi một giá trị ngoài enum tự chọn cho mình kết quả "vẫn còn quyền đọc". Chặn ở đây, không phải ở giao diện. Ghi chú bắt buộc vì §3.2 nói nhật ký phải đọc được: một bảng toàn mã lý do thì tháng sau không ai dựng lại được câu chuyện "vì sao khách này đổi người ba lần".

Báo cho các màn hình đang mở sau một lần đổi người giữ hội thoại — thu hồi trước, đẩy sau.

Thứ tự ở đây là một bản vá, không phải sở thích. Giai đoạn A đẩy ConversationUpdated trước rồi mới thu hồi phòng, nên người vừa bị cắt quyền xem còn nhận đúng một bản đẩy cuối cùng — kèm nguyên văn LastMessage của khách. Một bản đẩy vẫn là một bản đẩy: chuyển hội thoại vì khách phàn nàn (KeepReadAccess = false) mà người bị chuyển vẫn đọc được tin kế tiếp thì bản vá §6.2 chưa chạy. Thu hồi trước cũng đúng ở chiều mở rộng: ScopeChangedAsync cho người mới đưa họ vào phòng ngay, nên bản đẩy ngay sau đó tới được họ mà không phải đợi tải lại trang.

Nạp một hội thoại đang ở hàng chờ theo phạm vi ĐIỀU PHỐI — cửa thứ hai của đường phân công, chỉ mở cho người quản trị phân phối.

Không có cửa này thì trang /dieu-phoi-chat vô dụng với đúng vai nó sinh ra để phục vụ: người có ChatDistribution.Manage mà không phụ trách kênh nào nhìn thấy hàng chờ ( dùng ResolveForQueueAsync) nhưng mọi nút "Giao" đều trả "không tìm thấy hội thoại". Hai hàng rào giữ cho nó không thành một lỗ: điều kiện AssignedStaffId == null khoá cửa này vào ĐÚNG hàng chờ — hội thoại đã có người giữ không đi qua đây được, nên không ai giành được việc của người khác; và ResolveForQueueAsync chỉ nới phạm vi cho quyền quản trị phân phối, người khác nhận lại đúng phạm vi thường của họ. Đường này KHÔNG mở quyền đọc: phân công xong, người điều phối vẫn không xem được nội dung hội thoại vừa giao (phạm vi đọc của họ không đổi). Điều phối là quyền định đoạt hàng chờ, không phải quyền đọc tin của khách.

Ghi hội thoại và dòng nhật ký phân công trong một giao dịch, rồi mới báo realtime.

Hai lượt ghi này không được rời nhau. Cập nhật ChatConversation xong mà ghi nhật ký hỏng thì lượt cũ của người phụ trách trước vẫn đang mở — và mức Self của hàng rào đọc chính cột đó, nên người vừa bị chuyển đi vì khách phàn nàn giữ quyền xem vĩnh viễn, không có đường nào phát hiện ra. Chiều ngược lại (nhật ký xong, hội thoại hỏng) thì lịch sử nói một chuyện mà dữ liệu nói chuyện khác. Bản đẩy realtime nằm NGOÀI giao dịch, và cố ý: gửi đi rồi rollback là báo cho mọi màn hình một sự thật chưa từng xảy ra. Thân hàm chuyển hẳn về IChatAssignmentJournal.ApplyChangeAsync ở giai đoạn C, khi đường ghi thứ ba và thứ tư vào AssignedStaffId xuất hiện (uỷ quyền tạm khi nghỉ dài, và nhả hội thoại khi gỡ người khỏi kênh — sổ nợ PP-18) từ một service khác không inject được ISocialChatService. Giữ lại tên riêng ở đây vì nó được gọi từ bốn chỗ trong lớp này và cái tên nói đúng việc nó làm. Nhật ký vẫn ghi TRƯỚC mọi bản đẩy: cờ KeepReadAccess vừa ghi xuống chính là thứ ChatVisibilityResolver đọc để chấm lại phạm vi. Đảo thứ tự là thu hồi theo một phạm vi đã lỗi thời.

Ghi cột audit cho một thao tác do nhân viên thực hiện

Ép số tin một lần nạp về khoảng cho phép — tham số này đến từ client

Điền tên nhân viên phân công cho một trang danh sách bằng ĐÚNG MỘT lượt tra.

Chuyển một mẻ tin sang DTO, kèm khối trích dẫn tra sẵn bằng MỘT lời gọi database cho cả mẻ — tra từng dòng thì mở một hội thoại 50 tin là 50 lượt truy vấn.

Tra kênh của một hội thoại và kiểm nó có gửi tin ra được không. Trả về kênh khi dùng được, hoặc lý do đọc được khi không — dùng chung cho và để hai đường không bao giờ lệch luật.

Ghi nhật ký một payload webhook bị bỏ qua, ở đúng mức ồn của nó. Đây là bản vá của sổ nợ SC-30. Trước đó mọi trường hợp bỏ qua đều ghi LogDebug, mà Logging:LogLevel:Default của repo là Information — nên sự kiện nền tảng gửi mà LADA chưa hỗ trợ biến mất không để lại dấu vết. Hộp thư "Ẩn danh" của Zalo có hội thoại đều đặn cả tháng, LADA không nhận cái nào, và không một dòng nhật ký nào cho biết điều đó đang xảy ra. Bỏ CÓ CHỦ Ý (tiếng vọng của chính mình, message_reads theo §6.11, sự kiện ngoài phạm vi v1) vẫn giữ mức Debug — chúng xảy ra liên tục, nâng mức lên là làm ngập nhật ký rồi chẳng ai đọc nữa. Chỉ nhánh CHƯA HỖ TRỢ mới lên Warning, kèm tên sự kiện.

Số ký tự thân request in kèm cảnh báo sự kiện chưa hỗ trợ. Đủ cho một payload webhook thường (vài trăm ký tự) mà không biến nhật ký thành nơi đổ dữ liệu.

Payload trỏ tới một kênh không có trong DB hoặc đang tắt. Vẫn trả 200 cho nền tảng để nó không gửi lại vô hạn, nhưng phải để lại dấu vết vì đây cũng là hình dạng của một payload giả mạo.

Gỡ một thực thể vừa chèn hụt ra khỏi ngữ cảnh đang theo dõi, để lần lưu sau không kéo nó theo. Dùng RemoveAsync vì tầng service chỉ nhìn thấy : với thực thể đang ở trạng thái Added, DbSet.Remove của EF Core chuyển nó về Detached chứ không sinh lệnh DELETE nào, nên đây đúng là "quên bản ghi đó đi". Nuốt lỗi có chủ ý: đây đã là đường xử lý sự cố, việc gỡ thất bại không được che mất nguyên nhân gốc mà đường gọi đang xử lý.

Tin chiều ra vừa nhận qua webhook có phải là tiếng vọng của một tin CHÍNH LADA vừa gửi không. Đúng thì ghi bổ sung mã tin của nền tảng vào bản ghi đã có và trả true. Đường bảo vệ thứ nhất là mã tin nền tảng (IsMessageAlreadySavedAsync). Đây là đường thứ hai, cho khe hẹp giữa lúc lưu tin và lúc ghi được mã ấy xuống: trong khe đó bản ghi của LADA chưa có mã nên đường thứ nhất không nhận ra, và nếu không có hàm này thì mỗi câu nhân viên gửi từ SPA sẽ hiện thành hai bong bóng. Chỉ nhận những bản ghi CHƯA từng gặp tiếng vọng (PlatformEchoAt == null): bản đã được một sự kiện OA-gửi khớp vào rồi mà nội dung lại trùng là một tin khác thật sự (nhân viên gõ lại đúng câu đó trong ứng dụng Zalo OA), không được nuốt. Dấu ấy KHÔNG thể thay bằng "bản ghi chưa có mã tin", dù nghe tương đương: Zalo cấp hai mã khác hệ cho cùng một tin — data.message_id trong phản hồi của API gửi tin, và message.msg_id trong webhook. Bản ghi của LADA có mã thứ nhất ngay khi gửi xong, nên nếu lấy "đã có mã" làm dấu thì mọi tiếng vọng đều bị coi là tin mới và mỗi câu nhân viên gửi hiện thành hai bong bóng — bản gốc kẹt ở "Đã gửi" vì không sự kiện giao nhận nào nhắc tới mã thứ nhất, bản sao mang nhãn "ngoài LADA" và nhận đủ "Đã nhận"/"Đã xem". Đó chính là lý do mã của webhook GHI ĐÈ mã của API bên dưới: chỉ mã webhook mới tra được, và nó cũng là mã mà Zalo đòi khi trích dẫn hay thả cảm xúc lên tin. Và cũng KHÔNG nhận bản ghi đã Failed, dù nó cũng không có mã tin: tin gửi hỏng từ SPA rồi nhân viên gõ lại đúng câu ấy trong ứng dụng Zalo OA là chuyện thường gặp. Nuốt nó thì khung chat chỉ còn một bong bóng đỏ "Thất bại" trong khi khách đã nhận được câu trả lời — sai lệch tệ hơn hẳn một bong bóng thừa.

Bổ sung tên và ảnh đại diện khi nền tảng gửi kèm mà hội thoại chưa có. Không ghi đè bằng giá trị rỗng — payload thiếu thông tin không được xoá thứ đang có.

Hỏi nền tảng tên hiển thị của khách khi hội thoại còn thiếu. Webhook của Zalo chỉ gửi định danh người gửi, không gửi tên (đo được ngày 2026-08-26), nên không có bước này thì cột tên trong danh sách hội thoại rỗng với MỌI hội thoại thật. Chỉ gọi khi đang thiếu tên: quota API hồ sơ của nền tảng có hạn, và tên khách hầu như không đổi. Lõi không biết nền tảng nào — nó hỏi qua , đúng điểm mở rộng mà Facebook ở giai đoạn E sẽ cắm vào.

Thứ hạng trên thang tiến của trạng thái giao nhận. nằm NGOÀI thang (hạng 0) nên một báo nhận thật từ nền tảng vẫn sửa được tin từng bị đánh dấu thất bại.

Cắt chuỗi cho vừa độ dài cột. Dữ liệu do bên thứ ba gửi tới nên không được tin độ dài.

Đọc webhook của Facebook Messenger (Page). Viết theo tài liệu Graph API đọc ngày 2026-08-27 tại developers.facebook.com (Messenger Platform → Webhooks, message_echoes, message_deliveries, message_reads). Toàn bộ hiểu biết riêng của Facebook dừng lại ở lớp này — lõi chat không biết Facebook là gì. Ba điểm khác Zalo phải nhớ, vì đọc nhầm là gắn hội thoại sai người: Chữ ký là HMAC-SHA256 trên thân thô với App Secret, header X-Hub-Signature-256, giá trị có tiền tố sha256= — không phải băm nối chuỗi như Zalo. Vai sender/recipient ở hai sự kiện giao nhận ngược hẳn Zalo: Facebook để người dùng ở sender và Page ở recipient cho cả delivery lẫn read; chỉ có message_echoes mới đảo vai. Có thêm bước bắt tay GET (hub.challenge) mà Zalo không có.

Tên header mang chữ ký của Facebook

Tiền tố bắt buộc của giá trị chữ ký

Giá trị hub.mode duy nhất Facebook gửi khi đăng ký webhook

Định danh ứng dụng Facebook của LADA, dùng để nhận ra tiếng vọng của chính mình. Bỏ trống thì mọi tiếng vọng đều được lưu và việc chống trùng dồn hết cho lõi.

App ID của LADA (SocialChat:Facebook:AppId). Xem để biết vì sao cần.

Kiểm chữ ký theo công thức Facebook công bố: X-Hub-Signature-256: sha256=HMAC_SHA256(rawBody, AppSecret), chữ số hex viết thường. Đây là HMAC thật, KHÔNG phải băm nối chuỗi như Zalo — đừng đem công thức bên kia sang dùng. Khoá ký là App Secret của ứng dụng Facebook, không phải Page Access Token.

Một sự kiện bị bỏ qua trong lúc đọc payload, kèm lý do và mức ồn của nó. Facebook gom nhiều sự kiện vào một request nên không thể trả kết quả ngay tại chỗ bỏ — phải nhớ lại rồi tổng hợp ở cuối. Trước bản vá SC-30 danh sách này chỉ là chuỗi lý do, nên "bỏ có chủ ý" và "chưa hỗ trợ" trộn làm một và cùng chìm ở mức Debug.

Một sự kiện bị bỏ qua trong lúc đọc payload, kèm lý do và mức ồn của nó. Facebook gom nhiều sự kiện vào một request nên không thể trả kết quả ngay tại chỗ bỏ — phải nhớ lại rồi tổng hợp ở cuối. Trước bản vá SC-30 danh sách này chỉ là chuỗi lý do, nên "bỏ có chủ ý" và "chưa hỗ trợ" trộn làm một và cùng chìm ở mức Debug.

Bỏ vì đã quyết định như vậy — nhật ký mức Debug

Bỏ vì chưa hỗ trợ hoặc payload lạ — nhật ký mức Warning

Gộp danh sách bỏ qua thành một kết quả. Chỉ cần một sự kiện chưa hỗ trợ trong cả request là kết quả lên mức Warning — thà ồn một lần còn hơn để nó lẫn vào giữa những sự kiện bỏ có chủ ý rồi không ai thấy.

Kiểm bước bắt tay GET mà Facebook gọi đúng một lần lúc khai báo webhook trên cổng: GET ?hub.mode=subscribe&hub.verify_token=…&hub.challenge=…. Khớp thì phải trả về nguyên văn hub.challenge kèm HTTP 200, không khớp thì 403. Zalo không có bước này. So sánh hằng thời gian vì verify token là một bí mật dùng lại nhiều lần — Facebook gọi lại bước này mỗi lần đổi URL webhook.

Đọc một sự kiện thả/gỡ biểu tượng cảm xúc (field message_reactions, SC-29). Vai sender/recipient giống hệt nhóm giao nhận: khách ở sender, Page ở recipient — ngược với Zalo, nơi OA nằm ở sender của sự kiện tương ứng. Ưu tiên trường emoji hơn trường reaction: Messenger cho người dùng đổi bộ biểu tượng, và khi họ thả một biểu tượng ngoài bộ mặc định thì reaction chỉ còn là chuỗi "other" trong khi emoji vẫn mang đúng ký tự. Đọc theo reaction là dồn hết những lần thả ấy vào một nhánh sai. 🔴 Hai điều chưa đo. (a) Field này CHƯA bật trên cổng App — đo GET /{app-id}/subscriptions ngày 2026-08-27 chỉ thấy 3 field, nên tới giờ chưa một sự kiện thật nào đi qua nhánh này; phải bật ở CẢ HAI tầng (subscription cấp App và subscribed_apps của từng Page) rồi mới có lưu lượng. (b) Tài liệu chỉ mô tả chiều "khách thả cảm xúc lên tin của Page"; khách thả lên tin của chính khách thì tài liệu im lặng — nhánh dưới xử lý được cả hai vì nó tra tin theo mã, nhưng đừng coi đó là bằng chứng nền tảng có gửi.

Mã tin gốc của một tin trả lời trích dẫn: Facebook để ở message.reply_to.mid, và cũng chỉ gửi MÃ, không gửi nội dung — cùng hình dạng với quote_msg_id của Zalo, nên một trường chuẩn hoá phủ được cả hai (SC-27). Payload còn có reply_to.is_self_reply (khách trả lời chính tin của mình). Chưa đọc: chiều của tin gốc đã suy ra được từ bản ghi trong DB, thêm một trường nữa chỉ để nói lại điều đó là thừa.

Ghi nhận một entry không mang mảng messaging, gọi đúng tên thứ nó mang. changes là field trang (feed/mention…) — ngoài phạm vi chat, bỏ có chủ ý; standby là hội thoại đang do ứng dụng khác cầm lái, LADA chưa hỗ trợ bàn giao.

Khách nhắn vào Page: sender là người dùng (PSID), recipient là Page.

Tiếng vọng của tin do Page gửi ra (message_echoes). Vai ĐẢO so với tin khách gửi: sender là Page, recipient là người dùng. Facebook cho một thứ mà Zalo không có: trường app_id nói rõ tin đi ra từ ứng dụng nào. Tiếng vọng của chính LADA bị bỏ ngay tại đây, vì tin ấy đã nằm trong database từ lúc bấm gửi — giữ lại chỉ để lõi phải đối chiếu lại lần nữa, và đường đối chiếu theo nội dung có một khe hẹp không đóng được (chú thích ảnh của LADA đi thành một tin văn bản riêng, mang mã tin khác mã đã lưu, nên nó sẽ hiện thành bong bóng thứ hai). Tiếng vọng của ứng dụng KHÁC thì giữ — đó chính là câu trả lời nhân viên gõ trong hộp thư của Page (tài liệu ghi rõ: từ Graph API v12.0, tin gửi từ Page inbox mang app_id = 26390203743090). Không lưu chúng thì khung chat thiếu hẳn một nửa cuộc trò chuyện — đúng lý do sổ nợ SC-8 tồn tại.

Tin đã tới máy khách. Khác Zalo ở chỗ định danh kênh nằm ở recipient.id: Facebook giữ nguyên vai "người dùng là sender" cho cả sự kiện giao nhận. delivery.mids là tuỳ chọn (tài liệu ghi "may not be present", và E3.1 đã bắt được gói thật chỉ mang watermark — tin rơi vào gói đó kẹt ở "Đã gửi" vĩnh viễn, SC-25). Vì vậy đọc CẢ HAI: cập nhật đích danh cho từng mid có mặt, và một mốc watermark quét những tin mà gói sự kiện không nêu tên.

Khách đã xem — read.watermark: mọi tin gửi trước mốc này đã được xem, không có danh sách mã tin nào (SC-3). Nhánh này chạy được nhưng field message_reads phải được bật ở CẢ HAI tầng đăng ký (App subscription lẫn subscribed_apps của từng Page) thì sự kiện mới về.

Dựng một cập nhật theo mốc từ khối delivery/read. Người dùng lấy từ sender.id — Facebook để NGƯỜI DÙNG ở sender cho cả hai sự kiện giao nhận (ngược hẳn Zalo, xem §7 mục 33 của plan). Thiếu người dùng hay thiếu mốc thì không dựng: một mốc không khoanh được hội thoại là một mốc nâng nhầm tin của khách khác.

Loại nội dung suy từ attachments[0].type; không có đính kèm thì là văn bản. Nhãn dán của Facebook về dưới dạng đính kèm image kèm trường sticker_id — tên loại không phân biệt được, phải nhìn trường đó. Nhưng lưu lượng thật đo được ngày 2026-08-27 (Graph v26.0) đặt trường ấy ở chỗ khác tài liệu: sticker_id nằm trong attachments[0].payload, còn cấp message thì KHÔNG có; kèm theo đó Facebook gửi thêm attachments[1] mang type = "sticker". Vì vậy phải hỏi cả ba chỗ — hỏi mỗi cấp message là nhãn dán ra "Hình ảnh" một cách im lặng.

Có trường sticker_id đọc được ở đối tượng này không. Facebook trả nó khi thì là số, khi thì là chuỗi, nên nhận cả hai kiểu.

Phần chữ hiển thị trên khung chat. Quy ước phải giống hệt Zalo, vì giao diện chỉ có một cách vẽ: chỉ trả về thứ đọc được như một câu. Đường dẫn tệp đi ở AttachmentUrl chứ KHÔNG đi ở đây — đổ nó vào nội dung thì bong bóng ảnh mọc thêm một dòng URL fbcdn dài ngoằng bên dưới tấm ảnh, và cột xem trước ở danh sách hội thoại hiện nguyên đường dẫn thay vì "[Hình ảnh]" (nhãn đó do lõi tự đặt khi nội dung rỗng). Toạ độ trả về đúng định dạng "vĩ độ,kinh độ" mà giao diện đang dựng liên kết bản đồ — Facebook đặt tên trường là lat/long chứ không phải latitude/longitude như Zalo.

Đường dẫn tệp do Facebook cung cấp. Đường dẫn này CÓ THỜI HẠN (sổ nợ SC-9), giai đoạn này vẫn chỉ lưu lại chứ chưa tải tệp về máy chủ.

Facebook gửi timestamp dạng số mili giây ở cấp sự kiện. Không đọc được thì lấy giờ hiện tại để tin nhắn vẫn vào đúng chỗ thay vì rơi về năm 1970.

Đọc một trường dạng chuỗi, chấp nhận cả số: Facebook trả app_id và sticker_id lúc là số lúc là chuỗi tuỳ phiên bản Graph API.

Tin nhắn đã được chuẩn hoá về một dạng chung, không còn dấu vết của nền tảng gốc. Đây là ranh giới giữa phần đặc thù nền tảng (parser) và lõi chat.

Nền tảng gửi tin

Định danh kênh phía nền tảng (OA id / Page id) lấy từ payload. Đây CHỈ là gợi ý để tra kênh trong DB — không bao giờ dùng làm căn cứ tin cậy.

Định danh người dùng phía nền tảng

Chiều của tin so với hệ thống. Mặc định là — khách gửi vào. Có chiều ở đây vì một lý do rất thật: nhân viên vẫn trả lời khách từ CHÍNH ứng dụng Zalo OA trên điện thoại, và nền tảng báo việc đó về bằng sự kiện oa_send_*. Không lưu chúng thì khung chat hiện một cuộc trò chuyện thiếu hẳn một nửa — câu hỏi của khách có, câu trả lời không. Parser là nơi biết sự kiện nào thuộc chiều nào; lõi chỉ đọc trường này. Đừng suy chiều từ việc so ExternalUserId với định danh kênh trong lõi — đó là kiến thức nền tảng.

Tên người dùng nếu payload có mang theo

Ảnh đại diện người dùng nếu payload có mang theo

Loại nội dung

Nội dung văn bản hoặc mô tả của tin đa phương tiện

Đường dẫn tệp đính kèm do nền tảng cung cấp

Định danh tin nhắn phía nền tảng — dùng chống lưu trùng khi webhook được gửi lại

Mã tin gốc mà tin này trả lời trích dẫn, nếu payload có mang. Zalo đặt ở message.quote_msg_id, Facebook ở message.reply_to.mid — hai chỗ khác nhau, cùng một ý nghĩa, nên chuẩn hoá về đúng một trường (SC-27).

Định danh hội thoại phía nền tảng, chỉ điền khi nền tảng đòi HAI mã để gửi tin ngược lại. Parser là nơi biết điều đó; lõi chỉ chép xuống ChatConversation rồi chuyển tiếp lại cho tầng nền tảng khi gửi. Nền tảng nào chỉ cần một mã thì để trống (SC-28).

Người gửi là khách ẩn danh — nền tảng không cấp định danh bền vững cho họ. Parser đặt cờ này vì chỉ parser biết sự kiện nào thuộc luồng ẩn danh. Lõi dùng nó để đánh dấu hội thoại, và giao diện dựa vào đó để không mời gắn khách hàng.

Định danh admin của nền tảng đã gõ tin, khi tin chiều ra được gõ từ ứng dụng quản trị của nền tảng chứ không qua LADA (SC-26). Zalo đặt sender.admin_id trong sự kiện oa_send_* CHỈ khi tin gõ tay từ cửa sổ chat OA Admin — tin LADA gửi qua Open API không có trường này, và nhánh ẩn danh (oa_send_anonymous_*) cũng không (đo thật 2026-08-27). Facebook không có gì tương đương, để trống.

Thời điểm nền tảng ghi nhận tin nhắn

Một cập nhật trạng thái giao nhận do nền tảng báo về (đã nhận / đã xem).

Định danh kênh phía nền tảng mà cập nhật này thuộc về. Cũng chỉ là gợi ý như : lõi vẫn phải tra kênh trong DB. Bắt buộc có để cập nhật giao nhận đi qua đúng cổng kiểm tra như tin nhắn — thiếu nó thì ai cũng đổi được trạng thái tin của kênh bất kỳ.

Định danh tin nhắn phía nền tảng cần cập nhật

Trạng thái mới

Một cập nhật giao nhận theo MỐC THỜI GIAN: mọi tin chiều ra của hội thoại gửi trước mốc này đã đạt . Đây là hình dạng mà watermark của Facebook diễn đạt (message_deliveries có thể về KHÔNG kèm mids, message_reads thì không bao giờ có mã tin) — sổ nợ SC-25 / SC-3, quyết định nới lõi ghi ở §6.11 của plan.

Định danh kênh phía nền tảng — cùng vai trò gợi-ý-phải-tra-lại như .

Định danh người dùng phía nền tảng, để khoanh đúng MỘT hội thoại. Một mốc thời gian không có phạm vi hội thoại là một mốc nâng nhầm tin của khách khác.

Mốc thời gian: tin chiều ra gửi TRƯỚC HOẶC BẰNG mốc này đã đạt trạng thái đích

Trạng thái đích (Delivered với delivery, Read với read)

Một lần thả (hoặc gỡ) biểu tượng cảm xúc lên một tin nhắn đã có. Đi thành một hợp đồng riêng chứ không thành : thả cảm xúc là thuộc tính của một tin đã có, không phải tin mới. Ép nó thành tin thì mỗi lần khách thả một trái tim sẽ mọc thêm một bong bóng rác giữa cuộc trò chuyện và cột xem trước của danh sách hội thoại hiện "[Tin nhắn]" — lý lẽ này ghi ở §4 GĐ F1 từ hồi mục SC-29 còn mang quyết định "không làm", và nó vẫn đúng nguyên sau khi quyết định đảo chiều.

Định danh kênh phía nền tảng — cùng vai trò gợi-ý-phải-tra-lại như ở . Bắt buộc có để cập nhật cảm xúc đi qua đúng cổng kiểm kênh như tin nhắn và giao nhận.

Định danh người dùng phía nền tảng, để khoanh đúng MỘT hội thoại. Không có nó thì một mã tin trùng sẽ gắn cảm xúc vào tin của khách khác.

Định danh tin nhắn được thả cảm xúc, phía nền tảng

Biểu tượng cảm xúc dạng ký tự emoji thật, đã được tầng nền tảng dịch từ mã riêng của nó. null khi bật. Parser nào không dịch được mã của mình sang emoji thì không được dựng bản ghi này — hãy ghi nhật ký kèm chính mã đó. Để mã thô đi tiếp là nó chảy vào database rồi ra tới màn hình dưới dạng chữ, đúng bẫy SC-34.

Người dùng GỠ cảm xúc đã thả, thay vì thả một cái mới

Cảm xúc này do phía OA/Page thả (Zalo oa_reacted_message), chứ không phải khách. Quyết định cảm xúc rơi vào cột nào của tin.

Vì sao một payload webhook bị bỏ qua. Phân biệt hai loại này là toàn bộ giá trị của SC-30: gộp chung một mức nhật ký thì mọi sự kiện nền tảng gửi mà LADA chưa hỗ trợ đều biến mất không để lại dấu vết, và hệ thống hỏng CÂM trên production.

Bỏ có chủ ý: hệ thống BIẾT sự kiện này và đã quyết định không xử lý — tiếng vọng của chính LADA, message_reads theo §6.11, sự kiện nằm ngoài phạm vi phiên bản 1. Ghi nhật ký mức Debug là đủ.

Sự kiện nền tảng gửi mà LADA CHƯA hỗ trợ, hoặc payload có hình dạng lạ. Đây là thứ phải nhìn thấy được từ nhật ký production — nâng lên mức Warning.

Kết quả đọc một payload webhook. Một payload rơi vào đúng một trong ba trường hợp: mang tin nhắn mới, mang cập nhật trạng thái giao nhận, hoặc là sự kiện hệ thống chưa hỗ trợ.

Danh sách tin nhắn đọc được

Danh sách cập nhật trạng thái giao nhận đọc được

Danh sách cập nhật giao nhận theo mốc thời gian (SC-25 / SC-3). Đi song song với : một sự kiện delivery của Facebook có thể sinh CẢ HAI — cập nhật đích danh cho các mids có mặt, và một mốc quét cho những tin mà gói sự kiện không nêu tên.

Danh sách lần thả/gỡ biểu tượng cảm xúc đọc được. Cũng đi song song với các danh sách trên vì Facebook gom nhiều sự kiện vào một request.

Payload hợp lệ nhưng hệ thống cố ý không xử lý (ví dụ sự kiện quan tâm/bỏ quan tâm OA). Đây KHÔNG phải lỗi — webhook vẫn trả 200.

Lý do bỏ qua, để ghi nhật ký

Loại bỏ qua — quyết định mức nhật ký ở lõi. Mặc định là để một nhánh bỏ qua viết thiếu suy nghĩ vẫn im lặng; nhánh nào muốn ồn phải nói ra.

Tên sự kiện đọc được từ payload, để nhật ký gọi đúng tên thứ đang rơi. Không đọc được thì để trống.

Sự kiện chưa hỗ trợ nằm LẪN trong một payload mà phần còn lại đọc được bình thường. Cần vì Facebook gom nhiều sự kiện vào một request: chỉ báo động khi cả payload không đọc được gì là bỏ sót đúng đường thường gặp nhất — một tin khách bình thường đi kèm một sự kiện lạ thì sự kiện lạ đó biến mất không dấu vết. Lõi ghi Warning cho từng mục ở đây, độc lập với .

Payload mang tin nhắn mới

Payload mang cập nhật trạng thái giao nhận

Payload hệ thống BIẾT và cố ý không xử lý. Nhật ký mức Debug.

Payload mang sự kiện chưa hỗ trợ hoặc có hình dạng lạ. Nhật ký mức Warning, kèm tên sự kiện — đây là đường duy nhất để biết nền tảng đang gửi thứ gì mà LADA đang bỏ rơi.

Toàn bộ dữ liệu thô của một request webhook, đủ để mọi nền tảng tự kiểm chữ ký theo cách riêng. Mang cả header vì mỗi nền tảng cần thứ khác nhau: Zalo cần X-ZEvent-Signature (chữ ký nối chuỗi kèm dấu thời gian nằm trong thân), Facebook cần X-Hub-Signature-256 (HMAC). Giữ nguyên hình dạng này để thêm nền tảng mới không phải đổi giao diện.

Thân request nguyên văn — chữ ký tính trên chuỗi này, không phải trên object đã parse

Toàn bộ header của request, tra không phân biệt hoa thường

Lấy một header, trả chuỗi rỗng nếu không có

Điểm mở rộng chiều NHẬN TIN. Mỗi nền tảng hiện thực đúng một lớp này. Thêm nền tảng mới = thêm một lớp, KHÔNG sửa lõi.

Nền tảng mà parser này phụ trách

Đọc payload thô thành kết quả chuẩn hoá

Kiểm chữ ký của request theo đúng công thức nền tảng quy định. Không bao giờ được trả true vô điều kiện.

Đọc webhook của Zalo Official Account. Viết theo tài liệu chính thức đọc ngày 2026-08-26 tại developers.zalo.me/docs/official-account/webhook/… (nội dung thật nằm ở stc-developers.zdn.vn/docs/v2/…/index.html). Toàn bộ hiểu biết riêng của Zalo dừng lại ở lớp này — lõi chat không biết Zalo là gì.

Tên header mang chữ ký của Zalo

Tên header Zalo dùng để báo đây là lần gửi lại thứ mấy

Sự kiện Zalo có gửi mà LADA cố ý chưa xử lý ở phiên bản 1. Danh sách này tồn tại để tách khỏi nhánh "chưa từng lường tới": tên nằm trong đây thì nhật ký im ở mức Debug, tên lạ thì lên mức Warning (sổ nợ SC-30). Thêm tên vào đây là một quyết định, không phải thao tác dọn nhật ký. Chỉ thêm khi đã đối chiếu danh sách sự kiện trên cổng nhà phát triển và kết luận rằng LADA không cần sự kiện đó — kèm lý do trong sổ nợ.

Kiểm chữ ký theo công thức Zalo công bố: mac = sha256(appId + data + timeStamp + OASecretKey), trong đó data là nguyên văn chuỗi JSON của thân request, còn appId và timeStamp lấy từ chính thân request đó. Đây là băm nối chuỗi, KHÔNG phải HMAC — đừng đem công thức của Facebook sang dùng.

Đọc một sự kiện mang tin nhắn. Bốn luồng của Zalo dùng chung hàm này vì chúng chỉ khác nhau ở hai chỗ: ai đứng ở vai sender và khách có ẩn danh hay không.

true với sự kiện oa_send_*: vai sender/recipient ĐẢO so với sự kiện khách gửi — OA là bên gửi, người dùng là bên nhận, giống hệt hai sự kiện giao nhận. Lấy nhầm chiều là gắn hội thoại vào định danh của chính OA (§7 mục 33). Sự kiện oa_send_* về webhook cả khi tin đi từ LADA lẫn khi nhân viên trả lời từ chính ứng dụng Zalo OA — nhánh thứ hai là lý do phải xử lý (sổ nợ SC-8): không có nó thì khung chat thiếu hẳn những câu trả lời gõ ngoài SPA. true với luồng ẩn danh (anonymous_send_* và oa_send_anonymous_*). Khi đó payload mang thêm message.conversation_id, và API gửi tin đòi CẢ HAI mã. user_id_by_app cũng có trong payload nhưng đo thật thấy nó ĐỔI giữa hai phiên widget nên không dùng làm khoá hội thoại được.

Mã tin gốc của một tin trả lời trích dẫn. Zalo chỉ gửi MÃ, không gửi nội dung — nội dung được tra ngược ở tầng dịch vụ theo cặp (hội thoại, mã tin). Hỏi CẢ HAI cấp có chủ ý: sổ nợ SC-27 ghi trường này nằm ở message.quote_msg_id, còn tài liệu Zalo đọc lại 2026-08-27 nói *"trong data có thêm quote_msg_id"* — tức cấp gốc payload. Hai nguồn không khớp nhau và chưa có payload thật để phân xử, nên hỏi cả hai chỗ; đúng bài học §7 mục 36 của nhãn dán Facebook (tài liệu chỉ một chỗ, lưu lượng thật lại đặt ở chỗ khác). Tin thường không có trường này ở đâu cả, trả về null.

Đọc một sự kiện thả biểu tượng cảm xúc (user_reacted_message / oa_reacted_message). Payload mang message.msg_id và message.react_icon. 🔴 Giới hạn của chính nền tảng, phải nhớ khi đọc số liệu: tài liệu Zalo ghi nguyên văn rằng sự kiện này chỉ được gửi về khi người dùng nhận tin trên Zalo Mobile. Khách thả cảm xúc trên Zalo PC/Web thì OA không nhận được gì. Vì thế cột cảm xúc của kênh Zalo không phản ánh đầy đủ những gì khách đã thả — đừng đọc nó như một phép đếm. Tài liệu không mô tả riêng chiều GỠ, nhưng mã /-remove là mã Zalo dùng cho việc gỡ ở chiều gửi nên nhánh này nhận nó thành IsRemoved — thiếu thì mọi lần khách gỡ cảm xúc rơi vào "mã lạ" và huy hiệu cũ nằm lại màn hình vĩnh viễn.

Định danh kênh của hai sự kiện giao nhận nằm ở sender.id — ở các sự kiện này OA là bên GỬI còn người dùng là bên NHẬN, ngược hẳn với sự kiện khách gửi tin. Lấy nhầm sang recipient.id là tra ra định danh người dùng chứ không phải kênh.

Loại nội dung ưu tiên lấy theo attachments[0].type vì tên sự kiện không đủ chi tiết (ảnh GIF cũng về bằng user_send_image), chỉ khi không có đính kèm mới suy từ tên sự kiện.

Phần chữ hiển thị trên khung chat. Tin văn bản lấy message.text; tin đa phương tiện lấy thứ mô tả được nó (tên tệp, mô tả liên kết, toạ độ).

Đường dẫn tệp gốc do Zalo cung cấp. Giai đoạn A chỉ lưu lại đường dẫn, chưa tải tệp về máy chủ (đường dẫn của Zalo có thể hết hạn — nợ kỹ thuật đã ghi).

Lấy app_id và timestamp phục vụ tính chữ ký. Payload thiếu trường nào thì phần đó là chuỗi rỗng — chữ ký sẽ không khớp, đúng như mong muốn.

Bỏ tiền tố mac= nếu Zalo gửi kèm, và chuẩn hoá về chữ thường.

Zalo gửi timestamp dạng chuỗi mili giây. Không đọc được thì lấy giờ hiện tại để tin nhắn vẫn vào đúng chỗ thay vì rơi về năm 1970.

Đọc một trường dạng chuỗi. Zalo trả timestamp lúc là chuỗi lúc là số tuỳ sự kiện, nên chấp nhận cả hai thay vì ném lỗi.

Lớp duy nhất trong hệ thống biết giao thức của Zalo Official Account API. Mọi số liệu dưới đây lấy nguyên văn từ tài liệu thật ngày 2026-08-26 (https://stc-developers.zdn.vn/docs/v2/<đường-dẫn>/index.html — thiếu /index.html là nhận vỏ SPA kèm HTTP 200 chứ không phải 404). Lớp này KHÔNG chạm tới database và KHÔNG biết gì về ChatChannel: nó nhận access token đã giải mã sẵn và trả về kết quả thô. Việc lấy/lưu token là của ChatChannelService, việc ghép vào lõi chat là của ZaloMessenger.

Dựng đường dẫn để admin của OA bấm vào và cấp quyền cho ứng dụng.

Đổi authorization code (hiệu lực 10 phút, dùng một lần) lấy cặp access + refresh token.

Làm mới access token bằng refresh token. Refresh token của Zalo chỉ dùng được một lần: gọi thành công là bản cũ chết ngay, và access token cũ cũng hết hiệu lực lập tức. Mất cặp mới trả về là kênh chết im lặng.

Gửi tin tư vấn dạng văn bản. là mã tin nhắn phía Zalo mà tin này TRẢ LỜI TRÍCH DẪN, bỏ trống thì gửi tin thường. Tên trường trong thân request là message.quote_message_id — không trùng tên với message.quote_msg_id mà webhook gửi về ở chiều ngược lại (tài liệu "Gửi tin tư vấn trích dẫn", đọc 2026-08-28). Hai chiều lệch tên nhau là chỗ dễ chép nhầm nhất của tính năng này.

Tải một tệp ảnh lên máy chủ Zalo để lấy attachment_id.

Gửi tin tư vấn đính kèm ảnh. Truyền một trong hai: (đã tải lên) hoặc (đường dẫn công khai).

Gửi tin văn bản cho một người dùng ẩn danh. Đòi CẢ HAI mã: và — thiếu một là Zalo từ chối.

Gửi ảnh cho một người dùng ẩn danh. Thân request KHÔNG có chỗ cho chú thích: tài liệu luồng ẩn danh chỉ có message.attachment, không có message.text đi kèm. Caller muốn kèm chú thích thì phải gửi thành một tin văn bản riêng.

Thả (hoặc gỡ) một biểu tượng cảm xúc lên tin nhắn của khách. Nhận emoji thật chứ không nhận mã Zalo: việc dịch sang react_icon nằm ở , để mã riêng của Zalo không rò ra khỏi tầng này. Emoji ngoài bảng sáu mã của Zalo bị từ chối tại chỗ với một câu đọc được. Đặt để gỡ biểu tượng đã thả — Zalo không có endpoint xoá riêng, gỡ là gửi lại chính lời gọi này với mã /-remove.

Lấy tên và ảnh đại diện của một người dùng đã tương tác với OA.

Lấy thông tin OA đang gắn với access token — dùng để đặt tên kênh sau khi cấp quyền.

Tên HttpClient đã đăng ký sẵn ở DependencyRegister

Endpoint gửi tin cho người dùng ẩn danh (khách nhắn từ widget web, chưa đăng nhập Zalo). Vẫn là v2.0 có chủ ý: đọc lại tài liệu ngày 2026-08-27 thì Zalo KHÔNG cung cấp bản v3 nào cho luồng ẩn danh — /v3.0/oa/message/cs chỉ nhận user_id, không nhận anonymous_id. Bảng mã lỗi có -240 "MessageV2 API has been shut down", nên nếu Zalo trả mã đó ở đây thì luồng ẩn danh coi như bị khai tử và KHÔNG có đường vòng; phải nói được điều đó cho nhân viên đọc.

Endpoint thả biểu tượng cảm xúc. Trùng URL với đường ẩn danh ở trên là đúng, không phải chép nhầm — Zalo gom cả nhóm "các loại tin khác" vào v2.0/oa/message và phân biệt bằng thân request (sender_action thay cho message). Khai riêng một hằng số để chỗ dùng đọc được ý, và để ngày Zalo tách endpoint thì chỉ sửa một dòng. 🔴 Chưa đo bằng lưu lượng thật. Tài liệu xếp trang này trong nhánh v3 hiện hành nhưng vẫn ghi URL v2.0, trong khi bảng mã lỗi có -240 "MessageV2 API has been shut down". Cùng một mâu thuẫn với luồng ẩn danh (§6.12) — và ở đó thì v2.0 gọi thật đã thành công. Nhận -240 ở đây thì chiều nhân viên thả cảm xúc coi như bị Zalo khai tử; chiều NHẬN cảm xúc của khách vẫn chạy vì nó đi bằng webhook.

Giới hạn tài liệu ghi cho nội dung tin tư vấn dạng văn bản

Giới hạn tài liệu ghi cho ảnh tải lên: 1 MB, chỉ jpg và png

Khoá bí mật của ỨNG DỤNG — gửi ở header secret_key của luồng OAuth. Không phải khoá ký webhook (khoá đó là OA Secret Key).

Đường dẫn công khai Zalo chuyển hướng về sau khi admin OA đồng ý cấp quyền

Code verifier của PKCE. Zalo giữ code challenge ở cấu hình ứng dụng trên cổng nhà phát triển (không truyền theo từng request), nên phía LADA phải giữ đúng một verifier cố định khớp với nó. Bỏ trống = cổng không cấu hình code challenge, luồng đổi token không gửi code_verifier.

Tính code challenge từ code verifier: Base64(SHA-256(ASCII(code_verifier))), bỏ ký tự đệm. Trả về hai biến thể vì tài liệu Zalo và chuẩn PKCE nói khác nhau ở đúng một chỗ: tài liệu ghi "encode Base64 (without Padding)" (bảng chữ cái có + và /), còn RFC 7636 quy định base64url (- và _). Chỉ khác nhau khi mã băm sinh ra hai ký tự đó, tức là phần lớn trường hợp. Không có cách nào phân xử trên giấy — chủ dự án dán giá trị vào cổng nhà phát triển rồi chạy thử là biết ngay cái nào đúng.

Gửi một request tới endpoint OAuth và đọc cặp token trong phản hồi. Không bao giờ đưa nội dung form (chứa code/refresh token) vào nhật ký hay thông điệp lỗi.

Endpoint OAuth không dùng chung khuôn { data, error, message } với OpenAPI, và tài liệu không mô tả hình dạng phản hồi lỗi. Gom mọi tên trường lỗi hay gặp rồi mới lùi về mã HTTP.

Cả hai mã của người ẩn danh đều bắt buộc. Kiểm ở đây để lỗi nói đúng chuyện đang xảy ra, thay vì để Zalo trả một mã lỗi chung rồi nhân viên đọc không hiểu.

Gửi một thân request tới endpoint gửi tin. Endpoint là tham số vì luồng ẩn danh dùng một đường khác hẳn (v2.0), và phản hồi của nó KHÔNG có quota lẫn sent_time — hàm này chỉ đọc data.message_id nên chịu được cả hai hình dạng.

Gọi một API đọc của Zalo OpenAPI và trả về phần tử gốc của JSON, hoặc null nếu hỏng. Đây là đường phụ trợ (làm giàu hồ sơ, đặt tên kênh) nên hỏng thì chỉ ghi nhật ký chứ không ném.

Đường dẫn cấp quyền kèm những gì admin cần để khai báo trên cổng nhà phát triển.

Đường dẫn callback đã kèm state — phải khai đúng chuỗi này ở mục Callback URL trên cổng.

Đã cấu hình SocialChat:Zalo:CodeVerifier hay chưa

Code challenge theo chuẩn PKCE (base64url, bỏ ký tự đệm)

Code challenge theo đúng chữ nghĩa tài liệu Zalo (base64 thường, bỏ ký tự đệm)

Cặp token Zalo trả về sau khi đổi code hoặc làm mới.

Kết quả một lần gửi tin.

Kết quả tải ảnh lên máy chủ Zalo.

Hồ sơ rút gọn của một người dùng Zalo.

Thông tin rút gọn của một Official Account.

Dịch mã lỗi của Zalo Official Account API ra tiếng người. Nội dung lấy từ trang "Mã lỗi Official Account API" đọc ngày 2026-08-26. Chỉ giữ những mã một nhân viên chăm sóc khách hàng có thể gặp khi gửi tin — mã lạ thì trả nguyên văn thông điệp của Zalo kèm số hiệu, tuyệt đối không nuốt.

Trả về mô tả tiếng Việt của một mã lỗi Zalo, kèm số hiệu để tra cứu lại tài liệu.

Bảng đổi qua lại giữa biểu tượng cảm xúc mà LADA dùng và mã cảm xúc của Zalo. Lõi chat nói chuyện bằng emoji thật (ký tự Unicode), tầng nền tảng tự dịch — nếu không thì chuỗi "/-strong" sẽ chảy vào DTO rồi ra thẳng màn hình, đúng cái bẫy SC-34 đã cắn một lần: mã biểu tượng của Zalo lọt vào LADA dưới dạng chữ thô và nhân viên đọc được :b:-h thay vì thấy một hình. Bảng này CỐ Ý chỉ có sáu mã — đúng sáu mã mà tài liệu Zalo mô tả kèm ý nghĩa rõ ràng (đọc 2026-08-28, trang "Thả biểu tượng cảm xúc vào tin nhắn"). Tài liệu còn nhắc một mã thứ bảy là :-h trong ví dụ webhook nhưng hai nguồn mô tả nó khác nhau ("ngại" và "vẫy tay"), nên nó KHÔNG có ở đây: đoán sai nghĩa rồi vẽ nhầm một cảm xúc lên màn hình còn tệ hơn không vẽ gì. Mã lạ đi vào đường nhận sẽ được ghi nhật ký kèm chính mã đó (sổ nợ SC-36), quan sát được lưu lượng thật thì bổ sung vào đây.

Mã đặc biệt để gỡ biểu tượng cảm xúc đã thả. Zalo không có endpoint xoá riêng — gỡ là gửi lại chính lời gọi thả với mã này.

Bảng tra emoji → mã Zalo. So khớp theo thứ tự byte, không theo văn hoá.

Bảng tra ngược, dựng từ đúng bảng trên để hai chiều không bao giờ lệch nhau.

Sáu biểu tượng nhân viên được phép thả trên một hội thoại Zalo, theo đúng thứ tự hiển thị. Giao diện lấy danh sách này từ máy chủ chứ không tự chép lại — chép lại là hai bảng song song rồi sẽ lệch, và cái lệch chỉ lộ ra khi Zalo trả lỗi cho một biểu tượng đã bấm được.

Đổi emoji sang mã Zalo. Trả null khi Zalo không có mã tương ứng — caller phải từ chối bằng một câu đọc được, đừng gửi đi một mã bịa.

Đổi mã Zalo sang emoji để hiển thị. Trả null với mã chưa có trong bảng — đường nhận webhook phải ghi nhật ký rồi bỏ qua, tuyệt đối không lưu mã thô xuống database.

Dịch vụ quản lý khóa học đào tạo.

Tìm kiếm khóa học.

Lấy tất cả khóa học đang hoạt động (có filter theo quyền user).

Lấy chi tiết khóa học (bao gồm sections).

Tạo hoặc cập nhật khóa học.

Xóa khóa học.

Lấy danh sách PermissionIds được gán cho khóa học.

Cập nhật danh sách Permission cho khóa học.

Dịch vụ quản lý bài giảng.

Lấy danh sách bài giảng của section.

Lấy tất cả bài giảng của khóa học (theo GlobalOrder).

Lấy bài giảng độc lập (không thuộc chương nào) của khóa học.

Lấy tất cả LessonItem (lightweight projection) của khóa học - dùng cho Curriculum.

Lấy chi tiết bài giảng (bao gồm media).

Lấy chi tiết bài giảng kèm media items (cho learner view).

Tạo hoặc cập nhật bài giảng.

Xóa bài giảng.

Sắp xếp lại thứ tự bài giảng trong section.

Sắp xếp lại thứ tự toàn bộ bài giảng (GlobalOrder) trong khóa học.

Dịch vụ lưu trữ media - thiết kế linh hoạt để mở rộng Cloud Storage sau này.

Upload file media cho bài giảng.

Lấy danh sách media của bài giảng.

Xóa media.

Sắp xếp lại thứ tự media.

Lưu trữ media trên local storage (wwwroot/training-media/). Khi cần mở rộng sang Cloud Storage, chỉ cần tạo thêm CloudMediaStorageService implement IMediaStorageService và thay DI registration.

Dịch vụ quản lý section trong khóa học.

Lấy danh sách sections của khóa học.

Lấy chi tiết section.

Tạo hoặc cập nhật section.

Xóa section.

Sắp xếp lại thứ tự sections.

Đầu vào tính tình trạng một bộ phận — đã gom đủ mọi thứ engine cần, không tra thêm DB.

Ngày lắp bộ phận (mốc tính tuổi thọ theo thời gian)

ODO của xe lúc lắp; null khi lắp lúc xe chưa có chuỗi ODO nào

Tuổi thọ hiệu lực theo km = LifespanKmOverride ?? loại.DefaultLifespanKm

Tuổi thọ hiệu lực theo tháng = LifespanMonthsOverride ?? loại.DefaultLifespanMonths

Ngưỡng báo trước theo km — loại bộ phận ghi đè, thiếu thì lấy ngưỡng toàn cục

Ngưỡng báo trước theo ngày — loại bộ phận ghi đè, thiếu thì lấy ngưỡng toàn cục

Số ngày sau đó coi chuỗi ODO của xe là quá cũ

Xe đang chạy hay không (OperatingStatus.Running).

Quyết định duy nhất phụ thuộc trường này là có bắn hay không — số đo Việc 0 (plan §5.1): 11/16 xe Stop có ODO cũ hơn 30 ngày, bắn cảnh báo cho chúng là tạo 11 cảnh báo rác ngay ngày đầu.

ODO hiện tại của xe theo hàm chuẩn ITruckOdoService

Dựng đầu vào từ bộ phận + loại của nó — nơi duy nhất diễn giải "tuổi thọ hiệu lực" và "ngưỡng hiệu lực".

Quy tắc giống hệt TruckComponentItem.EffectiveLifespanKm/Months của GĐ A: giá trị riêng của bộ phận thắng, thiếu thì lấy mặc định của loại. Ngưỡng cảnh báo cũng vậy: loại khai WarnBeforeKm/Days thì dùng của loại, không thì dùng ngưỡng toàn cục AppConfig. Cả API tình trạng lẫn job quét đều đi qua đây để hai bên không bao giờ ra số khác nhau.

Tình trạng tính được của một bộ phận tại một thời điểm.

Mức cảnh báo; null nghĩa là chưa cần cảnh báo

Loại bộ phận có khai ít nhất một tiêu chí tuổi thọ (km hoặc tháng)

Tính được tiêu hao theo km hay không

Tính được tiêu hao theo thời gian hay không

Số km đã dùng từ lúc lắp; null khi không tính được

Số km còn lại trước khi hết tuổi thọ; âm nghĩa là đã vượt

Số ngày đã dùng từ lúc lắp

Số ngày còn lại trước khi hết tuổi thọ; âm nghĩa là đã vượt

Hạn theo thời gian (ngày lắp + tuổi thọ tháng)

Tỷ lệ tiêu hao theo km (%)

Tỷ lệ tiêu hao theo thời gian (%)

Tỷ lệ tiêu hao dùng để hiển thị = lớn hơn trong hai tiêu chí tính được.

Đúng luật §3.3: tiêu chí nào đến trước thì tính tiêu chí đó.

Lý do khi một tiêu chí không tính được — hiển thị cho người dùng, tiếng Việt

Tính tình trạng tuổi thọ của một bộ phận theo luật §3.3 của plan bảo dưỡng xe tải.

Thuần tính toán, không chạm DB — mọi dữ liệu vào qua . Tách như vậy để phủ được đủ ca biên (ODO âm, thiếu mốc lắp, chỉ một tiêu chí) bằng test đơn vị không cần fixture, vì đây là chỗ sai một lần thì cảnh báo sai hàng loạt.

Tính tình trạng một bộ phận tại thời điểm

Nhánh thời gian: hạn = ngày lắp + số tháng tuổi thọ.

Cộng tháng bằng AddMonths chứ không quy ra 30 ngày — bộ phận lắp 31/1 với tuổi thọ 1 tháng phải đến hạn 28/2, quy đổi 30 ngày sẽ lệch sang tháng 3.

Nhánh km. Trả về true khi chuỗi ODO của xe quá cũ để tin.

Ba trường hợp không tính được theo km, mỗi trường hợp là một sự thật đo được ở Việc 0: thiếu mốc InstalledOdo (GĐ A cố ý để null thay vì gán 0), xe chưa có ODO nào, và km đã dùng ra số âm — xe 29H78282 thay đồng hồ nên ODO hiện tại nhỏ hơn ODO lúc lắp. Cả ba đều rơi về tiêu chí thời gian, tuyệt đối không được lặng lẽ thành "còn mới".

Chọn mức cảnh báo — nặng hơn thắng: Overdue > DueSoon > StaleOdo.

StaleOdo chỉ có nghĩa với bộ phận tính theo km và chỉ với xe đang chạy: xe đỗ bãi không có ODO mới là chuyện bình thường (plan §5.1 giả định 1).

Áp luật §3.3 của phân hệ bảo dưỡng lên bộ phận xe sau khi một lần bảo dưỡng được lưu: thay mới thì reset mốc, đảo thì hoán vị trí, sửa/xoá dòng cũ thì tính lại mốc.

Phải chạy trong cùng transaction với lệnh lưu bản ghi bảo dưỡng. Mốc lắp là gốc để tính tuổi thọ; lưu được dòng công việc mà không cập nhật được mốc là lịch sử bộ phận hỏng âm thầm — rủi ro lớn nhất của giai đoạn này theo plan §5.

Đồng bộ bộ phận sau khi các dòng công việc của một lần bảo dưỡng đã được ghi.

Bản ghi bảo dưỡng vừa lưu Các dòng "Đảo vị trí" vừa được tạo trong lần lưu này. Chỉ dòng mới mới được hoán vị: bấm Lưu lần thứ hai trên cùng bản ghi mà hoán lại là hai lốp quay về đúng chỗ cũ. Mọi bộ phận có dòng công việc bị thêm/sửa/xoá trong lần lưu này

Tính lại mốc lắp của một bộ phận theo dòng "Thay mới" gần nhất còn lại; không còn dòng nào thì quay về nguyên bản nhà máy. Gọi được độc lập khi xoá cả một lần bảo dưỡng.

Xe mà bộ phận phải thuộc về. Khác thì bỏ qua, không ghi gì — chốt phòng thủ chiều sâu cho trường hợp id bộ phận đến từ payload client lọt qua được tầng kiểm tra phía trên.

Đảo vị trí: hoán của hai bộ phận cùng loại trên cùng xe, giữ nguyên mốc lắp của từng cái (lốp mang theo tuổi thọ của nó khi đổi chỗ).

Hoán vị trí qua ba bước, đi vòng qua .

Unique index IX_TruckComponent_TruckId_ComponentTypeId_Position lọc IsActive = 1 AND Position <> 0 và được SQL Server kiểm ngay sau từng lệnh UPDATE, không đợi hết transaction. Gán thẳng A←B rồi B←A là ở bước giữa hai bản ghi cùng vị trí ⇒ lỗi 2601. Đỗ tạm ở None nằm ngoài bộ lọc index nên không đụng ai.

Đóng mọi cảnh báo đang mở của một bộ phận (đánh dấu đã xử lý, không xoá mềm)

Tên gọi khác của loại bộ phận K200 (plan bảo dưỡng đợt 3 §3.4). Đường ghi DUY NHẤT là người dùng bấm "Ghi nhớ" trên một gợi ý — LLM chỉ đề xuất. Danh mục dùng chung toàn công ty nên alias không gác chi nhánh, nhưng role là Truck.ComponentTypeManage (chặt hơn role đọc gợi ý).

Các alias đang dùng; > 0 thì chỉ của loại đó.

Ghi nhớ một alias. Cùng tên đã trỏ về đúng loại đó → thành công, không tạo trùng.

Gỡ một alias (xoá mềm).

Khởi tạo dịch vụ alias loại bộ phận.

Dịch vụ danh mục garage. Danh mục dùng chung toàn công ty — không gác phạm vi chi nhánh (quyết định Q5, plan §7.1).

Tìm kiếm garage có phân trang.

Lấy danh sách garage đang bật để đổ vào ô chọn.

Lấy garage theo ID.

Tạo mới hoặc cập nhật garage.

Xoá mềm garage. Từ chối khi garage đang được bản ghi bảo dưỡng tham chiếu.

Khởi tạo dịch vụ garage.

Phạm vi chi nhánh mà một người dùng được nhìn thấy trong phân hệ bảo dưỡng xe tải. Vì sao là một kiểu riêng chứ không phải List<int>: pattern cũ trong TruckService.Search quy ước "danh sách null = không lọc = thấy tất". Quy ước đó gộp hai tình huống trái ngược nhau vào cùng một giá trị — Founder xem toàn hệ thống và người dùng không xác định được đơn vị — nên quên một nhánh là mở toang dữ liệu cả công ty. Đây đúng là loại lỗ IDOR mà audit 2026-07-11 chỉ ra. Kiểu này bắt nơi gọi nói rõ ý định: hay , không có giá trị nào mang nghĩa nước đôi.

Không giới hạn chi nhánh (Founder).

Danh sách chi nhánh được phép. Rỗng khi = true (không dùng tới) hoặc khi người dùng không được xem gì.

Người dùng không được xem bản ghi nào.

Phạm vi toàn hệ thống — chỉ dành cho Founder.

Phạm vi giới hạn theo danh sách chi nhánh (chi nhánh của người dùng + các chi nhánh con).

Không có phạm vi nào — người dùng không thuộc đơn vị nào.

Dựng phạm vi chi nhánh của người dùng hiện tại cho phân hệ bảo dưỡng.

Tách khỏi controller vì đã có hai controller cần đúng luật này (TruckMaintenanceController và TruckController ở nhóm bảo dưỡng). Hai bản sao của một luật phân quyền là hai chỗ để quên sửa một chỗ.

Phạm vi của một người dùng: Founder không giới hạn, người thường giới hạn theo chi nhánh của họ và các chi nhánh con, người không xác định được đơn vị thì không thấy gì (fail-closed).

Cờ hiển thị của phần "Đọc phiếu bằng AI" trên form bảo dưỡng (plan bảo dưỡng đợt 3 §3.6, rule quyen-hien-thi). Mỗi cờ đọc ĐÚNG bó role trên [Authorize] của endpoint nó gác — test reflection MaintenanceAiPermissionsTests khoá điều đó, đổi role ở controller mà quên ở đây là test đỏ.

Cờ không phải hàng rào: [Authorize] + phạm vi chi nhánh ở service vẫn gác như cũ. Founder được cộng vào vì vai đó bỏ qua mọi kiểm role ở máy chủ — ẩn nút của Founder là dựng một hàng rào không tồn tại.

Gác SlipRead, SlipReadUpload, SlipReading/{id}/Rematch, SlipReading/{id}/Attach.

Gác ComponentTypeAlias* và form tạo/sửa danh mục K200 hiện có.

Gác TruckController.TruckMaintAttrCreateOrUpdate (form hạng mục hiện có).

Gác ComponentCreateOrUpdate / ComponentInitForTruck (gắn bộ phận lên xe).

Role của người dùng (qua IUserRoleResolver, không qua JWT). Công tắc bật + provider đã chọn còn dùng được + có model — máy chủ tính trước.

Cờ trả cho giao diện; FE đọc từng cờ bằng === true.

Cờ trả cho giao diện; FE đọc từng cờ bằng === true.

Khoá AppConfig của đọc phiếu bảo dưỡng bằng AI — seed mặc định TẮT ở migration 202610271410.

Cấu hình đọc phiếu bảo dưỡng bằng AI đã chuẩn hoá (plan bảo dưỡng đợt 3 §3.5). Giá trị lạ không bao giờ thành "bật": chỉ true với đúng chuỗi true, số hỏng lấy mặc định của QĐ3-8.

Cấu hình đọc phiếu bảo dưỡng bằng AI đã chuẩn hoá (plan bảo dưỡng đợt 3 §3.5). Giá trị lạ không bao giờ thành "bật": chỉ true với đúng chuỗi true, số hỏng lấy mặc định của QĐ3-8.

Dưới mức này chữ trên phiếu không còn đọc được; trên 8000 px Anthropic từ chối.

Đủ cấu hình để gọi được (công tắc bật, có provider, có model) — chưa xét provider còn dùng được.

Đọc 6 khoá qua IAppConfigService CỦA FRAMEWORK (ghi rõ namespace: repo có hai interface trùng tên) — cache 60 giây, nhóm công tắc an toàn.

Đọc một hoá đơn bảo dưỡng đã đính kèm (PDF hoặc ảnh) và gợi ý số tiền / ngày / biển số cho form.

Đọc tệp đính kèm (TruckMaintenanceMedia.Id, loại hoá đơn) của một lần bảo dưỡng trong phạm vi chi nhánh . Chạy trong request: một hoá đơn 1–2 trang mất ~0,3 giây (PDF lớp text) tới ~2,5 giây (ảnh OCR). Không ném với lỗi dữ liệu.

Cùng đường đọc như nhưng trên tệp đã nằm trong bộ nhớ — đường dự phòng khi đọc phiếu bằng AI lỗi (plan bảo dưỡng đợt 3 QĐ3-6). Nơi gọi CHỊU TRÁCH NHIỆM đã kiểm phạm vi chi nhánh của xe.

Không móc vào đường upload (nguyên tắc số 1 của đợt trích-xuất-văn-bản): tệp đã nằm trên đĩa, dịch vụ này chỉ đọc lại theo Media.SystemPath qua — có chốt "phải nằm dưới thư mục media" nên DB bị sửa cũng không đọc được file tuỳ ý trên máy chủ. Phạm vi chi nhánh tính theo xe đang gắn với bản ghi bảo dưỡng, qua dùng chung với ; ngoài phạm vi trả cùng thông điệp "không tìm thấy" để không lộ sự tồn tại của bản ghi chi nhánh khác. Ảnh đính kèm đã bị ImageService nén sang WebP rộng ≤ 1200 px trước khi lưu. Đo 2026-08-21 trên 14 ảnh thật: bản WebP đọc không kém ảnh gốc (số tiền 9/14 so với 8/14) nên không cần giữ bản gốc.

Hoá đơn, báo giá sửa chữa dài nhất gặp là 2–3 trang; trần này giữ request không kéo dài vô hạn.

Khởi tạo dịch vụ đọc hoá đơn bảo dưỡng.

Chốt an toàn rẻ nhất của cả tính năng: biển số đọc đúng 100% (GĐ B) nên so được với xe của bản ghi; lệch là dấu hiệu người dùng đính nhầm hoá đơn của xe khác.

Một loại bộ phận K200 đang dùng, kèm các tên gọi khác đã ghi nhớ.

Một loại bộ phận K200 đang dùng, kèm các tên gọi khác đã ghi nhớ.

Danh mục đích so khớp — chỉ mục đang dùng (K200 IsActive, chưa xoá).

So khớp dòng phiếu với danh mục, hai tầng (plan bảo dưỡng đợt 3 §3.4). Tầng 2a thuần, tất định, chạy trước — dòng khớp ở đây không tốn lời gọi LLM nào. Tầng 2b gửi phần còn lại cho LLM; hàm ở đây chỉ dựng câu hỏi và KIỂM câu trả lời (mã phải có trong danh mục, nhóm phải hợp lệ) — lời gọi nằm ở .

Ngưỡng Jaccard trên tập từ cho khớp mờ (§3.4 mục 3).

Trần độ dài chữ tự do LLM được trả (reason, note, name) — §3.11.

Khoá so khớp: chữ thường, tách từ theo ký tự không phải chữ/số, bỏ từ dừng, bỏ dấu (đ → d), một khoảng trắng giữa các từ. "Thay Lọc DẦU (mới)" → "loc dau".

Tầng 2a cho một dòng: khớp chính xác theo thứ tự alias → mã → tên K200 (tên đầy đủ, phần trước ngoặc, phần trong ngoặc, từng vế nối bằng "+" hay ",") → tên hạng mục; rồi khớp mờ. Khoá trỏ về ≥ 2 mục thì coi như không khớp — để LLM phân xử, không đoán. Không khớp → Decision = unmatched.

System prompt bước 2b: luật cố định + bảng danh mục (đổi ít → adapter Anthropic cache được).

Lượt user bước 2b: chỉ các dòng 2a chưa khớp — không có ảnh.

Kiểm câu trả lời bước 2b rồi đổi thành gợi ý — KHÔNG tin LLM ở bất kỳ mã/tên nào: code không có trong danh mục thì hạ thành new kèm cảnh báo, hạng mục không tồn tại thì thành đề xuất tạo hạng mục, nhóm lạ thì bỏ, chữ tự do cắt ở 300 ký tự. Dòng không được hỏi hoặc trả trùng thì bỏ qua; dòng được hỏi mà LLM không trả thì giữ unmatched.

Các khoá tên của một mục danh mục: tên đầy đủ, phần ngoài ngoặc, từng vế của phần ngoài ngoặc (tách theo "+ , ; —"), và phần trong ngoặc GIỮ NGUYÊN. Không tách trong ngoặc: ngoặc thường là lời chú thích ("Dây curoa (máy phát, điều hòa)"), tách ra thì dòng "Điều hòa" khớp nhầm sang dây curoa.

Chỉ mục tra cứu dựng từ danh mục — khoá chuẩn hoá → tập Id.

Một bản ghi bảo dưỡng đã qua lọc phạm vi chi nhánh, kèm thông tin xe mà nơi gọi hay cần.

Bản ghi bảo dưỡng.

Chi nhánh của xe đang gắn với bản ghi — đây mới là chi nhánh dùng để xét phạm vi.

Biển số xe, nguyên văn trong DB (lưu lẫn có/không dấu gạch).

Luật "bản ghi bảo dưỡng nào nằm trong phạm vi chi nhánh của người dùng" — một bản duy nhất cho cả miền.

Trước đây luật này được chép ở mỗi service chạm tới bản ghi bảo dưỡng. Đó đúng là "hai chỗ để quên sửa một chỗ": ai siết luật ở một service sẽ để service kia lặng lẽ giữ luật cũ lỏng hơn, và lỗi loại đó không nổi lên ở build cũng chẳng nổi ở test của service bị bỏ quên. Phạm vi tính theo chi nhánh của xe, không theo TruckMaintenance.AgencyId và càng không theo tham số client gửi (nợ BD-11).

Nạp bản ghi bảo dưỡng kèm chi nhánh và biển số xe nếu xe nằm trong ; null nếu không tìm thấy hoặc nằm ngoài phạm vi — nơi gọi phải trả cùng một thông điệp cho hai ca này để không lộ sự tồn tại của bản ghi chi nhánh khác.

Phần nội dung gửi LLM cho một tệp phiếu; khác null là tệp bị từ chối (không gọi AI).

Phần nội dung gửi LLM cho một tệp phiếu; khác null là tệp bị từ chối (không gọi AI).

Tệp phiếu → phần nội dung gửi LLM (plan bảo dưỡng đợt 3 §3.1 bước 1, prompt GĐ B mục 4). Phân nhánh theo NỘI DUNG tệp, không theo đuôi hay content-type client khai: PDF → Anthropic nhận khối document, OpenAI nhận ảnh render từng trang (PDF-qua-part-file chưa kiểm, nợ BD3-8); ảnh → (xoá metadata, thu cạnh); HEIC iPhone → Magick.NET đổi JPEG trước vì ImageSharp không đọc HEIC.

Phiếu dài nhất gặp là 2–3 trang (đo đợt OCR); quá thì chỉ đọc chừng này trang đầu.

Độ phân giải render trang PDF cho đường ảnh — A4 ở 200 dpi ≈ 1654×2339, sau đó vẫn qua trần cạnh.

SHA-256 hex thường của tệp gốc — khoá bộ nhớ đệm.

Dựng phần nội dung cho . Không ném với tệp hỏng — trả kèm câu tiếng Việt cố định.

HEIC → JPEG chất lượng cao (metadata xoá ở bước sau đó); null nếu không đọc được.

Đọc phiếu / hoá đơn bảo dưỡng bằng LLM đa phương thức rồi so khớp từng dòng với danh mục K200 + hạng mục (plan bảo dưỡng đợt 3 §3.1). Mọi kết quả là GỢI Ý — không hàm nào ở đây ghi , hay (Nguyên tắc số 1).

Cờ hiển thị cho người có — tính cả công tắc + provider còn dùng được.

Đọc một tệp hoá đơn/phiếu đã đính kèm (chế độ sửa). Phạm vi theo xe gắn với bản ghi.

Đọc tệp tải thẳng lúc tạo mới (QĐ3-3) — tệp KHÔNG được lưu làm media ở bước này.

Chạy lại so khớp (2a + 2b) trên kết quả đã đọc — không gửi lại ảnh. Có trần số lần.

Mở lại gợi ý của một lượt đọc trong phạm vi.

Gắn lượt đọc lúc tạo mới vào bản ghi vừa lưu (và dòng media vừa tải lên, nếu có).

Thứ tự kiểm: phạm vi chi nhánh → cấu hình/provider → bộ nhớ đệm → trần lượt/ngày → tệp → gọi AI. Phạm vi luôn đứng đầu và mọi ca "không thấy / ngoài phạm vi" trả CÙNG một câu (không lộ bản ghi chi nhánh khác). AI lỗi (timeout, 429, 5xx, JSON hỏng, key sai): ghi dòng Failed rồi chạy OCR cũ cho 3 trường tiền/ngày/biển số, trả Mode = Offline (QĐ3-6). Log chỉ ghi loại lỗi + 200 ký tự đầu câu trả lời đã che base64 — không bao giờ ghi tệp, thân request hay key.

Trần tệp đọc — khớp [RequestSizeLimit] của endpoint tải thẳng (§3.11).

Kết quả cũ cùng tệp + cùng model được dùng lại trong chừng này ngày (QĐ3-7).

Số lần "Khớp lại" (bước 2b) tối đa cho một lượt đọc.

Phiếu dài 40 dòng ≈ 3.000 token JSON (§3.2) — để dư cho phiếu dài hơn.

Số dòng tối đa giữ lại từ một phiếu.

Khởi tạo dịch vụ đọc phiếu bảo dưỡng bằng AI.

Phần đọc sau khi đã giữ chỗ: chuẩn bị tệp → bước 1 → kiểm → so khớp → cập nhật dòng giữ chỗ.

Tầng 2a cho mọi dòng, tầng 2b cho phần còn lại; 2b lỗi thì giữ dòng "chưa khớp" kèm cảnh báo, không làm hỏng lượt đọc.

Trần đếm lượt THẬT gọi AI hôm nay (Succeeded + Failed, không tính lượt lấy lại kết quả cũ hay bị từ chối).

Cổng khoá cho phép "đếm trần rồi giữ chỗ" và "trừ quỹ khớp lại" — giữ vài mili giây, không bao lời gọi AI.

Dòng "đang đọc" cũ hơn mức này coi như tiến trình đã chết — không chặn đọc lại cùng tệp.

Số lần đã khớp lại tính trên dòng gốc (lượt lấy từ bộ nhớ đệm dùng chung quỹ với dòng gốc).

Kết quả trả client từ extraction ĐÃ KIỂM + gợi ý khớp. Cảnh báo số (thành tiền lệch, tổng lệch, ngày tương lai) và đối chiếu biển số tính lại mỗi lần — biển số so với xe của NGƯỜI GỌI, kể cả khi kết quả lấy từ bộ nhớ đệm.

Kiểm tra máy chủ trên kết quả bước 1 (plan §3.3 cuối): JSON của LLM không bao giờ tới client nguyên văn — chuỗi bị cắt độ dài, giá trị enum lạ quy về mặc định, số âm/vô lý bị bỏ, dòng đánh lại số thứ tự. Các cảnh báo về SỐ (thành tiền lệch đơn giá × số lượng, tổng lệch, ngày tương lai) là thuần, tính lại mỗi lần dựng kết quả.

10 tỉ đồng — một phiếu sửa xe tải vượt mức này là đọc nhầm (gộp số, đọc cả mã số thuế).

Thành tiền lệch số lượng × đơn giá quá 5 %.

Tổng phiếu lệch tổng các dòng (quá 1 % và quá 1.000 đ); ngày chứng từ ở tương lai.

Nguồn sự thật của hai schema structured output đọc phiếu bảo dưỡng (plan bảo dưỡng đợt 3 §3.3, §3.4) và system prompt đi kèm. Test MaintenanceSlipSchemasTests khoá chuỗi schema: sửa schema là đổi hợp đồng với nhà cung cấp (mất cache biên dịch 24 h) nên phải sửa cả test, có chủ ý.

Viết theo phần GIAO của hai provider: mọi object additionalProperties: false, MỌI thuộc tính nằm trong required (OpenAI strict đòi). Không dùng minimum/maxLength/minItems — structured output của Claude không nhận; trần độ dài và khoảng số do máy chủ kiểm sau khi parse. Trần 16 tham số union mỗi schema (Anthropic, đo gọi thật 2026-10-27: 17 anyOf → 400 "Schemas contains too many parameters with union types"). Vì vậy ô CHỮ có thể trống viết chuỗi rỗng "" (máy chủ đổi thành null), hành động không rõ là "none"; chỉ ô SỐ dùng anyOf [number, null] vì 0 đ là giá trị thật. Test MaintenanceSlipSchemasTests đếm union.

System prompt bước 1 — cố định (không chứa thứ đổi theo lượt) để adapter Anthropic cache được khi đủ dài. Nội dung phiếu là DỮ LIỆU KHÔNG TIN CẬY (§3.11): prompt nói rõ chữ trong ảnh không phải chỉ dẫn.

Phần luật của system prompt bước 2b; bảng danh mục nối sau (đổi ít — breakpoint cache nằm cuối system).

Tuỳ chọn ghi/đọc JSON đã kiểm vào TruckMaintenanceSlipReading — camelCase như hợp đồng với LLM.

Giao diện cho dịch vụ quản lý hoạt động xe tải.

Lấy thông tin hoạt động xe tải theo danh sách ID.

Danh sách ID của hoạt động xe tải. Kết quả chứa thông tin hoạt động xe tải.

Tạo mới hoặc cập nhật thông tin hoạt động xe tải.

Thông tin hoạt động xe tải. Kết quả của thao tác.

Xóa thông tin hoạt động xe tải.

Thông tin hoạt động xe tải. Kết quả của thao tác.

Nhận xe (Check-in) với upload hình ảnh

Thông tin nhận xe Kết quả nhận xe

Trả xe (Check-out) với upload hình ảnh

Thông tin trả xe Kết quả trả xe

Đổ dầu cho xe với upload hình ảnh và thông tin ODO

Thông tin đổ dầu Kết quả đổ dầu

Lấy danh sách xe có thể nhận (chưa có người phụ trách)

ID đại lý Danh sách xe có thể nhận

Lấy xe hiện tại của người dùng

ID người dùng Thông tin xe hiện tại

Triển khai dịch vụ quản lý hoạt động xe tải.

Khởi tạo một thể hiện của .

Đối tượng IRepository của Truck. Đối tượng IRepository của TruckActivity. Đối tượng IRepository của TruckAsset. Đối tượng IRepository của TruckSpecAttribute. Đối tượng IRepository của TruckMaintAttribute. Đối tượng IRepository của TruckMaintenance. Đối tượng IRepository của TruckSpecification.

Lấy thông tin hoạt động xe tải theo danh sách ID.

Danh sách ID của hoạt động xe tải. Kết quả chứa thông tin hoạt động xe tải.

Tạo mới hoặc cập nhật thông tin hoạt động xe tải.

Thông tin hoạt động xe tải. Kết quả của thao tác.

Xóa thông tin hoạt động xe tải.

Thông tin hoạt động xe tải. Kết quả của thao tác.

Kiểm tra xem người dùng có đang phụ trách xe nào không

ID người dùng Thông tin xe đang phụ trách (nếu có)

Xử lý và lưu nhiều file media cùng lúc

Danh sách file media Danh sách kết quả xử lý

Giao diện cho dịch vụ quản lý tài sản xe tải.

Lấy thông tin tài sản xe tải theo danh sách ID.

Danh sách ID của tài sản xe tải. Kết quả chứa thông tin tài sản xe tải.

Tạo mới hoặc cập nhật thông tin tài sản xe tải.

Thông tin tài sản xe tải. Kết quả của thao tác.

Xóa thông tin tài sản xe tải.

Thông tin tài sản xe tải. Kết quả của thao tác.

Triển khai dịch vụ quản lý tài sản xe tải.

Khởi tạo một thể hiện của .

Đối tượng IRepository của Truck. Đối tượng IRepository của TruckActivity. Đối tượng IRepository của TruckAsset. Đối tượng IRepository của TruckSpecAttribute. Đối tượng IRepository của TruckMaintAttribute. Đối tượng IRepository của TruckMaintenance. Đối tượng IRepository của TruckSpecification.

Lấy thông tin tài sản xe tải theo danh sách ID.

Danh sách ID của tài sản xe tải. Kết quả chứa thông tin tài sản xe tải.

Tạo mới hoặc cập nhật thông tin tài sản xe tải.

Thông tin tài sản xe tải. Kết quả của thao tác.

Xóa thông tin tài sản xe tải.

Thông tin tài sản xe tải. Kết quả của thao tác.

Tra cứu cảnh báo tuổi thọ bộ phận do job nền sinh.

Tìm kiếm cảnh báo trong phạm vi chi nhánh của người dùng

Dịch vụ quản lý bộ phận lắp trên xe. Phạm vi chi nhánh ép ở tầng này, không tin client. Mọi phương thức đọc/ghi đều nhận do controller dựng: Founder thì không giới hạn, người dùng thường thì giới hạn theo chi nhánh của họ cùng các chi nhánh con, còn người không xác định được đơn vị thì không xem được gì (fail-closed). Không có giá trị nào mang nghĩa nước đôi — đây là trọng tâm IDOR của audit 2026-07-11.

Tìm kiếm bộ phận trên xe có phân trang, trong phạm vi chi nhánh cho phép.

Lấy toàn bộ bộ phận của một xe, trong phạm vi chi nhánh cho phép.

Lấy một bộ phận theo ID, trong phạm vi chi nhánh cho phép.

Gắn mới hoặc sửa bộ phận trên xe.

Khởi tạo hàng loạt bộ phận cho một xe từ danh mục đang bật.

Xoá mềm bộ phận. Từ chối khi bộ phận đã có lịch sử bảo dưỡng.

Xe có nằm trong phạm vi chi nhánh cho phép hay không. Dùng để chặn trước khi trả bất kỳ dữ liệu vận hành nào của xe (kể cả chỉ số ODO).

Khởi tạo dịch vụ bộ phận trên xe.

Truy vấn bộ phận đã ghép xe + loại và ĐÃ lọc theo phạm vi chi nhánh. Mọi phương thức đọc/ghi đều đi qua đây để không bỏ sót bộ lọc.

Lấy xe nếu nó nằm trong phạm vi cho phép, null nếu không.

Kiểm tra ràng buộc vị trí của bộ phận. Trả null khi hợp lệ.

Dựng DTO hiển thị từ entity kèm dữ liệu ghép.

Đọc số nguyên từ một giá trị filter động. Trả 0 khi thiếu hoặc không đọc được — nơi gọi hiểu 0 là "không lọc theo trường này".

Đọc giá trị logic từ một giá trị filter động. Trả null khi thiếu hoặc không đọc được.

Kết quả ghép bộ phận với xe và loại bộ phận.

Dịch vụ danh mục loại bộ phận xe. Danh mục dùng chung toàn công ty, không gác phạm vi chi nhánh.

Tìm kiếm loại bộ phận có phân trang.

Lấy danh sách loại bộ phận để đổ vào ô chọn.

Lấy loại bộ phận theo ID.

Tạo mới hoặc cập nhật loại bộ phận.

Xoá mềm loại bộ phận. Từ chối khi đang có bộ phận trên xe thuộc loại này.

Khởi tạo dịch vụ danh mục loại bộ phận.

Kiểm tra dữ liệu đầu vào. Trả null khi hợp lệ.

Tình trạng bảo dưỡng theo xe: màn đội xe, hồ sơ một xe, lịch sử một bộ phận.

Mọi truy vấn đều lọc theo ép ở tầng service — không tin tham số truckId hay agencyId client gửi lên (trọng tâm IDOR của audit 2026-07-11).

Danh sách xe kèm ODO hiện tại và số bộ phận đang có vấn đề

Hồ sơ tình trạng một xe; null khi xe nằm ngoài phạm vi

Lịch sử các lần bảo dưỡng đã chạm tới một bộ phận

Tình trạng xe mà một lái xe đang nhận; null khi người đó chưa nhận xe nào.

Không có tham số truckId — và sẽ không bao giờ có. Xe suy ra từ Truck.CurrentDriverId khớp với người dùng trong token; nhận id từ client là mở đường cho một tài xế xem xe của người khác (§3.4, trọng tâm IDOR của audit 2026-07-11).

Đắp ODO và số đếm cảnh báo cho một trang xe.

Một lượt truy vấn cho cả trang: ODO lấy bằng bản nhận nhiều xe của ITruckOdoService, bộ phận và loại bộ phận mỗi thứ một truy vấn. Gọi trong vòng lặp từng xe là N+1 truy vấn trên màn dùng hằng ngày.

Lần thay gần nhất của từng bộ phận — một truy vấn cho cả lưới

Cộng dồn số đếm và giữ mức nặng nhất của xe

Chạy job quét cảnh báo bảo dưỡng mỗi ngày một lần.

Theo mẫu PromotionBackgroundService: vòng lặp tự quản chu kỳ bằng Task.Delay, mỗi lượt một scope DI riêng, lỗi một lượt không giết cả dịch vụ. Quét lại nhiều lần vô hại — job chống trùng theo cặp (bộ phận, mức) và chỉ gửi thông báo cho cảnh báo chưa gửi.

Chu kỳ quét — mỗi ngày một lần theo §3.3 của plan

Chờ trước khi thử lại khi một lượt lỗi

Tệp đính kèm (hoá đơn, ảnh hiện trạng) của một lần bảo dưỡng — đóng nợ BD-4.

Đi qua bảng liên kết + bảng dùng chung, theo đúng mẫu FuelRefillMedia. Trường chuỗi TruckMaintenance.InvoiceUrl cũ được giữ để hiển thị bản ghi lịch sử, không ghi mới (plan §3.11). Phạm vi chi nhánh tính theo xe đang gắn với bản ghi bảo dưỡng, không theo tham số client gửi — cùng luật với TruckMaintCreateOrUpdate (nợ BD-11). Tải hoá đơn lên thì bật luôn HasInvoice của bản ghi để cột "có hoá đơn" ở lịch sử bộ phận (ComponentHistoryItem.HasInvoice) không nói dối; xoá hoá đơn cuối cùng thì hạ cờ nếu bản ghi cũng không còn InvoiceUrl cũ. Nhận hai loại tệp, phân nhánh theo nội dung file chứ không theo đuôi hay content-type client khai: ảnh đi đường ProcessImageAsync (convert WebP) như cũ, tệp bắt đầu bằng %PDF đi IDocumentService. PDF chỉ nhận cho và tối đa 10 MB mỗi tệp; tên file lưu xuống đĩa do server sinh, tên gốc người dùng chỉ giữ ở Media.Caption để hiển thị (plan đợt 2 §3.3).

Danh sách tệp của một lần bảo dưỡng trong phạm vi; rỗng khi ngoài phạm vi.

Tải một hoặc nhiều tệp lên và gắn vào lần bảo dưỡng.

Gỡ một tệp (xoá mềm dòng liên kết).

Trần dung lượng một tệp PDF (10 MB) — DocumentService không tự giới hạn, còn [RequestSizeLimit] ở controller chỉ chặn tổng cả request.

Đuôi tệp duy nhất chấp nhận cho nhánh tài liệu.

Chữ ký đầu tệp PDF: %PDF.

Khởi tạo dịch vụ tệp đính kèm bảo dưỡng.

Tệp có phải PDF không — đọc 4 byte đầu, không tin phần mở rộng hay content-type client khai.

Luật nhận PDF (§3.3): chỉ dành cho hoá đơn, phải có đuôi .pdf, tối đa 10 MB. Trả về lý do từ chối, hoặc null nếu hợp lệ.

Lưu PDF qua với tên tệp do server sinh.

DocumentService.GenerateFileName ghép tên gốc người dùng vào đường dẫn lưu; hoá đơn nằm sau URL media không xác thực nên tên phải khó đoán và không do người dùng đặt. Vì vậy nội dung được nạp lại vào một mang tên server sinh trước khi đưa xuống. Nạp vào bộ nhớ an toàn vì luật 10 MB đã chặn trước đó.

Tên tệp an toàn để hiển thị/ghi chú: bỏ mọi thành phần thư mục và ký tự điều khiển, cắt ngắn.

Bỏ luôn ký tự định dạng Unicode (nhóm Cf, ví dụ U+202E đảo chiều đọc) — chúng vô hình nhưng đủ để một tên tệp trông như bao-gia.pdf trong khi thật ra là tên khác; hoá đơn là chứng từ kế toán nên tên hiển thị không được đánh lừa người xem.

Tên hiển thị của một tệp PDF đã lưu: tên gốc ghi ở Media.Caption, không có thì lấy tên trên đĩa.

Tên gốc quá dài bị cắt còn 200 ký tự nên có thể mất đuôi .pdf; khi đó hàm rơi về tên tệp server sinh — xấu nhưng vẫn là tên thật của tệp, hơn là hiện một chuỗi cụt.

Thông báo lỗi trả về client: chỉ chuyển tiếp message của tầng media khi đó là lỗi luật. Lỗi hệ thống mang theo ex.Message (đường dẫn ổ đĩa, chuỗi kết nối...) nên phải nuốt (bẫy BD-24).

Nạp bản ghi bảo dưỡng nếu xe đang gắn với nó nằm trong phạm vi; null nếu không. Luật phạm vi nằm ở — một bản duy nhất cho cả miền.

Mô tả một cảnh báo đủ để dựng nội dung thông báo, không cần tra thêm DB.

Xe

Biển số

Chi nhánh quản lý xe tại thời điểm gửi

Lái xe đang nhận xe; 0 = xe chưa có ai nhận

Tên bộ phận kèm vị trí, đã ghép sẵn để hiển thị

Mức cảnh báo

Phần "còn bao nhiêu" hoặc "quá bao nhiêu", đã diễn giải sang tiếng Việt

Gửi thông báo cảnh báo bảo dưỡng cho đúng người: lái xe đang nhận xe và quản lý của chi nhánh đang quản lý xe.

Không dùng SendToRoleAsync: hàm đó gửi cho mọi user có role trên toàn hệ thống, tức quản lý chi nhánh này nhận cảnh báo xe của chi nhánh khác (Q8 đã chốt lọc phạm vi trước).

Danh sách người nhận thông báo cho một xe, đã lọc theo phạm vi chi nhánh của xe

Gửi thông báo cho một cảnh báo; trả về số người đã gửi

Role quyết định ai là "quản lý" nhận cảnh báo (Q8)

User có role quản lý cảnh báo và thuộc chi nhánh quản lý xe (hoặc chi nhánh cha).

Role trong hệ thống này đến từ hai nguồn: gán trực tiếp qua UserRole và gán theo nhóm quyền qua Permission.PermissionRoles — IUserRoleResolver gộp cả hai. Chiều ngược lại chưa có hàm dùng chung nào gộp đủ: SendToRoleAsync chỉ đọc UserRole, còn SugUser chỉ đọc PermissionRoles. Lấy thiếu một nguồn là im lặng bỏ sót đúng người cần biết xe sắp hỏng, nên ở đây hợp cả hai.

Tên khoá AppConfig của phân hệ bảo dưỡng xe tải — seed bằng migration M202608151003, không hardcode giá trị ở nơi khác.

Công tắc gửi thông báo cảnh báo bảo dưỡng (plan §3.3.5, mặc định TẮT)

Ngưỡng cảnh báo trước theo số km còn lại (Q3: 1.000 km)

Ngưỡng cảnh báo trước theo số ngày còn lại (Q3: 15 ngày)

Số ngày không có ODO mới thì coi dữ liệu km của xe là quá cũ (Q4: 30 ngày)

Bộ ngưỡng cảnh báo toàn cục, đọc một lần rồi dùng cho cả lượt quét.

Job quét vài trăm bộ phận mỗi lượt; đọc AppConfig cho từng bộ phận là ba lần tra cache nhân số bộ phận. Gói thành một bản ghi để lấy một lần ở đầu lượt.

Ngưỡng cảnh báo trước theo km — cấp toàn cục, loại bộ phận có thể ghi đè

Ngưỡng cảnh báo trước theo ngày — cấp toàn cục, loại bộ phận có thể ghi đè

Số ngày sau đó coi chuỗi ODO của xe là quá cũ để tính km

Đọc 4 khoá cấu hình của phân hệ bảo dưỡng và diễn giải chúng thành bool/số.

Tách riêng để test được engine mà không dựng cả job, và để chỉ có một nơi diễn giải chuỗi cấu hình — mỗi nơi tự parse một kiểu là mỗi nơi sai một kiểu (bài học phân hệ KPI).

Có được phép gửi thông báo cảnh báo hay không.

Fail-closed: khoá thiếu, rỗng hay ghi sai đều trả false. Nhầm về phía "không gửi" chỉ làm job chạy chế độ ghi nhận (đúng bước 4 của §5.2); nhầm về phía "gửi" là hàng loạt lái xe nhận thông báo trước khi ai kịp đối chiếu danh sách cảnh báo.

Bộ ngưỡng toàn cục; khoá thiếu/sai rơi về mặc định đã chốt ở Q3/Q4

Ngưỡng km mặc định khi cấu hình thiếu hoặc ghi sai (Q3)

Ngưỡng ngày mặc định khi cấu hình thiếu hoặc ghi sai (Q3)

Số ngày ODO quá cũ mặc định khi cấu hình thiếu hoặc ghi sai (Q4)

Đọc một khoá số nguyên dương; thiếu, sai định dạng hay ≤ 0 đều rơi về mặc định.

Ép : máy chủ chạy văn hoá vi-VN, để int.Parse tự đoán là mở đường cho dấu phân cách nghìn diễn giải khác nhau giữa máy.

Chỉ số ODO hiện tại của một xe kèm thời điểm ghi nhận và nguồn lấy được.

Chỉ số ODO (km). Null khi xe chưa có dữ liệu ODO nào.

Thời điểm ghi nhận chỉ số này. Null khi không có dữ liệu.

Nguồn lấy được: FuelRefill / TruckActivity / LastRefillOdo / None

Số ngày kể từ lần ghi nhận gần nhất tới thời điểm đối chiếu. Null khi không có dữ liệu.

Có dữ liệu ODO hay không

Nguồn sự thật duy nhất về chỉ số ODO hiện tại của xe.

Lấy chỉ số ODO hiện tại của một xe kèm thời điểm ghi nhận.

ID xe Mốc thời gian đối chiếu để tính tuổi dữ liệu (mặc định: hiện tại)

Lấy ODO hiện tại cho nhiều xe một lượt — dùng cho màn tình trạng đội xe và job quét, tránh N+1 truy vấn.

Danh sách ID xe Mốc thời gian đối chiếu để tính tuổi dữ liệu (mặc định: hiện tại)

Triển khai nguồn ODO chuẩn. Luật chống nhiễu — thiết kế theo số đo thật ngày 2026-08-15 (plan §5.1), không đoán: Bỏ phiếu đổ dầu đã bị từ chối (FuelRefillStatus.Rejected). Đo được: 3 trong 5 cặp ODO giảm ngược của toàn bộ chuỗi là do phiếu nhập sai đã bị người duyệt bác; lọc chúng đi thì tỷ lệ nhiễu còn 0,14%. Lấy bản ghi MỚI NHẤT theo thời gian, tuyệt đối không lấy MAX(Odo). Xe 29H78282 có phiếu ODO 97.772 (đã bị từ chối) rồi đồng hồ được thay và chuỗi thật bắt đầu lại từ 275. Lấy max cho ra 97.772 — sai gấp 15 lần. Đồng hồ ODO bị thay là chuyện có thật nên "ODO chỉ tăng" không phải bất biến đúng. TruckActivity.CurrentOdo chỉ là nguồn dự phòng: toàn bộ 658 bản ghi check-in/check-out trên dữ liệu thật đều có ODO = 0 (trường có nhưng chưa bao giờ được nhập). Vẫn đọc để phòng khi luồng nhập được bật, nhưng lọc > 0. Truck.LastRefillOdo là nguồn cuối cùng, không dùng để đối chiếu đúng-sai: đo được lệch tới 21.140 km so với phiếu đổ dầu mới nhất, và 5 xe có phiếu nhưng trường này NULL — nó bị cập nhật thiếu nhịp. Chỉ dùng khi xe không có phiếu đổ dầu và không có hoạt động nào. Dịch vụ này chỉ đọc — không bao giờ UPDATE TruckActivity, FuelRefills hay Trucks (plan §3.11: chuỗi ODO lịch sử là dữ liệu chỉ đọc với phân hệ bảo dưỡng).

Khởi tạo dịch vụ ODO.

Giao diện cho dịch vụ quản lý xe tải.

Tạo mới hoặc cập nhật thông tin xe tải.

Thông tin xe tải. Kết quả của thao tác.

Lấy danh sách media (ảnh đăng ký, đăng kiểm) của xe tải.

ID xe tải. Danh sách media items.

Xóa thông tin xe tải.

ID xe tải cần xóa. Kết quả của thao tác.

Lấy thông tin xe tải theo danh sách ID.

Danh sách ID của xe tải. Kết quả chứa thông tin xe tải.

Lấy thông tin xe tải theo ID của đại lý.

ID của đại lý. Kết quả chứa thông tin xe tải.

Lấy thông tin xe tải theo danh sách ID đơn vị (bao gồm chi nhánh con).

Danh sách ID đơn vị. Kết quả chứa thông tin xe tải.

Tìm kiếm thông tin xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm xe tải.

Lấy lịch sử giao nhận xe tải theo ID xe

ID xe tải Danh sách lịch sử giao nhận xe với thông tin ODO, ghi chú và ảnh

Cập nhật giá trị ODO đổ dầu gần nhất của xe tải

ID xe tải Giá trị ODO Kết quả cập nhật

Lấy thông tin xe tải theo ID.

ID của xe tải. Thông tin xe tải kèm danh sách ảnh.

Lấy thông số kỹ thuật của xe tải theo danh sách ID.

Danh sách ID của thông số kỹ thuật. Kết quả chứa thông số kỹ thuật của xe tải.

Tạo mới hoặc cập nhật thông số kỹ thuật của xe tải.

Thông số kỹ thuật của xe tải. Kết quả của thao tác.

Xóa thông số kỹ thuật của xe tải.

Thông số kỹ thuật của xe tải. Kết quả của thao tác.

Tìm kiếm thông số kỹ thuật của xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm thông số kỹ thuật của xe tải.

Lấy tất cả thông số kỹ thuật của xe tải.

Thông số kỹ thuật của xe tải. Kết quả chứa tất cả thông số kỹ thuật của xe tải.

Lấy tất cả thuộc tính kỹ thuật của xe tải.

Kết quả chứa tất cả thuộc tính kỹ thuật của xe tải.

Tìm kiếm thuộc tính kỹ thuật của xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm thuộc tính kỹ thuật của xe tải.

Tạo mới hoặc cập nhật thuộc tính kỹ thuật của xe tải.

Thuộc tính kỹ thuật của xe tải. Kết quả của thao tác.

Xóa thuộc tính kỹ thuật của xe tải.

Thuộc tính kỹ thuật của xe tải. Kết quả của thao tác.

Lấy thông tin bảo dưỡng xe tải theo danh sách ID.

Danh sách ID của thông tin bảo dưỡng. Kết quả chứa thông tin bảo dưỡng xe tải. Lọc theo phạm vi chi nhánh của xe đang gắn với bản ghi (nợ BD-12) — cùng luật với TruckMaintCreateOrUpdate.

Tìm kiếm thông tin bảo dưỡng xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm thông tin bảo dưỡng xe tải. Lọc theo phạm vi chi nhánh của xe đang gắn với bản ghi (nợ BD-12).

Tạo mới hoặc cập nhật thông tin bảo dưỡng xe tải.

Thông tin bảo dưỡng xe tải. Kết quả của thao tác.

Xóa thông tin bảo dưỡng xe tải.

Thông tin bảo dưỡng xe tải. Kết quả của thao tác.

Lấy tất cả thuộc tính bảo dưỡng của xe tải.

Kết quả chứa tất cả thuộc tính bảo dưỡng của xe tải.

Tìm kiếm thuộc tính bảo dưỡng của xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm thuộc tính bảo dưỡng của xe tải.

Tạo mới hoặc cập nhật thuộc tính bảo dưỡng của xe tải.

Thuộc tính bảo dưỡng của xe tải. Kết quả của thao tác.

Xóa thuộc tính bảo dưỡng của xe tải.

Thuộc tính bảo dưỡng của xe tải. Kết quả của thao tác.

Lấy tất cả thông tin liên kết bảo dưỡng của xe tải.

Thông tin liên kết bảo dưỡng của xe tải. Kết quả chứa tất cả thông tin liên kết bảo dưỡng của xe tải. Gác phạm vi chi nhánh theo xe của bản ghi bảo dưỡng (nợ BD-12) — dòng công việc là một phần của bản ghi, ai không xem được bản ghi thì cũng không xem được dòng.

Gợi ý xe theo từ khóa (biển số, thương hiệu, model)

Triển khai dịch vụ quản lý xe tải.

Khởi tạo

Tìm kiếm thông tin xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm xe tải.

Lấy thông tin xe tải theo danh sách ID.

Danh sách ID của xe tải. Kết quả chứa thông tin xe tải.

Lấy thông tin xe tải theo ID của đại lý.

ID của đại lý. Kết quả chứa thông tin xe tải.

Lấy thông tin xe tải theo danh sách ID đơn vị (bao gồm chi nhánh con).

Danh sách ID đơn vị. Kết quả chứa thông tin xe tải.

Tạo mới hoặc cập nhật thông tin xe tải.

Thông tin xe tải. Kết quả của thao tác.

Xử lý upload/cập nhật media cho xe tải (ảnh đăng ký, đăng kiểm)

Xóa thông tin xe tải.

ID xe tải cần xóa. Kết quả của thao tác.

Lấy thông tin xe tải theo ID.

ID của xe tải. Thông tin xe tải kèm danh sách ảnh.

Lấy danh sách media (ảnh đăng ký, đăng kiểm) của xe tải

Tìm kiếm thông số kỹ thuật của xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm thông số kỹ thuật của xe tải.

Lấy tất cả thông số kỹ thuật của xe tải.

Thông số kỹ thuật của xe tải. Kết quả chứa tất cả thông số kỹ thuật của xe tải.

Lấy thông số kỹ thuật của xe tải theo danh sách ID.

Danh sách ID của thông số kỹ thuật. Kết quả chứa thông số kỹ thuật của xe tải.

Tạo mới hoặc cập nhật thông số kỹ thuật của xe tải.

Thông số kỹ thuật của xe tải. Kết quả của thao tác.

Xóa thông số kỹ thuật của xe tải.

Thông số kỹ thuật của xe tải. Kết quả của thao tác.

Lấy tất cả thuộc tính kỹ thuật của xe tải.

Kết quả chứa tất cả thuộc tính kỹ thuật của xe tải.

Tìm kiếm thuộc tính kỹ thuật của xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm thuộc tính kỹ thuật của xe tải.

Tạo mới hoặc cập nhật thuộc tính kỹ thuật của xe tải.

Thuộc tính kỹ thuật của xe tải. Kết quả của thao tác.

Xóa thuộc tính kỹ thuật của xe tải.

Thuộc tính kỹ thuật của xe tải. Kết quả của thao tác.

Tìm kiếm thông tin bảo dưỡng xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm thông tin bảo dưỡng xe tải.

Lấy thông tin bảo dưỡng xe tải theo danh sách ID.

Danh sách ID của thông tin bảo dưỡng. Kết quả chứa thông tin bảo dưỡng xe tải.

Tạo mới hoặc cập nhật thông tin bảo dưỡng xe tải.

Thông tin bảo dưỡng xe tải. Kết quả của thao tác.

Mỗi dòng công việc phải trỏ tới ít nhất một thứ: hạng mục theo danh mục cũ hoặc bộ phận trên xe. Hạng mục gửi 0 được coi là null (client cũ gửi 0 khi bỏ trống) — trước GĐ E giá trị 0 đi thẳng xuống FK và nổ DbUpdateException, còn production không có hạng mục nào để mà chọn.

Xe có nằm trong phạm vi chi nhánh của người gọi hay không.

Cùng luật với TruckComponentService.IsTruckInScope: Unrestricted (Founder) thấy tất, None không thấy gì, còn lại lọc theo cây chi nhánh. Đặt ở đây vì luồng bảo dưỡng cũ nằm trong TruckService, không đi qua service bộ phận.

Chuỗi có an toàn để hiển thị thành liên kết bấm được không: rỗng (xoá) hoặc http/https.

Trường InvoiceUrl vốn là ô nhập tự do của màn cũ và nay được render thành <a href> ở hồ sơ xe. Frontend đã lọc scheme khi hiển thị; chốt chặn thứ hai nằm đây để dữ liệu bẩn không vào được DB ngay từ đầu.

Bản ghi bảo dưỡng có nằm trong phạm vi chi nhánh của người gọi không — xét theo XE đang gắn với bản ghi.

Mọi bộ phận được nhắc tới trong lần lưu này phải thuộc đúng chiếc xe của bản ghi bảo dưỡng.

TruckComponentId là số nguyên client gửi lên và id bộ phận tăng dần nên đoán được. Không có kiểm tra này thì một dòng Replace trỏ sang bộ phận xe chi nhánh khác sẽ ghi đè InstalledDate/InstalledOdo của bộ phận đó và đóng sạch cảnh báo đang mở của nó — tức tắt cảnh báo an toàn của một chiếc xe mình không được phép đụng tới. Kiểm cả dòng cũ đang có: bản ghi bảo dưỡng bị đổi sang xe khác thì liên kết cũ cũng thành liên kết xuyên xe. Trả null khi mọi thứ hợp lệ.

Đồng bộ danh sách dòng công việc của một lần bảo dưỡng theo từng dòng.

Đây là chỗ đóng nợ BD-8. Luồng cũ xoá mềm toàn bộ TruckMaintLink rồi chèn lại từ payload; payload màn cũ không có TruckComponentId/ActionType/ LineCost nên một lần bấm Lưu vô hại làm thủng lịch sử tuổi thọ của bộ phận. Luật mới: Khớp dòng theo Id; màn cũ không gửi Id nên khớp tạm theo hạng mục để không nhân đôi dòng sau mỗi lần Lưu. Ba trường mới chỉ ghi đè khi payload có giá trị — null là "không nhắc tới". Dòng đang có bộ phận mà payload không nhắc tới thì giữ nguyên; muốn xoá phải nói tên nó trong DeletedTruckMaintLinkIds.

Xóa thông tin bảo dưỡng xe tải.

Thông tin bảo dưỡng xe tải. Kết quả của thao tác.

Lấy tất cả thông tin liên kết bảo dưỡng của xe tải.

Thông tin liên kết bảo dưỡng của xe tải. Kết quả chứa tất cả thông tin liên kết bảo dưỡng của xe tải.

Lấy tất cả thuộc tính bảo dưỡng của xe tải.

Kết quả chứa tất cả thuộc tính bảo dưỡng của xe tải.

Tìm kiếm thuộc tính bảo dưỡng của xe tải.

Thông số tìm kiếm. Kết quả tìm kiếm thuộc tính bảo dưỡng của xe tải.

Tạo mới hoặc cập nhật thuộc tính bảo dưỡng của xe tải.

Thuộc tính bảo dưỡng của xe tải. Kết quả của thao tác.

Xóa thuộc tính bảo dưỡng của xe tải.

Thuộc tính bảo dưỡng của xe tải. Kết quả của thao tác.

Lấy lịch sử giao nhận xe tải theo ID xe

ID của xe tải Danh sách lịch sử giao nhận xe

Lấy danh sách media cho một activity

ID của activity Danh sách media items

Cập nhật giá trị ODO đổ dầu gần nhất của xe tải

ID xe tải Giá trị ODO Kết quả cập nhật

Gateway giọng đọc dẫn đường: câu → khoá cache → file trên đĩa; thiếu thì gọi nguồn tổng hợp một lần rồi giữ mãi (plan §3.5.6). Không đụng database.

Bảo đảm mọi câu trong có âm thanh; trả bytes cho câu app chưa có.

Các câu cần đọc + hash app đã có. Người gọi — để tính trần ký tự câu mới theo ngày. Huỷ khi app ngắt kết nối (lượt tổng hợp đang chạy vẫn chạy nốt và vào cache).

Cài đặt . Đăng ký SINGLETON — giữ trạng thái dùng chung.

Trạng thái trong bộ nhớ (lượt đang bay, trần ngày, tạm ngắt khi hết token) mất khi khởi động lại tiến trình — chấp nhận: trần ngày là chốt chặn chống đốt token (Cloud) / đốt CPU (tự host), không phải sổ kế toán. Câu Pending của nguồn tự host được hoàn trần ngay (không Ok) nên hỏi lại nhiều lần không tiêu hạn mức.

Hết token / khoá sai thì ngừng gọi VieNeu chừng này rồi mới thử lại.

Hết hạn mức ngày/tuần có giờ đặt lại: ngừng tới giờ đó nhưng không quá chừng này.

429 không kèm Retry-After cũng không kèm giờ đặt lại (lớp chắn theo IP của VieNeu) thì chờ chừng này. Ngắn hơn tổng hai lượt thử lại của app (4 s + 12 s).

Múi giờ tính "ngày" của trần ký tự.

Thư mục cache: Tts:CacheDir, trống thì {ContentRoot}/App_Data/tts-cache. Tiến trình PHẢI có quyền ghi — trên IIS app pool identity thường chỉ đọc được thư mục site: khi đó mọi câu có âm thanh về đều thành Unavailable "Không lưu được file âm thanh" trong khi câu Pending vẫn Success → app lúc báo lỗi lúc không (cắn thật production 2026-09-28, thư mục App_Data không bao giờ xuất hiện). GET api/Tts/Status kiểm quyền ghi này.

Đường dẫn file âm thanh của một khoá — chia thư mục theo 2 ký tự đầu. Đuôi file theo của nguồn (cả hai nguồn hiện là mp3).

Mã lỗi cấp lượt gọi: lỗi nặng nhất trong các câu hỏng. Câu bị từ chối riêng lẻ (Rejected) hay đang chờ sinh nền ở nguồn tự host (Pending) KHÔNG làm cả lượt thành lỗi — những câu còn lại vẫn đọc được, app bỏ câu thiếu im lặng.

Luật chữ của gateway: chuẩn hoá, kiểm, băm, tính ký tự.

VieNeu tính tối thiểu chừng này ký tự mỗi lần gọi (đo thật 2026-09-23).

Ký tự cấm ngoài ký tự điều khiển: ngoặc nhọn/vuông/nhọn kép — VieNeu có cú pháp chèn cảm xúc trong câu, và câu chỉ dẫn thật (Valhalla + app) không bao giờ chứa chúng.

NFC, gộp mọi khoảng trắng liền nhau thành một dấu cách, bỏ hai đầu.

Lỗi của câu đã chuẩn hoá, null khi hợp lệ.

Nhận diện GIỌNG đang dùng (12 ký tự hex của sha256 khoá nguồn) — app thấy đổi thì bỏ chỉ mục câu → file cũ, không trộn hai giọng trong một chuyến. Không lộ khoá API.

sha256(câu \n khoá nguồn), hex thường.

Chuỗi có đúng dạng khoá cache không.

Số ký tự VieNeu tính tiền cho một câu.

Chọn nguồn tổng hợp cho MỖI lượt gọi — để đổi nguồn (Cloud ↔ tự host), địa chỉ sidecar hay khoá lúc đang chạy mà không khởi động lại API (đợt tự host 2026-09-28, memory project-tts-tu-host).

Engine đang có hiệu lực. Không ném lỗi — đọc cấu hình hỏng thì rơi về appsettings.

Provider cố định một engine — cho test và cho chỗ không có AppConfig.

Provider cố định một engine — cho test và cho chỗ không có AppConfig.

Khoá AppConfig (màn Cấu hình hệ thống, bảng AppConfig) của giọng đọc dẫn đường. Giá trị trống thì rơi về section Tts của appsettings / biến môi trường (). Seed bằng migration ChenCauHinhGiongDocTuHost.

VieNeuCloud | VieNeuSelfHost.

Gốc URL sidecar, ví dụ http://192.168.1.50:8011.

Khoá Bearer của sidecar (SIDECAR_API_KEY).

Giọng sidecar đang dùng — thành phần khoá cache.

Tag VieNeu-TTS đang ghim ở sidecar — thành phần khoá cache.

Đủ năm khoá, theo thứ tự hiển thị.

Đọc năm khoá từ AppConfig (Lada.Framework cache 1 giờ và làm mới ngay khi sửa qua màn quản trị — AppConfigManagementService.ReloadFrameworkCacheAsync), rơi về khi khoá trống hoặc DB lỗi. Giữ engine đã dựng cho tới khi giá trị đổi; đọc lại tối đa mỗi nên đổi cấu hình có hiệu lực trong vòng nửa phút.

Singleton (như ) nhưng IAppConfigService của Framework là scoped (cần DbContext) → mở scope riêng cho mỗi lần đọc. Khoá Cloud (Tts:VieNeu:ApiKey) vẫn đọc từ appsettings/biến môi trường như trước — chỉ phần tự host và công tắc nguồn nằm ở AppConfig.

Đọc lại AppConfig tối đa mỗi chừng này.

Tên nguồn + cấu hình tự host đang có hiệu lực (AppConfig đè appsettings). Không ném lỗi.

Cấu hình gateway giọng đọc dẫn đường (section Tts). Đợt dẫn đường DriverApp GĐ D2 (plan docs/plan-dan-duong-driverapp.md §3.5.6) và đợt tự host 2026-09-28 (memory project-tts-tu-host).

Hai nguồn tổng hợp, chọn bằng : VieNeuCloud (api.vieneu.io, cần Tts:VieNeu:ApiKey) hoặc VieNeuSelfHost (sidecar trên ladamap, cần Tts:SelfHost:BaseUrl + ApiKey). Thiếu khoá thì endpoint trả 503 "chưa cấu hình" chứ API vẫn khởi động — app coi đó là lỗi giọng đọc và dẫn đường bằng chữ. Khoá chỉ đặt ở user-secrets (dev) hoặc cấu hình server (production), KHÔNG vào repo: dotnet user-secrets set "Tts:SelfHost:ApiKey" "<khoá>" --project Ladaer.BackEnd/Ladaer.BackEnd.

Tên section trong cấu hình.

Giá trị : VieNeu Cloud API.

Giá trị : sidecar VieNeu-TTS tự host trên ladamap.

Nguồn tổng hợp đang dùng: (mặc định) hay . Đổi nguồn là đổi khoá cache và VoiceKey → app tự bỏ chỉ mục giọng cũ, không trộn hai giọng. Khoá AppConfig Tts.Engine (màn Cấu hình hệ thống) ĐÈ giá trị này khi không trống — xem ; tương tự cho bốn khoá Tts.SelfHost.*.

Thư mục cache file âm thanh. Để trống = {ContentRoot}/App_Data/tts-cache. Cache là dữ liệu công cộng (câu chỉ dẫn theo tên đường), xoá đi chỉ tốn token/CPU tổng hợp lại.

Số câu tối đa mỗi lần gọi (plan §3.11).

Số ký tự tối đa mỗi câu (plan §3.11). Câu dài nhất đo được ở D1/D2 là 106.

Trần ký tự TÍNH TIỀN của câu mới (chưa có trong cache) mỗi người dùng mỗi ngày. Câu ngắn hơn 50 ký tự vẫn tính 50 — đúng cách VieNeu tính. 20.000 ≈ 400 câu mới/ngày, gấp nhiều lần một chuyến 50 điểm (~150 câu, phần lớn trúng cache sau vài ngày). Với nguồn tự host đây là chốt chống lạm dụng CPU; câu Pending được hoàn trần ngay.

Trần ký tự tính tiền của câu mới toàn server mỗi ngày — chốt chặn cuối để một lỗi app hay một tài khoản bị lộ không đốt hết gói token trong vài phút. 300.000 ký tự ≈ 1,17 triệu token v4 ≈ 6.000 câu mới.

Số lần gọi nguồn chạy đồng thời toàn server, áp cho nguồn đang chọn. Cloud đo Việc 0 D2: 4 luồng v4 ra ~165 lượt/phút, 1,2 s/câu (p50). Sidecar tự host trả lời tức thì (cache hoặc pending) nên 4 cũng đủ; TTS thật chạy tuần tự ở worker của sidecar, không phụ thuộc số này.

Trần lượt gọi nguồn mỗi phút, tự giới hạn phía mình: Cloud ghi 300/phút/khoá cộng một lớp chắn theo IP không công bố ngưỡng → lấy 80 %. Vượt thì lượt gọi xếp hàng tối đa rồi báo RateLimited (không gọi ra ngoài).

Chờ hàng đợi nhịp gọi tối đa chừng này giây.

Cấu hình VieNeu Cloud.

Cấu hình sidecar tự host.

Cấu hình VieNeu Cloud API (https://docs.vieneu.io).

Khoá API vn_sk_… (gói trả phí) hoặc vn_test_… (thử 7 ngày).

Gốc API.

v3 (×1,5 token/ký tự) hoặc v4 (×3). Chọn ở Việc 0 GĐ D2.

Id giọng theo GET /voices?engine= — id khác nhau giữa v3 và v4.

Định dạng trả về. mp3 vì app còn chạy iOS 15/16 — AVPlayer ở đó không mở được Ogg Opus (opus nhỏ hơn 2,5 lần nhưng không phát được trên một phần máy lái xe).

Trần thời gian một lần tổng hợp (plan §3.5.10: timeout 10 s).

Cấu hình sidecar VieNeu-TTS tự host trên ladamap (Scripts/tts-vps/sidecar/vieneu_gateway.py, cài bằng 05-cai-sidecar.sh). Sidecar giữ cache, tách/ghép câu, chuyển mp3 và xếp hàng sinh nền; engine phía này chỉ là client mỏng.

Gốc URL sidecar = SIDECAR_BIND trong /opt/vieneu/sidecar.env, ví dụ http://192.168.1.50:8011. Trống = chưa cấu hình.

Khoá Bearer của sidecar (SIDECAR_API_KEY). Production: biến môi trường Tts__SelfHost__ApiKey.

Giọng sidecar đang dùng (VOICE của nó) — ở đây chỉ để dựng khoá cache và VoiceKey; sidecar tự chọn giọng khi gọi TTS. Đổi giọng ở sidecar thì đổi cả đây để cache cũ hai phía bị bỏ. Chốt 2026-09-28 (chủ dự án nghe thử trên bản tự host): một giọng duy nhất Trúc Ly — bản v3 Turbo mở không có "Ban Mai" của Cloud v4.

Tag repo VieNeu-TTS đang ghim ở sidecar (MODEL_VERSION) — thành phần khoá cache.

Trần thời gian một lần gọi sidecar. Nó trả ngay (cache/pending); ghép ffmpeg vài trăm ms.

Ảnh chụp trạng thái gateway giọng đọc cho người vận hành (GET api/Tts/Status) — xem . Mọi bước đều bắt lỗi và ghi vào kết quả, không ném ra ngoài.

Người gọi — lượt tổng hợp thử tính vào trần ký tự của người này (50 ký tự).

Câu thử: đoạn cố định sidecar sinh sẵn và Cloud tổng hợp được ngay — bình thường phải Ready.

Tạo thư mục, ghi rồi xoá một file thử; đếm file mp3 hiện có (trần 100.000 để không quét quá lâu).

AppConfig không trống thì đè appsettings — cùng luật với provider.

Che khoá bí mật: chỉ còn độ dài và 4 ký tự đầu — đủ để nhận ra dán nhầm (ngoặc kép → dài 66).

Một nguồn tổng hợp giọng. Hai cài đặt: (api.vieneu.io) và (sidecar tự host trên ladamap, đợt 2026-09-28 — memory project-tts-tu-host); chọn bằng Tts:Engine ở DependencyRegister để chuyển qua lại trong giai đoạn thử. Cache, trần ký tự, nhịp gọi nằm ở , dùng chung.

Đã có khoá API. false thì gateway trả "chưa cấu hình" mà không gọi ra ngoài.

Phần khoá cache phụ thuộc nguồn: mọi thứ làm đổi âm thanh ra (nhà cung cấp, engine, giọng, định dạng). Đổi giọng trong cấu hình là mọi câu có khoá mới — cache cũ tự bị bỏ qua.

Đuôi file âm thanh lưu cache, không có dấu chấm.

Tổng hợp một câu. Không ném lỗi — mọi thất bại trả về trong kết quả.

Vì sao một lần tổng hợp thất bại.

Nguồn từ chối CÂU này (400: câu không hợp lệ, giọng không tồn tại…).

Khoá sai/bị thu hồi (401) — lỗi cấu hình server.

Hết token, gói hết hạn, hoặc gói không được dùng engine này (403).

Vượt giới hạn tần suất hoặc hạn mức ngày/tuần (429).

Nguồn không phục vụ được (5xx, lỗi mạng, trả rỗng).

Quá thời gian chờ.

Nguồn tự host chưa có câu này và đã xếp hàng sinh nền (sidecar trả 202; RTF ≈ 2 nên không chờ). KHÔNG phải lỗi: gateway trả Ready=false, ErrorCode=Pending cho riêng câu, lượt gọi vẫn Success, không tạm ngắt nguồn, hoàn trần ký tự. App bỏ câu im lặng và tự hỏi lại lượt sau.

Kết quả một lần tổng hợp.

Bytes âm thanh khi thành công.

Lý do thất bại; null khi thành công.

Mô tả ngắn để ghi log — không chứa khoá.

Nguồn yêu cầu chờ bao lâu rồi mới thử lại (429), nếu có.

Thành công.

Tạo kết quả thành công.

Tạo kết quả thất bại.

Gọi POST /audio/speech của VieNeu Cloud (OpenAI-compatible, trả thẳng bytes âm thanh).

Đo thật 2026-09-23 (Việc 0 GĐ D2, plan §5.4): tính tiền đúng max(50, số ký tự) × hệ số engine × 1,3; aiRefine mặc định TẮT ở API công khai (câu đọc nguyên văn, không chuẩn hoá phát âm, không phụ phí) — nên câu phải chuẩn hoá sẵn ở app (plan §3.5.5). Route này trả lỗi theo phong bì OpenAI ({error:{message,type,code}}), KHÔNG mang mã GRANT_TOKENS_EXHAUSTED như các route /v1/tts — nên dựa vào mã HTTP, cộng giờ đặt lại trong câu lỗi 429 của hạn mức ngày/tuần (khoá thử: 50.000 token/ngày, đặt lại 00:00 giờ VN — cắn thật ở Việc 0 D2, xem ).

Tên HttpClient đăng ký ở DependencyRegister.

Mã HTTP → loại thất bại (hợp đồng lỗi của /audio/speech, docs.vieneu.io).

Giờ đặt lại hạn mức trong câu lỗi 429 của VieNeu, null khi không có. Nguyên văn đo được: "Daily token limit reached (50,000 tokens/day). Resets at 2026-09-23T17:00:00.000Z."

Đọc error.message (+ code) của phong bì OpenAI, cắt ngắn để ghi log.

Gọi sidecar VieNeu-TTS tự host trên ladamap (Scripts/tts-vps/sidecar/vieneu_gateway.py): POST {BaseUrl}/v1/clip {text} → 200 audio/mpeg (đã có trong cache sidecar, hoặc ghép từ các đoạn sẵn có trong vài trăm ms) hoặc 202 pending (đã xếp hàng sinh nền — TTS trên ladamap có RTF ≈ 2 nên KHÔNG chờ; app bỏ câu im lặng và tự hỏi lại lượt sau).

Khác : không có hạn mức token, không có "Resets at"; 429 chỉ khi hàng đợi sidecar đầy (kèm Retry-After). Tách câu theo mẫu Valhalla, ghép bằng ffmpeg, chuyển mp3 đều ở sidecar. Đổi giọng/phiên bản ở sidecar thì đổi Tts:SelfHost:Voice/ModelVersion để đổi theo và app bỏ chỉ mục cũ. Memory project-tts-tu-host.

Tên HttpClient đăng ký ở DependencyRegister.

Dựng với cấu hình đã hợp nhất AppConfig + appsettings ().

Mã HTTP của sidecar → loại thất bại (hợp đồng trong vieneu_gateway.py, route /v1/clip).

Đọc {"error": "…"} của sidecar, cắt ngắn để ghi log; không phải JSON thì ghi thô.

Lớp tĩnh để đăng ký các phụ thuộc cho ứng dụng.

Đăng ký các phụ thuộc cho ứng dụng.

Bộ sưu tập dịch vụ. Cấu hình ứng dụng.

Lớp mở rộng để đăng ký các dịch vụ và cấu hình ứng dụng.

Đăng ký các dịch vụ chung.

Đối tượng IServiceCollection. Đối tượng IConfiguration.

Cấu hình và chạy ứng dụng.

Đối tượng WebApplication.

Thân phản hồi của handler lỗi toàn cục ngoài Development — ProblemDetails (RFC 7807) không chứa stack trace, không chứa thông điệp của exception, chỉ có mã lỗi và mã tra cứu.

Vì sao tách khỏi : đoạn này là thứ duy nhất người ngoài Internet nhìn thấy khi máy chủ hỏng, nên nó phải có ca test của chính nó. Nằm trong lambda của UseExceptionHandler thì không có cách nào gọi tới mà không dựng cả pipeline. Vì sao không trả cả Message của exception (sổ nợ CS-25): thông điệp lỗi .NET thường xuyên mang đường dẫn ổ đĩa (FileNotFoundException), tên máy chủ và tên database (SqlException), tên assembly và tên kiểu (AutoMapper, JsonException). Bản cũ trả nguyên StackTrace của cả chuỗi InnerException ra body — chấp nhận được khi API chỉ nằm sau tường lửa, nhưng đợt này mở /connect/register (DCR) ra Internet, và đường đó không cần đăng nhập: một request méo là một bản đồ máy chủ. Chi tiết không mất đi — nó vào nhật ký kèm đúng RequestId in ra cho người gọi, nên tra ngược được. Với lời gọi /mcp, RequestId chính là request-id mà McpGateMiddleware đã gán vào TraceIdentifier và đã trả ở header X-Request-Id.

Mã lỗi ổn định cho client — cùng họ với mã lỗi của lớp MCP.

Kiểu nội dung theo RFC 7807.

Câu duy nhất người gọi nhận được. Cố ý không nói gì về nguyên nhân.

Header trả mã tra cứu để người gọi đọc được mà không cần đọc body.

Ghi nhật ký đầy đủ rồi trả body an toàn. Không ném — handler lỗi mà ném thì client nhận kết nối đứt, còn khó hiểu hơn lỗi gốc.

Ngữ cảnh request đang hỏng. Exception gốc; null khi pipeline không kèm được (vẫn trả 500). Nơi chi tiết thật sự đi tới.

Bản dùng trong pipeline: lấy exception từ .

Đăng ký Rate Limiting để chống spam/brute-force cho các endpoint công khai và chặn client chạy loạn. Sử dụng built-in Rate Limiting của .NET (System.Threading.RateLimiting). Ngưỡng đọc từ mục RateLimiting của appsettings ().

Giới hạn toàn cục tính theo user khi đã đăng nhập, theo IP khi chưa (, 2026-10-16). Bản cũ tính 100 request/phút/IP cho mọi request, mà cả văn phòng ra Internet bằng một IP NAT nên vài chục nhân viên chia nhau một hạn mức và liên tục nhận 429 như bị khoá. Muốn biết user thì middleware này phải chạy sau UseAuthentication — thứ tự ở GeneralRegister.ConfigAndRunApp; đặt trước là mọi request lại rơi về IP. Khoá IP luôn lấy từ — không có hàm đọc IP riêng ở file này (sổ nợ CS-23, đóng 2026-09-07). Bản cũ tự đọc X-Forwarded-For và lấy phần tử đầu, tức là sau reverse proxy thì ai cũng tự khai header để nhảy sang phân vùng khác và bơm request không giới hạn — trong khi whitelist IP của MCP lấy phần tử cuối. Hai luật cho cùng một câu hỏi thì sớm muộn cũng lệch; nay chỉ còn một.

Tên policy cho các endpoint anonymous (báo lỗi, đăng ký client MCP, callback OAuth kênh chat).

Tên policy cho các endpoint nhạy cảm (Login - chống brute-force)

Tên policy cho webhook chat đa nền tảng (Zalo OA, Facebook Messenger)

Tên ghi vào log/header khi request bị giới hạn toàn cục theo user.

Tên ghi vào log/header khi request bị giới hạn toàn cục theo IP.

Đăng ký Rate Limiting services.

DI container. Cấu hình ứng dụng — đọc mục RateLimiting, thiếu thì dùng mặc định.

Tên policy để ghi log và trả header X-RateLimit-Policy: lấy từ metadata của endpoint đã khớp route; endpoint không gắn policy riêng thì là giới hạn toàn cục — theo user hay theo IP tuỳ phân vùng.

Bản cũ đoán policy bằng cách so chuỗi path (Contains("Login")…) nên endpoint mới gắn policy mà không cập nhật danh sách đó thì log ghi sai. Đọc metadata thì không phải nhớ.

Phân vùng cửa sổ cố định 1 phút theo IP (); preflight OPTIONS không tính.

Lớp mở rộng để đăng ký các dịch vụ bảo mật.

Đăng ký các dịch vụ bảo mật.

Đối tượng IServiceCollection. Đối tượng IConfiguration.

Đăng ký các middleware bảo mật.

Đối tượng IApplicationBuilder.

Dịch vụ khởi động được lưu trữ.

Khởi tạo một thể hiện của .

Đối tượng IServiceProvider. Bộ ghi nhật ký.

Phương thức được gọi khi dịch vụ khởi động.

Đối tượng CancellationToken. Nhiệm vụ không đồng bộ.

Mã hoá các API key nhà cung cấp AI còn ở dạng bản rõ (cổng nhượng quyền GĐ G, CNQ-1) — xem . Không bao giờ chặn khởi động: lỗi thì ghi cảnh báo rồi đi tiếp, key vẫn đọc được ở dạng cũ.

In phiên bản schema (migration mới nhất đã áp dụng) ra nhật ký lúc khởi động. Lý do tồn tại: quy trình vận hành cấm can thiệp database production trực tiếp, mà Lada.Migrations -- list — đường duy nhất còn lại để biết production đang ở đâu — vẫn đòi chuỗi kết nối. Một dòng nhật ký lúc khởi động trả lời đúng câu hỏi ấy vào đúng lúc cần nhất (ngay sau deploy) mà không mở thêm bề mặt công khai nào. CHỈ ĐỌC, và cố ý không bao giờ chặn khởi động: bảng VersionInfo do FluentMigrator sở hữu và ứng dụng không tham chiếu project migration, nên nó có thể chưa tồn tại trên một database mới tinh. Hỏng thì ghi cảnh báo rồi đi tiếp.

Phương thức được gọi khi dịch vụ dừng.

Đối tượng CancellationToken. Nhiệm vụ hoàn thành.

Lớp mở rộng để đăng ký các dịch vụ và middleware của Swagger.

Đăng ký các dịch vụ của Swagger.

Đối tượng IServiceCollection.

Đăng ký các middleware của Swagger.

Đối tượng IApplicationBuilder.

Thêm Expense.DepositUserId (phiếu chi hoàn cọc / tạm ứng gắn với lái xe). Kèm Income.MediaId: migration 20260724055334_AddMediaIdToIncome bị gỡ khỏi thư mục (gitignore, chưa từng apply vào DB dev) nên gộp cột đó vào đây. Body được viết tay — scaffold gốc gánh theo diff không liên quan do snapshot lệch DB.

Example appsettings.json configuration

Giải captcha từ file SVG

Giải captcha từ nội dung SVG string (dùng khi nhận SVG từ API response)

Custom -derived type for the PhonePattern method.

Cached, thread-safe singleton instance.

Initializes the instance.

Provides a factory for creating instances to be used by methods on .

Creates an instance of a used by methods on .

Provides the runner that contains the custom logic implementing the specified regular expression.

Scan the starting from base.runtextstart for the next match.

The text being scanned by the regular expression.

Search starting from base.runtextpos for the next location a match could possibly start.

The text being scanned by the regular expression. true if a possible match was found; false if no more matches are possible.

Determine whether at base.runtextpos is a match for the regular expression.

The text being scanned by the regular expression. true if the regular expression matches at the current position; otherwise, false.

Caches a instance for the ScriptOrStyle method.

A custom Regex-derived type could not be generated because the expression contains case-insensitive backreferences which are not supported by the source generator.

Cached, thread-safe singleton instance.

Custom -derived type for the BlockBreak method.

Cached, thread-safe singleton instance.

Initializes the instance.

Provides a factory for creating instances to be used by methods on .

Creates an instance of a used by methods on .

Provides the runner that contains the custom logic implementing the specified regular expression.

Scan the starting from base.runtextstart for the next match.

The text being scanned by the regular expression.

Search starting from base.runtextpos for the next location a match could possibly start.

The text being scanned by the regular expression. true if a possible match was found; false if no more matches are possible.

Determine whether at base.runtextpos is a match for the regular expression.

The text being scanned by the regular expression. true if the regular expression matches at the current position; otherwise, false.

Custom -derived type for the AnyTag method.

Cached, thread-safe singleton instance.

Initializes the instance.

Provides a factory for creating instances to be used by methods on .

Creates an instance of a used by methods on .

Provides the runner that contains the custom logic implementing the specified regular expression.

Scan the starting from base.runtextstart for the next match.

The text being scanned by the regular expression.

Search starting from base.runtextpos for the next location a match could possibly start.

The text being scanned by the regular expression. true if a possible match was found; false if no more matches are possible.

Determine whether at base.runtextpos is a match for the regular expression.

The text being scanned by the regular expression. true if the regular expression matches at the current position; otherwise, false.

Custom -derived type for the NonAlphaNum method.

Cached, thread-safe singleton instance.

Initializes the instance.

Provides a factory for creating instances to be used by methods on .

Creates an instance of a used by methods on .

Provides the runner that contains the custom logic implementing the specified regular expression.

Scan the starting from base.runtextstart for the next match.

The text being scanned by the regular expression.

Search starting from base.runtextpos for the next location a match could possibly start.

The text being scanned by the regular expression. true if a possible match was found; false if no more matches are possible.

Determine whether at base.runtextpos is a match for the regular expression.

The text being scanned by the regular expression. true if the regular expression matches at the current position; otherwise, false.

Custom -derived type for the SlugRegex method.

Cached, thread-safe singleton instance.

Initializes the instance.

Provides a factory for creating instances to be used by methods on .

Creates an instance of a used by methods on .

Provides the runner that contains the custom logic implementing the specified regular expression.

Scan the starting from base.runtextstart for the next match.

The text being scanned by the regular expression.

Search starting from base.runtextpos for the next location a match could possibly start.

The text being scanned by the regular expression. true if a possible match was found; false if no more matches are possible.

Determine whether at base.runtextpos is a match for the regular expression.

The text being scanned by the regular expression. true if the regular expression matches at the current position; otherwise, false.

Custom -derived type for the Spaces method.

Cached, thread-safe singleton instance.

Initializes the instance.

Provides a factory for creating instances to be used by methods on .

Creates an instance of a used by methods on .

Provides the runner that contains the custom logic implementing the specified regular expression.

Scan the starting from base.runtextstart for the next match.

The text being scanned by the regular expression.

Search starting from base.runtextpos for the next location a match could possibly start.

The text being scanned by the regular expression. true if a possible match was found; false if no more matches are possible.

Determine whether at base.runtextpos is a match for the regular expression.

The text being scanned by the regular expression. true if the regular expression matches at the current position; otherwise, false.

Custom -derived type for the E164Vn method.

Cached, thread-safe singleton instance.

Initializes the instance.

Provides a factory for creating instances to be used by methods on .

Creates an instance of a used by methods on .

Provides the runner that contains the custom logic implementing the specified regular expression.

Scan the starting from base.runtextstart for the next match.

The text being scanned by the regular expression.

Search starting from base.runtextpos for the next location a match could possibly start.

The text being scanned by the regular expression. true if a possible match was found; false if no more matches are possible.

Determine whether at base.runtextpos is a match for the regular expression.

The text being scanned by the regular expression. true if the regular expression matches at the current position; otherwise, false.

Custom -derived type for the PhoneNoise method.

Cached, thread-safe singleton instance.

Initializes the instance.

Provides a factory for creating instances to be used by methods on .

Creates an instance of a used by methods on .

Provides the runner that contains the custom logic implementing the specified regular expression.

Scan the starting from base.runtextstart for the next match.

The text being scanned by the regular expression.

Search starting from base.runtextpos for the next location a match could possibly start.

The text being scanned by the regular expression. true if a possible match was found; false if no more matches are possible.

Custom -derived type for the EmailPattern method.

Cached, thread-safe singleton instance.

Initializes the instance.

Provides a factory for creating instances to be used by methods on .

Creates an instance of a used by methods on .

Provides the runner that contains the custom logic implementing the specified regular expression.

Scan the starting from base.runtextstart for the next match.

The text being scanned by the regular expression.

Search starting from base.runtextpos for the next location a match could possibly start.

The text being scanned by the regular expression. true if a possible match was found; false if no more matches are possible.

Determine whether at base.runtextpos is a match for the regular expression.

The text being scanned by the regular expression. true if the regular expression matches at the current position; otherwise, false.

Helper methods used by generated -derived implementations.

Default timeout value set in , or if none was set.

Whether is non-infinite.

Finds the next index of any character that matches a character in the set [()-.\s].

Supports searching for characters in or not in "0123456789abcdefghijklmnopqrstuvwxyz".

Supports searching for characters in or not in "\0\u0001\u0002\u0003\u0004\u0005\u0006\a\b\u000e\u000f\u0010\u0011\u0012\u0013\u0014\u0015\u0016\u0017\u0018\u0019\u001a\u001b\u001c\u001d\u001e\u001f!\"#$%&'*+,/0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~\u007f".

Supports searching for characters in or not in "\t\n\v\f\r \u0085             \u2028\u2029  　".