diff --git a/CLAUDE.md b/CLAUDE.md index 4960b61..b83885b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -731,8 +731,23 @@ WantedBy=multi-user.target - [ ] Gift cards (issuance with unique code; POS redemption; balance tracking; expiry) - [ ] End-of-day reconciliation (Close Day flow; cash count entry; variance calculation; `daily_reconciliations` record) -### Phase 4 — Tenant Operations Modules -- [ ] Staff management (profiles, job type, system role, location assignments, schedules) +### Phase 4 — Tenant Operations Modules ✅ COMPLETE +- [x] Pay structure per staff (hourly_rate, salary_amount, guarantee_amount, commission_rate, commission_enabled, pay_period — editable via staff form) +- [x] Pay period calculation engine (app/tenant/pay_periods/routes.py): hourly × hours, salary fixed, guarantee = max(guarantee, commission); results written to staff_pay_periods +- [x] Pay period approval workflow (draft → approved → paid; tenant_admin only) +- [x] Inventory (CRUD, reorder alerts, manual adjustment log; tenant_feature_required("inventory")) +- [x] Automatic inventory deduction on POS product sale (matched by SKU or name; InventoryLog entry created) +- [x] Appointment reminder engine (APScheduler job every 5 min; sends 24h + 2h email reminders; status=pending|sent|failed|cancelled) +- [x] Appointment reminders scheduled on appointment create (24h + 2h ahead) +- [x] Customer review request engine (APScheduler job every 10 min; delay per tenant setting; smart routing ≥4 stars shows platform links; one send enforced by review_request_sent_at) +- [x] app/scheduler_jobs.py — send_appointment_reminders(), send_review_requests() +- [x] Scheduler init in create_tenant_app() with SCHEDULER_API_ENABLED=False +- [x] pay_periods_bp + inventory_bp registered in tenant factory +- [x] Nav links wired: inventory → inventory.index, pay_periods → pay_periods.index +- [x] Both template trees in sync: 73 files each +- [x] Full validation passed: 6 imports OK, 0 missing templates, 0 illegal Jinja2, 0 broken extends + +### Phase 4 — Staff management (profiles, job type, system role, location assignments, schedules) (profiles, job type, system role, location assignments, schedules) - [ ] Pay structure setup per staff member (pay type, rates, pay period, commission toggle) - [ ] Commission tracking (per transaction, period summary; respects `commission_enabled` flag per staff) - [ ] Working hours / clockings (clock-in at login or manual; clock-out; total hours computed per period) @@ -949,6 +964,13 @@ Every fix must be validated by a programmatic test (import test, render test, or **Rule 10 — Pack files when more than 5 files are changed.** When a fix touches more than 5 files, compress them into a ZIP for delivery. Always include only the changed files — not the entire project. +**Rule 11 — Never call Python builtins or stdlib objects inside Jinja2 `{{ }}` expressions.** +Jinja2 does not have access to Python's standard library or builtins such as `set()`, `dict()`, `list()`, `int()`, `float()`, `str()`, `len()`, `sorted()`, `enumerate()`, `zip()`, `timedelta`, `datetime`, `date`. Any computation involving these must be done in the route and passed as a named template variable. Violations produce `UndefinedError` in production. Examples of what NOT to do: `(assigned_ids or set())`, `(view_date - timedelta(days=1))`. Correct approach: compute `prev_date = view_date - timedelta(days=1)` in the route and pass `prev_date=prev_date` to `render_template`. + +**Rule 12 — Always pass every variable a template references, on every code path.** +Every `render_template` call for a given template must supply the same set of variables — including early-return error paths. If the template uses `assigned_ids`, every `render_template("...form.html", ...)` call in that view must include `assigned_ids=...`. Missing variables on error-return paths produce `UndefinedError` only when that path is hit, making them hard to catch in testing. +When a fix touches more than 5 files, compress them into a ZIP for delivery. Always include only the changed files — not the entire project. + --- ## Phase 1 — Implementation Notes diff --git a/app/scheduler_jobs.py b/app/scheduler_jobs.py new file mode 100644 index 0000000..3979e37 --- /dev/null +++ b/app/scheduler_jobs.py @@ -0,0 +1,184 @@ +""" +app/scheduler_jobs.py +APScheduler job definitions for the tenant portal. +Registered in create_tenant_app() after scheduler.init_app(). + +Jobs: + - send_appointment_reminders every 5 minutes + - send_review_requests every 10 minutes +""" +import logging +from datetime import datetime, timezone, timedelta + +logger = logging.getLogger(__name__) + + +def send_appointment_reminders(app): + """ + Scan appointment_reminders for pending reminders due to be sent. + Sends email via Flask-Mail and marks status = 'sent' or 'failed'. + Runs every 5 minutes. + """ + with app.app_context(): + from app.extensions import db, mail + from app.models.salon import AppointmentReminder, Appointment, Customer + + now = datetime.now(timezone.utc) + + due = AppointmentReminder.query.filter_by(status="pending").filter( + AppointmentReminder.scheduled_for <= now + ).limit(50).all() + + if not due: + return + + sent = failed = 0 + for reminder in due: + appt = Appointment.query.get(reminder.appointment_id) + if not appt or appt.status in ("cancelled", "no_show"): + reminder.status = "cancelled" + continue + + customer = Customer.query.get(appt.customer_id) if appt.customer_id else None + if not customer or not customer.email: + # No email — mark sent so we don't retry endlessly + reminder.status = "sent" + reminder.sent_at = now + sent += 1 + continue + + try: + from flask_mail import Message + from app.models.platform import Tenant + tenant = Tenant.query.get(appt.tenant_id) + tenant_name = tenant.name if tenant else "Your salon" + + msg = Message( + subject=f"Appointment Reminder — {tenant_name}", + recipients=[customer.email], + body=( + f"Hi {customer.name},\n\n" + f"This is a reminder of your upcoming appointment:\n" + f"Date: {appt.start_time.strftime('%B %d, %Y at %I:%M %p')}\n" + f"Service: {appt.service.name if appt.service else 'N/A'}\n\n" + f"See you soon!\n{tenant_name}" + ), + ) + mail.send(msg) + reminder.status = "sent" + reminder.sent_at = now + sent += 1 + except Exception as exc: + logger.error("Reminder send failed id=%s: %s", reminder.id, exc) + reminder.status = "failed" + failed += 1 + + db.session.commit() + if sent or failed: + logger.info("Appointment reminders: sent=%d failed=%d", sent, failed) + + +def send_review_requests(app): + """ + Find completed transactions where review_request_sent_at IS NULL and + the transaction is old enough (per tenant setting review_request_delay_minutes). + Sends review email with smart routing: + - rating ≥ 4 → shows Google/Facebook/Yelp links + - rating < 4 → silent internal feedback only + One send per transaction enforced by review_request_sent_at. + Runs every 10 minutes. + """ + with app.app_context(): + from app.extensions import db, mail + from app.models.salon import Transaction, Customer, TenantSetting, CheckoutReview + from app.models.platform import Tenant + + now = datetime.now(timezone.utc) + + # Find eligible transactions: completed, not voided, no review sent yet + candidates = Transaction.query.filter( + Transaction.voided_at.is_(None), + Transaction.review_request_sent_at.is_(None), + Transaction.customer_id.isnot(None), + ).limit(100).all() + + sent = 0 + for txn in candidates: + # Get tenant-specific delay (default 60 minutes) + delay_setting = TenantSetting.query.filter_by( + tenant_id=txn.tenant_id, + setting_key="review_request_delay_minutes", + ).first() + delay_minutes = int(delay_setting.setting_value or 60) if delay_setting else 60 + eligible_after = txn.created_at.replace(tzinfo=timezone.utc) + timedelta(minutes=delay_minutes) + + if now < eligible_after: + continue + + customer = Customer.query.get(txn.customer_id) + if not customer or not customer.email: + # Mark sent to avoid retrying + txn.review_request_sent_at = now + continue + + tenant = Tenant.query.get(txn.tenant_id) + tenant_name = tenant.name if tenant else "Your salon" + + # Fetch review settings + def _get_setting(key): + s = TenantSetting.query.filter_by( + tenant_id=txn.tenant_id, setting_key=key).first() + return s.setting_value if s else None + + google_url = _get_setting("google_review_url") + yelp_url = _get_setting("yelp_review_url") + facebook_url = _get_setting("facebook_review_url") + + # Check if a review already submitted + existing_review = CheckoutReview.query.filter_by( + transaction_id=txn.id + ).first() + + try: + from flask_mail import Message + + if existing_review and existing_review.rating >= 4: + # High rating — encourage public review + links = [] + if google_url: + links.append(f"Google: {google_url}") + if yelp_url: + links.append(f"Yelp: {yelp_url}") + if facebook_url: + links.append(f"Facebook: {facebook_url}") + + body = ( + f"Hi {customer.name},\n\n" + f"Thank you for visiting {tenant_name}! We're so glad you enjoyed your visit.\n" + f"Would you mind sharing your experience online?\n\n" + + ("\n".join(links) if links else "(No review links configured)") + + f"\n\nThank you!\n{tenant_name}" + ) + else: + # No review yet or low rating — generic thank you only + body = ( + f"Hi {customer.name},\n\n" + f"Thank you for visiting {tenant_name}! We hope to see you again soon.\n\n" + f"{tenant_name}" + ) + + msg = Message( + subject=f"Thank you for visiting {tenant_name}!", + recipients=[customer.email], + body=body, + ) + mail.send(msg) + txn.review_request_sent_at = now + sent += 1 + except Exception as exc: + logger.error("Review request failed txn=%s: %s", txn.id, exc) + # Don't mark sent_at — will retry next cycle + + db.session.commit() + if sent: + logger.info("Review requests sent: %d", sent) diff --git a/app/templates/tenant/appointments/index.html b/app/templates/tenant/appointments/index.html index b16a947..d98a586 100644 --- a/app/templates/tenant/appointments/index.html +++ b/app/templates/tenant/appointments/index.html @@ -5,11 +5,12 @@

