roa2web-service-auto/features/TRIAL_BALANCE_FEATURE.md

# Feature: Balanță de Verificare Sintetică (Trial Balance)

**Branch**: `feature/trial-balance`
**Status**: 📋 Planning
**Created**: 2025-11-20
**Assigned to**: Claude Code

---

## 📋 Overview

Implementare pagină nouă în frontend pentru afișarea balanței de verificare sintetice simplificate din tabelul Oracle `VBAL`, cu filtrare dinamică și integrare completă în aplicație.

---

## 🎯 Business Requirements

### Functional Requirements
1. **Afișare Date Balanță de Verificare**:
   - Solduri precedente (debit/credit)
   - Rulaje lunare (debit/credit)
   - Solduri finale (debit/credit)
   - Cont contabil (cod)
   - Denumire cont

2. **Filtrare și Căutare**:
   - Filtrare după **număr cont** (ex: "512", "4111")
   - Filtrare după **denumire cont** (căutare parțială, case-insensitive)
   - Filtrare combinată (și după cont și după denumire)
   - Clear filters option

3. **Navigare și UX**:
   - Adăugare în meniul hamburger (secțiune Rapoarte / Reports)
   - Ordonare pe coloane (ascendent/descendent)
   - Paginare pentru volume mari de date
   - Loading states și error handling
   - Responsive design (mobile-friendly)

4. **Date Contextualizate**:
   - Afișare pentru compania activă curentă
   - Afișare pentru luna/anul curent (sau filtru de perioadă - opțional faza 2)

### Non-Functional Requirements
- **Performance**: Răspuns API < 2s pentru 10,000 înregistrări
- **Security**: Autentificare JWT obligatorie
- **Accessibility**: Conform design system existent
- **CSS**: Respectare strictă a arhitecturii CSS (ONBOARDING_CSS.md, CSS_PATTERNS.md)

---

## 🏗️ Technical Architecture

### Database Schema (Oracle `VBAL` table)
```sql
-- Structura tabelului VBAL (să fie verificată în Oracle)
SELECT
    CONT,              -- Număr cont contabil
    DCONT,             -- Denumire cont
    SD_PREC,           -- Sold precedent debit
    SC_PREC,           -- Sold precedent credit
    RD_LUNA,           -- Rulaj lunar debit
    RC_LUNA,           -- Rulaj lunar credit
    SD_FINAL,          -- Sold final debit
    SC_FINAL,          -- Sold final credit
    COD_FIRMA,         -- Cod firmă (pentru filtering)
    LUNA,              -- Luna (1-12)
    AN                 -- An
FROM VBAL
WHERE COD_FIRMA = :cod_firma
  AND AN = :an
  AND LUNA = :luna
  AND (CONT LIKE :cont_filter OR DCONT LIKE :denumire_filter)
ORDER BY CONT
```

### Backend API Endpoint

**Endpoint**: `GET /api/trial-balance`

**Request Parameters**:
```json
{
  "cod_firma": "string (required, from JWT)",
  "luna": "integer (1-12, optional, default: current month)",
  "an": "integer (optional, default: current year)",
  "cont_filter": "string (optional, partial match)",
  "denumire_filter": "string (optional, partial match, case-insensitive)",
  "sort_by": "string (optional, default: 'CONT')",
  "sort_order": "string (optional, 'asc' | 'desc', default: 'asc')",
  "page": "integer (optional, default: 1)",
  "page_size": "integer (optional, default: 50)"
}
```

