zeta-api

name	zeta-api
description	ZetaCP internal API reference — notification system, Zustand stores, Tauri invoke patterns, event bus, z-index table, and database schema. Load this skill when adding features, wiring error handling, or working with any store/command.

ZetaCP Internal API Reference

Đọc toàn bộ file này trước khi implement feature mới.
Gọi đúng API, không tự tạo lại những gì đã có.

---

1. Notification System

Import

// Dùng được mọi nơi — React component, store, hook, event listener
import { notify } from '@/stores/useNotificationStore';
// hoặc path tương đối:
import { notify } from '../../stores/useNotificationStore';

API

// Lỗi nghiêm trọng từ backend — KHÔNG tự dismiss
notify.error(title: string, message: string, hint?: string): string  // returns id

// Cảnh báo — KHÔNG tự dismiss
notify.warn(title: string, message: string, hint?: string): string

// Thông tin — tự dismiss sau 4s
notify.info(title: string, message: string): string

// Thành công — tự dismiss sau 4s
notify.success(title: string, message: string): string

// Parse ZetaError object tự động (code + message + hint)
notify.fromTauriError(title: string, err: unknown): string

// Đóng 1 notification
notify.dismiss(id: string): void

Pattern chuẩn khi dùng invoke()

// ✅ ĐÚNG
try {
  const result = await invoke<MyResult>('my_command', { param });
  notify.success('Hoàn thành', 'Mô tả ngắn');
} catch (err) {
  notify.fromTauriError('Tiêu đề lỗi', err);  // parse ZetaError tự động
}

// ✅ ĐÚNG — dạng .catch()
invoke('some_command', { param })
  .then(() => notify.success('OK', 'Done'))
  .catch((err) => notify.fromTauriError('Lỗi X', err));

// ❌ SAI — chỉ console.error, user không biết có lỗi
invoke('cmd').catch(console.error);

Dùng trong store (outside React)

// Store không có hook — dùng getState()
import { useNotificationStore } from './useNotificationStore';
const { error } = useNotificationStore.getState();
error('Lỗi lưu file', err.message);

// Hoặc dùng notify helper (recommended)
import { notify } from './useNotificationStore';
notify.fromTauriError('Lỗi lưu file', err);

ZetaError shape (từ backend)

interface ZetaError {
  code: 'COMPILER_NOT_FOUND' | 'DB_READONLY' | 'INVALID_INPUT' | 'IO_ERROR' | 'DB_ERROR' | 'FATAL';
  message: string;
  hint: string;
}
// notify.fromTauriError() tự parse shape này

---

2. Zustand Stores

Tổng quan stores

Store	File	Mục đích
useProjectStore	stores/useProjectStore.ts	Active file, tabs, file content, autosave
useTestcaseStore	stores/useTestcaseStore.ts	Testcase CRUD, judge run, file settings
useOverlayStore	stores/useOverlayStore.ts	Floating overlay windows + logs
useSettingsStore	stores/useSettingsStore.ts	Global settings (gpp_path, python_path...)
useLayoutStore	stores/useLayoutStore.ts	Panel open/close state, activeView
useStressTestStore	stores/useStressTestStore.ts	Stress test state, results
useSnippetStore	stores/useSnippetStore.ts	Code snippets
useNotificationStore	stores/useNotificationStore.ts	Notification center

useProjectStore — key API

const {
  rootPath,           // string | null — đường dẫn tuyệt đối project
  activeFile,         // string | null — relative path từ rootPath
  activeFileContent,  // string — nội dung Monaco hiện tại
  openTabs,           // string[] — list relative paths đang mở
  dirtyFiles,         // Record<path, boolean> — file có thay đổi chưa lưu
  cursorPos,          // { line, column }

  openProject,        // (path: string) => Promise<void>
  setActiveFile,      // (path: string | null) => Promise<void>
  saveActiveFile,     // () => Promise<void>
  closeTab,           // (path: string) => Promise<void>
} = useProjectStore();

useTestcaseStore — key API

const {
  metas,          // Map<id, TestcaseMeta>
  results,        // Map<id, TestcaseResult>
  loadedData,     // Map<id, TestcaseData> — lazy loaded
  subtasks,       // Map<id, Subtask>
  activeFilePath, // string | null
  fileSettings,   // FileSettings | null

  loadForFile,    // (filePath: string) => Promise<void>
  loadData,       // (id: string) => Promise<void> — lazy load input/output
  addTestcase,    // (input?, expected?, subtaskId?) => Promise<void>
  deleteTestcase, // (id: string) => Promise<void>
  simulateRun,    // (id?: string | string[]) => Promise<void> — chạy judge
  cancelRun,      // () => void

  saveFileSettings, // (settings: FileSettings) => Promise<void>
} = useTestcaseStore();

