132 lines
3.9 KiB
Markdown
132 lines
3.9 KiB
Markdown
# Face Attendance
|
|
|
|
Face Attendance is a modern Flask application for managing attendance with face recognition. It includes staff authentication, role-based authorization, person enrollment, a webcam kiosk, attendance reporting, database migrations, and a responsive English UI.
|
|
|
|
## Features
|
|
|
|
- Application factory pattern with modular Blueprints.
|
|
- Admin-created staff accounts with `admin`, `operator`, and `viewer` roles.
|
|
- Secure login/logout with Flask-Login and Werkzeug password hashing.
|
|
- CSRF-protected forms and secure session/cookie defaults.
|
|
- Person enrollment with one to four face reference images.
|
|
- Webcam-based recognition kiosk for check-in and check-out events.
|
|
- Attendance reports with person, timestamp, source, confidence, and staff user.
|
|
- SQLAlchemy models with Flask-Migrate/Alembic migrations.
|
|
- Pytest coverage for authentication, roles, and attendance behavior.
|
|
- Modern Bootstrap-based UI with an English welcome page.
|
|
|
|
## Roles
|
|
|
|
| Role | Permissions |
|
|
| --- | --- |
|
|
| `admin` | Manage staff accounts, enroll people, use the kiosk, and view reports. |
|
|
| `operator` | Enroll people, use the kiosk, and view reports. |
|
|
| `viewer` | View people and attendance reports only. |
|
|
|
|
Only admins can create staff accounts.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11 or 3.12 is recommended for production.
|
|
- Native build prerequisites for `face-recognition` and `dlib`.
|
|
- SQLite for local development, or PostgreSQL/MySQL for production.
|
|
- A production WSGI server such as Gunicorn on Linux or Waitress on Windows.
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
app/
|
|
__init__.py Application factory
|
|
config.py Environment-based configuration
|
|
extensions.py Flask extensions
|
|
auth/ Login/logout
|
|
admin/ Staff account management
|
|
attendance/ Kiosk and attendance reports
|
|
people/ Person enrollment and profiles
|
|
recognition/ Recognition API routes
|
|
models/ SQLAlchemy models
|
|
services/ Business logic
|
|
templates/ Jinja templates
|
|
static/ CSS, JS, and images
|
|
migrations/ Alembic migrations
|
|
tests/ Pytest suite
|
|
wsgi.py WSGI entrypoint
|
|
```
|
|
|
|
## Setup
|
|
|
|
```powershell
|
|
py -3.12 -m venv .venv
|
|
.\.venv\Scripts\Activate.ps1
|
|
pip install -r requirements.txt
|
|
Copy-Item .env.example .env
|
|
```
|
|
|
|
Edit `.env` before running the app.
|
|
|
|
```env
|
|
APP_ENV=development
|
|
SECRET_KEY=replace-with-a-long-random-secret
|
|
DATABASE_URL=sqlite:///instance/face_attendance.sqlite3
|
|
FACE_MATCH_TOLERANCE=0.55
|
|
MAX_CONTENT_LENGTH=8388608
|
|
```
|
|
|
|
## Database
|
|
|
|
Apply migrations:
|
|
|
|
```powershell
|
|
$env:FLASK_APP = "wsgi:app"
|
|
flask db upgrade
|
|
```
|
|
|
|
Create the first admin account:
|
|
|
|
```powershell
|
|
flask create-admin
|
|
```
|
|
|
|
## Run Locally
|
|
|
|
```powershell
|
|
$env:FLASK_APP = "wsgi:app"
|
|
flask run
|
|
```
|
|
|
|
Open `http://127.0.0.1:5000`.
|
|
|
|
## Tests
|
|
|
|
```powershell
|
|
pytest
|
|
```
|
|
|
|
The test suite uses an in-memory SQLite database and disables CSRF only for test requests.
|
|
|
|
## Production Deployment
|
|
|
|
1. Set `APP_ENV=production`.
|
|
2. Set a strong `SECRET_KEY`.
|
|
3. Set `DATABASE_URL` to your production database.
|
|
4. Install native dependencies for `face-recognition`/`dlib`.
|
|
5. Run `flask db upgrade`.
|
|
6. Serve through a production WSGI server behind HTTPS.
|
|
7. Configure your reverse proxy to forward HTTPS headers correctly.
|
|
|
|
Production config enables secure cookies. Do not run the Flask development server in production.
|
|
|
|
## Security Notes
|
|
|
|
- Face encodings are biometric data. Restrict database access and define a retention policy.
|
|
- Keep `.env` out of version control.
|
|
- Use HTTPS in production.
|
|
- Rotate staff accounts when operators leave the organization.
|
|
- Review database backups and access logs regularly.
|
|
|
|
## Troubleshooting
|
|
|
|
- If recognition endpoints return a dependency error, install `face-recognition` on Python 3.11 or 3.12 with the required `dlib` build tools.
|
|
- If the default Flask port is blocked on Windows, run `flask run --port 8000`.
|
|
- If database tables are missing, run `flask db upgrade`.
|