# CLAUDE.md — weather-data-ui

Frontend module: Vue 3 / Vite 5 / TypeScript SPA.

---

## Code Style

- **No emoji in UI strings.** Plain Chinese text for labels, buttons, status.
- **No emoji in code comments or docstrings.** Plain text only.
- **Keep CLAUDE.md current** — whenever code is modified, added, deleted, or any file change affects the module structure, build, conventions, or component patterns, update this file (and the root `CLAUDE.md` if cross-cutting) in the same commit to reflect the new state. Stale documentation is a bug.

---

## Commands

```bash
npm install                    # install dependencies
npm run dev                    # Vite dev server (port 8001, host 0.0.0.0)
npm run build / npm run build:prod  # production build
npm run serve                  # preview production build
npm run lint                   # lint with autofix (ESLint)
npx vue-tsc --noEmit           # type-check (not in pre-commit)
```

Pre-commit: `lint-staged` runs `eslint --fix` on `*.ts`/`*.vue` via `yorkie` git hooks (not husky). No test runner configured.

## Stack

- Vite 5 + Vue 3 + TypeScript SPA
- Element Plus + Element Plus Icons (all icons registered globally)
- `vue-router` with **hash history** (`createWebHashHistory`)
- Pinia for state management
- Axios via `src/utils/http.ts` + `src/service/baseService.ts`
- API base URL: `VITE_APP_API` env var, overridable at runtime by `window.SITE_CONFIG.apiURL`

## Environment config

- Dev: `VITE_APP_API=http://192.168.2.186:8080/system-admin` (hardcoded IP — new devs must change)
- Prod: `VITE_APP_API=/system-admin` (relative, proxied via Nginx)
- Runtime override takes priority: `window.SITE_CONFIG.apiURL`

## Vite config

- `base: "./"` (relative paths), `chunkSizeWarningLimit: 1024`
- Manual chunks: `lodash` and `vlib` (vue/vue-router/element-plus)
- Dev: HMR overlay disabled, `host: "0.0.0.0"`, port 8001

## Axios HTTP pattern

- Success check: `response.data.code === 0` (not `=== 200`)
- Request interceptor: adds `token` header, `X-Requested-With`, request timing, cache-busting `_t` on GET
- On `code === 401`: auto-redirects to `/login`
- Response unwrapped: callers receive `response.data`
- File exports: bypass Axios, use `window.location.href` with token as query param
- Uploads: no `Content-Type` set (browser auto-sets for `FormData`)

## Routing & state

- `src/router/base.ts`: 7 base routes (`/`, `/home`, `/login`, `/user/password`, `/iframe/:id?`, `/error`, 404 catch-all)
- `src/router/index.ts`: `beforeEach` guard — auth check, dynamic route registration from backend menus, tab management. Routes are dynamically added via `addRoute` with **flattened nested routes** (keep-alive limitation). View components resolved via `import.meta.glob("/src/views/**/*.vue")`.
- `src/store/index.ts` (`useAppStore`): monolithic store — all state nested in `state.state` (double nesting, e.g. `store.state.appIsLogin`). `initApp` fetches menus/permissions/user/dicts in 4 parallel requests.
- `src/store/importTasks.ts`: separate store for import task tracking (computed getters: `activeTasks`, `hasActiveTasks`, `recentTasks`).
- `src/utils/router.ts`: converts backend menu records → Vue router records, supports iframe/external links with `openStyle` flags.

Layout is event-driven: `src/layout/` shell + `mitt` event bus (`src/utils/emits.ts`). The `EMitt` enum defines events for sidebar, theme, tabs, layout changes. **Trace both the Pinia store and mitt events** when changing navigation/sidebar/tabs/theme.

Header right side: notification bell (combined badge) → `expand` (user menu). The old `import-task-indicator.vue` has been removed in favor of the notification center drawer.

## Common page pattern: `useView` hook

Admin CRUD pages use `src/hooks/useView.ts` for shared list-page workflow.

Key behaviors to know before refactoring:
- `closeCurrentTab()`: if tabs enabled, emits `OnCloseCurrTab` mitt event; otherwise navigates to `/home`.
- `exportHandle()`: uses `window.location.href` with token as query param (NOT Axios).
- `dataListSortChangeHandle()`: converts camelCase → snake_case for backend (e.g. `stationId` → `station_id`).
- `createdIsNeed: true` / `activatedIsNeed: false` by default. Pages needing refresh on tab activation must set `activatedIsNeed: true`.
- Includes workflow helpers (`handleFlowRoute`, `flowDetailRoute`) hardcoded to `/flow/task-form`.

## Cache utility

All cache keys prefixed with `v1@` to avoid collisions. Supports `localStorage` and `sessionStorage` (token uses sessionStorage). JSON serialization is automatic. `getCache` supports auto-delete-after-read (`isDelete` flag).

## Weather frontend module

The home dashboard (`src/views/home.vue`) uses a **composable-based architecture**:

| Composable | Responsibility |
|---|---|
| `useWeatherConstants.ts` | Rain levels, temperature thresholds, filter field definitions, `fmtVal()`, level/class helpers |
| `useWeatherFilter.ts` | Filter state, toggle/reset/match logic, `matchOp()` |
| `useWeatherStats.ts` | `computeStats()`, `buildStatCards()`, `buildSummary()`, `rainLevelDistribution`, `WeatherDataRow` type |
| `useWeatherChart.ts` | ECharts dynamic import, `buildChartOption()`, `ResizeObserver`, precise trigger key (not deep watch) |
| `useWeatherExport.ts` | PNG/PDF export with dynamic `html2canvas`/`jspdf` imports, loading indicator |

