📖 Tài Liệu Hướng Dẫn Mỹ Lích Calendar CLI

Hướng dẫn toàn diện từ việc sử dụng CLI/TUI đến triển khai tự host backend riêng tư.

1. Cài đặt & Bắt đầu nhanh với CLI

Mỹ Lích CLI là công cụ dòng lệnh cực nhẹ viết bằng Go, hỗ trợ đầy đủ Linux, macOS và Windows:

# Tải bản phát hành mới nhất từ GitHub Releases:
# https://github.com/spiderdev-vn/mylich/releases

# Hoặc cài đặt trực tiếp bằng Go:
go install github.com/spiderdev-vn/mylich/lich-cli/cmd/lich@latest

# Kiểm tra phiên bản
lich version

2. Tra cứu lệnh CLI thường dùng

Lệnh CLI	Mô tả tác vụ
lich	Mở giao diện Terminal tương tác toàn màn hình (TUI)
lich login	Đăng nhập hoặc đăng ký tài khoản vào máy chủ tự host
lich today	Xem lịch trình hôm nay dạng thẻ tóm tắt
lich week	Xem danh sách sự kiện trong tuần hiện tại
lich month	Xem lịch trình cả tháng
lich add <title>	Tạo sự kiện mới (hỗ trợ --date, --at, --to, --desc)
lich edit <id>	Chỉnh sửa tiêu đề hoặc mốc thời gian sự kiện
lich delete <id>	Xóa sự kiện (có hộp thoại hỏi xác nhận an toàn)
lich search <text>	Tìm kiếm sự kiện tức thì theo từ khóa trong tiêu đề/mô tả
lich sync	Đồng bộ hóa 2 chiều tức thì với lich-server
lich status	Kiểm tra kết nối máy chủ, hàng đợi đồng bộ và cache cục bộ
lich nuke-database	Xóa sạch database cục bộ (hoặc thêm --remote để xóa cả server)

3. Trải nghiệm giao diện TUI tương tác

Gõ lệnh lich để khởi động giao diện bảng điều khiển tương tác:

• Phím mũi tên (↑ ↓ ← →) hoặc h / j / k / l: Di chuyển qua lại giữa các ngày trong tháng.
• Phím [n] / [p]: Chuyển nhanh sang tháng tiếp theo hoặc quay về tháng trước.
• Phím [a]: Mở form thêm sự kiện mới.
• Phím [d]: Xóa sự kiện đang chọn.
• Phím [s]: Kích hoạt đồng bộ hóa ngầm.
• Phím [q] / [Esc]: Thoát TUI.

4. Tích hợp Google Calendar hai chiều

Để liên kết lịch cá nhân với Google Calendar:

# 1. Mở trình duyệt để xác thực OAuth với tài khoản Google
lich google connect

# 2. Kiểm tra trạng thái kết nối và danh sách lịch Google đã ánh xạ
lich google status

# 3. Đồng bộ 2 chiều sự kiện ngay lập tức
lich google sync

# 4. Hủy liên kết khi không còn nhu cầu
lich google disconnect

5. Hướng dẫn tự host lich-server bằng Docker

Triển khai máy chủ riêng với docker-compose.yml:

services:
  lich-server:
    image: ghcr.io/spiderdev-vn/mylich-server:latest
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./data:/data
    networks:
      - traefik_default
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.lich-server.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.lich-server.entrypoints=websecure"
      - "traefik.http.routers.lich-server.tls.certresolver=myresolver"
      - "traefik.http.services.lich-server.loadbalancer.server.port=3000"

networks:
  traefik_default:
    external: true

Copy và cấu hình file .env (từ .env.example):

DOMAIN=lich.yourdomain.com
JWT_SECRET=your-super-strong-32-chars-jwt-secret-key-here
GOOGLE_CLIENT_ID=your-google-oauth-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=https://lich.yourdomain.com/api/v1/auth/google/callback

6. Đặc tả REST API v1

Tất cả các API endpoints đều nằm dưới tiền tố chuẩn /api/v1/...:

• POST /api/v1/auth/register: Đăng ký người dùng mới
• POST /api/v1/auth/login: Đăng nhập nhận JWT Token
• GET /api/v1/auth/me: Xem thông tin người dùng hiện tại
• GET /api/v1/calendars: Danh sách lịch
• GET /api/v1/events: Lấy danh sách sự kiện (hỗ trợ lọc theo khoảng thời gian)
• POST /api/v1/events: Tạo sự kiện mới
• PATCH /api/v1/events/:id: Cập nhật sự kiện
• DELETE /api/v1/events/:id: Xóa sự kiện
• POST /api/v1/sync/push-pull: Đồng bộ hóa hai chiều theo Cursor log