ewa-mobile/AGENTS.md

AGENTS.md

Project Overview

ewa-mobile is a Vue 3 + Vite + Vant frontend with a Tauri 2 Rust backend.

The app uses local and remote model resources exposed through che-tauri, which is built on top of che-orm. Frontend model access should go through the generated TypeScript API in src/generated.

Main Stack

• Vue 3 with <script setup> single-file components.
• TypeScript with strict checks enabled.
• Vite for frontend dev/build.
• Vant for mobile UI components.
• Vue Router with hash history.
• Tauri 2 backend in src-tauri.
• SQLite local storage through che-orm.
• Remote REST integration through che-tauri and reqwest.

Important Paths

Frontend:

• package.json: npm scripts and frontend dependencies.
• vite.config.ts: Vite/Tauri dev server config.
• tsconfig.json: strict TypeScript config.
• src/main.ts: Vue app bootstrap.
• src/App.vue: shell layout, nav bar, tabbar.
• src/app/router/index.ts: main router and auth guard.
• src/apps/auth: login feature.
• src/apps/tasks: task list/detail/create feature.
• src/apps/contracts: contract list/detail/PDF feature.
• src/apps/users: users feature.
• src/apps/personnel: personnel shared UI.
• src/shared/auth/useAuth.ts: frontend auth state and token restore.
• src/shared/composables/useModelApi.ts: shared model API loading helper.

Generated frontend API:

• src/generated/api_client.ts
• src/generated/api.ts
• src/generated/models.ts

Tauri backend:

• src-tauri/Cargo.toml: Rust backend dependencies.
• src-tauri/tauri.conf.json: Tauri app config.
• src-tauri/app.toml: database and remote API config.
• src-tauri/src/lib.rs: Tauri commands and API initialization.
• src-tauri/src/main.rs: native entry point.
• src-tauri/src/bin/manage.rs: management CLI entry point.
• src-tauri/src/apps/mod.rs: installed app list.
• src-tauri/src/sync.rs: contract sync and file download logic.

Installed Backend Apps

Current che-tauri app modules:

• users
• frcapp
• projectapp
• personemanagment
• contractapp

Each app usually contains:

• models.rs: che_orm::Model structs.
• serializers.rs: frontend/remote field mapping.
• filters.rs: list filter metadata and remote query mapping.
• mod.rs: resource registration.
• migrations/: local SQLite migration SQL and schema.json when applicable.

Commands

Install dependencies:

npm install

Frontend development:

npm run dev

Frontend build/typecheck:

npm run build

Tauri development:

npm run tauri dev

Tauri build:

npm run tauri build

Backend checks:

cd src-tauri
cargo fmt
cargo check

Management CLI from src-tauri:

cd src-tauri
cargo run --bin manage -- migrate
cargo run --bin manage -- generate-ts --out ../src/generated

Create or update migrations for one backend app:

cd src-tauri
cargo run --bin manage -- makemigrations <app>
cargo run --bin manage -- migrate <app>

Generated API Rules

• Do not manually edit files under src/generated unless explicitly requested.
• Generated API is produced from Rust app/module metadata.
• After changing backend models, serializers, filters, or resources, regenerate TypeScript:

cd src-tauri
cargo run --bin manage -- generate-ts --out ../src/generated

• Frontend code should import model APIs from src/generated/api, for example:

import { taskApi } from "../../../generated/api";

• Shared loading/list state should prefer useModelApi from src/shared/composables/useModelApi.ts.

Tauri Commands

Commands are registered in src-tauri/src/lib.rs.

Important commands:

• che_api: generic model API dispatch used by generated API client.
• auth_login: remote token login.
• auth_set_token: restore saved token into backend state.
• auth_logout: clear backend token.
• auth_status: backend auth status.
• current_employee: fetch current employee from remote API.
• sync_contracts: sync contracts and application files into local SQLite.
• load_application_file: load a local file or download it from remote URL.

Adding Or Changing A Resource

For local SQLite-backed resources:

1. Edit src-tauri/src/apps/<app>/models.rs.
2. Update serializers.rs.
3. Update filters.rs if frontend list filtering needs the field.
4. Register or adjust the resource in <app>/mod.rs.
5. Run cargo run --bin manage -- makemigrations <app> from src-tauri.
6. Run cargo run --bin manage -- migrate <app> from src-tauri if local DB needs updating.
7. Run cargo run --bin manage -- generate-ts --out ../src/generated.
8. Run npm run build from project root.

For remote-only resources:

• Use ctx.remote_resource or ctx.mapped_remote_resource in the app module.
• Keep serializer Field::source(...) mappings aligned with remote JSON field names.
• Keep filters aligned with backend query params and generated frontend list params.
• Regenerate TS after resource metadata changes.

Frontend Conventions

• Use Vue 3 <script setup lang="ts">.
• Keep TypeScript strict-mode clean: no unused locals or parameters.
• Prefer existing Vant components and the current mobile layout language.
• Preserve current feature grouping under src/apps/<feature>.
• Use generated API types from src/generated/models.
• Keep auth-sensitive routes guarded with route metadata and the router guard in src/app/router/index.ts.
• Do not bypass useAuth for login/logout/token restore unless changing auth architecture intentionally.

Backend Conventions

• Keep Rust formatted with cargo fmt.
• Use che_orm::Model for model structs.
• Keep model, serializer, filter, resource registration, migration, and generated TS in sync.
• Prefer management CLI for migrations instead of hand-writing migration files.
• Do not edit old migration files unless the task is specifically migration repair.
• Avoid inspecting or modifying src-tauri/target and generated Android build artifacts unless the task requires it.

Config And Local Data

• src-tauri/app.toml contains database and remote API settings.
• src-tauri/src/lib.rs currently constructs AppConfig inline; do not assume app.toml is always the runtime source of truth.
• src-tauri/ewa-mobile.sqlite is a local SQLite artifact.
• Remote API URLs may be environment-specific and may not be reachable on every machine.

Validation Checklist

Frontend-only change:

npm run build

Tauri backend-only change:

cd src-tauri
cargo fmt
cargo check

Backend metadata or generated API change:

cd src-tauri
cargo fmt
cargo check
cargo run --bin manage -- generate-ts --out ../src/generated
cd ..
npm run build

Full app confidence check:

npm run build
cd src-tauri
cargo fmt
cargo check