67b0082df0
- Simplify CLAUDE.md from ~460 to ~145 lines with imports - Add Theme System section to css-design-system.md (3 modes: auto/light/dark) - Document theme toggle UI, localStorage persistence, CSS priority order - Add paths: frontmatter to authentication.md and company-period.md - Update DESIGN_TOKENS.md Dark Mode section with toggle documentation - Clean auto-build-memory.md header (remove non-existent auto-sync reference) - Remove non-existent plugin from settings.json 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
145 lines
4.6 KiB
Markdown
145 lines
4.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**ROA2WEB** - Modern ERP Application with ultrathin monolith architecture:
|
|
- **Reports Module** (`backend/modules/reports/`) - Read-only reports from Oracle
|
|
- **Data Entry Module** (`backend/modules/data_entry/`) - Data input with approval workflow
|
|
- **Telegram Bot Module** (`backend/modules/telegram/`) - Telegram bot integration
|
|
|
|
**Main Branch**: `main` | **Setup & Commands**: See `README.md`
|
|
|
|
---
|
|
|
|
## Module-Specific Instructions
|
|
|
|
> **IMPORTANT**: Read module documentation FIRST before working on a module!
|
|
|
|
| Module | Documentation | Key Points |
|
|
|--------|--------------|------------|
|
|
| **Data Entry** | `docs/data-entry/DATA-ENTRY-MODULE.md` | SQLModel, SQLite, workflow states |
|
|
| **Reports** | This file + `README.md` | Oracle read-only, caching |
|
|
| **Telegram** | `docs/telegram/README.md` | Bot commands, formatting |
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### Architecture
|
|
See `docs/ARCHITECTURE-DECISIONS.md` for:
|
|
- Single worker (`--workers 1`) - required for Telegram bot
|
|
- Ultrathin monolith rationale
|
|
- IIS deployment strategy
|
|
|
|
### Starting Services
|
|
```bash
|
|
./start-prod.sh # Backend :8001 + Frontend :3000
|
|
./ssh-tunnel-prod.sh # Oracle DB tunnel (REQUIRED on Linux)
|
|
./status.sh # Check services
|
|
```
|
|
|
|
### Database
|
|
- **Schema**: `CONTAFIN_ORACLE`
|
|
- **Connection**: SSH tunnel required (Linux dev)
|
|
- **Env**: `backend/.env` (see `backend/ENV-SETUP.md`)
|
|
|
|
---
|
|
|
|
## Key Rules (ALWAYS FOLLOW)
|
|
|
|
### Frontend Development
|
|
**Before writing CSS**: Read `docs/ONBOARDING_CSS.md` (5 min)
|
|
|
|
- Use design tokens: `var(--color-primary)` not `#2563eb`
|
|
- Use shared CSS from `src/assets/css/` - NEVER duplicate
|
|
- Check `docs/CSS_PATTERNS.md` for existing patterns
|
|
- **Theme toggle**: App has 3 modes (auto/light/dark) - test BOTH themes!
|
|
|
|
**Tables**:
|
|
- Use separate columns (Debit | Credit, not stacked)
|
|
- Filter buttons on separate row below filters
|
|
- Export ALL data, not just current page
|
|
|
|
### Backend Development
|
|
- Place logic in **services**, not routers
|
|
- Use `@cached` decorator for ALL database queries
|
|
- Cache schema lookups separately (24h TTL)
|
|
|
|
**Service pattern**:
|
|
```python
|
|
from app.cache.decorators import cached
|
|
|
|
class YourService:
|
|
@staticmethod
|
|
@cached(cache_type='your_data', key_params=['company_id', 'username'])
|
|
async def get_data(company_id: int, username: str):
|
|
# Query Oracle here
|
|
```
|
|
|
|
### Authentication
|
|
- JWT structure: `username`, `user_id`, `companies[]`, `permissions[]`, `exp`, `iat`, `type`
|
|
- Middleware: `shared/auth/middleware.py` (auto-injects `request.state.user`)
|
|
- Rate limiting: 5 req/5 min for `/auth/*`
|
|
|
|
---
|
|
|
|
## Documentation Index
|
|
|
|
| Topic | File | Description |
|
|
|-------|------|-------------|
|
|
| **Setup** | `README.md` | Commands, testing, deployment |
|
|
| **Architecture** | `docs/ARCHITECTURE-DECISIONS.md` | Critical decisions |
|
|
| **CSS Quick Start** | `docs/ONBOARDING_CSS.md` | START HERE for frontend |
|
|
| **CSS Patterns** | `docs/CSS_PATTERNS.md` | Cards, forms, buttons, tables |
|
|
| **Design Tokens** | `docs/DESIGN_TOKENS.md` | Colors, spacing, dark mode |
|
|
| **Data Entry** | `docs/data-entry/DATA-ENTRY-MODULE.md` | SQLModel, workflow |
|
|
| **Telegram** | `docs/telegram/README.md` | Bot development |
|
|
| **Deployment** | `deployment/linux/README.md` | Deploy from LXC |
|
|
|
|
---
|
|
|
|
## Learned Patterns & Known Issues
|
|
|
|
> **Patterns/Gotchas from previous sessions**: Auto-loaded from `.claude/rules/auto-build-memory.md`
|
|
|
|
### Known Issues & Fixes
|
|
|
|
#### Mobile File Upload ERR_NETWORK (Android/iOS)
|
|
**Problem**: File uploads fail with `ERR_NETWORK` (status 0) on mobile browsers.
|
|
|
|
**Cause**: Android/iOS browsers invalidate File object references after accessing properties due to SnapshotState in W3C File API. See [Chromium Bug #40703873](https://issues.chromium.org/40703873).
|
|
|
|
**Solution**: Clone the file into memory immediately after selection:
|
|
```javascript
|
|
const handleFile = async (file) => {
|
|
// FIX: Clone file to memory to avoid SnapshotState invalidation
|
|
const arrayBuffer = await file.arrayBuffer()
|
|
const clonedFile = new File([arrayBuffer], file.name, {
|
|
type: file.type,
|
|
lastModified: file.lastModified
|
|
})
|
|
selectedFile.value = clonedFile
|
|
}
|
|
```
|
|
|
|
**Applied in**: `src/modules/data-entry/components/ocr/OCRUploadZone.vue`
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
- Never commit `.env` files
|
|
- SSH keys in `ssh-tunnel/secrets/` (gitignored)
|
|
- Rate limiting in auth middleware
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
**Backend**: FastAPI, python-oracledb, JWT, Pydantic
|
|
**Frontend**: Vue.js 3, PrimeVue, Pinia, Vite
|
|
**Telegram**: python-telegram-bot, SQLite, httpx
|
|
**Infra**: Oracle DB, SSH Tunnel, IIS (Windows prod)
|