Incident Management — Case thường gặp

Cách đọc mỗi case: bắt đầu từ triệu chứng/câu hỏi, sau đó đọc behavior đúng, cách kiểm tra ở UI/API/dữ liệu/code, source anchor và Ví dụ thực tế. Các case ở đây ưu tiên behavior đang chạy; nếu cần contract gốc, mở spec/code được dẫn ở cuối case.

1. User không thấy incident nào

Kiểm tra:

1. User có quyền operational không: INCIDENT_MANAGEMENT_VIEW, INCIDENT_MANAGEMENT_CREATE, hoặc INCIDENT_MANAGEMENT_FULL_CONTROL. Riêng INCIDENT_MANAGEMENT chỉ bật menu, không cấp quyền xem.
2. Nếu chỉ có create-level, incident có phải do chính user tạo không.
3. Record có nằm trong Business Unit hiện tại + Org access scope của user không (view/full-control bị giới hạn theo scope).
4. Đang ở tab Active hay Closed; Closed chỉ gồm Closed và Cancelled.
5. Filter có đang thu hẹp quá mức không: date range, site, type, subtype, severity, status, attendee, account, creator, acknowledgement/signature requirement, search text.

Ví dụ thực tế: Giáo viên mở menu Incident nhưng danh sách trống. → Phân biệt "chưa có quyền xem" với "lọc quá hẹp". → Chỉ có INCIDENT_MANAGEMENT (bật menu, không cấp xem) → cần thêm ..._VIEW mới thấy record.

2. Không sửa được incident

Incident chỉ editable ở các trạng thái cho phép, thông dụng là:

Status	Edit?	Ghi chú
Draft	Có	Creator/create-level thao tác trên record của mình.
Changes Requested	Có	Sửa theo comment reviewer rồi submit lại.
Reopened	Có theo allowed actions	Sau khi reopen, có thể edit/submit/cancel.
Submitted, Under Review, Approved, Sent To Customer, Closed	Thường không	Dùng workflow action thay vì edit fields.

Nếu UI không hiện action, kiểm tra GetAllowedActions và permission level.

3. Manager không approve/request changes được

Cần INCIDENT_MANAGEMENT_FULL_CONTROL (lưu ý: INCIDENT_MANAGEMENT chỉ bật menu, không cấp governance) và status hợp lệ:

• Submitted: Start Review, Request Changes, Approve, Cancel.
• Under Review: Request Changes, Approve, Cancel.
• Approved: Send To Customer, Close.

Create-only user không làm governance actions cho incident của người khác.

Ví dụ thực tế: Trưởng ca cần duyệt báo cáo sự cố do giáo viên nộp. → Đảm bảo chỉ người có quyền governance mới approve/request changes. → Cần INCIDENT_MANAGEMENT_FULL_CONTROL và status Submitted/Under Review thì action mới hiện.

4. Gửi customer không tạo acknowledgement như mong đợi

Kiểm tra:

1. Incident đã Approved chưa.
2. Recipient list có contact hợp lệ không.
3. Contact nào là primary contact; primary mới mang acknowledgement responsibility.
4. Incident có RequiresAcknowledgement / RequiresSignature như mong đợi không.
5. Có duplicate acknowledgement đã tồn tại cho contact/incident không.
6. Nếu chọn attach latest document, incident đã có generated document hợp lệ chưa.

Ví dụ thực tế: Gửi báo cáo sự cố cho gia đình nhưng không tạo yêu cầu xác nhận. → Đảm bảo đúng người ký nhận. → Incident phải Approved và có primary contact hợp lệ → acknowledgement mới sinh cho primary contact.

5. Customer không thấy incident trong portal

Kiểm tra:

• Customer đang ở đúng account không.
• FormAcknowledgement có thuộc account đó không.
• Acknowledgement có phải NotificationOnly không; notification-only không nằm trong actionable list.
• Link detail có truyền đúng ackId không.
• Generated document có gắn với acknowledgement/attendee document đúng không.

6. PDF report thiếu file hoặc thiếu attendee

Hướng debug:

1. Kiểm tra request generate PDF: mode, attendeeRecordIds, internalOnly.
2. Kiểm tra BuildPdfDatasetAsync có gom đúng attendee/body marker/acknowledgement không.
3. Nếu cần merge PDF attachment, kiểm tra attachment có phải PDF và eligible theo scope không.
4. Kiểm tra BlobName của generated document có tồn tại và download được không.

7. Notification đã gửi chưa?

Trong staff detail, xem Notification History:

Dấu hiệu	Nên kiểm tra
Không có job	Business action có tạo notification job không; event/action đã chạy chưa.
Có job nhưng không có message	Worker Generator/Distributor và template/config.
Customer không nhận	Contact email/SMS, delivery channel, suppression/provider status.
Acknowledgement chưa Sent	Handler notification có update acknowledgement sau khi process không.
BU chưa cấu hình template	Worker phải fallback built-in default template, không skip/fail job.

8. Description không prefill hoặc bị ghi đè

Kiểm tra:

1. Loại incident đã chọn chưa; Description chỉ prefill khi field đang trống và đã chọn type.
2. Type có template lưu không; chưa lưu ⇒ dùng built-in default.
3. User đã sửa tay Description chưa — đã sửa thì hệ thống không auto-refresh khi đổi type/date/site/attendee.
4. Nếu thấy token thô như , đó là lỗi materialize; placeholder phải resolve thành text đọc được.

9. Generate PDF: nhầm visibility / nội dung

• Bỏ chọn Internal Use Only ⇒ luôn một PDF mỗi attendee, customer-visible, không hỏi combined/per-attendee.
• Chọn Internal Use Only ⇒ mới có lựa chọn gộp một report (mặc định) hoặc một PDF mỗi attendee.
• Customer-visible PDF không được chứa Created By, Internal Notes, attendee Description, hay acknowledgement của account khác.

Ví dụ thực tế: Sự cố liên quan 3 trẻ, cần gửi mỗi gia đình một bản không lộ thông tin trẻ khác. → Tách bản cho khách khỏi bản nội bộ. → Bỏ Internal Use Only → mỗi attendee một PDF customer-visible, không kèm internal notes/acknowledgement account khác.

10. Không mở được Settings / template

• Settings icon và API settings chỉ cho INCIDENT_MANAGEMENT_FULL_CONTROL; quyền khác bị từ chối.
• Lưu template ghi blob form-config-json và set PrefillBlobName cho version active của loại đó, scope theo Business Unit.

"PDF bị chặn bởi CSP hoặc quay lại mất context"

Dùng PdfDocumentPreview cho generated PDF và kiểm tra route có giữ các query parameters của onsite/app context hay không. Không dùng inline iframe mới hoặc đổi access scope để chữa lỗi hiển thị.

Ví dụ thực tế: PDF không render trong webview nhưng endpoint download trả file hợp lệ. → Giữ nguyên generated document; sửa đường preview CSP-safe và bảo toàn query context khi navigation.