Appointments

‹ + class="btn btn-outline-secondary btn-sm">‹ + onchange="window.location='{{ url_for('appointments.index') }}?date='+this.value" + style="width:150px;"> › + class="btn btn-outline-secondary btn-sm">› + New
@@ -18,15 +19,7 @@
- - - - - - - - - + {% for appt in appointments %} @@ -36,25 +29,20 @@ {% else %} - - - + {% endfor %}
TimeCustomerServiceStaffStatusType
TimeCustomerServiceStaffStatusType
{{ appt.service.name if appt.service else '—' }} {{ appt.staff.name if appt.staff else '—' }} - + {{ appt.status }} {{ 'Walk-in' if appt.is_walk_in else 'Booked' }} - View + View {% if appt.status in ['pending','confirmed','in_progress'] %} - Checkout + Checkout {% endif %}
No appointments for this day.
No appointments for this day.
diff --git a/app/templates/tenant/inventory/adjust.html b/app/templates/tenant/inventory/adjust.html new file mode 100644 index 0000000..0ce67a5 --- /dev/null +++ b/app/templates/tenant/inventory/adjust.html @@ -0,0 +1,32 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Adjust Stock — {{ item.name }}{% endblock %} +{% block content %} +
+
+
+
Adjust Stock — {{ item.name }}
+
+

Current quantity: {{ item.qty_on_hand }}

