chore: 整理项目结构与文档

- 更新 .gitignore 支持 docs 子目录图片
- 移除根目录重复的站点验证文件
- 完善 CLAUDE.md 文档说明
- 添加项目规范与开发指南
- 添加推广文案文档

Author: calderbuild

.gitignore

@@ -159,8 +159,10 @@ image copy 2.png
 线下聚会数据.png
 deepwiki.png
 *.png
-!docs/*.png
-!docs/*.jpg
+!docs/*.png
+!docs/*.jpg
+!docs/**/*.png
+!docs/**/*.jpg
 !public/**/*.png
 !public/**/*.jpg
 

.kiro/steering/api-development.md

@@ -0,0 +1,190 @@
+# Development Standards & Best Practices
+
+## Code Style & Formatting
+
+### Python Standards
+- **Indentation**: 4 spaces (never tabs)
+- **Type hints**: Required everywhere - functions, variables, class attributes
+- **Naming conventions**:
+  - Functions/variables: `snake_case`
+  - Classes: `PascalCase`
+  - Constants: `SCREAMING_SNAKE_CASE`
+  - Private methods: `_leading_underscore`
+- **Function length**: Keep under ~50 lines for readability
+- **Data structures**: Prefer dataclasses for structured payloads over dictionaries
+
+### HTML/CSS Standards
+- **Class naming**: BEM-like convention (`meetspot-header__title`, `card--featured`)
+- **Colors**: Always use design tokens from `static/css/design-tokens.css`
+- **Inline styles**: Minimize usage, only for generated HTML in `workspace/js_src/`
+- **Responsive design**: Mobile-first approach with progressive enhancement
+- **Accessibility**: All interactive elements must be keyboard accessible
+
+### JavaScript Standards
+- **ES6+**: Use modern JavaScript features
+- **Async/await**: Prefer over Promise chains
+- **Error handling**: Always wrap API calls in try-catch blocks
+- **DOM manipulation**: Use semantic HTML and ARIA attributes
+
+## Quality Gates
+
+### Pre-commit Requirements
+All of these must pass before opening a PR:
+
+```bash
+# Code formatting
+black .
+
+# Linting
+ruff check .
+
+# Type checking
+mypy app/
+
+# Test coverage
+pytest --cov=app tests/
+# Target: ≥80% coverage for app/ package
+```
+
+### Testing Standards
+- **Test organization**: Place tests in `tests/` using `test_<feature>.py` naming
+- **Test types**:
+  - Unit tests: Individual functions and classes
+  - Integration tests: FastAPI routes + tool layer helpers
+  - SEO tests: Meta tags, schema.org, sitemap validation
+- **Fixtures**: Create reusable fixtures for database, API clients, mock data
+- **Coverage**: Maintain ≥80% coverage for the `app/` package
+- **Focus areas**: Prioritize testing caching, concurrency, and SEO logic
+
+## Logging Standards
+
+### Structured Logging
+Use `app/logger.py` for all logging needs:
+
+```python
+from app.logger import logger
+
+# Good: Structured logging with context
+logger.info("geo_center_calculated", extra={
+    "center_lat": 39.9042,
+    "center_lng": 116.4074,
+    "locations_count": 3,
+    "processing_time": 1.2
+})
+
+# Bad: Unstructured string logging
+logger.info("Calculated center at 39.9042, 116.4074")
+```
+
+### Log Levels
+- **DEBUG**: Detailed diagnostic information
+- **INFO**: General operational messages
+- **WARNING**: Something unexpected but recoverable
+- **ERROR**: Error conditions that don't stop execution
+- **CRITICAL**: Serious errors that may abort execution
+
+## Performance Guidelines
+
+### Memory Management
+- **Concurrency**: Respect `MAX_CONCURRENT_REQUESTS = 3` semaphore
+- **Caching**: Use LRU cache with reasonable limits (30 geocodes, 15 POI searches)
+- **Cleanup**: Call `gc.collect()` after memory-intensive operations
+- **Agent mode**: Currently disabled to save memory on Render free tier
+
+### Async Best Practices
+- **All I/O async**: Use aiohttp, aiofiles, async database operations
+- **Concurrent operations**: Use `asyncio.gather()` for parallel API calls
+- **Error handling**: Always handle async exceptions properly
+- **Session management**: Reuse HTTP sessions, close properly
+
+### Caching Strategy
+- **HTTP caching**: Set appropriate Cache-Control headers
+  - Immutable assets: 1 year
+  - Images: 30 days
+  - Dynamic content: no-cache
+- **Application caching**: Use LRU cache for expensive operations
+- **Database caching**: Cache frequently accessed data
+
+## Security Standards
+
+### API Security
+- **Authentication**: Use JWT tokens for protected endpoints
+- **Rate limiting**: Apply appropriate limits (default 60/minute)
+- **Input validation**: Validate all inputs using Pydantic models
+- **CORS**: Configure appropriately for production
+- **Environment variables**: Never hardcode secrets, use `.env` files
+
+### Data Protection
+- **PII handling**: Mask phone numbers in logs and responses
+- **Token security**: Use secure JWT signing, appropriate expiration
+- **Database**: Use parameterized queries (SQLAlchemy ORM handles this)
+- **File uploads**: Validate file types and sizes if implemented
+
+## Configuration Management
+
+### Environment Variables
+Required variables:
+```bash
+AMAP_API_KEY              # Required: Amap API key
+```
+
+Optional variables:
+```bash
+AMAP_SECURITY_JS_CODE     # Amap JS security code
+AMAP_JS_API_KEY           # Amap JS API key
+LLM_API_KEY               # LLM API key
+LLM_API_BASE              # LLM base URL
+LLM_MODEL                 # LLM model name
+OPENAI_API_KEY            # Alternative OpenAI key
+PORT                      # Server port (default 8000)
+LOG_LEVEL                 # Logging level
+```
+
+### Configuration Hierarchy
+1. Environment variables (highest priority)
+2. `config/config.toml` file
+3. `config/config.toml.example` (fallback)
+4. Hardcoded defaults (lowest priority)
+
+### Adding New Configuration
+1. Add to appropriate settings class in `app/config.py`
+2. Update `AppConfig` model
+3. Add environment variable support
+4. Update `config/config.toml.example`
+5. Document in README.md
+
+## Error Handling
+
+### Exception Handling
+- **Custom exceptions**: Use classes from `app/exceptions.py`
+- **HTTP errors**: Return appropriate status codes with meaningful messages
+- **Async exceptions**: Always handle in async contexts
+- **Logging**: Log errors with context for debugging
+
+### API Error Responses
+```python
+# Good: Structured error response
+{
+    "success": false,
+    "error": "geocoding_failed",
+    "message": "无法解析地址: 北京市朝阳区",
+    "details": {
+        "address": "北京市朝阳区",
+        "provider": "amap"
+    }
+}
+```
+
+## Documentation Standards
+
+### Code Documentation
+- **Docstrings**: Use Google-style docstrings for all public functions/classes
+- **Type hints**: Comprehensive type annotations
+- **Comments**: Explain complex business logic, not obvious code
+- **README**: Keep up-to-date with setup instructions and API documentation
+
+### API Documentation
+- **FastAPI**: Automatic OpenAPI/Swagger documentation
+- **Endpoint descriptions**: Clear, concise descriptions of what each endpoint does
+- **Request/response examples**: Provide realistic examples
+- **Error codes**: Document all possible error responses