useLayoutStore — key API

const {
  terminalOpen,     // boolean
  setTerminalOpen,  // (v: boolean) => void
  activeView,       // 'editor' | 'stress-tester'
  setActiveView,    // (v: string) => void
} = useLayoutStore();

useSettingsStore — key API

const {
  settings,       // GlobalSettings | null
  isSettingsOpen, // boolean
  loadSettings,   // () => Promise<void>
  saveSettings,   // (s: GlobalSettings) => Promise<void>
  openSettings,   // () => void
  closeSettings,  // () => void
} = useSettingsStore();

Đọc store ngoài React (không có hook)

// Bất kỳ file nào — store, util, event handler
const rootPath = useProjectStore.getState().rootPath;
const activeFile = useProjectStore.getState().activeFile;
await useTestcaseStore.getState().simulateRun();

Subscribe store (side effects)

// Trong useEffect hoặc module-level
const unsub = useTestcaseStore.subscribe((state, prev) => {
  if (state.results !== prev.results) { /* ... */ }
});
// cleanup: unsub();

---

3. Tauri Invoke — Commands Reference

Import

import { invoke } from '@tauri-apps/api/core';
// Hoặc dùng tauri-bridge wrappers (preferred):
import { compileFile, loadFileSettings, ... } from '@/lib/tauri-bridge';

tauri-bridge.ts wrappers (dùng những cái này thay invoke trực tiếp)

// Settings
loadSettings(): Promise<GlobalSettings>
saveSettings(settings: GlobalSettings): Promise<void>

// File system
openProject(folderPath: string): Promise<ProjectInfo>
scanDirectory(folderPath: string, filter: FileFilter): Promise<FileNode[]>
startFileWatcher(root: string): Promise<void>
stopFileWatcher(): Promise<void>
writeTextFile(filePath: string, content: string, rootPath: string): Promise<void>
readTextFile(filePath: string, rootPath: string): Promise<string>

// Compiler
compileFile(filePath: string, flags: string[], projectRoot: string): Promise<CompileResult>
compileChecker(checkerPath: string, checkerType: string, projectRoot: string): Promise<CompileResult>

// Testcase
loadFileContext(filePath: string): Promise<FileContext>
loadFileSettings(filePath: string): Promise<FileSettings>
saveFileSettings(settings: FileSettings, filePath?: string): Promise<void>
importTestcasesFromFolder(folderPath: string, filePath: string): Promise<void>

// Overlay
loadOverlays(filePath: string): Promise<OverlayState[]>
saveOverlaysBackend(filePath: string, overlays: OverlayState[]): Promise<void>

Invoke trực tiếp (khi không có wrapper)

// Pattern chuẩn
const result = await invoke<ReturnType>('command_name', { paramCamelCase: value });

// Ví dụ thực tế
await invoke('run_testcases', { filePath, testcaseIds });
await invoke('stop_testcases');
await invoke('run_stress_test', { solutionPath, brutePath, ... });
await invoke('stop_stress_test');
await invoke('open_docs_window', { docsType: 'cp-algorithms' });
await invoke('compute_diff', { expected, actual });

---

4. Tauri Event Bus

Listen events (FE nhận từ BE)

import { listen } from '@tauri-apps/api/event';

// Judge progress — khi run testcases
const unlisten = await listen<JudgeProgress>('judge-progress', (event) => {
  const { testcaseId, status, result } = event.payload;
  // status: 'running' | 'done'
});

// Stress test progress
await listen<StressTestPayload>('stress-test-progress', (event) => {
  // event.payload.type: 'compiling' | 'progress' | 'stateUpdate' | 'complete' | 'error'
});

// File watcher — khi file/dir thay đổi trên disk
await listen('file-changed', handler);

// Testcase list thay đổi (import, stress export)
await listen('testcase-list-updated', ({ payload }) => {
  const { filePath } = payload as { filePath: string };
});

// Testcase import realtime
await listen<TestcaseImportedPayload>('testcase-imported', handler);

// Overlay sync
await listen('overlays-updated', handler);

// Diff data (cho detached diff windows)
await listen<{ testcaseId: string, diffLines: DiffLine[] }>('diff-data-updated', handler);

Emit events (FE gửi)

import { emit } from '@tauri-apps/api/event';

await emit('diff-data-updated', { testcaseId, diffLines });

Cleanup pattern

useEffect(() => {
  let unlisten: (() => void) | null = null;
  
  listen('event-name', handler).then(fn => { unlisten = fn; });
  
  return () => { unlisten?.(); };
}, []);