+ {% if error %}
{{ error }}
{% endif %} +
+ +
+ + +
+
+ + +
+
+ + Cancel +
+
+
+
+
+
+{% endblock %} \ No newline at end of file diff --git a/app/templates/tenant/inventory/form.html b/app/templates/tenant/inventory/form.html new file mode 100644 index 0000000..b39247d --- /dev/null +++ b/app/templates/tenant/inventory/form.html @@ -0,0 +1,61 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}{{ 'Edit' if mode == 'edit' else 'New' }} Inventory Item{% endblock %} +{% block content %} +
+
+
+
{{ 'Edit' if mode == 'edit' else 'Add' }} Inventory Item
+
+ {% if error %}
{{ error }}
{% endif %} +
+ +
+ + +
+
+
+ + +
+
+ + +
+
+ {% if mode == 'create' %} +
+ + +
+ {% endif %} +
+ + +
+
+
+ + +
+
+ + +
+
+
+ + Cancel +
+
+
+
+
+
+{% endblock %} \ No newline at end of file diff --git a/app/templates/tenant/inventory/index.html b/app/templates/tenant/inventory/index.html new file mode 100644 index 0000000..e5ed825 --- /dev/null +++ b/app/templates/tenant/inventory/index.html @@ -0,0 +1,52 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Inventory{% endblock %} +{% block content %} +
+

Inventory

+ + Add Item +
+ +{% if low_stock %} +
+ +
+ {{ low_stock|length }} item(s) at or below reorder level: + {{ low_stock|map(attribute='name')|join(', ') }} +
+
+{% endif %} + +
+
+ + + + + + {% for item in items %} + + + + + + + + + + + {% else %} + + {% endfor %} + +
NameSKUCategoryOn HandReorder AtCostSale
{{ item.name }}{{ item.sku or '—' }}{{ item.category or '—' }} + + {{ item.qty_on_hand }} + + {{ item.reorder_level }}{{ '$' ~ "%.2f"|format(item.cost_price) if item.cost_price else '—' }}{{ '$' ~ "%.2f"|format(item.sale_price) if item.sale_price else '—' }} + Adjust + Edit + Log +
No inventory items yet.
+
+
+{% endblock %} \ No newline at end of file diff --git a/app/templates/tenant/inventory/log.html b/app/templates/tenant/inventory/log.html new file mode 100644 index 0000000..5a2884a --- /dev/null +++ b/app/templates/tenant/inventory/log.html @@ -0,0 +1,31 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Stock Log — {{ item.name }}{% endblock %} +{% block content %} +
+

Stock Log — {{ item.name }}

