80 lines
5.2 KiB
Markdown
80 lines
5.2 KiB
Markdown
# Project Structure
|
|
|
|
```
|
|
├── src/ # Main application source
|
|
│ ├── main.py # TSPAssistant facade class (orchestrates all managers)
|
|
│ ├── agent_assistant.py # Agent-enhanced assistant variant
|
|
│ ├── agent/ # ReAct LLM agent
|
|
│ │ ├── react_agent.py # Agent loop with tool dispatch
|
|
│ │ └── llm_client.py # Agent-specific LLM client
|
|
│ ├── core/ # Core infrastructure
|
|
│ │ ├── models.py # SQLAlchemy ORM models (all entities)
|
|
│ │ ├── database.py # DatabaseManager singleton, session management
|
|
│ │ ├── llm_client.py # QwenClient (OpenAI-compatible LLM calls)
|
|
│ │ ├── cache_manager.py # In-memory + Redis caching
|
|
│ │ ├── redis_manager.py # Redis connection pool
|
|
│ │ ├── vector_store.py # Vector storage for embeddings
|
|
│ │ ├── embedding_client.py # Local embedding model client
|
|
│ │ ├── auth_manager.py # Authentication logic
|
|
│ │ └── ... # Performance, backup, query optimizer
|
|
│ ├── config/
|
|
│ │ └── unified_config.py # UnifiedConfig singleton (env → dataclasses)
|
|
│ ├── dialogue/ # Conversation management
|
|
│ │ ├── dialogue_manager.py # Message processing, work order creation
|
|
│ │ ├── conversation_history.py
|
|
│ │ └── realtime_chat.py # Real-time chat manager
|
|
│ ├── knowledge_base/
|
|
│ │ └── knowledge_manager.py # Knowledge CRUD, search, import
|
|
│ ├── analytics/ # Monitoring & analytics
|
|
│ │ ├── analytics_manager.py
|
|
│ │ ├── alert_system.py
|
|
│ │ ├── monitor_service.py
|
|
│ │ ├── token_monitor.py
|
|
│ │ └── ai_success_monitor.py
|
|
│ ├── integrations/ # External service integrations
|
|
│ │ ├── feishu_client.py # Feishu API client
|
|
│ │ ├── feishu_service.py # Feishu business logic
|
|
│ │ ├── feishu_longconn_service.py # Feishu event subscription (long-conn)
|
|
│ │ ├── workorder_sync.py # Feishu ↔ local work order sync
|
|
│ │ └── flexible_field_mapper.py # Feishu field mapping
|
|
│ ├── vehicle/
|
|
│ │ └── vehicle_data_manager.py
|
|
│ ├── utils/ # Shared helpers
|
|
│ │ ├── helpers.py
|
|
│ │ ├── encoding_helper.py
|
|
│ │ └── semantic_similarity.py
|
|
│ └── web/ # Web layer
|
|
│ ├── app.py # Flask app factory, middleware, blueprint registration
|
|
│ ├── service_manager.py # Lazy-loading service singleton registry
|
|
│ ├── decorators.py # @handle_errors, @require_json, @resolve_tenant_id, @rate_limit
|
|
│ ├── error_handlers.py # Unified API response helpers
|
|
│ ├── websocket_server.py # Standalone WebSocket server
|
|
│ ├── blueprints/ # Flask blueprints (one per domain)
|
|
│ │ ├── alerts.py, workorders.py, conversations.py, knowledge.py
|
|
│ │ ├── auth.py, tenants.py, chat.py, agent.py, vehicle.py
|
|
│ │ ├── analytics.py, monitoring.py, system.py
|
|
│ │ ├── feishu_sync.py, feishu_bot.py
|
|
│ │ └── test.py, core.py
|
|
│ ├── static/ # Frontend assets (JS, CSS)
|
|
│ └── templates/ # Jinja2 HTML templates
|
|
├── config/ # Runtime config files (field mappings)
|
|
├── data/ # SQLite DB file, system settings JSON
|
|
├── logs/ # Log files (per-startup subdirectories)
|
|
├── scripts/ # Migration and utility scripts
|
|
├── start_dashboard.py # Main entry point (Flask + WS + Feishu)
|
|
├── start_feishu_bot.py # Standalone Feishu bot entry point
|
|
├── init_database.py # DB initialization script
|
|
├── requirements.txt # Python dependencies
|
|
├── nginx.conf # Nginx reverse proxy config
|
|
└── .env / .env.example # Environment configuration
|
|
```
|
|
|
|
## Key Patterns
|
|
|
|
- **Singleton managers**: `db_manager`, `service_manager`, `get_config()` — instantiated once, imported globally.
|
|
- **Blueprint-per-domain**: Each functional area (workorders, alerts, knowledge, etc.) has its own Flask blueprint under `src/web/blueprints/`.
|
|
- **Service manager with lazy loading**: `ServiceManager` in `src/web/service_manager.py` provides thread-safe lazy initialization of all service instances. Blueprints access services through it.
|
|
- **Decorator-driven API patterns**: Common decorators in `src/web/decorators.py` handle error wrapping, JSON validation, tenant resolution, and rate limiting.
|
|
- **Multi-tenant by convention**: All DB queries should filter by `tenant_id`. The `@resolve_tenant_id` decorator extracts it from request body, query params, or session.
|
|
- **Config from env**: No hardcoded secrets. All configuration flows through `UnifiedConfig` which reads from `.env` via `python-dotenv`.
|