spms 1.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- spms-1.2.1/LICENSE +14 -0
- spms-1.2.1/PKG-INFO +298 -0
- spms-1.2.1/README.md +251 -0
- spms-1.2.1/pyproject.toml +116 -0
- spms-1.2.1/setup.cfg +4 -0
- spms-1.2.1/src/app_core/__init__.py +1 -0
- spms-1.2.1/src/app_core/assistant/__init__.py +70 -0
- spms-1.2.1/src/app_core/assistant/action_validation.py +970 -0
- spms-1.2.1/src/app_core/assistant/actions.py +473 -0
- spms-1.2.1/src/app_core/assistant/common.py +265 -0
- spms-1.2.1/src/app_core/assistant/engine.py +571 -0
- spms-1.2.1/src/app_core/assistant/feedback.py +175 -0
- spms-1.2.1/src/app_core/assistant/formatting.py +1299 -0
- spms-1.2.1/src/app_core/assistant/nlu.py +186 -0
- spms-1.2.1/src/app_core/assistant/runtime.py +387 -0
- spms-1.2.1/src/app_core/assistant/tools.py +1154 -0
- spms-1.2.1/src/app_core/barcodes.py +248 -0
- spms-1.2.1/src/app_core/db.py +1540 -0
- spms-1.2.1/src/app_core/doctor.py +686 -0
- spms-1.2.1/src/app_core/domain/__init__.py +10 -0
- spms-1.2.1/src/app_core/domain/availability.py +64 -0
- spms-1.2.1/src/app_core/domain/dates.py +162 -0
- spms-1.2.1/src/app_core/domain/metrics.py +119 -0
- spms-1.2.1/src/app_core/domain/money.py +106 -0
- spms-1.2.1/src/app_core/domain/tax.py +66 -0
- spms-1.2.1/src/app_core/paths.py +223 -0
- spms-1.2.1/src/app_core/services/__init__.py +36 -0
- spms-1.2.1/src/app_core/services/_monolith.py +7846 -0
- spms-1.2.1/src/app_core/services/_seed_data.py +214 -0
- spms-1.2.1/src/app_core/services/billing_docs.py +245 -0
- spms-1.2.1/src/app_core/services/reports_metrics.py +180 -0
- spms-1.2.1/src/app_core/support.py +389 -0
- spms-1.2.1/src/app_core/updater.py +478 -0
- spms-1.2.1/src/spms.egg-info/PKG-INFO +298 -0
- spms-1.2.1/src/spms.egg-info/SOURCES.txt +172 -0
- spms-1.2.1/src/spms.egg-info/dependency_links.txt +1 -0
- spms-1.2.1/src/spms.egg-info/entry_points.txt +3 -0
- spms-1.2.1/src/spms.egg-info/requires.txt +25 -0
- spms-1.2.1/src/spms.egg-info/top_level.txt +4 -0
- spms-1.2.1/tests/test_assistant.py +508 -0
- spms-1.2.1/tests/test_assistant_actions_validation_feedback.py +262 -0
- spms-1.2.1/tests/test_assistant_coverage_recent.py +92 -0
- spms-1.2.1/tests/test_assistant_engine_runtime_coverage.py +139 -0
- spms-1.2.1/tests/test_assistant_runtime_coverage.py +167 -0
- spms-1.2.1/tests/test_assistant_tools_formatting_coverage.py +257 -0
- spms-1.2.1/tests/test_assistant_tools_new.py +31 -0
- spms-1.2.1/tests/test_attribution.py +32 -0
- spms-1.2.1/tests/test_audit_fixes_2026.py +112 -0
- spms-1.2.1/tests/test_auth.py +106 -0
- spms-1.2.1/tests/test_batch_fefo_traceability.py +138 -0
- spms-1.2.1/tests/test_business_fixes_analytics.py +88 -0
- spms-1.2.1/tests/test_cov95_assistant_core.py +367 -0
- spms-1.2.1/tests/test_cov95_assistant_formatting_tools.py +215 -0
- spms-1.2.1/tests/test_cov95_db.py +345 -0
- spms-1.2.1/tests/test_cov95_doctor_updater.py +294 -0
- spms-1.2.1/tests/test_cov95_monolith_services_a.py +423 -0
- spms-1.2.1/tests/test_cov95_monolith_services_b.py +293 -0
- spms-1.2.1/tests/test_cov95_monolith_services_c.py +132 -0
- spms-1.2.1/tests/test_cov95_support_paths_barcodes.py +248 -0
- spms-1.2.1/tests/test_cov95b_assistant_core.py +509 -0
- spms-1.2.1/tests/test_cov95b_core_platform.py +675 -0
- spms-1.2.1/tests/test_cov95b_monolith_extra.py +645 -0
- spms-1.2.1/tests/test_cov95b_monolith_more.py +193 -0
- spms-1.2.1/tests/test_coverage_90_action_validation_tools.py +291 -0
- spms-1.2.1/tests/test_coverage_90_batch2.py +368 -0
- spms-1.2.1/tests/test_coverage_90_batch3.py +21 -0
- spms-1.2.1/tests/test_coverage_90_deps.py +137 -0
- spms-1.2.1/tests/test_coverage_90_doctor_engine.py +280 -0
- spms-1.2.1/tests/test_coverage_90_formatting_tools_branches.py +344 -0
- spms-1.2.1/tests/test_coverage_90_monolith_batch1.py +271 -0
- spms-1.2.1/tests/test_coverage_90_monolith_batch2.py +215 -0
- spms-1.2.1/tests/test_coverage_90_quickwins.py +343 -0
- spms-1.2.1/tests/test_coverage_90_tools_more.py +307 -0
- spms-1.2.1/tests/test_coverage_gaps.py +554 -0
- spms-1.2.1/tests/test_dashboards.py +188 -0
- spms-1.2.1/tests/test_db_coverage.py +101 -0
- spms-1.2.1/tests/test_db_integrity_idempotency.py +68 -0
- spms-1.2.1/tests/test_db_migrations.py +81 -0
- spms-1.2.1/tests/test_demo_seed_guards.py +54 -0
- spms-1.2.1/tests/test_domain_primitives.py +209 -0
- spms-1.2.1/tests/test_expenses.py +71 -0
- spms-1.2.1/tests/test_extra.py +342 -0
- spms-1.2.1/tests/test_extra2.py +346 -0
- spms-1.2.1/tests/test_extra3.py +305 -0
- spms-1.2.1/tests/test_final.py +712 -0
- spms-1.2.1/tests/test_golive_invariants_migrations_contracts.py +262 -0
- spms-1.2.1/tests/test_guests.py +144 -0
- spms-1.2.1/tests/test_integration.py +88 -0
- spms-1.2.1/tests/test_integrity_batch_ops.py +60 -0
- spms-1.2.1/tests/test_integrity_batch_seed_strengthened.py +293 -0
- spms-1.2.1/tests/test_inventory.py +131 -0
- spms-1.2.1/tests/test_invoice_clean.py +50 -0
- spms-1.2.1/tests/test_invoices.py +93 -0
- spms-1.2.1/tests/test_ledger.py +122 -0
- spms-1.2.1/tests/test_migrate_v9_idempotency.py +52 -0
- spms-1.2.1/tests/test_paths.py +86 -0
- spms-1.2.1/tests/test_paths_updater_doctor_coverage.py +312 -0
- spms-1.2.1/tests/test_payments.py +101 -0
- spms-1.2.1/tests/test_pos.py +142 -0
- spms-1.2.1/tests/test_printers.py +147 -0
- spms-1.2.1/tests/test_quality_gate_foundations.py +405 -0
- spms-1.2.1/tests/test_recipes.py +230 -0
- spms-1.2.1/tests/test_reports.py +92 -0
- spms-1.2.1/tests/test_reports_metrics.py +105 -0
- spms-1.2.1/tests/test_reservations.py +265 -0
- spms-1.2.1/tests/test_rooms.py +185 -0
- spms-1.2.1/tests/test_round_2.py +327 -0
- spms-1.2.1/tests/test_round_3.py +306 -0
- spms-1.2.1/tests/test_seed_barcode_batch.py +107 -0
- spms-1.2.1/tests/test_services_catalog_vouchers_rules.py +119 -0
- spms-1.2.1/tests/test_services_coverage_100.py +511 -0
- spms-1.2.1/tests/test_services_groups_packages_approvals_shifts.py +195 -0
- spms-1.2.1/tests/test_services_integrity_night_audit.py +106 -0
- spms-1.2.1/tests/test_settings.py +94 -0
- spms-1.2.1/tests/test_subagent_expanded_coverage.py +618 -0
- spms-1.2.1/tests/test_subagent_scope_coverage.py +432 -0
- spms-1.2.1/tests/test_subagent_scope_nov12_expansion.py +461 -0
- spms-1.2.1/tests/test_support_reporting.py +125 -0
- spms-1.2.1/tests/test_updater.py +28 -0
- spms-1.2.1/ui/__init__.py +1 -0
- spms-1.2.1/ui/web/__init__.py +1 -0
- spms-1.2.1/ui/web/deps.py +614 -0
- spms-1.2.1/ui/web/rendering.py +81 -0
- spms-1.2.1/ui/web/route_utils.py +48 -0
- spms-1.2.1/ui/web/routes/__init__.py +1 -0
- spms-1.2.1/ui/web/routes/accounting.py +168 -0
- spms-1.2.1/ui/web/routes/assistant.py +585 -0
- spms-1.2.1/ui/web/routes/dashboard.py +33 -0
- spms-1.2.1/ui/web/routes/files.py +28 -0
- spms-1.2.1/ui/web/routes/guests.py +115 -0
- spms-1.2.1/ui/web/routes/housekeeping.py +158 -0
- spms-1.2.1/ui/web/routes/pos_inventory.py +492 -0
- spms-1.2.1/ui/web/routes/reports_analytics.py +80 -0
- spms-1.2.1/ui/web/routes/reservations.py +628 -0
- spms-1.2.1/ui/web/routes/settings_branding.py +910 -0
- spms-1.2.1/ui/web/routes/support.py +55 -0
- spms-1.2.1/ui/web/server.py +273 -0
- spms-1.2.1/ui/web/static/app.css +142 -0
- spms-1.2.1/ui/web/static/app.js +80 -0
- spms-1.2.1/ui/web/static/assistant_widget.js +284 -0
- spms-1.2.1/ui/web/static/icons/apple-touch-icon.png +0 -0
- spms-1.2.1/ui/web/static/icons/icon-192.png +0 -0
- spms-1.2.1/ui/web/static/icons/icon-512.png +0 -0
- spms-1.2.1/ui/web/static/manifest.webmanifest +25 -0
- spms-1.2.1/ui/web/static/sw.js +63 -0
- spms-1.2.1/ui/web/templates/accounting/index.html +163 -0
- spms-1.2.1/ui/web/templates/assistant/_messages.html +102 -0
- spms-1.2.1/ui/web/templates/assistant/index.html +80 -0
- spms-1.2.1/ui/web/templates/base.html +94 -0
- spms-1.2.1/ui/web/templates/dashboard.html +95 -0
- spms-1.2.1/ui/web/templates/errors/500.html +29 -0
- spms-1.2.1/ui/web/templates/guests/detail.html +132 -0
- spms-1.2.1/ui/web/templates/guests/list.html +23 -0
- spms-1.2.1/ui/web/templates/housekeeping/index.html +94 -0
- spms-1.2.1/ui/web/templates/partials/forms.html +7 -0
- spms-1.2.1/ui/web/templates/partials/ui.html +24 -0
- spms-1.2.1/ui/web/templates/pos/index.html +378 -0
- spms-1.2.1/ui/web/templates/reports/index.html +51 -0
- spms-1.2.1/ui/web/templates/reports/view.html +7 -0
- spms-1.2.1/ui/web/templates/reservations/detail.html +249 -0
- spms-1.2.1/ui/web/templates/reservations/groups.html +89 -0
- spms-1.2.1/ui/web/templates/reservations/list.html +71 -0
- spms-1.2.1/ui/web/templates/settings/approvals.html +70 -0
- spms-1.2.1/ui/web/templates/settings/health.html +25 -0
- spms-1.2.1/ui/web/templates/settings/index.html +230 -0
- spms-1.2.1/ui/web/templates/settings/packages.html +69 -0
- spms-1.2.1/ui/web/templates/settings/rate_plans.html +89 -0
- spms-1.2.1/ui/web/templates/settings/service_catalog.html +56 -0
- spms-1.2.1/ui/web/templates/settings/users.html +55 -0
- spms-1.2.1/ui/web/templates/settings/vouchers.html +56 -0
- spms-1.2.1/ui/web/templates/setup_wizard.html +41 -0
- spms-1.2.1/ui/web/templates/support/report.html +322 -0
- spms-1.2.1/ui/web/templates/unlock.html +14 -0
- spms-1.2.1/ui/web/templates/unlock_recovery.html +17 -0
spms-1.2.1/LICENSE
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
Copyright (c) 2026 Michael Helmy. All rights reserved.
|
|
2
|
+
|
|
3
|
+
This software and associated documentation files (the "Software") are proprietary.
|
|
4
|
+
No license is granted to use, copy, modify, merge, publish, distribute,
|
|
5
|
+
sublicense, and/or sell copies of the Software, in whole or in part, except
|
|
6
|
+
with prior written permission from the copyright holder.
|
|
7
|
+
|
|
8
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
9
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
10
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
11
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
12
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
13
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
14
|
+
SOFTWARE.
|
spms-1.2.1/PKG-INFO
ADDED
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: spms
|
|
3
|
+
Version: 1.2.1
|
|
4
|
+
Summary: SPMS (Super Property Management System) — local-first property management with FastAPI/HTMX web UI (shared core, SQLite-safe single-worker web).
|
|
5
|
+
Author: Michael Helmy
|
|
6
|
+
License: Proprietary
|
|
7
|
+
Project-URL: Homepage, https://github.com/Michaelhehelmy/spms
|
|
8
|
+
Project-URL: Repository, https://github.com/Michaelhehelmy/spms
|
|
9
|
+
Project-URL: Issues, https://github.com/Michaelhehelmy/spms/issues
|
|
10
|
+
Keywords: property,hotel,pms,pos,inventory,fastapi,htmx,sqlite,web
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Environment :: Web Environment
|
|
19
|
+
Classifier: Framework :: FastAPI
|
|
20
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
21
|
+
Classifier: Topic :: Office/Business
|
|
22
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: fastapi>=0.110
|
|
27
|
+
Requires-Dist: uvicorn[standard]>=0.27
|
|
28
|
+
Requires-Dist: jinja2>=3.1
|
|
29
|
+
Requires-Dist: python-multipart>=0.0.9
|
|
30
|
+
Requires-Dist: itsdangerous>=2.1
|
|
31
|
+
Provides-Extra: assistant-ml
|
|
32
|
+
Requires-Dist: scikit-learn>=1.3; extra == "assistant-ml"
|
|
33
|
+
Requires-Dist: joblib>=1.3; extra == "assistant-ml"
|
|
34
|
+
Requires-Dist: setfit>=1.0; extra == "assistant-ml"
|
|
35
|
+
Requires-Dist: sentence-transformers>=2.2; extra == "assistant-ml"
|
|
36
|
+
Provides-Extra: assistant-llm
|
|
37
|
+
Requires-Dist: llama-cpp-python>=0.2; extra == "assistant-llm"
|
|
38
|
+
Provides-Extra: dev
|
|
39
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
40
|
+
Requires-Dist: httpx>=0.24; extra == "dev"
|
|
41
|
+
Requires-Dist: pytest-cov>=4.0; extra == "dev"
|
|
42
|
+
Requires-Dist: ruff>=0.8.0; extra == "dev"
|
|
43
|
+
Provides-Extra: labels
|
|
44
|
+
Provides-Extra: all
|
|
45
|
+
Requires-Dist: spms[dev]; extra == "all"
|
|
46
|
+
Dynamic: license-file
|
|
47
|
+
|
|
48
|
+
# SPMS (Super Property Management System)
|
|
49
|
+
|
|
50
|
+
SPMS (Super Property Management System) — local-first property management with a shared backend and a web frontend:
|
|
51
|
+
|
|
52
|
+
- **Web UI:** FastAPI + HTMX server (`ui.web.server:app`, `launcher.py`, `main.py`) for browser access on desktop/mobile, LAN, or behind a reverse proxy.
|
|
53
|
+
|
|
54
|
+
**Architecture:** all business logic lives in `src/app_core/` (DB, services, paths, assistant, integrity/doctor, updater, barcode/batch logic, support/reporting) and is used by `ui/web/`. SQLite is the datastore.
|
|
55
|
+
|
|
56
|
+
## Current capabilities
|
|
57
|
+
|
|
58
|
+
- **Front desk & reservations:** guests (including 360° portfolio views), rooms/rate plans, availability, create/check-in/checkout flows, folio/balances, payments/refunds where applicable, invoices/receipts.
|
|
59
|
+
- **POS & inventory:** catalog, walk-in and reservation-linked sales, recipes/meals/ingredients with auto-deduction, expenses, and **traceable barcodes/SKUs/lots**.
|
|
60
|
+
- **Batch/lot traceability & FEFO:** inventory supports batch/lot tracking with received date/time, expiry date, remaining/received quantity, unit cost, supplier/reference/notes, status/expiry state, and movements. Supports **FEFO-aware** (First Expired, First Out) workflows, expiring/expired batch review, batch/lot lists, and barcode/SKU/lot trace (resolved item or lot with received/expiry/remaining and recent movements when available).
|
|
61
|
+
- **Activities/trips:** register/book activities/excursions, track bookings/stats, and post charges to folios/invoices.
|
|
62
|
+
- **Accounting, reports & analytics:** ledger, operational/financial reports and analytics/exports (as available in the app).
|
|
63
|
+
- **Grounded assistant (read-only):** Web assistant answers from real app data/tools (ops, reports, guests/portfolios, reservations/balances, inventory including expiring batches, batch lists, barcode/lot trace, activities/bookings, integrity/health, and app version/update status). Assistant follows configured unlock/allowlist policy and remains read-only.
|
|
64
|
+
- **Integrity & health:** read-only ledger/data integrity checks in-app, CLI **doctor** (`python -m app_core.doctor`), safe backup/verify helpers, and web liveness/readiness probes `GET /health`, `GET /healthz`, `GET /readyz`.
|
|
65
|
+
- **Issue reporting (privacy-first):** Web **Report issue** (`/support/report`) and CLI **`python -m app_core.support`** generate sanitized diagnostics (no passwords/secrets/tokens/CSRF/session/recovery codes or DB/guest/payment records), let you review/edit details, download/copy Markdown or JSON reports (including device/OS info and recent in-app steps), open a prefilled GitHub issue, or upload the downloaded JSON report via the landing page (if configured) so it can be delivered to maintainers. Unhandled web errors show a friendly “Report this issue” page with prefilled context.
|
|
66
|
+
- **In-app updates (git installs):** **Settings → App updates** supports **Check for updates**, changelog/commit details, and **Apply/Update** via **git fast-forward**. Local source changes must be committed/stashed/discarded before apply.
|
|
67
|
+
- **Backups & data safety:** create verified DB backups from Settings (**Backup now**, subject to unlock/CSRF as applicable) or CLI/scripts. Runtime data is preserved across source updates; **restore is manual and offline**.
|
|
68
|
+
|
|
69
|
+
## Operational requirements (important)
|
|
70
|
+
|
|
71
|
+
- **SQLite / single worker:** always run the web server with **`--workers 1`**. Do not increase worker count.
|
|
72
|
+
- **Web secret key:** set **`PM_WEB_SECRET_KEY`** to a strong random value for any non-local/shared/LAN/remote deployment.
|
|
73
|
+
- **HTTPS / transport security:** bind to `127.0.0.1` for local-only use. For LAN/remote/browser access, use **HTTPS** (reverse proxy that terminates TLS) or a private network (VPN/Tailscale/SSH tunnel). Do not expose plain HTTP publicly.
|
|
74
|
+
- **Data directory & permissions:** runtime data lives in `PM_DATA_DIR` or app defaults/legacy locations (DB, exports, invoices). Ensure the process user can read/write the data directory and keep a single writer.
|
|
75
|
+
- **Data preserved across updates:** source/app updates (in-app fast-forward or `git pull --ff-only`) do **not** modify runtime data (DB, exports, invoices, configured data dir). DB migrations run on startup and are additive where applicable.
|
|
76
|
+
- **Restart after apply:** after applying an in-app update, **restart the app/server** to load the new version.
|
|
77
|
+
- **Local source changes:** in-app apply requires a clean working tree for fast-forward; commit, stash, or discard local changes first.
|
|
78
|
+
- **Backups before risky operations:** take and verify backups before upgrades/migrations, restores, or major operational changes.
|
|
79
|
+
- **No destructive one-click restore:** restore is deliberate/manual/offline (stop app, verify backup, replace files, start, verify integrity).
|
|
80
|
+
- **Security model:** web state-changing requests are CSRF-protected; sensitive/destructive/admin mutations require **super-password unlock** (and CSRF) per policy, while some routine operational/front-desk flows remain usable with CSRF only. See `docs/web_authz_matrix.md`.
|
|
81
|
+
|
|
82
|
+
## Repository layout
|
|
83
|
+
|
|
84
|
+
```text
|
|
85
|
+
launcher.py # unified web launcher/menu
|
|
86
|
+
main.py # web entry point (compatibility)
|
|
87
|
+
pyproject.toml # packaging metadata, dependencies, extras
|
|
88
|
+
requirements.txt # runtime dependencies (web-only app)
|
|
89
|
+
requirements-dev.txt # dev/test dependencies
|
|
90
|
+
scripts/ # install/setup/update/backup/coverage helpers
|
|
91
|
+
src/app_core/ # shared backend (db, services, paths, assistant, doctor, updater, ...)
|
|
92
|
+
ui/web/ # FastAPI + HTMX web UI
|
|
93
|
+
docs/ # operations, security, deployment, runbooks
|
|
94
|
+
assistant.md # assistant capabilities/evolution/plan
|
|
95
|
+
tests/ # pytest suite
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Quick decision: how to run
|
|
99
|
+
|
|
100
|
+
| Goal | Recommended mode |
|
|
101
|
+
|---|---|
|
|
102
|
+
| Local use on a PC/server | Web UI on `127.0.0.1` (`python launcher.py` / `python main.py`) |
|
|
103
|
+
| Access from phone/tablet browser on same LAN | **Web** bound to `0.0.0.0` behind trusted LAN/VPN and with `PM_WEB_SECRET_KEY`; prefer HTTPS reverse proxy if feasible |
|
|
104
|
+
| Remote access over internet | **Web** behind **HTTPS** reverse proxy / VPN / Tailscale (never plain HTTP public exposure) |
|
|
105
|
+
| iSH (iOS/Alpine, constrained) | Run the Web UI on a supported host when web dependencies/toolchains are unavailable on-device |
|
|
106
|
+
| Android (Termux) | **Web** (`--workers 1`) |
|
|
107
|
+
| Windows desktop/server | `scripts/install_windows.ps1` / `scripts/setup_windows.ps1` or manual venv |
|
|
108
|
+
|
|
109
|
+
## One-line install / update (all supported OS families)
|
|
110
|
+
|
|
111
|
+
These commands are intended for **first-time install and later re-runs** on git-based installs: they bootstrap prerequisites where possible, clone/update (fast-forward), refresh dependencies, preserve runtime data, and launch/run per selected mode. **Always keep web on `--workers 1`**. For shared/non-local/LAN/remote web access, set a strong `PM_WEB_SECRET_KEY` and use **HTTPS** via reverse proxy/VPN/private networking (do not expose plain HTTP publicly). **Built-in recovery:** if an install/update gets stuck due to dirty tree, stale `.git/index.lock`, stuck merge/rebase, or ff-only/checkout errors (e.g. `Reset branch 'main'`), rerun with `REPAIR=1` (Unix/Termux) or `-Repair` / `$env:REPAIR='1'` (Windows) to auto-recover by resetting local source to the target branch (runtime data in `PM_DATA_DIR`/external data dirs is not removed by git).
|
|
112
|
+
|
|
113
|
+
| OS / Environment | One-line command | Notes |
|
|
114
|
+
|---|---|---|
|
|
115
|
+
| **Linux / macOS / WSL / generic Unix** (curl) | `curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Detects environment/package manager, installs/updates, and launches the web app. Re-run anytime. |
|
|
116
|
+
| **Linux / macOS / WSL** (wget) | `wget -qO- https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Fallback if `curl` is unavailable. |
|
|
117
|
+
| **Web server for LAN (trusted network)** | `curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| MODE=web HOST=0.0.0.0 PORT=8000 PM_WEB_SECRET_KEY="$(openssl rand -hex 32)" sh` | `--workers 1` required (SQLite). Use HTTPS reverse proxy/VPN for shared/remote access. |
|
|
118
|
+
| **Android (Termux)** | `pkg update -y && pkg install -y curl && curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Installs/updates and launches web app. For LAN web add `MODE=web HOST=0.0.0.0 PORT=8000 PM_WEB_SECRET_KEY=...` (use HTTPS/proxy for shared access). |
|
|
119
|
+
| **Windows (PowerShell, bootstrap)** | `irm https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.ps1 \| iex` | Uses winget when available to install Python/Git if missing, then clones/updates and runs setup/deploy. Customize via `$env:ACTION/$env:MODE/$env:HOST/$env:PORT/$env:PM_WEB_SECRET_KEY`. |
|
|
120
|
+
| **Windows (CMD bootstrap)** | `curl -fsSL -o install_windows.cmd https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.cmd && install_windows.cmd -Action deploy -Mode auto` | Downloads/runs bootstrap wrapper (uses PowerShell script). |
|
|
121
|
+
|
|
122
|
+
**Common env vars / parameters (Unix installer/setup):** `INSTALL_DIR`, `REPO_URL`, `BRANCH`, `GIT_REF`/`TAG`/`COMMIT` (pinned ref), `MODE` (`web`; legacy values map to web), `ACTION` (`auto|setup|run|deploy`), `SKIP_WEB` (`auto|0|1`), `HOST`, `PORT`, `PYTHON`, `INSTALL_DEV`, `RUN_TESTS`, `PM_DATA_DIR`, `PM_WEB_SECRET_KEY`. **Windows:** pass `-GitRef`/`-Action`/`-Mode`/`-BindHost`/`-Port` or set corresponding env vars (`GIT_REF`/`TAG`/`COMMIT`, etc.).
|
|
123
|
+
|
|
124
|
+
- `ACTION=auto` (default): full install+launch if missing, else update deps/code and launch.
|
|
125
|
+
- `ACTION=setup`: install/update/prepare only. `ACTION=run`: run existing install. `ACTION=deploy`: setup + run.
|
|
126
|
+
- Runtime data (DB/exports/invoices/`PM_DATA_DIR`) is preserved by scripts/updates.
|
|
127
|
+
|
|
128
|
+
### Pinned/reproducible installs
|
|
129
|
+
|
|
130
|
+
- Install/update to a specific tag/commit/branch: `GIT_REF=<tag-or-commit-or-branch> sh` (Unix) or `-GitRef <...>` / `$env:GIT_REF=<...>` (Windows). Aliases: `TAG`, `COMMIT`.
|
|
131
|
+
- **Pinned bootstrap script URL:** use the raw script at the same ref to ensure installer logic is reproducible, e.g. `https://raw.githubusercontent.com/Michaelhehelmy/spms/<tag-or-commit>/scripts/install.sh` (Unix) or `.../<tag-or-commit>/scripts/install_windows.ps1` (Windows).
|
|
132
|
+
- Existing checkouts: `GIT_REF=<tag> ACTION=setup sh scripts/setup.sh` (or Windows setup script) checks out the requested ref; when on a branch, scripts may fast-forward as applicable. Runtime data is preserved.
|
|
133
|
+
- For immutable production-like deployments, prefer pinning to a release tag/commit and recording the resolved commit (`git -C <install-dir> rev-parse HEAD`) alongside backups/change records.
|
|
134
|
+
|
|
135
|
+
### Dependency/install robustness (constrained environments)
|
|
136
|
+
|
|
137
|
+
- **Web dependency/toolchain issues:** if web dependency installation/build fails (e.g. `pydantic-core`/Rust wheel issues on constrained environments), install/upgrade Python/build tools or a compatible prebuilt wheel, or run the web app on a fuller host.
|
|
138
|
+
- **`pydantic-core` / Rust wheel issues:** on iSH/Termux/older CPU architectures or limited toolchains, some web deps may require Rust/cargo/build tools or a prebuilt wheel matching your Python version/architecture. If unavailable, upgrade Python/toolchain, install build deps, or run the Web UI on a supported host.
|
|
139
|
+
- **SQLite web safety:** always run the web server with `--workers 1`. Use `PM_WEB_SECRET_KEY` and HTTPS reverse proxy/VPN for non-local/shared access. Runtime data (`PM_DATA_DIR`, DB, exports, invoices) is preserved across setup/update runs.
|
|
140
|
+
|
|
141
|
+
## Platform-specific setup
|
|
142
|
+
|
|
143
|
+
### Linux / macOS / WSL / Unix-like
|
|
144
|
+
- Use `scripts/install.sh` (bootstrap) or `scripts/setup.sh` from a checkout.
|
|
145
|
+
- Examples: `sh scripts/setup.sh` (setup), `MODE=web ACTION=deploy sh scripts/setup.sh`, `MODE=web HOST=127.0.0.1 PORT=8000 ACTION=deploy sh scripts/setup.sh`.
|
|
146
|
+
- WSL: treat as Linux; bind carefully for LAN access and account for Windows firewall/port forwarding.
|
|
147
|
+
|
|
148
|
+
### Android (Termux)
|
|
149
|
+
```sh
|
|
150
|
+
pkg update && pkg install -y git python curl
|
|
151
|
+
curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh | sh
|
|
152
|
+
# or web on LAN (trusted network): add MODE=web HOST=0.0.0.0 PORT=8000 and PM_WEB_SECRET_KEY
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### iOS (iSH / Alpine)
|
|
156
|
+
```sh
|
|
157
|
+
apk add --no-cache curl
|
|
158
|
+
curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh | MODE=web sh
|
|
159
|
+
```
|
|
160
|
+
If web dependencies cannot be built on-device, run the Web UI on a supported host and access it from the browser.
|
|
161
|
+
|
|
162
|
+
### iOS/iPadOS as web client
|
|
163
|
+
Run the server on a capable host (Mac/Linux/Windows/Termux/RPi/VPS) and open from Safari (`http://<host>:8000` on LAN or `https://...` via reverse proxy/Tailscale/VPN). Add to Home Screen for app-like use.
|
|
164
|
+
|
|
165
|
+
### Windows (10/11, Server)
|
|
166
|
+
- **Bootstrap (recommended):** PowerShell (Admin recommended for winget):
|
|
167
|
+
```powershell
|
|
168
|
+
irm https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.ps1 | iex
|
|
169
|
+
```
|
|
170
|
+
Customize: `$env:ACTION='deploy'; $env:MODE='web'; $env:HOST='127.0.0.1'; $env:PORT='8000'; $env:PM_WEB_SECRET_KEY='...'; irm ... | iex`
|
|
171
|
+
- **From existing checkout:**
|
|
172
|
+
```powershell
|
|
173
|
+
powershell -ExecutionPolicy Bypass -File scripts\install_windows.ps1 -Action deploy -Mode web
|
|
174
|
+
powershell -ExecutionPolicy Bypass -File scripts\setup_windows.ps1 -Action deploy -Mode web -BindHost 127.0.0.1 -Port 8000
|
|
175
|
+
scripts\install_windows.cmd -Action deploy -Mode auto
|
|
176
|
+
```
|
|
177
|
+
- If winget is unavailable, install Python 3.10+ (PATH) and Git, then re-run. Scripts attempt to refresh PATH/bootstrap prerequisites.
|
|
178
|
+
|
|
179
|
+
### Manual install (any OS with Python)
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
git clone https://github.com/Michaelhehelmy/spms.git
|
|
183
|
+
cd spms
|
|
184
|
+
python3 -m venv .venv
|
|
185
|
+
# activate: Unix `. .venv/bin/activate` | PowerShell `.\\.venv\\Scripts\\Activate.ps1` | cmd `.venv\\Scripts\\activate.bat`
|
|
186
|
+
pip install -r requirements.txt # runtime dependencies (web-only app)
|
|
187
|
+
# optional dev/test deps: pip install -r requirements-dev.txt
|
|
188
|
+
python launcher.py # menu
|
|
189
|
+
python launcher.py --web --host 127.0.0.1 --port 8000
|
|
190
|
+
# direct web server (always --workers 1):
|
|
191
|
+
PYTHONPATH=src python -m uvicorn ui.web.server:app --host 127.0.0.1 --port 8000 --workers 1
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`pyproject.toml` also defines extras/scripts (`.[web]`, `.[dev]`, `property-manager`, `pm`, etc.) for packaging workflows.
|
|
195
|
+
|
|
196
|
+
## Web deployment essentials
|
|
197
|
+
|
|
198
|
+
- **Workers:** `--workers 1` only (SQLite/shared state). Never increase workers.
|
|
199
|
+
- **Bind:** `127.0.0.1` local-only; `0.0.0.0` reachable on interfaces (LAN). Manage firewall exposure explicitly.
|
|
200
|
+
- **Secret:** set `PM_WEB_SECRET_KEY` to a strong random value for any non-local/shared deployment (required for non-loopback use unless an explicit local/dev insecure override is set).
|
|
201
|
+
- **TLS/remote access:** use reverse proxy with HTTPS or a private network (VPN/Tailscale/SSH tunnel). Do not expose plain HTTP publicly.
|
|
202
|
+
- **Data directory & permissions:** set `PM_DATA_DIR` if needed; ensure the service user can read/write the data directory and run with a single writer.
|
|
203
|
+
- **Health probes:** `GET /health` and `GET /healthz` (liveness/basic health with readiness summary), `GET /readyz` (readiness/runtime checks including data-dir writability). Keep probes and app on `--workers 1`.
|
|
204
|
+
- **Service/autostart:** use systemd/launchd/NSSM/Task Scheduler/supervisor/Docker restart policy to run venv Python/uvicorn with `--workers 1`.
|
|
205
|
+
- **Reverse proxy:** proxy to `127.0.0.1:8000`, terminate TLS, and forward standard proxy headers as needed.
|
|
206
|
+
- **Backups, restore, updates:** take and verify backups before upgrades/migrations; restore is manual/offline (with restore drill validation recommended); restart the app/server after applying updates.
|
|
207
|
+
- **App icon / launcher:** no native installer icons are bundled. For browser/mobile install use "Add to Home Screen" (add PWA assets like `manifest.webmanifest` and icons under `ui/web/static/` and link from `ui/web/templates/base.html` if needed); for Windows/Linux create OS shortcuts (`.lnk`/`.desktop`) pointing to the venv launcher with a custom icon.
|
|
208
|
+
- See `docs/DEPLOYMENT.md` and `docs/SECURITY.md` for examples and hardening.
|
|
209
|
+
|
|
210
|
+
## Security model (Web) — summary
|
|
211
|
+
|
|
212
|
+
- **CSRF:** all state-changing web requests (POST/PUT/PATCH/DELETE) are CSRF-protected (form tokens and/or header/middleware enforcement per request type).
|
|
213
|
+
- **Super-password unlock:** sensitive/destructive/admin mutations require active unlock (super password) in addition to CSRF (financial/accounting operations, inventory/stock/batch/recipe/meal/activity changes, voids/refunds/cancels/deletes/modifications, exports/backups/seed/demo/settings changes, labels, protected downloads where applicable, etc.).
|
|
214
|
+
- **Routine operational flows:** some front-desk/POS operations may remain usable with CSRF where appropriate, but policy-sensitive overrides/destructive actions remain gated by unlock.
|
|
215
|
+
- **Assistant:** follows configured unlock/allowlist policy while remaining read-only and grounded.
|
|
216
|
+
- **Secrets & transport:** strong `PM_WEB_SECRET_KEY`, HTTPS/private networking for shared/remote access.
|
|
217
|
+
- **Reference:** `docs/web_authz_matrix.md` is the authoritative route-group matrix for `ui/web`. See `docs/SECURITY.md` for hardening checklist.
|
|
218
|
+
|
|
219
|
+
## Updates
|
|
220
|
+
|
|
221
|
+
**In-app (recommended for git installs):** **Settings → Updates & Health → App updates** → **Check for updates** → **Update now / Apply** appears **only when an update is available** (git fast-forward for clean checkouts).
|
|
222
|
+
|
|
223
|
+
- **Automated:** check/fetch metadata, show changelog/commits, apply ff-only when eligible.
|
|
224
|
+
- **Requirements/limits:** clean working tree required; non-fast-forward/diverged histories need manual git resolution.
|
|
225
|
+
- **Data preserved:** DB, exports, invoices, and configured data directory (`PM_DATA_DIR`/defaults) are not modified by source updates.
|
|
226
|
+
- **After apply:** **restart the app/server** to load the new version. If dependencies changed, refresh the venv via setup scripts.
|
|
227
|
+
- **Update notifications (auto-check):** built-in polling-based checks run when online (cached/rate-limited, configurable via `auto_check_updates` / `auto_update_check_interval_hours`) and notify in the web UI when updates/releases are available. Git installs can be applied in-app (ff-only) then restarted; native/packaged installs require downloading/installing the new release artifact. No push infrastructure; auto-apply is not enabled by default.
|
|
228
|
+
- **First-time update / platform guides:** Windows: rerun `scripts/install_windows.ps1` (or `git pull --ff-only` + `scripts\setup_windows.ps1 -Action setup`) then restart. Termux: rerun `scripts/install.sh` with `MODE=web ... --workers 1` (or manual ff-only + setup) then restart. Details in `docs/UPDATES.md`.
|
|
229
|
+
- **Manual CLI:** `git pull --ff-only` then re-run setup to refresh deps if needed (Unix/Termux: `MODE=<...> ACTION=setup sh scripts/setup.sh`, Windows: `scripts\setup_windows.ps1 -Action setup`).
|
|
230
|
+
|
|
231
|
+
See `docs/UPDATES.md` for release/update/rollback guidance.
|
|
232
|
+
|
|
233
|
+
## Integrity, health checks & doctor
|
|
234
|
+
|
|
235
|
+
- **In-app (read-only):** ledger/data integrity checks available in Web UI and via grounded assistant queries.
|
|
236
|
+
- **CLI doctor:** `PYTHONPATH=src python -m app_core.doctor` (or `scripts/backup_runtime.* --doctor`) for operational health checks. Supports `--json`, `--check-updates`, `--strict`, and safe backup/verify helpers: `--backup [--backup-to <path>]`, `--verify-backup <path>` / `--verify`.
|
|
237
|
+
- **Web probes:** `GET /health`, `GET /healthz`, `GET /readyz` for liveness/readiness (and detailed readiness checks).
|
|
238
|
+
|
|
239
|
+
## Backups & restore
|
|
240
|
+
|
|
241
|
+
- **Create backups (automated/helpers):**
|
|
242
|
+
- Web UI: **Settings → Backup now** (subject to unlock/CSRF as applicable).
|
|
243
|
+
- CLI: `python3 scripts/backup_runtime.py --backup [--to <path>]`, `python3 scripts/backup_runtime.py --verify <backup.db>`, `python3 scripts/backup_runtime.py --doctor [--json] [--check-updates]`, or `PYTHONPATH=src python -m app_core.doctor --backup/--verify-backup`.
|
|
244
|
+
- Wrappers: `scripts/backup_runtime.sh`, `scripts/backup_runtime.cmd`, `scripts/backup_runtime.ps1`.
|
|
245
|
+
- **Preserve:** DB, exports, invoices, and data dir (`PM_DATA_DIR` or defaults). Take backups regularly and before upgrades/migrations.
|
|
246
|
+
- **Restore (manual, offline):** no destructive one-click in-app restore.
|
|
247
|
+
1. Stop app/server.
|
|
248
|
+
2. Verify candidate backup (`--verify` / `--verify-backup`).
|
|
249
|
+
3. Copy current DB/files as safety backup.
|
|
250
|
+
4. Replace active DB (and related exports/invoices if needed) with verified backup in the correct data directory.
|
|
251
|
+
5. Start app/server (`--workers 1` for web); migrations run on startup.
|
|
252
|
+
6. Verify with doctor/integrity checks and app smoke tests.
|
|
253
|
+
|
|
254
|
+
See `docs/BACKUP_RESTORE.md` for DR guidance.
|
|
255
|
+
|
|
256
|
+
## Tests & checks
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
python -m py_compile src/app_core/*.py ui/web/*.py main.py launcher.py
|
|
260
|
+
PYTHONPATH=src pytest -q
|
|
261
|
+
pytest --cov=src/app_core --cov=ui --cov-report=term-missing --cov-report=xml:coverage.xml
|
|
262
|
+
python -m pip install -r requirements.txt -r requirements-dev.txt && python -m pytest -q
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
## Troubleshooting (quick)
|
|
266
|
+
|
|
267
|
+
- **Web deps/build issues (iSH/limited toolchains):** use `SKIP_WEB=0 MODE=web`.
|
|
268
|
+
- **`venv` missing:** install distro Python venv package (e.g. `python3-venv`) or re-run setup scripts.
|
|
269
|
+
- **Port in use / unreachable:** change `PORT`, bind correct `HOST`, allow firewall, verify LAN IP/proxy.
|
|
270
|
+
- **DB/permission issues:** ensure writable data dir (`PM_DATA_DIR`/defaults), single writer, `--workers 1` for web.
|
|
271
|
+
- **Update apply blocked:** commit/stash/discard local changes or resolve non-fast-forward state manually.
|
|
272
|
+
|
|
273
|
+
See `docs/TROUBLESHOOTING.md`.
|
|
274
|
+
|
|
275
|
+
## Packaging & install formats
|
|
276
|
+
|
|
277
|
+
- **Python package (wheel/sdist):** `pyproject.toml` builds distributable packages including web UI assets (`ui/web/templates`, `ui/web/static`, PWA manifest/icons/service worker). CI workflow: `.github/workflows/release-python-package.yml` (artifacts on tags/dispatch; optional PyPI publish via `PYPI_API_TOKEN`).
|
|
278
|
+
- **Container image (GHCR):** multi-arch image published by `.github/workflows/release-container.yml` to `ghcr.io/michaelhehelmy/spms` (run with `--workers 1`, persistent `PM_DATA_DIR`).
|
|
279
|
+
- **Native binaries:** Nuitka builds via `.github/workflows/release-native.yml` (Windows `.exe`, Linux binary/AppImage path, macOS `.dmg`). See `docs/NATIVE_BUILDS.md`.
|
|
280
|
+
- **PWA / installable web app:** manifest, icons, and a minimal service worker are served from `ui/web/static/` for “Add to Home Screen / Install app” (best over HTTPS for non-localhost).
|
|
281
|
+
- **Kubernetes/Helm:** chart skeleton in `deploy/helm/spms` (single-replica, SQLite-safe `--workers 1`, persistent data volume, probes).
|
|
282
|
+
- **Linux packages scaffolds:** Debian/Ubuntu `.deb` (`deploy/packaging/deb/build-deb.sh`) and RPM (`deploy/packaging/rpm/build-rpm.sh`, `SPECS/spms.spec`) with `spms-web` systemd service and `/etc/spms/spms.env`.
|
|
283
|
+
- **Android WebView wrapper scaffold:** `deploy/mobile/android-webview/` (configurable SPMS URL; reuse web UI/PWA).
|
|
284
|
+
- **Planned/optional (external/signing/hardening):** Windows/macOS installers (signed/notarized), TWA/store packaging. Details and roadmap: `docs/PACKAGING.md`.
|
|
285
|
+
|
|
286
|
+
## More documentation
|
|
287
|
+
|
|
288
|
+
- `assistant.md` — assistant capabilities, grounded/read-only behavior, evolution and plan.
|
|
289
|
+
- `docs/PACKAGING.md` — packaging/distribution formats, modularization boundaries, and implementation roadmap/status.
|
|
290
|
+
- `docs/NATIVE_BUILDS.md` — Nuitka/native standalone build and release packaging guidance (GitHub Releases assets auto-detected by landing page). Landing page can also accept uploaded JSON issue reports via Cloudflare Pages Function (`functions/api/report.js`) when configured with secrets (e.g. `REPORT_GITHUB_TOKEN`, optional `REPORT_GITHUB_REPO`/`REPORT_GITHUB_LABELS`) to create GitHub issues for maintainers.
|
|
291
|
+
- `docs/PRODUCTION_ROADMAP.md` — phased P0–P3 production hardening/operations roadmap and checklist.
|
|
292
|
+
- `docs/DEPLOYMENT.md` — local/LAN/remote deployment, reverse proxy + HTTPS, systemd/Docker guidance.
|
|
293
|
+
- `docs/SECURITY.md` — hardening checklist, secrets/cookies, authz/unlock/CSRF, printer/file/data handling.
|
|
294
|
+
- `docs/BACKUP_RESTORE.md` — backup, verify, restore, DR, data preservation.
|
|
295
|
+
- `docs/UPDATES.md` — release/update/rollback guidance.
|
|
296
|
+
- `docs/TROUBLESHOOTING.md` — common issues and diagnostics.
|
|
297
|
+
- `docs/GO_LIVE_CHECKLIST.md` — operational go-live steps (monitoring, domain/TLS, backups, pilot, etc.).
|
|
298
|
+
- `docs/web_authz_matrix.md` — web route-group authz/CSRF/unlock reference (authoritative for `ui/web`).
|
spms-1.2.1/README.md
ADDED
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
# SPMS (Super Property Management System)
|
|
2
|
+
|
|
3
|
+
SPMS (Super Property Management System) — local-first property management with a shared backend and a web frontend:
|
|
4
|
+
|
|
5
|
+
- **Web UI:** FastAPI + HTMX server (`ui.web.server:app`, `launcher.py`, `main.py`) for browser access on desktop/mobile, LAN, or behind a reverse proxy.
|
|
6
|
+
|
|
7
|
+
**Architecture:** all business logic lives in `src/app_core/` (DB, services, paths, assistant, integrity/doctor, updater, barcode/batch logic, support/reporting) and is used by `ui/web/`. SQLite is the datastore.
|
|
8
|
+
|
|
9
|
+
## Current capabilities
|
|
10
|
+
|
|
11
|
+
- **Front desk & reservations:** guests (including 360° portfolio views), rooms/rate plans, availability, create/check-in/checkout flows, folio/balances, payments/refunds where applicable, invoices/receipts.
|
|
12
|
+
- **POS & inventory:** catalog, walk-in and reservation-linked sales, recipes/meals/ingredients with auto-deduction, expenses, and **traceable barcodes/SKUs/lots**.
|
|
13
|
+
- **Batch/lot traceability & FEFO:** inventory supports batch/lot tracking with received date/time, expiry date, remaining/received quantity, unit cost, supplier/reference/notes, status/expiry state, and movements. Supports **FEFO-aware** (First Expired, First Out) workflows, expiring/expired batch review, batch/lot lists, and barcode/SKU/lot trace (resolved item or lot with received/expiry/remaining and recent movements when available).
|
|
14
|
+
- **Activities/trips:** register/book activities/excursions, track bookings/stats, and post charges to folios/invoices.
|
|
15
|
+
- **Accounting, reports & analytics:** ledger, operational/financial reports and analytics/exports (as available in the app).
|
|
16
|
+
- **Grounded assistant (read-only):** Web assistant answers from real app data/tools (ops, reports, guests/portfolios, reservations/balances, inventory including expiring batches, batch lists, barcode/lot trace, activities/bookings, integrity/health, and app version/update status). Assistant follows configured unlock/allowlist policy and remains read-only.
|
|
17
|
+
- **Integrity & health:** read-only ledger/data integrity checks in-app, CLI **doctor** (`python -m app_core.doctor`), safe backup/verify helpers, and web liveness/readiness probes `GET /health`, `GET /healthz`, `GET /readyz`.
|
|
18
|
+
- **Issue reporting (privacy-first):** Web **Report issue** (`/support/report`) and CLI **`python -m app_core.support`** generate sanitized diagnostics (no passwords/secrets/tokens/CSRF/session/recovery codes or DB/guest/payment records), let you review/edit details, download/copy Markdown or JSON reports (including device/OS info and recent in-app steps), open a prefilled GitHub issue, or upload the downloaded JSON report via the landing page (if configured) so it can be delivered to maintainers. Unhandled web errors show a friendly “Report this issue” page with prefilled context.
|
|
19
|
+
- **In-app updates (git installs):** **Settings → App updates** supports **Check for updates**, changelog/commit details, and **Apply/Update** via **git fast-forward**. Local source changes must be committed/stashed/discarded before apply.
|
|
20
|
+
- **Backups & data safety:** create verified DB backups from Settings (**Backup now**, subject to unlock/CSRF as applicable) or CLI/scripts. Runtime data is preserved across source updates; **restore is manual and offline**.
|
|
21
|
+
|
|
22
|
+
## Operational requirements (important)
|
|
23
|
+
|
|
24
|
+
- **SQLite / single worker:** always run the web server with **`--workers 1`**. Do not increase worker count.
|
|
25
|
+
- **Web secret key:** set **`PM_WEB_SECRET_KEY`** to a strong random value for any non-local/shared/LAN/remote deployment.
|
|
26
|
+
- **HTTPS / transport security:** bind to `127.0.0.1` for local-only use. For LAN/remote/browser access, use **HTTPS** (reverse proxy that terminates TLS) or a private network (VPN/Tailscale/SSH tunnel). Do not expose plain HTTP publicly.
|
|
27
|
+
- **Data directory & permissions:** runtime data lives in `PM_DATA_DIR` or app defaults/legacy locations (DB, exports, invoices). Ensure the process user can read/write the data directory and keep a single writer.
|
|
28
|
+
- **Data preserved across updates:** source/app updates (in-app fast-forward or `git pull --ff-only`) do **not** modify runtime data (DB, exports, invoices, configured data dir). DB migrations run on startup and are additive where applicable.
|
|
29
|
+
- **Restart after apply:** after applying an in-app update, **restart the app/server** to load the new version.
|
|
30
|
+
- **Local source changes:** in-app apply requires a clean working tree for fast-forward; commit, stash, or discard local changes first.
|
|
31
|
+
- **Backups before risky operations:** take and verify backups before upgrades/migrations, restores, or major operational changes.
|
|
32
|
+
- **No destructive one-click restore:** restore is deliberate/manual/offline (stop app, verify backup, replace files, start, verify integrity).
|
|
33
|
+
- **Security model:** web state-changing requests are CSRF-protected; sensitive/destructive/admin mutations require **super-password unlock** (and CSRF) per policy, while some routine operational/front-desk flows remain usable with CSRF only. See `docs/web_authz_matrix.md`.
|
|
34
|
+
|
|
35
|
+
## Repository layout
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
launcher.py # unified web launcher/menu
|
|
39
|
+
main.py # web entry point (compatibility)
|
|
40
|
+
pyproject.toml # packaging metadata, dependencies, extras
|
|
41
|
+
requirements.txt # runtime dependencies (web-only app)
|
|
42
|
+
requirements-dev.txt # dev/test dependencies
|
|
43
|
+
scripts/ # install/setup/update/backup/coverage helpers
|
|
44
|
+
src/app_core/ # shared backend (db, services, paths, assistant, doctor, updater, ...)
|
|
45
|
+
ui/web/ # FastAPI + HTMX web UI
|
|
46
|
+
docs/ # operations, security, deployment, runbooks
|
|
47
|
+
assistant.md # assistant capabilities/evolution/plan
|
|
48
|
+
tests/ # pytest suite
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Quick decision: how to run
|
|
52
|
+
|
|
53
|
+
| Goal | Recommended mode |
|
|
54
|
+
|---|---|
|
|
55
|
+
| Local use on a PC/server | Web UI on `127.0.0.1` (`python launcher.py` / `python main.py`) |
|
|
56
|
+
| Access from phone/tablet browser on same LAN | **Web** bound to `0.0.0.0` behind trusted LAN/VPN and with `PM_WEB_SECRET_KEY`; prefer HTTPS reverse proxy if feasible |
|
|
57
|
+
| Remote access over internet | **Web** behind **HTTPS** reverse proxy / VPN / Tailscale (never plain HTTP public exposure) |
|
|
58
|
+
| iSH (iOS/Alpine, constrained) | Run the Web UI on a supported host when web dependencies/toolchains are unavailable on-device |
|
|
59
|
+
| Android (Termux) | **Web** (`--workers 1`) |
|
|
60
|
+
| Windows desktop/server | `scripts/install_windows.ps1` / `scripts/setup_windows.ps1` or manual venv |
|
|
61
|
+
|
|
62
|
+
## One-line install / update (all supported OS families)
|
|
63
|
+
|
|
64
|
+
These commands are intended for **first-time install and later re-runs** on git-based installs: they bootstrap prerequisites where possible, clone/update (fast-forward), refresh dependencies, preserve runtime data, and launch/run per selected mode. **Always keep web on `--workers 1`**. For shared/non-local/LAN/remote web access, set a strong `PM_WEB_SECRET_KEY` and use **HTTPS** via reverse proxy/VPN/private networking (do not expose plain HTTP publicly). **Built-in recovery:** if an install/update gets stuck due to dirty tree, stale `.git/index.lock`, stuck merge/rebase, or ff-only/checkout errors (e.g. `Reset branch 'main'`), rerun with `REPAIR=1` (Unix/Termux) or `-Repair` / `$env:REPAIR='1'` (Windows) to auto-recover by resetting local source to the target branch (runtime data in `PM_DATA_DIR`/external data dirs is not removed by git).
|
|
65
|
+
|
|
66
|
+
| OS / Environment | One-line command | Notes |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| **Linux / macOS / WSL / generic Unix** (curl) | `curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Detects environment/package manager, installs/updates, and launches the web app. Re-run anytime. |
|
|
69
|
+
| **Linux / macOS / WSL** (wget) | `wget -qO- https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Fallback if `curl` is unavailable. |
|
|
70
|
+
| **Web server for LAN (trusted network)** | `curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| MODE=web HOST=0.0.0.0 PORT=8000 PM_WEB_SECRET_KEY="$(openssl rand -hex 32)" sh` | `--workers 1` required (SQLite). Use HTTPS reverse proxy/VPN for shared/remote access. |
|
|
71
|
+
| **Android (Termux)** | `pkg update -y && pkg install -y curl && curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh \| sh` | Installs/updates and launches web app. For LAN web add `MODE=web HOST=0.0.0.0 PORT=8000 PM_WEB_SECRET_KEY=...` (use HTTPS/proxy for shared access). |
|
|
72
|
+
| **Windows (PowerShell, bootstrap)** | `irm https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.ps1 \| iex` | Uses winget when available to install Python/Git if missing, then clones/updates and runs setup/deploy. Customize via `$env:ACTION/$env:MODE/$env:HOST/$env:PORT/$env:PM_WEB_SECRET_KEY`. |
|
|
73
|
+
| **Windows (CMD bootstrap)** | `curl -fsSL -o install_windows.cmd https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.cmd && install_windows.cmd -Action deploy -Mode auto` | Downloads/runs bootstrap wrapper (uses PowerShell script). |
|
|
74
|
+
|
|
75
|
+
**Common env vars / parameters (Unix installer/setup):** `INSTALL_DIR`, `REPO_URL`, `BRANCH`, `GIT_REF`/`TAG`/`COMMIT` (pinned ref), `MODE` (`web`; legacy values map to web), `ACTION` (`auto|setup|run|deploy`), `SKIP_WEB` (`auto|0|1`), `HOST`, `PORT`, `PYTHON`, `INSTALL_DEV`, `RUN_TESTS`, `PM_DATA_DIR`, `PM_WEB_SECRET_KEY`. **Windows:** pass `-GitRef`/`-Action`/`-Mode`/`-BindHost`/`-Port` or set corresponding env vars (`GIT_REF`/`TAG`/`COMMIT`, etc.).
|
|
76
|
+
|
|
77
|
+
- `ACTION=auto` (default): full install+launch if missing, else update deps/code and launch.
|
|
78
|
+
- `ACTION=setup`: install/update/prepare only. `ACTION=run`: run existing install. `ACTION=deploy`: setup + run.
|
|
79
|
+
- Runtime data (DB/exports/invoices/`PM_DATA_DIR`) is preserved by scripts/updates.
|
|
80
|
+
|
|
81
|
+
### Pinned/reproducible installs
|
|
82
|
+
|
|
83
|
+
- Install/update to a specific tag/commit/branch: `GIT_REF=<tag-or-commit-or-branch> sh` (Unix) or `-GitRef <...>` / `$env:GIT_REF=<...>` (Windows). Aliases: `TAG`, `COMMIT`.
|
|
84
|
+
- **Pinned bootstrap script URL:** use the raw script at the same ref to ensure installer logic is reproducible, e.g. `https://raw.githubusercontent.com/Michaelhehelmy/spms/<tag-or-commit>/scripts/install.sh` (Unix) or `.../<tag-or-commit>/scripts/install_windows.ps1` (Windows).
|
|
85
|
+
- Existing checkouts: `GIT_REF=<tag> ACTION=setup sh scripts/setup.sh` (or Windows setup script) checks out the requested ref; when on a branch, scripts may fast-forward as applicable. Runtime data is preserved.
|
|
86
|
+
- For immutable production-like deployments, prefer pinning to a release tag/commit and recording the resolved commit (`git -C <install-dir> rev-parse HEAD`) alongside backups/change records.
|
|
87
|
+
|
|
88
|
+
### Dependency/install robustness (constrained environments)
|
|
89
|
+
|
|
90
|
+
- **Web dependency/toolchain issues:** if web dependency installation/build fails (e.g. `pydantic-core`/Rust wheel issues on constrained environments), install/upgrade Python/build tools or a compatible prebuilt wheel, or run the web app on a fuller host.
|
|
91
|
+
- **`pydantic-core` / Rust wheel issues:** on iSH/Termux/older CPU architectures or limited toolchains, some web deps may require Rust/cargo/build tools or a prebuilt wheel matching your Python version/architecture. If unavailable, upgrade Python/toolchain, install build deps, or run the Web UI on a supported host.
|
|
92
|
+
- **SQLite web safety:** always run the web server with `--workers 1`. Use `PM_WEB_SECRET_KEY` and HTTPS reverse proxy/VPN for non-local/shared access. Runtime data (`PM_DATA_DIR`, DB, exports, invoices) is preserved across setup/update runs.
|
|
93
|
+
|
|
94
|
+
## Platform-specific setup
|
|
95
|
+
|
|
96
|
+
### Linux / macOS / WSL / Unix-like
|
|
97
|
+
- Use `scripts/install.sh` (bootstrap) or `scripts/setup.sh` from a checkout.
|
|
98
|
+
- Examples: `sh scripts/setup.sh` (setup), `MODE=web ACTION=deploy sh scripts/setup.sh`, `MODE=web HOST=127.0.0.1 PORT=8000 ACTION=deploy sh scripts/setup.sh`.
|
|
99
|
+
- WSL: treat as Linux; bind carefully for LAN access and account for Windows firewall/port forwarding.
|
|
100
|
+
|
|
101
|
+
### Android (Termux)
|
|
102
|
+
```sh
|
|
103
|
+
pkg update && pkg install -y git python curl
|
|
104
|
+
curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh | sh
|
|
105
|
+
# or web on LAN (trusted network): add MODE=web HOST=0.0.0.0 PORT=8000 and PM_WEB_SECRET_KEY
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### iOS (iSH / Alpine)
|
|
109
|
+
```sh
|
|
110
|
+
apk add --no-cache curl
|
|
111
|
+
curl -fsSL https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install.sh | MODE=web sh
|
|
112
|
+
```
|
|
113
|
+
If web dependencies cannot be built on-device, run the Web UI on a supported host and access it from the browser.
|
|
114
|
+
|
|
115
|
+
### iOS/iPadOS as web client
|
|
116
|
+
Run the server on a capable host (Mac/Linux/Windows/Termux/RPi/VPS) and open from Safari (`http://<host>:8000` on LAN or `https://...` via reverse proxy/Tailscale/VPN). Add to Home Screen for app-like use.
|
|
117
|
+
|
|
118
|
+
### Windows (10/11, Server)
|
|
119
|
+
- **Bootstrap (recommended):** PowerShell (Admin recommended for winget):
|
|
120
|
+
```powershell
|
|
121
|
+
irm https://raw.githubusercontent.com/Michaelhehelmy/spms/main/scripts/install_windows.ps1 | iex
|
|
122
|
+
```
|
|
123
|
+
Customize: `$env:ACTION='deploy'; $env:MODE='web'; $env:HOST='127.0.0.1'; $env:PORT='8000'; $env:PM_WEB_SECRET_KEY='...'; irm ... | iex`
|
|
124
|
+
- **From existing checkout:**
|
|
125
|
+
```powershell
|
|
126
|
+
powershell -ExecutionPolicy Bypass -File scripts\install_windows.ps1 -Action deploy -Mode web
|
|
127
|
+
powershell -ExecutionPolicy Bypass -File scripts\setup_windows.ps1 -Action deploy -Mode web -BindHost 127.0.0.1 -Port 8000
|
|
128
|
+
scripts\install_windows.cmd -Action deploy -Mode auto
|
|
129
|
+
```
|
|
130
|
+
- If winget is unavailable, install Python 3.10+ (PATH) and Git, then re-run. Scripts attempt to refresh PATH/bootstrap prerequisites.
|
|
131
|
+
|
|
132
|
+
### Manual install (any OS with Python)
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
git clone https://github.com/Michaelhehelmy/spms.git
|
|
136
|
+
cd spms
|
|
137
|
+
python3 -m venv .venv
|
|
138
|
+
# activate: Unix `. .venv/bin/activate` | PowerShell `.\\.venv\\Scripts\\Activate.ps1` | cmd `.venv\\Scripts\\activate.bat`
|
|
139
|
+
pip install -r requirements.txt # runtime dependencies (web-only app)
|
|
140
|
+
# optional dev/test deps: pip install -r requirements-dev.txt
|
|
141
|
+
python launcher.py # menu
|
|
142
|
+
python launcher.py --web --host 127.0.0.1 --port 8000
|
|
143
|
+
# direct web server (always --workers 1):
|
|
144
|
+
PYTHONPATH=src python -m uvicorn ui.web.server:app --host 127.0.0.1 --port 8000 --workers 1
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
`pyproject.toml` also defines extras/scripts (`.[web]`, `.[dev]`, `property-manager`, `pm`, etc.) for packaging workflows.
|
|
148
|
+
|
|
149
|
+
## Web deployment essentials
|
|
150
|
+
|
|
151
|
+
- **Workers:** `--workers 1` only (SQLite/shared state). Never increase workers.
|
|
152
|
+
- **Bind:** `127.0.0.1` local-only; `0.0.0.0` reachable on interfaces (LAN). Manage firewall exposure explicitly.
|
|
153
|
+
- **Secret:** set `PM_WEB_SECRET_KEY` to a strong random value for any non-local/shared deployment (required for non-loopback use unless an explicit local/dev insecure override is set).
|
|
154
|
+
- **TLS/remote access:** use reverse proxy with HTTPS or a private network (VPN/Tailscale/SSH tunnel). Do not expose plain HTTP publicly.
|
|
155
|
+
- **Data directory & permissions:** set `PM_DATA_DIR` if needed; ensure the service user can read/write the data directory and run with a single writer.
|
|
156
|
+
- **Health probes:** `GET /health` and `GET /healthz` (liveness/basic health with readiness summary), `GET /readyz` (readiness/runtime checks including data-dir writability). Keep probes and app on `--workers 1`.
|
|
157
|
+
- **Service/autostart:** use systemd/launchd/NSSM/Task Scheduler/supervisor/Docker restart policy to run venv Python/uvicorn with `--workers 1`.
|
|
158
|
+
- **Reverse proxy:** proxy to `127.0.0.1:8000`, terminate TLS, and forward standard proxy headers as needed.
|
|
159
|
+
- **Backups, restore, updates:** take and verify backups before upgrades/migrations; restore is manual/offline (with restore drill validation recommended); restart the app/server after applying updates.
|
|
160
|
+
- **App icon / launcher:** no native installer icons are bundled. For browser/mobile install use "Add to Home Screen" (add PWA assets like `manifest.webmanifest` and icons under `ui/web/static/` and link from `ui/web/templates/base.html` if needed); for Windows/Linux create OS shortcuts (`.lnk`/`.desktop`) pointing to the venv launcher with a custom icon.
|
|
161
|
+
- See `docs/DEPLOYMENT.md` and `docs/SECURITY.md` for examples and hardening.
|
|
162
|
+
|
|
163
|
+
## Security model (Web) — summary
|
|
164
|
+
|
|
165
|
+
- **CSRF:** all state-changing web requests (POST/PUT/PATCH/DELETE) are CSRF-protected (form tokens and/or header/middleware enforcement per request type).
|
|
166
|
+
- **Super-password unlock:** sensitive/destructive/admin mutations require active unlock (super password) in addition to CSRF (financial/accounting operations, inventory/stock/batch/recipe/meal/activity changes, voids/refunds/cancels/deletes/modifications, exports/backups/seed/demo/settings changes, labels, protected downloads where applicable, etc.).
|
|
167
|
+
- **Routine operational flows:** some front-desk/POS operations may remain usable with CSRF where appropriate, but policy-sensitive overrides/destructive actions remain gated by unlock.
|
|
168
|
+
- **Assistant:** follows configured unlock/allowlist policy while remaining read-only and grounded.
|
|
169
|
+
- **Secrets & transport:** strong `PM_WEB_SECRET_KEY`, HTTPS/private networking for shared/remote access.
|
|
170
|
+
- **Reference:** `docs/web_authz_matrix.md` is the authoritative route-group matrix for `ui/web`. See `docs/SECURITY.md` for hardening checklist.
|
|
171
|
+
|
|
172
|
+
## Updates
|
|
173
|
+
|
|
174
|
+
**In-app (recommended for git installs):** **Settings → Updates & Health → App updates** → **Check for updates** → **Update now / Apply** appears **only when an update is available** (git fast-forward for clean checkouts).
|
|
175
|
+
|
|
176
|
+
- **Automated:** check/fetch metadata, show changelog/commits, apply ff-only when eligible.
|
|
177
|
+
- **Requirements/limits:** clean working tree required; non-fast-forward/diverged histories need manual git resolution.
|
|
178
|
+
- **Data preserved:** DB, exports, invoices, and configured data directory (`PM_DATA_DIR`/defaults) are not modified by source updates.
|
|
179
|
+
- **After apply:** **restart the app/server** to load the new version. If dependencies changed, refresh the venv via setup scripts.
|
|
180
|
+
- **Update notifications (auto-check):** built-in polling-based checks run when online (cached/rate-limited, configurable via `auto_check_updates` / `auto_update_check_interval_hours`) and notify in the web UI when updates/releases are available. Git installs can be applied in-app (ff-only) then restarted; native/packaged installs require downloading/installing the new release artifact. No push infrastructure; auto-apply is not enabled by default.
|
|
181
|
+
- **First-time update / platform guides:** Windows: rerun `scripts/install_windows.ps1` (or `git pull --ff-only` + `scripts\setup_windows.ps1 -Action setup`) then restart. Termux: rerun `scripts/install.sh` with `MODE=web ... --workers 1` (or manual ff-only + setup) then restart. Details in `docs/UPDATES.md`.
|
|
182
|
+
- **Manual CLI:** `git pull --ff-only` then re-run setup to refresh deps if needed (Unix/Termux: `MODE=<...> ACTION=setup sh scripts/setup.sh`, Windows: `scripts\setup_windows.ps1 -Action setup`).
|
|
183
|
+
|
|
184
|
+
See `docs/UPDATES.md` for release/update/rollback guidance.
|
|
185
|
+
|
|
186
|
+
## Integrity, health checks & doctor
|
|
187
|
+
|
|
188
|
+
- **In-app (read-only):** ledger/data integrity checks available in Web UI and via grounded assistant queries.
|
|
189
|
+
- **CLI doctor:** `PYTHONPATH=src python -m app_core.doctor` (or `scripts/backup_runtime.* --doctor`) for operational health checks. Supports `--json`, `--check-updates`, `--strict`, and safe backup/verify helpers: `--backup [--backup-to <path>]`, `--verify-backup <path>` / `--verify`.
|
|
190
|
+
- **Web probes:** `GET /health`, `GET /healthz`, `GET /readyz` for liveness/readiness (and detailed readiness checks).
|
|
191
|
+
|
|
192
|
+
## Backups & restore
|
|
193
|
+
|
|
194
|
+
- **Create backups (automated/helpers):**
|
|
195
|
+
- Web UI: **Settings → Backup now** (subject to unlock/CSRF as applicable).
|
|
196
|
+
- CLI: `python3 scripts/backup_runtime.py --backup [--to <path>]`, `python3 scripts/backup_runtime.py --verify <backup.db>`, `python3 scripts/backup_runtime.py --doctor [--json] [--check-updates]`, or `PYTHONPATH=src python -m app_core.doctor --backup/--verify-backup`.
|
|
197
|
+
- Wrappers: `scripts/backup_runtime.sh`, `scripts/backup_runtime.cmd`, `scripts/backup_runtime.ps1`.
|
|
198
|
+
- **Preserve:** DB, exports, invoices, and data dir (`PM_DATA_DIR` or defaults). Take backups regularly and before upgrades/migrations.
|
|
199
|
+
- **Restore (manual, offline):** no destructive one-click in-app restore.
|
|
200
|
+
1. Stop app/server.
|
|
201
|
+
2. Verify candidate backup (`--verify` / `--verify-backup`).
|
|
202
|
+
3. Copy current DB/files as safety backup.
|
|
203
|
+
4. Replace active DB (and related exports/invoices if needed) with verified backup in the correct data directory.
|
|
204
|
+
5. Start app/server (`--workers 1` for web); migrations run on startup.
|
|
205
|
+
6. Verify with doctor/integrity checks and app smoke tests.
|
|
206
|
+
|
|
207
|
+
See `docs/BACKUP_RESTORE.md` for DR guidance.
|
|
208
|
+
|
|
209
|
+
## Tests & checks
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
python -m py_compile src/app_core/*.py ui/web/*.py main.py launcher.py
|
|
213
|
+
PYTHONPATH=src pytest -q
|
|
214
|
+
pytest --cov=src/app_core --cov=ui --cov-report=term-missing --cov-report=xml:coverage.xml
|
|
215
|
+
python -m pip install -r requirements.txt -r requirements-dev.txt && python -m pytest -q
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
## Troubleshooting (quick)
|
|
219
|
+
|
|
220
|
+
- **Web deps/build issues (iSH/limited toolchains):** use `SKIP_WEB=0 MODE=web`.
|
|
221
|
+
- **`venv` missing:** install distro Python venv package (e.g. `python3-venv`) or re-run setup scripts.
|
|
222
|
+
- **Port in use / unreachable:** change `PORT`, bind correct `HOST`, allow firewall, verify LAN IP/proxy.
|
|
223
|
+
- **DB/permission issues:** ensure writable data dir (`PM_DATA_DIR`/defaults), single writer, `--workers 1` for web.
|
|
224
|
+
- **Update apply blocked:** commit/stash/discard local changes or resolve non-fast-forward state manually.
|
|
225
|
+
|
|
226
|
+
See `docs/TROUBLESHOOTING.md`.
|
|
227
|
+
|
|
228
|
+
## Packaging & install formats
|
|
229
|
+
|
|
230
|
+
- **Python package (wheel/sdist):** `pyproject.toml` builds distributable packages including web UI assets (`ui/web/templates`, `ui/web/static`, PWA manifest/icons/service worker). CI workflow: `.github/workflows/release-python-package.yml` (artifacts on tags/dispatch; optional PyPI publish via `PYPI_API_TOKEN`).
|
|
231
|
+
- **Container image (GHCR):** multi-arch image published by `.github/workflows/release-container.yml` to `ghcr.io/michaelhehelmy/spms` (run with `--workers 1`, persistent `PM_DATA_DIR`).
|
|
232
|
+
- **Native binaries:** Nuitka builds via `.github/workflows/release-native.yml` (Windows `.exe`, Linux binary/AppImage path, macOS `.dmg`). See `docs/NATIVE_BUILDS.md`.
|
|
233
|
+
- **PWA / installable web app:** manifest, icons, and a minimal service worker are served from `ui/web/static/` for “Add to Home Screen / Install app” (best over HTTPS for non-localhost).
|
|
234
|
+
- **Kubernetes/Helm:** chart skeleton in `deploy/helm/spms` (single-replica, SQLite-safe `--workers 1`, persistent data volume, probes).
|
|
235
|
+
- **Linux packages scaffolds:** Debian/Ubuntu `.deb` (`deploy/packaging/deb/build-deb.sh`) and RPM (`deploy/packaging/rpm/build-rpm.sh`, `SPECS/spms.spec`) with `spms-web` systemd service and `/etc/spms/spms.env`.
|
|
236
|
+
- **Android WebView wrapper scaffold:** `deploy/mobile/android-webview/` (configurable SPMS URL; reuse web UI/PWA).
|
|
237
|
+
- **Planned/optional (external/signing/hardening):** Windows/macOS installers (signed/notarized), TWA/store packaging. Details and roadmap: `docs/PACKAGING.md`.
|
|
238
|
+
|
|
239
|
+
## More documentation
|
|
240
|
+
|
|
241
|
+
- `assistant.md` — assistant capabilities, grounded/read-only behavior, evolution and plan.
|
|
242
|
+
- `docs/PACKAGING.md` — packaging/distribution formats, modularization boundaries, and implementation roadmap/status.
|
|
243
|
+
- `docs/NATIVE_BUILDS.md` — Nuitka/native standalone build and release packaging guidance (GitHub Releases assets auto-detected by landing page). Landing page can also accept uploaded JSON issue reports via Cloudflare Pages Function (`functions/api/report.js`) when configured with secrets (e.g. `REPORT_GITHUB_TOKEN`, optional `REPORT_GITHUB_REPO`/`REPORT_GITHUB_LABELS`) to create GitHub issues for maintainers.
|
|
244
|
+
- `docs/PRODUCTION_ROADMAP.md` — phased P0–P3 production hardening/operations roadmap and checklist.
|
|
245
|
+
- `docs/DEPLOYMENT.md` — local/LAN/remote deployment, reverse proxy + HTTPS, systemd/Docker guidance.
|
|
246
|
+
- `docs/SECURITY.md` — hardening checklist, secrets/cookies, authz/unlock/CSRF, printer/file/data handling.
|
|
247
|
+
- `docs/BACKUP_RESTORE.md` — backup, verify, restore, DR, data preservation.
|
|
248
|
+
- `docs/UPDATES.md` — release/update/rollback guidance.
|
|
249
|
+
- `docs/TROUBLESHOOTING.md` — common issues and diagnostics.
|
|
250
|
+
- `docs/GO_LIVE_CHECKLIST.md` — operational go-live steps (monitoring, domain/TLS, backups, pilot, etc.).
|
|
251
|
+
- `docs/web_authz_matrix.md` — web route-group authz/CSRF/unlock reference (authoritative for `ui/web`).
|