XTransformer

Trình chỉnh sửa JSON aip-304-app dạng bảng cho macOS + Windows. Thay thế quy trình Google Sheets cũ — full CRUD cho Screens, Banners, Categories, Styles, Media, Countries với cam kết round-trip identity (file xuất ra giống hệt file đầu vào khi không có chỉnh sửa).

1. Cài đặt

macOS (Apple Silicon)

1. Tải release/XTransformer-0.1.0-arm64.dmg.
2. Mở DMG → kéo XTransformer.app vào thư mục Applications.
3. Mở app lần đầu: chuột phải → Open → Open (vì app chưa được Apple notarize, Gatekeeper sẽ cảnh báo).

Windows (64-bit)

Chọn 1 trong 2:

Lần đầu mở: Windows SmartScreen có thể chặn → click More info → Run anyway (vì .exe chưa có code-sign).

2. Cách dùng cơ bản

Mở và lưu file JSON

1. Click Open JSON (hoặc ⌘O / Ctrl+O) → chọn file aip-304-app-*.json.
2. App load file → mỗi entity hiện ở 1 tab riêng:
   • Screens: danh sách màn hình của app
   • Banners: banner trong từng screen
   • Categories: nhóm style xếp theo screen
   • Styles: style đầy đủ + cardPreviews
   • Media: thư viện ảnh/video referenced
   • Countries: country code i18n
   • Meta: version + exportedAt
3. Sửa trực tiếp trong bảng — mọi thay đổi tự validate realtime.
4. Click Save JSON (⌘S / Ctrl+S):
   • Nếu có lỗi validation → dialog hiện errors, phải sửa trước khi xuất.
   • Nếu có warning → dialog hỏi xác nhận, vẫn cho xuất.
   • Hiện diff (added / modified / deleted) trước khi ghi file.

Phím tắt

Chỉnh sửa cell

• Text: click vào ô → gõ → Enter để commit, Esc để hủy.
• Foreign key (FK): dropdown chỉ liệt kê giá trị hợp lệ — không thể tạo dangling reference.
• Boolean: toggle.
• Tags: gõ tag → Enter, dùng × để xóa.

Master-detail (Banners, Categories, Styles)

• Click mũi tên ▶ đầu hàng để mở rộng row.
• Detail panel cho phép sửa i18n titles/subtitles theo countryCode, style refs (Categories), card previews (Styles).

Bộ lọc theo Banner action

• Banner.action chỉ nhận 2 giá trị: CATEGORY hoặc STYLE.
• Đổi action sẽ tự xóa FK đối ngược (chọn CATEGORY → styleCode về null, ngược lại).
• Cột được dùng (Category hoặc Style) sẽ highlight vàng; cột không dùng mờ đi.

Validation

• Status bar đáy màn hình hiện số errors / warnings realtime.
• Click vào chip màu để mở Validation dialog xem chi tiết.
• Errors block xuất file; warnings chỉ cảnh báo.

Autosave

• Mỗi 5 giây khi có thay đổi chưa lưu, app backup vào localStorage.
• Mở app lần sau nếu phát hiện draft → prompt Restore / Discard.

3. Upload media lên CMS

Tích hợp Strapi CMS để upload ảnh/file thay vì phải vào trình duyệt → upload thủ công → copy URL → paste.

Setup lần đầu

1. Tab Media → click ⚙ Settings.
2. Confirm Base URL (mặc định https://cms.aperogroup.ai) → Save URL.
3. Click Sign in to Strapi → cửa sổ login mở ra → đăng nhập Google bằng tài khoản công ty.
4. App tự thu thập JWT-looking tokens trong localStorage/sessionStorage/cookies/URL của cửa sổ login → test từng cái với /upload/folders → cái nào trả 200 sẽ được lưu.
5. Nếu auto-detect fail → hiện danh sách candidates để pick thủ công, hoặc dán token trực tiếp từ DevTools.
6. Set Default upload folder từ dropdown (có search theo tên).

Upload

1. Tab Media → click ☁ Upload to CMS (hoặc dialog tự mở khi chưa đăng nhập).
2. Chọn folder đích (dropdown có search — gõ tên folder).
3. Pick file: hỗ trợ chọn nhiều file cùng lúc (⌘/Ctrl + click), mọi định dạng (image, video, zip, json, etc.).
4. Click Upload N files → progress bar realtime, mỗi file có status: ⏱ pending → ⟳ uploading → ✓ done / ⚠ error.
5. File upload thành công → tự thêm row mới vào Media table với strapi_id, url, name, mime đã fill, highlight vàng 60 giây để dễ nhận.

Đổi tài khoản Google

Trong Settings → click Switch account → app xóa cookies/storage của cửa sổ login → lần sign-in sau Google sẽ hiện lại màn chọn account.

Fallback dán token thủ công

Nếu Strapi setup khác lạ làm auto-detect fail:

1. Đăng nhập Strapi trong browser bình thường.
2. DevTools → Application → Local Storage → https://cms.aperogroup.ai.
3. Tìm key có giá trị dạng eyJhbGci... (JWT).
4. Settings → Paste token manually → dán → Save token.

4. Build & phát triển

# Cài dependencies
npm install

# Chạy dev mode (hot reload)
npm run dev

# Build production bundle
npm run build

# Type check
npm run typecheck

# Chạy test (Vitest round-trip)
npm test

# Đóng gói installer
npm run package:mac    # → release/XTransformer-*-arm64.dmg
npm run package:win    # → release/XTransformer-*-x64-setup.exe + portable
npm run package:all    # cả 2

5. Kiến trúc tóm tắt

src/
├── main/        Electron main process (file dialogs, IPC, Strapi handlers)
├── preload/     contextBridge (window.api)
└── renderer/    React app
    ├── lib/    schema · import · export · validate (port từ Sheets tool)
    ├── store/  Zustand (editor + diff-tracker + autosave + Strapi config)
    ├── components/  data-table · cells · dialogs · upload · folder-picker
    └── pages/  1 tab cho mỗi entity group

Tech stack: Electron 33 · Vite 5 · React 18 + TypeScript 5 · TanStack Table v8 · Tailwind 3 · Zustand 5 · Zod · Vitest · electron-builder

6. Không thuộc phạm vi (out of scope)

• Multi-user collab (single-user only)
• Cloud sync / backend riêng
• Schema editor (schema khoá ở aip-304-app v1.0)
• Sửa media trực tiếp (chỉ link URL)
• i18n cho UI app (chỉ data có i18n, UI dùng tiếng Anh)
• Code signing / notarization (skip cho nội bộ)

Made by Bạch Tử Hoạ