docs: optimize and streamline documentation (59% reduction)
Major documentation refactoring to eliminate duplications and improve maintainability: CLAUDE.md (562→230 lines, 59% reduction): - Eliminated duplicate content with README.md - Added smart references to detailed documentation - Streamlined "Common Development Tasks" with golden rules - Created comprehensive "Documentation Index" as single source of truth - Focused on AI-friendly quick reference patterns README.md (402→251 lines, 37% reduction): - Simplified Quick Start to single command - Condensed Tech Stack to one-line summary with CLAUDE.md reference - Merged "Development Commands" + "Testing" into compact section - Updated Production Deployment with modern workflow (Publish-And-Deploy.ps1, ROA2WEB-Console.ps1) - Added Frontend Styling & CSS documentation references Key improvements: - Zero duplications across documentation files - Clear separation: README.md = quick start, CLAUDE.md = development guide - Smart cross-references between docs - Updated deployment section with current scripts - Maintained all essential information while reducing context by 446 lines 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
593
CLAUDE.md
593
CLAUDE.md
@@ -4,60 +4,55 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## 🚀 Project Overview
|
||||
|
||||
**ROA2WEB** - Modern ERP Reports Application with FastAPI backend and Vue.js frontend using microservices architecture.
|
||||
**ROA2WEB** - Modern ERP Reports Application with FastAPI backend, Vue.js frontend, and Telegram bot interface using microservices architecture.
|
||||
|
||||
**Active Branch**: `v2-roa2web-fastapi`
|
||||
**Main Branch**: `main` (use for PRs)
|
||||
**Working Directory**: Repository root - All development happens here
|
||||
**Working Directory**: Repository root
|
||||
|
||||
**Quick Reference**: See `README.md` for complete setup, commands, deployment, and testing instructions.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
### Microservices Structure
|
||||
```
|
||||
.
|
||||
├── shared/ # Shared components across microservices
|
||||
│ ├── database/ # Oracle connection pool (singleton pattern)
|
||||
│ ├── auth/ # JWT authentication & middleware
|
||||
│ └── utils/ # Common utilities
|
||||
├── reports-app/ # Main reports application
|
||||
├── shared/ # Shared components (DB pool, auth, utils)
|
||||
├── reports-app/
|
||||
│ ├── backend/ # FastAPI API (port 8001)
|
||||
│ ├── frontend/ # Vue.js 3 UI (Vite dev server, port 3000-3005)
|
||||
│ └── telegram-bot/ # Telegram bot frontend (port 8002 internal API)
|
||||
├── nginx/ # Reverse proxy & load balancer
|
||||
│ ├── frontend/ # Vue.js 3 UI (port 3000-3005)
|
||||
│ └── telegram-bot/ # Telegram bot (port 8002 internal)
|
||||
├── docs/ # Architecture & style guides
|
||||
├── deployment/ # Production deployment scripts
|
||||
└── ssh-tunnel/ # SSH tunnel for Oracle DB access
|
||||
```
|
||||
|
||||
### Key Architectural Decisions
|
||||
- **Shared Database Connection Pool**: Singleton `OraclePool` class in `shared/database/oracle_pool.py` is shared across all microservices. Uses `python-oracledb` with connection pooling.
|
||||
- **Centralized Authentication**: JWT-based auth in `shared/auth/` with middleware that auto-injects user data into `request.state`.
|
||||
- **SSH Tunnel Requirement**: All Oracle DB connections go through an SSH tunnel to the remote server (see Database Setup below).
|
||||
- **FastAPI Structure**: Routers in `backend/app/routers/`, schemas in `backend/app/schemas/`, no traditional models (Oracle stored procedures used instead).
|
||||
- **Telegram Bot Frontend**: Alternative command-based interface for Telegram. Uses standalone SQLite database for Telegram-specific data (auth codes, sessions) and communicates with backend via HTTP API.
|
||||
- **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`
|
||||
- **SSH Tunnel**: Required for Oracle DB connections (development/Linux) - see Database Setup
|
||||
- **FastAPI Structure**: Routers in `backend/app/routers/`, schemas in `backend/app/schemas/`, Oracle stored procedures (no ORM)
|
||||
- **Telegram Bot**: Standalone SQLite database for bot data, communicates with backend via HTTP API
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ Database Setup
|
||||
|
||||
**Schema**: `CONTAFIN_ORACLE` - Used for authentication and user management
|
||||
**Connection Method**: SSH tunnel required (Oracle DB is on remote network)
|
||||
**Schema**: `CONTAFIN_ORACLE` (authentication and user management)
|
||||
**Connection**: SSH tunnel required (Oracle on remote network)
|
||||
|
||||
### SSH Tunnel Management
|
||||
### SSH Tunnel (Development/Linux)
|
||||
```bash
|
||||
./ssh_tunnel.sh start # Start tunnel (localhost:1526 -> remote:1521)
|
||||
./ssh_tunnel.sh start # localhost:1526 → remote:1521
|
||||
./ssh_tunnel.sh status # Check tunnel
|
||||
./ssh_tunnel.sh stop # Stop tunnel
|
||||
./ssh_tunnel.sh status # Check tunnel status
|
||||
./ssh_tunnel.sh restart # Restart tunnel
|
||||
```
|
||||
|
||||
**SSH Configuration**:
|
||||
- Remote Server: `83.103.197.79:22122`
|
||||
- User: `roa2web`
|
||||
- SSH Key: `ssh-tunnel/secrets/roa_oracle_server`
|
||||
- Local Port: `1526`
|
||||
- Remote Oracle: `10.0.20.36:1521`
|
||||
|
||||
**IMPORTANT**: Always ensure SSH tunnel is running before starting backend services.
|
||||
|
||||
### Environment Variables
|
||||
Located in `reports-app/backend/.env`:
|
||||
### Environment Variables (`reports-app/backend/.env`)
|
||||
```bash
|
||||
# Oracle Database (through SSH tunnel)
|
||||
ORACLE_USER=CONTAFIN_ORACLE
|
||||
@@ -75,355 +70,23 @@ JWT_EXPIRE_MINUTES=30
|
||||
TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
|
||||
```
|
||||
|
||||
**IMPORTANT for Windows Deployment:** Ensure `TELEGRAM_BOT_INTERNAL_API` is set in backend `.env` file. This allows the backend to communicate with the Telegram bot's internal API for auth code management. See `deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md` for diagnostics.
|
||||
**Windows Production**: Direct Oracle connection, no SSH tunnel required. Ensure `TELEGRAM_BOT_INTERNAL_API` is set for auth code management.
|
||||
|
||||
## 🛠️ Development Commands
|
||||
|
||||
### Quick Start (All Services)
|
||||
```bash
|
||||
./start-dev.sh # Starts SSH tunnel, backend, and frontend
|
||||
./start-dev.sh stop # Stops all ROA2WEB services
|
||||
./start-dev.sh help # Show help
|
||||
```
|
||||
|
||||
This script manages:
|
||||
- SSH tunnel (Oracle DB connection)
|
||||
- Backend (FastAPI on port 8001)
|
||||
- Frontend (Vue.js/Vite on port 3000-3005)
|
||||
|
||||
### Backend (FastAPI)
|
||||
```bash
|
||||
cd reports-app/backend/
|
||||
|
||||
# Create virtual environment (first time only)
|
||||
python3 -m venv venv
|
||||
|
||||
# Activate virtual environment
|
||||
source venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Run development server
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
|
||||
|
||||
# API Documentation (when running)
|
||||
# http://localhost:8001/docs # Swagger UI
|
||||
# http://localhost:8001/redoc # ReDoc
|
||||
# http://localhost:8001/health # Health check endpoint
|
||||
```
|
||||
|
||||
### Frontend (Vue.js + Vite)
|
||||
```bash
|
||||
cd reports-app/frontend/
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Run development server (Vite will auto-assign port 3000-3005)
|
||||
npm run dev
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Preview production build
|
||||
npm run preview
|
||||
|
||||
# Lint and format
|
||||
npm run lint
|
||||
npm run format
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
#### Backend Tests (Shared Components)
|
||||
```bash
|
||||
cd shared/
|
||||
python -m pytest -v # All tests
|
||||
python -m pytest tests/test_auth.py -v # Specific test file
|
||||
```
|
||||
|
||||
#### Frontend E2E Tests (Playwright)
|
||||
```bash
|
||||
cd reports-app/frontend/
|
||||
|
||||
# Run all tests (headless)
|
||||
npm run test:e2e
|
||||
|
||||
# Run with browser UI visible
|
||||
npm run test:e2e:headed
|
||||
|
||||
# Debug mode with step-through
|
||||
npm run test:e2e:debug
|
||||
|
||||
# Interactive UI mode
|
||||
npm run test:e2e:ui
|
||||
|
||||
# View test report
|
||||
npm run test:e2e:report
|
||||
```
|
||||
|
||||
**Frontend Test Structure**:
|
||||
- Uses Page Object Model pattern
|
||||
- Tests in `tests/e2e/{auth,dashboard,invoices,payments,responsive}/`
|
||||
- Page objects in `tests/page-objects/`
|
||||
- Mocks all backend API calls for speed and reliability
|
||||
- See `reports-app/frontend/tests/README.md` for details
|
||||
|
||||
#### Telegram Bot Tests
|
||||
```bash
|
||||
cd reports-app/telegram-bot/
|
||||
|
||||
# Run all tests
|
||||
pytest tests/ -v
|
||||
|
||||
# Run specific test suites
|
||||
pytest tests/test_auth.py -v # Authentication flow tests
|
||||
pytest tests/test_session_company.py -v # Session management tests
|
||||
|
||||
# Run with coverage
|
||||
pytest tests/ --cov=app --cov-report=html
|
||||
```
|
||||
|
||||
**Telegram Bot Test Coverage:**
|
||||
- Authentication flow tests (link/unlink, JWT management)
|
||||
- Session management tests (active company persistence)
|
||||
- Manual testing checklist: `tests/MANUAL_TESTING_CHECKLIST.md`
|
||||
---
|
||||
|
||||
## 🔑 Authentication Flow
|
||||
|
||||
1. **Login**: `POST /api/auth/login` calls Oracle stored procedure `pack_drepturi.verificautilizator(username, password)`
|
||||
2. **Token Generation**: JWT token includes `username`, `user_id`, `companies[]`, `permissions[]`, `exp`, `iat`, `type`
|
||||
3. **Middleware**: `AuthenticationMiddleware` in `shared/auth/middleware.py` auto-validates tokens and injects user into `request.state.user`
|
||||
4. **Protected Routes**: All routes except `excluded_paths` require valid JWT token
|
||||
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
|
||||
- `shared/auth/middleware.py` - FastAPI middleware with rate limiting (5 req/5 min)
|
||||
- `shared/auth/jwt_handler.py` - Token creation/validation
|
||||
- `reports-app/backend/app/main.py` - Auth router inline definition
|
||||
|
||||
## 🔌 API Endpoints
|
||||
|
||||
All endpoints prefixed with `/api`:
|
||||
|
||||
### Authentication
|
||||
- `POST /api/auth/login` - Login with username/password
|
||||
|
||||
### 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 stats
|
||||
|
||||
### Treasury
|
||||
- `GET /api/treasury/{company_id}` - Treasury/payment data
|
||||
|
||||
### Telegram Bot
|
||||
- `POST /api/telegram/auth/generate-code` - Generate 8-char linking code (requires JWT)
|
||||
- `POST /api/telegram/auth/verify-user` - Verify Oracle user_id (public)
|
||||
- `POST /api/telegram/auth/refresh-token` - Refresh JWT token (public)
|
||||
- `POST /api/telegram/export` - Export reports for Telegram (requires JWT)
|
||||
- `GET /api/telegram/health` - Health check (public)
|
||||
|
||||
**Backend Routers**: `reports-app/backend/app/routers/{companies,dashboard,invoices,treasury,telegram}.py`
|
||||
|
||||
## 🎨 Frontend Stack
|
||||
|
||||
- **Framework**: Vue.js 3 (Composition API)
|
||||
- **UI Library**: PrimeVue (rich component library)
|
||||
- **State Management**: Pinia stores in `src/stores/`
|
||||
- **Routing**: Vue Router in `src/router/`
|
||||
- **Build Tool**: Vite
|
||||
- **Charts**: Chart.js via vue-chartjs
|
||||
- **HTTP**: Axios
|
||||
- **Testing**: Playwright (E2E)
|
||||
|
||||
**Key Frontend Components**:
|
||||
- `src/views/LoginView.vue` - Login page
|
||||
- `src/views/DashboardView.vue` - Main dashboard
|
||||
- `src/views/InvoicesView.vue` - Invoice management
|
||||
- `src/components/dashboard/cards/` - Dashboard metric cards
|
||||
- `src/components/layout/` - Layout components
|
||||
|
||||
## 🤖 Telegram Bot Frontend
|
||||
|
||||
The Telegram Bot provides an alternative command-based interface to ROA2WEB for Telegram users.
|
||||
|
||||
### Architecture
|
||||
|
||||
- **Bot Framework**: python-telegram-bot (v20.7+)
|
||||
- **Database**: Standalone SQLite (auth codes, sessions, active company)
|
||||
- **Backend Communication**: HTTP API client (httpx)
|
||||
- **Internal API**: FastAPI (port 8002) for backend callbacks
|
||||
|
||||
### Development Commands
|
||||
|
||||
```bash
|
||||
cd reports-app/telegram-bot/
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Configure environment
|
||||
cp .env.example .env
|
||||
# Edit .env with TELEGRAM_BOT_TOKEN
|
||||
|
||||
# Run bot
|
||||
python -m app.main
|
||||
|
||||
# Health check
|
||||
curl http://localhost:8002/internal/health
|
||||
```
|
||||
|
||||
### Authentication Flow (Telegram)
|
||||
|
||||
1. User logs into ROA2WEB web app
|
||||
2. User requests Telegram linking → Backend generates 8-char code
|
||||
3. Backend saves code to telegram-bot via `POST /internal/save-code` (port 8002)
|
||||
4. User sends code to Telegram bot: `/start ABC123XY`
|
||||
5. Bot verifies code, creates user in SQLite, receives JWT token
|
||||
6. User can now use commands to query data
|
||||
|
||||
### Bot Commands
|
||||
|
||||
- `/start [code]` - Welcome message or link account with code
|
||||
- `/help` - Usage guide and available commands
|
||||
- `/companies` - View accessible companies
|
||||
- `/selectcompany [name]` - Select or search for active company
|
||||
- `/dashboard` - View financial dashboard for active company
|
||||
- `/sold` - View balance (alias for `/dashboard`)
|
||||
- `/facturi [filter]` - View invoices (optional filters: neplatite, platite)
|
||||
- `/trezorerie` - View treasury/payment data
|
||||
- `/clear` - Clear active company selection
|
||||
- `/unlink` - Unlink Telegram from Oracle account
|
||||
|
||||
### Database (SQLite)
|
||||
|
||||
Standalone database in `data/telegram_bot.db`:
|
||||
- **telegram_users**: Telegram-Oracle account linking
|
||||
- **telegram_auth_codes**: 8-char codes (15 min expiry)
|
||||
- **telegram_sessions**: Active company selection
|
||||
|
||||
Automatic cleanup runs hourly to remove expired data.
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Unit and integration tests
|
||||
pytest tests/ -v
|
||||
|
||||
# Coverage report
|
||||
pytest tests/ --cov=app --cov-report=html
|
||||
```
|
||||
|
||||
### Key Files
|
||||
|
||||
- `app/main.py` - Bot entry point and Telegram application setup
|
||||
- `app/bot/handlers.py` - Telegram command handlers
|
||||
- `app/bot/helpers.py` - Helper functions for commands
|
||||
- `app/bot/formatters.py` - Response formatting utilities
|
||||
- `app/agent/session.py` - Session management (active company)
|
||||
- `app/auth/linking.py` - Account linking logic
|
||||
- `app/db/operations.py` - SQLite CRUD operations
|
||||
- `app/api/client.py` - Backend API client
|
||||
- `app/internal_api.py` - Internal FastAPI for backend callbacks
|
||||
|
||||
See `reports-app/telegram-bot/README.md` for complete documentation.
|
||||
|
||||
## 🐳 Docker & Production
|
||||
|
||||
### Docker Compose (Legacy Flask App)
|
||||
The root `docker-compose.yaml` is for the old Flask application - NOT for the current FastAPI/Vue.js app.
|
||||
|
||||
### Production Deployment Options
|
||||
|
||||
ROA2WEB supports two production deployment architectures:
|
||||
|
||||
#### 🐧 Linux Production (Docker)
|
||||
|
||||
```bash
|
||||
# Setup production environment
|
||||
./setup_production.sh
|
||||
|
||||
# Deployment scripts
|
||||
./scripts/deploy.sh # Deploy application
|
||||
./scripts/backup.sh # Backup data
|
||||
./scripts/rollback.sh # Rollback deployment
|
||||
./scripts/health-check.sh # Health monitoring
|
||||
```
|
||||
|
||||
See `DEPLOYMENT_GUIDE.md` for full Linux/Docker deployment instructions.
|
||||
|
||||
#### 🪟 Windows Server Production (IIS)
|
||||
|
||||
Windows Server deployment uses IIS and Windows Services without Docker:
|
||||
|
||||
**Build deployment package (on WSL/Linux development machine):**
|
||||
```powershell
|
||||
cd deployment/windows/scripts
|
||||
|
||||
# Build complete package (Frontend + Backend + Telegram Bot)
|
||||
.\Build-ROA2WEB.ps1
|
||||
|
||||
# Or build specific components
|
||||
.\Build-ROA2WEB.ps1 -Component Frontend # Frontend + Backend only
|
||||
.\Build-ROA2WEB.ps1 -Component TelegramBot # Telegram Bot only
|
||||
|
||||
# Output: ./deploy-package/
|
||||
# Transfer this to Windows Server
|
||||
```
|
||||
|
||||
**Deploy on Windows Server (PowerShell as Administrator):**
|
||||
```powershell
|
||||
# Initial installation
|
||||
cd C:\path\to\deploy-package\scripts
|
||||
|
||||
# Install main application
|
||||
.\Install-ROA2WEB.ps1
|
||||
|
||||
# Install Telegram Bot
|
||||
.\Install-TelegramBot.ps1
|
||||
|
||||
# Configure applications
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Deploy/update application files
|
||||
.\Deploy-ROA2WEB.ps1
|
||||
.\Deploy-TelegramBot.ps1
|
||||
|
||||
# Service Management (Unified)
|
||||
.\Manage-ROA2WEB.ps1 -Action Start # Start all services
|
||||
.\Manage-ROA2WEB.ps1 -Action Stop # Stop all services
|
||||
.\Manage-ROA2WEB.ps1 -Action Restart # Restart all services
|
||||
.\Manage-ROA2WEB.ps1 -Action Status # Check status
|
||||
|
||||
# Manage specific components
|
||||
.\Manage-ROA2WEB.ps1 -Action Start -Component Backend
|
||||
.\Manage-ROA2WEB.ps1 -Action Restart -Component TelegramBot
|
||||
```
|
||||
|
||||
**Windows Deployment Architecture:**
|
||||
- **IIS Web Server**: Serves frontend static files (port 80/443)
|
||||
- **Windows Service**: FastAPI backend via NSSM (port 8000)
|
||||
- **Windows Service**: Telegram Bot via NSSM (internal API port 8002)
|
||||
- **Direct Oracle Connection**: No SSH tunnel required
|
||||
- **URL Rewrite Module**: Reverse proxy for `/api/*` routes
|
||||
|
||||
**Telegram Bot Integration:**
|
||||
- Backend must have `TELEGRAM_BOT_INTERNAL_API=http://localhost:8002` in `.env`
|
||||
- Telegram Bot service must be running before generating linking codes
|
||||
- Troubleshooting: See `deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md`
|
||||
|
||||
See `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` for complete Windows deployment guide.
|
||||
---
|
||||
|
||||
## 📝 Common Development Tasks
|
||||
|
||||
@@ -431,131 +94,137 @@ See `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` for complete Windows deploym
|
||||
1. Create router in `reports-app/backend/app/routers/your_router.py`
|
||||
2. Define Pydantic schemas in `app/schemas/`
|
||||
3. Use `oracle_pool.get_connection()` context manager for DB queries
|
||||
4. Register router in `app/main.py` with `app.include_router(your_router, prefix="/api/your_prefix")`
|
||||
4. Register router in `app/main.py`: `app.include_router(your_router, prefix="/api/your_prefix")`
|
||||
|
||||
### Adding Shared Functionality
|
||||
1. Place in `shared/{database|auth|utils}/`
|
||||
2. Import using `sys.path.append()` pattern (see `backend/app/main.py:21`)
|
||||
3. Test in `shared/tests/`
|
||||
|
||||
### Working with Oracle Stored Procedures
|
||||
**Example**:
|
||||
```python
|
||||
async with oracle_pool.get_connection() as connection:
|
||||
with connection.cursor() as cursor:
|
||||
cursor.execute("""
|
||||
SELECT pack_name.procedure_name(:param1, :param2)
|
||||
FROM DUAL
|
||||
""", {
|
||||
'param1': value1,
|
||||
'param2': value2
|
||||
})
|
||||
""", {'param1': value1, 'param2': value2})
|
||||
result = cursor.fetchone()
|
||||
```
|
||||
|
||||
### 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`)
|
||||
- ❌ Never use `:deep()` in components (use `src/assets/css/vendor/` for PrimeVue overrides)
|
||||
- ❌ Never duplicate CSS (write once, use everywhere)
|
||||
|
||||
### Adding a New Telegram Bot Command
|
||||
**IMPORTANT**: Follow established command patterns and formatting.
|
||||
|
||||
**Before coding**: Read **`reports-app/telegram-bot/TELEGRAM_COMMANDS.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/authStore.js)
|
||||
// Store pattern (src/stores/yourStore.js)
|
||||
import axios from 'axios';
|
||||
|
||||
const api = axios.create({
|
||||
baseURL: 'http://localhost:8001/api',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`
|
||||
}
|
||||
headers: { 'Authorization': `Bearer ${token}` }
|
||||
});
|
||||
|
||||
const response = await api.get('/companies');
|
||||
const response = await api.get('/endpoint');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security
|
||||
|
||||
- **Git Hooks**: Security scanning hooks in `security/install_hooks.sh`
|
||||
- **Environment Files**: Never commit `.env` files (use `.env.example` as template)
|
||||
- **SSH Keys**: Stored in `ssh-tunnel/secrets/` (gitignored)
|
||||
- **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 authentication middleware (5 requests per 5 minutes)
|
||||
- **Rate Limiting**: Built into auth middleware (5 requests per 5 minutes)
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
---
|
||||
|
||||
### SSH Tunnel Issues
|
||||
```bash
|
||||
# Check tunnel status
|
||||
./ssh_tunnel.sh status
|
||||
## 📚 Documentation Index
|
||||
|
||||
# View tunnel logs
|
||||
ps aux | grep ssh | grep 1526
|
||||
### Quick Start & Commands
|
||||
→ **`README.md`** - Project overview, setup, development commands, testing, deployment
|
||||
|
||||
# Test Oracle connectivity through tunnel
|
||||
timeout 5 bash -c "cat < /dev/null > /dev/tcp/127.0.0.1/1526"
|
||||
```
|
||||
|
||||
### Backend Not Starting
|
||||
- Ensure SSH tunnel is running
|
||||
- Check `.env` file exists with correct credentials
|
||||
- Verify virtual environment is activated
|
||||
- Check port 8001 is not already in use: `lsof -ti:8001`
|
||||
|
||||
### Frontend Build Issues
|
||||
- Clear node_modules: `rm -rf node_modules && npm install`
|
||||
- Check Node.js version: `node -v` (requires 16+)
|
||||
- Vite may auto-assign ports 3000-3005 if 3000 is busy
|
||||
|
||||
### Database Connection Errors
|
||||
- Verify SSH tunnel: `./ssh_tunnel.sh status`
|
||||
- Check Oracle listener is running on remote server
|
||||
- Verify credentials in `.env` file
|
||||
- Test connection: `http://localhost:8001/health`
|
||||
|
||||
## 📚 Additional Documentation
|
||||
|
||||
### General Documentation
|
||||
- `README.md` - Project overview
|
||||
### Architecture & Planning
|
||||
- `docs/ARCHITECTURE_SCHEMA.md` - Architecture diagrams and schemas
|
||||
- `docs/MICROSERVICES_GUIDE.md` - Microservices architecture details
|
||||
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan
|
||||
- `ARCHITECTURE_SCHEMA.md` - Architecture diagrams and schemas
|
||||
- `MICROSERVICES_GUIDE.md` - Microservices architecture details
|
||||
|
||||
### Deployment Documentation
|
||||
- `DEPLOYMENT_GUIDE.md` - Production deployment (Linux/Docker & Windows/IIS)
|
||||
### 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
|
||||
- `reports-app/frontend/README.md` - Frontend architecture and setup
|
||||
- `reports-app/frontend/tests/README.md` - Playwright E2E testing guide
|
||||
|
||||
### Backend Development
|
||||
- `reports-app/backend/README.md` - Backend architecture and API details
|
||||
- API endpoints documented in `README.md` (Authentication, Companies, Dashboard, Invoices, Treasury, Telegram)
|
||||
|
||||
### Telegram Bot Development
|
||||
- **`reports-app/telegram-bot/README.md`** - Complete bot architecture and development guide (START HERE)
|
||||
- **`reports-app/telegram-bot/TELEGRAM_COMMANDS.md`** - Command reference and patterns
|
||||
- `tests/MANUAL_TESTING_CHECKLIST.md` - Manual testing procedures
|
||||
|
||||
### Deployment
|
||||
- **`DEPLOYMENT_GUIDE.md`** - Production deployment (Linux/Docker & Windows/IIS)
|
||||
- `deployment/windows/README.md` - Windows deployment quick start
|
||||
- `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` - Complete Windows deployment guide
|
||||
- `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` - Complete Windows guide
|
||||
- `deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md` - Bot troubleshooting
|
||||
|
||||
### Component Documentation
|
||||
- `reports-app/backend/README.md` - Backend specifics
|
||||
- `reports-app/frontend/README.md` - Frontend guide
|
||||
- `reports-app/frontend/tests/README.md` - Testing guide
|
||||
- `reports-app/telegram-bot/README.md` - Telegram bot complete guide
|
||||
- `reports-app/telegram-bot/TELEGRAM_COMMANDS.md` - Command reference
|
||||
### 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`
|
||||
|
||||
## 🔧 Tech Stack Summary
|
||||
---
|
||||
|
||||
**Backend**:
|
||||
- FastAPI (async Python web framework)
|
||||
- python-oracledb (Oracle database driver)
|
||||
- JWT (PyJWT for authentication)
|
||||
- Pydantic (data validation)
|
||||
- pytest (testing)
|
||||
## 🔧 Tech Stack
|
||||
|
||||
**Frontend**:
|
||||
- Vue.js 3 (Composition API)
|
||||
- PrimeVue (UI components)
|
||||
- Pinia (state management)
|
||||
- Vite (build tool)
|
||||
- Playwright (E2E testing)
|
||||
- Axios (HTTP client)
|
||||
- Chart.js (data visualization)
|
||||
**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)
|
||||
|
||||
**Telegram Bot Frontend**:
|
||||
- python-telegram-bot (Telegram API wrapper)
|
||||
- SQLite + aiosqlite (standalone database)
|
||||
- httpx (async HTTP client for backend)
|
||||
- FastAPI + uvicorn (internal API)
|
||||
- pytest + pytest-asyncio (testing)
|
||||
---
|
||||
|
||||
**Infrastructure**:
|
||||
- Oracle Database (enterprise data)
|
||||
- SQLite (Telegram bot standalone data)
|
||||
- SSH Tunnel (secure database access - Linux/development)
|
||||
- Nginx (reverse proxy - Linux production)
|
||||
- Docker Compose (orchestration - Linux production)
|
||||
- Windows Server + IIS (Windows production deployment)
|
||||
- NSSM (Windows service manager for backend)
|
||||
**For detailed information on any topic, always check the Documentation Index above first.**
|
||||
|
||||
247
README.md
247
README.md
@@ -34,35 +34,14 @@ ROA2WEB is a comprehensive financial reporting platform built with modern techno
|
||||
git clone <repository-url>
|
||||
cd roa2web
|
||||
|
||||
# Start all services (SSH tunnel + Backend + Frontend)
|
||||
cd roa2web
|
||||
# Start all services with one command
|
||||
./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
|
||||
```
|
||||
|
||||
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)
|
||||
@@ -105,180 +84,79 @@ python -m app.main
|
||||
|
||||
---
|
||||
|
||||
## Core Technologies
|
||||
## Tech Stack
|
||||
|
||||
### 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
|
||||
**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)
|
||||
**Infrastructure**: Oracle Database, SSH Tunnel, Nginx, Docker (Linux), IIS + NSSM (Windows)
|
||||
|
||||
### 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)
|
||||
*See `CLAUDE.md` for detailed tech stack information and architecture decisions.*
|
||||
|
||||
---
|
||||
|
||||
## Development Commands
|
||||
## Development & Testing
|
||||
|
||||
### Backend (FastAPI)
|
||||
**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
|
||||
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
|
||||
./ssh_tunnel.sh start # Start Oracle DB tunnel
|
||||
cd reports-app/backend && uvicorn app.main:app --reload # Backend (port 8001)
|
||||
cd reports-app/frontend && npm run dev # Frontend (port 3000-3005)
|
||||
cd reports-app/telegram-bot && python -m app.main # Telegram Bot (port 8002)
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
**API Documentation** (when backend running):
|
||||
- Swagger UI: http://localhost:8001/docs
|
||||
- ReDoc: http://localhost:8001/redoc
|
||||
- Health Check: http://localhost:8001/health
|
||||
|
||||
---
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### Linux/Docker Deployment
|
||||
ROA2WEB supports two deployment architectures:
|
||||
|
||||
### 🐧 Linux/Docker Deployment
|
||||
```bash
|
||||
cd roa2web
|
||||
|
||||
# Setup production environment
|
||||
./setup_production.sh
|
||||
|
||||
# Deploy application
|
||||
./scripts/deploy.sh
|
||||
|
||||
# Health check
|
||||
./scripts/health-check.sh
|
||||
./setup_production.sh # Initial setup
|
||||
./scripts/deploy.sh # Deploy application
|
||||
./scripts/health-check.sh # Health monitoring
|
||||
```
|
||||
|
||||
See `DEPLOYMENT_GUIDE.md` for complete deployment instructions.
|
||||
|
||||
### Windows Server Deployment
|
||||
|
||||
ROA2WEB supports deployment on Windows Server with IIS:
|
||||
### 🪟 Windows/IIS Deployment
|
||||
|
||||
**Modern Unified Workflow** (recommended):
|
||||
```powershell
|
||||
# On Windows Server (PowerShell as Administrator)
|
||||
cd C:\path\to\roa2web\deployment\windows\scripts
|
||||
# On Development Machine (WSL/Linux)
|
||||
cd deployment/windows/scripts
|
||||
.\Publish-And-Deploy.ps1 # Build + Transfer to server (interactive menu)
|
||||
|
||||
# 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
|
||||
# On Windows Server (PowerShell as Admin)
|
||||
cd deployment/windows/scripts
|
||||
.\ROA2WEB-Console.ps1 # Deploy + Manage services (interactive console)
|
||||
```
|
||||
|
||||
See `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` for details.
|
||||
**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
|
||||
|
||||
---
|
||||
|
||||
@@ -342,12 +220,11 @@ BACKEND_API_URL=http://localhost:8001
|
||||
|
||||
## Documentation
|
||||
|
||||
### General
|
||||
- `CLAUDE.md` - Development guide for Claude Code
|
||||
### Quick Reference
|
||||
- **`CLAUDE.md`** - Development guide for AI/Claude Code (architecture, common tasks, troubleshooting)
|
||||
- `docs/ARCHITECTURE_SCHEMA.md` - Architecture diagrams and schemas
|
||||
- `docs/MICROSERVICES_GUIDE.md` - Microservices architecture details
|
||||
- `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
|
||||
@@ -357,6 +234,14 @@ BACKEND_API_URL=http://localhost:8001
|
||||
- `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
|
||||
|
||||
Reference in New Issue
Block a user