Supporting utils: `src/utils/chartBuilder.ts`, `src/utils/exportReport.ts`.

## Critical rules

### 1. Null ≠ zero — missing data MUST be preserved as null
When mapping backend API responses to frontend models, **never** default missing numeric values to `0`. Rainfall of `0mm` means "no rain that day" (valid measurement); `null` means "no data available" (missing record). Use `: null` not `: 0` in data mapping, and display `"—"` for null values via `fmtVal()`.

```typescript
// ✅ Correct
rainfall: row.rain2020 != null ? +row.rain2020 : null,

// ❌ Wrong — confuses "no data" with "measured zero"
rainfall: row.rain2020 != null ? +row.rain2020 : 0,
```

All helper functions must accept `number | null` and return `"—"` or `""` for null. Stats computations must skip null values.

### 2. Heavy libraries must use dynamic imports
`html2canvas`, `jspdf`, and `echarts` are NOT imported at module level. Load them via `await import()` only when triggered by user action. This saves ~600KB from the initial bundle.

### 3. Fonts are self-hosted — no external network dependency
Fonts (Noto Sans SC, JetBrains Mono) are bundled via `@fontsource/*` packages, imported in `src/main.ts`. Do NOT add Google Fonts `<link>` tags or `@import` back — the system runs on intranet where external network may be unavailable. To add a new font weight, import the corresponding fontsource CSS file in `main.ts`.

### 4. Export must show user feedback
Always show `ElLoading.service` fullscreen and `ElMessage` success/failure. Disable the export button during rendering.

### 5. Deep watchers on filter objects are banned
Never use `watch(filters, callback, { deep: true })`. Derive a precise computed trigger key (e.g. `dataHash`, `filteredHash`, `extremesVersion`) and watch that instead.

## Notification center

The global notification system (`src/components/alert-marquee/index.vue`) aggregates two feed types:

| Feed | Source | Clickable? |
|---|---|---|
| System alerts | `useAlertMarquee.ts` composable (polls `/sys/alert/active/since` every 30s) | Yes — opens detail dialog |
| Import tasks | `useImportTaskStore` Pinia store | No — shows real-time progress inline |

### Components & composables

| File | Role |
|---|---|
| `src/composables/useAlertMarquee.ts` | Module-level singleton: message queue, drawer toggle, detail dialog state, scrollbar position. Real-time delivery: SSE (`/sys/alert/stream`) primary + 10s polling fallback. Exports danger-specific computed: `dangerMessages`, `latestDangerMessage`, `dangerCount`, `hasDangerMessages` |
| `src/composables/useFloatingDrag.ts` | Pointer Events drag logic: `setPointerCapture`, viewport clamping, deferred `isDragging` (activates only on >3px move), `dragMoved` flag to distinguish drag vs click |
| `src/components/alert-marquee/index.vue` | Floating scrollbar (640px wide, centered top, draggable) + `el-drawer` notification center + `el-dialog` detail popup |
| `src/layout/header/base-header.vue` | Bell button with combined badge (alerts + active import tasks), toggles drawer |
| `src/store/importTasks.ts` | Import task CRUD: `addTask`, `updateTask`, `removeTask`, `clearCompleted`; getters: `activeTasks`, `recentTasks` |

### Level-based routing

- **danger (紧急)**: triggers the floating scrollbar + appears in notification center drawer + bell badge
- **warning / info (警告 / 提示)**: notification center drawer + bell badge only (no scrollbar)
- The bell badge in base-header always shows total count (all levels + active import tasks)

### Floating scrollbar behavior

- Visible only when logged in (`appStore.state.appIsLogin`) and has danger-level alerts (`hasDangerMessages`)
- Positioned centered at top (`y: 56` below header), draggable to reposition, re-centers on window resize
- Shows latest alert headline + count badge
- **Close button** hides the bar; **auto-reappears** when new danger alerts arrive (watch on `dangerCount`)
- **查看详情** button opens `el-dialog` with full alert text
- The old `import-task-indicator.vue` (bell icon with popover in header) has been **removed**

### Import progress integration

1. Upload via `baseService.upload()` (FormData, no explicit Content-Type).
2. On upload start, toast: `"导入已开始，可在通知中心查看进度"`.
3. Poll `GET .../import/progress/{backendTaskId}` every 3 seconds.
4. Update Pinia store (`useImportTaskStore`) — progress bar + status tag render reactively in the drawer.
5. On completion: green checkmark; on failure: red cross + error message. Completed/failed tasks show a dismiss button.

### Alert management page

Manual alert CRUD at route `sys/system-alert`:

| File | Role |
|---|---|
| `src/views/sys/system-alert.vue` | List page: `useView`-based, search by level/title/sourceType, batch delete, per-row withdraw |
| `src/views/sys/system-alert-add-or-update.vue` | Add/edit dialog: level (info/warning/danger), title, content (textarea), sourceType, expireTime (datetime picker) |

Backend endpoints under `/sys/alert`:
- `GET /page` — paginated list (`sys:alert:page`)
- `GET /{id}` — detail (`sys:alert:info`)
- `POST /` — create (`sys:alert:save`)
- `PUT /` — update (`sys:alert:update`)
- `DELETE /` — batch delete (`sys:alert:delete`)
- `PUT /{id}/withdraw` — soft-withdraw (`sys:alert:update`)
- `GET /active`, `GET /active/since` — frontend polling (no permission required)