From 0bdf079a2068e8bf16195c43025065110a951a22 Mon Sep 17 00:00:00 2001 From: Marius Mutu Date: Mon, 22 Dec 2025 10:51:08 +0200 Subject: [PATCH] docs: Update unified app spec to use root directory structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Modified all specification files to reference the project root directory (.) instead of creating a new unified-app/ subdirectory: - spec.md: Updated project structure and all file paths - SUMMARY.md: Updated critical files paths and documentation references - critical-files.md: Updated all source/destination paths for migration - MIGRATION_CHECKLIST.md: Updated directory creation and file paths All implementation files will now be created directly in /mnt/e/proiecte/roa2web/ instead of /mnt/e/proiecte/roa2web/unified-app/ ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .../specs/unified-app/MIGRATION_CHECKLIST.md | 406 ++++++ .auto-build-data/specs/unified-app/SUMMARY.md | 346 +++++ .../specs/unified-app/critical-files.md | 477 +++++++ .auto-build-data/specs/unified-app/spec.md | 1114 +++++++++++++++++ .../specs/unified-app/status.json | 30 + 5 files changed, 2373 insertions(+) create mode 100644 .auto-build-data/specs/unified-app/MIGRATION_CHECKLIST.md create mode 100644 .auto-build-data/specs/unified-app/SUMMARY.md create mode 100644 .auto-build-data/specs/unified-app/critical-files.md create mode 100644 .auto-build-data/specs/unified-app/spec.md create mode 100644 .auto-build-data/specs/unified-app/status.json diff --git a/.auto-build-data/specs/unified-app/MIGRATION_CHECKLIST.md b/.auto-build-data/specs/unified-app/MIGRATION_CHECKLIST.md new file mode 100644 index 0000000..03cc403 --- /dev/null +++ b/.auto-build-data/specs/unified-app/MIGRATION_CHECKLIST.md @@ -0,0 +1,406 @@ +# Unified App Migration Checklist + +**Track your progress** as you implement the unified app. + +--- + +## Phase 1: Project Setup (0.5 days) + +### Directory Structure +- [ ] Create directory structure in root (`/mnt/e/proiecte/roa2web/`) +- [ ] Create `src/` subdirectories: + - [ ] `src/modules/reports/views/` + - [ ] `src/modules/reports/stores/` + - [ ] `src/modules/reports/services/` + - [ ] `src/modules/data-entry/views/receipts/` + - [ ] `src/modules/data-entry/components/ocr/` + - [ ] `src/modules/data-entry/stores/` + - [ ] `src/modules/data-entry/services/` + - [ ] `src/shared/components/` + - [ ] `src/shared/stores/` + - [ ] `src/shared/styles/` + - [ ] `src/config/` + - [ ] `src/router/` + - [ ] `src/assets/css/` + +### Core Configuration Files +- [ ] Create `package.json` (merge dependencies from both apps) +- [ ] Create `vite.config.js` (dual proxy + lazy loading) +- [ ] Create `src/main.js` (PrimeVue setup) +- [ ] Create `.env.example` (environment variables) +- [ ] Create `.gitignore` +- [ ] Create `README.md` + +### Copy Shared Resources +- [ ] Copy `shared/frontend/components/` โ†’ `src/shared/components/` +- [ ] Copy `shared/frontend/stores/` โ†’ `src/shared/stores/` +- [ ] Copy `shared/frontend/styles/` โ†’ `src/shared/styles/` +- [ ] Copy `reports-app/frontend/src/assets/css/` โ†’ `src/assets/css/` + +### Verification +- [ ] Run `npm install` - succeeds +- [ ] Run `npm run dev` - starts on port 3000 +- [ ] No console errors + +--- + +## Phase 2: Module Migration (1 day) + +### Reports Module - Views +- [ ] Copy `DashboardView.vue` โ†’ `src/modules/reports/views/` +- [ ] Copy `InvoicesView.vue` โ†’ `src/modules/reports/views/` +- [ ] Copy `BankCashRegisterView.vue` โ†’ `src/modules/reports/views/` +- [ ] Copy `TrialBalanceView.vue` โ†’ `src/modules/reports/views/` +- [ ] Copy `TelegramView.vue` โ†’ `src/modules/reports/views/` +- [ ] Copy `CacheStatsView.vue` โ†’ `src/modules/reports/views/` +- [ ] Update imports in all views (if needed) + +### Reports Module - Stores +- [ ] Copy `dashboard.js` โ†’ `src/modules/reports/stores/` +- [ ] Copy `invoices.js` โ†’ `src/modules/reports/stores/` +- [ ] Copy `treasury.js` โ†’ `src/modules/reports/stores/` +- [ ] Copy `trialBalance.js` โ†’ `src/modules/reports/stores/` +- [ ] Copy `cacheStore.js` โ†’ `src/modules/reports/stores/` +- [ ] Update imports in all stores (if needed) + +### Reports Module - Services +- [ ] Copy `api.js` โ†’ `src/modules/reports/services/` (in root) +- [ ] Update base URL to `/api/reports/` in api.js +- [ ] Test API calls route to localhost:8001 + +### Data Entry Module - Views +- [ ] Copy `ReceiptsListView.vue` โ†’ `src/modules/data-entry/views/receipts/` +- [ ] Copy `ReceiptCreateView.vue` โ†’ `src/modules/data-entry/views/receipts/` +- [ ] Update imports in views (if needed) + +### Data Entry Module - Components +- [ ] Copy `OCRUploadZone.vue` โ†’ `src/modules/data-entry/components/ocr/` +- [ ] Copy `OCRPreview.vue` โ†’ `src/modules/data-entry/components/ocr/` +- [ ] Copy `OCRConfidenceIndicator.vue` โ†’ `src/modules/data-entry/components/ocr/` +- [ ] Update imports in components (if needed) + +### Data Entry Module - Stores +- [ ] Copy `receiptsStore.js` โ†’ `src/modules/data-entry/stores/` +- [ ] Update imports in store (if needed) + +### Data Entry Module - Services +- [ ] Copy `api.js` โ†’ `src/modules/data-entry/services/` (in root) +- [ ] Update base URL to `/api/data-entry/` in api.js +- [ ] Test API calls route to localhost:8003 + +### CSS Merge +- [ ] Review `data-entry-app/frontend/src/assets/css/main.css` +- [ ] Merge unique styles into `src/assets/css/` (in root) +- [ ] Resolve any style conflicts +- [ ] Test responsive design + +### Verification +- [ ] All Reports views render without errors +- [ ] All Data Entry views render without errors +- [ ] No import errors in console +- [ ] CSS loads correctly +- [ ] No style conflicts + +--- + +## Phase 3: Routing & Navigation (0.5 days) + +### Router Configuration +- [ ] Create `src/router/index.js` (in root) +- [ ] Add `/login` route (eager loaded) +- [ ] Add `/reports/*` routes (lazy loaded) +- [ ] Add `/data-entry/*` routes (lazy loaded) +- [ ] Add redirect `/` โ†’ `/reports/dashboard` +- [ ] Add authentication guard +- [ ] Add 404 handling +- [ ] Test all routes work + +### Menu Configuration +- [ ] Create `src/config/menu.js` (in root) +- [ ] Define "Rapoarte" section +- [ ] Define "Introduceri Date" section +- [ ] Define "Sistem" section +- [ ] Export menu configuration + +### Feature Flags +- [ ] Create `src/config/features.js` (in root) +- [ ] Add reports.enabled flag +- [ ] Add dataEntry.enabled flag +- [ ] Add module-level flags +- [ ] Export isFeatureEnabled function + +### Root Component +- [ ] Create `src/App.vue` (in root) +- [ ] Integrate AppHeader with unified menu +- [ ] Integrate SlideMenu with menu sections +- [ ] Add router-view +- [ ] Add Toast and ConfirmDialog +- [ ] Test menu navigation + +### Verification +- [ ] Can navigate to all routes +- [ ] Menu highlights active route +- [ ] Authentication guard works +- [ ] Login redirects to dashboard +- [ ] 404 redirects work + +--- + +## Phase 4: Error Boundaries & Resilience (0.25 days) + +### Error Boundary Component +- [ ] Create `src/shared/components/ErrorBoundary.vue` (in root) +- [ ] Implement onErrorCaptured hook +- [ ] Add user-friendly error display +- [ ] Add retry functionality +- [ ] Add navigate away option +- [ ] Test with intentional error + +### Module Layouts +- [ ] Create `src/modules/reports/ReportsLayout.vue` (in root) +- [ ] Wrap with ErrorBoundary component +- [ ] Create `src/modules/data-entry/DataEntryLayout.vue` (in root) +- [ ] Wrap with ErrorBoundary component + +### Error Isolation Testing +- [ ] Introduce error in Reports module +- [ ] Verify Data Entry still works +- [ ] Introduce error in Data Entry module +- [ ] Verify Reports still works +- [ ] Test retry functionality +- [ ] Test navigate away functionality + +### Feature Flags Testing +- [ ] Disable Reports module +- [ ] Verify menu items hidden +- [ ] Disable Data Entry module +- [ ] Verify menu items hidden +- [ ] Re-enable all modules + +### Loading States +- [ ] Add loading spinner for lazy routes +- [ ] Test module switching loading +- [ ] Add skeleton screens (optional) + +### Verification +- [ ] Error boundary catches component errors +- [ ] User sees friendly error message +- [ ] Can retry or navigate away +- [ ] Module isolation works (error in one doesn't crash other) +- [ ] Feature flags work + +--- + +## Phase 5: Build & Deploy (0.25 days) + +### Production Build +- [ ] Run `npm run build` +- [ ] Build succeeds without errors +- [ ] Check `dist/` output +- [ ] Verify chunks created: + - [ ] vendor-core.[hash].js + - [ ] vendor-primevue.[hash].js + - [ ] vendor-utils.[hash].js + - [ ] reports.[hash].js (lazy) + - [ ] data-entry.[hash].js (lazy) + - [ ] main.[hash].js + - [ ] main.[hash].css + +### Bundle Analysis +- [ ] Install `rollup-plugin-visualizer` +- [ ] Analyze bundle sizes +- [ ] Verify total size โ‰ค sum of current apps +- [ ] Check for duplicate dependencies + +### Local Preview +- [ ] Run `npm run preview` +- [ ] Test all routes work +- [ ] Test API calls work +- [ ] Test error boundaries +- [ ] Test lazy loading + +### IIS Configuration +- [ ] Create `web.config` (in root) with URL rewrite rules +- [ ] Add SPA routing rule (all โ†’ index.html) +- [ ] Add proxy rule: `/api/reports/*` โ†’ `http://localhost:8001/api/*` +- [ ] Add proxy rule: `/api/data-entry/*` โ†’ `http://localhost:8003/api/*` +- [ ] Add proxy rule: `/uploads/*` โ†’ `http://localhost:8003/uploads/*` + +### Staging Deployment +- [ ] Deploy to staging IIS site +- [ ] Test all routes +- [ ] Test API calls +- [ ] Test error boundaries +- [ ] Test on different browsers +- [ ] Test on mobile devices + +### Production Deployment +- [ ] Backup current IIS configuration +- [ ] Backup current builds +- [ ] Deploy unified app +- [ ] Test all routes +- [ ] Test API calls +- [ ] Monitor error logs + +### Verification +- [ ] Build succeeds +- [ ] Chunks split correctly +- [ ] IIS deployment works +- [ ] API routing correct +- [ ] All features work in production + +--- + +## Testing Checklist + +### Manual Testing +- [ ] Login flow works +- [ ] Navigate to all Reports views +- [ ] Navigate to all Data Entry views +- [ ] Switch between modules +- [ ] Test company selector +- [ ] Test period selector +- [ ] Test logout +- [ ] Test on mobile (375px) +- [ ] Test on tablet (768px) +- [ ] Test on desktop (1920px) + +### E2E Tests +- [ ] Create `tests/e2e/login.spec.js` (in root) +- [ ] Create `tests/e2e/reports-navigation.spec.js` (in root) +- [ ] Create `tests/e2e/data-entry-navigation.spec.js` (in root) +- [ ] Create `tests/e2e/module-switching.spec.js` (in root) +- [ ] Create `tests/e2e/error-isolation.spec.js` (in root) +- [ ] Run all E2E tests - pass + +### Performance Testing +- [ ] Run Lighthouse audit +- [ ] Performance score โ‰ฅ 90 +- [ ] Initial load < 2 seconds +- [ ] Module switching < 500ms (cached) + +--- + +## Post-Implementation Checklist + +### Documentation Updates +- [ ] Update `CLAUDE.md` - Architecture section +- [ ] Update `CLAUDE.md` - Deployment section +- [ ] Update `README.md` - Quick start +- [ ] Update `README.md` - URL structure +- [ ] Update `DEPLOYMENT_GUIDE.md` - IIS configuration +- [ ] Update `docs/ARCHITECTURE_SCHEMA.md` - Diagrams +- [ ] Update `deployment/windows/README.md` - Deployment steps + +### Cleanup (After 1 Week) +- [ ] Archive `reports-app/frontend/` โ†’ `reports-app/frontend-archived/` +- [ ] Archive `data-entry-app/frontend/` โ†’ `data-entry-app/frontend-archived/` +- [ ] Update `start-test.sh` to use root directory +- [ ] Update `start-data-entry.sh` to use root directory +- [ ] Update CI/CD pipelines (if any) +- [ ] Document migration in CHANGELOG.md + +### Monitoring (First Week) +- [ ] Day 1: Review error logs +- [ ] Day 2: Review error logs +- [ ] Day 3: Review error logs +- [ ] Day 4: Review error logs +- [ ] Day 5: Review error logs +- [ ] Day 6: Review error logs +- [ ] Day 7: Review error logs + user feedback + +### Optimization (First Month) +- [ ] Week 2: Analyze bundle sizes +- [ ] Week 2: Optimize images/assets +- [ ] Week 3: Consider further code splitting +- [ ] Week 3: Add performance monitoring +- [ ] Week 4: Evaluate feature flag usage +- [ ] Week 4: Plan next improvements + +--- + +## Common Issues & Solutions + +### Issue: CSS Conflicts +**Solution**: Use CSS modules, check `docs/CSS_PATTERNS.md` + +### Issue: Import Errors +**Solution**: Update import paths, check alias configuration in vite.config.js + +### Issue: API Calls Failing +**Solution**: Verify proxy configuration, check backend is running + +### Issue: Error Boundary Not Catching +**Solution**: Check onErrorCaptured implementation, add global error handler + +### Issue: Large Bundle Size +**Solution**: Review manualChunks, enable tree shaking, lazy load more + +### Issue: IIS Routing Not Working +**Solution**: Check web.config URL rewrite rules, verify IIS URL Rewrite module installed + +### Issue: Store Contamination +**Solution**: Use module-scoped stores, check for global state + +### Issue: PrimeVue Theme Conflicts +**Solution**: Use single theme (saga-blue), override in vendor CSS + +--- + +## Progress Tracking + +**Phase 1: Setup** +- Started: ___________ +- Completed: ___________ +- Time Spent: ___________ hours + +**Phase 2: Migration** +- Started: ___________ +- Completed: ___________ +- Time Spent: ___________ hours + +**Phase 3: Routing** +- Started: ___________ +- Completed: ___________ +- Time Spent: ___________ hours + +**Phase 4: Error Boundaries** +- Started: ___________ +- Completed: ___________ +- Time Spent: ___________ hours + +**Phase 5: Build & Deploy** +- Started: ___________ +- Completed: ___________ +- Time Spent: ___________ hours + +**Total Time**: ___________ hours (Estimated: 20 hours) + +--- + +## Success Metrics + +### Deployment +- [ ] Single IIS site running (not 2) +- [ ] Single build process (not 2) +- [ ] Zero downtime during deployment + +### Performance +- [ ] Initial load < 2 seconds +- [ ] Module switching < 500ms +- [ ] Lighthouse score โ‰ฅ 90 +- [ ] Bundle size โ‰ค sum of old apps + +### Quality +- [ ] 100% feature parity +- [ ] All E2E tests passing +- [ ] Zero user-reported bugs (first week) +- [ ] Error isolation verified + +--- + +**Status**: โฌœ Not Started | ๐Ÿ”ต In Progress | โœ… Complete + +**Last Updated**: ___________ +**Completed By**: ___________ +**Production Deploy Date**: ___________ diff --git a/.auto-build-data/specs/unified-app/SUMMARY.md b/.auto-build-data/specs/unified-app/SUMMARY.md new file mode 100644 index 0000000..0c118f3 --- /dev/null +++ b/.auto-build-data/specs/unified-app/SUMMARY.md @@ -0,0 +1,346 @@ +# Unified App Specification - Executive Summary + +**Created**: 2025-12-22 +**Status**: Implementation-Ready +**Estimated Effort**: 2.5 days + +--- + +## What We're Building + +A single unified SPA that consolidates the Reports App and Data Entry App into one application with: +- Unified menu navigation between modules +- Module isolation via error boundaries +- Lazy loading for optimal performance +- Single build and deployment process + +--- + +## Key Requirements (Top 5) + +1. **Unified Navigation**: Single menu with Reports and Data Entry sections +2. **Module Isolation**: Error in one module doesn't crash the other +3. **Lazy Loading**: Modules loaded on-demand, not upfront +4. **Simplified Deployment**: Single IIS site instead of 2 +5. **Zero Backend Changes**: Both backends (8001, 8003) remain unchanged + +--- + +## Technical Approach + +### Architecture: Pragmatic Monolith + +**NOT using micro-frontends** because: +- Only 1 developer (not 20+ team) +- Weekly deploys (not multiple times per day) +- 1-5 concurrent users (not millions) +- Same tech stack (Vue 3 only) + +**Using instead**: +- Error boundaries for isolation (50-70% blast radius reduction) +- Lazy loading for performance +- Feature flags for module control +- Shared dependencies for smaller bundles + +### URL Structure + +``` +/login โ†’ Login +/ โ†’ Redirect to /reports/dashboard + +/reports/dashboard โ†’ Dashboard +/reports/invoices โ†’ Invoices +/reports/bank-cash โ†’ Bank/Cash +/reports/trial-balance โ†’ Trial Balance +/reports/telegram โ†’ Telegram Bot +/reports/cache-stats โ†’ Cache Stats + +/data-entry โ†’ Receipts List +/data-entry/create โ†’ New Receipt +/data-entry/:id โ†’ View Receipt +/data-entry/:id/edit โ†’ Edit Receipt +``` + +### API Routing + +**Vite Dev Proxy**: +- `/api/reports/*` โ†’ `http://localhost:8001/api/*` +- `/api/data-entry/*` โ†’ `http://localhost:8003/api/*` +- `/uploads/*` โ†’ `http://localhost:8003/uploads/*` + +**IIS Production Proxy**: +- Same routing via web.config URL rewrite rules + +--- + +## Critical Files (Top 10) + +### To Create (in root directory) + +1. `package.json` - Merged dependencies +2. `vite.config.js` - Dual proxy + lazy loading +3. `src/main.js` - App initialization +4. `src/App.vue` - Root with unified menu +5. `src/router/index.js` - Unified router +6. `src/config/menu.js` - Menu configuration +7. `src/shared/components/ErrorBoundary.vue` - Error isolation +8. `src/modules/reports/ReportsLayout.vue` - Reports wrapper +9. `src/modules/data-entry/DataEntryLayout.vue` - Data Entry wrapper +10. `web.config` - IIS configuration + +### To Migrate + +**Reports Module** (7 views, 5 stores, 1 service): +- Views: Dashboard, Invoices, BankCash, TrialBalance, Telegram, CacheStats +- Stores: dashboard, invoices, treasury, trialBalance, cacheStore +- Service: api.js (change base URL to `/api/reports/`) + +**Data Entry Module** (2 views, 3 components, 1 store, 1 service): +- Views: ReceiptsList, ReceiptCreate +- Components: OCRUploadZone, OCRPreview, OCRConfidenceIndicator +- Store: receiptsStore +- Service: api.js (change base URL to `/api/data-entry/`) + +**Shared** (5 components, 3 stores): +- Components: LoginView, AppHeader, SlideMenu, CompanySelector, PeriodSelector +- Stores: auth, companies, accountingPeriod (factories) + +**CSS**: Copy entire `reports-app/frontend/src/assets/css/` structure + +--- + +## Implementation Phases + +### Phase 1: Setup (0.5 days) +- Create directory structure +- Setup package.json, vite.config.js +- Copy shared components and CSS + +**Verify**: `npm install` and `npm run dev` work + +### Phase 2: Migration (1 day) +- Migrate all views, components, stores +- Update API service base URLs +- Merge CSS + +**Verify**: All views render, no import errors + +### Phase 3: Routing & Navigation (0.5 days) +- Create unified router with lazy loading +- Create menu configuration +- Create error boundaries +- Integrate AppHeader and SlideMenu + +**Verify**: Navigation works, lazy loading works + +### Phase 4: Error Boundaries & Resilience (0.25 days) +- Test error isolation +- Test feature flags +- Add loading states + +**Verify**: Error in one module doesn't crash other + +### Phase 5: Build & Deploy (0.25 days) +- Production build +- IIS configuration +- Deploy to staging +- Test all routes + +**Verify**: Build succeeds, IIS works, APIs route correctly + +--- + +## Expected Build Output + +``` +dist/ +โ”œโ”€โ”€ index.html +โ”œโ”€โ”€ assets/ +โ”‚ โ”œโ”€โ”€ vendor-core.[hash].js (~150KB) - Vue, Router, Pinia +โ”‚ โ”œโ”€โ”€ vendor-primevue.[hash].js (~200KB) - PrimeVue components +โ”‚ โ”œโ”€โ”€ vendor-utils.[hash].js (~80KB) - Axios, date-fns +โ”‚ โ”œโ”€โ”€ vendor-charts.[hash].js (~150KB) - Chart.js (lazy) +โ”‚ โ”œโ”€โ”€ vendor-export.[hash].js (~200KB) - XLSX, jsPDF (lazy) +โ”‚ โ”œโ”€โ”€ reports.[hash].js (~150KB) - Reports module (lazy) +โ”‚ โ”œโ”€โ”€ data-entry.[hash].js (~100KB) - Data Entry module (lazy) +โ”‚ โ”œโ”€โ”€ main.[hash].js (~50KB) - App shell +โ”‚ โ””โ”€โ”€ main.[hash].css (~80KB) - Global CSS +``` + +--- + +## Success Criteria + +### Must Have (Before Production) +- [ ] All Reports views work correctly +- [ ] All Data Entry views work correctly +- [ ] Navigation preserves auth and company/period +- [ ] Error in one module doesn't crash other +- [ ] Single IIS site deployment works +- [ ] API routing to both backends works + +### Performance Targets +- [ ] Initial load < 2 seconds +- [ ] Module switching < 500ms (cached) +- [ ] Bundle size โ‰ค sum of current apps +- [ ] Lighthouse score โ‰ฅ 90 + +### Testing +- [ ] E2E tests pass for login +- [ ] E2E tests pass for Reports navigation +- [ ] E2E tests pass for Data Entry navigation +- [ ] E2E tests pass for module switching +- [ ] E2E tests verify error isolation + +--- + +## Risks & Mitigations + +| Risk | Mitigation | +|------|------------| +| CSS conflicts | Use design tokens, test thoroughly | +| Large bundle size | Lazy loading, code splitting, tree shaking | +| Error boundary gaps | Test error scenarios, add global handler | +| IIS deployment complexity | Document config, test on staging first | +| Store contamination | Module-scoped stores, test isolation | + +--- + +## Rollback Plan + +**If deployment fails**: + +1. **Keep both apps running** (zero downtime) + - Leave `/roa2web/` and `/data-entry/` running + - Add unified app at `/unified/` for testing + +2. **Quick rollback** (15 minutes) + - Restore IIS config from backup + - Restore builds from `dist-backup/` + +3. **Git rollback** + - Tag before merge: `v1.0-pre-unified` + - Revert if needed: `git reset --hard v1.0-pre-unified` + +--- + +## Post-Implementation + +### After 1 Week of Stability + +**Archive old frontends**: +```bash +mv reports-app/frontend reports-app/frontend-archived +mv data-entry-app/frontend data-entry-app/frontend-archived +``` + +**Update documentation**: +- CLAUDE.md - Architecture and deployment +- DEPLOYMENT_GUIDE.md - IIS configuration +- README.md - Quick start and commands + +**Update scripts**: +- `./start-test.sh` - Point to root directory +- `./start-data-entry.sh` - Point to root directory + +### Monitoring (First Month) + +**Week 1**: Daily error log review +**Week 2-4**: Performance optimization +- Bundle size optimization +- Further code splitting +- Cache optimization + +--- + +## Open Questions & Recommendations + +### 1. PrimeVue Theme +**Question**: Use `saga-blue` (reports-app) or `lara-light-blue` (data-entry-app)? +**Recommendation**: `saga-blue` (reports-app is primary) + +### 2. Feature Flags +**Question**: Config file or environment variables? +**Recommendation**: Config file for simplicity, env vars for override + +### 3. Module Activation +**Question**: All active by default or opt-in? +**Recommendation**: All active by default (disable via config if needed) + +### 4. Monitoring +**Question**: Console logs only or add Sentry/similar? +**Recommendation**: Console logs for MVP, add monitoring later + +--- + +## Key Decisions Made + +1. **Architecture**: Pragmatic monolith (not micro-frontends) +2. **Error Isolation**: Error boundaries per module +3. **Code Splitting**: Lazy loading with manual chunks +4. **URL Structure**: `/reports/*` and `/data-entry/*` +5. **API Routing**: Proxy via Vite (dev) and IIS (prod) +6. **CSS System**: Use reports-app CSS structure +7. **PrimeVue Theme**: saga-blue (from reports-app) +8. **Shared Components**: Use existing from `shared/frontend/` +9. **Deployment**: Single IIS site at root `/` +10. **Backends**: No changes (remain at 8001, 8003) + +--- + +## Documentation Locations + +**Complete Spec**: `.auto-build-data/specs/unified-app/spec.md` +**Critical Files**: `.auto-build-data/specs/unified-app/critical-files.md` +**This Summary**: `.auto-build-data/specs/unified-app/SUMMARY.md` + +**Note**: All implementation files will be created in the project root directory (`.` or `/mnt/e/proiecte/roa2web/`) + +**Reference Docs**: +- `IMPLEMENTATION_PLAN_UNIFIED_APP.md` - Original plan +- `CLAUDE.md` - Project documentation (update after) +- `docs/ONBOARDING_CSS.md` - CSS system guide +- `docs/CSS_PATTERNS.md` - Available CSS patterns + +--- + +## Next Steps + +1. **Read the complete spec**: `spec.md` (detailed technical specification) +2. **Review critical files**: `critical-files.md` (files to migrate/create) +3. **Start Phase 1**: Project setup (0.5 days) +4. **Follow implementation plan**: 5 phases over 2.5 days +5. **Test thoroughly**: E2E tests before production +6. **Deploy to staging**: Test IIS configuration +7. **Deploy to production**: Single site deployment +8. **Monitor for 1 week**: Daily error log review +9. **Archive old apps**: After stability confirmed +10. **Update docs**: Complete documentation updates + +--- + +## Quick Stats + +- **Files to create**: ~15 +- **Files to migrate**: ~20 +- **CSS files to copy**: ~30 +- **Total files affected**: ~65 +- **Estimated time**: 2.5 days (20 hours) +- **Complexity**: Medium +- **Risk level**: Medium-Low (with mitigations) + +--- + +**Specification Status**: โœ… Implementation-Ready +**All Technical Decisions**: โœ… Made +**Rollback Plan**: โœ… Defined +**Success Criteria**: โœ… Defined + +**Ready to implement!** ๐Ÿš€ + +--- + +**Version**: 1.0 +**Created**: 2025-12-22 +**Author**: Claude (Specification Agent) +**For**: ROA2WEB Unified App Feature diff --git a/.auto-build-data/specs/unified-app/critical-files.md b/.auto-build-data/specs/unified-app/critical-files.md new file mode 100644 index 0000000..80d63e8 --- /dev/null +++ b/.auto-build-data/specs/unified-app/critical-files.md @@ -0,0 +1,477 @@ +# Unified App - Critical Files Reference + +**Quick Reference**: Files that will be most affected during implementation + +--- + +## Files to Analyze (Before Implementation) + +### Configuration Files + +**Reports App**: +- `/mnt/e/proiecte/roa2web/reports-app/frontend/package.json` - Dependencies to merge +- `/mnt/e/proiecte/roa2web/reports-app/frontend/vite.config.js` - Proxy config, build settings +- `/mnt/e/proiecte/roa2web/reports-app/frontend/src/main.js` - PrimeVue setup + +**Data Entry App**: +- `/mnt/e/proiecte/roa2web/data-entry-app/frontend/package.json` - Dependencies to merge +- `/mnt/e/proiecte/roa2web/data-entry-app/frontend/vite.config.js` - Proxy config +- `/mnt/e/proiecte/roa2web/data-entry-app/frontend/src/main.js` - PrimeVue setup + +### Application Entry Points + +**Reports App**: +- `/mnt/e/proiecte/roa2web/reports-app/frontend/src/App.vue` - Root component, menu integration +- `/mnt/e/proiecte/roa2web/reports-app/frontend/src/router/index.js` - Router config + +**Data Entry App**: +- `/mnt/e/proiecte/roa2web/data-entry-app/frontend/src/App.vue` - Root component, menu integration +- `/mnt/e/proiecte/roa2web/data-entry-app/frontend/src/router/index.js` - Router config + +### Shared Components (Already Created) + +- `/mnt/e/proiecte/roa2web/shared/frontend/components/LoginView.vue` +- `/mnt/e/proiecte/roa2web/shared/frontend/components/layout/AppHeader.vue` +- `/mnt/e/proiecte/roa2web/shared/frontend/components/layout/SlideMenu.vue` +- `/mnt/e/proiecte/roa2web/shared/frontend/components/CompanySelector.vue` +- `/mnt/e/proiecte/roa2web/shared/frontend/components/PeriodSelector.vue` + +### Shared Stores (Factories) + +- `/mnt/e/proiecte/roa2web/shared/frontend/stores/auth.js` +- `/mnt/e/proiecte/roa2web/shared/frontend/stores/companies.js` +- `/mnt/e/proiecte/roa2web/shared/frontend/stores/accountingPeriod.js` + +--- + +## Views to Migrate + +### Reports Module (7 views) + +Source: `/mnt/e/proiecte/roa2web/reports-app/frontend/src/views/` +Destination: `/mnt/e/proiecte/roa2web/src/modules/reports/views/` + +1. `DashboardView.vue` - Main dashboard with metrics +2. `InvoicesView.vue` - Invoices table and filters +3. `BankCashRegisterView.vue` - Bank and cash register transactions +4. `TrialBalanceView.vue` - Trial balance report +5. `TelegramView.vue` - Telegram bot management +6. `CacheStatsView.vue` - Cache statistics +7. ~~`LoginView.vue`~~ - USE SHARED VERSION + +### Data Entry Module (2 views + 3 components) + +**Views**: +Source: `/mnt/e/proiecte/roa2web/data-entry-app/frontend/src/views/receipts/` +Destination: `/mnt/e/proiecte/roa2web/src/modules/data-entry/views/receipts/` + +1. `ReceiptsListView.vue` - List of receipts with filters +2. `ReceiptCreateView.vue` - Create/edit receipt form + +**Components**: +Source: `/mnt/e/proiecte/roa2web/data-entry-app/frontend/src/components/ocr/` +Destination: `/mnt/e/proiecte/roa2web/src/modules/data-entry/components/ocr/` + +1. `OCRUploadZone.vue` - File upload zone for receipts +2. `OCRPreview.vue` - Preview uploaded receipt image +3. `OCRConfidenceIndicator.vue` - OCR confidence indicator + +--- + +## Stores to Migrate + +### Reports Module (5 stores) + +Source: `/mnt/e/proiecte/roa2web/reports-app/frontend/src/stores/` +Destination: `/mnt/e/proiecte/roa2web/src/modules/reports/stores/` + +1. `dashboard.js` - Dashboard data and metrics +2. `invoices.js` - Invoices data and filters +3. `treasury.js` - Bank/cash register data +4. `trialBalance.js` - Trial balance data +5. `cacheStore.js` - Cache statistics + +**SKIP** (use shared): +- ~~`auth.js`~~ - Use `/mnt/e/proiecte/roa2web/shared/frontend/stores/auth.js` +- ~~`companies.js`~~ - Use `/mnt/e/proiecte/roa2web/shared/frontend/stores/companies.js` +- ~~`accountingPeriod.js`~~ - Use `/mnt/e/proiecte/roa2web/shared/frontend/stores/accountingPeriod.js` + +### Data Entry Module (1 store) + +Source: `/mnt/e/proiecte/roa2web/data-entry-app/frontend/src/stores/` +Destination: `/mnt/e/proiecte/roa2web/src/modules/data-entry/stores/` + +1. `receiptsStore.js` - Receipts data and CRUD operations + +**SKIP** (use shared): +- ~~`auth.js`~~ - Use shared +- ~~`companies.js`~~ - Use shared +- ~~`accountingPeriod.js`~~ - Use shared + +--- + +## Services to Migrate + +### Reports Module + +Source: `/mnt/e/proiecte/roa2web/reports-app/frontend/src/services/` +Destination: `/mnt/e/proiecte/roa2web/src/modules/reports/services/` + +1. `api.js` - **MODIFY**: Change base URL to `/api/reports/` + +**Current**: +```javascript +const api = axios.create({ + baseURL: '/api' +}) +``` + +**New**: +```javascript +const api = axios.create({ + baseURL: '/api/reports' +}) +``` + +### Data Entry Module + +Source: `/mnt/e/proiecte/roa2web/data-entry-app/frontend/src/services/` +Destination: `/mnt/e/proiecte/roa2web/src/modules/data-entry/services/` + +1. `api.js` - **MODIFY**: Change base URL to `/api/data-entry/` + +**Current**: +```javascript +const api = axios.create({ + baseURL: '/api' +}) +``` + +**New**: +```javascript +const api = axios.create({ + baseURL: '/api/data-entry' +}) +``` + +--- + +## CSS to Migrate + +### Reports Module CSS (COPY ENTIRE STRUCTURE) + +Source: `/mnt/e/proiecte/roa2web/reports-app/frontend/src/assets/css/` +Destination: `/mnt/e/proiecte/roa2web/src/assets/css/` + +**Copy ALL files** (this is the main CSS system): +- `core/` - Design tokens (colors, spacing, typography) +- `components/` - Reusable UI patterns (buttons, forms, cards, tables, stats) +- `patterns/` - Interactive patterns (animations, dashboard, interactive) +- `layout/` - Page structure (containers, grid, navigation) +- `utilities/` - Utility classes (colors, spacing, flex, text, display) +- `vendor/` - PrimeVue overrides +- `global.css` - Global styles +- `main.css` - Main entry point +- `mobile.css` - Mobile responsive styles + +### Data Entry Module CSS (MERGE) + +Source: `/mnt/e/proiecte/roa2web/data-entry-app/frontend/src/assets/css/` + +**Analyze and merge unique styles**: +- `main.css` - Merge with reports-app main.css +- Any component-specific styles - Integrate into unified system + +### Shared CSS + +Source: `/mnt/e/proiecte/roa2web/shared/frontend/styles/` +Destination: `/mnt/e/proiecte/roa2web/src/shared/styles/` + +1. `login.css` - Login page styles +2. `layout/header.css` - Header styles +3. `layout/navigation.css` - Navigation styles + +--- + +## Critical Implementation Files + +### 1. Package Configuration + +**File**: `/mnt/e/proiecte/roa2web/package.json` + +**Dependencies to merge**: +- From reports-app: axios, chart.js, date-fns, jspdf, jspdf-autotable, qrcode.vue, xlsx +- From data-entry-app: All covered by reports-app +- Shared: vue@^3.4.0, vue-router@^4.2.5, pinia@^2.1.7, primevue@^3.46.0 + +### 2. Vite Configuration + +**File**: `/mnt/e/proiecte/roa2web/vite.config.js` + +**Key sections**: +- Dual proxy for `/api/reports/` โ†’ `http://localhost:8001` +- Dual proxy for `/api/data-entry/` โ†’ `http://localhost:8003` +- Lazy loading configuration (manualChunks) +- Alias configuration (@, @shared, @reports, @data-entry) + +### 3. Application Entry + +**File**: `/mnt/e/proiecte/roa2web/src/main.js` + +**Key setup**: +- PrimeVue configuration (theme: saga-blue) +- Global components registration +- Router, Pinia, ToastService, ConfirmationService +- CSS imports + +### 4. Root Component + +**File**: `/mnt/e/proiecte/roa2web/src/App.vue` + +**Key elements**: +- AppHeader with unified menu +- SlideMenu with module sections +- router-view +- Toast, ConfirmDialog + +### 5. Router Configuration + +**File**: `/mnt/e/proiecte/roa2web/src/router/index.js` + +**Key routes**: +- `/login` - LoginView (eager loaded) +- `/reports/*` - ReportsLayout (lazy loaded) with children +- `/data-entry/*` - DataEntryLayout (lazy loaded) with children +- Authentication guard + +### 6. Menu Configuration + +**File**: `/mnt/e/proiecte/roa2web/src/config/menu.js` + +**Sections**: +- Rapoarte (Reports) +- Introduceri Date (Data Entry) +- Sistem (System) + +### 7. Feature Flags + +**File**: `/mnt/e/proiecte/roa2web/src/config/features.js` + +**Flags**: +- reports.enabled +- dataEntry.enabled +- Module-level flags + +### 8. Error Boundary Component + +**File**: `/mnt/e/proiecte/roa2web/src/shared/components/ErrorBoundary.vue` + +**Key features**: +- onErrorCaptured hook +- User-friendly error display +- Retry functionality +- Navigate away option + +### 9. Module Layouts + +**File**: `/mnt/e/proiecte/roa2web/src/modules/reports/ReportsLayout.vue` + +**Wrapper**: +```vue + + + +``` + +**File**: `/mnt/e/proiecte/roa2web/src/modules/data-entry/DataEntryLayout.vue` + +**Wrapper**: +```vue + + + +``` + +--- + +## Deployment Files + +### IIS Configuration + +**File**: `/mnt/e/proiecte/roa2web/web.config` + +**Key rules**: +- SPA routing (all routes โ†’ index.html) +- API proxy: `/api/reports/*` โ†’ `http://localhost:8001/api/*` +- API proxy: `/api/data-entry/*` โ†’ `http://localhost:8003/api/*` +- Uploads proxy: `/uploads/*` โ†’ `http://localhost:8003/uploads/*` + +### Environment Variables + +**File**: `/mnt/e/proiecte/roa2web/.env.example` + +**Variables**: +```bash +# API Endpoints (dev only, production uses IIS proxy) +VITE_REPORTS_API=http://localhost:8001 +VITE_DATA_ENTRY_API=http://localhost:8003 + +# Feature Flags +VITE_ENABLE_REPORTS=true +VITE_ENABLE_DATA_ENTRY=true +``` + +--- + +## Testing Files + +### E2E Tests + +**New files to create**: +- `/mnt/e/proiecte/roa2web/tests/e2e/login.spec.js` +- `/mnt/e/proiecte/roa2web/tests/e2e/reports-navigation.spec.js` +- `/mnt/e/proiecte/roa2web/tests/e2e/data-entry-navigation.spec.js` +- `/mnt/e/proiecte/roa2web/tests/e2e/module-switching.spec.js` +- `/mnt/e/proiecte/roa2web/tests/e2e/error-isolation.spec.js` + +**Existing tests to adapt**: +- `/mnt/e/proiecte/roa2web/reports-app/frontend/tests/` - Update routes +- `/mnt/e/proiecte/roa2web/data-entry-app/frontend/tests/` - Update routes + +--- + +## Documentation Files to Update + +### Primary Documentation + +1. **CLAUDE.md** (root) + - Update architecture diagram + - Add unified-app section + - Mark old apps as archived + - Update deployment instructions + +2. **README.md** (root) + - Update quick start + - Update deployment section + - Update URL structure + +3. **DEPLOYMENT_GUIDE.md** + - Update IIS configuration + - Update build process + - Add rollback instructions + +4. **docs/ARCHITECTURE_SCHEMA.md** + - Update architecture diagrams + - Document module structure + - Add error boundary architecture + +### Deployment Documentation + +5. **deployment/windows/README.md** + - Update deployment steps + - Update IIS configuration + - Update proxy rules + +6. **deployment/windows/docs/WINDOWS_DEPLOYMENT.md** + - Complete Windows guide updates + +--- + +## File Count Summary + +**To Create**: ~15 new files +- 9 core files (package.json, vite.config.js, main.js, App.vue, router, menu, features, ErrorBoundary, 2 layouts) +- 3 configuration files (.env.example, web.config, README.md) +- 3 documentation updates + +**To Migrate**: ~20 files +- 7 Reports views +- 2 Data Entry views +- 3 Data Entry components +- 5 Reports stores +- 1 Data Entry store +- 2 API services + +**To Copy**: ~30 CSS files +- Entire reports-app CSS structure + +**Total Files Affected**: ~65 files + +--- + +## Time Estimates per File Type + +| Task | Files | Avg Time | Total | +|------|-------|----------|-------| +| Create core files | 9 | 30 min | 4.5 hours | +| Migrate views | 9 | 20 min | 3 hours | +| Migrate components | 3 | 15 min | 45 min | +| Migrate stores | 6 | 20 min | 2 hours | +| Migrate services | 2 | 30 min | 1 hour | +| Copy CSS | 1 | 1 hour | 1 hour | +| Configuration | 3 | 30 min | 1.5 hours | +| Documentation | 6 | 30 min | 3 hours | +| Testing & fixes | - | - | 4 hours | + +**Total**: ~20 hours (~2.5 days) + +--- + +## Verification Checklist + +After migrating each category: + +### Configuration Files โœ“ +- [ ] package.json has all dependencies +- [ ] vite.config.js has dual proxy +- [ ] main.js initializes correctly +- [ ] npm install succeeds +- [ ] npm run dev starts + +### Views โœ“ +- [ ] All Reports views render +- [ ] All Data Entry views render +- [ ] No import errors +- [ ] Routes work + +### Stores โœ“ +- [ ] All stores import correctly +- [ ] No duplicate store instances +- [ ] Shared stores work +- [ ] Module stores isolated + +### Services โœ“ +- [ ] API calls route to correct backend +- [ ] /api/reports/ โ†’ :8001 +- [ ] /api/data-entry/ โ†’ :8003 +- [ ] Auth headers preserved + +### CSS โœ“ +- [ ] No style conflicts +- [ ] Design tokens work +- [ ] PrimeVue theme consistent +- [ ] Responsive works + +### Router โœ“ +- [ ] All routes accessible +- [ ] Lazy loading works +- [ ] Auth guard works +- [ ] 404 redirects + +### Error Boundaries โœ“ +- [ ] Catches component errors +- [ ] Displays user message +- [ ] Module isolation works +- [ ] Can retry/navigate + +### Build โœ“ +- [ ] npm run build succeeds +- [ ] Chunks split correctly +- [ ] Bundle size acceptable +- [ ] Preview works + +--- + +**Last Updated**: 2025-12-22 +**For**: Unified App Implementation +**Reference**: See spec.md for complete specification diff --git a/.auto-build-data/specs/unified-app/spec.md b/.auto-build-data/specs/unified-app/spec.md new file mode 100644 index 0000000..d86b782 --- /dev/null +++ b/.auto-build-data/specs/unified-app/spec.md @@ -0,0 +1,1114 @@ +# Feature: Unified App - Pragmatic Monolith Consolidation + +## Overview + +Consolidate the two separate frontend applications (Reports App and Data Entry App) into a single unified SPA with both modules accessible from one menu. This pragmatic monolith approach maintains module isolation while simplifying deployment and providing a unified user experience with a single build and single IIS site. + +**Status**: Implementation-Ready +**Complexity**: Medium +**Estimated Effort**: 2.5 days + +--- + +## Problem Statement + +### Current Issues +- Two separate frontend deployments in IIS (`/roa2web/` and `/data-entry/`) +- Complex deployment process (2 builds, 2 IIS configurations) +- CSS conflicts when using shared components (white text on white background) +- No unified navigation between modules +- Duplicate setup and configuration code + +### Benefits of Unification +- Simplified deployment (single build, single IIS site) +- Unified user experience with single menu +- Shared component consistency +- Module isolation preserved through error boundaries +- Optimized bundle loading via lazy loading + +--- + +## User Stories + +### Primary Users +- As a **user**, I want to access both Reports and Data Entry modules from a single menu so that I can navigate seamlessly between functionalities. +- As a **developer**, I want simplified deployment with a single build process so that I can reduce deployment complexity and maintenance overhead. +- As a **user**, I want the app to remain functional even if one module encounters an error so that my work is not interrupted. +- As an **administrator**, I want a single IIS site configuration so that I can manage deployment more easily. + +--- + +## Functional Requirements + +### Core Requirements + +#### 1. Unified Navigation +- Single top-level menu with sections for Reports and Data Entry modules +- Menu structure: + - **Rapoarte** (Reports) section with Dashboard, Invoices, Bank/Cash, Trial Balance + - **Introduceri Date** (Data Entry) section with Receipts List, New Receipt + - **Sistem** section with Telegram Bot, Cache Stats +- Active route highlighting +- Responsive slide menu (mobile + desktop) + +#### 2. Module Isolation +- Error boundary per module (Reports, Data Entry) +- Bug in one module does not crash the other +- Independent lazy loading per module +- Separate stores per module (no cross-contamination) + +#### 3. URL Structure +``` +/login โ†’ Login page +/ โ†’ Redirect to /reports/dashboard + +/reports/dashboard โ†’ Dashboard (Reports module) +/reports/invoices โ†’ Invoices view +/reports/bank-cash โ†’ Bank/Cash register view +/reports/trial-balance โ†’ Trial Balance view +/reports/telegram โ†’ Telegram Bot management +/reports/cache-stats โ†’ Cache statistics + +/data-entry โ†’ Receipts list (Data Entry module) +/data-entry/create โ†’ Create new receipt +/data-entry/:id โ†’ View receipt details +/data-entry/:id/edit โ†’ Edit receipt +``` + +#### 4. Shared Components Integration +- Use existing shared components from `shared/frontend/`: + - `LoginView.vue` - Login page + - `AppHeader.vue` - Top navigation bar + - `SlideMenu.vue` - Sidebar menu + - `CompanySelector.vue` - Company dropdown + - `PeriodSelector.vue` - Accounting period selector +- Maintain consistent styling and behavior across modules + +#### 5. Authentication & Authorization +- Unified JWT authentication +- Single login flow for both modules +- Preserve existing auth store factory pattern +- Session persistence across module navigation + +### Secondary Requirements + +#### 1. Feature Flags +- Ability to enable/disable modules via configuration +- Feature flag configuration in `src/config/features.js` +- UI hides disabled module menu items + +#### 2. Loading States +- Module-level loading spinners +- Skeleton screens for lazy-loaded routes +- Progress indication during module switching + +#### 3. Analytics & Monitoring +- Track module switching events +- Error boundary triggers logged +- Performance metrics per module + +--- + +## Technical Requirements + +### Project Structure + +``` +. +โ”œโ”€โ”€ public/ +โ”‚ โ””โ”€โ”€ favicon.ico +โ”œโ”€โ”€ src/ +โ”‚ โ”œโ”€โ”€ main.js # App entry point +โ”‚ โ”œโ”€โ”€ App.vue # Root component with unified menu +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ router/ +โ”‚ โ”‚ โ””โ”€โ”€ index.js # Unified router with lazy loading +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ modules/ +โ”‚ โ”‚ โ”œโ”€โ”€ reports/ # ISOLATED REPORTS MODULE +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ReportsLayout.vue # Error boundary wrapper +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ views/ # Reports views (migrated) +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ DashboardView.vue +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ InvoicesView.vue +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ BankCashRegisterView.vue +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ TrialBalanceView.vue +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ TelegramView.vue +โ”‚ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ CacheStatsView.vue +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ stores/ # Module-specific stores +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ dashboard.js +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ invoices.js +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ treasury.js +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ trialBalance.js +โ”‚ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ cacheStore.js +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ services/ # Module API services +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ api.js # Reports API client +โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€ data-entry/ # ISOLATED DATA ENTRY MODULE +โ”‚ โ”‚ โ”œโ”€โ”€ DataEntryLayout.vue # Error boundary wrapper +โ”‚ โ”‚ โ”œโ”€โ”€ views/ # Data Entry views (migrated) +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ receipts/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ReceiptsListView.vue +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ReceiptCreateView.vue +โ”‚ โ”‚ โ”œโ”€โ”€ components/ # Module-specific components +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ocr/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ OCRUploadZone.vue +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ OCRPreview.vue +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ OCRConfidenceIndicator.vue +โ”‚ โ”‚ โ”œโ”€โ”€ stores/ # Module-specific stores +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ receiptsStore.js +โ”‚ โ”‚ โ””โ”€โ”€ services/ # Module API services +โ”‚ โ”‚ โ””โ”€โ”€ api.js # Data Entry API client +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ shared/ # SHARED COMPONENTS & LOGIC +โ”‚ โ”‚ โ”œโ”€โ”€ components/ # Shared UI components +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ layout/ +โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ AppHeader.vue +โ”‚ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ SlideMenu.vue +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ LoginView.vue +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ CompanySelector.vue +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ PeriodSelector.vue +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ErrorBoundary.vue # NEW: Error boundary component +โ”‚ โ”‚ โ”œโ”€โ”€ stores/ # Shared stores (factories) +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ auth.js # Auth store factory +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ companies.js # Companies store factory +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ accountingPeriod.js # Period store factory +โ”‚ โ”‚ โ””โ”€โ”€ styles/ # Shared CSS +โ”‚ โ”‚ โ”œโ”€โ”€ login.css +โ”‚ โ”‚ โ”œโ”€โ”€ layout/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ header.css +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ navigation.css +โ”‚ โ”‚ โ””โ”€โ”€ shared.css +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ config/ +โ”‚ โ”‚ โ”œโ”€โ”€ menu.js # Unified menu configuration +โ”‚ โ”‚ โ””โ”€โ”€ features.js # Feature flags +โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€ assets/ +โ”‚ โ””โ”€โ”€ css/ # Global CSS (from reports-app) +โ”‚ โ”œโ”€โ”€ core/ # Design tokens +โ”‚ โ”œโ”€โ”€ components/ # Reusable UI patterns +โ”‚ โ”œโ”€โ”€ patterns/ # Interactive patterns +โ”‚ โ”œโ”€โ”€ layout/ # Page structure +โ”‚ โ”œโ”€โ”€ utilities/ # Utility classes +โ”‚ โ””โ”€โ”€ vendor/ # PrimeVue overrides +โ”‚ +โ”œโ”€โ”€ vite.config.js # Unified Vite config (root) +โ”œโ”€โ”€ package.json # Merged dependencies (root) +โ”œโ”€โ”€ .env.example # Environment template (root) +โ””โ”€โ”€ README.md # Unified app documentation (root) +``` + +### Files to Create + +| File | Purpose | +|------|---------| +| `package.json` | Merged dependencies from both apps | +| `vite.config.js` | Dual proxy config, lazy loading, base path `/` | +| `src/main.js` | App initialization, PrimeVue setup, global components | +| `src/App.vue` | Root component with unified menu | +| `src/router/index.js` | Unified router with lazy loading | +| `src/config/menu.js` | Menu configuration | +| `src/config/features.js` | Feature flags | +| `src/shared/components/ErrorBoundary.vue` | Error boundary component | +| `src/modules/reports/ReportsLayout.vue` | Reports error boundary wrapper | +| `src/modules/data-entry/DataEntryLayout.vue` | Data Entry error boundary wrapper | +| `.env.example` | Environment variables template | +| `README.md` | Documentation | + +### Files to Migrate + +#### From `reports-app/frontend/` + +**Views** (โ†’ `modules/reports/views/`): +- DashboardView.vue +- InvoicesView.vue +- BankCashRegisterView.vue +- TrialBalanceView.vue +- TelegramView.vue +- CacheStatsView.vue +- ~~LoginView.vue~~ (use shared) + +**Stores** (โ†’ `modules/reports/stores/`): +- dashboard.js +- invoices.js +- treasury.js +- trialBalance.js +- cacheStore.js +- ~~auth.js~~ (use shared) +- ~~companies.js~~ (use shared) +- ~~accountingPeriod.js~~ (use shared) + +**Services** (โ†’ `modules/reports/services/`): +- api.js (adapt for `/api/reports/` prefix) + +**CSS** (โ†’ `assets/css/`): +- Copy entire `src/assets/css/` directory structure +- All design tokens, components, patterns, utilities + +#### From `data-entry-app/frontend/` + +**Views** (โ†’ `modules/data-entry/views/receipts/`): +- ReceiptsListView.vue +- ReceiptCreateView.vue +- ~~LoginView.vue~~ (use shared) + +**Components** (โ†’ `modules/data-entry/components/`): +- ocr/OCRUploadZone.vue +- ocr/OCRPreview.vue +- ocr/OCRConfidenceIndicator.vue + +**Stores** (โ†’ `modules/data-entry/stores/`): +- receiptsStore.js +- ~~auth.js~~ (use shared) +- ~~companies.js~~ (use shared) +- ~~accountingPeriod.js~~ (use shared) + +**Services** (โ†’ `modules/data-entry/services/`): +- api.js (adapt for `/api/data-entry/` prefix) + +**CSS** (โ†’ merge with `assets/css/`): +- main.css (merge with reports-app main.css) +- Any component-specific styles + +#### From `shared/frontend/` + +**Components** (โ†’ `shared/components/`): +- LoginView.vue +- layout/AppHeader.vue +- layout/SlideMenu.vue +- CompanySelector.vue +- PeriodSelector.vue + +**Stores** (โ†’ `shared/stores/`): +- auth.js (factory) +- companies.js (factory) +- accountingPeriod.js (factory) + +**Styles** (โ†’ `shared/styles/`): +- login.css +- layout/header.css +- layout/navigation.css + +### Dependencies + +#### Unified package.json (root directory) + +Merge all dependencies from both apps: + +**From reports-app**: +- axios: ^1.6.2 +- chart.js: ^4.5.0 +- date-fns: ^2.30.0 +- jspdf: ^3.0.1 +- jspdf-autotable: ^5.0.2 +- pinia: ^2.1.7 +- primeicons: ^6.0.1 +- primevue: ^3.46.0 +- qrcode.vue: ^3.6.0 +- vue: ^3.4.0 +- vue-chartjs: ^5.3.2 +- vue-router: ^4.2.5 +- xlsx: ^0.18.5 + +**From data-entry-app**: +- All duplicates already covered +- Additional: @primevue/themes: ^4.0.0 (optional, may remove) + +**DevDependencies**: +- @playwright/test: ^1.54.2 +- @vitejs/plugin-vue: ^5.0.0 +- eslint: ^8.56.0 +- eslint-plugin-vue: ^9.20.0 +- prettier: ^3.1.1 +- vite: ^5.0.10 + +### API Routing + +#### Vite Dev Server Proxy + +```javascript +// vite.config.js +server: { + port: 3000, + proxy: { + '/api/reports': { + target: 'http://localhost:8001', + changeOrigin: true, + rewrite: (path) => path.replace(/^\/api\/reports/, '/api') + }, + '/api/data-entry': { + target: 'http://localhost:8003', + changeOrigin: true, + rewrite: (path) => path.replace(/^\/api\/data-entry/, '/api') + }, + '/uploads': { + target: 'http://localhost:8003', + changeOrigin: true + } + } +} +``` + +#### IIS Production Proxy + +```xml + + + + + + + + + + + + + + + +``` + +### Build Configuration + +#### Vite Config - Lazy Loading & Bundle Splitting + +```javascript +// vite.config.js +export default defineConfig({ + plugins: [vue(), htmlTimestampPlugin()], + base: process.env.NODE_ENV === 'production' ? '/' : '/', + resolve: { + alias: { + '@': fileURLToPath(new URL('./src', import.meta.url)), + '@shared': fileURLToPath(new URL('./src/shared', import.meta.url)), + '@reports': fileURLToPath(new URL('./src/modules/reports', import.meta.url)), + '@data-entry': fileURLToPath(new URL('./src/modules/data-entry', import.meta.url)) + }, + dedupe: ['vue', 'vue-router', 'pinia', 'primevue'] + }, + build: { + outDir: 'dist', + sourcemap: true, + rollupOptions: { + output: { + manualChunks: { + // Core vendors + 'vendor-core': ['vue', 'vue-router', 'pinia'], + 'vendor-primevue': ['primevue/config', 'primevue/button', 'primevue/datatable'], + 'vendor-utils': ['axios', 'date-fns'], + + // Charts (reports only) + 'vendor-charts': ['chart.js', 'vue-chartjs'], + + // Excel/PDF exports + 'vendor-export': ['xlsx', 'jspdf', 'jspdf-autotable'], + + // Module-specific chunks (lazy loaded) + // Reports module loaded via dynamic import + // Data Entry module loaded via dynamic import + }, + entryFileNames: `assets/[name].[hash].js`, + chunkFileNames: `assets/[name].[hash].js`, + assetFileNames: `assets/[name].[hash].[ext]` + } + } + } +}) +``` + +**Expected Build Output**: +``` +dist/ +โ”œโ”€โ”€ index.html +โ”œโ”€โ”€ assets/ +โ”‚ โ”œโ”€โ”€ vendor-core.[hash].js (~150KB) - Vue, Router, Pinia +โ”‚ โ”œโ”€โ”€ vendor-primevue.[hash].js (~200KB) - PrimeVue components +โ”‚ โ”œโ”€โ”€ vendor-utils.[hash].js (~80KB) - Axios, date-fns +โ”‚ โ”œโ”€โ”€ vendor-charts.[hash].js (~150KB) - Chart.js (lazy) +โ”‚ โ”œโ”€โ”€ vendor-export.[hash].js (~200KB) - XLSX, jsPDF (lazy) +โ”‚ โ”œโ”€โ”€ reports.[hash].js (~150KB) - Reports module (lazy) +โ”‚ โ”œโ”€โ”€ data-entry.[hash].js (~100KB) - Data Entry module (lazy) +โ”‚ โ”œโ”€โ”€ main.[hash].js (~50KB) - App shell +โ”‚ โ””โ”€โ”€ main.[hash].css (~80KB) - Global CSS +``` + +--- + +## Design Decisions + +### Approach: Pragmatic Monolith + +**Why NOT Micro-frontends (Module Federation / Single-SPA)?** + +| Micro-Frontend Criterion | ROA2WEB Reality | Justification | +|-------------------------|-----------------|---------------| +| 20+ developers on separate teams | 1 developer | Overkill - no team coordination needed | +| Deploy multiple times per day | Weekly deploys | No benefit from independent deployments | +| Millions of users, high scale | 1-5 concurrent users | No scaling justification | +| Different frameworks per team | Vue 3 only | No technical diversity | +| Independent release cycles | Single release cycle | Adds unnecessary complexity | + +**Pragmatic Monolith Benefits**: +- Simple build process (single `npm run build`) +- Shared dependencies (smaller bundle size) +- Error boundaries provide 50-70% isolation (close to separate apps) +- Lazy loading prevents loading unused modules +- Feature flags allow disabling modules without redeploy + +### Error Boundary Implementation + +**ErrorBoundary.vue Component**: +```vue + + + +``` + +**Usage in Module Layouts**: +```vue + + + + + +``` + +### Lazy Loading Strategy + +**Router Configuration**: +```javascript +const routes = [ + { + path: '/login', + name: 'Login', + component: LoginView, + meta: { requiresAuth: false } + }, + { + path: '/reports', + component: () => import('@/modules/reports/ReportsLayout.vue'), + children: [ + { + path: 'dashboard', + name: 'Dashboard', + component: () => import('@/modules/reports/views/DashboardView.vue'), + meta: { requiresAuth: true, title: 'Dashboard - ROA Reports' } + }, + { + path: 'invoices', + name: 'Invoices', + component: () => import('@/modules/reports/views/InvoicesView.vue'), + meta: { requiresAuth: true, title: 'Facturi - ROA Reports' } + }, + // ... more routes + ] + }, + { + path: '/data-entry', + component: () => import('@/modules/data-entry/DataEntryLayout.vue'), + children: [ + { + path: '', + name: 'ReceiptsList', + component: () => import('@/modules/data-entry/views/receipts/ReceiptsListView.vue'), + meta: { requiresAuth: true, title: 'Lista Bonuri' } + }, + // ... more routes + ] + }, + { + path: '/', + redirect: '/reports/dashboard' + } +] +``` + +### Menu Configuration + +**config/menu.js**: +```javascript +export const menuSections = [ + { + title: 'Rapoarte', + items: [ + { to: '/reports/dashboard', icon: 'pi pi-home', label: 'Dashboard' }, + { to: '/reports/invoices', icon: 'pi pi-file', label: 'Facturi' }, + { to: '/reports/bank-cash', icon: 'pi pi-money-bill', label: 'Casa ศ™i Banca' }, + { to: '/reports/trial-balance', icon: 'pi pi-calculator', label: 'Balanศ›ฤƒ de Verificare' } + ] + }, + { + title: 'Introduceri Date', + items: [ + { to: '/data-entry', icon: 'pi pi-list', label: 'Lista Bonuri' }, + { to: '/data-entry/create', icon: 'pi pi-plus', label: 'Bon Nou' } + ] + }, + { + title: 'Sistem', + items: [ + { to: '/reports/telegram', icon: 'pi pi-telegram', label: 'Telegram Bot' }, + { to: '/reports/cache-stats', icon: 'pi pi-chart-bar', label: 'Statistici Cache' } + ] + } +] +``` + +### Feature Flags + +**config/features.js**: +```javascript +export const features = { + reports: { + enabled: true, + modules: { + dashboard: true, + invoices: true, + bankCash: true, + trialBalance: true, + telegram: true, + cacheStats: true + } + }, + dataEntry: { + enabled: true, + modules: { + receipts: true, + ocr: true + } + } +} + +export function isFeatureEnabled(module, subModule = null) { + if (!features[module]?.enabled) return false + if (subModule && !features[module]?.modules?.[subModule]) return false + return true +} +``` + +### CSS Architecture + +**Preserve Reports App CSS System**: +- Use complete CSS structure from `reports-app/frontend/src/assets/css/` +- Design tokens in `core/tokens.css` +- Component patterns in `components/` +- PrimeVue overrides in `vendor/primevue-overrides.css` + +**Merge Data Entry CSS**: +- Extract unique data-entry styles +- Integrate into existing pattern system +- Ensure no conflicts with reports CSS + +**Shared Styles**: +- Import from `src/shared/styles/` for LoginView, AppHeader, SlideMenu +- Maintain consistency across modules + +--- + +## Acceptance Criteria + +### Functionality +- [ ] User can log in and access both Reports and Data Entry modules from unified menu +- [ ] All Reports views (Dashboard, Invoices, Bank/Cash, Trial Balance, Telegram, Cache Stats) work correctly +- [ ] All Data Entry views (Receipts List, Create Receipt, Edit Receipt) work correctly +- [ ] Navigation between modules preserves authentication and selected company/period +- [ ] Error in Reports module does not crash Data Entry module (and vice versa) +- [ ] Logout works correctly and clears all stores + +### Performance +- [ ] Initial page load < 2 seconds on 3G connection +- [ ] Module switching (Reports โ†” Data Entry) < 500ms (already loaded) or < 1s (first load) +- [ ] Build produces separate chunks for each module (reports.js, data-entry.js) +- [ ] Total bundle size โ‰ค sum of current apps (no regression) +- [ ] Lighthouse score โ‰ฅ 90 for Performance + +### Build & Deployment +- [ ] `npm run build` succeeds without errors +- [ ] Build output contains expected chunks (vendor-core, reports, data-entry) +- [ ] IIS deployment with single site works correctly +- [ ] API proxy routes correctly to both backends (8001, 8003) +- [ ] Production build works on Windows IIS +- [ ] Cache busting works (new builds force reload) + +### Error Handling +- [ ] Error boundary catches component errors +- [ ] Error boundary displays user-friendly message +- [ ] User can retry or navigate away from error +- [ ] Console logs error details for debugging +- [ ] Error in one module doesn't affect the other + +### Responsive Design +- [ ] Works on mobile (375px width) +- [ ] Works on tablet (768px width) +- [ ] Works on desktop (1920px width) +- [ ] Slide menu works on mobile +- [ ] Company/Period selectors work on mobile + +### Testing +- [ ] E2E tests pass for login flow +- [ ] E2E tests pass for Reports module navigation +- [ ] E2E tests pass for Data Entry module navigation +- [ ] E2E tests pass for module switching +- [ ] E2E tests verify error boundary isolation + +--- + +## Out of Scope + +The following are explicitly NOT included in this implementation: + +### Backend Changes +- No changes to `reports-app/backend/` (port 8001) +- No changes to `data-entry-app/backend/` (port 8003) +- Backends remain separate microservices + +### Shared Database +- Each backend keeps its own database (Oracle for Reports, SQLite for Data Entry) +- No database consolidation + +### API Consolidation +- APIs remain at separate ports (8001, 8003) +- No unified API gateway (using IIS/Vite proxy instead) + +### Telegram Bot +- Telegram bot remains in `reports-app/telegram-bot/` +- No changes to bot architecture + +### Advanced Features +- No server-side rendering (SSR) +- No progressive web app (PWA) features +- No offline mode +- No real-time updates (WebSockets) + +### Future Enhancements +- Module-level permissions (show/hide based on user role) +- Module analytics dashboard +- A/B testing framework +- Module versioning +- Micro-frontend migration (if team grows to 20+) + +--- + +## Risks and Mitigations + +| Risk | Likelihood | Impact | Mitigation | +|------|------------|--------|------------| +| **CSS conflicts between modules** | Medium | Medium | Use CSS modules or scoped styles; test thoroughly; maintain design token system from reports-app | +| **Large bundle size** | Medium | Medium | Implement aggressive code splitting; lazy load modules; use tree shaking; monitor with webpack-bundle-analyzer | +| **Error boundary not catching all errors** | Low | High | Test error scenarios thoroughly; add global error handler; log errors to monitoring service | +| **Deployment complexity on IIS** | Medium | High | Document IIS proxy configuration; create deployment scripts; test on staging first | +| **Store contamination between modules** | Low | High | Keep stores module-scoped; use namespaced modules; test isolation | +| **PrimeVue theme conflicts** | Low | Medium | Use single PrimeVue theme (saga-blue from reports-app); override in vendor CSS | +| **Breaking existing E2E tests** | High | Medium | Update test selectors; test both modules independently; add new tests for unified navigation | +| **Shared component changes breaking both modules** | Medium | High | Version shared components; add component tests; minimize changes to shared code | + +--- + +## Implementation Plan + +### Phase 1: Project Setup (0.5 days) + +**Tasks**: +1. Create directory structure in root (`.`) +2. Create `package.json` with merged dependencies +3. Create `vite.config.js` with dual proxy and lazy loading +4. Create `src/main.js` with PrimeVue setup +5. Create `.env.example` with environment variables +6. Copy `shared/frontend/` to `src/shared/` +7. Copy `reports-app/frontend/src/assets/css/` to `src/assets/css/` + +**Verification**: +- `npm install` succeeds +- `npm run dev` starts dev server on port 3000 +- No build errors + +### Phase 2: Module Migration (1 day) + +**Tasks**: +1. Create module structure (`modules/reports/`, `modules/data-entry/`) +2. Migrate Reports views to `modules/reports/views/` +3. Migrate Reports stores to `modules/reports/stores/` +4. Migrate Reports services, adapt API base URL to `/api/reports/` +5. Migrate Data Entry views to `modules/data-entry/views/` +6. Migrate Data Entry components to `modules/data-entry/components/` +7. Migrate Data Entry stores to `modules/data-entry/stores/` +8. Migrate Data Entry services, adapt API base URL to `/api/data-entry/` +9. Merge CSS from data-entry-app into main CSS system + +**Verification**: +- All views render without errors +- API calls route to correct backend +- No import errors + +### Phase 3: Routing & Navigation (0.5 days) + +**Tasks**: +1. Create unified router in `src/router/index.js` +2. Configure lazy loading for module layouts +3. Add authentication guard +4. Create `config/menu.js` with unified menu structure +5. Create `App.vue` with AppHeader and SlideMenu integration +6. Create `ReportsLayout.vue` with error boundary +7. Create `DataEntryLayout.vue` with error boundary +8. Create `ErrorBoundary.vue` component + +**Verification**: +- Navigation works between all routes +- Lazy loading chunks load correctly +- Error boundary catches and displays errors +- Menu highlights active route + +### Phase 4: Error Boundaries & Resilience (0.25 days) + +**Tasks**: +1. Test error boundary with intentional errors +2. Verify module isolation (error in one doesn't crash other) +3. Add global error handler +4. Test feature flags (enable/disable modules) +5. Add loading states for lazy-loaded routes + +**Verification**: +- Error boundary displays user-friendly message +- User can retry or navigate away +- Other module continues working +- Feature flags hide disabled modules + +### Phase 5: Build & Deployment (0.25 days) + +**Tasks**: +1. Run production build: `npm run build` +2. Verify bundle splitting (check `dist/assets/`) +3. Test production build locally: `npm run preview` +4. Create IIS web.config with URL rewrite rules +5. Deploy to staging IIS site +6. Test all routes and API calls on staging +7. Document deployment process + +**Verification**: +- Build succeeds without errors +- Separate chunks generated (vendor-core, reports, data-entry) +- IIS deployment works +- API proxy routes correctly +- All features work in production + +--- + +## Testing Strategy + +### Unit Tests +- Store actions and mutations +- Service API methods +- Utility functions +- Error boundary component + +### Integration Tests +- Router navigation +- Store integration with components +- API service integration +- Error boundary with child components + +### E2E Tests (Playwright) + +**Critical Paths**: +1. **Login Flow** + - Navigate to /login + - Enter credentials + - Verify redirect to /reports/dashboard + +2. **Reports Module Navigation** + - Navigate to each Reports view + - Verify data loads + - Test filters and actions + +3. **Data Entry Module Navigation** + - Navigate to receipts list + - Navigate to create receipt + - Verify form validation + +4. **Module Switching** + - Navigate from Reports to Data Entry + - Verify state persistence (company, period) + - Navigate back to Reports + +5. **Error Isolation** + - Trigger error in Reports module + - Verify Data Entry still works + - Retry error module + +6. **Logout** + - Logout from any module + - Verify redirect to login + - Verify stores cleared + +### Performance Tests +- Lighthouse audit (target: 90+ Performance) +- Bundle size analysis (webpack-bundle-analyzer) +- Load time measurement (initial load, module switching) + +--- + +## Rollback Plan + +### If Deployment Fails + +**Option 1: Keep Both Apps Running** (Zero Downtime) +- Leave existing `/roa2web/` and `/data-entry/` sites running +- Add new unified app at `/unified/` for testing +- Switch over when stable + +**Option 2: Quick Rollback** (15 minutes) +- Keep backup of current IIS configuration +- Keep backup of current builds in `dist-backup/` +- Restore IIS sites from backup +- Restore builds from backup + +### Git Strategy +- Create feature branch: `feature/unified-app-pragmatic-monolith` +- Tag last stable version before merge: `v1.0-pre-unified` +- Can revert to tag if needed: `git reset --hard v1.0-pre-unified` + +### Monitoring +- Check IIS logs: `C:\inetpub\logs\LogFiles\` +- Check application errors in browser console +- Monitor backend logs (both 8001 and 8003) +- Track user feedback in first 48 hours + +--- + +## Documentation Updates + +### Files to Create/Update + +1. **README.md** (in root directory) + - Project overview + - Setup instructions + - Development commands + - Deployment guide + - Architecture overview + +2. **CLAUDE.md** (root) + - Update architecture diagram + - Update deployment instructions + - Mark old apps as archived + - Document new root structure + +3. **DEPLOYMENT_GUIDE.md** + - Update IIS configuration + - Update build process + - Update URL structure + - Add rollback instructions + +4. **docs/ARCHITECTURE_SCHEMA.md** + - Update architecture diagrams + - Document module structure + - Add error boundary architecture + +5. **deployment/windows/README.md** + - Update deployment steps + - Update IIS configuration + - Update proxy rules + +--- + +## Post-Implementation Tasks + +### Archiving Old Apps + +After successful deployment and 1 week of stability: + +1. Archive old frontends: + ```bash + mv reports-app/frontend reports-app/frontend-archived + mv data-entry-app/frontend data-entry-app/frontend-archived + ``` + +2. Update start scripts to use root directory: + ```bash + # ./start-test.sh (update frontend path to root) + # ./start-data-entry.sh (update frontend path to root) + ``` + +3. Update CI/CD pipelines (if any) + +4. Document migration in CHANGELOG.md + +### Monitoring & Optimization + +**First Week**: +- Monitor error logs daily +- Track bundle load times +- Gather user feedback +- Fix critical bugs + +**First Month**: +- Optimize bundle sizes +- Add performance monitoring +- Consider further code splitting +- Evaluate feature flag usage + +--- + +## Dependencies on Other Work + +### Prerequisites +- None - can start immediately + +### Blocking +- No other work blocked by this + +### Nice to Have (Not Required) +- Updated E2E tests (can do after deployment) +- Performance monitoring setup (can add later) +- Analytics integration (can add later) + +--- + +## Success Metrics + +### Deployment Success +- โœ… Single IIS site running instead of 2 +- โœ… Single build command instead of 2 +- โœ… Zero downtime during deployment + +### User Experience +- โœ… 100% feature parity with old apps +- โœ… < 2s initial load time +- โœ… < 500ms module switching (cached) +- โœ… Zero user-reported bugs in first week + +### Technical +- โœ… Bundle size โ‰ค sum of old apps +- โœ… Error isolation working (test scenarios) +- โœ… All E2E tests passing +- โœ… Lighthouse score โ‰ฅ 90 + +--- + +## Open Questions + +1. **PrimeVue Theme Standardization**: Use `saga-blue` (reports-app) or `lara-light-blue` (data-entry-app)? + - **Recommendation**: Use `saga-blue` (reports-app is primary) + +2. **Feature Flag Storage**: Config file or environment variables? + - **Recommendation**: Config file for simplicity, env vars for production override + +3. **Module Activation Strategy**: All modules active by default or opt-in? + - **Recommendation**: All active by default (can disable via config) + +4. **Monitoring Solution**: Console logs only or add Sentry/similar? + - **Recommendation**: Console logs for MVP, add monitoring later + +5. **Progressive Enhancement**: Load Reports first (most used) or parallel? + - **Recommendation**: Load on-demand (lazy loading), whichever user navigates to first + +--- + +## Estimated Complexity + +**Medium Complexity** - Justification: + +**Factors Increasing Complexity**: +- Merging two apps with different structures +- Ensuring error isolation between modules +- CSS conflicts and PrimeVue theme differences +- IIS proxy configuration complexity +- Testing both modules thoroughly + +**Factors Decreasing Complexity**: +- No backend changes required +- Shared components already exist +- Clear architectural pattern (pragmatic monolith) +- Lazy loading well-supported by Vue Router +- Both apps use same tech stack (Vue 3, PrimeVue) + +**Time Estimate**: 2.5 days (as per implementation plan) + +--- + +## References + +### Related Documents +- `IMPLEMENTATION_PLAN_UNIFIED_APP.md` - Initial plan (this spec expands on it) +- `CLAUDE.md` - Project documentation (update after implementation) +- `docs/ONBOARDING_CSS.md` - CSS system guide +- `docs/CSS_PATTERNS.md` - Available CSS patterns +- `docs/ARCHITECTURE_SCHEMA.md` - Current architecture (update after) + +### Key Files to Reference During Implementation +- `reports-app/frontend/vite.config.js` - Proxy config, build settings (reference for new root `vite.config.js`) +- `reports-app/frontend/src/router/index.js` - Router patterns (reference for new `src/router/index.js`) +- `reports-app/frontend/src/App.vue` - AppHeader/SlideMenu integration (reference for new `src/App.vue`) +- `data-entry-app/frontend/src/App.vue` - Alternative integration pattern +- `shared/frontend/components/layout/AppHeader.vue` - Header API (copy to `src/shared/components/layout/`) +- `shared/frontend/components/layout/SlideMenu.vue` - Menu API (copy to `src/shared/components/layout/`) + +--- + +## Handover Notes + +This specification is **implementation-ready**. All technical decisions have been made. The implementation plan provides a clear path with verification steps at each phase. + +**Critical Files to Create First** (in root directory): +1. `package.json` - Merged dependencies +2. `vite.config.js` - Dual proxy config +3. `src/router/index.js` - Unified router with lazy loading +4. `src/shared/components/ErrorBoundary.vue` - Error isolation + +**After Implementation**: +- Archive old frontends after 1 week of stability +- Update all documentation (CLAUDE.md, DEPLOYMENT_GUIDE.md) +- Consider adding monitoring/analytics +- Optimize bundle sizes based on real usage + +--- + +**Specification Version**: 1.0 +**Created**: 2025-12-22 +**Status**: Ready for Implementation +**Estimated Effort**: 2.5 days diff --git a/.auto-build-data/specs/unified-app/status.json b/.auto-build-data/specs/unified-app/status.json new file mode 100644 index 0000000..44acf04 --- /dev/null +++ b/.auto-build-data/specs/unified-app/status.json @@ -0,0 +1,30 @@ +{ + "feature": "unified-app", + "status": "SPEC_COMPLETE", + "created": "2025-12-22T01:09:00Z", + "updated": "2025-12-22T01:13:00Z", + "complexity": "medium", + "estimated_effort": "2.5 days", + "history": [ + { + "status": "SPEC_DRAFT", + "at": "2025-12-22T01:09:00Z" + }, + { + "status": "SPEC_COMPLETE", + "at": "2025-12-22T01:13:00Z" + } + ], + "files": { + "spec": "spec.md", + "summary": "SUMMARY.md", + "critical_files": "critical-files.md", + "migration_checklist": "MIGRATION_CHECKLIST.md" + }, + "stats": { + "files_to_create": 15, + "files_to_migrate": 20, + "css_files_to_copy": 30, + "total_files_affected": 65 + } +}