dla-docs

Dịp đặc biệt

1. Mục đích

Module Dịp đặc biệt giúp bạn quản lý các dịp đặc biệt trong năm và chuẩn bị cho chúng, bao gồm:

Quản lý các dịp đặc biệt (sinh nhật, lễ tết, v.v.)
Tạo danh sách việc cần làm (preparation steps)
Gắn checklist cho từng bước chuẩn bị
Nhắc nhở trước dịp
Theo dõi tiến độ chuẩn bị

2. Khi nào nên dùng

Sử dụng module này khi bạn muốn:

Quản lý các dịp đặc biệt trong năm
Chuẩn bị cho các dịp quan trọng
Tạo danh sách việc cần làm
Nhận nhắc nhở trước dịp

3. Các màn hình liên quan

Danh sách dịp đặc biệt
Thêm dịp đặc biệt mới
Chi tiết dịp và các bước chuẩn bị
Thêm bước chuẩn bị
Chọn checklist
Tạo checklist mới

4. Cách sử dụng chính

4.1 Thêm dịp đặc biệt

Vào Chức năng → Chọn Dịp đặc biệt
Nhấn nút + (FAB)
Điền thông tin:
- Tên dịp: (ví dụ: “Sinh nhật mẹ”)
- Ngày: Chọn ngày/tháng (DatePicker chỉ chọn ngày/tháng, không có năm)
- Sử dụng lịch âm: (Tùy chọn) Tick nếu muốn dùng lịch âm
  - Nếu tick: Nhập ngày và tháng âm, app tự tính ngày dương gần nhất
- Lặp lại: Hằng năm / Chỉ năm nay
- Hiện thông báo lúc: Chọn giờ (bắt buộc, ví dụ: 07:00)
- Ghi chú: Thông tin bổ sung (tùy chọn)
(Tùy chọn) Thêm các bước chuẩn bị (xem 4.2)
Nhấn Lưu

4.2 Thêm bước chuẩn bị

Khi thêm dịp mới: Nhấn + Thêm bước trong section “Các bước chuẩn bị”
Hoặc từ chi tiết dịp: Nhấn + Thêm bước
Điền thông tin:
- Khi nào?: “X ngày trước” hoặc “Đúng ngày”
- Số ngày: (nếu chọn “X ngày trước”) Nhập số ngày trước dịp
- Hiện thông báo lúc: Chọn giờ (bắt buộc)
- Nhắc lại mỗi ngày đến khi hoàn thành: (Tùy chọn) Tick nếu muốn nhắc mỗi ngày
- Nội dung: Tên bước (bắt buộc, ví dụ: “Mua quà”)
- Ghi chú: (Tùy chọn)
- Dùng checklist: (Tùy chọn) Tick để liên kết với checklist mua sắm
Nhấn Thêm (hoặc FAB “Áp dụng”)

4.3 Tạo checklist

Khi thêm bước chuẩn bị, tick Dùng checklist
Màn hình “Chọn checklist mua sắm” tự động mở
Nhấn FAB + để tạo checklist mới
Nhập tên checklist
Thêm các mục:
- Nhập tên mục
- Nhấn + để thêm mục mới
Nhấn Lưu
Checklist mới được tự động chọn và quay lại màn hình “Thêm bước chuẩn bị”

4.4 Đánh dấu hoàn thành bước

Vào chi tiết dịp đặc biệt
Tìm bước cần đánh dấu
Nhấn vào checkbox [ ] để chuyển thành [✓]
Nếu có checklist, nhấn vào tên checklist để xem và tick/untick các món

4.5 Xem tiến độ

Vào chi tiết dịp đặc biệt
Xem section “Tổng quan”:
- Số bước chuẩn bị: Tổng số bước
- Đã hoàn thành: Số bước đã tick / Tổng số bước
- Trạng thái: Chưa bắt đầu / Đang chuẩn bị / Hoàn tất

4.6 Sửa dịp đặc biệt

Vào chi tiết dịp đặc biệt
Nhấn hyperlink Sửa › ở header
Chỉnh sửa thông tin: Tên, ngày, lặp lại, giờ nhắc, ghi chú
Nhấn Lưu

4.7 Sửa bước chuẩn bị

Vào chi tiết dịp đặc biệt
Nhấn vào bước cần sửa (click vào toàn bộ item, trừ icon Xóa)
Chỉnh sửa thông tin: Thời gian, nội dung, checklist
Nhấn Áp dụng (hoặc FAB)

5. Ví dụ & minh hoạ giao diện

OCCASION-01: Tạo dịp đặc biệt mới (sinh nhật với các bước chuẩn bị)

Mục tiêu: Tạo một dịp đặc biệt mới (sinh nhật) với các bước chuẩn bị để app tự động nhắc nhở trước khi dịp diễn ra.

