# CLAUDE.md

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

## Project Overview

MeetSpot is an **AI Agent** for multi-person meeting point recommendations. Users provide locations and requirements; the Agent calculates the geographic center and recommends optimal venues. Built with FastAPI and Python 3.11+, uses Amap (Gaode Map) API for geocoding/POI search, and DeepSeek/GPT-4o-mini for semantic scoring.

**Live Demo**: https://meetspot-irq2.onrender.com

## Quick Reference

```bash
# Environment
conda activate meetspot                  # Or: source venv/bin/activate

# Development
uvicorn api.index:app --reload           # Preferred for iteration
python web_server.py                     # Full stack with auto env detection

# Test the main endpoint
curl -X POST "http://127.0.0.1:8000/api/find_meetspot" \
  -H "Content-Type: application/json" \
  -d '{"locations": ["北京大学", "清华大学"], "keywords": "咖啡馆"}'

# Testing
pytest tests/ -v                         # Full suite
pytest tests/test_file.py::test_name -v  # Single test
pytest --cov=app tests/                  # Coverage (target: 80%)
python tests/test_seo.py http://localhost:8000  # SEO validation (standalone)

# Quality gates (run before PRs)
black . && ruff check . && mypy app/

# Postmortem regression check (optional, runs in CI)
python tools/postmortem_check.py         # Check for known issue patterns
```

**Key URLs**: Main UI (`/`), API docs (`/docs`), Health (`/health`)

## Repo Rules

- Follow `AGENTS.md` for repo-local guidelines (style, structure, what not to commit). In particular: runtime-generated files under `workspace/js_src/` must not be committed.
- There are no Cursor/Copilot rule files in this repo (no `.cursorrules`, no `.cursor/rules/`, no `.github/copilot-instructions.md`).

## Environment Setup

**Conda**: `conda env create -f environment.yml && conda activate meetspot` (env name is `meetspot`, not `meetspot-dev`)
**Pip**: `python3.11 -m venv venv && source venv/bin/activate && pip install -r requirements.txt`

**Required Environment Variables**:
- `AMAP_API_KEY` - Gaode Map API key (required)
- `AMAP_SECURITY_JS_CODE` - JS security code for frontend map
- `LLM_API_KEY` - DeepSeek/OpenAI API key (for AI chat and LLM scoring)
- `LLM_API_BASE` - API base URL (default: `https://newapi.deepwisdom.ai/v1`)
- `LLM_MODEL` - Model name (default: `deepseek-chat`)

**Local Config**: Copy `config/config.toml.example` to `config/config.toml` and fill in API keys. Alternatively, create a `.env` file with the environment variables above.

## Architecture

### Request Flow

```
POST /api/find_meetspot
        ↓
Complexity Router (assess_request_complexity)
        ↓
Rule+LLM Mode (Agent mode disabled for memory savings on free tier)
        ↓
5-Step Pipeline: Geocode → Center Calc → POI Search → Ranking → HTML Gen
```

Complexity scoring: +10/location, +15 for complex keywords, +10 for special requirements. Currently all requests use Rule+LLM mode since Agent mode is disabled (`agent_available = False` in `api/index.py`).

### Entry Points
- `web_server.py` - Main entry, auto-detects production vs development
- `api/index.py` - FastAPI app with all endpoints, middleware, and request handling

### Three-Tier Configuration (Graceful Degradation)

| Mode | Trigger | What Works |
|------|---------|------------|
| Full | `config/config.toml` exists | All features, TOML-based config |
| Simplified | `RAILWAY_ENVIRONMENT` set | Uses `app/config_simple.py` |
| Minimal | Only `AMAP_API_KEY` env var | `MinimalConfig` class in `api/index.py`, basic recommendations only |

### Core Components

```
app/tool/meetspot_recommender.py    # Main recommendation engine (CafeRecommender class)
  |- university_mapping dict        # 45 abbreviations (e.g., "北大" -> "北京市海淀区北京大学")
  |- landmark_mapping dict          # 45 city landmarks (e.g., "陆家嘴" -> "上海市浦东新区陆家嘴")
  |- PLACE_TYPE_CONFIG dict         # 12 venue themes with colors, icons
  |- _rank_places()                 # 100-point scoring algorithm
  |- _generate_html_content()       # Standalone HTML with Amap JS API
  |- geocode_cache (max 30)         # LRU-style address cache (reduced for free tier)
  |- poi_cache (max 15)             # LRU-style POI cache (reduced for free tier)

app/design_tokens.py                # WCAG AA color palette, CSS generation
api/routers/seo_pages.py            # SEO landing pages
```

### LLM Scoring (Agent Mode)

