Add "mss-failsafe"

2026-04-04 14:42:46 +02:00
parent 85531b6a54
commit b618192df8
1 changed files with 174 additions and 0 deletions
@@ -0,0 +1,174 @@
+# 🏗️ mss-failsafe — Enterprise Multi-Module App
+
+![MSS Failsafe Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/mss-failsafe-banner.png)
+
+**mss-failsafe** is a multi-module Maven enterprise application covering machine/service ticket tracking, company management, location management, and user administration. It follows a strict layered architecture separating domain model, user data, and web presentation concerns across independent Maven modules.
+
+- **GroupId:** `plate.software`
+- **ArtifactId:** `mss-failsafe`
+- **Version:** `1.0-SNAPSHOT`
+- **Java:** 11
+- **Jakarta EE:** 8.0
+
+## Module Structure
+
+```
+mss-failsafe/
+├── pom.xml                     ← Parent POM (packaging: pom), defines 4 modules
+├── mssfailsafe.datalayer/      ← JPA domain model + entities (JAR)
+├── userdata/                   ← User management, security, PDF generation (JAR)
+├── mssfailsafeWeblayer/        ← Web layer module (WAR)
+└── mss/                        ← Main MSS web application (WAR)
+```
+
+### Module Details
+
+| Module | Packaging | Purpose |
+|---|---|---|
+| `mssfailsafe.datalayer` | JAR | JPA entities, domain model, enums |
+| `userdata` | JAR | User auth, security, PrimeFaces 10 UI components |
+| `mssfailsafeWeblayer` | WAR | Admin + user web layer (admin/welcome, user/welcome) |
+| `mss` | WAR | Main MSS module (companies, locations, machines, tickets) |
+
+## Domain Model
+
+The `mssfailsafe.datalayer` module defines the complete domain model across 5 sub-packages:
+
+### Addresses
+| Entity | Description |
+|---|---|
+| `Address` | Base address entity |
+| `CompanyBillingAddress` | Billing address for companies |
+| `LocationAddress` | Physical address for locations |
+
+### Company
+| Entity | Description |
+|---|---|
+| `Company` | Top-level organization entity |
+| `Location` | Physical location/branch of a company |
+| `Status` | Company/location status enum |
+
+### Customer
+| Entity | Description |
+|---|---|
+| `Customer` | Customer entity linked to companies |
+
+### Files
+| Entity | Description |
+|---|---|
+| `FileDB` | Binary file storage entity |
+| `Invoice` | Invoice document entity |
+| `Mime` | MIME type enum for stored files |
+| `Report` | Report document entity |
+
+### Ticket
+| Entity | Description |
+|---|---|
+| `Ticket` | Core service/support ticket |
+| `TicketLocation` | Location context for a ticket |
+| `TicketMachine` | Machine associated with a ticket |
+| `Comment` | Comment on a ticket |
+| `Status` | Ticket status enum |
+| `FilenameGeneration` | Ticket filename generation utility |
+
+### Machine
+| Entity | Description |
+|---|---|
+| `Machine` | Machine/equipment tracked in the system |
+
+## Web Pages
+
+### MSS Module (`mss/`)
+```
+src/main/webapp/
+├── index.xhtml               ← Entry point
+├── error.xhtml               ← Error page
+└── user/
+    ├── welcome.xhtml         ← User dashboard
+    ├── companies.xhtml       ← Company management
+    ├── locations.xhtml       ← Location management
+    ├── machines.xhtml        ← Machine tracking
+    ├── tickets.xhtml         ← (implied — ticket management)
+    ├── profile.xhtml         ← User profile
+    └── protection.xhtml      ← Security/access protection page
+```
+
+### MSS Failsafe Web Layer (`mssfailsafeWeblayer/`)
+```
+src/main/webapp/
+├── index.xhtml
+├── error.xhtml
+├── admin/welcome.xhtml       ← Admin dashboard
+└── user/welcome.xhtml        ← User landing page
+```
+
+### User Management (`userManagement/`)
+```
+src/main/webapp/
+├── index.xhtml
+├── error.xhtml
+├── admin/welcome.xhtml       ← Admin user management dashboard
+└── user/welcome.xhtml        ← User self-service portal
+```
+
+## Features
+
+- **Machine Tracking** — Register and manage machines/equipment across company locations
+- **Ticket System** — Create, track, and comment on service/support tickets linked to machines
+- **Company Management** — Multi-tenant company + location hierarchy
+- **User Management** — Dedicated `userManagement` module for admin + self-service user portal
+- **Document Storage** — Binary file persistence via `FileDB` entity (invoices, reports)
+- **PDF Generation** — `pdfbox 2.0.13` in the `userdata` module for document generation
+- **Security** — Jakarta Security via Soteria + OmniFaces for authentication flows
+
+## Security
+
+The `userdata` module handles all authentication and security:
+
+| Dependency | Version | Purpose |
+|---|---|---|
+| `org.glassfish.soteria:javax.security.enterprise` | 1.0 | Jakarta Security API (Soteria impl) |
+| `org.omnifaces:omnifaces` | 3.11.1 | JSF utility library + auth helpers |
+| `org.glassfish:javax.faces` | 2.3.0 | JSF 2.3 (provided) |
+
+Security approach:
+- **Jakarta Security API** (`javax.security.enterprise`) for declarative authentication
+- **Soteria 1.0** as the reference implementation
+- **OmniFaces 3.x** for programmatic JSF security utilities
+- Separate admin and user role areas enforced at the WAR level via `WEB-INF/web.xml`
+
+## Dependencies (userdata module)
+
+| Dependency | Version | Purpose |
+|---|---|---|
+| `javax:javaee-api` | 8.0 | Java EE 8 API (provided) |
+| `javax:javaee-web-api` | 8.0 | Web API (provided) |
+| `org.primefaces:primefaces` | 10.0.0 | PrimeFaces 10 UI components |
+| `org.glassfish.soteria:javax.security.enterprise` | 1.0 | Security API |
+| `org.omnifaces:omnifaces` | 3.11.1 | JSF utilities |
+| `org.apache.pdfbox:pdfbox` | 2.0.13 | PDF generation |
+| `org.apache.logging.log4j:log4j-api` | 2.14.1 | Logging API |
+| `org.apache.logging.log4j:log4j-core` | 2.14.1 | Logging implementation |
+
+## Build
+
+```bash
+cd java/mss-failsafe
+# Build all modules in order (parent POM manages module sequence)
+mvn clean install
+
+# Module build order (defined in parent POM):
+# 1. mssfailsafe.datalayer (JAR — entities)
+# 2. userdata (JAR — security + utils)
+# 3. mssfailsafeWeblayer (WAR)
+# 4. mss (WAR)
+```
+
+### WildFly Deployment
+Each WAR module has its own WildFly descriptors:
+- `WEB-INF/jboss-web.xml` — context root per module
+- `WEB-INF/jboss-app.xml` — EAR/app metadata
+
+## Notes
+
+This project represents a more mature architecture than `wellmann-shop`, using Java 11, PrimeFaces 10, Log4j2, and a properly separated multi-module Maven structure. The `mssfailsafe.datalayer` JAR is a reusable domain model shared across multiple WAR modules — a classic enterprise Java pattern.