.kiro/steering/development-standards.md

@@ -0,0 +1,51 @@
+# MeetSpot Project Overview
+
+## What is MeetSpot?
+
+MeetSpot is an AI-powered multi-person meeting point recommendation system that finds fair meeting locations using geographic algorithms and LLM-based intelligent scoring. It integrates with Amap (高德地图) for geolocation services and uses GPT-4o for semantic analysis.
+
+## Core Architecture
+
+### Technology Stack
+- **Backend**: FastAPI + SQLAlchemy (async) + aiosqlite
+- **Frontend**: Jinja2 templates + CSS design tokens + Amap JS API
+- **AI/LLM**: OpenAI SDK (GPT-4o, DeepSeek), tiktoken for token counting
+- **External APIs**: Amap (高德地图) for geocoding and POI search
+- **Deployment**: Docker, Render, Vercel support
+
+### Key Components
+1. **Intelligent Routing System**: Automatically selects between fast rule-based mode and deep LLM-enhanced Agent mode
+2. **5-Step Recommendation Pipeline**: Geocoding → Center calculation → POI search → Ranking → HTML generation
+3. **WCAG 2.1 AA Design System**: Accessible color tokens and responsive design
+4. **SEO-Optimized Pages**: Schema.org structured data, meta tags, sitemap
+5. **Authentication**: JWT + SMS verification system
+
+## Project Structure
+```
+MeetSpot/
+├── api/                    # FastAPI application layer
+├── app/                    # Core business logic (authoritative source)
+│   ├── tool/              # Tool implementations (recommender, search, etc.)
+│   ├── agent/             # AI Agent system (currently disabled)
+│   ├── auth/              # Authentication (JWT, SMS)
+│   ├── models/            # SQLAlchemy ORM models
+│   └── db/                # Database layer
+├── templates/             # Jinja2 templates
+├── static/                # CSS, design tokens
+├── public/                # Marketing pages, SEO assets
+├── workspace/js_src/      # Generated recommendation HTML pages
+└── tests/                 # Test suite
+```
+
+## Development Workflow
+- Use `python web_server.py` for local development
+- Quality gates: `black .`, `ruff check .`, `mypy app/` must be clean
+- Target ≥80% test coverage for `app/` package
+- Follow Conventional Commits (`feat:`, `fix:`, `ci:`, `docs:`)
+
+## Key Features
+- **Complexity Assessment**: Automatically routes simple requests to fast rule mode, complex ones to LLM mode
+- **Multi-factor Scoring**: Base score + popularity + distance + scenario + requirements
+- **Brand Knowledge Base**: 60+ brand mappings with feature scores
+- **Caching Strategy**: Optimized for memory constraints on cloud platforms
+- **Accessibility First**: All colors meet WCAG 2.1 AA contrast requirements

.kiro/steering/project-overview.md

@@ -101,6 +101,10 @@ app/design_tokens.py                # WCAG AA color palette, CSS generation
 api/routers/seo_pages.py            # SEO landing pages
 ```
 
+### Frontend Address Input
+
+`public/meetspot_finder.html` uses AMap Autocomplete API for real-time address suggestions. When users select from dropdown, coordinates are pre-resolved client-side, bypassing backend geocoding. Falls back to backend geocoding when manual text is entered.
+
 ### LLM Scoring (Agent Mode)
 
 When Agent Mode is enabled, final venue scores blend rule-based and LLM semantic analysis:
@@ -148,9 +152,9 @@ The `max_distance` filter applies after POI retrieval during ranking. To change
 `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).
+**Preferred**: Edit `data/address_aliases.json` - maps abbreviations to full names (e.g., "北大" → "北京大学").
+
+**For cross-city issues**: Add to `university_mapping` or `landmark_mapping` dicts in `meetspot_recommender.py` with city prefix (e.g., "华南理工" → "广州市番禺区华南理工大学").
 
 ### Adding Venue Themes
 Add entry to `PLACE_TYPE_CONFIG` with: Chinese name, Boxicons icons, 6 color values.