chore: Migrate auto-build specs and memory for team sharing
This commit is contained in:
346
.auto-build/specs/unified-app/SUMMARY.md
Normal file
346
.auto-build/specs/unified-app/SUMMARY.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user