# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **uni-app x** project — DCloud's cross-platform app framework that compiles to native Android, iOS, HarmonyOS, H5, and various mini-programs. The `assistant` directory is the project root.

- **Language**: UTS (uni-app TypeScript) — a TypeScript superset that compiles to platform-native code
- **UI Framework**: Vue 3 with Composition API (`<script setup>` pattern)
- **Current target**: Android (`platformConfig.json` targets `APP-ANDROID`)
- **Template files**: `.uvue` (uni-app Vue single-file components)

## Build & Development

This project is designed for **HBuilderX IDE** (DCloud's IDE). Development, building, and debugging are done through the IDE rather than CLI commands.

- Open the `assistant` directory in HBuilderX
- Use HBuilderX's **Run** menu to launch on a device/emulator (Android, iOS, H5, or mini-program)
- Build outputs go to the `unpackage/` directory (gitignored)
- HBuilderX handles the UTS → platform-native compilation pipeline

## Architecture

### Entry Flow

```
index.html → main.uts → App.uvue → pages/index/index.uvue
```

1. **`index.html`** — H5/web entry point; for native apps this is largely a bootstrap shell
2. **`main.uts`** — Creates the Vue 3 app instance via `createSSRApp(App)` and exports `createApp()`. This SSR pattern is standard for uni-app x — the framework calls `createApp()` to instantiate the app on each platform.
3. **`App.uvue`** — Root component. Contains app-level lifecycle hooks (`onLaunch`, `onAppShow`, `onAppHide`, `onLastPageBackPress`, `onExit`) and global CSS classes (`.uni-row`, `.uni-column`).
4. **`pages/index/index.uvue`** — The single page of this app; defined in `pages.json`.

### Key Configuration Files

- **`pages.json`** — Page routing (the `pages` array), global navigation bar style, and `uniIdRouter` (for uni-id authentication routing). The first entry in `pages` is the launch page.
- **`manifest.json`** — App identity (`appid`, `name`, `version`), cross-platform config (WeChat/Alipay/Baidu/Toutiao mini-program settings), and Vue version (`"vueVersion": "3"`). The `uni-app-x` key enables uni-app x mode.
- **`platformConfig.json`** — Declares which native platforms to build for (currently Android only).
- **`uni.scss`** — SCSS design tokens (colors, font sizes, spacing, border radius, opacity). These variables are automatically available in all `.uvue` components without importing. Use these variables to maintain visual consistency.

### Platform-Specific Code

Use preprocessor directives in `.uts`/`.uvue` files to gate platform-specific logic:

```uts
// #ifdef APP-ANDROID || APP-HARMONY
// Android/HarmonyOS-only code
// #endif

// #ifdef MP-WEIXIN
// WeChat mini-program-only code
// #endif
```

See `App.uvue` for an example — the back-press double-tap-to-exit logic is Android-only.

### Static Assets

Place static files in `static/`. Reference them in templates with `/static/...` paths (e.g., `/static/logo.png`).

## UTS Notes

- UTS is structurally like TypeScript but compiles differently per platform target
- `uni.*` APIs (e.g., `uni.showToast()`, `uni.exit()`) are the cross-platform API surface — see [uni-app x API docs](https://doc.dcloud.net.cn/uni-app-x/api/)
- `ref()` and other Vue 3 Composition API functions are available globally in `<script setup>` blocks