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}.