Cây Assets có file JSON hệ thống/CMS cùng pages
File hệ thống & CMS

DINHDANH Creator · Bài AM11 · SECTION SYSTEM FILES & AURA CMS

File hệ thống & CMS manifest
gọi API đúng tên · đúng quyền

Phần API-facing của Aura CMS - không phải method Panel nội bộ. Biết file nào đọc được, entity map ra tên JSON nào, và khi security enforce bật thì 403/null là đúng.

Mục tiêu: Không gọi nhầm system file; đọc manifest lấy data_file; hiểu security enforce - không workaround.

UI Panel / cài đặt bảo mật: loạt AS10 (CMS manifest) · AS11 (security UI).

Trước: AM10 · Sau: AM12 (ví dụ minh họa)

1. System files - policy backend

Tổng quan Backend nơi phạm vi API key và chính sách kho áp dụng
Chính sách Backend

Backend enforce bảo mật - không gọi trực tiếp bằng tên file tùy ý:

FilePolicyĐọcGhi
login.jsondeny❌ 403❌ - chỉ API auth (AM06)
__super_master_index__.jsondeny❌ 403❌ backend tự quản
routes.jsonroute_api✅❌ writeFile - dùng addRoute/removeRoute (AM05)
cms-settings.jsonadmin_settings✅ public đọc contactadmin/superadmin qua writeFile
.shards/*shard❌ 403❌ - chỉ readList/readFile(id)
❌ KHÔNG readFile('login.json') · KHÔNG tạo auth.json riêng · KHÔNG writeFsFile('routes.json') · KHÔNG appendData vào system file.

2. Entity → data_file (CMS bật)

__cms_manifest__.json quy định tên file JSON - đọc manifest trước, không đoán (blog.json sai; CMS dùng blog-posts.json).

Entitydata_filePublic ghi?
postsblog-posts.json- (admin)
productsshop-products.json-
ordersshop-orders.jsonappendData checkout
contactscontacts.jsonappendData form
pagespages.json-
categoriesblog-categories.json-
tagsblog-tags.json-

Code mẫu

readList blog public
await window.waitForAppStorage()
const res = await appifio_client.appifio_readList('blog-posts.json',
  ['id','title','slug','excerpt','status','published_at'])
let posts = res.data?.content || []
posts = posts.filter(p => p.status === 'published')
appendData form liên hệ (public)
await appifio_client.appifio_appendData('contacts.json', {
  name: 'Nguyễn A', email: 'a@example.com', message: 'Xin chào'
})
Admin tạo bài + addRoute
await appifio_client.validateAdminSession()
const created = await appifio_client.appifio_appendData('blog-posts.json', {
  title: 'Tiêu đề', slug: 'tieu-de', content: '

…

', status: 'draft'
})
const id = created.data?.id
await appifio_client.appifio_updateData('blog-posts.json', id, { status: 'published' })
await appifio_client.appifio_addRoute('tieu-de', 'blog/detail.html', 'post')
readFile cms-settings · readFsFile HTML
const settings = await appifio_client.appifio_readFile('cms-settings.json')
// settings.data.content → site_mode, contact_form, display_formats…

const html = await appifio_client.appifio_readFsFile('blog/detail.html')  // AM04

__cms_ui_contract__.json - hook DOM (#post-list, class acms-*). Khi sửa layout HTML, giữ id/class trong contract để CMS script hoạt động.

3. Kiểu dữ liệu tùy chỉnh

Entity mới khai báo trong Panel → Kiểu dữ liệu tùy chỉnh → CMS cập nhật manifest. Sau khi user lưu, đọc lại __cms_manifest__.json lấy entities.{key}.data_file.

typeWidget
string, text, htmltext / textarea
number, boolean, url, imagenumber / toggle / url / image
enumselect - giá trị trong fields.*.enum
Trường hệ thống custom: id, slug, publish_state, created_at, updated_at. Trường status tùy chỉnh khác publish_state - filter public thường dùng publish_state === 'published'.

4. Security enforce (tùy chọn)

Chủ site có thể bật trong Panel (xem AS11). Khi bật, backend siết quyền - code vẫn viết như AM02; nếu gặp 403 hoặc content: null thì đó là hành vi đúng, không workaround.

 Mặc địnhKhi enforce bật
appendData publicKhông cần tokenMột số entity → 403
readList guestTheo fields clientLọc bản ghi + ẩn field
Admin đã loginTheo roleĐọc/ghi đầy đủ (trừ append disabled)
Chế độ appendGuestAdmin token
public✅✅
admin❌ 403✅
disabled❌ 403❌ 403

Checklist trước khi gọi API:

  1. System file? → tuân policy bảng trên
  2. Entity data? → đúng data_file từ manifest
  3. Thiếu entity? → nhắc user khai báo Custom type (Panel)
  4. HTML/assets? → readFsFile / writeFsFile (AM04)
  5. Auth? → login / registerAdmin - không đọc login.json
  6. 403 bất ngờ? → kiểm AS11, không đổi sang writeFile

DINHDANH Creator · Loạt Method · AM11