164 lines
6.3 KiB
Markdown
164 lines
6.3 KiB
Markdown
# Frymaster Badge App
|
|
|
|
A cross-platform **.NET MAUI** application for managing employee records, generating customizable ID badges, handling company profiles, and printing via local desktop printers. Features dynamic tab navigation, photo capture/cropping, barcode generation, and robust file-based logging.
|
|
|
|
---
|
|
|
|
## 📋 Prerequisites
|
|
|
|
| Requirement | Details |
|
|
|-------------|---------|
|
|
| **SDK** | `.NET 8.0` or later |
|
|
| **Workload** | `maui` workload installed (`dotnet workload install maui`) |
|
|
| **IDE** | Visual Studio 2022 (v17.8+) with MAUI, or VS Code + C# Dev Kit |
|
|
| **Database** | SQL Server (2019/2022/Express/Azure SQL) |
|
|
| **Platform** | Windows 10/11 (recommended for printing & file pickers) |
|
|
|
|
> ⚠️ **Note:** Printer APIs (`System.Drawing.Printing`) and folder/file pickers used in this app are desktop-optimized. Mobile targets may require platform-specific fallbacks.
|
|
|
|
---
|
|
|
|
## 🗄️ Database Setup
|
|
|
|
1. Create a database named `Frymaster` in your SQL Server instance.
|
|
2. Run the following schema to create the required tables (matches application queries):
|
|
|
|
```sql
|
|
CREATE TABLE dbo.Companies (
|
|
ID INT IDENTITY(1,1) PRIMARY KEY,
|
|
Name NVARCHAR(100) NOT NULL,
|
|
Address NVARCHAR(200),
|
|
City NVARCHAR(100),
|
|
State NVARCHAR(50),
|
|
Zip NVARCHAR(20),
|
|
Logo NVARCHAR(255)
|
|
);
|
|
|
|
CREATE TABLE dbo.tblData (
|
|
Data1 NVARCHAR(50) PRIMARY KEY, -- Employee Record Number
|
|
Data2 NVARCHAR(100), -- First Name
|
|
LastName NVARCHAR(100),
|
|
Data3 NVARCHAR(100), -- Display Name
|
|
Data4 NVARCHAR(100), -- Additional Info
|
|
Data5 DATETIME, -- Issue/Start Date
|
|
Data7 NVARCHAR(10), -- Medical Indicator 1 (True/False)
|
|
Data8 NVARCHAR(10), -- Medical Indicator 2 (1/0 or True/False)
|
|
Active NVARCHAR(10), -- YES/NO
|
|
Data9 NVARCHAR(50), -- Badge Number
|
|
picCode NVARCHAR(255), -- Photo filename reference
|
|
cropX FLOAT DEFAULT 0,
|
|
cropY FLOAT DEFAULT 0,
|
|
cropScale FLOAT DEFAULT 1.0,
|
|
BadgeType NVARCHAR(50) DEFAULT 'OFFICE', -- OFFICE, GUEST, PLANT, MAINTENANCE, VENDOR
|
|
ToPrint BIT DEFAULT 0,
|
|
CdsPrinted BIT DEFAULT 0
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ Configuration
|
|
|
|
1. Create `appsettings.json` inside `Resources/Raw/`
|
|
2. Set its **Build Action** to `MauiAsset`
|
|
3. Add your connection string:
|
|
|
|
```json
|
|
{
|
|
"ConnectionStrings": {
|
|
"DefaultConnection": "Server=127.0.0.1;Database=Frymaster;User Id=sa;Password=YourSecurePassword;TrustServerCertificate=True;"
|
|
}
|
|
}
|
|
```
|
|
|
|
> 🔒 **Security Note:** The app contains a hardcoded fallback connection string in `MauiProgram.cs`. **Never deploy to production without providing `appsettings.json`**, as the fallback uses plain-text credentials and will log a warning.
|
|
|
|
---
|
|
|
|
## 🛠️ Building & Running
|
|
|
|
### ✅ Using CLI
|
|
```bash
|
|
# Restore dependencies
|
|
dotnet restore
|
|
|
|
# Build
|
|
dotnet build -c Release
|
|
|
|
# Run (Windows Desktop default)
|
|
dotnet run -f net8.0-windows10.0.19041.0
|
|
```
|
|
|
|
### ✅ Using Visual Studio
|
|
1. Open `FrymasterBadgeApp.csproj` or `.sln`
|
|
2. Select your target framework in the toolbar (e.g., `net8.0-windows10.0.19041.0`)
|
|
3. Press `F5` or click ▶ Run
|
|
4. The app will automatically restore NuGet packages and launch.
|
|
|
|
---
|
|
|
|
## 🚀 First Run & Navigation Flow
|
|
|
|
1. **Initial Setup Tab**: If no companies exist in the database, the app shows a `Setup` tab. Click it to add your first company via `CompanyPage`.
|
|
2. **Dynamic Tabs**: Once companies are added, each gets its own tab in the bottom `TabBar`. Tabs are generated dynamically at runtime.
|
|
3. **Employee Management**: Click a company tab → select/search employees → view/edit badge preview → capture/update photos → print.
|
|
4. **Settings**: Use the top-right `⚙️` icon to configure storage paths (`C:\FrymasterData\...` defaults) and UI theme (`System`/`Light`/`Dark`).
|
|
5. **Company Management**: Use the `🏢` icon in `AppShell` to manage company records and upload logos.
|
|
|
|
---
|
|
|
|
## 📂 Storage & Paths
|
|
|
|
| Setting | Default | Notes |
|
|
|---------|---------|-------|
|
|
| Photos | `C:\FrymasterData\photos` | Stores employee JPGs (`{recordNum}_{ticks}.jpg`) |
|
|
| Logos | `C:\FrymasterData\logos` | Stores company logo images |
|
|
| Images | `C:\FrymasterData\images` | Stores guest/default badge assets |
|
|
| Logs | `%LOCALAPPDATA%` | Rotates daily, max 5MB/file, 30-day auto-cleanup |
|
|
|
|
> 🌍 **Cross-Platform Note:** The `C:\...` defaults are Windows-specific. On macOS/Linux, change paths immediately via the **Settings Page** to avoid `UnauthorizedAccessException` or missing directory errors.
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
| Issue | Solution |
|
|
|-------|----------|
|
|
| `SqlService` connection fails | Verify SQL Server is running, check `appsettings.json`, ensure `TrustServerCertificate=True` |
|
|
| App crashes on startup | Check `FrymasterBadgeApp_*.log` in `%LOCALAPPDATA%` for DI or XAML errors |
|
|
| Missing tabs / "Loading..." stuck | Ensure at least one company exists in `dbo.Companies` |
|
|
| Print fails / `PrinterSettings` empty | Ensure desktop target is selected. Mobile platforms don't expose `InstalledPrinters` |
|
|
| `FolderPicker` or `Toast` crashes | Wrapped in try/catch. Intentionally disables auto-navigation after save to prevent Shell crashes |
|
|
| Missing barcode font | Ensure `LibreBarcode39-Regular.ttf` is in `Resources/Fonts` with `Build Action: MauiFont` |
|
|
|
|
---
|
|
|
|
## 📜 Logging & Diagnostics
|
|
|
|
- **Location:** `%LOCALAPPDATA%\FrymasterBadgeApp_YYYY-MM-DD.log`
|
|
- **Rotation:** Files >5MB are renamed to `.old` (previous `.old` is deleted)
|
|
- **Cleanup:** `AppLogger.CleanupOldLogs()` deletes logs older than 30 days
|
|
- **Viewing:** Open with any text editor or run:
|
|
```powershell
|
|
Get-ChildItem $env:LOCALAPPDATA\FrymasterBadgeApp_*.log | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Invoke-Item
|
|
```
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/your-feature`)
|
|
3. Commit changes (`git commit -m "Add your feature"`)
|
|
4. Push to the branch (`git push origin feature/your-feature`)
|
|
5. Open a Pull Request
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
Property of Frymaster
|
|
|
|
---
|
|
|
|
> 💡 **Tip:** Run `dotnet workload restore` before first build if you encounter missing MAUI SDK errors. Ensure your `.csproj` targets a supported Windows SDK version (`net8.0-windows10.0.19041.0` or higher). |