119 lines
5.4 KiB
Markdown
119 lines
5.4 KiB
Markdown
# 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
|