refactor: align repo layout and logging safeguards

2026-01-29 17:02:09 +08:00
parent 6af0989fe7
commit c2e65fa157
56 changed files with 1881 additions and 890 deletions
@@ -1,6 +1,57 @@
 ## Docker Startup

-Must use environment file when starting services:
+Always start services with the env file:
 ```bash
-docker compose --env-file infra/env/.env.local -f infra/local/docker-compose.yml up -d
+docker compose --env-file .env -f docker/docker-compose.yml up -d
 ```
+
+## Python Environment
+
+**MUST use uv for dependency management and virtual environment execution.**
+
+- All Python commands: `uv run <command>`
+- Add dependencies: `uv add <package>`
+- All dependencies declared in `pyproject.toml`
+
+## Code Quality Checks
+
+**Git pre-commit hook enforces code quality before commit.**
+
+Pre-commit hook automatically runs on api/ directory:
+- `ruff check` - code style and linting
+- `basedpyright` - type checking with error level
+
+If any error detected, commit is rejected. Fix errors before committing.
+Do not bypass or weaken checks (no ignores, disables, or config relaxations). Resolve the underlying issues.
+
+
+## TDD First Policy
+
+**Principle: tests before implementation.**
+
+### Coverage Requirements
+- Minimum coverage: 80%
+- Required test types:
+  - Unit: isolated functions, utilities, components
+  - Integration: API endpoints, database operations
+  - E2E: critical user flows (Playwright)
+
+### Limited Exceptions
+- Docs-only changes (README, comments, formatting) may skip integration/E2E
+- Non-runtime config changes may skip E2E if no behavior changes
+- Any runtime code change requires unit + integration + E2E
+- If an exception is used, record the reason in the PR/test notes
+
+### Mandatory TDD Workflow
+1. Write tests (RED) - they must fail
+2. Run tests - confirm failure
+3. Implement minimal code (GREEN) - only to pass
+4. Run tests - confirm success
+5. Refactor (IMPROVE)
+6. Verify coverage - must be 80%+
+
+### Enforcement
+- Must use the `tdd-guide` agent for new features
+- Do not write implementation before tests
+- Do not lower coverage requirements
+- Must include unit, integration, and E2E tests