99 lines
4.3 KiB
Markdown
99 lines
4.3 KiB
Markdown
# AGENTS.md — Web App Project Rules
|
|
|
|
## Tech Stack
|
|
- Frontend: Next.js 15, React 19, TypeScript 5
|
|
- Styling: Tailwind CSS v3.4, Lucide React (Icons)
|
|
- Backend: Python 3.14, FastAPI, Uvicorn
|
|
- Database: SQLite (SQLAlchemy) + Dexie (IndexedDB pentru offline-first)
|
|
- AI & Vision: Google Gemini 2.0 (Vision), Tesseract.js (Local OCR)
|
|
- Infrastructure: Docker, Caddy (Automatic SSL Reverse Proxy)
|
|
- Security: JWT (python-jose), LDAP (Enterprise Integration)
|
|
|
|
## Code Quality
|
|
- Keep cyclomatic complexity under 10 per function
|
|
- Aim for files under 300 lines
|
|
- All files must follow single responsibility principle (one clear purpose per module)
|
|
- Extract complex logic into reusable utilities/services
|
|
|
|
## Testing
|
|
|
|
### Standard Testing (Ongoing)
|
|
- Write unit tests for all utility functions
|
|
- Minimum 80% coverage on new code
|
|
- Use Vitest for unit tests
|
|
|
|
### AI-Friendly Refactoring Testing Strategy (v1.10.16+)
|
|
**Scope:** Full test coverage before refactoring to prevent UI/functionality regression.
|
|
|
|
**Backend Testing (Pytest)**
|
|
- Target: 85%+ coverage (unit + integration tests)
|
|
- Structure: `backend/tests/` with suites for routers, models, auth, AI pipeline
|
|
- Coverage tools: `pytest backend/tests/ --cov=backend --cov-report=html`
|
|
- Test types: Unit (functions), Integration (full API workflows), Fixtures (mocked auth, in-memory DB)
|
|
|
|
**Frontend Testing (Vitest)**
|
|
- Target: 80%+ coverage (components, hooks, snapshots)
|
|
- Structure: `frontend/tests/` with component tests, hook tests, integration workflows
|
|
- Coverage tools: `npm test -- --coverage`
|
|
- Test types: Component rendering, Hook state/side effects, Snapshot tests for UI layouts
|
|
|
|
**E2E Testing (Playwright)**
|
|
- Target: Critical user workflows automated
|
|
- Workflows: Login, Scan → Match → Stock adjustment, New Item (AI), Admin config, Offline sync
|
|
- Runtime: ~30 min total
|
|
- Command: `npx playwright test`
|
|
|
|
**Test-First Approach**
|
|
- All tests written and passing BEFORE refactoring any code
|
|
- Tests serve as gating condition: no code changes if tests fail
|
|
- Functional preservation: Zero behavior changes post-refactor
|
|
- Regression prevention: Manual checklist + automated tests catch UI breakage
|
|
|
|
## Security
|
|
- Store all secrets in inventory.env — never hardcode credentials
|
|
- Never log API keys, tokens or passwords
|
|
- Validate all user input before processing
|
|
|
|
## Git Conventions
|
|
- Use conventional commits (feat:, fix:, docs:, refactor:, test:, etc.)
|
|
- Keep PRs under 400 lines of diff when possible
|
|
- Refactoring commits: `refactor: split {module} into smaller modules`
|
|
- Testing commits: `test: add {suite} coverage for {module}`
|
|
- All commits must have passing test suite before merge
|
|
|
|
## Refactoring Guidelines (AI-Friendly Modularity)
|
|
|
|
### Refactoring Principles
|
|
- **Target:** Break monolithic files into focused modules (<300 lines each)
|
|
- **Priority Order:** Backend routers → Components → Pages
|
|
- **No Behavior Changes:** Every refactor must pass 100% of existing tests
|
|
- **Gating Rule:** No refactor commit unless all tests pass (pre + post)
|
|
- **Regression Prevention:** Manual checklist + automated tests validate UI integrity
|
|
|
|
### Refactoring Process
|
|
1. Ensure full test coverage exists (backend 85%, frontend 80%)
|
|
2. Run complete test suite (all tests PASS)
|
|
3. Refactor module: split into smaller files/services
|
|
4. Run test suite again (all tests PASS)
|
|
5. Manual browser validation: UI unchanged, all buttons/features work
|
|
6. Commit with test results in message body
|
|
7. Move to next module
|
|
|
|
### Module Extraction Patterns
|
|
- **Backend Routers:** Split into router (endpoints only) + service (business logic) + validators (input validation)
|
|
- **Components:** Split into orchestrator component + sub-components + custom hooks for state/logic
|
|
- **Pages:** Extract page logic into custom hooks, move forms into separate components
|
|
- **Utilities:** Consolidate repeated logic into `lib/` or `services/` modules
|
|
|
|
### Validation Checklist (Post-Refactor)
|
|
- [ ] All pytest tests passing (backend coverage 85%+)
|
|
- [ ] All vitest tests passing (frontend coverage 80%+)
|
|
- [ ] All e2e workflows passing (Playwright)
|
|
- [ ] Login works (LDAP + local)
|
|
- [ ] Scanner functional (scan → match → stock adjustment)
|
|
- [ ] AI extraction working (new item → AI popup → validation)
|
|
- [ ] Admin page responsive and functional
|
|
- [ ] No console errors in browser
|
|
- [ ] Mobile responsive (320px, 768px, 1024px+ viewports)
|
|
- [ ] Keyboard navigation works (focus indicators visible)
|