UI Backend File Type flat vs indexed
Flat vs indexed JSON

DINHDANH Creator · Bài T03 · Thuật ngữ

Flat JSON vs Indexed
(CRUD list)

Một quyết định sai - dùng writeFile cho danh sách blog/đơn hàng - có thể phá sharding và làm dữ liệu “mất hình” khi scale.

Mục tiêu: Chọn đúng kiểu file; biết API nào đi với flat, API nào với indexed; phát hiện khi AI làm sai.

Thời lượng: 12-14 phút · Trước: T02, F02 · Sau: T04

UI: Backend · Xem backend database content · Chat mode Coder · Kiến trúc · So sánh thay đổi

1. Sơ đồ quyết định

Dữ liệu của bạn là gì?
→ Một object cấu hình (cms-settings, theme flags)
FLAT → readFile / writeFile (fileType: 'flat')
vd. cms-settings.json = { site_name, logo_url, … }
→ Danh sách nhiều bản ghi (bài viết, contact, sản phẩm, đơn)
INDEXED → appendData + readList + updateData + deleteFile(id)
vd. blog-posts.json, contacts.json, orders.json
❌ KHÔNG writeFile cả mảng list → mất sharding Aura (X07)

2. Thuật ngữ & API Aura Storage

Thuật ngữNghĩaAPI chính
FlatMột JSON object cho cả filereadFile, writeFile
Indexed / CRUD listDanh sách có id; master index + shard (T04)appendData, readList, updateData, readFile(file,id)
id / created_atBackend tự sinh khi append - không tự setKết quả appendData
Đọc lần đầu rỗngsuccess: true + [] / null - không phải 404Mọi read vdisk

3. Ví dụ file cụ thể

// FLAT - cms-settings.json
{ "site_name": "Shop ABC", "currency": "VND" }
// INDEXED - contacts.json (logic; physical có shard)
appendData('contacts.json', { name, email, message })
readList('contacts.json') → [{ id, created_at, name, … }, …]
updateData('contacts.json', id, { status: 'read' })

4. Các bước dùng đúng (qua Creator)

  1. Tab "Backend" → xác nhận Advanced version nếu cần list lớn / CMS (T06).
  2. Chat mode "Coder" hoặc "Kiến trúc" → prompt: “Form liên hệ: lưu bằng appendData vào contacts.json (indexed). Admin đọc readList. Không writeFile list.”
  3. Sau AI sửa → mở So sánh thay đổi → kiểm có appendData/readList; nếu thấy writeFile('blog-posts.json', [...]) cả mảng → ✗.
  4. Submit form thử → Backend → "Xem backend database content" thấy bản ghi mới có id.
  5. CMS bật: tên file theo entities.*.data_file trong __cms_manifest__ (T05) - vd. blog-posts.json không đổi thành my-blog.json.
  6. Nhấn "Lưu thay đổi" khi ổn.

5. So sánh · Giới hạn

  • Airtable / Notion DB: luôn list-oriented; Aura Indexed gần tinh thần đó.
  • Một ô nhớ trình duyệt chứa cả danh sách: giống sai lầm writeFile list - vỡ khi lớn.
  • Mongo 1 document settings vs collection: flat ≈ settings doc; indexed ≈ collection.
Làm được: list lớn nhờ shard; flat cho settings một object.
Không: tự đụng .shards/*; tự đặt id; mỗi item một file blog-1.json riêng.

6. Bảo mật · Sự cố

Guest chỉ được appendData khi policy cho phép - không cho guest writeFile/updateData (T07). CMS bật → bám manifest data_file.

Sự cốXử lý
List “mất” sau vài trăm bản ghiNghi writeFile list - migrate indexed (X07/F05)
Đọc lần đầu tưởng lỗiKhởi tạo default khi rỗng - success vẫn true
updateData không tìm idDùng id từ appendData/readList - không tự invent

7. Lời khuyên · Checklist

  • Prompt cố định: “Indexed cho mọi danh sách; Flat chỉ cho settings.”
  • Một file list (vd. blog-posts.json) chứa mọi item - backend tự shard.
  1. Bạn phân biệt được khi nào writeFile vs appendData?
  2. Bạn đọc Diff và từ chối writeFile([...]) cho list?
  3. Bạn biết readList trả id do backend sinh?

Tiếp: T04 - Sharding & system files