131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# 01 — Product Overview
|
||
|
||
## What is QuoteForge
|
||
|
||
A corporate server configuration and quotation tool.
|
||
Operates in **strict local-first** mode: all user operations go through local SQLite; MariaDB is used only by synchronization and dedicated setup/migration tooling.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
### For Users
|
||
- Mobile-first interface — works comfortably on phones and tablets
|
||
- Server configurator — step-by-step component selection
|
||
- Automatic price calculation — based on pricelists from local cache
|
||
- CSV export — ready-to-use specifications for clients
|
||
- Configuration history — versioned snapshots with rollback support
|
||
- Full offline operation — continue working without network, sync later
|
||
- Guarded synchronization — sync is blocked by preflight check if local schema is not ready
|
||
|
||
### Local Client Security Model
|
||
|
||
QuoteForge is currently a **single-user thick client** bound to `localhost`.
|
||
|
||
- The local HTTP/UI layer is not treated as a multi-user security boundary.
|
||
- RBAC is not part of the active product contract for the local client.
|
||
- The authoritative authentication boundary is the remote sync server and its DB credentials captured during setup.
|
||
- If the app is ever exposed beyond `localhost`, auth/RBAC must be reintroduced as an enforced perimeter before release.
|
||
|
||
### Price Freshness Indicators
|
||
|
||
| Color | Status | Condition |
|
||
|-------|--------|-----------|
|
||
| Green | Fresh | < 30 days, ≥ 3 sources |
|
||
| Yellow | Normal | 30–60 days |
|
||
| Orange | Aging | 60–90 days |
|
||
| Red | Stale | > 90 days or no data |
|
||
|
||
---
|
||
|
||
## Tech Stack
|
||
|
||
| Layer | Stack |
|
||
|-------|-------|
|
||
| Backend | Go 1.22+, Gin, GORM |
|
||
| Frontend | HTML, Tailwind CSS, htmx |
|
||
| Local DB | SQLite (`qfs.db`) |
|
||
| Server DB | MariaDB 11+ (sync transport only for app runtime) |
|
||
| Export | encoding/csv, excelize (XLSX) |
|
||
|
||
---
|
||
|
||
## Product Scope
|
||
|
||
**In scope:**
|
||
- Component configurator and quotation calculation
|
||
- Projects and configurations
|
||
- Read-only pricelist viewing from local cache
|
||
- Sync (pull components/pricelists, push local changes)
|
||
|
||
**Out of scope (removed intentionally — do not restore):**
|
||
- Admin pricing UI/API
|
||
- Stock import
|
||
- Alerts
|
||
- Cron/importer utilities
|
||
|
||
---
|
||
|
||
## Repository Structure
|
||
|
||
```
|
||
quoteforge/
|
||
├── cmd/
|
||
│ ├── qfs/main.go # HTTP server entry point
|
||
│ ├── migrate/ # Migration tool
|
||
│ └── migrate_ops_projects/ # OPS project migrator
|
||
├── internal/
|
||
│ ├── appmeta/ # App version metadata
|
||
│ ├── appstate/ # State management, backup
|
||
│ ├── article/ # Article generation
|
||
│ ├── config/ # Config parsing
|
||
│ ├── db/ # DB initialization
|
||
│ ├── handlers/ # HTTP handlers
|
||
│ ├── localdb/ # SQLite layer
|
||
│ ├── middleware/ # Auth, CORS, etc.
|
||
│ ├── models/ # GORM models
|
||
│ ├── repository/ # Repository layer
|
||
│ └── services/ # Business logic
|
||
├── web/
|
||
│ ├── templates/ # HTML templates + partials
|
||
│ └── static/ # CSS, JS, assets
|
||
├── migrations/ # SQL migration files (30+)
|
||
├── bible/ # Architectural documentation (this section)
|
||
├── releases/memory/ # Per-version changelogs
|
||
├── config.example.yaml # Config template (the only one in repo)
|
||
└── go.mod
|
||
```
|
||
|
||
---
|
||
|
||
## Integration with Existing DB
|
||
|
||
QuoteForge integrates with the existing `RFQ_LOG` database.
|
||
|
||
Hard boundary:
|
||
|
||
- normal runtime HTTP handlers, UI flows, pricing, export, BOM resolution, and project/config CRUD must use SQLite only;
|
||
- MariaDB access is allowed only inside `internal/services/sync/*` and dedicated setup/migration tools under `cmd/`;
|
||
- any new direct MariaDB query in non-sync runtime code is an architectural violation.
|
||
|
||
**Read-only:**
|
||
- `lot` — component catalog
|
||
- `qt_lot_metadata` — extended component data
|
||
- `qt_categories` — categories
|
||
- `qt_pricelists`, `qt_pricelist_items` — pricelists
|
||
- `stock_log` — stock quantities consumed during sync enrichment
|
||
- `qt_partnumber_books`, `qt_partnumber_book_items` — partnumber book snapshots consumed during sync pull
|
||
|
||
**Read + Write:**
|
||
- `qt_configurations` — configurations
|
||
- `qt_projects` — projects
|
||
|
||
**Sync service tables:**
|
||
- `qt_client_schema_state` — applied migrations state and operational client status per device (`username + hostname`)
|
||
Fields written by QuoteForge:
|
||
`app_version`, `last_sync_at`, `last_sync_status`,
|
||
`pending_changes_count`, `pending_errors_count`, `configurations_count`, `projects_count`,
|
||
`estimate_pricelist_version`, `warehouse_pricelist_version`, `competitor_pricelist_version`,
|
||
`last_sync_error_code`, `last_sync_error_text`, `last_checked_at`, `updated_at`
|
||
- `qt_pricelist_sync_status` — pricelist sync status
|