Initial commit: ROA2WEB - FastAPI + Vue.js + Telegram Bot
Modern ERP Reports Application with microservices architecture Tech Stack: - Backend: FastAPI + python-oracledb (Oracle DB integration) - Frontend: Vue.js 3 + PrimeVue + Vite - Telegram Bot: python-telegram-bot + SQLite - Infrastructure: Shared database pool, JWT authentication, SSH tunnel Features: - FastAPI backend with async Oracle connection pool - Vue.js 3 responsive frontend with PrimeVue components - Telegram bot alternative interface - Microservices architecture with shared components - Complete deployment support (Linux Docker + Windows IIS) - Comprehensive testing (Playwright E2E + pytest) Repository Structure: - reports-app/ - Main application (backend, frontend, telegram-bot) - shared/ - Shared components (database pool, auth, utils) - deployment/ - Deployment scripts (Linux & Windows) - docs/ - Project documentation - security/ - Security scanning and git hooks
This commit is contained in:
393
README.md
Normal file
393
README.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# 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 (SSH tunnel + Backend + Frontend)
|
||||
cd roa2web
|
||||
./start-dev.sh
|
||||
|
||||
# Or start services individually:
|
||||
|
||||
# 1. Start SSH tunnel for Oracle DB
|
||||
./ssh_tunnel.sh start
|
||||
|
||||
# 2. Start FastAPI backend (port 8001)
|
||||
cd reports-app/backend
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
|
||||
|
||||
# 3. Start Vue.js frontend (port 3000-3005)
|
||||
cd reports-app/frontend
|
||||
npm install
|
||||
npm run dev
|
||||
|
||||
# 4. Start Telegram Bot (optional, port 8002)
|
||||
cd reports-app/telegram-bot
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
python -m app.main
|
||||
```
|
||||
|
||||
### 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
|
||||
- **JWT Authentication**: Secure token-based auth with middleware
|
||||
- **Microservices**: Independent services with clear separation of concerns
|
||||
- **Oracle Integration**: Direct Oracle stored procedure calls
|
||||
- **Responsive Design**: Mobile-friendly Vue.js interface
|
||||
- **Telegram Integration**: Alternative bot-based interface
|
||||
|
||||
---
|
||||
|
||||
## Core Technologies
|
||||
|
||||
### Backend
|
||||
- **FastAPI**: Modern, high-performance Python web framework
|
||||
- **python-oracledb**: Oracle database driver with connection pooling
|
||||
- **JWT (PyJWT)**: Token-based authentication
|
||||
- **Pydantic**: Data validation and settings management
|
||||
- **pytest**: Comprehensive testing
|
||||
|
||||
### Frontend
|
||||
- **Vue.js 3**: Progressive JavaScript framework (Composition API)
|
||||
- **PrimeVue**: Rich UI component library
|
||||
- **Pinia**: State management
|
||||
- **Vue Router**: Client-side routing
|
||||
- **Vite**: Fast build tool
|
||||
- **Axios**: HTTP client
|
||||
- **Chart.js**: Data visualization
|
||||
- **Playwright**: E2E testing
|
||||
|
||||
### Telegram Bot
|
||||
- **python-telegram-bot**: Telegram Bot API wrapper
|
||||
- **SQLite + aiosqlite**: Standalone database for bot data
|
||||
- **httpx**: Async HTTP client for backend communication
|
||||
- **FastAPI**: Internal API for backend callbacks
|
||||
|
||||
### Infrastructure
|
||||
- **Oracle Database**: Enterprise data storage
|
||||
- **SSH Tunnel**: Secure database access (development)
|
||||
- **Nginx**: Reverse proxy and load balancer (production)
|
||||
- **Docker**: Containerization (production)
|
||||
|
||||
---
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Backend (FastAPI)
|
||||
|
||||
```bash
|
||||
cd reports-app/backend
|
||||
|
||||
# Development server with auto-reload
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
|
||||
|
||||
# Run tests
|
||||
pytest -v
|
||||
|
||||
# API documentation
|
||||
# Swagger UI: http://localhost:8001/docs
|
||||
# ReDoc: http://localhost:8001/redoc
|
||||
```
|
||||
|
||||
### Frontend (Vue.js)
|
||||
|
||||
```bash
|
||||
cd reports-app/frontend
|
||||
|
||||
# Development server
|
||||
npm run dev
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Preview production build
|
||||
npm run preview
|
||||
|
||||
# Lint code
|
||||
npm run lint
|
||||
|
||||
# E2E tests (Playwright)
|
||||
npm run test:e2e
|
||||
npm run test:e2e:ui # Interactive UI mode
|
||||
npm run test:e2e:debug # Debug mode
|
||||
```
|
||||
|
||||
### Telegram Bot
|
||||
|
||||
```bash
|
||||
cd reports-app/telegram-bot
|
||||
|
||||
# Run bot
|
||||
python -m app.main
|
||||
|
||||
# Run tests
|
||||
pytest tests/ -v
|
||||
|
||||
# Health check
|
||||
curl http://localhost:8002/internal/health
|
||||
```
|
||||
|
||||
### SSH Tunnel Management
|
||||
|
||||
```bash
|
||||
cd roa2web
|
||||
|
||||
# Start tunnel (localhost:1526 -> remote Oracle:1521)
|
||||
./ssh_tunnel.sh start
|
||||
|
||||
# Check status
|
||||
./ssh_tunnel.sh status
|
||||
|
||||
# Stop tunnel
|
||||
./ssh_tunnel.sh stop
|
||||
|
||||
# Restart tunnel
|
||||
./ssh_tunnel.sh restart
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Backend Tests
|
||||
```bash
|
||||
cd shared
|
||||
python -m pytest -v
|
||||
```
|
||||
|
||||
### Frontend E2E Tests
|
||||
```bash
|
||||
cd reports-app/frontend
|
||||
npm run test:e2e # Headless mode
|
||||
npm run test:e2e:headed # With browser UI
|
||||
npm run test:e2e:ui # Interactive mode
|
||||
```
|
||||
|
||||
### Telegram Bot Tests
|
||||
```bash
|
||||
cd reports-app/telegram-bot
|
||||
pytest tests/ -v
|
||||
pytest tests/ --cov=app --cov-report=html
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### Linux/Docker Deployment
|
||||
|
||||
```bash
|
||||
cd roa2web
|
||||
|
||||
# Setup production environment
|
||||
./setup_production.sh
|
||||
|
||||
# Deploy application
|
||||
./scripts/deploy.sh
|
||||
|
||||
# Health check
|
||||
./scripts/health-check.sh
|
||||
```
|
||||
|
||||
See `DEPLOYMENT_GUIDE.md` for complete deployment instructions.
|
||||
|
||||
### Windows Server Deployment
|
||||
|
||||
ROA2WEB supports deployment on Windows Server with IIS:
|
||||
|
||||
```powershell
|
||||
# On Windows Server (PowerShell as Administrator)
|
||||
cd C:\path\to\roa2web\deployment\windows\scripts
|
||||
|
||||
# Install
|
||||
.\Install-ROA2WEB.ps1
|
||||
|
||||
# Deploy
|
||||
.\Deploy-ROA2WEB.ps1 -SourcePath "C:\path\to\deploy-package"
|
||||
|
||||
# Manage services
|
||||
.\Start-ROA2WEB.ps1
|
||||
.\Stop-ROA2WEB.ps1
|
||||
.\Restart-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
See `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` for details.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
### General
|
||||
- `CLAUDE.md` - Development guide for Claude Code
|
||||
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan
|
||||
- `TEAM_IMPLEMENTATION_GUIDE.md` - Team implementation guide
|
||||
- `ARCHITECTURE_SCHEMA.md` - Architecture diagrams
|
||||
- `MICROSERVICES_GUIDE.md` - Microservices details
|
||||
|
||||
### 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
|
||||
|
||||
### 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
Block a user