docs(delivery): document customer source packaging

2026-06-11 10:24:05 +08:00
parent 1ec82971ca
commit 322e8156ee
1 changed files with 73 additions and 0 deletions
@@ -0,0 +1,73 @@
+# Repository Guidelines
+
+## Project Purpose
+
+This repository is the customer-delivery edition of the TJWater backend. Treat it as a deployable delivery package, not as the primary internal development repository. Changes should be limited to customer-facing fixes, deployment compatibility, configuration templates, packaging, and delivery documentation.
+
+Do not introduce internal-only experiments, debug utilities, local data, or source material that is not required for customer operation.
+
+## Source Encapsulation Requirement
+
+Core backend source code must be encapsulated before delivery. The sensitive implementation areas include business services, native integrations, hydraulic/network algorithms, and EPANET-related logic, especially:
+
+- `app/services`
+- `app/native`
+- `app/algorithms`
+- `app/infra/epanet`
+
+Use the existing Cython packaging flow in `scripts/compile.py` for these areas. Do not ship uncompiled core `.py` files in the final customer package when compiled extension modules are expected. Keep public entry points, configuration loading, route wiring, and minimal package files readable only where required for runtime and operations.
+
+Before removing source files with `--delete-source`, verify the build from a clean working tree or disposable copy. The delete mode is destructive by design.
+
+## Workspace Structure
+
+- `app/main.py` is the FastAPI entry point.
+- `app/api` contains HTTP route handlers.
+- `app/services` contains core business orchestration and must be protected in delivery builds.
+- `app/native`, `app/algorithms`, and `app/infra/epanet` contain specialized computation and integration code that must be protected in delivery builds.
+- `infra/` and `Dockerfile` contain deployment assets.
+- `scripts/` contains operational and packaging helpers.
+- `tests/` contains backend tests.
+
+## Common Commands
+
+Run commands from this repository root:
+
+```bash
+conda run -n server python -m pytest tests -q
+conda run -n server python scripts/run_server.py
+conda run -n server python scripts/compile.py
+```
+
+Clean compiled extensions when needed:
+
+```bash
+conda run -n server python scripts/compile.py --clean
+```
+
+Only use source deletion in a prepared delivery copy:
+
+```bash
+conda run -n server python scripts/compile.py --delete-source
+```
+
+## Change Policy
+
+Keep changes scoped and conservative. Prefer compatibility patches, configuration adjustments, packaging fixes, and customer deployment hardening. If a change requires substantial business logic updates, make it first in the internal backend repository and then port the reviewed result here.
+
+Do not weaken the encapsulation process to make debugging easier. If debugging requires readable source, do it in the internal repository or a non-delivery branch/copy.
+
+## Testing Guidelines
+
+Run the narrowest useful test command for the affected area. For delivery packaging changes, verify both:
+
+- tests still pass before packaging;
+- the packaged/compiled runtime can import and start the FastAPI app.
+
+Do not add tests that depend on untracked customer data, local database dumps, or machine-specific files.
+
+## Security & Delivery Rules
+
+Never commit `.env`, production credentials, customer data, logs, generated caches, `node_modules/`, database dumps, or temporary delivery archives. Use `.env.example` or deployment documentation for required configuration.
+
+Review Docker and deployment files carefully before delivery. Customer packages should contain only the files needed to run, operate, and diagnose the deployed service.