+ Current: {{ item.qty_on_hand }} units +
+
+
+ + + + {% for e in entries %} + + + + + + {% else %} + + {% endfor %} + +
DateChangeReason
{{ e.created_at.strftime('%Y-%m-%d %H:%M') }} + {{ '+' if e.delta > 0 else '' }}{{ e.delta }} + {{ e.reason or '—' }}
No log entries.
+
+
+ + Back to Inventory + +{% endblock %} \ No newline at end of file diff --git a/app/templates/tenant/layouts/base.html b/app/templates/tenant/layouts/base.html index 7815faa..1437712 100644 --- a/app/templates/tenant/layouts/base.html +++ b/app/templates/tenant/layouts/base.html @@ -116,7 +116,7 @@
  • + href="{{ url_for('inventory.index') }}"> Inventory
    • @@ -132,6 +132,12 @@ Reconciliation +
  • + + Pay Periods + +
  • diff --git a/app/templates/tenant/pay_periods/calculate.html b/app/templates/tenant/pay_periods/calculate.html new file mode 100644 index 0000000..854323a --- /dev/null +++ b/app/templates/tenant/pay_periods/calculate.html @@ -0,0 +1,76 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Calculate Pay Period{% endblock %} +{% block content %} +
    +
    +
    +
    Calculate Pay Period
    +
    +
    + +
    +
    + + +
    +
    + + +
    +
    +
    + + +
    Hold Ctrl/Cmd to select multiple.
    +
    + +
    +
    +
    +
    + + {% if results %} +
    +
    +
    + Results — {{ period_start.strftime('%b %d') if period_start else '' }}–{{ period_end.strftime('%b %d, %Y') if period_end else '' }} +
    +
    + + + + + + {% for row in results %} + + + + + + + + + {% endfor %} + + + + + + + +
    StaffTypeHoursBaseCommissionTotal
    {{ row.staff.name }}{{ row.calc.pay_type.title() }}{{ "%.1f"|format(row.calc.total_hours) }}h${{ "%.2f"|format(row.calc.base_amount) }}${{ "%.2f"|format(row.calc.commission_amount) }}${{ "%.2f"|format(row.calc.total_amount) }}
    Grand Total${{ "%.2f"|format(results|sum(attribute='calc.total_amount')) }}
    +
    +
    + Records saved as drafts. Go to Pay Periods to approve and mark as paid. +
    +
    +
    + {% endif %} +
    +{% endblock %} \ No newline at end of file diff --git a/app/templates/tenant/pay_periods/index.html b/app/templates/tenant/pay_periods/index.html new file mode 100644 index 0000000..b10adbe --- /dev/null +++ b/app/templates/tenant/pay_periods/index.html @@ -0,0 +1,53 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Pay Periods{% endblock %} +{% block content %} +
    +

    Pay Periods

    + Calculate Period +
    + +{% if periods %} +
    +
    + + + + + + {% for pp in periods %} + + + + + + + + + + + + {% endfor %} + +
    StaffPeriodTypeBaseCommissionTopupTotalStatus
    {{ pp.staff.name if pp.staff else pp.staff_id }}{{ pp.period_start.strftime('%b %d') }}–{{ pp.period_end.strftime('%b %d, %Y') }}{{ pp.pay_type.title() }}${{ "%.2f"|format(pp.base_amount) }}${{ "%.2f"|format(pp.commission_amount) }}{{ '$' ~ "%.2f"|format(pp.guarantee_topup) if pp.guarantee_topup > 0 else '—' }}${{ "%.2f"|format(pp.total_amount) }} + + {{ pp.status }} + + + {% if pp.status == 'draft' %} +
    + + +
    + {% elif pp.status == 'approved' %} +
    + + +
    + {% endif %} +
    +
    +
    +{% else %} +
    No pay periods calculated yet. Use Calculate Period to get started.
    +{% endif %} +{% endblock %} \ No newline at end of file diff --git a/app/templates/tenant/staff/form.html b/app/templates/tenant/staff/form.html index 8db6496..917a069 100644 --- a/app/templates/tenant/staff/form.html +++ b/app/templates/tenant/staff/form.html @@ -1,5 +1,18 @@ {% extends "tenant/layouts/base.html" %} {% block title %}{{ 'Edit' if mode == 'edit' else 'New' }} Staff Member{% endblock %} +{% block scripts %} + +{% endblock %} {% block content %}
    @@ -47,13 +60,63 @@
    +
    +
    Pay Structure
    +
    +
    + + +
    +
    + + +
    +
    +
    + + +
    +
    + + +
    +
    + + +
    +
    +
    + + +
    +
    +
    + + +
    +
    +
    {% for loc in locations %}
    + {{ 'checked' if assigned_ids and loc.id in assigned_ids }}>
    {% endfor %} diff --git a/app/tenant/__init__.py b/app/tenant/__init__.py index a435c06..6ed14c4 100644 --- a/app/tenant/__init__.py +++ b/app/tenant/__init__.py @@ -119,9 +119,35 @@ def create_tenant_app(config_override=None): from app.tenant.inventory.routes import inventory_bp from app.tenant.marketing.routes import marketing_bp from app.tenant.reports.routes import reports_bp + from app.tenant.pay_periods.routes import pay_periods_bp flask_app.register_blueprint(inventory_bp) flask_app.register_blueprint(marketing_bp) flask_app.register_blueprint(reports_bp) + flask_app.register_blueprint(pay_periods_bp) + + # ── APScheduler ─────────────────────────────────────────── + flask_app.config.setdefault("SCHEDULER_API_ENABLED", False) + flask_app.config.setdefault("SCHEDULER_TIMEZONE", "UTC") + from app.scheduler_jobs import send_appointment_reminders, send_review_requests + if not scheduler.running: + scheduler.init_app(flask_app) + scheduler.add_job( + id="appointment_reminders", + func=send_appointment_reminders, + args=[flask_app], + trigger="interval", + minutes=5, + replace_existing=True, + ) + scheduler.add_job( + id="review_requests", + func=send_review_requests, + args=[flask_app], + trigger="interval", + minutes=10, + replace_existing=True, + ) + scheduler.start() # ── Import all models for Migrate ───────────────────────── import app.models # noqa: F401 diff --git a/app/tenant/appointments/routes.py b/app/tenant/appointments/routes.py index 1396cba..a9d6b96 100644 --- a/app/tenant/appointments/routes.py +++ b/app/tenant/appointments/routes.py @@ -115,6 +115,22 @@ def create(): log_tenant_action("appointment.create", "appointment", appt.id, {"customer": customer_id, "staff": staff_id, "start": start_raw}) + + # Schedule 24h and 2h email reminders + from app.models.salon import AppointmentReminder as AR + for hours, rtype in [(24, "24h"), (2, "2h")]: + remind_at = start_time - timedelta(hours=hours) + if remind_at > datetime.now(timezone.utc): + db.session.add(AR( + tenant_id=g.tenant.id, + location_id=g.location.id, + appointment_id=appt.id, + reminder_type=rtype, + scheduled_for=remind_at, + channel="email", + status="pending", + )) + db.session.commit() flash("Appointment created.", "success") return redirect(url_for("appointments.index", diff --git a/app/tenant/inventory/routes.py b/app/tenant/inventory/routes.py index 56d917d..11994ad 100644 --- a/app/tenant/inventory/routes.py +++ b/app/tenant/inventory/routes.py @@ -1,17 +1,174 @@ """ app/tenant/inventory/routes.py -Phase 4 stub — implemented in Phase 4. +Inventory management: list, create, edit, adjust stock, reorder alerts. +Phase 4: automatic deduction on POS sale handled by pos/routes.py. """ -from flask import Blueprint, render_template, g +import logging +from flask import Blueprint, render_template, redirect, url_for, flash, request, g from flask_login import login_required -from app.decorators import require_role +from app.extensions import db +from app.models.salon import Inventory, InventoryLog +from app.decorators import require_role, demo_readonly, tenant_feature_required +from app.tenant.utils import log_tenant_action +logger = logging.getLogger(__name__) inventory_bp = Blueprint("inventory", __name__, url_prefix="/inventory") @inventory_bp.route("/") @login_required @require_role("tenant_admin", "tenant_manager") +@tenant_feature_required("inventory") def index(): - return render_template("tenant/feature_unavailable.html", - feature="Inventory") + items = Inventory.query.filter_by( + tenant_id=g.tenant.id, location_id=g.location.id + ).order_by(Inventory.category, Inventory.name).all() + low_stock = [i for i in items if i.qty_on_hand <= i.reorder_level] + return render_template("tenant/inventory/index.html", + items=items, low_stock=low_stock) + + +@inventory_bp.route("/new", methods=["GET", "POST"]) +@login_required +@require_role("tenant_admin", "tenant_manager") +@demo_readonly +@tenant_feature_required("inventory") +def create(): + if request.method == "POST": + name = request.form.get("name", "").strip() + if not name: + return render_template("tenant/inventory/form.html", + mode="create", error="Name is required.") + try: + qty = int(request.form.get("qty_on_hand", 0)) + reorder = int(request.form.get("reorder_level", 5)) + except ValueError: + return render_template("tenant/inventory/form.html", + mode="create", error="Invalid quantity or reorder level.") + + item = Inventory( + tenant_id=g.tenant.id, + location_id=g.location.id, + name=name, + sku=request.form.get("sku", "").strip() or None, + category=request.form.get("category", "").strip() or None, + qty_on_hand=qty, + reorder_level=reorder, + cost_price=_parse_decimal(request.form.get("cost_price", "")), + sale_price=_parse_decimal(request.form.get("sale_price", "")), + ) + db.session.add(item) + db.session.flush() + + if qty > 0: + db.session.add(InventoryLog( + tenant_id=g.tenant.id, location_id=g.location.id, + inventory_id=item.id, delta=qty, reason="Initial stock", + )) + + log_tenant_action("inventory.create", "inventory", item.id, {"name": name}) + db.session.commit() + flash(f"Item \'{name}\' added to inventory.", "success") + return redirect(url_for("inventory.index")) + + return render_template("tenant/inventory/form.html", mode="create") + + +@inventory_bp.route("//edit", methods=["GET", "POST"]) +@login_required +@require_role("tenant_admin", "tenant_manager") +@demo_readonly +@tenant_feature_required("inventory") +def edit(item_id): + item = Inventory.query.filter_by( + id=item_id, tenant_id=g.tenant.id, location_id=g.location.id + ).first_or_404() + + if request.method == "POST": + name = request.form.get("name", "").strip() + if not name: + return render_template("tenant/inventory/form.html", + mode="edit", item=item, error="Name is required.") + try: + reorder = int(request.form.get("reorder_level", item.reorder_level)) + except ValueError: + return render_template("tenant/inventory/form.html", + mode="edit", item=item, + error="Invalid reorder level.") + + item.name = name + item.sku = request.form.get("sku", "").strip() or None + item.category = request.form.get("category", "").strip() or None + item.reorder_level = reorder + item.cost_price = _parse_decimal(request.form.get("cost_price", "")) + item.sale_price = _parse_decimal(request.form.get("sale_price", "")) + + log_tenant_action("inventory.edit", "inventory", item.id, {"name": name}) + db.session.commit() + flash(f"\'{name}\' updated.", "success") + return redirect(url_for("inventory.index")) + + return render_template("tenant/inventory/form.html", mode="edit", item=item) + + +@inventory_bp.route("//adjust", methods=["GET", "POST"]) +@login_required +@require_role("tenant_admin", "tenant_manager") +@demo_readonly +@tenant_feature_required("inventory") +def adjust(item_id): + item = Inventory.query.filter_by( + id=item_id, tenant_id=g.tenant.id, location_id=g.location.id + ).first_or_404() + + if request.method == "POST": + try: + delta = int(request.form.get("delta", 0)) + except ValueError: + return render_template("tenant/inventory/adjust.html", + item=item, error="Invalid adjustment quantity.") + + reason = request.form.get("reason", "").strip() or "Manual adjustment" + new_qty = item.qty_on_hand + delta + if new_qty < 0: + return render_template("tenant/inventory/adjust.html", + item=item, + error=f"Adjustment would result in negative stock ({new_qty}).") + + item.qty_on_hand = new_qty + db.session.add(InventoryLog( + tenant_id=g.tenant.id, location_id=g.location.id, + inventory_id=item.id, delta=delta, reason=reason, + )) + log_tenant_action("inventory.adjust", "inventory", item.id, + {"delta": delta, "new_qty": new_qty, "reason": reason}) + db.session.commit() + logger.info("Inventory adjusted: item=%s delta=%s new_qty=%s", + item.id, delta, new_qty) + flash(f"Stock adjusted: {item.name} now has {new_qty} units.", "success") + return redirect(url_for("inventory.index")) + + return render_template("tenant/inventory/adjust.html", item=item) + + +@inventory_bp.route("//log") +@login_required +@require_role("tenant_admin", "tenant_manager") +@tenant_feature_required("inventory") +def log(item_id): + item = Inventory.query.filter_by( + id=item_id, tenant_id=g.tenant.id, location_id=g.location.id + ).first_or_404() + entries = InventoryLog.query.filter_by( + inventory_id=item_id, tenant_id=g.tenant.id + ).order_by(InventoryLog.created_at.desc()).limit(100).all() + return render_template("tenant/inventory/log.html", item=item, entries=entries) + + +def _parse_decimal(value): + if not value or not str(value).strip(): + return None + try: + return float(value) + except ValueError: + return None diff --git a/app/tenant/pay_periods/__init__.py b/app/tenant/pay_periods/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/app/tenant/pay_periods/routes.py b/app/tenant/pay_periods/routes.py new file mode 100644 index 0000000..ee84a43 --- /dev/null +++ b/app/tenant/pay_periods/routes.py @@ -0,0 +1,284 @@ +""" +app/tenant/pay_periods/routes.py +Pay period management: calculate, list, approve, mark paid. +Engine: hourly (rate × hours), salary (fixed), guarantee (max of guarantee vs commission). +""" +import logging +from datetime import datetime, timezone, date, timedelta +from decimal import Decimal, ROUND_HALF_UP + +from flask import Blueprint, render_template, redirect, url_for, flash, request, g +from flask_login import login_required + +from app.extensions import db +from app.models.salon import Staff, StaffPayPeriod, StaffClocking, CommissionLog +from app.decorators import require_role, demo_readonly +from app.tenant.utils import log_tenant_action + +logger = logging.getLogger(__name__) +pay_periods_bp = Blueprint("pay_periods", __name__, url_prefix="/pay-periods") + + +def _period_bounds(period_type: str, ref_date: date): + """Return (start, end) date for the pay period containing ref_date.""" + if period_type == "weekly": + start = ref_date - timedelta(days=ref_date.weekday()) + end = start + timedelta(days=6) + elif period_type == "biweekly": + # Anchor biweekly to 2025-01-06 (a Monday) + anchor = date(2025, 1, 6) + delta = (ref_date - anchor).days + week_num = delta // 7 + period_num = week_num // 2 + start = anchor + timedelta(weeks=period_num * 2) + end = start + timedelta(days=13) + else: # monthly + start = ref_date.replace(day=1) + if start.month == 12: + end = date(start.year + 1, 1, 1) - timedelta(days=1) + else: + end = date(start.year, start.month + 1, 1) - timedelta(days=1) + return start, end + + +def calculate_pay_period(staff: Staff, period_start: date, period_end: date) -> dict: + """ + Calculate pay for a staff member over the given period. + Returns a dict with base_amount, commission_amount, guarantee_topup, total_amount. + """ + # Total minutes clocked in the period + start_dt = datetime.combine(period_start, datetime.min.time()).replace(tzinfo=timezone.utc) + end_dt = datetime.combine(period_end, datetime.max.time()).replace(tzinfo=timezone.utc) + + clockings = StaffClocking.query.filter_by( + tenant_id=staff.tenant_id, staff_id=staff.id + ).filter( + StaffClocking.clocked_in_at >= start_dt, + StaffClocking.clocked_in_at <= end_dt, + StaffClocking.clocked_out_at.isnot(None), + ).all() + + total_minutes = sum(c.total_minutes or 0 for c in clockings) + total_hours = Decimal(total_minutes) / Decimal(60) + + # Commission for the period + comm_logs = CommissionLog.query.filter_by( + tenant_id=staff.tenant_id, staff_id=staff.id + ).filter( + CommissionLog.period.isnot(None), + ).all() + + # Filter by date range using the transaction's created_at via join + from app.models.salon import Transaction + comm_rows = ( + db.session.query(CommissionLog) + .join(Transaction, CommissionLog.transaction_id == Transaction.id) + .filter( + CommissionLog.tenant_id == staff.tenant_id, + CommissionLog.staff_id == staff.id, + Transaction.created_at >= start_dt, + Transaction.created_at <= end_dt, + Transaction.voided_at.is_(None), + ).all() + ) + commission_amount = sum( + Decimal(str(c.amount)) for c in comm_rows + ) + + pay_type = staff.pay_type + base_amount = Decimal("0") + guarantee_topup = Decimal("0") + + if pay_type == "hourly": + rate = Decimal(str(staff.hourly_rate or 0)) + base_amount = (rate * total_hours).quantize( + Decimal("0.01"), rounding=ROUND_HALF_UP + ) + + elif pay_type == "salary": + base_amount = Decimal(str(staff.salary_amount or 0)) + + elif pay_type == "guarantee": + guarantee = Decimal(str(staff.guarantee_amount or 0)) + if commission_amount >= guarantee: + base_amount = commission_amount + commission_amount = Decimal("0") # rolled into base + else: + base_amount = guarantee + guarantee_topup = (guarantee - commission_amount).quantize( + Decimal("0.01"), rounding=ROUND_HALF_UP + ) + commission_amount = Decimal("0") # topup covers the gap + + # Commission on top of hourly/salary (if enabled) + if pay_type in ("hourly", "salary") and not staff.commission_enabled: + commission_amount = Decimal("0") + + total_amount = (base_amount + commission_amount + guarantee_topup).quantize( + Decimal("0.01"), rounding=ROUND_HALF_UP + ) + + return { + "pay_type": pay_type, + "base_amount": float(base_amount), + "commission_amount": float(commission_amount), + "guarantee_topup": float(guarantee_topup), + "total_amount": float(total_amount), + "total_hours": float(total_hours), + } + + +@pay_periods_bp.route("/") +@login_required +@require_role("tenant_admin", "tenant_manager") +def index(): + periods = ( + StaffPayPeriod.query.filter_by(tenant_id=g.tenant.id) + .order_by(StaffPayPeriod.period_start.desc()) + .limit(100) + .all() + ) + staff_list = Staff.query.filter_by( + tenant_id=g.tenant.id, is_active=True + ).filter(Staff.deleted_at.is_(None)).order_by(Staff.name).all() + return render_template( + "tenant/pay_periods/index.html", + periods=periods, + staff_list=staff_list, + ) + + +@pay_periods_bp.route("/calculate", methods=["GET", "POST"]) +@login_required +@require_role("tenant_admin") +@demo_readonly +def calculate(): + staff_list = Staff.query.filter_by( + tenant_id=g.tenant.id, is_active=True + ).filter(Staff.deleted_at.is_(None)).order_by(Staff.name).all() + + results = [] + period_start = None + period_end = None + + if request.method == "POST": + period_start_raw = request.form.get("period_start", "") + period_end_raw = request.form.get("period_end", "") + staff_ids = request.form.getlist("staff_ids") + + try: + period_start = date.fromisoformat(period_start_raw) + period_end = date.fromisoformat(period_end_raw) + except ValueError: + flash("Invalid date range.", "danger") + return render_template( + "tenant/pay_periods/calculate.html", + staff_list=staff_list, + results=[], period_start=None, period_end=None, + ) + + if period_end < period_start: + flash("End date must be after start date.", "danger") + return render_template( + "tenant/pay_periods/calculate.html", + staff_list=staff_list, + results=[], period_start=period_start, period_end=period_end, + ) + + target_staff = [s for s in staff_list + if not staff_ids or str(s.id) in staff_ids] + + for member in target_staff: + calc = calculate_pay_period(member, period_start, period_end) + + # Check if a period record already exists + existing = StaffPayPeriod.query.filter_by( + tenant_id=g.tenant.id, + staff_id=member.id, + period_start=period_start, + period_end=period_end, + ).first() + + if existing: + # Update draft; never overwrite approved/paid + if existing.status == "draft": + existing.pay_type = calc["pay_type"] + existing.base_amount = calc["base_amount"] + existing.commission_amount = calc["commission_amount"] + existing.guarantee_topup = calc["guarantee_topup"] + existing.total_amount = calc["total_amount"] + pp = existing + else: + pp = existing + else: + pp = StaffPayPeriod( + tenant_id=g.tenant.id, + staff_id=member.id, + period_start=period_start, + period_end=period_end, + **{k: v for k, v in calc.items()}, + ) + db.session.add(pp) + + results.append({"staff": member, "calc": calc, "pay_period": pp}) + + db.session.commit() + log_tenant_action( + "pay_period.calculate", "pay_period", None, + {"period": f"{period_start}–{period_end}", + "staff_count": len(results)}, + ) + logger.info( + "Pay periods calculated: tenant=%s period=%s–%s count=%d", + g.tenant.id, period_start, period_end, len(results), + ) + flash(f"Calculated pay for {len(results)} staff member(s).", "success") + + return render_template( + "tenant/pay_periods/calculate.html", + staff_list=staff_list, + results=results, + period_start=period_start, + period_end=period_end, + ) + + +@pay_periods_bp.route("//approve", methods=["POST"]) +@login_required +@require_role("tenant_admin") +@demo_readonly +def approve(pp_id): + pp = StaffPayPeriod.query.filter_by( + id=pp_id, tenant_id=g.tenant.id + ).first_or_404() + if pp.status != "draft": + flash("Only draft periods can be approved.", "warning") + return redirect(url_for("pay_periods.index")) + pp.status = "approved" + log_tenant_action("pay_period.approve", "pay_period", pp.id, + {"staff": pp.staff_id, "total": float(pp.total_amount)}) + db.session.commit() + logger.info("Pay period approved: id=%s staff=%s", pp.id, pp.staff_id) + flash("Pay period approved.", "success") + return redirect(url_for("pay_periods.index")) + + +@pay_periods_bp.route("//mark-paid", methods=["POST"]) +@login_required +@require_role("tenant_admin") +@demo_readonly +def mark_paid(pp_id): + pp = StaffPayPeriod.query.filter_by( + id=pp_id, tenant_id=g.tenant.id + ).first_or_404() + if pp.status != "approved": + flash("Only approved periods can be marked as paid.", "warning") + return redirect(url_for("pay_periods.index")) + pp.status = "paid" + pp.notes = request.form.get("notes", pp.notes) + log_tenant_action("pay_period.mark_paid", "pay_period", pp.id, + {"staff": pp.staff_id, "total": float(pp.total_amount)}) + db.session.commit() + logger.info("Pay period marked paid: id=%s staff=%s", pp.id, pp.staff_id) + flash("Pay period marked as paid.", "success") + return redirect(url_for("pay_periods.index")) diff --git a/app/tenant/pos/routes.py b/app/tenant/pos/routes.py index 666ad1a..6f39eb2 100644 --- a/app/tenant/pos/routes.py +++ b/app/tenant/pos/routes.py @@ -212,6 +212,37 @@ def submit(): ) db.session.add(comm_log) + # ── Inventory auto-deduction for product line items ───── + for item in db.session.query(TransactionItem).filter_by( + transaction_id=txn.id + ).filter(TransactionItem.product_id.isnot(None)).all(): + from app.models.salon import Inventory, InventoryLog, Product as _Prod + prod = _Prod.query.get(item.product_id) + if prod and prod.sku: + inv = Inventory.query.filter_by( + tenant_id=g.tenant.id, + location_id=g.location.id, + sku=prod.sku, + ).first() + elif prod: + inv = Inventory.query.filter_by( + tenant_id=g.tenant.id, + location_id=g.location.id, + name=prod.name, + ).first() + else: + inv = None + + if inv and inv.qty_on_hand > 0: + inv.qty_on_hand -= item.qty + db.session.add(InventoryLog( + tenant_id=g.tenant.id, + location_id=g.location.id, + inventory_id=inv.id, + delta=-item.qty, + reason=f"POS sale txn#{txn.id}", + )) + log_tenant_action("transaction.create", "transaction", txn.id, {"total": float(total), "payment": payment_method}) db.session.commit() diff --git a/app/tenant/staff/routes.py b/app/tenant/staff/routes.py index ddfa6f1..50c736d 100644 --- a/app/tenant/staff/routes.py +++ b/app/tenant/staff/routes.py @@ -136,6 +136,14 @@ def edit(staff_id): member.phone = phone member.staff_type = request.form.get("staff_type", member.staff_type) member.is_active = request.form.get("is_active") == "1" + # Pay structure fields + member.pay_type = request.form.get("pay_type", member.pay_type) + member.pay_period = request.form.get("pay_period", member.pay_period) + member.commission_enabled = request.form.get("commission_enabled") == "1" + member.hourly_rate = _parse_decimal(request.form.get("hourly_rate", "")) + member.salary_amount = _parse_decimal(request.form.get("salary_amount", "")) + member.guarantee_amount = _parse_decimal(request.form.get("guarantee_amount", "")) + member.commission_rate = _parse_decimal(request.form.get("commission_rate", "")) # Update location assignments StaffLocation.query.filter_by( @@ -192,4 +200,4 @@ def reset_passcode(staff_id): "success") return redirect(url_for("staff.index")) - return render_template("tenant/staff/reset_passcode.html", staff=member) \ No newline at end of file + return render_template("tenant/staff/reset_passcode.html", staff=member) diff --git a/templates/tenant/inventory/adjust.html b/templates/tenant/inventory/adjust.html new file mode 100644 index 0000000..0ce67a5 --- /dev/null +++ b/templates/tenant/inventory/adjust.html @@ -0,0 +1,32 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Adjust Stock — {{ item.name }}{% endblock %} +{% block content %} +
    +
    +
    +
    Adjust Stock — {{ item.name }}
    +
    +

    Current quantity: {{ item.qty_on_hand }}

    + {% if error %}
    {{ error }}
    {% endif %} +
    + +
    + + +
    +
    + + +
    +
    + + Cancel +
    +
    +
    +
    +
    +
    +{% endblock %} \ No newline at end of file diff --git a/templates/tenant/inventory/form.html b/templates/tenant/inventory/form.html new file mode 100644 index 0000000..b39247d --- /dev/null +++ b/templates/tenant/inventory/form.html @@ -0,0 +1,61 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}{{ 'Edit' if mode == 'edit' else 'New' }} Inventory Item{% endblock %} +{% block content %} +
    +
    +
    +
    {{ 'Edit' if mode == 'edit' else 'Add' }} Inventory Item
    +
    + {% if error %}
    {{ error }}
    {% endif %} +
    + +
    + + +
    +
    +
    + + +
    +
    + + +
    +
    + {% if mode == 'create' %} +
    + + +
    + {% endif %} +
    + + +
    +
    +
    + + +
    +
    + + +
    +
    +
    + + Cancel +
    +
    +
    +
    +
    +
    +{% endblock %} \ No newline at end of file diff --git a/templates/tenant/inventory/index.html b/templates/tenant/inventory/index.html new file mode 100644 index 0000000..e5ed825 --- /dev/null +++ b/templates/tenant/inventory/index.html @@ -0,0 +1,52 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Inventory{% endblock %} +{% block content %} +
    +

    Inventory

    + + Add Item +
    + +{% if low_stock %} +
    + +
    + {{ low_stock|length }} item(s) at or below reorder level: + {{ low_stock|map(attribute='name')|join(', ') }} +
    +
    +{% endif %} + +
    +
    + + + + + + {% for item in items %} + + + + + + + + + + + {% else %} + + {% endfor %} + +
    NameSKUCategoryOn HandReorder AtCostSale
    {{ item.name }}{{ item.sku or '—' }}{{ item.category or '—' }} + + {{ item.qty_on_hand }} + + {{ item.reorder_level }}{{ '$' ~ "%.2f"|format(item.cost_price) if item.cost_price else '—' }}{{ '$' ~ "%.2f"|format(item.sale_price) if item.sale_price else '—' }} + Adjust + Edit + Log +
    No inventory items yet.
    +
    +
    +{% endblock %} \ No newline at end of file diff --git a/templates/tenant/inventory/log.html b/templates/tenant/inventory/log.html new file mode 100644 index 0000000..5a2884a --- /dev/null +++ b/templates/tenant/inventory/log.html @@ -0,0 +1,31 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Stock Log — {{ item.name }}{% endblock %} +{% block content %} +
    +

    Stock Log — {{ item.name }}

    + Current: {{ item.qty_on_hand }} units +
    +
    +
    + + + + {% for e in entries %} + + + + + + {% else %} + + {% endfor %} + +
    DateChangeReason
    {{ e.created_at.strftime('%Y-%m-%d %H:%M') }} + {{ '+' if e.delta > 0 else '' }}{{ e.delta }} + {{ e.reason or '—' }}
    No log entries.
    +
    +
    + + Back to Inventory + +{% endblock %} \ No newline at end of file diff --git a/templates/tenant/layouts/base.html b/templates/tenant/layouts/base.html index 7815faa..1437712 100644 --- a/templates/tenant/layouts/base.html +++ b/templates/tenant/layouts/base.html @@ -116,7 +116,7 @@
  • + href="{{ url_for('inventory.index') }}"> Inventory
    • @@ -132,6 +132,12 @@ Reconciliation +
  • + + Pay Periods + +
  • diff --git a/templates/tenant/pay_periods/calculate.html b/templates/tenant/pay_periods/calculate.html new file mode 100644 index 0000000..854323a --- /dev/null +++ b/templates/tenant/pay_periods/calculate.html @@ -0,0 +1,76 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Calculate Pay Period{% endblock %} +{% block content %} +
    +
    +
    +
    Calculate Pay Period
    +
    +
    + +
    +
    + + +
    +
    + + +
    +
    +
    + + +
    Hold Ctrl/Cmd to select multiple.
    +
    + +
    +
    +
    +
    + + {% if results %} +
    +
    +
    + Results — {{ period_start.strftime('%b %d') if period_start else '' }}–{{ period_end.strftime('%b %d, %Y') if period_end else '' }} +
    +
    + + + + + + {% for row in results %} + + + + + + + + + {% endfor %} + + + + + + + +
    StaffTypeHoursBaseCommissionTotal
    {{ row.staff.name }}{{ row.calc.pay_type.title() }}{{ "%.1f"|format(row.calc.total_hours) }}h${{ "%.2f"|format(row.calc.base_amount) }}${{ "%.2f"|format(row.calc.commission_amount) }}${{ "%.2f"|format(row.calc.total_amount) }}
    Grand Total${{ "%.2f"|format(results|sum(attribute='calc.total_amount')) }}
    +
    +
    + Records saved as drafts. Go to Pay Periods to approve and mark as paid. +
    +
    +
    + {% endif %} +
    +{% endblock %} \ No newline at end of file diff --git a/templates/tenant/pay_periods/index.html b/templates/tenant/pay_periods/index.html new file mode 100644 index 0000000..b10adbe --- /dev/null +++ b/templates/tenant/pay_periods/index.html @@ -0,0 +1,53 @@ +{% extends "tenant/layouts/base.html" %} +{% block title %}Pay Periods{% endblock %} +{% block content %} +
    +

    Pay Periods

    + Calculate Period +
    + +{% if periods %} +
    +
    + + + + + + {% for pp in periods %} + + + + + + + + + + + + {% endfor %} + +
    StaffPeriodTypeBaseCommissionTopupTotalStatus
    {{ pp.staff.name if pp.staff else pp.staff_id }}{{ pp.period_start.strftime('%b %d') }}–{{ pp.period_end.strftime('%b %d, %Y') }}{{ pp.pay_type.title() }}${{ "%.2f"|format(pp.base_amount) }}${{ "%.2f"|format(pp.commission_amount) }}{{ '$' ~ "%.2f"|format(pp.guarantee_topup) if pp.guarantee_topup > 0 else '—' }}${{ "%.2f"|format(pp.total_amount) }} + + {{ pp.status }} + + + {% if pp.status == 'draft' %} +
    + + +
    + {% elif pp.status == 'approved' %} +
    + + +
    + {% endif %} +
    +
    +
    +{% else %} +
    No pay periods calculated yet. Use Calculate Period to get started.
    +{% endif %} +{% endblock %} \ No newline at end of file diff --git a/templates/tenant/staff/form.html b/templates/tenant/staff/form.html index 644ffda..917a069 100644 --- a/templates/tenant/staff/form.html +++ b/templates/tenant/staff/form.html @@ -1,5 +1,18 @@ {% extends "tenant/layouts/base.html" %} {% block title %}{{ 'Edit' if mode == 'edit' else 'New' }} Staff Member{% endblock %} +{% block scripts %} + +{% endblock %} {% block content %}
    @@ -11,17 +24,19 @@
    - +
    - +
    {% if mode == 'create' %}
    - +
    Staff will use this PIN to log in. Show it to them once, then discard it.
    {% endif %} @@ -30,7 +45,7 @@ {% for t in ['hourly','salary','guarantee'] %} - + {% endfor %}
    +
    +
    Pay Structure
    +
    +
    + + +
    +
    + + +
    +
    +
    + + +
    +
    + + +
    +
    + + +
    +
    +
    + + +
    +
    +
    + + +
    +
    +
    {% for loc in locations %}
    - +
    {% endfor %}
    {% if mode == 'edit' %}
    - +
    {% endif %}