radionica3d/docs/development.md

Development Workflow

This guide explains how to set up your local environment and perform common development tasks.

Local Setup

1. Prerequisites

• Node.js (v18+)
• Python (v3.11+)
• Git

2. Frontend Setup

npm install
# Generate initial translations
backend\.venv\Scripts\python.exe scripts\manage_locales.py split
# Start dev server
npm run dev

3. Backend Setup

cd backend
python -m venv .venv
# Activate venv
.venv\Scripts\activate
# Install deps
pip install -r requirements.txt
# Run server
python -m uvicorn main:app --port 8000 --reload

Common Tasks

Adding a new Translation Key

The localization system is the heart of the project's multi-language support.

1. Add the key to the appropriate file in src/locales/master_user/ or master_admin/.
2. Provide values for all 4 languages.
3. Run backend\.venv\Scripts\python.exe scripts\manage_locales.py split.
4. Use the key in your Vue component: {{ t('category.key') }}.

Modifying the Database

1. Create a new SQL file in backend/migrations/ (e.g., 004_add_user_preferences.sql).

2. Run the migration script:

   python backend/run_migrations.py
   

3. Update Pydantic models in backend/schemas.py.

Testing

• Backend Tests: Located in backend/tests/. Run with pytest.

  pytest backend/tests
  

• Frontend Tests: Located alongside components as *.test.ts. Run with npm run test.

Code Style and Standards

• Frontend: Use Composition API with <script setup>. Follow Tailwind's utility-first approach but keep complex styles in index.css if necessary.
• Backend: Use type hints everywhere. Document complex logic in services. Follow the "Router -> Service -> DB" flow.

Guidelines for Contributions

• Always work in a feature branch.
• Ensure npm run lint passes before committing.
• Do not commit large binary files or secrets (.env files).
• Keep the legacy/ folder clean; move only truly obsolete scripts there.