**Response**:
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "cont": "4111",
        "dcont": "Furnizori interni",
        "sold_precedent_debit": 0.00,
        "sold_precedent_credit": 15000.00,
        "rulaj_lunar_debit": 5000.00,
        "rulaj_lunar_credit": 8000.00,
        "sold_final_debit": 0.00,
        "sold_final_credit": 18000.00
      }
    ],
    "pagination": {
      "total_items": 150,
      "total_pages": 3,
      "current_page": 1,
      "page_size": 50
    },
    "filters_applied": {
      "luna": 11,
      "an": 2025,
      "cont_filter": null,
      "denumire_filter": "furnizori"
    }
  }
}
```

**Error Responses**:
- `401 Unauthorized`: Missing/invalid JWT token
- `403 Forbidden`: User doesn't have access to company
- `500 Internal Server Error`: Database connection/query error

---

### Frontend Architecture

**Location**: `reports-app/frontend/src/views/TrialBalanceView.vue`

**Store**: `reports-app/frontend/src/stores/trialBalanceStore.js`

**Route**: `/trial-balance` (added to `router/index.js`)

**Menu Integration**:
- Add to hamburger menu in `src/components/layout/HamburgerMenu.vue`
- Section: "Rapoarte" / "Reports"
- Icon: Calculator/Table icon (PrimeVue icon)
- Label: "Balanță de Verificare"

**Component Structure**:
```vue
<template>
  <div class="trial-balance-view">
    <!-- Page Header -->
    <div class="roa-page-header">
      <h1>Balanță de Verificare</h1>
      <p class="roa-subtitle">Luna: {{ currentMonth }}/{{ currentYear }}</p>
    </div>

    <!-- Filters Section -->
    <div class="roa-card roa-filters-card">
      <!-- Cont filter -->
      <!-- Denumire filter -->
      <!-- Clear filters button -->
    </div>

    <!-- Data Table -->
    <div class="roa-card">
      <DataTable
        :value="trialBalanceData"
        :loading="loading"
        paginator
        :rows="50"
        sortField="cont"
        :sortOrder="1"
      >
        <!-- Columns definition -->
      </DataTable>
    </div>

    <!-- Empty State / Error State -->
  </div>
