romfast/roa2web-service-auto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d507a81b0a143acf1b722380d36415caef5f3537
roa2web-service-auto/README.md
Marius Mutu d507a81b0a feat: Implement unified Vue SPA with granular service control 
Consolidate Reports and Data Entry apps into a single Vue.js SPA with:

Architecture:
- Module-based structure with lazy-loaded routes (@reports, @data-entry)
- Error boundaries per module to prevent cascade failures
- Dual API proxy in Vite for microservices (reports:8001, data-entry:8003)
- Pinia store factories for shared auth, company, and period stores
- Vite path aliases for clear module boundaries (@shared, @reports, @data-entry)

Service Management:
- Granular service control scripts (backend-reports.sh, backend-data-entry.sh, bot.sh, frontend.sh)
- 87% faster frontend restart: 7s vs 53s full restart
- 38% faster full startup: 33s vs 53s via parallel backend initialization
- Enhanced start-dev.sh with proper service timeouts (OCR: 30s, Vite: 15s, Bot: 10s)
- status.sh for comprehensive health checks

Features:
- Auto-select first company on login with period auto-load
- Hamburger menu with feature toggle support
- JWT token auto-injection via axios interceptors
- Unified header with company/period selectors
- IIS web.config for production deployment with multi-API routing

UX Improvements:
- Vue watchers for reactive company/period loading
- Lazy store initialization with graceful error handling
- Period persistence per user+company in localStorage
- Feature flags for optional modules

Deployment:
- Single IIS site serves unified frontend with API proxy rules
- Maintains separate backend processes for microservices
- Windows line ending fixes (.env CRLF → LF conversion)

Stats: 112 files changed, 38,342 insertions(+), 2,342 deletions(-)

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

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-24 19:06:23 +02:00

346 lines
11 KiB
Markdown
Raw Blame History

