Novel-Map/AGENTS.md

# AGENTS.md

This file contains guidelines for agentic coding assistants working in this repository.

## Project Overview
Vue 3 + Vite + Leaflet interactive map visualizing the novel "大唐双龙传" (The Twin of Brothers), showing factions, locations, character routes, and key events across 20 volumes.

## Commands

### Build & Dev
- `cd frontend && npm run dev` - Start dev server (http://localhost:5173)
- `cd frontend && npm run build` - Production build (outputs to ../dist)
- `cd frontend && npm run preview` - Preview production build

### Testing
No test framework currently configured. Before adding tests, propose the approach (e.g., Vitest for unit tests, Playwright for E2E).

### Linting/Typechecking
No linting tools configured. Before adding eslint/prettier, verify compatibility with existing code style.

## Code Style Guidelines

### Vue 3 & JavaScript
- Use Composition API with `<script setup>` syntax
- Import only what you need: `import { ref, computed, onMounted } from 'vue'`
- Use `const` for all variables, `let` only when necessary
- Separate concerns: state first, then lifecycle hooks, then functions
- Use computed properties for derived state, watchers for side effects
- Function names use camelCase, descriptive: `drawTerritories()`, `toggleRoute()`

### Imports
- Group imports: Vue libraries first, then external packages, then local files
- Named imports only, avoid default imports where possible
- Leaflet: `import L from 'leaflet'` then `import 'leaflet/dist/leaflet.css'`

### File Organization
- Single-file components: template, script, style in that order
- Script sections separated with comment dividers:
  ```javascript
  // ── 响应式状态 ──────────────────────────────────────────────
  // ── Leaflet 图层管理 ────────────────────────────────────────
  // ── 生命周期 ────────────────────────────────────────────────
  // ── 数据加载 ────────────────────────────────────────────────
  // ── 地图初始化 ──────────────────────────────────────────────
  // ── 工具函数 ────────────────────────────────────────────────
  ```

### Naming Conventions
- Variables: camelCase (`currentVol`, `mergedLocations`, `isLoading`)
- Constants: UPPER_SNAKE_CASE (`layerGroups`)
- Files: kebab-case (`chapter-panel.vue`, not ChapterPanel.vue`)
- IDs in JSON: lowercase with underscores (`yuwen_faction`, `grand_canal`)
- CSS classes: kebab-case (`.map-container`, `.legend-item`)

### CSS & Styling
- Use scoped styles in components
- Dark theme: backgrounds `rgba(20, 20, 40, 0.9)`, text `#e0e0e0`
- Accent color: `#c9a96e` (gold) for headers and highlights
- Absolute positioning for UI overlays (z-index 1000+ for panels)
- Panels use fixed width/height or flexbox for layouts
- Leaflet overrides in global style.css (popup styles)

### Data Structure (JSON volumes)
Each `volXX.json` in `/data` follows:
```json
{
  "volume": "卷X",
  "chapters": ["第01章 标题", ...],
  "locations": [
    { "id": "unique_id", "name": "Location", "type": "city|town|landmark|waterway",
      "lat": 0.0, "lng": 0.0, "description": "..." }
  ],
  "factions": [
    { "id": "unique_id", "name": "Faction", "type": "门阀|朝廷|义军",
      "color": "#hex", "leader": "Name", "territory": ["loc_id", ...],
      "key_figures": ["Name", ...], "description": "..." }
  ],
  "character_routes": [
    { "character": "Name", "color": "#hex",
      "route": [{ "chapter": 1, "location": "loc_id", "event": "..." }] }
  ],
  "key_events": [
    { "chapter": 1, "event": "Description", "location": "loc_id" }
  ]
}
```

### Error Handling
- Use try/catch for fetch operations
- Log warnings with context: `console.warn('vol01.json load failed:', err)`
- User-facing loading states: `isLoading.value = true/false`
- Graceful degradation: missing data should not crash the app

### Leaflet Integration
- Initialize map in `onMounted()`, store in module-scoped variable
- Use layer groups for organized rendering: `territories`, `locations`, `routes`, `events`
- Clear layers before redrawing: `layerGroups.someLayer.clearLayers()`
- Custom icons use `L.divIcon()` for HTML markers
- Dark map tile: CartoDB Dark Matter basemap

### Comments & Documentation
- Minimal comments - code should be self-documenting
- Section dividers (as shown above) for organization
- TODO notes for future improvements
- README.md contains project overview and technical architecture

### Performance Considerations
- Lazy load data: fetch all volumes in parallel, store in reactive array
- Use computed properties with Map for efficient deduplication
- Debounce heavy operations (map redraws, calculations)
- Limit rendered elements: show only up to `currentVol`

### Adding New Features
1. Check existing data structure in `/data/volXX.json`
2. Follow established code patterns in App.vue
3. Use layer groups for new map features
4. Update UI panels (legend, chapter-panel, info-panel) consistently
5. Ensure responsive state updates with Vue's reactivity system