JGJS2026/CLAUDE.md

# CLAUDE.md

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

# 任何项目都务必遵守的规则（极其重要！！！）

## Communication

- 永远使用简体中文进行思考和对话

## Documentation

- 编写 .md 文档时，也要用中文
- 正式文档写到项目的 docs/ 目录下
- 用于讨论和评审的计划、方案等文档，写到项目的 discuss/ 目录下

## Code Architecture

- 编写代码的硬性指标，包括以下原则：
 （1）对于 Python、JavaScript、TypeScript 等动态语言，尽可能确保每个代码文件不要超过 500 行
 （3）每层文件夹中的文件，尽可能不超过 8 个。如有超过，需要规划为多层子文件夹
- 除了硬性指标以外，还需要时刻关注优雅的架构设计，避免出现以下可能侵蚀我们代码质量的「坏味道」：
 （1）僵化 (Rigidity): 系统难以变更，任何微小的改动都会引发一连串的连锁修改。
 （2）冗余 (Redundancy): 同样的代码逻辑在多处重复出现，导致维护困难且容易产生不一致。
 （3）循环依赖 (Circular Dependency): 两个或多个模块互相纠缠，形成无法解耦的“死结”，导致难以测试与复用。
 （4）脆弱性 (Fragility): 对代码一处的修改，导致了系统中其他看似无关部分功能的意外损坏。
 （5）晦涩性 (Obscurity): 代码意图不明，结构混乱，导致阅读者难以理解其功能和设计。
 （6）数据泥团 (Data Clump): 多个数据项总是一起出现在不同方法的参数中，暗示着它们应该被组合成一个独立的对象。
 （7）不必要的复杂性 (Needless Complexity): 用“杀牛刀”去解决“杀鸡”的问题，过度设计使系统变得臃肿且难以理解。
- 【非常重要！！】无论是你自己编写代码，还是阅读或审核他人代码时，都要严格遵守上述硬性指标，以及时刻关注优雅的架构设计。
- 【非常重要！！】无论何时，一旦你识别出那些可能侵蚀我们代码质量的「坏味道」，都应当立即询问用户是否需要优化，并给出合理的优化建议。
## Commands

- **Dev server**: `bun run dev` (uses `bunx --bun vite`)
- **Build**: `bun run build` (type-checks then bundles via Vite)
- **Type check only**: `bun run type-check`
- **Preview build**: `bun run preview`

No test runner is configured. Use Playwright for UI automation when needed (see AGENTS.md).

## Architecture Overview

This is a **browser-only Vue 3 SPA** — no backend, no SSR. All data is persisted client-side via IndexedDB (through localforage). The domain is **交通建设项目工程造价咨询** (transport infrastructure cost-consulting fee calculation for road, railway, and waterway projects).

### App Entry & Routing

There is no Vue Router. Navigation is tab-based, managed entirely by `useTabStore` (`src/pinia/tab.ts`). `src/App.vue` shows either `HomeEntryView` (first-launch onboarding) or the main `Tab` layout depending on `tabStore.hasCompletedSetup`.

The `Tab` layout (`src/layout/tab.vue`) renders the active tab's component by name using `defineAsyncComponent` with a map of component names → import paths.

### Workspace Modes

Defined in `src/lib/workspace.ts`. Three modes: `home`, `project`, `quick`. The current mode is persisted to `localStorage` under key `jgjs-workspace-mode-v1`. Two fixed/protected tab IDs exist: `ProjectCalcView` and `QuickCalcView` (and the quick-contract tab), which cannot be closed.

### State & Persistence

- **Pinia** is used for all state management with `pinia-plugin-persistedstate`.
- The persistence plugin is customized at `src/pinia/Plugin/indexdb` — it stores pinia state in IndexedDB (not localStorage), using localforage with `mode: 'multiple'` (each store in its own IndexedDB store named `pinia`).
- `useTabStore` (`src/pinia/tab.ts`): tab list, active tab, setup flag. Persisted.
- `useZxFwPricingStore` (`src/pinia/zxFwPricing.ts`): the core domain store. Manages contract-level 咨询服务 (consulting service) pricing state, per-service pricing method states, and contract extra-fee states. Uses a generic key/value layer (`getKeyState`/`setKeyState`/`loadKeyState`) backed by `useKvStore`.
- `useKvStore` (`src/pinia/kv.ts`): raw key-value access to IndexedDB via localforage.

### Data Layer (`src/sql.ts`)

Despite the name, there is no SQL database. `src/sql.ts` is a large static data file containing:
- `industryTypeList`: road / railway / waterway
- `majorList`: engineering specialties (E1–E4 codes) with coefficient ranges
- `serviceList`: consulting service types (D1–D5 codes) with pricing method flags
- `additionalWorkList`: extra work item definitions
- `exportFile`: Excel export logic using ExcelJS

All fee calculation formulas and coefficient tables live here.

### Lib Utilities (`src/lib/`)

- `decimal.ts` / `number.ts` / `numberFormat.ts`: safe arithmetic using `decimal.js`, thousand-separator formatting
- `zwArchive.ts`: AES-GCM encryption/decryption for `.zw` save files (import/export format). The key is derived from a fixed seed via SHA-256. File magic bytes: `JGJSZW`.
- `workspace.ts`: workspace mode constants and storage helpers
- `diyAgGridOptions.ts`: shared AG Grid configuration defaults
- `pricingScaleFee.ts` / `pricingMethodTotals.ts`: fee calculation helpers
- `projectWorkspace.ts` / `xmFactorDefaults.ts`: project-level workspace helpers
- `zxFwPricingSync.ts`: syncs pricing store state to/from IndexedDB on demand

### Views (`src/components/views/`)

Key views:
- `HomeEntryView.vue`: onboarding screen shown on first launch; dispatches `home-import-selected` DOM event on completion
- `ProjectWorkspaceView.vue` / `xmCard.vue`: project card workspace (项目卡片)
- `QuickCalcView.vue`: quick calculation mode
- `ZxFwView.vue`: 咨询服务 (consulting services) grid — the primary fee input view
- `Ht.vue` / `htCard.vue`: contract (合同) views
- `HtFeeMethodTypeLineView.vue`: per-service fee method line (rate/hourly/quantity-unit-price)
- `WorkContentGrid.vue`: AG Grid-based work content table

### AG Grid

AG Grid Enterprise is used throughout. Modules are registered once globally in `src/main.ts`. A license key is set there. Shared grid option defaults live in `src/lib/diyAgGridOptions.ts`.

### UI Components

Reka UI (headless component library) + Tailwind CSS v4 + `lucide-vue-next` icons + `@iconify/vue`. Shared UI primitives are in `src/components/ui/`. Tailwind is integrated as a Vite plugin (`@tailwindcss/vite`).

### Build

Vite 8 with rolldown. Output goes to `dist/` with `base: './'` (relative paths — important for local file:// deployment). Code-splitting separates `ag-grid`, `vue/pinia`, and `reka-ui` into distinct vendor chunks.

### Code Conventions

- All code comments are in Chinese.
- Composition API (`<script setup>`) everywhere.
- No Vue Router — use `useTabStore.openTab()` to navigate.
- Numeric calculations always go through `src/lib/decimal.ts` helpers to avoid floating-point errors.
- Storage keys follow patterns like `zxFW-{contractId}`, `tzGMF-{contractId}-{serviceId}`, `htExtraFee-{contractId}-{feeType}`.