
DINHDANH Creator · Bài AM11 · SECTION SYSTEM FILES & AURA CMS
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

Backend enforce bảo mật - không gọi trực tiếp bằng tên file tùy ý:
| File | Policy | Đọc | Ghi |
|---|---|---|---|
login.json | deny | ❌ 403 | ❌ - chỉ API auth (AM06) |
__super_master_index__.json | deny | ❌ 403 | ❌ backend tự quản |
routes.json | route_api | ✅ | ❌ writeFile - dùng addRoute/removeRoute (AM05) |
cms-settings.json | admin_settings | ✅ public đọc contact | admin/superadmin qua writeFile |
.shards/* | shard | ❌ 403 | ❌ - chỉ readList/readFile(id) |
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).
| Entity | data_file | Public ghi? |
|---|---|---|
| posts | blog-posts.json | - (admin) |
| products | shop-products.json | - |
| orders | shop-orders.json | appendData checkout |
| contacts | contacts.json | appendData form |
| pages | pages.json | - |
| categories | blog-categories.json | - |
| tags | blog-tags.json | - |
Code mẫu
readList blog publicawait 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'
})addRouteawait 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 HTMLconst 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.
type | Widget |
|---|---|
| string, text, html | text / textarea |
| number, boolean, url, image | number / toggle / url / image |
| enum | select - giá trị trong fields.*.enum |
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 định | Khi enforce bật | |
|---|---|---|
appendData public | Không cần token | Một số entity → 403 |
readList guest | Theo fields client | Lọc bản ghi + ẩn field |
| Admin đã login | Theo role | Đọc/ghi đầy đủ (trừ append disabled) |
| Chế độ append | Guest | Admin token |
|---|---|---|
| public | ✅ | ✅ |
| admin | ❌ 403 | ✅ |
| disabled | ❌ 403 | ❌ 403 |
Checklist trước khi gọi API:
- System file? → tuân policy bảng trên
- Entity data? → đúng
data_filetừ manifest - Thiếu entity? → nhắc user khai báo Custom type (Panel)
- HTML/assets? →
readFsFile/writeFsFile(AM04) - Auth? →
login/registerAdmin- không đọclogin.json - 403 bất ngờ? → kiểm AS11, không đổi sang
writeFile
Điều hướng nội bộ (cùng ngôn ngữ)
DINHDANH Creator · Loạt Method · AM11