---

5. Z-Index Hierarchy

KHÔNG dùng z-index tùy tiện. Tuân theo bảng sau:

Z-index	Dùng cho
z-10	Resize handles nền
z-30	StressTester maximize button
z-50	TitleBar, StatusBar, dropdowns thông thường, modal fixed inset-0
z-[100]	SettingsPanel (modal backdrop)
z-[9000]	Notification toasts & panel — trên mọi thứ trừ pinned overlay
z-[9999]	OverlayPlusMenu, SnippetManager modal
overlay.zIndex	Overlay window thường (dynamic, bắt đầu ~1)
overlay.zIndex + 10000	isPinned overlay — luôn trên cùng
overlay.zIndex + 15000	Drag ghost layer khi đang kéo

Rule: Notification (z-9000) thắng tất cả trừ pinned overlay (≥10001).

---

6. Database Schema Reference

DB 1: zetacp-settings.db — Global, 1 file duy nhất

Bảng	Columns	Ghi chú
Settings	key TEXT PK, value TEXT	Global config: compiler.gpp_path, compiler.python_path, compiler.default_flags, judge.threads
RecentProjects	path TEXT PK, last_open INTEGER	Unix timestamp
Snippets	id INT PK, trigger TEXT, description TEXT, code TEXT, language TEXT, is_default INT	UNIQUE(trigger, language)

Đọc settings từ BE:

let val = sqlx::query_scalar::<_, String>("SELECT value FROM Settings WHERE key = ?")
    .bind("compiler.gpp_path")
    .fetch_optional(&state.settings_db)
    .await?;

DB 2: ZetaCP.db — Per source directory (<dir>/.ZetaCP/ZetaCP.db)

Bảng	Columns key	Phân loại	Ghi chú
TestcaseMeta	id PK, file_path, name, order_index, subtask_id, is_active	Domain core	Index: (file_path, order_index)
TestcaseData	id PK FK(Meta), input, expected_output	Heavy data	CASCADE delete khi xóa Meta
TestcaseResult	id PK FK(Meta), last_status, exec_time_ms, memory_kb, actual_output, diff_info, run_at	Heavy operational	(Lưu ý: Bảng này chỉ còn phục vụ hiển thị nhanh cho testcase, các bản ghi chi tiết đã chuyển sang bảng Runs)
Subtask	id PK, file_path, name, max_score, order_index	Domain core
CompileCache	file_path PK, source_hash, binary_path, compiled_at	Ephemeral	Hash = SHA-256 source
ExecutionConfig	file_path PK, compiler_flags, interpreter_flags, io_mode, input_file, output_file, time_limit_ms, memory_limit_kb, run_mode, checker_type, custom_checker_path, custom_checker_binary	Config chạy	Chứa cài đặt cấu hình chạy & dịch cơ bản
StressConfig	file_path PK FK(ExecutionConfig), brute_path, sol_path, gen_path, gen_mode, gen_time_limit_ms, gen_memory_limit_kb, brute_time_limit_ms, brute_memory_limit_kb	Config Stress	Lưu cấu hình Stress test tách biệt
Runs	id PK, run_type, parent_id, file_path, verdict, exec_time_ms, memory_kb, actual_output, diff_info, run_at, extra_json	Heavy operational	Bảng ghi lịch sử chạy tập trung (Stress + Judge)
OverlayState	id PK, file_path, type, title, content, x, y, width, height, ...	UI session

Lưu ý về backward compatibility: Bảng cũ FileSettings (20 cột) vẫn được giữ lại trong database và đồng bộ hai chiều thông qua các SQLite triggers (file_settings_after_insert, file_settings_after_update, file_settings_after_delete) để tránh gây lỗi cho frontend cũ chưa nâng cấp. Tuy nhiên, code mới nên ưu tiên đọc/ghi trực tiếp vào ExecutionConfig và StressConfig.

Lấy project DB pool từ BE:

// create_if_missing = true: tạo DB nếu chưa có
// create_if_missing = false: trả None nếu chưa có
let proj_db = state.get_db_pool(&file_path, true).await?.unwrap();

---

7. Types Reference (Frontend)

Key types — import từ @/types/testcase

import {
  TestcaseMeta,    // { id, filePath, name, orderIndex, subtaskId, isActive }
  TestcaseData,    // { id, input, expectedOutput }
  TestcaseResult,  // { id, lastStatus, execTimeMs, memoryKb, actualOutput, diffInfo, runAt }
  Subtask,         // { id, filePath, name, maxScore, orderIndex }
  FileSettings,    // { filePath, compilerFlags, ioMode, timeLimitMs, ... }
  FileContext,     // { subtasks, metas, results, settings }
  DiffLine,        // { line, expected, actual }
  JudgeProgress,   // { testcaseId, status, result? }
} from '@/types/testcase';

