Aug 7 - Update: documents, no code update
This commit is contained in:
+145
-1
@@ -3,6 +3,8 @@
|
||||
> **Audience:** AI assistants and developers extending JQC into a multi-tenant SaaS.
|
||||
> **Companion to:** `CLAUDE.md` (single-tenant architecture reference).
|
||||
> **Status:** MT-0 through MT-8 complete and deployed (MT-8 billing is flag-gated behind `BILLING_ENABLED`, default off). MT-9 (iOS multi-tenant) is fully pending — both the server-side discovery endpoints and the iOS client are unbuilt.
|
||||
>
|
||||
> **Feature parity with the single-tenant tree (MT-10 → MT-17): complete.** MT forked from ST before ST kept shipping, and that gap has now been closed phase by phase — see §12. The only deliberate divergence is ST's `phase50_default_modern`, which MT does not adopt (§12.3). Tenant migration head: `phase52_user_ui_theme`.
|
||||
|
||||
---
|
||||
|
||||
@@ -328,4 +330,146 @@ python -m control.tenant_migrate bootstrap --tenant acme # fresh DB only
|
||||
# Superadmin panel
|
||||
sudo systemctl status jqc-panel
|
||||
sudo systemctl restart jqc-panel
|
||||
```
|
||||
```
|
||||
---
|
||||
|
||||
## 12. Feature parity with the single-tenant tree (MT-10 → MT-17)
|
||||
|
||||
MT forked from the single-tenant codebase (`LT_Janitorial_Quality_Control`, "ST")
|
||||
before ST continued shipping features. This section records how that gap was
|
||||
closed. It is **complete** as of MT-17.
|
||||
|
||||
### 12.1 Why the two trees look more different than they are
|
||||
|
||||
A file-by-file comparison of the two trees overstates the gap. Several ST files
|
||||
have no MT counterpart *by name* while the feature is fully present under MT's
|
||||
own naming. These are **not** gaps and must not be "fixed":
|
||||
|
||||
| ST | MT equivalent |
|
||||
|---|---|
|
||||
| `models/scheduled_inspection.py` | `models/inspection_schedule.py` |
|
||||
| `routes/scheduled_inspections.py` | `routes/inspection_schedules.py` |
|
||||
| `routes/public.py` | `routes/facility_qr.py` |
|
||||
| `models/notification_recipient.py` | `models/project_recipient.py` |
|
||||
| `ContractNotificationRecipient` / `get_event_types()` | `ProjectNotificationRecipient` / `get_events()` |
|
||||
| `app/add_form_schema.py` | `scripts/add_form_schema.py` |
|
||||
| `support/admin_conversation_detail.html` | `support/conversation_detail.html` |
|
||||
|
||||
There is also one place where **MT is ahead of ST**: `utils/forms.py`
|
||||
`strong_password()` (length + complexity + common-password blocklist) versus
|
||||
ST's bare `Length(min=6)`. Porting ST's version would be a downgrade.
|
||||
|
||||
### 12.2 Phase log
|
||||
|
||||
Migrations `phase41` → `phase52` in `migrations/versions/` are the parity track:
|
||||
auditor role, area QR tokens, schedule plan fields, internal handler, frequency
|
||||
ENUM widening, recurrence, end date, parent inspection, follow-up attribution,
|
||||
schedule acknowledgement, and then:
|
||||
|
||||
**MT-15 — External Inspector role. ✅ DONE** (`phase51_external_inspector`)
|
||||
Adds `external_inspector` to the `users.role` ENUM: an inspector employed by the
|
||||
customer or a third party, with identical capabilities to `inspector` and scoped
|
||||
the same way through `InspectorAssignment`.
|
||||
|
||||
The ENUM widening and the code **must ship together**. MT had ~80 sites testing
|
||||
`role == 'inspector'` with a literal comparison; widening the ENUM alone would
|
||||
make every one of them evaluate False for the new role and fall through to the
|
||||
*unscoped* branch — `get_inspector_scope()` returns `None`, downstream queries
|
||||
drop their facility filter, and an inspector employed by one customer sees every
|
||||
other customer's contracts. `User.INSPECTOR_ROLES` (exposed as the
|
||||
`is_inspector` property) is now the single definition, and
|
||||
`test_external_inspector_scope_is_not_unrestricted` fails loudly if anyone
|
||||
reverts a membership test to a literal.
|
||||
|
||||
Also in this phase: external inspectors are **invited**, never given a password
|
||||
(`password_set=False` + emailed 72-hour token, reusing the customer invite mail),
|
||||
with a new `auth.resend_invite` route so a bounced invitation cannot brick an
|
||||
account permanently. Creating any other role with a blank password is now
|
||||
rejected — it previously stored the hash of the empty string.
|
||||
|
||||
**MT-16 — Modern web portal design. ✅ DONE** (`phase52_user_ui_theme`)
|
||||
Ports ST's `phase48`. `base.html` became a one-line dispatcher
|
||||
(`{% extends jqc_layout %}`); the old chrome moved verbatim to
|
||||
`layouts/classic.html`; `layouts/modern.html` is the sidebar shell. All existing
|
||||
page templates needed **zero edits** — Jinja resolves `{% block %}` overrides
|
||||
through the whole inheritance chain.
|
||||
|
||||
`ThemedEnvironment.get_template()` swaps `x.html` → `modern/x.html` for modern
|
||||
users. **The swap is in `get_template()`, not the loader, on purpose:** Jinja's
|
||||
template cache is keyed on the name `get_template()` receives, so a cached
|
||||
modern template can never be served to a classic user — and in MT, where one
|
||||
Gunicorn worker serves many tenants, a loader-level swap would leak across
|
||||
tenants too.
|
||||
|
||||
MT-specific adaptations that ST's files required: tenant branding (ST hardcodes
|
||||
its own company name), `inspection_schedules` for ST's `scheduled_inspections`,
|
||||
`facilities.qr_print_all` for ST's `facility_qr_print_all`, the billing banner,
|
||||
`role_label` for MT-15's new role, and a rewritten tenant-neutral About page.
|
||||
`_quota_warning.html` is deliberately **not** in the modern layout — it is a
|
||||
per-form include, not chrome, and would render twice on four pages.
|
||||
|
||||
**MT-17 — Enrollment intake form. ✅ DONE** (no migration)
|
||||
Ports ST's `app/enrollment/` — a public, login-free intake form plus an
|
||||
admin-only inbox, kept deliberately outside the schema (flat JSON, no model, no
|
||||
migration, deletable package).
|
||||
|
||||
**Tenant isolation was the change ST's version required.** ST keeps every
|
||||
submission in one flat directory; in MT that directory is shared by every tenant
|
||||
on the host, so `/enrollment/admin` would list other organisations' submissions.
|
||||
Submissions are now filed under `<ENROLLMENT_DIR>/t<tenant_id>/`, mirroring
|
||||
`storage.tenant_key_prefix()`. When multi-tenancy is on and no tenant is bound,
|
||||
`storage.enrollment_dir()` **raises `TenantUnresolved` rather than falling back
|
||||
to the root** — a fallback would be a silent cross-tenant leak; an exception is
|
||||
loud and safe.
|
||||
|
||||
Branding was the second change: ST hardcodes its company name in four places and
|
||||
a personal Gmail address as the customer-facing "corrections" contact. Both now
|
||||
resolve from `TenantSettings`, with a test that greps the package so they cannot
|
||||
silently return.
|
||||
|
||||
### 12.3 Deliberate divergence: ST `phase50_default_modern` is NOT ported
|
||||
|
||||
ST's `phase50` flips the `ui_theme` column default to `modern` **and** runs:
|
||||
|
||||
```sql
|
||||
UPDATE users SET ui_theme = 'modern' WHERE ui_theme = 'classic';
|
||||
```
|
||||
|
||||
That overwrites every saved preference. It was defensible for a single-tenant
|
||||
deployment deciding for its own staff after its own A/B test.
|
||||
|
||||
**It is not portable to MT.** The same statement runs against *every tenant
|
||||
database*, flipping the entire UI for tenants who never saw the test and never
|
||||
asked. MT therefore ships the `phase48` semantics only: default `classic`, **no
|
||||
backfill of any kind**.
|
||||
|
||||
The effective default for accounts that never chose is config
|
||||
`DEFAULT_UI_THEME` (`app/__init__.py::resolve_ui_theme`), which reads the
|
||||
environment and itself defaults to `classic`. A stored `users.ui_theme` always
|
||||
wins. **To put a tenant on the modern design, set `DEFAULT_UI_THEME=modern` in
|
||||
that tenant's process environment** — a config change, reversible, with no
|
||||
preferences destroyed. `test_new_user_defaults_to_classic` pins this so a future
|
||||
port of `phase50` has to be a deliberate act.
|
||||
|
||||
### 12.4 Open decisions
|
||||
|
||||
- **Seat quota.** `tenancy/quota.py::count_active_users()` counts all active
|
||||
users regardless of role, so external inspectors consume a seat against
|
||||
`max_users`. Intentional (they are real accounts), but tenants near their cap
|
||||
will hit `@quota_soft_check('users')` when inviting third parties. Excluding
|
||||
them is a billing-policy decision, not a bug fix.
|
||||
- **`enrollment/schema.py::CORRECTIONS_EMAIL`** is now an empty last-resort
|
||||
default. Decide whether to drop the constant and its two config fallbacks in
|
||||
favour of requiring `TenantSettings.support_email`.
|
||||
|
||||
### 12.5 Deferred, with reasons
|
||||
|
||||
- **`_handler_split` dashboard cards.** ST's classic dashboard shows handler
|
||||
breakdowns for *opened today* and *unassigned* as well as open issues. MT
|
||||
supplies `handler_breakdown` (open issues) and both MT dashboards render it;
|
||||
the other two would require converting `.count()` queries to `.all()` and
|
||||
fetching full rows for a cosmetic card, which regresses large tenants. If
|
||||
wanted, do it as a SQL `GROUP BY handler_type` rather than ST's Python-side
|
||||
count over fetched rows.
|
||||
- **PDF / audit hardening.**
|
||||
- **MT-9 iOS client** (see §7).
|
||||
|
||||
Reference in New Issue
Block a user