🛠️ Tizia Dev · Hướng dẫn phát triển app

1. Làm thử trong 5 phút

Tạo hai file này rồi nén lại thành hello.zip:

{
  "alias": "hello-tizia",
  "name": "Hello Tizia",
  "description": "App đầu tiên của tôi",
  "icon": "👋",
  "version": "1.0.0"
}

<!doctype html>
<html lang="vi">
<head><meta charset="utf-8"><title>Hello Tizia</title></head>
<body style="font-family:system-ui;padding:32px">
  <h1>Xin chào 👋</h1>
  <p id="who">Đang đọc danh tính…</p>
  <script>
    // Tizia chèn sẵn biến này trước khi trang chạy.
    var u = window.__PORTAL_USER__;
    document.getElementById('who').textContent =
      u ? 'Chào ' + u.name + ' (id ' + u.id + ')' : 'Bạn chưa đăng nhập';
  </script>
</body>
</html>

zip -r hello.zip manifest.json public/

Kéo hello.zip vào trang Portal Apps:

Mở app lên, nó chào đúng tên người đang đăng nhập — danh tính do Tizia đưa sang:

2. Tải app mẫu về

Nhanh hơn nữa: tải một gói mẫu đã đóng sẵn, kéo thả vào Tizia để xem nó chạy, rồi giải nén ra sửa thành app của bạn. Mỗi gói là một file HTML duy nhất, không cần cài đặt gì, không cần build — mở bằng trình soạn thảo là đọc hiểu được ngay.

3. Cấu trúc gói .zip

my-app.zip
├── manifest.json        ← bắt buộc, nằm ở gốc (hoặc trong 1 thư mục con duy nhất)
└── public/
    ├── index.html       ← bắt buộc, là điểm vào
    └── assets/          ← JS/CSS/ảnh đã build
        ├── index-abc123.js
        └── index-abc123.css

Tizia chỉ giải nén những gì nằm trong public/. File để ngoài (README, thư mục schema/, mã nguồn…) bị bỏ qua, không gây lỗi. Manifest được đọc rồi lưu vào cơ sở dữ liệu.

4. manifest.json

5. Host đưa gì cho app

Khi phục vụ index.html, Tizia chèn thêm vào <head> mấy thứ sau. App chỉ việc đọc — không cần gọi API nào để biết mình đang chạy ở đâu, ai đang dùng:

Nhìn thấy tận mắt

Mở app rồi xem mã nguồn trang, phần đầu sẽ trông như thế này:

<head>
  <base href="/portal-apps/u/23/hello-tizia/">
  <script>window.__WRITE_API_BASE__="/api/apps/hello-tizia";
          window.__DATA_API_BASE__="/api/apps/hello-tizia";</script>
  <script>window.__AI_PORTAL_LOCALE__="vi";</script>
  <script>window.__PORTAL_USER__={"id":"23","email":"","name":"Nguyễn Văn A"};</script>
  … phần <head> gốc của bạn giữ nguyên …

6. Lưu dữ liệu ở đâu

Tizia không cấp sẵn kho dữ liệu cho app. Bạn có ba lựa chọn, chọn theo mức độ nghiêm túc của dữ liệu:

7. App có backend riêng

Tizia không chạy code backend nằm trong file zip. Backend của bạn phải là một dịch vụ riêng đang chạy sẵn; bạn khai địa chỉ nó vào apiProxyTarget, còn Tizia làm proxy và gắn danh tính người dùng vào từng request.

{
  "alias": "my-app",
  "name": "My App",
  "hasBackend": true,
  "apiProxyTarget": "https://api.vidu.vn/my-app"
}

Phía app gọi thế nào

const base = window.__WRITE_API_BASE__ || '';   // "/api/apps/my-app"

export async function getSources() {
  const r = await fetch(base + '/sources', { credentials: 'include' });
  if (r.status === 401) throw new Error('Phiên đăng nhập đã hết');
  return r.json();
}

Phía backend đọc danh tính thế nào

app.get('/sources', (req, res) => {
  const userId = req.header('X-User-Id');       // "23" — Tizia đã xác thực
  if (!userId) return res.status(401).json({ error: 'no_identity' });
  res.json({ items: db.listFor(userId) });
});

Bốn luật phải nhớ

• apiProxyTarget phải là URL tuyệt đối. Đường dẫn kiểu /my-api bị từ chối (502).
• Backend trong mạng nội bộ (localhost, 10.x, 172.16–31.x, 192.168.x) mặc định bị chặn để tránh SSRF. Cần thì nhờ quản trị bật PORTAL_APPS_ALLOW_INTERNAL.
• Phần đuôi sau /api/apps/<alias> được ghép nguyên xi vào target, kể cả query. Tizia không tự thêm /api.
• Chỉ tin X-User-* khi request thực sự đến từ Tizia. Đặt backend sau tường lửa, hoặc kiểm tra thêm một khoá bí mật dùng chung.

8. Build sao cho đúng

Ba lỗi dưới đây chiếm gần hết số ca "cài xong mở ra trắng trang". Đọc kỹ phần này tiết kiệm cho bạn cả buổi.

export default defineConfig({
  base: './',              // ← quan trọng nhất
  build: { outDir: 'public' },
})

