# 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)