Cột File Type trong bảng Backend hiện flat indexed và shard
File Type: flat vs indexed

DINHDANH Creator · Bài F05 · Trung bình → Nâng cao

Flat vs Indexed JSON:
chọn đúng kiểu dữ liệu ngay từ đầu

Bài tổng kết nhóm F: một quy tắc duy nhất giúp bạn (và AI) không làm hỏng cấu trúc dữ liệu khi app lớn dần - bằng ví von đời thường, không cần biết code.

Mục tiêu bài học: Phân biệt flat vs indexed, nhận diện khi AI viết sai, và biết giới hạn khi đổi kiểu giữa chừng.

Thời lượng đọc: khoảng 14-16 phút

Điều kiện trước: Đã đọc F01-F02.

Bài trước → sau: F02 → F05 → G01

1. Sơ đồ quyết định (1 câu hỏi)

Dữ liệu của bạn là gì?
Một cấu hình / một object duy nhất (settings, theme, cms-settings)
→ flat - writeFile / readFile
Một danh sách nhiều bản ghi (blog, sản phẩm, liên hệ, đơn hàng)
→ indexed - appendData / readList / updateData
Ví von:
flat = 1 tờ giấy cài đặt dán trên tường
indexed = sổ đăng ký - mỗi người thêm 1 dòng, hệ thống tự chia nhỏ khi sổ dày

2. Thuật ngữ (bảng 3 cột)

Thuật ngữNghĩaNơi thấy trên UI
flatMột object JSON cho cả file - ghi đè toàn bộ khi sửaCMS: Một khối cấu hình (G05)
indexedDanh sách bản ghi có id - thêm từng dòng, hệ thống tự chia nhỏ khi lớnCMS: Danh sách có mã (G05)
writeFileAPI ghi đè cả file - đúng cho flat, sai cho danh sáchTên API khi nhờ AI (F02/F05)
appendDataAPI thêm 1 bản ghi vào danh sách indexedForm guest (F02)
readListAPI đọc toàn bộ danh sách indexedTrang admin / CMS
__cms_manifest__.jsonFile quy định tên file/schema khi bật Aura CMS - AI phải đọc trước khi đặt tênTab Thư mục (Creator)

3. Bảng so sánh chi tiết

products.json indexed master kèm file shard trong Backend database
Danh sách indexed tự tách shard
 flatindexed
Ví dụ filecms-settings.json, config.jsonblog.json, contacts.json, products.json
API tạo/sửawriteFile (ghi đè toàn bộ)appendData (thêm), updateData (sửa 1 bản ghi)
API đọcreadFile(fileName)readList(fileName) hoặc readFile(fileName, id)
Chưa có dữ liệucontent: "" (rỗng, không lỗi)content: [] (danh sách trống)
id / created_atKhông có - bạn tự định nghĩa fieldServer tự sinh - form không tự set được
Lỗi kinh điển: AI dùng writeFile('blog.json', JSON.stringify([...toàn bộ bài viết...])) mỗi lần thêm bài. Vẫn "chạy được" lúc ít bài, nhưng phá cơ chế chia nhỏ danh sách, dễ mất dữ liệu khi 2 người sửa cùng lúc, và không tương thích Aura CMS. Sửa ngay khi thấy.

4. Các bước kiểm tra & sửa nếu AI làm sai

  1. Hỏi AI: "File nào là danh sách (list) và file nào là cấu hình (config)?" - để AI tự rà soát.
  2. Với mỗi file danh sách, kiểm tra code có gọi writeFile với một mảng không - nếu có, đó là dấu hiệu sai.
  3. Yêu cầu: "Chuyển logic ghi danh sách sang appendData/updateData, dùng readList để đọc."
  4. Mở tab Backend → Xem nội dung database backend - xác nhận cấu trúc danh sách đúng sau khi sửa.
  5. Nếu dùng CMS: nhờ AI đọc __cms_manifest__.json trước - tên file phải khớp entity trong panel.

5. So sánh với công cụ khác

  • MongoDB: collection ≈ indexed list; document config đơn ≈ flat.
  • Airtable / Google Sheet: mỗi bảng ≈ indexed - mỗi dòng có id; tab Settings ≈ flat.
  • WordPress: wp_options ≈ flat; wp_posts ≈ indexed.
  • Notion database vs page: database ≈ indexed; trang cài đặt ≈ flat.

5b. Ví dụ đời thường (không cần biết JSON)

  • Cài đặt cửa hàng (tên shop, số điện thoại, màu chủ đạo) = flat - một tờ giấy cấu hình, ghi đè cả tờ khi đổi.
  • Sổ khách gửi liên hệ / danh sách sản phẩm / đơn hàng = indexed - mỗi dòng một khách/sản phẩm, thêm dòng mới không được chép lại cả sổ.
  • Nhắc AI bằng tiếng Việt: “contacts là danh sách nhiều bản ghi - dùng thêm bản ghi (appendData), không ghi đè cả file (writeFile).”

6. Giới hạn kỹ thuật

Làm được

  • Trộn flat + indexed trong cùng app (settings + blog)
  • Danh sách tự chia nhỏ khi nhiều bản ghi (Advanced)
  • CMS đọc đúng entity nếu tên file khớp manifest

Không nên / hạn chế

  • Đổi flat ↔ indexed giữa chừng khi đã có dữ liệu thật
  • writeFile cho danh sách guest gửi liên tục
  • Tự đặt tên file khác manifest khi CMS đã bật
  • Easy mode: indexed phức tạp có thể thiếu tính năng (F01)

7. Vấn đề thường gặp

Tình huốngXử lý
Hai người thêm cùng lúc, một bản ghi biến mấtDấu hiệu writeFile sai cho list - chuyển appendData
CMS có bài nhưng trang blog trốngTên file lệch manifest - đối chiếu __cms_manifest__.json
readFile trả content: nullGọi indexed kèm id không tồn tại, hoặc Security enforce lọc bản ghi

8. Lời khuyên - tổng kết nhóm F

  • Hỏi trước khi thiết kế: "Cái này sẽ có nhiều bản ghi tăng dần không?" - có thì chắc chắn indexed.
  • Nhớ chuỗi F01 (Backend/Easy-Advanced) → F02 (form appendData) → F03 (login.json/role) → F04 (Secrets) → F05 (flat/indexed).
  • Sau F05, mở Aura CMS tại /tên-link-của-bạn/cms (G01) để vận hành nội dung hàng ngày.

9. Checklist tự kiểm

  1. Bạn phân biệt flat và indexed chỉ bằng tên hàm API?
  2. Bạn phát hiện được lỗi writeFile cho danh sách?
  3. Bạn biết khi nào cần đọc __cms_manifest__.json?

Bài tiếp theo

G01 - Vào Aura CMS lần đầu: setup superadmin & đăng nhập

Chuyển sang nhóm G: quản trị nội dung hàng ngày qua panel riêng - mở địa chỉ dạng /tên-link-của-bạn/cms.

Điều hướng nội bộ (cùng ngôn ngữ)

DINHDANH Creator · Bộ hướng dẫn người dùng · F05 · Flat vs Indexed