GlobalSettings — import từ @/types/settings

interface GlobalSettings {
  'compiler.gpp_path': string;
  'compiler.python_path': string;
  'compiler.default_flags': string;
  'judge.threads': string;  // số thread, stored as string
  // ... các key khác
}

---

8. Component Mounting Pattern

Thêm component global mới vào App

// src/App.tsx — cuối MainApp return, sau InternalOverlayContainer
return (
  <div className="flex flex-col h-screen ...">
    {/* ... panels ... */}
    <InternalOverlayContainer />
    <NotificationCenter />       {/* ← thêm tương tự đây */}
    <MyNewGlobalComponent />
  </div>
);

Thêm tab vào ActivityBar (left sidebar)

// App.tsx — trong Panel left, thêm case vào switch activeTab
{activeTab === 'my-tab' ? (
  <MyComponent />
) : /* ... */}

Overlay floating window

// Tạo overlay mới
await useOverlayStore.getState().addOverlay('scratchpad', 'Title', 'initial content');
// Types: 'scratchpad' | 'notes' | 'md' | 'image' | 'pdf' | 'notification' | 'diff-viewer'

---

9. Codicons Reference (hay dùng)

codicon-error          → lỗi (đỏ)
codicon-warning        → cảnh báo (vàng)
codicon-info           → thông tin (xanh)
codicon-pass-filled    → thành công (xanh)
codicon-bell           → notification
codicon-bell-slash     → no notification
codicon-terminal       → terminal/console
codicon-play           → run/execute
codicon-debug-stop     → stop
codicon-loading        → loading (spinner với animate-spin)
codicon-close          → đóng
codicon-chevron-down   → collapse/expand
codicon-refresh        → reload
codicon-gear           → settings
codicon-file           → file
codicon-folder         → folder
codicon-eye / codicon-eye-closed  → show/hide
codicon-pin / codicon-pinned      → pin overlay

Dùng: <span className="codicon codicon-error text-[14px] text-red-400" />

---

10. Checklist trước khi submit code

• Mọi invoke() catch đều gọi notify.fromTauriError()
• Mọi BE command trả Result<T, ZetaError> — không unwrap()
• Process spawn qua run_in_sandbox() — không Command::new() trực tiếp
• Z-index dùng đúng bảng phân tầng
• Không thêm cột vào FileSettings, ExecutionConfig, hay StressConfig — tạo bảng mới nếu cần
• Migration file mới: vN.sql + đăng ký trong db/mod.rs
• Không tự viết lại logic resolve_verdict hay compile_cpp — sử dụng các module dùng chung dưới judge/

---

11. Rust Backend Unified Modules

Khi thực thi chạy, dịch hoặc kiểm thử trong các Tauri command mới, bắt buộc phải gọi các hàm tiện ích đã được unify dưới đây:

1. Biên dịch C++ thống nhất (judge/compiler.rs)

pub async fn compile_cpp(
    state: &AppState,
    src_path: &Path,
    bin_path: &Path,
    flags: &[String],
    include_parent: bool, // true nếu cần nạp include path (.h) của thư mục chứa binary (stress test)
) -> Result<String, String> // Trả về Ok(stderr) nếu dịch thành công, Err(stderr) nếu thất bại

2. Chạy Sandbox (judge/runner.rs)

pub async fn execute_once(opts: &RunOptions) -> Result<RunResult, std::io::Error>

3. Phân tích kết quả chạy (judge/runner.rs)

pub fn resolve_verdict(
    stdout: &str,
    stderr: &str,
    success: bool,
    is_timeout: bool,
    memory_kb: i64,
    memory_limit_kb: i64,
    expected_output: Option<&str>,
    checker_type: Option<&str>,
) -> String // Trả về AC, WA, TLE, MLE, RE (tự nhận diện 8 MLE keywords hoa/thường)

4. Chạy Batch testcases song song (judge/orchestrator.rs)

pub async fn execute_batch(
    testcase_ids: Vec<String>,
    exec_path: String,
    args: Vec<String>,
    settings: FileSettings,
    run_dir: &Path,
    inp_name: String,
    out_name: String,
    proj_db: sqlx::SqlitePool,
    app_handle: tauri::AppHandle,
    concurrency: usize,
    cancel_token: Arc<AtomicBool>,
) -> Result<Vec<TestcaseResult>, ZetaError> // Tự động quản lý luồng Semaphore, cancellation, và phát event "judge-batch-progress" tăng dần đều.