Các bước chính:

Vào Chức năng → Dịp đặc biệt → Nhấn nút “+” (FAB)
Nhập tên dịp, chọn ngày (05/01), chọn lặp lại “Hằng năm”, chọn giờ nhắc (07:00)
Thêm bước chuẩn bị 1: “7 ngày trước – 08:00” - “Mua quà”
Thêm bước chuẩn bị 2: “1 ngày trước – 19:00” - “Đặt bánh”
Nhấn “Lưu”

Wireframe - Màn hình Thêm dịp đặc biệt:

┌──────────────────────────────────────────────┐
│ <  Thêm dịp đặc biệt                          │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│ 📝 Thông tin dịp                              │
│                                               │
│ Tên dịp *                                     │
│ [ Sinh nhật bé An                    ]       │
│                                               │
│ Ngày                                          │
│ [ 05 / 01            ▼ ]                      │
│ (DatePicker chỉ chọn ngày/tháng)             │
│                                               │
│ [ ] Sử dụng lịch âm                           │
│                                               │
│ Lặp lại                                       │
│ (•) Hằng năm                                   │
│ ( ) Chỉ năm nay                                │
│                                               │
│ Hiện thông báo lúc *                          │
│ [ 07:00        ▼ ]                            │
│                                               │
│ Ghi chú (tuỳ chọn)                             │
│ [                                      ]      │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│ 📋 Các bước chuẩn bị          [ + Thêm bước ]│
│ ┌──────────────────────────────────────────┐ │
│ │  1. Mua quà                   [Icon Xóa] │ │
│ │     7 ngày trước – 08:00                 │ │
│ │ ──────────────────────────────────────── │ │
│ │  2. Đặt bánh                   [Icon Xóa] │ │
│ │     1 ngày trước – 19:00                 │ │
│ └──────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

        [ Hủy ]                        [ Lưu ]

OCCASION-02: Tạo dịp đặc biệt dùng lịch âm (Giỗ với checklist mua sắm)

Mục tiêu: Tạo một dịp đặc biệt dùng lịch âm (Giỗ) với các bước chuẩn bị có liên kết checklist mua sắm để theo dõi việc mua đồ cúng.

Các bước chính:

Vào Chức năng → Dịp đặc biệt → Nhấn nút “+” (FAB)
Nhập tên dịp “Giỗ mẹ”, tick “Sử dụng lịch âm”
Nhập ngày âm: 15/11, app tự tính ngày dương: 15/12/2025
Thêm 3 bước chuẩn bị, trong đó bước 2 có liên kết checklist “mua đồ cúng”
Nhấn “Lưu”

Wireframe - Chọn ngày âm:

│ │ │ Ngày âm                                     │ │ │
│ │ │ Ngày (1-30)    Tháng (1-12)                │ │ │
│ │ │ [ 15 ]        [ 11 ]                       │ │ │
│ │ │                                               │ │ │
│ │ │ Ngày dương lịch (tự tính - chỉ hiển thị)    │ │ │
│ │ │ [ Text: 15/12/2025                 ]         │ │ │
│ │ │ (Đây là ngày dương GẦN NHẤT trong tương lai)│ │ │

OCCASION-03: Xem danh sách và chi tiết dịp đặc biệt

Mục tiêu: Xem tổng quan các dịp đặc biệt, lọc theo thời gian, và xem chi tiết từng dịp với tiến độ chuẩn bị.

Các bước chính:

Vào Chức năng → Dịp đặc biệt
Xem danh sách với filter “Tất cả”, “Sắp tới”, “Tháng này”
Nhấn vào card dịp để xem chi tiết
Xem tổng quan: Số bước, Đã hoàn thành, Trạng thái
Đánh dấu hoàn thành bước bằng cách tick checkbox

Wireframe - Màn hình Danh sách dịp đặc biệt:

┌────────────────────────────────────────────────────────────┐
│ 📅 Danh sách dịp đặc biệt                                   │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ [ + Thêm dịp ]                                         │ │
│ └────────────────────────────────────────────────────────┘ │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 🔍 Filter: [ Tất cả ]  [ Sắp tới ]  [ Tháng này ]      │ │
│ └────────────────────────────────────────────────────────┘ │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 📌 Giỗ mẹ                 [Đang chuẩn bị] [Icon Xóa] │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ 📅 15/12/2025 • 15/11 (Âm) • Còn 10 ngày            │ │ │
│ │ │                                                      │ │ │
│ │ │ ✅ Các bước cần chuẩn bị:                            │ │ │
│ │ │   [✓] 3 ngày trước – Lên danh sách đồ cúng         │ │ │
│ │ │   [ ] 1 ngày trước – Đi chợ chuẩn bị đồ cúng        │ │ │
│ │ │   [ ] Đúng ngày – Chuẩn bị bàn thờ / làm lễ         │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │

