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>
118 lines
4.4 KiB
Markdown
118 lines
4.4 KiB
Markdown
# راهنمای توسعهدهنده (Developer Guide)
|
||
|
||
## ۱. پیشنیازها
|
||
- Python 3.11+ (backend)
|
||
- Node.js 18+ (frontend)
|
||
- Docker و Docker Compose (برای اجرای کامل)
|
||
- PostgreSQL 15+ و Redis (در صورت اجرای بدون Docker)
|
||
|
||
## ۲. قانون جداسازی Frontend/Backend (اجباری)
|
||
- تمام کد backend فقط در `backend/` قرار دارد.
|
||
- تمام کد frontend فقط در `frontend/` قرار دارد.
|
||
- ارتباط فقط از طریق REST API نسخهدار (`lib/api-client.ts` در frontend).
|
||
- جزئیات در [`architecture.md`](../architecture/architecture.md) و [`module-boundaries.md`](../architecture/module-boundaries.md).
|
||
|
||
## ۳. راهاندازی با Docker
|
||
```bash
|
||
cp .env.example .env
|
||
docker compose up -d --build
|
||
```
|
||
سرویسها: Core API روی `:8000`، Identity روی `:8001`، Frontend روی `:3000`،
|
||
Keycloak روی `:8080`. همه با `docker compose up -d --build` بالا میآیند.
|
||
|
||
## ۴. راهاندازی محلی — Backend
|
||
```bash
|
||
cd backend/core-service
|
||
python -m venv .venv
|
||
# Windows: .venv\Scripts\Activate.ps1 | Linux/macOS: source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
alembic upgrade head
|
||
uvicorn app.main:app --reload
|
||
```
|
||
|
||
## ۵. راهاندازی محلی — Frontend
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
Frontend: http://localhost:3000
|
||
|
||
## ۶. متغیرهای محیطی
|
||
همه تنظیمات در `.env` هستند (نمونه: `.env.example`). هیچ مقداری در کد
|
||
hardcode نمیشود.
|
||
|
||
**Backend:** `DATABASE_URL`, `DATABASE_URL_SYNC`, `REDIS_URL`, `CELERY_BROKER_URL`,
|
||
`KEYCLOAK_*`, `INTERNAL_TOKEN_SECRET`, `PLATFORM_*`.
|
||
|
||
**Frontend:** `NEXT_PUBLIC_API_BASE_URL` (پیشفرض: `http://localhost:8000`).
|
||
|
||
## ۷. ساختار backend
|
||
```
|
||
backend/
|
||
├── core-service/app/
|
||
│ ├── api/v1/ # routerها
|
||
│ ├── core/ # config, database, cache, security, logging
|
||
│ ├── models/ # مدلهای SQLAlchemy
|
||
│ ├── schemas/ # اسکیماهای Pydantic
|
||
│ ├── services/ # منطق کسبوکار
|
||
│ ├── repositories/ # دسترسی به داده
|
||
│ ├── middlewares/ # تشخیص tenant
|
||
│ ├── workers/ # Celery
|
||
│ └── tests/ # تستها
|
||
├── shared-lib/ # کتابخانه مشترک backend
|
||
└── services/ # placeholder سرویسهای آینده
|
||
```
|
||
|
||
## ۸. ساختار frontend
|
||
```
|
||
frontend/
|
||
├── app/ # صفحات Next.js (App Router)
|
||
├── components/ # کامپوننتهای UI
|
||
├── hooks/ # React hooks
|
||
├── lib/ # API client، theme
|
||
├── styles/ # CSS global
|
||
└── public/ # فایلهای استاتیک
|
||
```
|
||
|
||
## ۹. Migrations (Alembic)
|
||
```bash
|
||
cd backend/core-service
|
||
alembic revision --autogenerate -m "توضیح"
|
||
alembic upgrade head
|
||
```
|
||
|
||
## ۱۰. اجرای تستها (Backend)
|
||
```bash
|
||
cd backend/core-service
|
||
pytest -q
|
||
```
|
||
|
||
## ۱۱. Celery
|
||
```bash
|
||
cd backend/core-service
|
||
celery -A app.workers.celery_app.celery_app worker -Q default,core_events,notifications,webhooks
|
||
celery -A app.workers.celery_app.celery_app beat
|
||
```
|
||
|
||
## ۱۲. الگوهای کدنویسی
|
||
- کامل در [`coding-standards.md`](coding-standards.md) و [`project-principles.md`](project-principles.md).
|
||
- منطق کسبوکار فقط در backend (`services/`).
|
||
- UI فقط در frontend.
|
||
- خطاها از `shared.exceptions` استفاده کنند.
|
||
|
||
## ۱۳. افزودن سرویس جدید (فازهای بعدی)
|
||
1. پوشه سرویس را در `backend/services/` توسعه دهید.
|
||
2. دیتابیس مستقل با `tenant_id` بسازید.
|
||
3. قابلیتها را در Core ثبت کنید و [`module-registry.md`](../module-registry.md) را بهروز کنید.
|
||
4. UI مربوطه را در `frontend/` بسازید (فقط از API استفاده کند).
|
||
5. ارتباط را فقط از طریق API/Event برقرار کنید.
|
||
6. مستندات architecture/reference/phase را همزمان بهروز کنید — [`docs/README.md`](../README.md).
|
||
|
||
## Related Documents
|
||
|
||
- [Architecture Overview](../architecture/architecture.md)
|
||
- [Testing Strategy](testing-strategy.md)
|
||
- [Deployment](../deployment/deployment.md)
|
||
- [Services Contracts](../reference/services-contracts.md)
|