romfast/roa2web-service-auto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Restructure styling documentation and add theme toggle docs

Browse Source 
- Simplify CLAUDE.md from ~460 to ~145 lines with imports
- Add Theme System section to css-design-system.md (3 modes: auto/light/dark)
- Document theme toggle UI, localStorage persistence, CSS priority order
- Add paths: frontmatter to authentication.md and company-period.md
- Update DESIGN_TOKENS.md Dark Mode section with toggle documentation
- Clean auto-build-memory.md header (remove non-existent auto-sync reference)
- Remove non-existent plugin from settings.json

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude Agent
2026-01-06 14:58:24 +00:00
parent 1bb3a382de
commit 67b0082df0
7 changed files with 157 additions and 414 deletions
Download Patch File Download Diff File Expand all files Collapse all files

464
CLAUDE.md
View File

@@ -1,437 +1,119 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This file provides guidance to Claude Code when working with code in this repository.
## 🚀 Project Overview
## Project Overview
**ROA2WEB** - Modern ERP Application with ultrathin monolith architecture:
1. **Reports Module** (`backend/modules/reports/`) - Read-only reports from Oracle (raportări)
2. **Data Entry Module** (`backend/modules/data_entry/`) - Data input with approval workflow (introduceri date)
3. **Telegram Bot Module** (`backend/modules/telegram/`) - Telegram bot integration
- **Reports Module** (`backend/modules/reports/`) - Read-only reports from Oracle
- **Data Entry Module** (`backend/modules/data_entry/`) - Data input with approval workflow
- **Telegram Bot Module** (`backend/modules/telegram/`) - Telegram bot integration
**Main Branch**: `main` (use for PRs)
**Working Directory**: Repository root
**Quick Reference**: See `README.md` for complete setup, commands, deployment, and testing instructions.
**Main Branch**: `main` | **Setup & Commands**: See `README.md`
---
## 📁 Module-Specific Instructions
## Module-Specific Instructions
> **IMPORTANT**: When working on a specific module, read its documentation first!
> **IMPORTANT**: Read module documentation FIRST before working on a module!
| Module | Documentation Location | Description |
|--------|----------------------|-------------|
| **Data Entry** | `docs/data-entry/DATA-ENTRY-MODULE.md` | Bonuri fiscale, chitanțe, workflow aprobare |
| **Reports** | This file (below) | Rapoarte Oracle read-only |
| **Telegram Bot** | `docs/telegram/README.md` | Bot Telegram |
### When to Use Which Instructions
**Working on Data Entry** (`backend/modules/data_entry/` or `src/modules/data-entry/`):
→ **FIRST read `docs/data-entry/DATA-ENTRY-MODULE.md`** for:
- SQLModel + Alembic patterns (NOT Oracle)
- SQLite database (NOT Oracle pool)
- Workflow states (DRAFT → PENDING → APPROVED)
- Receipt/Attachment/AccountingEntry models
- Expense types and auto-generation logic
- Oracle nomenclatures integration
**Working on Reports Module** (`backend/modules/reports/` or `src/modules/reports/`):
→ Use instructions from this file (below)
**Working on shared components** (`shared/auth/`, `shared/database/`, `shared/frontend/`):
→ These are used by ALL modules - be careful with changes!
→ `shared/frontend/` contains: LoginView.vue, auth store factory, login styles
| Module | Documentation | Key Points |
|--------|--------------|------------|
| **Data Entry** | `docs/data-entry/DATA-ENTRY-MODULE.md` | SQLModel, SQLite, workflow states |
| **Reports** | This file + `README.md` | Oracle read-only, caching |
| **Telegram** | `docs/telegram/README.md` | Bot commands, formatting |
---
## 🏗️ Architecture
## Quick Reference
> **Important Architecture Decisions:** See `docs/ARCHITECTURE-DECISIONS.md` for critical decisions about:
> - Why single worker (`--workers 1`) is required for Telegram bot
> - Ultrathin monolith vs microservices rationale
> - IIS sub-application deployment strategy
> - Performance characteristics and scaling considerations
### Ultrathin Monolith Structure
```
.
├── backend/ # Unified FastAPI backend (port 8000/8001)
│ ├── modules/ # Business logic modules
│ │ ├── reports/ # Reports module (Oracle read-only)
│ │ ├── data_entry/ # Data entry module (SQLite + workflow)
│ │ ├── telegram/ # Telegram bot module
│ │ └── data/ # Shared data (telegram_bot.db)
│ ├── config.py # Centralized configuration
│ └── main.py # FastAPI app entry point
│
├── src/ # Unified Vue.js 3 frontend
│ ├── modules/ # Feature modules
│ │ ├── reports/ # Reports frontend
│ │ └── data-entry/ # Data entry frontend
│ ├── shared/ # Shared frontend components
│ │ ├── components/ # Reusable Vue components
│ │ └── stores/ # Pinia stores
│ ├── assets/ # Global CSS, images
│ ├── router/ # Vue Router
│ └── App.vue # Root component
│
├── shared/ # Shared backend components
│ ├── database/ # Oracle pool
│ ├── auth/ # JWT auth & middleware
│ └── frontend/ # Shared frontend assets
│ ├── components/ # LoginView.vue
│ ├── stores/ # Auth store factory
│ └── styles/ # Login CSS
│
├── docs/ # Architecture & style guides
├── deployment/ # Production deployment scripts
└── ssh-tunnel/ # SSH tunnel for Oracle DB access
```
### Architecture
See `docs/ARCHITECTURE-DECISIONS.md` for:
- Single worker (`--workers 1`) - required for Telegram bot
- Ultrathin monolith rationale
- IIS deployment strategy
### Starting Services
**Quick Start** (Unified backend + frontend):
```bash
./start-prod.sh # Prod env: Backend :8001, Frontend :3000
./start-test.sh # Test env: Backend :8001, Frontend :3000
./start-prod.sh # Backend :8001 + Frontend :3000
./ssh-tunnel-prod.sh # Oracle DB tunnel (REQUIRED on Linux)
./status.sh # Check services
```
**Individual Service Control**:
```bash
./start-frontend.sh restart # Restart frontend only (~7s - fastest!)
./start-backend.sh # Start unified backend :8000 or :8001
./status.sh # Show services status + health checks
```
**Infrastructure**:
```bash
./ssh-tunnel-prod.sh start # Oracle DB tunnel (production: 10.0.20.36)
./ssh-tunnel-test.sh start # Oracle TEST tunnel (LXC: 10.0.20.121)
```
**Benefits**:
- **Single backend process**: All modules in one FastAPI app
- **Faster startup**: No multi-service coordination overhead
- **Easier debugging**: Single process to monitor
- **Shared resources**: Connection pools, cache, and middleware
### Key Architectural Decisions
**Core Architecture:**
- **Ultrathin Monolith**: Single backend process with modular structure (`backend/modules/`)
- **Single Worker Mode**: `--workers 1` (required for Telegram bot - see ADR-002 in `docs/ARCHITECTURE-DECISIONS.md`)
- **Shared Database Pool**: Singleton `OraclePool` in `shared/database/oracle_pool.py` (python-oracledb with connection pooling)
- **Centralized Auth**: JWT-based auth in `shared/auth/` with middleware auto-injecting `request.state.user`
**Module-Specific:**
- **Module-Based Cache**: Each module can have its own cache strategy (Reports uses L1+L2 hybrid cache)
- **Telegram Bot**: Integrated module with SQLite database (`backend/modules/data/telegram_bot.db`)
- **FastAPI Structure**: Modules in `backend/modules/*/`, each with services, routers, models/schemas
**Infrastructure:**
- **SSH Tunnel**: Required for Oracle DB connections (development/Linux) - see Database Setup
- **IIS Sub-Application**: Deployed at `/roa2web` path, not root (production)
> **For detailed rationale and trade-offs**, see `docs/ARCHITECTURE-DECISIONS.md`
### Database
- **Schema**: `CONTAFIN_ORACLE`
- **Connection**: SSH tunnel required (Linux dev)
- **Env**: `backend/.env` (see `backend/ENV-SETUP.md`)
---
## 🗄️ Database Setup
## Key Rules (ALWAYS FOLLOW)
**Schema**: `CONTAFIN_ORACLE` (authentication and user management)
**Connection**: SSH tunnel required (Oracle on remote network)
### Frontend Development
**Before writing CSS**: Read `docs/ONBOARDING_CSS.md` (5 min)
### SSH Tunnel (Development/Linux)
```bash
./ssh-tunnel-prod.sh start # localhost:1526 → remote:1521
./ssh-tunnel-prod.sh status # Check tunnel
./ssh-tunnel-prod.sh stop # Stop tunnel
```
- Use design tokens: `var(--color-primary)` not `#2563eb`
- Use shared CSS from `src/assets/css/` - NEVER duplicate
- Check `docs/CSS_PATTERNS.md` for existing patterns
- **Theme toggle**: App has 3 modes (auto/light/dark) - test BOTH themes!
**IMPORTANT**: Always ensure SSH tunnel is running before starting backend services.
**Tables**:
- Use separate columns (Debit | Credit, not stacked)
- Filter buttons on separate row below filters
- Export ALL data, not just current page
### Environment Variables (`backend/.env`)
```bash
# Oracle Database (through SSH tunnel)
ORACLE_USER=CONTAFIN_ORACLE
ORACLE_PASSWORD=your_password
ORACLE_HOST=localhost
ORACLE_PORT=1526
ORACLE_SID=ROA
### Backend Development
- Place logic in **services**, not routers
- Use `@cached` decorator for ALL database queries
- Cache schema lookups separately (24h TTL)
# JWT Authentication
JWT_SECRET_KEY=your_secret_key
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=30
# Module Configuration
MODULE_REPORTS_ENABLED=true
MODULE_DATA_ENTRY_ENABLED=true
MODULE_TELEGRAM_ENABLED=true
```
**Windows Production**: Direct Oracle connection, no SSH tunnel required.
**Environment Files**: Multiple .env files available (.env.dev, .env.test, .env.prod) - see `backend/ENV-SETUP.md` for details.
---
## 🔑 Authentication Flow
1. **Login**: `POST /api/auth/login` → calls `pack_drepturi.verificautilizator(username, password)`
2. **Token**: JWT includes `username`, `user_id`, `companies[]`, `permissions[]`, `exp`, `iat`, `type`
3. **Middleware**: `AuthenticationMiddleware` in `shared/auth/middleware.py` validates tokens, injects user
4. **Protected Routes**: All routes except `excluded_paths` require valid JWT
**Key Files**:
- `shared/auth/middleware.py` - FastAPI middleware with rate limiting (5 req/5 min)
- `shared/auth/jwt_handler.py` - Token creation/validation
- `backend/main.py` - Main FastAPI app with auth router registration
---
## 📝 Common Development Tasks
### Adding a New API Endpoint
**IMPORTANT**: Always use the cache system for database queries to improve performance.
1. Create **service** in `backend/modules/reports/services/your_service.py` (NOT in router!)
2. Define Pydantic schemas in `modules/*/schemas/` or `modules/*/models/`
3. **Add caching** using `@cached` decorator in service methods
4. Create router in `backend/modules/reports/routers/your_router.py` (calls service)
5. Register router in `app/main.py`: `app.include_router(your_router, prefix="/api/your_prefix")`
**Service Example with Caching** (RECOMMENDED):
**Service pattern**:
```python
# app/services/your_service.py
from app.cache.decorators import cached
from database.oracle_pool import oracle_pool
class YourService:
@staticmethod
@cached(cache_type='schema', key_params=['company_id'])
async def _get_schema(company_id: int) -> str:
"""Get schema for company (CACHED 24h)"""
async with oracle_pool.get_connection() as connection:
with connection.cursor() as cursor:
cursor.execute("""
SELECT schema FROM CONTAFIN_ORACLE.v_nom_firme
WHERE id_firma = :company_id
""", {'company_id': company_id})
result = cursor.fetchone()
return result[0] if result else None
@staticmethod
@cached(cache_type='your_data', key_params=['filter_params', 'username'])
async def get_your_data(filter_params: YourFilter, username: str) -> YourResponse:
"""
Get your data from Oracle (CACHED 10 min)
Cache automatically:
- Generates unique key from filter_params + username
- Stores in L1 (memory) + L2 (SQLite)
- Returns cached data on subsequent calls
- Tracks performance metrics
"""
schema = await YourService._get_schema(filter_params.company_id)
async with oracle_pool.get_connection() as connection:
with connection.cursor() as cursor:
cursor.execute(f"""
SELECT * FROM {schema}.your_table
WHERE your_condition = :param
""", {'param': filter_params.param})
rows = cursor.fetchall()
# Process results...
return YourResponse(data=processed_data)
@cached(cache_type='your_data', key_params=['company_id', 'username'])
async def get_data(company_id: int, username: str):
# Query Oracle here
```
**Router Example** (calls service):
```python
# app/routers/your_router.py
from app.services.your_service import YourService
@router.get("/", response_model=YourResponse)
async def get_your_data(
filter_params: YourFilter = Depends(),
current_user: CurrentUser = Depends(get_current_user)
):
"""Get your data - delegated to service with caching"""
return await YourService.get_your_data(filter_params, current_user.username)
```
**Cache Configuration** (add to `app/cache/config.py` if new cache type):
```python
# Add TTL for your cache type
ttl_your_data: int = int(os.getenv('CACHE_TTL_YOUR_DATA', '600')) # 10 min default
# Add to get_ttl_for_type() method:
'your_data': self.ttl_your_data,
```
**Cache Best Practices**:
- ✅ Use `@cached` decorator for ALL database queries
- ✅ Place logic in services (NOT routers)
- ✅ Cache schema lookups separately (long TTL: 24h)
- ✅ Choose appropriate TTL (frequently changing data: 5-10 min, static data: 30 min - 24h)
- ✅ Include `username` in `key_params` for user-specific data
- ✅ Include filter parameters in `key_params` for query variations
- ❌ Don't query Oracle directly in routers (use services with caching)
- ❌ Don't skip caching for performance-critical endpoints
### Adding a New Frontend Page/Component
**IMPORTANT**: Follow the established CSS architecture and design system.
**Before writing ANY CSS**: Read **`docs/ONBOARDING_CSS.md`** (5-minute quick start) → See "Documentation Index" below for complete guide list.
**Golden Rules**:
- ✅ Use global patterns first (`.roa-card`, `.roa-metric`, `.roa-badge-*`) - check `CSS_PATTERNS.md`
- ✅ Use design tokens (`var(--color-primary)`) not hardcoded values (`#2563eb`)
- ✅ **Use shared CSS** from `src/assets/css/` - NEVER create new CSS when shared classes exist
- ✅ For inline stats/totals use `.summary-stats-inline`, `.stat-item`, `.stat-label`, `.stat-value` from `stats.css`
- ❌ Never use `:deep()` in components (use `src/assets/css/vendor/` for PrimeVue overrides)
- ❌ Never duplicate CSS (write once, use everywhere)
- ❌ Never add new scoped CSS for patterns that already exist in shared CSS files
**Tables - Unified Column Structure & Filter Buttons**:
- ✅ **ALWAYS use separate columns** for related data (Debit | Credit, not Debit+Credit stacked)
- ✅ **Use PrimeVue DataTable** with one value per `<Column>` component
- ✅ **Add filter/action buttons** (clear, export Excel, export PDF, refresh) **on separate row below filters**
- ✅ **PrimeVue Button** components with **icon + label** (not icon-only!)
- ✅ **Export ALL data** from backend (page_size: 999999), not just current page
- ❌ **Never group multiple values** vertically in a single column
- ❌ **Never use HTML `<button>` for filter actions** (use PrimeVue `<Button>`)
- ❌ **Never put action buttons on same row as filters** (separate row!)
- ❌ **Never export only current page** (must fetch all data for export)
- 📖 **See**: `CSS_PATTERNS.md` → Table Patterns → Unified Table Column Structure & Filter/Action Buttons
### Adding a New Telegram Bot Command
**IMPORTANT**: Follow established command patterns and formatting.
**Before coding**: Read **`docs/telegram/TELEGRAM_BUTTON_INTERFACE_PLAN.md`** for command patterns → See "Documentation Index" for complete guides.
**Standard Pattern** (add handler in `app/bot/handlers.py`):
```python
async def your_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
telegram_id = update.effective_user.id
# 1. Check authentication (use helpers.py)
user = await get_user_by_telegram_id(telegram_id)
if not user:
await update.message.reply_text("⚠️ Account not linked. Use /start with code.")
return
# 2. Check active company (use session.py)
active_company = await get_active_company(telegram_id)
if not active_company:
await update.message.reply_text("⚠️ Select company first: /selectcompany")
return
# 3. Call backend API (use api/client.py)
# 4. Format response (use formatters.py)
# 5. Add tests + update MANUAL_TESTING_CHECKLIST.md
```
### Adding Shared Functionality
1. Place in `shared/{database|auth|utils}/`
2. Import using `sys.path.append()` pattern (see `backend/app/main.py:21`)
3. Add tests in `shared/tests/`
### Frontend API Integration
```javascript
// Store pattern (src/stores/yourStore.js)
import axios from 'axios';
const api = axios.create({
baseURL: 'http://localhost:8001/api',
headers: { 'Authorization': `Bearer ${token}` }
});
const response = await api.get('/endpoint');
```
### Authentication
- JWT structure: `username`, `user_id`, `companies[]`, `permissions[]`, `exp`, `iat`, `type`
- Middleware: `shared/auth/middleware.py` (auto-injects `request.state.user`)
- Rate limiting: 5 req/5 min for `/auth/*`
---
## 🔒 Security
## Documentation Index
- **Git Hooks**: Security scanning in `security/install_hooks.sh`
- **Environment Files**: Never commit `.env` (use `.env.example` as template)
- **SSH Keys**: In `ssh-tunnel/secrets/` (gitignored)
- **JWT Secrets**: Generate strong secrets for production
- **Rate Limiting**: Built into auth middleware (5 requests per 5 minutes)
| Topic | File | Description |
|-------|------|-------------|
| **Setup** | `README.md` | Commands, testing, deployment |
| **Architecture** | `docs/ARCHITECTURE-DECISIONS.md` | Critical decisions |
| **CSS Quick Start** | `docs/ONBOARDING_CSS.md` | START HERE for frontend |
| **CSS Patterns** | `docs/CSS_PATTERNS.md` | Cards, forms, buttons, tables |
| **Design Tokens** | `docs/DESIGN_TOKENS.md` | Colors, spacing, dark mode |
| **Data Entry** | `docs/data-entry/DATA-ENTRY-MODULE.md` | SQLModel, workflow |
| **Telegram** | `docs/telegram/README.md` | Bot development |
| **Deployment** | `deployment/linux/README.md` | Deploy from LXC |
---
## 📚 Documentation Index
## Learned Patterns & Known Issues
### Quick Start & Commands
→ **`README.md`** - Project overview, setup, development commands, testing, deployment
### Data Entry App (Bonuri Fiscale)
- **`docs/data-entry/CLAUDE.md`** - ⚠️ **READ FIRST** when working on data-entry
- `docs/data-entry/README.md` - Quick start guide
- `docs/data-entry/REQUIREMENTS.md` - Functional requirements
- `docs/data-entry/ARCHITECTURE.md` - Technical architecture (SQLModel, workflow)
### Architecture & Planning
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan
### Frontend Development
- **`docs/ONBOARDING_CSS.md`** - CSS system quick start (START HERE for new components)
- **`docs/CSS_PATTERNS.md`** - Complete CSS patterns library (cards, forms, buttons, etc.)
- **`docs/DESIGN_TOKENS.md`** - Design tokens (colors, spacing, typography)
- `docs/STYLING_GUIDELINES.md` - CSS best practices and conventions
- `docs/COMPONENT_STYLING.md` - Component-specific styling guide
- `docs/FORM_TEMPLATE.md` - Standardized form template
- `Frontend module documentation in src/modules/` - Frontend architecture and setup
- `Playwright E2E testing (see tests/ directory)` - Playwright E2E testing guide
### Backend Development
- `Backend module documentation in backend/modules/` - Backend architecture and API details
- API endpoints documented in `README.md` (Authentication, Companies, Dashboard, Invoices, Treasury, Telegram)
### Telegram Bot Development
- **`docs/telegram/README.md`** - Complete bot architecture and development guide (START HERE)
- **`docs/telegram/TELEGRAM_BUTTON_INTERFACE_PLAN.md`** - Command reference and patterns
- `tests/MANUAL_TESTING_CHECKLIST.md` - Manual testing procedures
### Deployment
**🚀 Quick Deploy from Claude-Agent LXC:**
```bash
# Din orice director ROA2WEB (main, worktree, branch):
./deployment/linux/deploy.sh # Full deploy (frontend + backend)
./deployment/linux/deploy.sh frontend # Frontend only
./deployment/linux/deploy.sh backend # Backend only
./deployment/linux/deploy.sh test # Test SSH connection
```
→ Server auto-deploys within 5 minutes (scheduled task)
- **`deployment/linux/README.md`** - ⚠️ **DEPLOY FROM LXC** - Linux to Windows deployment guide
- `deployment/windows/README.md` - Windows deployment quick start
- `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` - Complete Windows guide
- **`deployment/windows/docs/TWO-TIER-IIS-DEPLOYMENT.md`** - ⚠️ **PRODUCTION ARCHITECTURE** - 2-tier IIS setup with public gateway
- `deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md` - Bot troubleshooting
### Troubleshooting
→ **`README.md`** - Common issues (SSH tunnel, backend, frontend, database)
→ **Backend**: Check `.env`, SSH tunnel status, port 8001 availability
→ **Frontend**: Clear node_modules, check Node.js version (16+), Vite auto-ports
→ **Database**: Verify SSH tunnel, Oracle listener, credentials, test `/health`
> **Patterns/Gotchas from previous sessions**: Auto-loaded from `.claude/rules/auto-build-memory.md`
### Known Issues & Fixes
#### Mobile File Upload ERR_NETWORK (Android/iOS)
**Problem**: File uploads (OCR, attachments) fail with `ERR_NETWORK` (status 0) on mobile browsers, but work on desktop.
**Problem**: File uploads fail with `ERR_NETWORK` (status 0) on mobile browsers.
**Cause**: Android/iOS browsers invalidate File object references after accessing properties (`file.name`, `file.size`, `file.type`) due to **SnapshotState** in the W3C File API. See [Chromium Bug #40703873](https://issues.chromium.org/40703873).
**Cause**: Android/iOS browsers invalidate File object references after accessing properties due to SnapshotState in W3C File API. See [Chromium Bug #40703873](https://issues.chromium.org/40703873).
**Solution**: Clone the file into memory immediately after selection, before accessing any properties:
**Solution**: Clone the file into memory immediately after selection:
```javascript
const handleFile = async (file) => {
// Validations first...
// FIX: Clone file to memory to avoid SnapshotState invalidation
const arrayBuffer = await file.arrayBuffer()
const clonedFile = new File([arrayBuffer], file.name, {
@@ -446,13 +128,17 @@ const handleFile = async (file) => {
---
## 🔧 Tech Stack
## Security
**Backend**: FastAPI, python-oracledb, JWT (PyJWT), Pydantic, pytest
**Frontend**: Vue.js 3 (Composition API), PrimeVue, Pinia, Vite, Axios, Chart.js, Playwright
**Telegram Bot**: python-telegram-bot, SQLite + aiosqlite, httpx, FastAPI (internal), pytest
**Infrastructure**: Oracle Database, SSH Tunnel, Nginx (Linux prod), Docker (Linux prod), IIS + NSSM (Windows prod)
- Never commit `.env` files
- SSH keys in `ssh-tunnel/secrets/` (gitignored)
- Rate limiting in auth middleware
---
**For detailed information on any topic, always check the Documentation Index above first.**
## Tech Stack
**Backend**: FastAPI, python-oracledb, JWT, Pydantic
**Frontend**: Vue.js 3, PrimeVue, Pinia, Vite
**Telegram**: python-telegram-bot, SQLite, httpx
**Infra**: Oracle DB, SSH Tunnel, IIS (Windows prod)