📖 Hướng dẫn Sử dụng: Quản lý Địa điểm & Địa bàn (Location & Geo System)

1. 📌 Định nghĩa & Mục đích Tính năng (Overview)

• Tên tính năng: Quản lý Địa điểm & Địa giới Hành chính (Location Management & VN Geo Search).
• Phân hệ áp dụng: 🌐 Web Dashboard / 📱 Mobile App / 📱 Zalo Mini App.
• Vấn đề giải quyết: Cung cấp cơ chế quản lý dữ liệu thực địa đa tầng (Ground-truth Master Data) kết hợp lớp cấu hình riêng cho từng Workspace (Tenant Overlays), tìm kiếm nhanh toàn quốc với PGroonga và vòng đời xóa an toàn (Safe Purge / Graceful Unsubscribe).
• Lợi ích mang lại:
  • Tra cứu địa chỉ, địa giới hành chính toàn quốc tức thì (hỗ trợ Tiếng Việt không dấu).
  • Tái sử dụng điểm Master dùng chung hoặc tùy biến tên, mã điểm, danh mục nội bộ theo từng Workspace/Folder.
  • Bảo vệ tính toàn vẹn dữ liệu: không thể xóa cứng các điểm đã phát sinh lịch sử công việc (chuyển sang hủy liên kết an toàn).

2. 👥 Đối tượng Sử dụng & Quyền Hạn (Target Audience & IAM)

3. 📖 Thuật ngữ & Khái niệm Nghiệp vụ (Glossary)

• Master Location (Ground Truth): Điểm thực địa gốc chứa thông tin vật lý chuẩn (tọa độ GPS, số nhà, phường xã, ảnh chụp thực tế).
• Workspace Location (Overlay): Bản ghi liên kết địa điểm vào Workspace, cho phép đặt tên tùy biến (custom_name), mã nội bộ (custom_code), danh mục riêng (custom_category).
• Owner Safe Purge: Quyền xóa vĩnh viễn Master Record nếu người xóa là Creator/Owner và điểm chưa có ai sử dụng trong công việc.
• Graceful Unsubscribe: Tự động chuyển thành hủy liên kết nội bộ nếu điểm đã có ràng buộc công việc, bảo toàn lịch sử chấm công và bằng chứng thực địa.

4. 🔄 Luồng Trải nghiệm Người dùng (User Flow)

5. 🛠 Các Bước Thực hiện Chi tiết (Step-by-Step Guide)

🔹 Bước 1: Thêm Địa Điểm với Wizard 2 Bước (LocationFormModal)

1. Truy cập: Vào Địa điểm (/locations) ➔ Bấm “Thêm địa điểm”.
2. Bước 1 (Tìm kiếm & Khám phá):
   • Gõ tên điểm, địa chỉ hoặc tên phường/xã.
   • Nếu có điểm Master gợi ý: Bấm chọn để chuyển sang Bước 2 ở chế độ Tùy biến.
   • Nếu chưa có: Bấm ”+ Tạo địa điểm mới” để chuyển sang Bước 2 ở chế độ Tạo mới.
3. Bước 2 (Cấu hình & Nhập liệu):
   • Chế độ Tùy biến: Điền Tên tùy biến (custom_name), Mã cửa hàng nội bộ (custom_code), Phân loại kênh (custom_category) và Thư mục trực thuộc.
   • Chế độ Tạo mới:
     • Nhập Số nhà/tên đường, chọn Tỉnh/Thành, Phường/Xã.
     • Tọa độ GPS: Bấm “Lấy tọa độ tự động” để hệ thống tự dò Vĩ độ / Kinh độ dựa trên địa chỉ vừa nhập. Sau khi có tọa độ, bấm “Xem bản đồ” để đối soát nhanh vị trí trên Google Maps.
     • Tải lên ảnh chụp thực địa và thiết lập cấu hình Workspace.
4. Bấm “Lưu địa điểm”: Điểm được lưu và tự động hiển thị trong Workspace.

🔹 Bước 2: Chọn Địa Điểm Trong Form Công Việc (LocationPickerField)

• Tại Bước 3 của Form Đăng việc (JobFormModal), ô chọn địa điểm hỗ trợ cơ chế Smart Step Initialization:
  • Gõ từ khóa tìm kiếm ➔ Nếu không thấy và bấm + Tạo mới "Tên điểm", hệ thống tự động mở thẳng Bước 2 (bỏ qua bước tìm kiếm trùng lặp), điền sẵn tên điểm và địa chính.
  • Sau khi chọn hoặc tạo, hiển thị Full Location Details Card bao gồm: Tên điểm, Mã Store, Phân loại, Địa chỉ đầy đủ, Tọa độ GPS, Thư viện ảnh thực địa và Google Maps preview iframe.

🔹 Bước 3: Xóa hoặc Hủy Liên Kết Địa Điểm (Safe Delete)

1. Tại danh sách Địa điểm (/locations), bấm nút icon Thùng rác (Xóa) tại dòng địa điểm cần xóa.
2. Hộp thoại xác nhận hiển thị thông tin rõ ràng:
   • Nếu điểm chưa phát sinh công việc và bạn là chủ sở hữu: Điểm sẽ được xóa hoàn toàn.
   • Nếu điểm đã có lịch sử công việc hoặc đang dùng chung: Điểm sẽ được hủy liên kết an toàn khỏi Workspace mà không làm mất dữ liệu lịch sử.

🚨 6. Xử lý Lỗi Thường gặp (Troubleshooting & FAQs)