Add quote bridge and quote handoff flow
This commit is contained in:
+123
-124
@@ -1,147 +1,146 @@
|
||||
# Product App - Modular Flask Application
|
||||
# Product Finder Application
|
||||
|
||||
## 🏗️ Structure
|
||||
## 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
|
||||
|
||||
```
|
||||
product_app/
|
||||
├── app.py # Main application file
|
||||
├── passenger_wsgi.py # Passenger WSGI entry point for production
|
||||
├── requirements.txt # Python dependencies
|
||||
├── blueprints/ # Modular routes organized by feature
|
||||
│ ├── __init__.py
|
||||
│ ├── auth.py # Login/logout/session management
|
||||
│ └── users.py # User CRUD operations
|
||||
├── templates/ # HTML templates
|
||||
│ ├── login.html
|
||||
│ └── user_manager.html
|
||||
└── data/ # Data storage
|
||||
└── users.json # User accounts with hashed passwords
|
||||
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
|
||||
```
|
||||
|
||||
## 🎯 Features Implemented
|
||||
## Implemented Features
|
||||
|
||||
### ✅ Authentication System (blueprints/auth.py)
|
||||
- Login with username/password
|
||||
- Session management
|
||||
- Password hashing (PBKDF2-SHA256, 1M iterations)
|
||||
- Login required decorator
|
||||
- Permission checking: `can_user('manage_users')`
|
||||
- User status checking (active/inactive)
|
||||
### 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 (blueprints/users.py)
|
||||
- View all users
|
||||
- Add new users
|
||||
### User Management
|
||||
- List users
|
||||
- Create users
|
||||
- Delete users
|
||||
- Toggle active/inactive status
|
||||
- Change passwords (requires admin verification)
|
||||
- Location-based access control
|
||||
- Permission system (manage_users, create_quotes, etc.)
|
||||
- Download users as JSON
|
||||
- Toggle active status
|
||||
- Change passwords
|
||||
- Download user data JSON
|
||||
|
||||
## 🔐 Default Login
|
||||
### 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`
|
||||
|
||||
- **Username:** `Master`
|
||||
- **Password:** `Master`
|
||||
- **Permissions:** Full access (manage_users)
|
||||
### 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
|
||||
|
||||
## 🚀 Local Testing
|
||||
### 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 product_app
|
||||
python app.py
|
||||
cd app
|
||||
../.venv/bin/python app.py
|
||||
```
|
||||
|
||||
Visit: http://localhost:8080/
|
||||
Open:
|
||||
- `http://127.0.0.1:8080/`
|
||||
- `http://127.0.0.1:8080/quiz/`
|
||||
|
||||
## Routes
|
||||
## Data Update Workflow
|
||||
|
||||
### Main Routes
|
||||
- `/` - Home (redirects to login if not authenticated)
|
||||
- `/test` - Test page to verify app is running
|
||||
If product source data changes, use the VS Code tasks from the repository root:
|
||||
|
||||
### Authentication Routes (auth_bp)
|
||||
- `/login` - Login page
|
||||
- `/logout` - Logout
|
||||
- `/api/login` - POST: Login API
|
||||
- `/api/session` - GET: Current session info
|
||||
- `Update Data Files from CSV`
|
||||
- `Generate Bitwise Data`
|
||||
- `Process All Data`
|
||||
|
||||
### User Management Routes (users_bp)
|
||||
- `/users/` - User management page
|
||||
- `/users/api` - GET: List all users, POST: Add user
|
||||
- `/users/api/<index>` - DELETE: Delete user
|
||||
- `/users/api/<index>/active` - PATCH: Toggle active status
|
||||
- `/users/api/<index>/change-password` - POST: Change password
|
||||
- `/users/api/download` - GET: Download users.json
|
||||
These regenerate the JSON files consumed by the quiz and filtering logic.
|
||||
|
||||
## 📦 Production Deployment
|
||||
## Current Limitations
|
||||
|
||||
### Upload to Server: `/home/bmdwtjuw/product-finder/`
|
||||
- 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.
|
||||
|
||||
Files to upload:
|
||||
- `app.py`
|
||||
- `passenger_wsgi.py` (or just use existing)
|
||||
- `blueprints/` (entire folder)
|
||||
- `__init__.py`
|
||||
- `auth.py`
|
||||
- `users.py`
|
||||
- `templates/` (entire folder)
|
||||
- `login.html`
|
||||
- `user_manager.html`
|
||||
- `data/users.json`
|
||||
## Recommended Next Work
|
||||
|
||||
### Control Panel Settings
|
||||
|
||||
- **Application startup file:** `passenger_wsgi.py` (or `app.py`)
|
||||
- **Application Entry point:** `application`
|
||||
- **Python version:** 3.13.11
|
||||
|
||||
### Test After Deployment:
|
||||
1. https://columbiawindows.com/product-finder/test
|
||||
2. https://columbiawindows.com/product-finder/login
|
||||
3. Login with Master/Master
|
||||
4. Test user management
|
||||
|
||||
## 🔧 Adding New Features
|
||||
|
||||
### Create a New Blueprint
|
||||
|
||||
1. Create `blueprints/your_feature.py`:
|
||||
|
||||
```python
|
||||
from flask import Blueprint, render_template
|
||||
from blueprints.auth import login_required, can_user
|
||||
|
||||
your_feature_bp = Blueprint('your_feature', __name__, url_prefix='/your-feature')
|
||||
|
||||
@your_feature_bp.route('/')
|
||||
@login_required
|
||||
def index():
|
||||
return render_template('your_feature.html')
|
||||
```
|
||||
|
||||
2. Register in `app.py`:
|
||||
|
||||
```python
|
||||
from blueprints.your_feature import your_feature_bp
|
||||
app.register_blueprint(your_feature_bp)
|
||||
```
|
||||
|
||||
3. Create `templates/your_feature.html`
|
||||
|
||||
4. Test locally, then upload to server
|
||||
|
||||
## 📝 Benefits of Blueprint Structure
|
||||
|
||||
✅ **Separation of Concerns:** Each feature in its own file
|
||||
✅ **Easy to Maintain:** Find and edit specific features quickly
|
||||
✅ **Scalable:** Add new features without touching existing code
|
||||
✅ **Testable:** Each blueprint can be tested independently
|
||||
✅ **Reusable:** Share decorators (login_required, permission_required) across blueprints
|
||||
|
||||
## 🛠️ Next Steps
|
||||
|
||||
- Add more blueprints for other features (quotes, products, etc.)
|
||||
- Add more templates as needed
|
||||
- Extend permission system
|
||||
- Add location selection page
|
||||
- Add the main product finder quiz
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user