12c8615615
Adds accounting-service PATCH/archive, fiscal helpers, COA templates and setup status, plus SuperApp Accounting UI (DS, scoreboard, masters, vouchers, ledger, ops modules) with session refresh and HTTPS public API URLs. Co-authored-by: Cursor <cursoragent@cursor.com>
102 lines
2.7 KiB
Markdown
102 lines
2.7 KiB
Markdown
# Coding Standards
|
|
|
|
## Folder Conventions
|
|
|
|
```
|
|
backend/<service>/app/
|
|
api/v1/ # routers
|
|
core/ # config, db, security
|
|
models/
|
|
schemas/ # Pydantic DTOs
|
|
services/ # business logic
|
|
repositories/
|
|
middlewares/
|
|
workers/
|
|
tests/
|
|
|
|
frontend/
|
|
app/ # Next.js App Router pages
|
|
components/
|
|
hooks/
|
|
lib/ # API clients, auth, theme
|
|
styles/
|
|
public/
|
|
```
|
|
|
|
## Naming
|
|
|
|
| Kind | Convention |
|
|
| --- | --- |
|
|
| Files / modules | `snake_case.py`, `PascalCase.tsx` for components |
|
|
| Classes | `PascalCase` |
|
|
| Functions / vars | `snake_case` (Python), `camelCase` (TS) |
|
|
| DB tables / columns | `snake_case` |
|
|
| API paths | `/api/v1/...` kebab or resource nouns |
|
|
| Events | `aggregate.past_tense` |
|
|
| Feature keys | `{service}.{resource}.{action}` |
|
|
| Migrations | Alembic revision with descriptive message |
|
|
|
|
Names are English. Comments may be Persian or English.
|
|
|
|
## Python
|
|
|
|
- Python 3.11+
|
|
- Type hints on public functions
|
|
- Explicit imports; no wildcard imports
|
|
- Raise shared exceptions (`shared.exceptions`) with stable error codes
|
|
|
|
## FastAPI
|
|
|
|
- Versioned routers under `api/v1`
|
|
- Dependencies for auth and tenant
|
|
- Pydantic schemas for request/response — no ORM models in responses
|
|
- Keep route functions thin
|
|
|
|
## Django
|
|
|
|
Not used for new services. If legacy Django appears, do not expand it; prefer FastAPI services.
|
|
|
|
## DTO / Schema Conventions
|
|
|
|
- `Create`, `Update`, `Read`, `List` suffixes
|
|
- Never expose internal secrets or password hashes
|
|
- Paginated lists use shared `Page` meta
|
|
|
|
## Repository Conventions
|
|
|
|
- Accept `tenant_id` for tenant-owned entities
|
|
- No entitlement or workflow decisions
|
|
- Return domain models / rows; services map to DTOs
|
|
|
|
## Service Conventions
|
|
|
|
- One primary service per aggregate/use-case group
|
|
- Write outbox events in the same transaction as state changes
|
|
- Call other services only via HTTP clients / events
|
|
|
|
## Migration Conventions
|
|
|
|
- Autogenerate then review
|
|
- Idempotent seeds where needed (`ON CONFLICT DO NOTHING`)
|
|
- Never edit committed production revisions; add a new revision
|
|
|
|
## Event Naming
|
|
|
|
See [event-driven-architecture.md](../architecture/event-driven-architecture.md).
|
|
|
|
## API Naming
|
|
|
|
Resource nouns, plural collections, verbs only for non-CRUD actions (`/suspend`, `/activate`, `/complete`).
|
|
|
|
## Database Naming
|
|
|
|
- UUID primary keys named `id`
|
|
- Foreign keys `{table_singular}_id`
|
|
- Enums stored as string enums with documented values
|
|
|
|
## Related Documents
|
|
|
|
- [Project Principles](project-principles.md)
|
|
- [Developer Guide](developer-guide.md)
|
|
- [Service Architecture](../architecture/service-architecture.md)
|