Wireframe - Màn hình Chi tiết dịp đặc biệt:

┌─────────────────────────────────────────────────────────┐
│ 📋 Chi tiết dịp đặc biệt                                    │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 📌 Giỗ mẹ                                   [Sửa ›]        │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ 15/12/2025 (Dương) • 15/11 (Âm lịch)              │ │ │
│ │ │ Còn 10 ngày • Lặp lại: Hằng năm                    │ │ │
│ │ │                                                      │ │ │
│ │ │ Ghi chú:                                             │ │ │
│ │ │ Làm mâm cơm nhỏ, hoa trắng, hạn chế khách mời.      │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 📊 Tổng quan                                            │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ Số bước chuẩn bị: 3                                │ │ │
│ │ │ Đã hoàn thành: 1 / 3                               │ │ │
│ │ │ Trạng thái: [Đang chuẩn bị]                       │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 📝 Các bước chuẩn bị                  [ + Thêm bước ]                  │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ [✓] Lên danh sách đồ cúng                [Icon Xóa]           │ │ │
│ │ │     3 ngày trước – 08:00                          │ │ │
│ │ │     Hoàn thành lúc 09:15 – 12/12/2025              │ │ │
│ │ │ ──────────────────────────────────────────────────── │ │ │
│ │ │                                                      │ │ │
│ │ │ [ ] Đi chợ chuẩn bị đồ cúng                [Icon Xóa]            │ │ │
│ │ │     1 ngày trước – 19:00                        │ │ │
│ │ │     Nhắc lại mỗi ngày đến khi hoàn thành            │ │ │
│ │ │     Checklist mua sắm: mua đồ cúng ›                 │ │ │
│ │ │     [✓] Hoàn thành 3 / 8 món                            │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │

OCCASION-04: Thêm bước chuẩn bị với checklist mua sắm

Mục tiêu: Thêm bước chuẩn bị mới cho dịp đặc biệt và liên kết với checklist mua sắm để theo dõi việc mua đồ.

Các bước chính:

Vào chi tiết dịp đặc biệt → Nhấn “+ Thêm bước”
Chọn “Khi nào?”: “X ngày trước”, nhập số ngày: 1
Chọn giờ nhắc: 19:00
Bật “Nhắc lại mỗi ngày đến khi hoàn thành”
Nhập nội dung: “Đi chợ chuẩn bị đồ cúng”
Tick “Dùng checklist” → Chọn checklist “mua đồ cúng”
Nhấn “Thêm”

Wireframe - Màn hình Thêm bước chuẩn bị:

┌────────────────────────────────────────────────────────────┐
│ ➕ Thêm bước chuẩn bị                                       │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ ⏰ Thời gian chuẩn bị                                       │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ Khi nào? * (bắt buộc)                             │ │ │
│ │ │ [ X ngày trước         ▼ ]                        │ │ │
│ │ │                                                      │ │ │
│ │ │ Số ngày * (chỉ hiển thị khi chọn "X ngày trước") │ │ │
│ │ │ [  1  ]  ngày trước                                │ │ │
│ │ │                                                      │ │ │
│ │ │ Hiện thông báo lúc * (bắt buộc)                   │ │ │
│ │ │ [ 19:00        ▼ ]                                 │ │ │
│ │ │                                                      │ │ │
│ │ │ [✓] Nhắc lại mỗi ngày đến khi hoàn thành            │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 📝 Nội dung                                            │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ Nội dung * (bắt buộc)                             │ │ │
│ │ │ [ Đi chợ chuẩn bị đồ cúng               ]          │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 🔗 Liên kết với checklist mua sắm?                     │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ ☑ Dùng checklist                                    │ │ │
│ │ │ Checklist mua sắm: mua đồ cúng ›        [Icon Swap]  │ │ │
│ │ │ (8 món)                                             │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│                                                              │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ [ Hủy ]                        [ Thêm ]               │ │
│ └────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘

OCCASION-05: Đánh dấu hoàn thành bước chuẩn bị và xem tiến độ checklist

Mục tiêu: Đánh dấu hoàn thành các bước chuẩn bị và theo dõi tiến độ checklist mua sắm.

Các bước chính:

Vào chi tiết dịp đặc biệt
Xem bước có checklist với tiến độ “Hoàn thành 3 / 8 món”
Nhấn vào tên checklist để xem chi tiết và tick/untick các món
Tick checkbox bước để đánh dấu hoàn thành
Xem “Tổng quan” cập nhật real-time

OCCASION-06: Sửa dịp đặc biệt và bước chuẩn bị

Mục tiêu: Chỉnh sửa thông tin dịp đặc biệt và các bước chuẩn bị sau khi đã tạo.