# ROA2WEB - Modern ERP Reports Application
**FastAPI Backend + Vue.js 3 Frontend + Telegram Bot**
Modern microservices-based ERP reporting application for managing invoices, payments, and financial data with Oracle database integration.
---
## Project Overview
ROA2WEB is a comprehensive financial reporting platform built with modern technologies:
- **Backend**: FastAPI (Python) - High-performance async API
- **Frontend**: Vue.js 3 + PrimeVue - Rich, responsive web interface
- **Telegram Bot**: Alternative command-based interface
- **Database**: Oracle Database with connection pooling
- **Architecture**: Microservices with shared components
---
## Quick Start
### Prerequisites
- Python 3.11+
- Node.js 16+
- Oracle Database access
- SSH access to Oracle server (for development)
### Development Setup
```bash
# Clone repository
git clone <repository-url>
cd roa2web
# Start all services with one command
./start-dev.sh
```
This starts SSH tunnel, backend (port 8001), and frontend (port 3000-3005).
**For individual service setup or troubleshooting**: See "Development & Testing" section below or component-specific READMEs.
### Access the Application
- **Frontend**: http://localhost:3000 (or 3001-3005 if 3000 is busy)
- **Backend API Docs**: http://localhost:8001/docs (Swagger UI)
- **Backend ReDoc**: http://localhost:8001/redoc
- **Health Check**: http://localhost:8001/health
---
## Architecture
### Directory Structure
```
├── shared/ # Shared components
│ ├── database/ # Oracle connection pool (singleton)
│ ├── auth/ # JWT authentication & middleware
│ └── utils/ # Common utilities
│
├── reports-app/ # Main reports application
│ ├── backend/ # FastAPI backend (port 8001)
│ ├── frontend/ # Vue.js 3 frontend (port 3000-3005)
│ └── telegram-bot/ # Telegram bot (port 8002)
│
├── nginx/ # Nginx reverse proxy config
├── ssh-tunnel/ # SSH tunnel for Oracle DB
├── deployment/ # Deployment scripts (Linux & Windows)
└── scripts/ # Utility scripts
```
### Key Features
- **Shared Database Pool**: Singleton Oracle connection pool shared across microservices
- **Two-Tier Cache System**: Hybrid L1 (Memory) + L2 (SQLite) for optimal performance
- **JWT Authentication**: Secure token-based auth with middleware
- **Microservices**: Independent services with clear separation of concerns
- **Oracle Integration**: Direct Oracle stored procedure calls with caching
- **Responsive Design**: Mobile-friendly Vue.js interface
- **Telegram Integration**: Alternative bot-based interface
---
## Tech Stack
**Backend**: FastAPI, python-oracledb, JWT (PyJWT), Pydantic, pytest, **Two-tier cache (Memory + SQLite)**
**Frontend**: Vue.js 3 (Composition API), PrimeVue, Pinia, Vite, Axios, Chart.js, Playwright
**Telegram Bot**: python-telegram-bot, SQLite + aiosqlite, httpx, FastAPI (internal)
**Infrastructure**: Oracle Database, SSH Tunnel, Nginx, Docker (Linux), IIS + NSSM (Windows)
*See `CLAUDE.md` for detailed tech stack information, cache system, and architecture decisions.*
---
## Development & Testing
**Quick Start**: Use `./start-dev.sh` to start all services (SSH tunnel + Backend + Frontend).
**For detailed development commands, testing procedures, and troubleshooting**: See `CLAUDE.md` and component-specific READMEs:
- Backend: `reports-app/backend/README.md`
- Frontend: `reports-app/frontend/README.md` & `reports-app/frontend/tests/README.md`
- Telegram Bot: `reports-app/telegram-bot/README.md`
**Key Commands**:
```bash
# Start All Services (FAST with parallel backend startup - ~11s dev, ~33s test)
./start-dev.sh # Start all (SSH tunnel + Backends + Bot + Frontend)
./start-test.sh # Start all (TEST environment)
# Individual Service Control (NEW - for quick restarts!)
./frontend.sh start|stop|restart|status # Frontend only (~7s restart!)
./backend-reports.sh start|stop|status # Reports backend only
./backend-data-entry.sh start|stop|status # Data Entry backend only
./bot.sh start|stop|status # Telegram bot only
# System Monitoring
./status.sh # Show all services status + health checks
# Infrastructure Only
./ssh_tunnel.sh start|stop|status # Oracle DB tunnel (production)
./ssh-tunnel-test.sh start|stop|status # Oracle TEST tunnel
```
**💡 Pro Tips**:
- **Frontend changes?** Use `./frontend.sh restart` instead of restarting everything (87% faster!)
- **Check what's running:** `./status.sh` shows everything at a glance
- **Backend-uri pornesc în paralel** în start-dev.sh și start-test.sh pentru pornire mai rapidă
### 📖 Usage Flow
**Individual scripts (`frontend.sh`, `backend-*.sh`, `bot.sh`) are environment-neutral:**
- They DON'T change `.env` files
- They use whatever `.env` is already present
- Use them for **quick restarts** when working on a specific service
**Master scripts (`start-dev.sh`, `start-test.sh`) set the environment:**
- `start-dev.sh` → uses existing `.env` files (DEV mode)
- `start-test.sh` → copies `.env.test` → `.env` (TEST mode)
**Recommended workflow:**
```bash
# Morning: Start full stack with environment selection
./start-dev.sh # DEV mode - sets up .env files
# During development: Quick service restarts
./frontend.sh restart # Frontend only (~7s)
./backend-reports.sh restart # Reports backend only (~30s)
# ⚠️ Individual scripts inherit the environment set by start-dev.sh
# End of day: Stop everything
./start-dev.sh stop
```
**Common scenarios:**
```bash
# Scenario 1: Working on frontend only
./start-dev.sh # Start everything once
./frontend.sh restart # Restart frontend multiple times (fast!)
# Scenario 2: Debugging a single backend
./start-dev.sh stop # Stop all
./ssh_tunnel.sh start # Infrastructure only
./backend-reports.sh start # Just the backend you need
./frontend.sh start # Just the frontend
# Scenario 3: Testing mode
./start-test.sh # Starts everything in TEST mode
# All subsequent individual script calls use TEST .env files
# Scenario 4: Check what's running
./status.sh # See all services + health checks
```
**Note**: For automated testing and validation (`/validate` command), use `start-test.sh` which starts all services connected to Oracle TEST server (LXC 10.0.20.121) with test credentials.
**API Documentation** (when backend running):
- Swagger UI: http://localhost:8001/docs
- ReDoc: http://localhost:8001/redoc
- Health Check: http://localhost:8001/health
---
## Production Deployment
ROA2WEB supports two deployment architectures:
### 🐧 Linux/Docker Deployment
```bash
./setup_production.sh # Initial setup
./scripts/deploy.sh # Deploy application
./scripts/health-check.sh # Health monitoring
```
### 🪟 Windows/IIS Deployment
**Modern Unified Workflow** (recommended):
```powershell
# On Development Machine (WSL/Linux)
cd deployment/windows/scripts
.\Publish-And-Deploy.ps1 # Build + Transfer to server (interactive menu)
# On Windows Server (PowerShell as Admin)
cd deployment/windows/scripts
.\ROA2WEB-Console.ps1 # Deploy + Manage services (interactive console)
```
**Alternative - Manual Installation**:
```powershell
# First-time installation
.\Install-ROA2WEB.ps1
.\Install-TelegramBot.ps1
# Automated deployment
.\Check-And-Deploy.ps1
```
**Complete Documentation**:
- **`DEPLOYMENT_GUIDE.md`** - Comprehensive guide for both platforms
- **`deployment/windows/README.md`** - Windows quick start
- **`deployment/windows/docs/WINDOWS_DEPLOYMENT.md`** - Complete Windows guide
---
## API Endpoints
All endpoints prefixed with `/api`:
### Authentication
- `POST /api/auth/login` - Login with Oracle credentials
### Companies
- `GET /api/companies` - Get user's accessible companies
### Dashboard
- `GET /api/dashboard/{company_id}` - Dashboard statistics
### Invoices
- `GET /api/invoices/{company_id}` - List invoices with filters
- `GET /api/invoices/{company_id}/summary` - Invoice summary
### Treasury
- `GET /api/treasury/{company_id}` - Payment data
### Telegram Bot
- `POST /api/telegram/auth/generate-code` - Generate linking code
- `POST /api/telegram/auth/verify-user` - Verify Oracle user
- `POST /api/telegram/auth/refresh-token` - Refresh JWT token
- `POST /api/telegram/export` - Export reports
---
## Environment Configuration
Copy `.env.example` to `.env` in each microservice and configure:
### Backend (`reports-app/backend/.env`)
```bash
# Oracle Database (through SSH tunnel)
ORACLE_USER=your_username
ORACLE_PASSWORD=your_password
ORACLE_HOST=localhost
ORACLE_PORT=1526
ORACLE_SID=ROA
# JWT Authentication
JWT_SECRET_KEY=your_secret_key
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=30
```
### Telegram Bot (`reports-app/telegram-bot/.env`)
```bash
# Telegram Bot Token
TELEGRAM_BOT_TOKEN=your_bot_token
# Backend API
BACKEND_API_URL=http://localhost:8001
```
---
## Documentation
### Quick Reference
- **`CLAUDE.md`** - Development guide for AI/Claude Code (architecture, cache system, common tasks, troubleshooting)
- **`docs/ARCHITECTURE_SCHEMA.md`** - Architecture diagrams, cache system, and schemas
- `docs/MICROSERVICES_GUIDE.md` - Microservices architecture details
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan
### Component-Specific
- `README.md` - Main application README
- `reports-app/backend/README.md` - Backend specifics
- `reports-app/frontend/README.md` - Frontend guide
- `reports-app/frontend/tests/README.md` - Frontend testing
- `reports-app/telegram-bot/README.md` - Telegram bot guide
- `reports-app/telegram-bot/TELEGRAM_COMMANDS.md` - Bot commands
### Frontend Styling & CSS
- `docs/ONBOARDING_CSS.md` - CSS system onboarding guide (start here!)
- `docs/CSS_PATTERNS.md` - Comprehensive CSS patterns library
- `docs/DESIGN_TOKENS.md` - Design tokens reference (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 and patterns
### Deployment
- `DEPLOYMENT_GUIDE.md` - Production deployment (Linux & Windows)
- `deployment/windows/README.md` - Windows quick start
- `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` - Complete Windows guide
---
## Contributing
1. Create feature branch from `main`
2. Make changes following project structure
3. Write tests for new features
4. Run all tests before committing
5. Create pull request with clear description
---
## License
[Your License Here]
---
## Support
For issues and questions:
- Check documentation in `` subdirectories
- Review CLAUDE.md for development guidelines
- See component-specific READMEs for detailed information
---
**Branch**: v2-roa2web-fastapi
**Working Directory**: `` - All development happens here
Reference in New Issue View Git Blame Copy Permalink