2.9 KiB
Repository Guidelines
Project Structure & Module Organization
This repository contains the TJWater Python backend. Main application code lives in app/: API routes under app/api, authentication in app/auth, configuration in app/core, database and repository code in app/infra, domain models/schemas in app/domain, and business logic in app/services and app/algorithms.
Tests are under tests/, split into tests/unit, tests/api, and tests/auth. CLI code lives in cli/tjwater_cli, with CLI tests in cli/tests. SQL and sample assets are stored in resources/; deployment files are in Dockerfile, .gitea/workflows/package.yml, and infra/docker/docker-compose.yml. Local data directories such as db_inp/, temp/, data/, and .env are ignored and should not be committed.
Build, Test, and Development Commands
Use the existing conda environment when available:
conda run -n server python -m pytest tests/unit tests/auth -q
conda run -n server uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
docker build -t tjwater-server:local .
docker compose -f infra/docker/docker-compose.yml config
pytest runs backend tests. uvicorn starts the FastAPI app locally. docker build verifies the container image. docker compose config validates compose syntax and variable expansion.
Coding Style & Naming Conventions
Use Python 3.12, four-space indentation, type hints for new public functions, and explicit imports. Keep API endpoint modules grouped by domain under app/api/v1/endpoints. Use snake_case for files, functions, and variables; PascalCase for classes and Pydantic models. Prefer existing repository/service patterns in app/infra/db and app/services over introducing new abstractions.
Testing Guidelines
The project uses pytest. Name test files test_*.py and test functions test_*. Keep unit tests isolated with fakes or monkeypatching from tests/conftest.py. Some existing tests depend on local data outside the repository; avoid adding new tests that require untracked files. For API changes, add or update tests in tests/api.
Commit & Pull Request Guidelines
History uses a mix of Conventional Commit prefixes and concise Chinese messages, for example feat(api): add Tianditu geocoding, fix(cli): constrain timeseries option values, or 更新 cli 命令.... Prefer feat(scope): ..., fix(scope): ..., or a clear Chinese summary.
Pull requests should describe the behavior change, list verification commands, mention configuration or migration impacts, and link related issues. Include API examples or screenshots only when they clarify user-facing behavior.
Security & Configuration Tips
Do not commit .env, database dumps, generated caches, or local project data. Use .env.example as the configuration template. Secrets for CI/CD belong in Gitea repository secrets such as REGISTRY_USERNAME, REGISTRY_PASSWORD, and deploy webhook credentials.