Kiến trúc hệ thống

Thông tin về Cloudflare trong tài liệu này (giới hạn gói, file _headers, link xem trước, khôi phục bản cũ) cập nhật tới giữa năm 2026. Hãy kiểm tra lại tài liệu mới nhất của Cloudflare trước khi làm theo.

1. Yêu cầu

Yêu cầu chức năng (theo spec đã duyệt)

Yêu cầu phi chức năng

Ràng buộc

• Chưa có backend, hệ thống quản lý nội dung hay dữ liệu thật. Mọi nội dung là nội dung tĩnh, dữ liệu mẫu đều có nhãn.
• Trang chạy trên Cloudflare và chỉ có tiếng Việt.
• Áp dụng quality contract ở mức Full, profile web.
• Chỉ deploy hoặc tạo tài nguyên trên Cloudflare khi chủ dự án đã đồng ý.

2. Kiến trúc tổng thể

                 BUILD TIME                                   RUN TIME
┌──────────────────────────────────────┐      ┌──────────────────────────────────────┐
│ GitHub repo                          │      │ Điện thoại / webview Zalo / desktop  │
│  src/ (TS, CSS)  public/ (font, SVG) │      │                                      │
│  spec/homepage.feature               │      │   GET /  ──────────┐                 │
└──────────────┬───────────────────────┘      │   GET /assets/*  ──┤                 │
               │ push / PR                    └────────────────────┼─────────────────┘
               ▼                                                   ▼
┌──────────────────────────────────────┐      ┌──────────────────────────────────────┐
│ GitHub Actions                       │      │ Cloudflare edge                      │
│  lint · typecheck · unit · coverage  │      │  Workers static assets               │
│  axe · acceptance (playwright-bdd)   │      │   index.html   (cache ngắn)          │
│  mutation (Stryker) · secrets · deps │      │   assets/*.hash.js|css|woff2         │
│  ── merge main ──▶ vite build        │      │                (cache 1 năm)         │
│                   wrangler deploy ───┼─────▶│   _headers: CSP, bảo mật             │
└──────────────────────────────────────┘      └──────────────────────────────────────┘

Không có Worker script, database, hay lời gọi API lúc chạy.
Mọi tương tác (lọc, tạm dừng, thông báo) chạy hoàn toàn trên trình duyệt.

Vì sao chọn Workers static assets thay vì Pages: Cloudflare đang khuyến nghị dự án mới dùng Workers. Với một trang tĩnh, hai cách này như nhau. Chọn Workers thì sau này có thể thêm một đoạn Worker script nhỏ (ví dụ chuyển hướng /app sang link Mini App) mà không phải chuyển nền tảng.

3. Cấu trúc mã

├── index.html                 # khung trang, markup ngữ nghĩa, nội dung tĩnh
├── src/
│   ├── main.ts                # điểm vào: khởi tạo 3 tính năng, không chứa logic
│   ├── data/content.ts        # MỌI dữ liệu: việc làm, các bước, nhãn lọc, thông báo
│   ├── features/
│   │   ├── jobs-filter.ts     # logic thuần filterJobs() + gắn DOM
│   │   ├── reward-journey.ts  # trạng thái chuyển động + IntersectionObserver
│   │   └── notice.ts          # máy trạng thái thông báo + gắn DOM
│   ├── styles/
│   │   ├── tokens.css         # màu, font, bo góc; ghi độ tương phản trong comment
│   │   └── main.css
│   └── vite-env.d.ts
├── public/
│   ├── fonts/                 # Phudu, Be Vietnam Pro (woff2, subset) + giấy phép OFL
│   └── _headers               # header bảo mật & cache
├── spec/homepage.feature      # kịch bản đã duyệt → acceptance
├── tests/
│   ├── unit/                  # logic thuần: filterJobs, notice reducer
│   ├── component/             # DOM thật + Testing Library + vitest-axe
│   └── e2e/                   # playwright-bdd, 390px và 1440px
└── wrangler.jsonc             # assets.directory = ./dist

Mã được tách làm hai lớp. Phần xử lý logic không đụng tới DOM, nên dễ viết unit test và mutation test cho kết quả đáng tin. Phần gắn với DOM viết ngắn gọn và được kiểm bằng component test. Nội dung chính nằm sẵn trong HTML, để trang vẫn đọc được nếu JavaScript bị lỗi. Chỉ dữ liệu cần lọc hoặc hiển thị lặp lại mới đặt trong content.ts.

4. Mô hình dữ liệu

type JobType = 'full' | 'part';

interface Job {
  title: string;          // "Kỹ thuật viên bảo trì máy"
  where: string;          // "[Tên doanh nghiệp], Từ Sơn": chỗ chưa có dữ liệu để trong ngoặc vuông
  type: JobType;
  isSample: true;         // bắt buộc true cho tới khi có dữ liệu thật
}

type JobFilter = 'all' | JobType;

interface JourneyStep { title: string; text: string }   // đúng 3 bước, có thứ tự

type NotReadyTarget = 'mini-app' | 'email' | 'privacy' | 'news';
const NOT_READY: Record<NotReadyTarget, string>;         // lý do hiển thị

Trường isSample được khai báo cố định là true. Khi chuyển sang dữ liệu thật, lập trình viên phải đổi kiểu này, và trình biên dịch sẽ báo mọi chỗ đang hiện nhãn “dữ liệu mẫu” để sửa, không bỏ sót chỗ nào.

5. Hành vi và trạng thái

Thông báo “Chưa hoàn thiện”

            show(target)                 show(target2)
  Hidden ───────────────▶ Shown(msg) ─────────────────▶ Shown(msg2)  (hẹn giờ đặt lại)
     ▲                       │   │
     │   hết 4 giây          │   │ bấm "Đóng thông báo"
     └───────────────────────┘◀──┘

• Chỉ dùng một bộ hẹn giờ. Mỗi lần gọi show sẽ huỷ hẹn giờ trước đó, nên thông báo cũ không tự ẩn nhầm thông báo mới.
• Vùng role="status" aria-live="polite" luôn có sẵn trong DOM, chỉ thay nội dung bên trong.

Phần chuyển động

Ba điều kiện sau quyết định phần chuyển động chạy hay dừng:

Chuyển động viết bằng CSS keyframes và animation-play-state. JavaScript chỉ bật hoặc tắt một thuộc tính trên khối cha. Nếu người dùng đã bấm tạm dừng, cuộn ra khỏi phần này rồi cuộn lại thì chuyển động vẫn phải giữ trạng thái dừng.

Lọc việc làm

filterJobs(jobs, filter) là hàm thuần, chỉ trả về danh sách đã lọc. Phần giao diện vẽ lại danh sách và cập nhật aria-pressed trên ba nút lọc.

6. Giao tiếp bên ngoài

Khi chạy, trang không gọi API nào. Ở giai đoạn demo, đây là lựa chọn có chủ ý.

Mỗi khi một phần trong bảng trên có thông tin thật: đổi nút thành link, xoá dòng tương ứng khỏi bảng Examples trong spec, rồi gửi duyệt lại spec.

7. Phân phối, cache và bảo mật

Cache

Header bảo mật

/*
  Content-Security-Policy: default-src 'self'; img-src 'self' data:; font-src 'self';
    style-src 'self'; script-src 'self'; frame-ancestors 'none'; base-uri 'self';
    form-action 'none'
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()

• CSP đặt chặt được vì trang không tải tài nguyên từ bên ngoài. Muốn thêm nguồn mới (công cụ thống kê, ảnh từ CDN) thì phải sửa CSP cho riêng nguồn đó.
• Vite có thể chèn CSS trực tiếp vào HTML. Nếu CSP chặn phần này, cấu hình build để xuất CSS ra file riêng, không thêm 'unsafe-inline'.
• Sau khi đặt frame-ancestors 'none', kiểm tra lại trang vẫn mở bình thường trong trình duyệt của Zalo.

8. Môi trường, CI/CD và vận hành

Quy trình: PR phải qua hết các bước kiểm tra → merge vào main → build → deploy. Bước deploy cần hai secret do chủ dự án tạo: CLOUDFLARE_API_TOKEN (chỉ cần quyền sửa Workers) và CLOUDFLARE_ACCOUNT_ID.

Quay lại bản cũ: chạy wrangler rollback để về phiên bản trước, hoặc revert commit rồi để quy trình tự deploy lại. Trang không lưu dữ liệu nên quay lại bản cũ không làm mất dữ liệu.

Theo dõi: nếu Tỉnh đoàn cần số lượt xem, dùng Cloudflare Web Analytics (không dùng cookie), và khai báo thêm vào CSP cùng chính sách quyền riêng tư. Đặt một bước kiểm tra định kỳ xem trang / còn chạy. Trang không có backend nên không cần cảnh báo phức tạp hơn.

9. Lượng truy cập và mở rộng

Trang tĩnh phục vụ từ mạng máy chủ của Cloudflare chịu được lượng truy cập của cả tỉnh. Kể cả lúc đông người vào nhất (có sự kiện lớn, link được chia sẻ trong các nhóm Zalo), chi phí chủ yếu chỉ là băng thông tải file tĩnh.

10. Vị trí trong toàn hệ thống

┌──────────────┐  link/QR   ┌──────────────────┐   API    ┌──────────────────────┐
│  HOMEPAGE    │──────────▶ │  Zalo Mini App   │────────▶ │  Backend (HubCom)    │
│  (tài liệu   │            │  thanh niên      │          │  việc làm, voucher,  │
│   này)       │            └──────────────────┘          │  check-in, quiz,     │
└──────────────┘            ┌──────────────────┐   API    │  phân quyền địa bàn  │
       ▲                    │  Cổng quản trị   │────────▶ │                      │
       │ (tương lai:        │  cán bộ, DN      │          └─────────┬────────────┘
       │  đọc API công khai)└──────────────────┘                    │ API
       └─────────────────────────────────────────────────┐ ┌────────▼────────────┐
                                                         └─│ AI (Thái Sơn)       │
                                                           │ chưa có đặc tả      │
                                                           └─────────────────────┘

Hiện tại trang chủ chỉ có link dẫn sang Mini App. Trang không có đăng nhập, không lưu dữ liệu người dùng và không gọi backend. Nhờ vậy, trang chủ deploy được riêng, không phải chờ các phần khác của dự án còn đang dở (API AI, cây địa bàn, Zalo duyệt Mini App).

11. Đánh đổi đã chọn

Lưu ý: bản đang chạy khác tài liệu này ở một điểm. Trang dựng bằng Next.js (xuất ra file tĩnh) thay vì TypeScript thuần với Vite. Phần hosting thì đúng như mô tả: Workers static assets, deploy bằng wrangler deploy.