When Agent Mode is enabled, final venue scores blend rule-based and LLM semantic analysis:
```
Final Score = Rule Score * 0.4 + LLM Score * 0.6
```
Agent Mode is currently disabled (`agent_available = False`) to conserve memory on free hosting tiers.

### Data Flow

```
1. Address enhancement (90+ university/landmark mappings)
2. Geocoding via Amap API (with retry + rate limiting)
3. Center point calculation (spherical geometry)
4. POI search (concurrent for multiple keywords)
   Fallback: tries 餐厅->咖啡馆->商场->美食, then expands to 50km
5. Ranking with multi-scenario balancing (max 8 venues)
6. HTML generation -> workspace/js_src/
```

### Optional Components

Database layer (`app/db/`, `app/models/`) is optional - core recommendation works without it. Used for auth/social features with SQLite + aiosqlite.

Experimental agent endpoint (`/api/find_meetspot_agent`) requires OpenManus framework - **not production-ready**.

## Key Patterns

### Ranking Algorithm
Edit `_rank_places()` in `meetspot_recommender.py`:
- Base: 30 points (rating x 6)
- Popularity: 20 points (log-scaled reviews)
- Distance: 25 points (500m = full score, decays)
- Scenario: 15 points (keyword match)
- Requirements: 10 points (parking/quiet/business)

### Distance Filtering
Two-stage distance handling in `meetspot_recommender.py`:
1. **POI Search**: Amap API `radius` parameter (hardcoded 5000m, fallback to 50000m)
2. **Post-filter**: `max_distance` parameter in `_rank_places()` (default 100km, in meters)

The `max_distance` filter applies after POI retrieval during ranking. To change search radius, modify `radius=5000` in `_search_places()` calls around lines 556-643.

### Brand Knowledge Base
`BRAND_FEATURES` dict in `meetspot_recommender.py` contains 50+ brand profiles (Starbucks, Haidilao, etc.) with feature scores (0.0-1.0) for: quiet, WiFi, business, parking, child-friendly, 24h. Used in requirements matching - brands scoring >=0.7 satisfy the requirement. Place types prefixed with `_` (e.g., `_library`) provide defaults.

### Adding Address Mappings
Two sources for address resolution:
1. **External file**: `data/address_aliases.json` - JSON file with `university_aliases` and `landmark_aliases` dicts. Preferred for new mappings.
2. **Internal dicts**: `university_mapping` and `landmark_mapping` in `_enhance_address()` method of `meetspot_recommender.py`. Use for mappings requiring city prefixes (prevents cross-city geocoding errors).

### Adding Venue Themes
Add entry to `PLACE_TYPE_CONFIG` with: Chinese name, Boxicons icons, 6 color values.

## Postmortem System

Automated regression prevention system that tracks historical fixes and warns when code changes might reintroduce past bugs.

### Structure
```
postmortem/
  PM-2025-001.yaml ... PM-2026-xxx.yaml  # Historical fix documentation
tools/
  postmortem_init.py     # Generate initial knowledge base from git history
  postmortem_check.py    # Check code changes against known patterns
  postmortem_generate.py # Generate postmortem for a single commit
```

### CI Integration
- `postmortem-check.yml`: Runs on PRs, warns if changes match known issue patterns
- `postmortem-update.yml`: Auto-generates postmortem when `fix:` commits merge to main

### Adding New Postmortems
When fixing a bug, the CI will auto-generate a postmortem. For manual creation:
```bash
python tools/postmortem_generate.py <commit-hash>
```

Each postmortem YAML contains triggers (file patterns, function names, regex, keywords) that enable multi-dimensional pattern matching.

## Debugging

| Issue | Solution |
|-------|----------|
| `未找到AMAP_API_KEY` | Set environment variable |
| Import errors in production | Check MinimalConfig fallback |
| Wrong city geocoding | Add to `landmark_mapping` with city prefix |
| Empty POI results | Fallback mechanism handles this automatically |
| Render OOM (512MB) | Caches are reduced (30/15 limits); Agent mode disabled |
| Render service down | Trigger redeploy: `git commit --allow-empty -m "trigger redeploy" && git push` |

**Logging**: Uses loguru via `app/logger.py`. `/health` endpoint shows config status.

## Deployment

Hosted on Render free tier (512MB RAM, cold starts after 15min idle).

**Redeploy**: Push to `main` branch triggers auto-deploy. For manual restart without code changes:
```bash
git commit --allow-empty -m "chore: trigger redeploy" && git push origin main
```

**Generated artifacts**: HTML files in `workspace/js_src/` are runtime-generated and should not be committed.

## Code Style

- Python: 4-space indent, type hints, `snake_case` functions, `PascalCase` classes
- CSS: BEM-like (`meetspot-header__title`), colors from `design_tokens.py`
- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`)