# 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:

```bash
npm install
```

Frontend development:

```bash
npm run dev
```

Frontend build/typecheck:

```bash
npm run build
```

Tauri development:

```bash
npm run tauri dev
```

Tauri build:

```bash
npm run tauri build
```

Backend checks:

```bash
cd src-tauri
cargo fmt
cargo check
```

Management CLI from `src-tauri`:

```bash
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:

```bash
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:

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

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

```ts
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:

```bash
npm run build
```

Tauri backend-only change:

```bash
cd src-tauri
cargo fmt
cargo check
```

Backend metadata or generated API change:

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

Full app confidence check:

```bash
npm run build
cd src-tauri
cargo fmt
cargo check
```