From a85ff8e21549985847b08d720aea7d2728ba72e2 Mon Sep 17 00:00:00 2001 From: Jiang Date: Thu, 5 Feb 2026 10:47:54 +0800 Subject: [PATCH] =?UTF-8?q?copilot=E9=A1=B9=E7=9B=AE=E6=8F=8F=E8=BF=B0?= =?UTF-8?q?=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 200 ++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..33b73d8 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,200 @@ +# TJWater Server - Copilot Instructions + +This is a FastAPI-based water network management system (供水管网智能管理系统) that provides hydraulic simulation, SCADA data integration, network element management, and risk analysis capabilities. + +## Running the Server + +```bash +# Install dependencies +pip install -r requirements.txt + +# Start the server (default: http://0.0.0.0:8000 with 2 workers) +python scripts/run_server.py + +# Note: On Windows, the script automatically sets WindowsSelectorEventLoopPolicy +``` + +## Running Tests + +```bash +# Run all tests +pytest + +# Run a specific test file with verbose output +pytest tests/unit/test_pipeline_health_analyzer.py -v + +# Run from conftest helper +python tests/conftest.py +``` + +## Architecture Overview + +### Core Components + +1. **Native Modules** (`app/native/`): Platform-specific compiled extensions (`.so` for Linux, `.pyd` for Windows) providing performance-critical functionality including: + - SCADA device integration + - Water distribution analysis (WDA) + - Pipe risk probability calculations + - Wrapped through `app.services.tjnetwork` interface + +2. **Services Layer** (`app/services/`): + - `tjnetwork.py`: Main network API wrapper around native modules + - `simulation.py`: Hydraulic simulation orchestration (EPANET integration) + - `project_info.py`: Project configuration management + - `epanet/`: EPANET hydraulic engine integration + +3. **API Layer** (`app/api/v1/`): + - **Network Elements**: Separate endpoint modules for junctions, reservoirs, tanks, pipes, pumps, valves + - **Components**: Curves, patterns, controls, options, quality, visuals + - **Network Features**: Tags, demands, geometry, regions/DMAs + - **Core Services**: Auth, project, simulation, SCADA, data query, snapshots + +4. **Database Infrastructure** (`app/infra/db/`): + - **PostgreSQL**: Primary relational database (users, audit logs, project metadata) + - **TimescaleDB**: Time-series extension for historical data + - **InfluxDB**: Optional time-series database for high-frequency SCADA data + - Connection pools initialized in `main.py` lifespan context + - Database instance stored in `app.state.db` for dependency injection + +5. **Domain Layer** (`app/domain/`): + - `models/`: Enums and domain objects (e.g., `UserRole`) + - `schemas/`: Pydantic models for request/response validation + +6. **Algorithms** (`app/algorithms/`): + - `api_ex/`: Analysis algorithms (k-means sensor placement, sensitivity analysis, pipeline health) + - `data_cleaning.py`: Data preprocessing utilities + - `simulations.py`: Simulation helpers + +### Security & Authentication + +- **Authentication**: JWT-based with access tokens (30 min) and refresh tokens (7 days) +- **Authorization**: Role-based access control (RBAC) with 4 roles: + - `VIEWER`: Read-only access + - `USER`: Read-write access + - `OPERATOR`: Modify data + - `ADMIN`: Full permissions +- **Audit Logging**: `AuditMiddleware` automatically logs POST/PUT/DELETE requests +- **Encryption**: Fernet symmetric encryption for sensitive data (`app.core.encryption`) + +Default admin accounts: +- `admin` / `admin123` +- `tjwater` / `tjwater@123` + +### Key Files + +- `app/main.py`: FastAPI app initialization, lifespan (DB pools), CORS, middleware, router mounting +- `app/api/v1/router.py`: Central router aggregating all endpoint modules +- `app/core/config.py`: Settings management using `pydantic-settings` +- `app/auth/dependencies.py`: Auth dependencies (`get_current_active_user`, `get_db`) +- `app/auth/permissions.py`: Permission decorators (`require_role`, `get_current_admin`) +- `configs/project_info.yml`: Default project configuration (auto-loaded on startup) +- `.env`: Environment configuration (database credentials, JWT secret, encryption key) + +## Important Conventions + +### Database Connections + +- Database instances are initialized in `main.py` lifespan and stored in `app.state.db` +- Access via dependency injection: + ```python + from app.auth.dependencies import get_db + + async def endpoint(db = Depends(get_db)): + # Use db connection + ``` + +### Authentication in Endpoints + +Use dependency injection for auth requirements: + +```python +from app.auth.dependencies import get_current_active_user +from app.auth.permissions import require_role, get_current_admin +from app.domain.models.role import UserRole + +# Require any authenticated user +@router.get("/data") +async def get_data(current_user = Depends(get_current_active_user)): + return data + +# Require specific role (USER or higher) +@router.post("/data") +async def create_data(current_user = Depends(require_role(UserRole.USER))): + return result + +# Admin-only access +@router.delete("/data/{id}") +async def delete_data(id: int, current_user = Depends(get_current_admin)): + return result +``` + +### API Routing Structure + +- All v1 APIs are mounted under `/api/v1` prefix via `api_router` +- Legacy routes without version prefix are also mounted for backward compatibility +- Group related endpoints in separate router modules under `app/api/v1/endpoints/` +- Use descriptive tags in `router.py` for OpenAPI documentation grouping + +### Native Module Integration + +- Native modules are pre-compiled for specific platforms +- Always import through `app.native.api` or `app.services.tjnetwork` +- The `tjnetwork` service wraps native APIs with constants like: + - Element types: `JUNCTION`, `RESERVOIR`, `TANK`, `PIPE`, `PUMP`, `VALVE` + - Operations: `API_ADD`, `API_UPDATE`, `API_DELETE` + - `ChangeSet` for batch operations + +### Project Initialization + +- On startup, `main.py` automatically loads project from `project_info.name` if set +- Projects are opened via `open_project(name)` from `tjnetwork` service +- Initial project config comes from `configs/project_info.yml` + +### Audit Logging + +Manual audit logging for critical operations: + +```python +from app.core.audit import log_audit_event, AuditAction + +await log_audit_event( + action=AuditAction.UPDATE, + user_id=current_user.id, + username=current_user.username, + resource_type="resource_name", + resource_id=str(resource_id), + ip_address=request.client.host, + request_data=data +) +``` + +### Environment Configuration + +- Copy `.env.example` to `.env` before first run +- Required environment variables: + - `SECRET_KEY`: JWT signing (generate with `openssl rand -hex 32`) + - `ENCRYPTION_KEY`: Data encryption (generate with Fernet) + - Database credentials for PostgreSQL, TimescaleDB, and optionally InfluxDB + +### Database Migrations + +SQL migration scripts are in `migrations/`: +- `001_create_users_table.sql`: User authentication tables +- `002_create_audit_logs_table.sql`: Audit logging tables + +Apply with: +```bash +psql -U postgres -d tjwater -f migrations/001_create_users_table.sql +``` + +## API Documentation + +- Swagger UI: http://localhost:8000/docs +- ReDoc: http://localhost:8000/redoc +- OpenAPI schema: http://localhost:8000/openapi.json + +## Additional Resources + +- `SECURITY_README.md`: Comprehensive security feature documentation +- `DEPLOYMENT.md`: Integration guide for security features +- `readme.md`: Project overview and directory structure (in Chinese)