weather-data/weather-data-ui/CLAUDE.md

# CLAUDE.md - weather-data-ui

This file provides guidance to Claude Code when working in the weather-data-ui module.

## Purpose

Vue 3 + TypeScript frontend for the weather data management system. Single-page application built with Vite 5.

## Tech Stack

- Vue 3.5 (Composition API), TypeScript 5.7, Vite 5.4
- Element Plus 2.10 (UI library)
- Pinia 2.3 (state management)
- Vue Router 4.2 (hash mode routing)
- ECharts 5 + vue-echarts 6 (charts)
- Axios 1.11 (HTTP client)
- Less/Sass for styling

## Build Commands

```bash
npm install
npm run dev          # dev server on port 8001, hot reload, proxies /api to backend
npm run build        # production build (vite build --mode production), outputs to dist/
npm run lint         # ESLint on src/**/*.{vue,ts} with --fix
npm run serve        # build + vite preview
```

## Project Structure

```
src/
├── main.ts                    # App bootstrap, Pinia init
├── App.vue                    # Root component
├── assets/                    # Static assets (css, icons, images, theme)
├── components/                # Reusable components
│   ├── alert-marquee/         # Alert scrolling marquee (SSE-driven)
│   ├── base/                  # Base table/form/dialog wrappers
│   ├── sys-dept-tree/         # Department tree selector
│   ├── sys-radio-group/       # Radio group with dict-driven options
│   ├── sys-region-tree/       # Region tree selector
│   ├── sys-select/            # Dict-driven select dropdown
│   └── wang-editor/           # Rich text editor wrapper
├── composables/               # Vue 3 composables
│   ├── useAlertMarquee.ts     # SSE alert streaming logic
│   ├── useFloatingDrag.ts     # Draggable floating panel logic
│   ├── useWeatherChart.ts     # ECharts chart configuration
│   ├── useWeatherConstants.ts # Weather domain constants
│   ├── useWeatherExport.ts    # Export to Excel/PDF
│   ├── useWeatherFilter.ts    # Query filter state management
│   └── useWeatherStats.ts     # Statistical computation
├── constants/                 # Application constants
│   ├── app.ts                 # API base URL, request timeout
│   ├── cacheKey.ts            # Cache key enums
│   ├── config.ts              # App config
│   └── enum.ts                # Enums (EMitt events, etc.)
├── hooks/                     # Legacy hooks
│   └── useView.ts             # View loader for dynamic routes
├── layout/                    # Layout components
│   ├── index.vue              # Main layout with sidebar + header
│   ├── layout.vue             # Alternative layout
│   ├── fullscreen-layout.vue  # Fullscreen page layout
│   ├── header/                # Top header bar
│   ├── sidebar/               # Left sidebar navigation
│   └── view/                  # Content view wrapper (tabs)
├── router/
│   ├── index.ts               # Router instance + dynamic route registration
│   └── base.ts                # Static base routes (login, home, error, iframe)
├── service/
│   └── baseService.ts         # HTTP helpers: get/post/put/delete/upload
├── store/
│   ├── index.ts               # useAppStore (user, permissions, menus, routes, tabs)
│   └── importTasks.ts         # Import task progress store
├── types/                     # TypeScript type definitions
├── utils/
│   ├── cache.ts               # Cookie/localStorage cache helpers (token storage)
│   ├── chartBuilder.ts        # ECharts option builder
│   ├── emits.ts               # Event bus (mitt)
│   ├── exportReport.ts        # PDF/Excel export utilities
│   ├── http.ts                # Axios instance with interceptors
│   ├── router.ts              # Route merging and registration helpers
│   ├── theme.ts               # Theme switching logic
│   └── utils.ts               # General utility functions
└── views/                     # Feature views
    ├── dailyweather/          # Daily weather data query/import/charts
    ├── home.vue               # Dashboard home page
    ├── iframe.vue             # Iframe wrapper for external pages
    ├── job/                   # Scheduled job management
    ├── login.vue              # Login page
    ├── oss/                   # Cloud file storage management
    ├── region/                # Region management
    ├── station/               # Weather station management
    ├── sys/                   # System management (users, roles, menus, depts, dicts, alerts)
    ├── tools/                 # Utility tools
    └── weather/               # Weather data views
```

## Router Architecture

- **Mode**: `createWebHashHistory()` (hash mode)
- **Dynamic routing**: On login, `useAppStore.initApp()` fetches `/sys/menu/nav` (menu tree), `/sys/menu/permissions` (perms), `/sys/user/info` (user), `/sys/dict/type/all` (dicts). Menu data is merged with `src/views/**/*.vue` component map via `mergeServerRoute()` to build the full route table.
- **Auto-registration**: `registerDynamicToRouterAndNext()` can register a new route at runtime by matching path to a view component file.
- **Tab tracking**: Router `beforeEach` guard emits tab push events; tabs are tracked in store state.
- **404 fallback**: Unmatched routes redirect to `/error` with `to=404` query param.

## State Management (Pinia)

`useAppStore` holds all application state:
- `appIsLogin`, `appIsReady`, `appIsRender` -- lifecycle flags
- `permissions[]` -- user permission set (strings)
- `user` -- current user object
- `dicts[]` -- dictionary data array
- `routes[]` -- resolved route records
- `routeToMeta` -- path-to-metadata mapping for tab titles
- `tabs[]`, `activeTabName`, `closedTabs` -- tab management

`initApp()` is called once on login -- returns merged routes that are then registered with the router.

## HTTP Layer

`utils/http.ts` creates an Axios instance:
- **Request interceptor**: Injects `token` header from cache, adds `_t` timestamp to GET requests, handles form-urlencoded serialization
- **Response interceptor**: `code === 0` means success; `code === 401` triggers redirect to `/login`; other codes show ElMessage error

`service/baseService.ts` wraps HTTP methods:
- `get(path, params, headers)` -- adds cache-busting `_t`
- `post(path, body, headers)` -- JSON content-type
- `put(path, params, headers)` -- JSON content-type
- `delete(path, params)` -- sends body
- `upload(path, formData, headers)` -- multipart form upload

## SSE Alert Integration

`composables/useAlertMarquee.ts` manages SSE connection lifecycle. It connects to the backend SSE endpoint and dispatches `alert`, `alert-withdrawn`, and `alert-deleted` events to the `alert-marquee` component for real-time notification display.

## Environment Variables

- `VITE_APP_API`: Backend API base URL (injected into `constants/app.ts` at build time)
- `.env.development` / `.env.production`: Environment-specific configs

## Key Dependencies

- `@vueuse/core`: Vue composition utilities
- `mitt`: Lightweight event emitter
- `nprogress`: Page load progress bar
- `html2canvas` + `jspdf`: Client-side PDF export
- `js-cookie`: Cookie management (token storage)
- `qs`: Query string parsing/serialization