sansenhoshi/weather-data
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

项目优化，构建文件Lombok异常问题修复

Browse Source
This commit is contained in:
sansenhoshi
2026-06-29 13:55:42 +08:00
parent 53b3b2c989
commit 0799f9cb4d
47 changed files with 1034 additions and 865 deletions
Download Patch File Download Diff File Expand all files Collapse all files
weather-data-ui/CLAUDE.md
+122 -158
View File
@@ -1,184 +1,148 @@
# CLAUDE.md — weather-data-ui
# CLAUDE.md - weather-data-ui
Frontend module: Vue 3 / Vite 5 / TypeScript SPA.
This file provides guidance to Claude Code when working in the weather-data-ui module.
---
## Purpose
## Code Style
Vue 3 + TypeScript frontend for the weather data management system. Single-page application built with Vite 5.
- **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.
## 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
## Commands
## Build 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)
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
```
Pre-commit: `lint-staged` runs `eslint --fix` on `*.ts`/`*.vue` via `yorkie` git hooks (not husky). No test runner configured.
## Project Structure
## 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,
```
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
```
All helper functions must accept `number | null` and return `"—"` or `""` for null. Stats computations must skip null values.
## Router Architecture
### 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.
- **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.
### 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`.
## State Management (Pinia)
### 4. Export must show user feedback
Always show `ElLoading.service` fullscreen and `ElMessage` success/failure. Disable the export button during rendering.
`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
### 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.
`initApp()` is called once on login -- returns merged routes that are then registered with the router.
## Notification center
## HTTP Layer
The global notification system (`src/components/alert-marquee/index.vue`) aggregates two feed types:
`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
| 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 |
`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
### Components & composables
## SSE Alert Integration
| 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` |
`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.
### Level-based routing
## Environment Variables
- **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)
- `VITE_APP_API`: Backend API base URL (injected into `constants/app.ts` at build time)
- `.env.development` / `.env.production`: Environment-specific configs
### Floating scrollbar behavior
## Key Dependencies
- 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)
- `@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