Các bước chính:

Vào chi tiết dịp đặc biệt → Nhấn “Sửa ›”
Chỉnh sửa tên dịp, ghi chú
Nhấn “Lưu”
Nhấn vào bước để sửa: Thay đổi thời gian, nội dung
Nhấn icon Xóa để xóa bước (có confirm dialog)

6. Logic & quy tắc

6.1 Ngày âm lịch

Bạn có thể nhập cả ngày dương và ngày âm lịch
App tự động tính ngày dương tương ứng với ngày âm
Hỗ trợ lặp lại hàng năm theo âm lịch

6.2 Lặp lại

Hằng năm: Dịp lặp lại mỗi năm (theo dương hoặc âm lịch)
- Với lịch dương: Mỗi năm tính nextOccurDate dựa trên (ngày/tháng) của solarDate
- Với lịch âm: Mỗi năm convert từ ngày âm sang ngày dương tương ứng và cập nhật nextOccurDate
Chỉ năm nay: Dịp chỉ có hiệu lực trong năm hiện tại, không lặp lại năm sau

6.3 Bước chuẩn bị

Khi nào?: Có 2 lựa chọn:
- X ngày trước: Nhắc trước X ngày so với ngày dịp (phải nhập số ngày)
- Đúng ngày: Nhắc vào chính ngày dịp (không cần nhập số ngày)
Hiện thông báo lúc: Thời gian nhắc (bắt buộc, format HH:mm)
Nhắc lại mỗi ngày đến khi hoàn thành: Nếu bật, thông báo sẽ lặp lại hàng ngày cho đến khi user đánh dấu hoàn thành
Liên kết checklist: Mỗi bước có thể gắn một checklist mua sắm để theo dõi tiến độ mua đồ

6.4 Checklist

Checklist có thể được tái sử dụng cho nhiều bước
Theo dõi số mục đã hoàn thành / Tổng số mục (ví dụ: “Hoàn thành 3 / 8 món”)
Hiển thị trong chi tiết bước với link “tên checklist ›” để xem chi tiết
Có thể tick/untick các món trong checklist để cập nhật tiến độ
Bước chuẩn bị có thể đánh dấu hoàn thành ngay cả khi checklist chưa hoàn thành hết

6.5 Thông báo

Thông báo chính dịp: Tạo tại nextOccurDate + reminder_time
- Với dịp YEARLY: notification sẽ được rebuild lại khi app start (dựa trên nextOccurDate mới được tính lại)
- Với dịp ONCE: notification chỉ được tạo một lần cho nextOccurDate hiện tại
Thông báo bước chuẩn bị: Tính toán ngày nhắc dựa trên:
- nextOccurDate của special occasion
- reminderType và daysBefore (nếu có)
- reminderTime
Thông báo lặp lại: Nếu repeatDailyUntilComplete = true:
- Tạo notification lặp lại hàng ngày
- Sử dụng notificationGroupKey để group các notification lặp lại
- Tự động hủy khi user đánh dấu hoàn thành bước

7. Lưu ý quan trọng

Ngày âm lịch:
- App tự động chuyển đổi sang dương lịch để hiển thị
- Tìm “Ngày dương lịch GẦN NHẤT trong tương lai” so với ngày hiện tại
- Các năm sau: Hệ thống luôn tự tính lại ngày dương tương ứng từ (lunar_day, lunar_month) cho từng năm
- Nếu năm đó có cả tháng thường và tháng nhuận cùng tháng: Hệ thống có thể tạo 2 lần nhắc để tránh bỏ sót
Lặp lại hàng năm:
- Dịp sẽ tự động tính lại nextOccurDate vào năm sau
- Với lịch âm: Mỗi năm convert từ ngày âm sang ngày dương tương ứng
Giờ nhắc:
- Bắt buộc phải có giá trị (không được để trống)
- Phải đúng format HH:mm (00:00 - 23:59)
Checklist:
- Checklist bị xóa vẫn hiển thị trong bước (nhưng không thể sửa)
- Có thể đánh dấu hoàn thành bước ngay cả khi checklist chưa hoàn thành hết
Thông báo:
- Cần bật thông báo trong Cài đặt để nhận nhắc nhở
- Thông báo lặp lại sẽ tự động hủy khi đánh dấu hoàn thành bước
Trạng thái dịp:
- Chưa bắt đầu: Tất cả các bước đều chưa hoàn thành (màu xám)
- Đang chuẩn bị: Có ít nhất 1 bước đã hoàn thành nhưng chưa hết (màu xanh dương)
- Hoàn tất: Tất cả các bước đã hoàn thành (màu xanh lá đậm)
- Nếu dịp không có bước chuẩn bị: Trạng thái tính theo ngày (Chưa bắt đầu / Đang diễn ra / Hoàn tất)