</template>
```

**CSS Patterns to Use**:
- `.roa-page-header` - Page header (CSS_PATTERNS.md)
- `.roa-card` - Card container (CSS_PATTERNS.md)
- `.roa-filters-card` - Filters section (CSS_PATTERNS.md)
- Design tokens from DESIGN_TOKENS.md (colors, spacing)
- **NO `:deep()`** - Use `src/assets/css/vendor/primevue/datatable.css` for PrimeVue overrides

**State Management** (Pinia store):
```javascript
// src/stores/trialBalanceStore.js
export const useTrialBalanceStore = defineStore('trialBalance', {
  state: () => ({
    trialBalanceData: [],
    loading: false,
    error: null,
    filters: {
      cont: '',
      denumire: '',
      luna: new Date().getMonth() + 1,
      an: new Date().getFullYear()
    },
    pagination: {
      totalItems: 0,
      currentPage: 1,
      pageSize: 50
    }
  }),

  actions: {
    async fetchTrialBalance() { /* ... */ },
    async applyFilters(filters) { /* ... */ },
    clearFilters() { /* ... */ }
  }
})
```

---

## 📝 Implementation Plan (Phases)

### ✅ Phase 0: Preparation & Branch Setup
**Status**: 🔲 Not Started

**Tasks**:
- [ ] Create feature branch `feature/trial-balance` from `main`
- [ ] Verify Oracle `VBAL` table structure and test queries
- [ ] Review existing code patterns (InvoicesView, DashboardView)
- [ ] Read CSS documentation (ONBOARDING_CSS.md, CSS_PATTERNS.md)

**Estimated Time**: 30 minutes

---

### ✅ Phase 1: Backend API Implementation
**Status**: 🔲 Not Started

**Tasks**:
- [ ] Create Pydantic schema: `backend/app/schemas/trial_balance.py`
  - `TrialBalanceItem` model
  - `TrialBalanceRequest` model
  - `TrialBalanceResponse` model
- [ ] Create router: `backend/app/routers/trial_balance.py`
  - `GET /api/trial-balance` endpoint
  - Query parameters validation
  - Oracle stored procedure/query execution
  - Pagination logic
  - Filtering logic (cont, denumire)
  - Sorting logic
- [ ] Register router in `backend/app/main.py`
- [ ] Test endpoint manually with Postman/curl
  - Test with valid JWT token
  - Test filtering by cont
  - Test filtering by denumire
  - Test pagination
  - Test sorting
  - Test error cases (invalid token, DB errors)

**Files to Create/Modify**:
- `reports-app/backend/app/schemas/trial_balance.py` (NEW)
- `reports-app/backend/app/routers/trial_balance.py` (NEW)
- `reports-app/backend/app/main.py` (MODIFY)

**Acceptance Criteria**:
- ✅ API returns correct data from `VBAL` table
- ✅ Filtering works for cont and denumire
- ✅ Pagination returns correct page counts
- ✅ Sorting works for all columns
- ✅ Proper error handling and status codes

**Estimated Time**: 2-3 hours

---

### ✅ Phase 2: Frontend Store Implementation
**Status**: 🔲 Not Started

**Tasks**:
- [ ] Create Pinia store: `frontend/src/stores/trialBalanceStore.js`
  - State definition (data, loading, error, filters, pagination)
  - `fetchTrialBalance()` action with Axios
  - `applyFilters()` action
  - `clearFilters()` action
  - Getters for computed values
- [ ] Add API service: `frontend/src/services/trialBalanceService.js` (optional)
- [ ] Test store in browser DevTools

**Files to Create**:
- `reports-app/frontend/src/stores/trialBalanceStore.js` (NEW)
- `reports-app/frontend/src/services/trialBalanceService.js` (NEW, optional)

**Acceptance Criteria**:
- ✅ Store successfully fetches data from API
- ✅ Filters update correctly
- ✅ Loading states work properly
- ✅ Error handling displays user-friendly messages

**Estimated Time**: 1-2 hours

---

### ✅ Phase 3: Frontend View Component
**Status**: 🔲 Not Started

**Tasks**:
- [ ] Create Vue component: `frontend/src/views/TrialBalanceView.vue`
  - Page header with title and period info
  - Filters card (cont input, denumire input, clear button)
  - PrimeVue DataTable with columns:
    - Cont
    - Denumire Cont
    - Sold Precedent (Debit/Credit)
    - Rulaj Lunar (Debit/Credit)
    - Sold Final (Debit/Credit)
  - Loading spinner
  - Empty state (no data)
  - Error state
- [ ] Use **existing CSS patterns** (NO new custom CSS unless necessary)
  - `.roa-page-header`
  - `.roa-card`
  - `.roa-filters-card`
  - Design tokens (spacing, colors)
- [ ] Implement responsive design (mobile breakpoints)
- [ ] Add number formatting (Romanian locale, 2 decimals)

**Files to Create**:
- `reports-app/frontend/src/views/TrialBalanceView.vue` (NEW)

**Acceptance Criteria**:
- ✅ Page displays correctly with data
- ✅ Filters work and update table
- ✅ Sorting on columns works
- ✅ Pagination works
- ✅ Loading/error states display correctly
- ✅ CSS follows design system (NO `:deep()`, NO custom colors)
- ✅ Responsive on mobile devices

**Estimated Time**: 3-4 hours

---

### ✅ Phase 4: Routing & Navigation
**Status**: 🔲 Not Started

**Tasks**:
- [ ] Add route in `frontend/src/router/index.js`:
  ```javascript
  {
    path: '/trial-balance',
    name: 'TrialBalance',
    component: () => import('@/views/TrialBalanceView.vue'),
    meta: { requiresAuth: true }
  }
  ```
- [ ] Add menu item in `frontend/src/components/layout/HamburgerMenu.vue`:
  - Section: "Rapoarte"
  - Icon: `pi-calculator` or `pi-table`
  - Label: "Balanță de Verificare"
  - Route: `/trial-balance`
- [ ] Test navigation from menu

**Files to Modify**:
- `reports-app/frontend/src/router/index.js` (MODIFY)
- `reports-app/frontend/src/components/layout/HamburgerMenu.vue` (MODIFY)

**Acceptance Criteria**:
- ✅ Route is accessible at `/trial-balance`
- ✅ Menu item appears in hamburger menu
- ✅ Clicking menu item navigates to page
- ✅ Auth guard prevents unauthorized access

**Estimated Time**: 30 minutes

---

### ✅ Phase 5: Testing & Refinement
**Status**: 🔲 Not Started

**Tasks**:
- [ ] Manual testing:
  - Test with different companies
  - Test with different date ranges
  - Test filtering edge cases (empty results, special characters)
  - Test sorting on all columns
  - Test pagination with large datasets
  - Test on mobile devices (responsive)
  - Test error scenarios (API down, invalid token)
- [ ] Add Playwright E2E tests (optional, recommended):
  - `frontend/tests/e2e/trial-balance/trial-balance.spec.js`
  - Test navigation
  - Test filtering
  - Test data display
- [ ] Code review & refinement:
  - Check CSS adherence (no `:deep()`, use patterns)
  - Check error handling
  - Check loading states
  - Check accessibility (keyboard navigation, screen readers)
- [ ] Performance testing:
  - Test with 10,000+ rows
  - Check API response time
  - Check frontend rendering performance

**Files to Create** (optional):
- `reports-app/frontend/tests/e2e/trial-balance/trial-balance.spec.js` (NEW)

**Acceptance Criteria**:
- ✅ All manual tests pass
- ✅ E2E tests pass (if implemented)
- ✅ Performance benchmarks met (API < 2s)
- ✅ Code follows project conventions
- ✅ CSS follows design system strictly

**Estimated Time**: 2-3 hours

---

### ✅ Phase 6: Documentation & PR
**Status**: 🔲 Not Started

**Tasks**:
- [ ] Update `README.md` - add Trial Balance to features list
- [ ] Update `CLAUDE.md` - add Trial Balance to documentation index (if needed)
- [ ] Add API documentation in backend README
- [ ] Create PR from `feature/trial-balance` to `main`:
  - Title: "feat: Add Trial Balance (Balanță de Verificare) page"
  - Description: Link to this feature file, list phases completed
  - Screenshots of UI
  - API endpoint documentation
- [ ] Request code review
- [ ] Address review comments
- [ ] Merge to `main`

**Acceptance Criteria**:
- ✅ All documentation updated
- ✅ PR created with complete description
- ✅ Code review approved
- ✅ Branch merged successfully

**Estimated Time**: 1 hour

---

## 📊 Progress Tracking

### Overall Progress
- **Phase 0**: 🔲 Not Started (0%)
- **Phase 1**: 🔲 Not Started (0%)
- **Phase 2**: 🔲 Not Started (0%)
- **Phase 3**: 🔲 Not Started (0%)
- **Phase 4**: 🔲 Not Started (0%)
- **Phase 5**: 🔲 Not Started (0%)
- **Phase 6**: 🔲 Not Started (0%)

**Total Progress**: 0% Complete

### Status Legend
- 🔲 Not Started
- 🔄 In Progress
- ✅ Completed
- ⚠️ Blocked
- ❌ Cancelled

---

## 🚀 Getting Started

### Prerequisites
1. SSH tunnel running (`./ssh_tunnel.sh status`)
2. Backend running (`cd reports-app/backend && uvicorn app.main:app --reload --port 8001`)
3. Frontend running (`cd reports-app/frontend && npm run dev`)
4. Valid JWT token for testing API

### Starting Development
```bash
# 1. Create feature branch
git checkout main
git pull origin main
git checkout -b feature/trial-balance