grep -r "localhost" public/assets/*.js | head

const base =
  (typeof window !== 'undefined' && window.__WRITE_API_BASE__) ||
  import.meta.env.VITE_API_URL ||
  '';

Cấu hình mẫu theo công cụ

9. Chạy thử ở máy trước khi đóng gói

Ở máy bạn không có Tizia nên __PORTAL_USER__ không tồn tại. Giả lập vài dòng là đủ để phát triển thoải mái:

<script>
  // Giả lập môi trường Tizia khi chạy ở localhost.
  if (location.hostname === 'localhost') {
    window.__PORTAL_USER__ = { id: '1', email: 'dev@local', name: 'Dev' };
    window.__WRITE_API_BASE__ = 'http://localhost:4000';   // backend dev của bạn
  }
</script>

Đoạn này nằm trong index.html nên vẫn theo vào bản build — nhưng vì có điều kiện localhost nên lên Tizia nó không chạy. Muốn sạch hơn thì đặt trong file riêng và loại khi build.

10. Cài đặt, cập nhật, công khai

Cài lần đầu

Kéo thả .zip vào trang Portal Apps. Cần đăng nhập và hồ sơ đã điền đủ.

Cập nhật

Cài lại đúng alias đó là xong — bản cũ bị thay hoàn toàn (Tizia giải nén ra thư mục tạm rồi mới tráo, nên app không bao giờ ở trạng thái nửa vời). URL không đổi, người dùng không phải làm gì.

Công khai cho mọi người

Mặc định app chỉ mình bạn thấy. Khi muốn phát hành cho cả trường, nhờ quản trị viên bấm công khai — lúc đó app xuất hiện trong mục "Apps cộng đồng" ở trang Ứng dụng:

Hai đường dẫn tới app — dùng đúng cái

Tự động hoá bằng API

curl -X POST https://tizia.vn/api/portal-apps/install \
  -b "tizia_sid=<cookie phiên của bạn>" \
  -H "Content-Type: application/zip" \
  --data-binary @my-app.zip

11. Giao diện & trải nghiệm

• Nền tối là mặc định. Tizia dark-only ở hầu hết trang. App nền trắng vẫn mở được nhưng chói mắt khi người học đang đi từ trang tối sang. Nếu làm được cả hai nền thì đọc __PORTAL_THEME__.
• Người dùng là học sinh, sinh viên. Chữ tiếng Việt, câu ngắn, nút to. Tránh thuật ngữ tiếng Anh không chú giải.
• Chạy được trên màn hình hẹp. Nhiều em học bằng máy tính bảng hoặc điện thoại.
• Đừng tự mở cửa sổ mới hay chuyển hướng ra ngoài — app đang nằm trong khung của Tizia, làm vậy người học lạc mất đường về.
• Trạng thái rỗng phải nói được gì đó. "Chưa có dữ liệu" kèm một nút để bắt đầu, đừng để màn hình trống trơn.

12. Bảo mật & quyền riêng tư

• Không nhúng khoá API vào bundle. Mã frontend ai cũng đọc được. Khoá phải nằm ở backend của bạn.
• Không tự dựng form đăng nhập. Người dùng đã đăng nhập Tizia rồi; hỏi mật khẩu lần nữa là dấu hiệu lừa đảo.
• Backend phải chạy HTTPS nếu đặt ngoài mạng nội bộ.
• Kiểm tra quyền theo X-User-Id, đừng tin id do app gửi lên trong body.
• Chỉ xin đúng thứ cần. App tạo mã QR thì không có lý do gì đụng tới camera hay vị trí.

13. Xử lý sự cố

14. Mã lỗi khi cài

15. Checklist trước khi nộp

• ☐index.html trỏ asset bằng ./ — không còn đường dẫn tuyệt đối.
• ☐Đã grep bundle: không còn localhost, không còn khoá API.
• ☐Mở app khi chưa đăng nhập cũng không vỡ (phòng khi chạy ở host khác).
• ☐Gọi backend qua __WRITE_API_BASE__, không gọi thẳng domain riêng.
• ☐Thử ở khung hẹp 375px — nút vẫn bấm được, chữ không tràn.
• ☐Đọc được trên nền tối.
• ☐alias, name, description, icon (emoji), version đã điền đúng.
• ☐Zip không lẫn node_modules, không lẫn mã nguồn.
• ☐Cài thử lên tài khoản của mình và bấm hết các nút một lượt.

16. Giới hạn hiện tại

• Không chạy code backend trong zip. App kiểu AI Portal đóng gói sẵn dist/embed.js chỉ chạy được phần giao diện; muốn có backend thì tách ra dịch vụ riêng rồi khai apiProxyTarget.
• Không chạy file .sql trong zip. Thư mục schema/ được chấp nhận nhưng bỏ qua — app tự lo phần lưu trữ.
• Khai báo functions[] chưa dùng được. Tizia lưu lại nhưng trợ lý AI chưa tự gọi hàm của app.
• Icon Lucide chưa vẽ được. Manifest ghi "icon": "FileText" thì Tizia hiển thị 🧩. Dùng emoji để có icon đúng ý.
• Định danh người dùng ở Tizia là số, ở AI Portal là UUID. Backend nào ràng buộc định dạng UUID cần nới ra.
• Chưa có kho app chung để người khác tự cài — hiện phải nhờ quản trị công khai từng app.

17. App mẫu đang chạy

Sáu app dưới đây đang chạy thật trên Tizia bằng đúng cơ chế mô tả ở trên. Mở ra xem trước khi bắt tay làm app của bạn:

Vướng chỗ nào, gửi yêu cầu bằng nút góp ý ở góc màn hình — cùng đường với góp ý của người học, và có người đọc thật.