147 lines
4.7 KiB
Markdown
147 lines
4.7 KiB
Markdown
# Product Finder Application
|
|
|
|
## Overview
|
|
|
|
This folder contains the active Flask application for the Product Finder project.
|
|
The app is structured around blueprints and serves a guided product-selection flow,
|
|
admin tooling, and image preview APIs from the same codebase.
|
|
|
|
## Current Architecture
|
|
|
|
```
|
|
app/
|
|
├── app.py # Flask app entry point and blueprint registration
|
|
├── config.py # Backend/config toggles
|
|
├── data_access.py # Chooses JSON or SQLite backend
|
|
├── data_access_json.py # JSON-backed data operations
|
|
├── data_access_sqlite.py # SQLite-backed data operations
|
|
├── models.py # SQLAlchemy models for SQLite mode
|
|
├── blueprints/
|
|
│ ├── auth.py # Login, logout, session, location selection
|
|
│ ├── users.py # User CRUD and password management
|
|
│ ├── products.py # Quiz pages, product APIs, admin pages
|
|
│ └── canvas.py # Layered image fallback API
|
|
├── static/
|
|
│ ├── css/styles.css # Main application styles
|
|
│ ├── js/script.js # Quiz flow, URL state, search, previews
|
|
│ └── images/ # Product and layered image assets
|
|
├── templates/ # Flask templates
|
|
└── data/ # JSON data files used by the app
|
|
```
|
|
|
|
## Implemented Features
|
|
|
|
### Authentication and Session Flow
|
|
- Username/password login
|
|
- Session-backed authentication
|
|
- Active/inactive user checks
|
|
- Multi-location session support with location selection
|
|
- Permission checks via `can_user(...)`
|
|
|
|
### User Management
|
|
- List users
|
|
- Create users
|
|
- Delete users
|
|
- Toggle active status
|
|
- Change passwords
|
|
- Download user data JSON
|
|
|
|
### Product Finder
|
|
- Quiz flow served at `/quiz/`
|
|
- URL-based state restoration with query params:
|
|
- `b` for bitwise state
|
|
- `q` for current question/results state
|
|
- `p` for direct product links
|
|
- Product results grid with clickable product cards
|
|
- Product detail page with configuration controls
|
|
- Share buttons for results and product-detail URLs
|
|
- Browser back/forward support via `popstate`
|
|
|
|
### Product Management and Search
|
|
- Advanced search page
|
|
- Product listing page with search and pagination API
|
|
- Product manager page
|
|
- Product CRUD API endpoints
|
|
- Product attributes API endpoint
|
|
|
|
### Image Systems
|
|
- Flat-image preview support
|
|
- Static layered-image support
|
|
- Canvas API fallback system for hierarchical image lookup
|
|
- Layer transforms for flipped/mirrored previews where configured
|
|
|
|
### Data Backends
|
|
- JSON backend is the current default
|
|
- SQLite backend is supported behind `USE_DATABASE = True` in `config.py`
|
|
- Data-access calls are routed through `data_access.py`
|
|
|
|
## Important Routes
|
|
|
|
### App-Level Routes
|
|
- `/` - Authenticated home page
|
|
- `/test` - Basic app health page
|
|
- `/init-db` - Create SQLite tables when database mode is enabled
|
|
|
|
### Auth Routes
|
|
- `/login`
|
|
- `/select-location`
|
|
- `/api/login`
|
|
- `/api/select-location`
|
|
- `/api/session`
|
|
- `/logout`
|
|
|
|
### Product Routes
|
|
- `/quiz/`
|
|
- `/quiz/index`
|
|
- `/quiz/advanced-search`
|
|
- `/quiz/list`
|
|
- `/quiz/manage`
|
|
- `/quiz/product/<product_code>`
|
|
- `/quiz/api/products`
|
|
- `/quiz/api/products/search`
|
|
- `/quiz/api/products/<product_code>`
|
|
- `/quiz/api/product-attributes`
|
|
|
|
### Canvas API Routes
|
|
- `/api/canvas/<product_code>/<layer>`
|
|
- `/api/canvas/<product_code>/info`
|
|
- `/api/canvas/test`
|
|
|
|
## Local Development
|
|
|
|
From the repository root:
|
|
|
|
```bash
|
|
cd app
|
|
../.venv/bin/python app.py
|
|
```
|
|
|
|
Open:
|
|
- `http://127.0.0.1:8080/`
|
|
- `http://127.0.0.1:8080/quiz/`
|
|
|
|
## Data Update Workflow
|
|
|
|
If product source data changes, use the VS Code tasks from the repository root:
|
|
|
|
- `Update Data Files from CSV`
|
|
- `Generate Bitwise Data`
|
|
- `Process All Data`
|
|
|
|
These regenerate the JSON files consumed by the quiz and filtering logic.
|
|
|
|
## Current Limitations
|
|
|
|
- Generic conditional-question evaluation is not fully implemented in the frontend.
|
|
The current flow works with the generated navigation structure and a small amount
|
|
of hardcoded branching, but it does not yet use a reusable `resolveNextQuestion`
|
|
style engine for all conditional prompts.
|
|
- SQLite support exists, but the project currently runs in JSON mode by default.
|
|
- There is no automated test suite in this repository yet; validation is currently manual.
|
|
|
|
## Recommended Next Work
|
|
|
|
1. Finish generic conditional navigation so `conditional` metadata in `navigation.json` is evaluated uniformly.
|
|
2. Add smoke tests for login, quiz state restoration, and product detail deep links.
|
|
3. Decide whether SQLite should remain optional or become the default backend.
|