347 lines
10 KiB
Markdown
347 lines
10 KiB
Markdown
# 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
|