# 2. Verify Oracle VBAL table
# Connect to Oracle and run:
# SELECT * FROM VBAL WHERE ROWNUM <= 10;

# 3. Start backend (Phase 1)
cd reports-app/backend
# Create schemas/trial_balance.py
# Create routers/trial_balance.py
# Test with curl/Postman

# 4. Start frontend (Phases 2-4)
cd reports-app/frontend
# Create stores/trialBalanceStore.js
# Create views/TrialBalanceView.vue
# Update router and menu

# 5. Test and refine (Phase 5)
# Manual testing
# E2E tests (optional)

# 6. Create PR (Phase 6)
git add .
git commit -m "feat: Add Trial Balance page with filtering and pagination"
git push origin feature/trial-balance
# Create PR on GitHub/GitLab
```

---

## 📚 Reference Documentation

**MUST READ before coding**:
- `docs/ONBOARDING_CSS.md` - CSS quick start (5 min read)
- `docs/CSS_PATTERNS.md` - All available CSS patterns
- `docs/DESIGN_TOKENS.md` - Colors, spacing, typography
- `reports-app/frontend/README.md` - Frontend architecture
- `reports-app/backend/README.md` - Backend architecture

**Similar implementations to reference**:
- `reports-app/frontend/src/views/InvoicesView.vue` - Table + filters pattern
- `reports-app/frontend/src/views/DashboardView.vue` - Cards + data display
- `reports-app/backend/app/routers/invoices.py` - API with filtering/pagination

---

## ⚠️ Important Notes

### CSS Architecture Compliance
**CRITICAL**: This feature MUST follow the established CSS architecture:

✅ **DO**:
- Use existing `.roa-*` patterns from `CSS_PATTERNS.md`
- Use design tokens (`var(--color-primary)`, `var(--spacing-4)`)
- Use vendor overrides in `src/assets/css/vendor/primevue/` for PrimeVue
- Keep component styles minimal and semantic
- Follow BEM naming if creating new components

❌ **DON'T**:
- Use `:deep()` in Vue components
- Hardcode colors or spacing values
- Duplicate existing patterns
- Create custom CSS without checking patterns first
- Override PrimeVue styles in component `<style>` blocks

### Database Considerations
- **Performance**: Use indexes on `VBAL(COD_FIRMA, AN, LUNA, CONT)`
- **Data Volume**: Consider pagination for companies with many accounts
- **Filters**: Use Oracle `LIKE` with wildcards efficiently: `CONT LIKE :cont || '%'`

### Security
- **JWT Auth**: Required for all API calls
- **Company Access**: Verify user has access to `cod_firma` in request
- **SQL Injection**: Use parameterized queries (`:param` syntax)

### Future Enhancements (Not in Initial Scope)
- Export to Excel/PDF
- Drill-down to account details (sold și rulaj pe luni)
- Comparison between periods (current vs previous month/year)
- Charts/visualizations (rulaj pe conturi)
- Advanced filters (by account class/category)

---

## 🐛 Known Issues / Risks

1. **Oracle VBAL table structure unknown**: Verify column names and types in Phase 0
2. **Performance with large datasets**: Monitor query performance, add indexes if needed
3. **Decimal precision**: Ensure proper handling of Romanian decimal separator (comma vs dot)
4. **Company switching**: Ensure data refreshes when user switches active company

---

## 📞 Support

For questions or blockers, refer to:
- **Architecture**: `docs/ARCHITECTURE_SCHEMA.md`, `docs/MICROSERVICES_GUIDE.md`
- **CSS Issues**: `docs/ONBOARDING_CSS.md`, `docs/STYLING_GUIDELINES.md`
- **Backend Issues**: `reports-app/backend/README.md`, `README.md` (troubleshooting)
- **Frontend Issues**: `reports-app/frontend/README.md`

---

**Last Updated**: 2025-11-20
**Feature Owner**: Claude Code
**Reviewers**: TBD