1363 lines
60 KiB
Markdown
1363 lines
60 KiB
Markdown
|
# BaMoRT Backend — Comprehensive Architecture & Code Findings
|
|||
|
|
|
|||
|
|
> Generated: 2026-03-13
|
|||
|
|
> Source: `/home/de31a2/bamort/backend`
|
|||
|
|
> Module: `bamort` (Go 1.24, toolchain 1.24.4)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Table of Contents
|
|||
|
|
|
|||
|
|
1. [Module Structure Overview](#1-module-structure-overview)
|
|||
|
|
2. [Entry Point — cmd/main.go](#2-entry-point--cmdmaingo)
|
|||
|
|
3. [Router & Middleware Setup](#3-router--middleware-setup)
|
|||
|
|
4. [Authentication & Authorization](#4-authentication--authorization)
|
|||
|
|
5. [Configuration](#5-configuration)
|
|||
|
|
6. [Database Layer](#6-database-layer)
|
|||
|
|
7. [Models (GORM Entities)](#7-models-gorm-entities)
|
|||
|
|
8. [Module-by-Module Analysis](#8-module-by-module-analysis)
|
|||
|
|
- [user/](#81-user)
|
|||
|
|
- [character/](#82-character)
|
|||
|
|
- [equipment/](#83-equipment)
|
|||
|
|
- [gsmaster/](#84-gsmaster)
|
|||
|
|
- [gamesystem/](#85-gamesystem)
|
|||
|
|
- [maintenance/](#86-maintenance)
|
|||
|
|
- [pdfrender/](#87-pdfrender)
|
|||
|
|
- [importer/](#88-importer)
|
|||
|
|
- [transfer/](#89-transfer)
|
|||
|
|
- [appsystem/](#810-appsystem)
|
|||
|
|
- [logger/](#811-logger)
|
|||
|
|
- [mail/](#812-mail)
|
|||
|
|
- [router/](#813-router)
|
|||
|
|
- [config/](#814-config)
|
|||
|
|
- [database/](#815-database)
|
|||
|
|
- [testutils/](#816-testutils)
|
|||
|
|
- [api/](#817-api)
|
|||
|
|
9. [Complete API Route Listing](#9-complete-api-route-listing)
|
|||
|
|
10. [Testing Approach](#10-testing-approach)
|
|||
|
|
11. [Key Dependencies](#11-key-dependencies)
|
|||
|
|
12. [Security Observations](#12-security-observations)
|
|||
|
|
13. [Cross-Module Relationships Diagram](#13-cross-module-relationships-diagram)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. Module Structure Overview
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
backend/
|
|||
|
|
├── cmd/ # Entry point (main.go)
|
|||
|
|
├── config/ # App configuration loading from env/.env
|
|||
|
|
├── database/ # DB connection, migrations, test helpers
|
|||
|
|
├── models/ # All GORM entities and migration orchestration
|
|||
|
|
├── router/ # Gin engine setup, CORS, base route group + JWT guard
|
|||
|
|
├── user/ # User accounts, auth, roles, password reset
|
|||
|
|
├── character/ # Core character CRUD, skills, spells, learning system
|
|||
|
|
├── equipment/ # Character equipment (weapons, containers, gear)
|
|||
|
|
├── gsmaster/ # Game-system master data (skills, spells, weapons, learning costs)
|
|||
|
|
├── gamesystem/ # Game system record management and initial seed data
|
|||
|
|
├── maintenance/ # Admin/maintainer ops – DB checks, migrations, scratchpad endpoints
|
|||
|
|
├── pdfrender/ # HTML→PDF export using chromedp + pdfcpu merge
|
|||
|
|
├── importer/ # VTT-JSON / CSV import and export of characters/spells
|
|||
|
|
├── transfer/ # JSON-based character and full-database import/export
|
|||
|
|
├── appsystem/ # Version and system-info endpoints
|
|||
|
|
├── logger/ # Custom leveled logger (DEBUG/INFO/WARN/ERROR)
|
|||
|
|
├── mail/ # SMTP email client (password reset emails)
|
|||
|
|
├── api/ # Integration tests spanning multiple modules
|
|||
|
|
├── testutils/ # Shared test environment setup helpers
|
|||
|
|
├── testdata/ # Prepared SQLite snapshot used by all tests
|
|||
|
|
├── templates/ # PDF HTML templates (Default_A4_Quer/)
|
|||
|
|
└── scripts/ # Shell scripts (e.g., SQLite→MariaDB transfer)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Each domain module follows the pattern:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
module/
|
|||
|
|
handlers.go HTTP handler functions (Gin controllers)
|
|||
|
|
routes.go RegisterRoutes(r *gin.RouterGroup)
|
|||
|
|
*_test.go Tests using setupTestEnvironment(t)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. Entry Point — cmd/main.go
|
|||
|
|
|
|||
|
|
**File:** `cmd/main.go`
|
|||
|
|
|
|||
|
|
### Startup Sequence
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
func main() {
|
|||
|
|
cfg := config.Cfg // 1. Load config (auto-loaded in init())
|
|||
|
|
|
|||
|
|
logger.SetDebugMode(cfg.DebugMode) // 2. Configure logger
|
|||
|
|
logger.SetMinLogLevel(...)
|
|||
|
|
|
|||
|
|
if cfg.IsProduction() {
|
|||
|
|
gin.SetMode(gin.ReleaseMode) // 3. Set Gin mode
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
database.ConnectDatabase() // 4. Connect to database
|
|||
|
|
|
|||
|
|
pdfrender.InitializeTemplates(...) // 5. Sync PDF templates
|
|||
|
|
|
|||
|
|
r := gin.Default()
|
|||
|
|
router.SetupGin(r) // 6. CORS middleware
|
|||
|
|
|
|||
|
|
protected := router.BaseRouterGrp(r) // 7. Public auth routes + JWT-protected group
|
|||
|
|
|
|||
|
|
// 8. Register module routes
|
|||
|
|
user.RegisterRoutes(protected)
|
|||
|
|
gsmaster.RegisterRoutes(protected)
|
|||
|
|
character.RegisterRoutes(protected)
|
|||
|
|
equipment.RegisterRoutes(protected)
|
|||
|
|
maintenance.RegisterRoutes(protected)
|
|||
|
|
importer.RegisterRoutes(protected)
|
|||
|
|
pdfrender.RegisterRoutes(protected)
|
|||
|
|
transfer.RegisterRoutes(protected)
|
|||
|
|
appsystem.RegisterRoutes(protected)
|
|||
|
|
|
|||
|
|
// 9. Public routes (no auth)
|
|||
|
|
pdfrender.RegisterPublicRoutes(r)
|
|||
|
|
appsystem.RegisterPublicRoutes(r)
|
|||
|
|
|
|||
|
|
r.Run(cfg.GetServerAddress()) // 10. Start HTTP server
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Swagger Annotations
|
|||
|
|
The file contains `@title BaMoRT API`, `@version 1`, `@host localhost:8180` – indicates Swagger/OpenAPI doc generation is intended.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. Router & Middleware Setup
|
|||
|
|
|
|||
|
|
### CORS (`router/setup.go`)
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
func SetupGin(r *gin.Engine) {
|
|||
|
|
allowedOrigins := []string{
|
|||
|
|
config.Cfg.FrontendURL,
|
|||
|
|
"http://localhost:5173",
|
|||
|
|
"http://192.168.0.48:5173",
|
|||
|
|
"http://192.168.0.36:5173",
|
|||
|
|
"https://bamort.trokan.de",
|
|||
|
|
}
|
|||
|
|
r.Use(cors.New(cors.Config{
|
|||
|
|
AllowOrigins: allowedOrigins,
|
|||
|
|
AllowMethods: []string{"GET", "POST", "PUT", "PATCH", "DELETE"},
|
|||
|
|
AllowHeaders: []string{"Origin", "Content-Type", "Authorization"},
|
|||
|
|
ExposeHeaders: []string{"Content-Length"},
|
|||
|
|
AllowCredentials: true,
|
|||
|
|
MaxAge: 12 * 3600,
|
|||
|
|
}))
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Route Groups (`router/routes.go`)
|
|||
|
|
|
|||
|
|
**Public (unauthenticated) routes:**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| POST | `/register` | `user.RegisterUser` |
|
|||
|
|
| POST | `/login` | `user.LoginUser` |
|
|||
|
|
| POST | `/password-reset/request` | `user.RequestPasswordReset` |
|
|||
|
|
| GET | `/password-reset/validate/:token` | `user.ValidateResetToken` |
|
|||
|
|
| POST | `/password-reset/reset` | `user.ResetPassword` |
|
|||
|
|
|
|||
|
|
**Protected group:** `/api` — guarded by `user.AuthMiddleware()`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. Authentication & Authorization
|
|||
|
|
|
|||
|
|
### Token Scheme
|
|||
|
|
|
|||
|
|
The project uses a **custom MD5-based token**, not JWT.
|
|||
|
|
|
|||
|
|
**Token Generation (`user/handlers.go`):**
|
|||
|
|
```go
|
|||
|
|
func GenerateToken(u *User) string {
|
|||
|
|
tx := md5.Sum([]byte(u.Username + u.CreatedAt.String()))
|
|||
|
|
hashString := hex.EncodeToString(tx[:])
|
|||
|
|
// Insert ".{userID}:" at position 7
|
|||
|
|
pos := 7
|
|||
|
|
idm := "." + fmt.Sprintf("%d", u.UserID) + ":"
|
|||
|
|
token := hashString[:pos] + idm + hashString[pos:]
|
|||
|
|
return token
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
The token embeds the user ID in a predictable location. Clients send it as the `Authorization` header value (prefixed `Bearer `).
|
|||
|
|
|
|||
|
|
**Token Validation (`CheckToken`):**
|
|||
|
|
1. Extracts user ID from position `7 + len("Bearer ")` in the `Authorization` header.
|
|||
|
|
2. Loads the user from the database by that ID.
|
|||
|
|
3. Returns the user or `nil`.
|
|||
|
|
|
|||
|
|
**No cryptographic signature is verified.** Any token with a valid user ID at the expected position is accepted.
|
|||
|
|
|
|||
|
|
### `AuthMiddleware()` (`user/handlers.go`)
|
|||
|
|
|
|||
|
|
Sets `userID`, `username`, and `user` in the Gin context for downstream handlers.
|
|||
|
|
|
|||
|
|
### Password Hashing
|
|||
|
|
|
|||
|
|
Passwords are hashed with **MD5** (not bcrypt):
|
|||
|
|
```go
|
|||
|
|
hashedPassword := md5.Sum([]byte(user.PasswordHash))
|
|||
|
|
user.PasswordHash = hex.EncodeToString(hashedPassword[:])
|
|||
|
|
```
|
|||
|
|
The bcrypt implementation is commented out.
|
|||
|
|
|
|||
|
|
### Roles (`user/model.go`)
|
|||
|
|
|
|||
|
|
| Constant | Value | Description |
|
|||
|
|
|----------|-------|-------------|
|
|||
|
|
| `RoleStandardUser` | `"standard"` | Default for new registrations |
|
|||
|
|
| `RoleMaintainer` | `"maintainer"` | Can manage master data |
|
|||
|
|
| `RoleAdmin` | `"admin"` | Can manage users |
|
|||
|
|
|
|||
|
|
Role-checking middleware:
|
|||
|
|
- `RequireAdmin()` → used on `/api/users/*` admin endpoints
|
|||
|
|
- `RequireMaintainer()` → used on maintenance/gsmaster write endpoints
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. Configuration
|
|||
|
|
|
|||
|
|
**File:** `config/config.go`
|
|||
|
|
|
|||
|
|
### `Config` Struct Fields
|
|||
|
|
|
|||
|
|
| Field | Env Var(s) | Default | Description |
|
|||
|
|
|-------|-----------|---------|-------------|
|
|||
|
|
| `ServerPort` | `API_PORT`, `SERVER_PORT` | `"8180"` | HTTP listen port |
|
|||
|
|
| `DatabaseURL` | `DATABASE_URL` | `""` | DSN string for DB driver |
|
|||
|
|
| `DatabaseType` | `DATABASE_TYPE` | `"mysql"` | `mysql` or `sqlite` |
|
|||
|
|
| `DebugMode` | `DEBUG` | `false` | Enables verbose logging |
|
|||
|
|
| `LogLevel` | `LOG_LEVEL` | `"INFO"` | `DEBUG`, `INFO`, `WARN`, `ERROR` |
|
|||
|
|
| `Environment` | `ENVIRONMENT`, `GO_ENV` | `"production"` | `production`, `development`, `test` |
|
|||
|
|
| `DevTesting` | `DEVTESTING` | `"no"` | `"yes"` redirects to SQLite test DB |
|
|||
|
|
| `FrontendURL` | `BASE_URL` | `"http://localhost:5173"` | CORS allowed origin |
|
|||
|
|
| `TemplatesDir` | `TEMPLATES_DIR` | `"./templates"` | PDF template directory |
|
|||
|
|
| `ExportTempDir` | `EXPORT_TEMP_DIR` | `"./xporttemp"` | Temporary PDF output directory |
|
|||
|
|
| `MailHost` | `MAIL_HOST` | `""` | SMTP server hostname |
|
|||
|
|
| `MailPort` | `MAIL_PORT` | `465` | SMTP port (465=TLS, 587=STARTTLS) |
|
|||
|
|
| `MailUsername` | `MAIL_USERNAME` | `""` | SMTP credentials |
|
|||
|
|
| `MailPassword` | `MAIL_PASSWORD` | `""` | SMTP credentials |
|
|||
|
|
| `MailFrom` | `MAIL_FROM` | (falls back to username) | Sender email address |
|
|||
|
|
|
|||
|
|
### Loading Logic
|
|||
|
|
|
|||
|
|
1. Reads `.env` and `.env.local` files from the working directory.
|
|||
|
|
2. Overrides with env vars.
|
|||
|
|
3. `ENVIRONMENT=development` automatically enables `DebugMode=true` and `LogLevel=DEBUG`.
|
|||
|
|
4. `ENVIRONMENT=test` or `DEVTESTING=yes` causes `ConnectDatabase()` to use the SQLite test snapshot.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. Database Layer
|
|||
|
|
|
|||
|
|
**Package:** `database/`
|
|||
|
|
|
|||
|
|
### Connection (`database/config.go`)
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
func ConnectDatabase() *gorm.DB {
|
|||
|
|
if envIsTest || devTestingIsYes {
|
|||
|
|
SetupTestDB() // Use prepared SQLite snapshot
|
|||
|
|
} else {
|
|||
|
|
ConnectDatabaseOrig() // MySQL or SQLite via DATABASE_URL
|
|||
|
|
}
|
|||
|
|
return DB
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Supported drivers: `mysql` (default), `sqlite`.
|
|||
|
|
|
|||
|
|
### Global Variable
|
|||
|
|
|
|||
|
|
`database.DB *gorm.DB` — all packages import this directly.
|
|||
|
|
|
|||
|
|
### Test Database
|
|||
|
|
|
|||
|
|
- **Source:** `testdata/prepared_test_data.db` (SQLite snapshot with real test data including character ID 18 "Fanjo Vetrani")
|
|||
|
|
- **Mechanism:** `SetupTestDB()` copies the snapshot to a `os.MkdirTemp` directory, opens it, and assigns it to `database.DB`.
|
|||
|
|
- Each test run gets a fresh isolated copy.
|
|||
|
|
|
|||
|
|
### Migration Tables (`database/model.go`)
|
|||
|
|
|
|||
|
|
| Table | Purpose |
|
|||
|
|
|-------|---------|
|
|||
|
|
| `schema_version` | Current schema version tracking |
|
|||
|
|
| `migration_history` | Log of applied migrations |
|
|||
|
|
|
|||
|
|
### Migration Orchestration (`models/database.go`)
|
|||
|
|
|
|||
|
|
`models.MigrateStructure(db)` calls in order:
|
|||
|
|
1. `gameSystemMigrateStructure` — `game_systems`
|
|||
|
|
2. `gsMasterMigrateStructure` — skills, spells, equipment, weapons, etc.
|
|||
|
|
3. `characterMigrateStructure` — characters, skills, spells, equipment
|
|||
|
|
4. `equipmentMigrateStructure`
|
|||
|
|
5. `skillsMigrateStructure` — learning cost tables
|
|||
|
|
6. `importerMigrateStructure` — (currently no-op)
|
|||
|
|
7. `learningMigrateStructure` — all learning/cost relation tables
|
|||
|
|
|
|||
|
|
### `StringArray` Custom Type
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
type StringArray []string
|
|||
|
|
// Stored as JSON in TEXT column (Value+Scan implementations)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Used for `Char.Spezialisierung` (character specializations).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. Models (GORM Entities)
|
|||
|
|
|
|||
|
|
### Base Types
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
type BamortBase struct {
|
|||
|
|
ID uint `gorm:"primaryKey"`
|
|||
|
|
Name string
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
type BamortCharTrait struct {
|
|||
|
|
BamortBase
|
|||
|
|
CharacterID uint `gorm:"index"`
|
|||
|
|
UserID uint `gorm:"index"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
type Magisch struct {
|
|||
|
|
IstMagisch bool
|
|||
|
|
Abw int
|
|||
|
|
Ausgebrannt bool
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### User Model (`user/model.go` → table: `users`)
|
|||
|
|
|
|||
|
|
| Field | Type | Notes |
|
|||
|
|
|-------|------|-------|
|
|||
|
|
| `UserID` | uint PK | |
|
|||
|
|
| `Username` | string unique | |
|
|||
|
|
| `DisplayName` | string | Falls back to Username if empty |
|
|||
|
|
| `PasswordHash` | string | MD5 hex string |
|
|||
|
|
| `Email` | string unique | |
|
|||
|
|
| `Role` | string | `standard`, `maintainer`, `admin` |
|
|||
|
|
| `PreferredLanguage` | string | default `de` |
|
|||
|
|
| `ResetPwHash` | *string | Hidden from JSON serialization |
|
|||
|
|
| `ResetPwHashExpires` | *time.Time | 14 days validity |
|
|||
|
|
| `CreatedAt`, `UpdatedAt` | time.Time | |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Character Model (`models/model_character.go` → table: `char_chars`)
|
|||
|
|
|
|||
|
|
**Main struct `Char`:**
|
|||
|
|
|
|||
|
|
| Field | Type | Notes |
|
|||
|
|
|-------|------|-------|
|
|||
|
|
| `ID` | uint PK | (via BamortBase) |
|
|||
|
|
| `Name` | string | Character name |
|
|||
|
|
| `GameSystem` | string | e.g. `"midgard"` |
|
|||
|
|
| `GameSystemId` | uint | FK to `game_systems` |
|
|||
|
|
| `UserID` | uint index | FK to `users` |
|
|||
|
|
| `User` | User | FK `UserID→users.user_id` CASCADE |
|
|||
|
|
| `Rasse` | string | Race (e.g. "Mensch", "Zwerg") |
|
|||
|
|
| `Typ` | string | Class code (e.g. "Kr", "Ma") |
|
|||
|
|
| `Alter` | int | Age |
|
|||
|
|
| `Anrede` | string | Title/salutation |
|
|||
|
|
| `Grad` | int | Character grade/level |
|
|||
|
|
| `Gender` | string | |
|
|||
|
|
| `SocialClass` | string | |
|
|||
|
|
| `Groesse` | int | Height (cm) |
|
|||
|
|
| `Gewicht` | int | Weight (kg) |
|
|||
|
|
| `Herkunft` | string | Origin/homeland |
|
|||
|
|
| `Glaube` | string | Faith |
|
|||
|
|
| `Hand` | string | Dominant hand |
|
|||
|
|
| `Public` | bool | Publicly visible |
|
|||
|
|
| `ResistenzKoerper` | int | Body resistance (derived) |
|
|||
|
|
| `ResistenzGeist` | int | Mental resistance (derived) |
|
|||
|
|
| `Abwehr` | int | Defense value (derived) |
|
|||
|
|
| `Zaubern` | int | Spell casting value (derived) |
|
|||
|
|
| `Raufen` | int | Brawling value (derived) |
|
|||
|
|
| `Lp` | Lp | Life points (has-one, CASCADE) |
|
|||
|
|
| `Ap` | Ap | Action points (has-one) |
|
|||
|
|
| `B` | B | Load/burden (has-one) |
|
|||
|
|
| `Merkmale` | Merkmale | Physical traits (has-one) |
|
|||
|
|
| `Eigenschaften` | []Eigenschaft | Attributes Au/Gs/Gw/In/Ko/St/Wk/Zt/PA |
|
|||
|
|
| `Fertigkeiten` | []SkFertigkeit | Skills (has-many) |
|
|||
|
|
| `Waffenfertigkeiten` | []SkWaffenfertigkeit | Weapon skills |
|
|||
|
|
| `Zauber` | []SkZauber | Spells |
|
|||
|
|
| `Spezialisierung` | StringArray | TEXT/JSON stored |
|
|||
|
|
| `Bennies` | Bennies | Gg/Gp/Sg |
|
|||
|
|
| `Vermoegen` | Vermoegen | GS/SS/KS wealth |
|
|||
|
|
| `Erfahrungsschatz` | Erfahrungsschatz | EP/ES experience |
|
|||
|
|
| `Waffen` | []EqWaffe | Weapons (has-many) |
|
|||
|
|
| `Behaeltnisse` | []EqContainer | Containers |
|
|||
|
|
| `Transportmittel` | []EqContainer | Transportation |
|
|||
|
|
| `Ausruestung` | []EqAusruestung | General equipment |
|
|||
|
|
| `Image` | string | Base64 or URL |
|
|||
|
|
|
|||
|
|
**Helper types:**
|
|||
|
|
|
|||
|
|
| Type | Table | Fields |
|
|||
|
|
|------|-------|--------|
|
|||
|
|
| `Eigenschaft` | (embedded in preload) | ID, CharacterID, UserID, Name, Value |
|
|||
|
|
| `Lp` | — | ID, CharacterID, Max, Value |
|
|||
|
|
| `Ap` | — | ID, CharacterID, Max, Value |
|
|||
|
|
| `B` | — | ID, CharacterID, Max, Value |
|
|||
|
|
| `Merkmale` | — | BamortCharTrait + Augenfarbe/Haarfarbe/Sonstige/Breite/Groesse |
|
|||
|
|
| `Erfahrungsschatz` | — | BamortCharTrait + ES, EP |
|
|||
|
|
| `Bennies` | — | BamortCharTrait + Gg, Gp, Sg |
|
|||
|
|
| `Vermoegen` | — | BamortCharTrait + Goldstuecke, Silberstuecke, Kupferstuecke |
|
|||
|
|
|
|||
|
|
**`FeChar`** (frontend-facing):
|
|||
|
|
Embeds `Char` + `Git` (gift tolerance = 30+Ko/2) + `CategorizedSkills` map + `InnateSkills` slice.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Skill Models (`models/model_char_skills.go`)
|
|||
|
|
|
|||
|
|
| Type | Table | Key Fields |
|
|||
|
|
|------|-------|------------|
|
|||
|
|
| `SkFertigkeit` | `char_skills` | BamortCharTrait + Fertigkeitswert, BasisWert, Bonus, Pp, Category, Improvable, LearningCost |
|
|||
|
|
| `SkWaffenfertigkeit` | `char_weaponskills` | Embeds SkFertigkeit |
|
|||
|
|
| `SkAngeboreneFertigkeit` | (no own table) | Embeds SkFertigkeit |
|
|||
|
|
| `SkZauber` | `char_spells` | BamortCharTrait + Beschreibung, Bonus, Quelle |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Equipment Models (`models/model_char_equipment.go`)
|
|||
|
|
|
|||
|
|
| Type | Table | Key Fields |
|
|||
|
|
|------|-------|------------|
|
|||
|
|
| `EqAusruestung` | `equi_equipments` | BamortCharTrait + Magisch + Anzahl, ContainedIn, Bonus, Gewicht, Wert |
|
|||
|
|
| `EqWaffe` | `equi_weapons` | BamortCharTrait + Magisch + Abwb, Anb, Anzahl, Schb, NameFuerSpezialisierung |
|
|||
|
|
| `EqContainer` | `equi_containers` | BamortCharTrait + Magisch + IsTransportation, Tragkraft, Volumen, ExtID |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### GSMaster Models (`models/model_gsmaster.go`)
|
|||
|
|
|
|||
|
|
| Type | Table | Key Fields |
|
|||
|
|
|------|-------|------------|
|
|||
|
|
| `Skill` | `gsm_skills` | ID, GameSystem/Id, Name, Initialwert, BasisWert, Bonuseigenschaft, Improvable, InnateSkill, Category, Difficulty |
|
|||
|
|
| `WeaponSkill` | (inherits Skill) | Embeds Skill |
|
|||
|
|
| `Spell` | (via gsmaster) | ID, Name, Stufe, AP, Art, Zauberdauer, Reichweite, Ursprung, Category, LearningCategory |
|
|||
|
|
| `Equipment` | (via gsmaster) | ID, Name, Gewicht, Wert, PersonalItem |
|
|||
|
|
| `Weapon` | (extends Equipment) | SkillRequired, Damage, RangeNear/Middle/Far |
|
|||
|
|
| `Container` | (extends Equipment) | Tragkraft, Volumen |
|
|||
|
|
| `Transportation` | (extends Container) | — |
|
|||
|
|
| `Believe` | (via gsmaster) | ID, GameSystem/Id, Name, Beschreibung, SourceID |
|
|||
|
|
| `MiscLookup` | `gsm_misc_lookups` | ID, GameSystem/Id, Key, Value |
|
|||
|
|
| `LookupList` | `gsm_lookup_lists` | Generic lookup |
|
|||
|
|
| `LearnCost` | (computed, no own table) | GameSystem, Stufe, LE, TE, Ep, Money, PP |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Game System (`models/model_game_system.go` → table: `game_systems`)
|
|||
|
|
|
|||
|
|
| Field | Notes |
|
|||
|
|
|-------|-------|
|
|||
|
|
| `Code` | Unique, e.g. `"M5"` |
|
|||
|
|
| `Name` | e.g. `"M-System"` |
|
|||
|
|
| `IsActive` | bool |
|
|||
|
|
|
|||
|
|
Default game system: Code=`M5`, Name=`M-System`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Learning-Cost Models (`models/model_learning_costs.go`)
|
|||
|
|
|
|||
|
|
| Type | Table | Purpose |
|
|||
|
|
|------|-------|---------|
|
|||
|
|
| `Source` | `gsm_lit_sources` | Rulebook/sourcebook references |
|
|||
|
|
| `CharacterClass` | `gsm_character_classes` | Class codes (Kr, Ma, Hx …) + source link |
|
|||
|
|
| `SkillCategory` | `learning_skill_categories` | Alltag, Freiland, Halbwelt, Kampf, Körper, Sozial, Unterwelt, Waffen, Wissen |
|
|||
|
|
| `SkillDifficulty` | `learning_skill_difficulties` | leicht, normal, schwer, sehr schwer |
|
|||
|
|
| `SpellSchool` | `learning_spell_schools` | Beherrschen, Bewegen, Erkennen, … |
|
|||
|
|
| `ClassCategoryEPCost` | `learning_class_category_ep_costs` | EP per TE by class+category |
|
|||
|
|
| `ClassSpellSchoolEPCost` | `learning_class_spell_school_ep_costs` | EP per LE by class+school |
|
|||
|
|
| `SpellLevelLECost` | `learning_spell_level_le_costs` | LE required by spell level |
|
|||
|
|
| `SkillCategoryDifficulty` | `learning_skill_category_difficulties` | LE cost for skill in category+difficulty |
|
|||
|
|
| `WeaponSkillCategoryDifficulty` | (separate table) | LE cost for weapon skills |
|
|||
|
|
| `SkillImprovementCost` | `learning_skill_improvement_costs` | TE to improve by current level |
|
|||
|
|
| `ClassCategoryLearningPoints` | — | Starting LP per class+category for creation |
|
|||
|
|
| `AuditLogEntry` | `audit_log_entries`(?) | EP/gold change audit trail |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Character Creation Session (`models/model_character_creation.go`)
|
|||
|
|
|
|||
|
|
| Type | Table | Purpose |
|
|||
|
|
|------|-------|---------|
|
|||
|
|
| `CharacterCreationSession` | `char_creation_sessions` | Multi-step wizard persistence |
|
|||
|
|
|
|||
|
|
Fields: UserID, Name, Rasse, Typ, Herkunft, Stand, Glaube, Attributes (JSON), DerivedValues (JSON), Skills (JSON), Spells (JSON), SkillPoints (JSON), CurrentStep, ExpiresAt.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Character Share (`models/model_character_share.go` → table: `char_shares`)
|
|||
|
|
|
|||
|
|
| Field | Notes |
|
|||
|
|
|-------|-------|
|
|||
|
|
| `CharacterID` | FK to char_chars |
|
|||
|
|
| `UserID` | FK to users (recipient) |
|
|||
|
|
| `Permission` | `"read"` or `"write"` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### Database Schema/Migration Models (`database/model.go`)
|
|||
|
|
|
|||
|
|
| Type | Table |
|
|||
|
|
|------|-------|
|
|||
|
|
| `SchemaVersion` | `schema_version` |
|
|||
|
|
| `MigrationHistory` | `migration_history` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. Module-by-Module Analysis
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.1 `user/`
|
|||
|
|
|
|||
|
|
**Purpose:** User account management, authentication, authorization, password reset.
|
|||
|
|
|
|||
|
|
**Key Files:**
|
|||
|
|
- `model.go` — User struct, CRUD methods, reset-hash helpers
|
|||
|
|
- `handlers.go` — RegisterUser, LoginUser, CheckToken, AuthMiddleware, password reset
|
|||
|
|
- `admin_handlers.go` — ListUsers, GetUser, UpdateUserRole, ChangeUserPassword, DeleteUser
|
|||
|
|
- `middleware.go` — RequireRole, RequireAdmin, RequireMaintainer
|
|||
|
|
- `database.go` — `MigrateStructure` for `users` table
|
|||
|
|
- `routes.go` — Route registration
|
|||
|
|
|
|||
|
|
**Business Logic:**
|
|||
|
|
- Registration creates users with MD5-hashed passwords and a default `standard` role.
|
|||
|
|
- Login returns a custom MD5 token containing the encoded user ID.
|
|||
|
|
- Password reset uses a 32-byte random hex hash (secure) with a 14-day expiry, sent via SMTP.
|
|||
|
|
- `AuthMiddleware` validates the token structure, loads the user from DB, injects `userID`/`username`/`user` into context.
|
|||
|
|
|
|||
|
|
**HTTP Endpoints (protected unless noted):**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler | Auth level |
|
|||
|
|
|--------|------|---------|-----------|
|
|||
|
|
| POST | `/register` | `RegisterUser` | Public |
|
|||
|
|
| POST | `/login` | `LoginUser` | Public |
|
|||
|
|
| POST | `/password-reset/request` | `RequestPasswordReset` | Public |
|
|||
|
|
| GET | `/password-reset/validate/:token` | `ValidateResetToken` | Public |
|
|||
|
|
| POST | `/password-reset/reset` | `ResetPassword` | Public |
|
|||
|
|
| GET | `/api/user/profile` | `GetUserProfile` | Auth |
|
|||
|
|
| PUT | `/api/user/display-name` | `UpdateDisplayName` | Auth |
|
|||
|
|
| PUT | `/api/user/email` | `UpdateEmail` | Auth |
|
|||
|
|
| PUT | `/api/user/password` | `UpdatePassword` | Auth |
|
|||
|
|
| PUT | `/api/user/language` | `UpdateLanguage` | Auth |
|
|||
|
|
| GET | `/api/users` | `ListUsers` | Admin |
|
|||
|
|
| GET | `/api/users/:id` | `GetUser` | Admin (own profile also allowed) |
|
|||
|
|
| PUT | `/api/users/:id/role` | `UpdateUserRole` | Admin |
|
|||
|
|
| PUT | `/api/users/:id/password` | `ChangeUserPassword` | Admin |
|
|||
|
|
| DELETE | `/api/users/:id` | `DeleteUser` | Admin |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.2 `character/`
|
|||
|
|
|
|||
|
|
**Purpose:** Core character management — CRUD, skill/spell learning system, character creation wizard, audit logging, sharing, practice points, PDF-relevant data prep.
|
|||
|
|
|
|||
|
|
**Key Files:**
|
|||
|
|
- `handlers.go` — ListCharacters, CreateCharacter, GetCharacter, UpdateCharacter, DeleteCharacter, ToFeChar, UpdateCharacterImage, GetDatasheetOptions
|
|||
|
|
- `lerncost_handler.go` — `GetLernCostNewSystem`, `ImproveSkill`, `LearnSkill`, `LearnSpell` — full learning economy
|
|||
|
|
- `derived_values_calculator.go` — `CalculateStaticFields`, `CalculateRolledField` — character creation math
|
|||
|
|
- `creation_rules.go` — `GetSpecialAbilityByRoll` — special ability table
|
|||
|
|
- `audit_log.go` — `CreateAuditLogEntry`, `GetAuditLogForCharacter/Field`
|
|||
|
|
- `share_handlers.go` — `GetCharacterShares`, `UpdateCharacterShares`, `GetAvailableUsersForSharing`
|
|||
|
|
- `practice_points_handler.go` — `GetPracticePoints`, `UpdatePracticePoints`, `AddPracticePoint`, `UsePracticePoint`
|
|||
|
|
- `skill_type_helper.go` — skill categorization helpers
|
|||
|
|
- `system_information_handlers.go` — `GetSkillCategoriesHandlerStatic`
|
|||
|
|
- `spell_utils.go` — spell availability and creation utilities
|
|||
|
|
- `database.go` — `SaveCharacterToDB`
|
|||
|
|
- `image_handler.go` — character image upload/handling
|
|||
|
|
|
|||
|
|
**Business Logic:**
|
|||
|
|
- `ListCharacters`: Returns `{ self_owned: [], others: [] }` where `others` = public + shared.
|
|||
|
|
- `GetCharacter`: Returns `FeChar` (augmented view with categorized skills).
|
|||
|
|
- `toFeChar`: Adds bonus field from attributes, splits skills by category.
|
|||
|
|
- `checkCharacterOwnership`: Guards update/delete/share with `character.UserID == c.GetUint("userID")`.
|
|||
|
|
- **Learning System** (`GetLernCostNewSystem`): Calculates LE/TE/EP/Money cost for learning or improving a skill/spell/weapon. Considers: character class, skill category, difficulty, current level, practice points (PP) reductions, gold-for-EP conversion, reward types (free learning, half EP).
|
|||
|
|
- **Derived Values**: `CalculateStaticFieldsLogic` implements Midgard 5th edition formulae for Ausdauer-, Schadens-, Angriffs-, Abwehr-, Zauber-Bonus, Resistenz, Abwehr, Zaubern, Raufen.
|
|||
|
|
|
|||
|
|
**HTTP Endpoints (`/api/characters/...`):**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| GET | `/api/characters` | `ListCharacters` |
|
|||
|
|
| POST | `/api/characters` | `CreateCharacter` |
|
|||
|
|
| GET | `/api/characters/:id` | `GetCharacter` |
|
|||
|
|
| PUT/PATCH | `/api/characters/:id` | `UpdateCharacter` |
|
|||
|
|
| DELETE | `/api/characters/:id` | `DeleteCharacter` |
|
|||
|
|
| PUT | `/api/characters/:id/image` | `UpdateCharacterImage` |
|
|||
|
|
| GET | `/api/characters/:id/datasheet-options` | `GetDatasheetOptions` |
|
|||
|
|
| GET | `/api/characters/:id/shares` | `GetCharacterShares` |
|
|||
|
|
| PUT | `/api/characters/:id/shares` | `UpdateCharacterShares` |
|
|||
|
|
| GET | `/api/characters/:id/available-users` | `GetAvailableUsersForSharing` |
|
|||
|
|
| GET | `/api/characters/:id/experience-wealth` | `GetCharacterExperienceAndWealth` |
|
|||
|
|
| PUT | `/api/characters/:id/experience` | `UpdateCharacterExperience` |
|
|||
|
|
| PUT | `/api/characters/:id/wealth` | `UpdateCharacterWealth` |
|
|||
|
|
| GET | `/api/characters/:id/audit-log` | `GetCharacterAuditLog` |
|
|||
|
|
| GET | `/api/characters/:id/audit-log/stats` | `GetAuditLogStats` |
|
|||
|
|
| POST | `/api/characters/lerncost-new` | `GetLernCostNewSystem` |
|
|||
|
|
| POST | `/api/characters/lerncost` | `GetLernCostNewSystem` |
|
|||
|
|
| POST | `/api/characters/improve-skill-new` | `ImproveSkill` |
|
|||
|
|
| POST | `/api/characters/improve-skill` | `ImproveSkill` |
|
|||
|
|
| POST | `/api/characters/:id/learn-skill-new` | `LearnSkill` |
|
|||
|
|
| POST | `/api/characters/:id/learn-skill` | `LearnSkill` |
|
|||
|
|
| POST | `/api/characters/:id/learn-spell-new` | `LearnSpell` |
|
|||
|
|
| POST | `/api/characters/:id/learn-spell` | `LearnSpell` |
|
|||
|
|
| POST | `/api/characters/available-skills-new` | `GetAvailableSkillsNewSystem` |
|
|||
|
|
| POST | `/api/characters/available-skills` | `GetAvailableSkillsNewSystem` |
|
|||
|
|
| POST | `/api/characters/available-skills-creation` | `GetAvailableSkillsForCreation` |
|
|||
|
|
| POST | `/api/characters/available-spells-creation` | `GetAvailableSpellsForCreation` |
|
|||
|
|
| POST | `/api/characters/available-spells-new` | `GetAvailableSpellsNewSystem` |
|
|||
|
|
| POST | `/api/characters/available-spells` | `GetAvailableSpellsNewSystem` |
|
|||
|
|
| GET | `/api/characters/spell-details` | `GetSpellDetails` |
|
|||
|
|
| GET | `/api/characters/:id/reward-types` | `GetRewardTypesStatic` |
|
|||
|
|
| GET | `/api/characters/:id/practice-points` | `GetPracticePoints` |
|
|||
|
|
| PUT | `/api/characters/:id/practice-points` | `UpdatePracticePoints` |
|
|||
|
|
| POST | `/api/characters/:id/practice-points/add` | `AddPracticePoint` |
|
|||
|
|
| POST | `/api/characters/:id/practice-points/use` | `UsePracticePoint` |
|
|||
|
|
| GET | `/api/characters/skill-categories` | `GetSkillCategoriesHandlerStatic` |
|
|||
|
|
| GET | `/api/characters/create-sessions` | `ListCharacterSessions` |
|
|||
|
|
| POST | `/api/characters/create-session` | `CreateCharacterSession` |
|
|||
|
|
| GET | `/api/characters/create-session/:sessionId` | `GetCharacterSession` |
|
|||
|
|
| PUT | `/api/characters/create-session/:sessionId/basic` | `UpdateCharacterBasicInfo` |
|
|||
|
|
| PUT | `/api/characters/create-session/:sessionId/attributes` | `UpdateCharacterAttributes` |
|
|||
|
|
| PUT | `/api/characters/create-session/:sessionId/derived` | `UpdateCharacterDerivedValues` |
|
|||
|
|
| PUT | `/api/characters/create-session/:sessionId/skills` | `UpdateCharacterSkills` |
|
|||
|
|
| POST | `/api/characters/create-session/:sessionId/finalize` | `FinalizeCharacterCreation` |
|
|||
|
|
| DELETE | `/api/characters/create-session/:sessionId` | `DeleteCharacterSession` |
|
|||
|
|
| GET | `/api/characters/races` | `GetRaces` |
|
|||
|
|
| GET | `/api/characters/classes` | `GetCharacterClasses` |
|
|||
|
|
| GET | `/api/characters/classes/learning-points` | `GetCharacterClassLearningPoints` |
|
|||
|
|
| GET | `/api/characters/origins` | `GetOrigins` |
|
|||
|
|
| GET | `/api/characters/beliefs` | `SearchBeliefs` |
|
|||
|
|
| POST | `/api/characters/calculate-static-fields` | `CalculateStaticFields` |
|
|||
|
|
| POST | `/api/characters/calculate-rolled-field` | `CalculateRolledField` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.3 `equipment/`
|
|||
|
|
|
|||
|
|
**Purpose:** CRUD for character-owned equipment items and weapons.
|
|||
|
|
|
|||
|
|
**Key Files:** `handlers.go`, `routes.go`
|
|||
|
|
|
|||
|
|
**Business Logic:**
|
|||
|
|
- `checkEquipmentOwnership`: Loads character by ID, compares `character.UserID` to logged-in user.
|
|||
|
|
- All operations (CRUD) filter/verify ownership before executing DB writes.
|
|||
|
|
|
|||
|
|
**HTTP Endpoints:**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| POST | `/api/equipment` | `CreateAusruestung` |
|
|||
|
|
| GET | `/api/equipment/character/:character_id` | `ListAusruestung` |
|
|||
|
|
| PUT | `/api/equipment/:ausruestung_id` | `UpdateAusruestung` |
|
|||
|
|
| DELETE | `/api/equipment/:ausruestung_id` | `DeleteAusruestung` |
|
|||
|
|
| POST | `/api/weapons` | `CreateWaffe` |
|
|||
|
|
| GET | `/api/weapons/character/:character_id` | `ListWaffen` |
|
|||
|
|
| PUT | `/api/weapons/:waffe_id` | `UpdateWaffe` |
|
|||
|
|
| DELETE | `/api/weapons/:waffe_id` | `DeleteWaffe` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.4 `gsmaster/`
|
|||
|
|
|
|||
|
|
**Purpose:** Game-system master data management — the reference library for skills, weapon skills, spells, equipment, weapons, and learning costs.
|
|||
|
|
|
|||
|
|
**Key Files:**
|
|||
|
|
- `handlers.go` — Generic get/add/update/delete using Go generics (`getMDItem[T]`, `getMDItems[T]`, etc.)
|
|||
|
|
- `routes.go` — Public read endpoints + maintainer-guarded write endpoints
|
|||
|
|
- `learning_costs.go` — `LearningCostsTable` with full EP/TE cost tables for all 15 character classes
|
|||
|
|
- `learning_costs_init.go` — `ValidateLearningCostsData`, `GetLearningCostsSummary`
|
|||
|
|
- `levelup.go` — `CalculateImprovementCost`, `CalculateSkillImprovementCost`
|
|||
|
|
- `game_system.go` — Game system lookup helper
|
|||
|
|
- `misclookup.go` — `GetMiscLookupByKey`, `GetMiscLookupByKeyForSystem` (races, faiths, origins, etc.)
|
|||
|
|
- `skill_enhanced_handlers.go`, `spell_enhanced_handlers.go`, `weapon_enhanced_handlers.go`, `weapon_skill_enhanced_handlers.go`, `equipment_enhanced_handlers.go` — Enhanced CRUD with source/difficulty enrichment
|
|||
|
|
|
|||
|
|
**Business Logic:**
|
|||
|
|
- Learning costs are stored both as hardcoded Go maps (in `learning_costs.go`, 15 classes × 8-9 categories) and in the database (`ClassCategoryEPCost` tables).
|
|||
|
|
- `GetMiscLookupByKey("faiths")` merges entries from both `gsm_misc_lookups` and `gsm_believes` tables.
|
|||
|
|
- Generic handlers use interface constraints (`Creator`, `Saver`, `FirstIdGetter`, `Deleter`) via Go generics for DRY CRUD.
|
|||
|
|
|
|||
|
|
**HTTP Endpoints (`/api/maintenance/...`):**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler | Auth Level |
|
|||
|
|
|--------|------|---------|-----------|
|
|||
|
|
| GET | `/api/maintenance` | `GetMasterData` | Auth |
|
|||
|
|
| GET | `/api/maintenance/skills` | `GetMDSkills` | Auth |
|
|||
|
|
| GET | `/api/maintenance/skills-enhanced` | `GetEnhancedMDSkills` | Auth |
|
|||
|
|
| GET | `/api/maintenance/skills/:id` | `GetMDSkill` | Auth |
|
|||
|
|
| GET | `/api/maintenance/skills-enhanced/:id` | `GetEnhancedMDSkill` | Auth |
|
|||
|
|
| GET | `/api/maintenance/weaponskills` | `GetMDWeaponSkills` | Auth |
|
|||
|
|
| GET | `/api/maintenance/weaponskills-enhanced` | `GetEnhancedMDWeaponSkills` | Auth |
|
|||
|
|
| GET | `/api/maintenance/weaponskills/:id` | `GetMDWeaponSkill` | Auth |
|
|||
|
|
| GET | `/api/maintenance/weaponskills-enhanced/:id` | `GetEnhancedMDWeaponSkill` | Auth |
|
|||
|
|
| GET | `/api/maintenance/spells` | `GetMDSpells` | Auth |
|
|||
|
|
| GET | `/api/maintenance/spells-enhanced` | `GetEnhancedMDSpells` | Auth |
|
|||
|
|
| GET | `/api/maintenance/spells/:id` | `GetMDSpell` | Auth |
|
|||
|
|
| GET | `/api/maintenance/spells-enhanced/:id` | `GetEnhancedMDSpell` | Auth |
|
|||
|
|
| GET | `/api/maintenance/equipment` | `GetMDEquipments` | Auth |
|
|||
|
|
| GET | `/api/maintenance/equipment-enhanced` | `GetEnhancedMDEquipment` | Auth |
|
|||
|
|
| GET | `/api/maintenance/equipment/:id` | `GetMDEquipment` | Auth |
|
|||
|
|
| GET | `/api/maintenance/equipment-enhanced/:id` | `GetEnhancedMDEquipmentItem` | Auth |
|
|||
|
|
| GET | `/api/maintenance/weapons` | `GetMDWeapons` | Auth |
|
|||
|
|
| GET | `/api/maintenance/weapons-enhanced` | `GetEnhancedMDWeapons` | Auth |
|
|||
|
|
| GET | `/api/maintenance/weapons/:id` | `GetMDWeapon` | Auth |
|
|||
|
|
| GET | `/api/maintenance/weapons-enhanced/:id` | `GetEnhancedMDWeapon` | Auth |
|
|||
|
|
| POST | `/api/maintenance/skills-enhanced` | `CreateEnhancedMDSkill` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/skills/:id` | `UpdateMDSkill` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/skills-enhanced/:id` | `UpdateEnhancedMDSkill` | Maintainer |
|
|||
|
|
| POST | `/api/maintenance/skills` | `AddSkill` | Maintainer |
|
|||
|
|
| DELETE | `/api/maintenance/skills/:id` | `DeleteMDSkill` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/weaponskills/:id` | `UpdateMDWeaponSkill` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/weaponskills-enhanced/:id` | `UpdateEnhancedMDWeaponSkill` | Maintainer |
|
|||
|
|
| POST | `/api/maintenance/weaponskills` | `AddWeaponSkill` | Maintainer |
|
|||
|
|
| DELETE | `/api/maintenance/weaponskills/:id` | `DeleteMDWeaponSkill` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/spells/:id` | `UpdateMDSpell` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/spells-enhanced/:id` | `UpdateEnhancedMDSpell` | Maintainer |
|
|||
|
|
| POST | `/api/maintenance/spells` | `AddSpell` | Maintainer |
|
|||
|
|
| DELETE | `/api/maintenance/spells/:id` | `DeleteMDSpell` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/equipment/:id` | `UpdateMDEquipment` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/equipment-enhanced/:id` | `UpdateEnhancedMDEquipmentItem` | Maintainer |
|
|||
|
|
| POST | `/api/maintenance/equipment` | `AddEquipment` | Maintainer |
|
|||
|
|
| DELETE | `/api/maintenance/equipment/:id` | `DeleteMDEquipment` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/weapons/:id` | `UpdateMDWeapon` | Maintainer |
|
|||
|
|
| PUT | `/api/maintenance/weapons-enhanced/:id` | `UpdateEnhancedMDWeapon` | Maintainer |
|
|||
|
|
| POST | `/api/maintenance/weapons` | `AddWeapon` | Maintainer |
|
|||
|
|
| DELETE | `/api/maintenance/weapons/:id` | `DeleteMDWeapon` | Maintainer |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.5 `gamesystem/`
|
|||
|
|
|
|||
|
|
**Purpose:** Minimal package that handles migration of the `game_systems` table and seeds the initial Midgard 5 game system.
|
|||
|
|
|
|||
|
|
**Key File:** `database.go`
|
|||
|
|
|
|||
|
|
- `MigrateStructure(db)` — AutoMigrates `GameSystem`.
|
|||
|
|
- `MigrateDataIfNeeded(db)` — Creates `{Code:"M5", Name:"M-System"}` if no row with ID=1 exists.
|
|||
|
|
|
|||
|
|
No HTTP endpoints registered.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.6 `maintenance/`
|
|||
|
|
|
|||
|
|
**Purpose:** Admin/maintainer tooling — DB health checks, data migrations, test data generation, SQLite→MariaDB transfer.
|
|||
|
|
|
|||
|
|
**Key Files:**
|
|||
|
|
- `handlers.go` — SetupCheck, MakeTestdataFromLive, ReconnectDataBase, ReloadENV, TransferSQLiteToMariaDB, migrateAllStructures
|
|||
|
|
- `masterdata_handlers.go` — GetGameSystems, UpdateGameSystem, GetLitSources, UpdateLitSource, GetMisc, UpdateMisc, GetSkillImprovementCost2, UpdateSkillImprovementCost2
|
|||
|
|
- `believe_handlers.go` — GetBelieves, UpdateBelieve
|
|||
|
|
- `skill_migration.go` — Skill-related migration helpers
|
|||
|
|
|
|||
|
|
**Business Logic:**
|
|||
|
|
- `migrateAllStructures` calls all module `MigrateStructure()` functions in correct dependency order.
|
|||
|
|
- `MakeTestdataFromLive` exports current live DB to a SQLite file for test snapshots.
|
|||
|
|
- `TransferSQLiteToMariaDB` copies records table-by-table from SQLite to MariaDB.
|
|||
|
|
- All endpoints require `RequireMaintainer()` or `RequireAdmin()` — no public access.
|
|||
|
|
|
|||
|
|
**HTTP Endpoints (`/api/maintenance/...` — Maintainer required):**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| GET | `/api/maintenance/gsm-believes` | `GetBelieves` |
|
|||
|
|
| PUT | `/api/maintenance/gsm-believes/:id` | `UpdateBelieve` |
|
|||
|
|
| GET | `/api/maintenance/game-systems` | `GetGameSystems` |
|
|||
|
|
| PUT | `/api/maintenance/game-systems/:id` | `UpdateGameSystem` |
|
|||
|
|
| GET | `/api/maintenance/gsm-lit-sources` | `GetLitSources` |
|
|||
|
|
| PUT | `/api/maintenance/gsm-lit-sources/:id` | `UpdateLitSource` |
|
|||
|
|
| GET | `/api/maintenance/gsm-misc` | `GetMisc` |
|
|||
|
|
| PUT | `/api/maintenance/gsm-misc/:id` | `UpdateMisc` |
|
|||
|
|
| GET | `/api/maintenance/skill-improvement-cost2` | `GetSkillImprovementCost2` |
|
|||
|
|
| PUT | `/api/maintenance/skill-improvement-cost2/:id` | `UpdateSkillImprovementCost2` |
|
|||
|
|
| GET | `/api/maintenance/setupcheck` | `SetupCheck` |
|
|||
|
|
| GET | `/api/maintenance/setupcheck-dev` | `SetupCheckDev` |
|
|||
|
|
| GET | `/api/maintenance/mktestdata` | `MakeTestdataFromLive` |
|
|||
|
|
| GET | `/api/maintenance/reconndb` | `ReconnectDataBase` |
|
|||
|
|
| GET | `/api/maintenance/reloadenv` | `ReloadENV` |
|
|||
|
|
| POST | `/api/maintenance/transfer-sqlite-to-mariadb` | `TransferSQLiteToMariaDB` |
|
|||
|
|
|
|||
|
|
*(These overlap with the `gsmaster` maintenance prefix — both modules register under `/api/maintenance` with `gsmaster` first, then `maintenance` module adds its own routes. Both use `RequireMaintainer()` for writes.)*
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.7 `pdfrender/`
|
|||
|
|
|
|||
|
|
**Purpose:** Generate multi-page PDF character sheets from HTML templates using headless Chromium + pdfcpu merge.
|
|||
|
|
|
|||
|
|
**Key Files:**
|
|||
|
|
- `handlers.go` — `ListTemplates`, `ExportCharacterToPDF`, `CleanupExportTemp`, `GetPDFFile`
|
|||
|
|
- `init.go` — `InitializeTemplates` — copies bundled templates to `TemplatesDir` on startup
|
|||
|
|
- `chromedp.go` — `NewPDFRenderer`, `RenderHTMLToPDF` using chromedp
|
|||
|
|
- `mapper.go` — `MapCharacterToViewModel` — maps `Char` to `CharacterSheetViewModel`
|
|||
|
|
- `viewmodel.go` — All view model types (`CharacterSheetViewModel`, `CharacterInfo`, `AttributeValues`, `DerivedValueSet`, `SkillViewModel`, `WeaponViewModel`, `SpellViewModel`, `EquipmentViewModel`, `MagicItemViewModel`, `PageMeta`)
|
|||
|
|
- `render_with_continuation.go` — `RenderPageWithContinuations` — auto-generates overflow pages
|
|||
|
|
- `pagination.go` / `pagination_helper.go` — item distribution across pages
|
|||
|
|
- `fill_capacity.go` — reads `<!-- MaxItems: N -->` comments from HTML templates
|
|||
|
|
- `template_parser.go` / `template_metadata.go` — template loading and Go `html/template` execution
|
|||
|
|
- `inline_resources.go` — inlines CSS/images into HTML before rendering
|
|||
|
|
- `file_management.go` — manages `xporttemp` directory
|
|||
|
|
|
|||
|
|
**Business Logic:**
|
|||
|
|
1. On startup: sync `./default_templates` → `cfg.TemplatesDir`.
|
|||
|
|
2. `ExportCharacterToPDF`:
|
|||
|
|
- Loads character, maps to view model.
|
|||
|
|
- Renders pages 1–4 (`page_1.html` through `page_4.html`) with continuation logic.
|
|||
|
|
- Each page checks `<!-- MaxItems: N -->` to determine when to create a continuation page.
|
|||
|
|
- All rendered PDFs are merged via `pdfcpu`.
|
|||
|
|
- Saves to `xporttemp/` directory, returns `{"filename": "..."}`.
|
|||
|
|
3. `GetPDFFile`: public endpoint, serves files from `xporttemp/` by filename.
|
|||
|
|
|
|||
|
|
**HTTP Endpoints:**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler | Auth |
|
|||
|
|
|--------|------|---------|------|
|
|||
|
|
| GET | `/api/pdf/templates` | `ListTemplates` | Auth |
|
|||
|
|
| GET | `/api/pdf/export/:id` | `ExportCharacterToPDF` | Auth |
|
|||
|
|
| POST | `/api/pdf/cleanup` | `CleanupExportTemp` | Auth |
|
|||
|
|
| GET | `/api/pdf/file/:filename` | `GetPDFFile` | Public |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.8 `importer/`
|
|||
|
|
|
|||
|
|
**Purpose:** Import characters from VTT JSON format or CSV; export characters as VTT JSON, CSV, or spell CSV.
|
|||
|
|
|
|||
|
|
**Key Files:**
|
|||
|
|
- `handler.go` — `UploadFiles`, `ImportSpellCSVHandler`
|
|||
|
|
- `importer.go` — `ImportChar`, `CheckSkill`, VTT import logic
|
|||
|
|
- `importVTTJson.go` — `ImportVTTJSON` — main VTT import driver
|
|||
|
|
- `exporter.go` — `ExportCharToVTT`, `ExportCharacterToCSV`
|
|||
|
|
- `model.go` — `CharacterImport` struct (VTT format), sub-structs for Fertigkeiten/Spells/Equipment
|
|||
|
|
- `routes.go` — Route registration
|
|||
|
|
|
|||
|
|
**Business Logic:**
|
|||
|
|
- `UploadFiles`: Accepts `file_vtt` (required) + `file_csv` (optional), validates extensions (.csv/.json), calls `ImportVTTJSON`.
|
|||
|
|
- `CheckSkill`: Looks up skill in `gsm_skills`, auto-creates if `autocreate=true`.
|
|||
|
|
- Source IDs are cached (`sourceIDCache`) to reduce DB queries during bulk import.
|
|||
|
|
- `ExportCharacterVTTFileHandler`: Returns character data as downloadable `.json` file.
|
|||
|
|
|
|||
|
|
**HTTP Endpoints:**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| POST | `/api/importer/upload` | `UploadFiles` |
|
|||
|
|
| POST | `/api/importer/spells/csv` | `ImportSpellCSVHandler` |
|
|||
|
|
| GET | `/api/importer/export/vtt/:id` | `ExportCharacterVTTHandler` |
|
|||
|
|
| GET | `/api/importer/export/vtt/:id/file` | `ExportCharacterVTTFileHandler` |
|
|||
|
|
| GET | `/api/importer/export/csv/:id` | `ExportCharacterCSVHandler` |
|
|||
|
|
| GET | `/api/importer/export/spells/csv` | `ExportSpellsCSVHandler` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.9 `transfer/`
|
|||
|
|
|
|||
|
|
**Purpose:** JSON-serialized character import/export and full database backup/restore.
|
|||
|
|
|
|||
|
|
**Key Files:**
|
|||
|
|
- `handlers.go` — HTTP handlers for all transfer operations
|
|||
|
|
- `exporter.go` — `ExportCharacter` — serializes a full `Char` + metadata to `CharacterExport`
|
|||
|
|
- `importer.go` — `ImportCharacter` — deserializes and recreates character in DB
|
|||
|
|
- `database.go` — `ExportDatabase`, `ImportDatabase` — full table serialization
|
|||
|
|
- `routes.go` — Route registration
|
|||
|
|
|
|||
|
|
**Business Logic:**
|
|||
|
|
- `ExportCharacter` / `ImportCharacter`: Full round-trip JSON serialization of characters with all associations.
|
|||
|
|
- `ExportDatabase` / `ImportDatabase`: Table-level JSON snapshot used for backup/restore.
|
|||
|
|
- `DownloadCharacterHandler` sets `Content-Disposition: attachment` for browser download.
|
|||
|
|
|
|||
|
|
**HTTP Endpoints:**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| GET | `/api/transfer/export/:id` | `ExportCharacterHandler` |
|
|||
|
|
| GET | `/api/transfer/download/:id` | `DownloadCharacterHandler` |
|
|||
|
|
| POST | `/api/transfer/import` | `ImportCharacterHandler` |
|
|||
|
|
| POST | `/api/transfer/database/export` | `ExportDatabaseHandler` |
|
|||
|
|
| POST | `/api/transfer/database/import` | `ImportDatabaseHandler` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.10 `appsystem/`
|
|||
|
|
|
|||
|
|
**Purpose:** Exposes application version and system info (user/character counts, DB version).
|
|||
|
|
|
|||
|
|
**Key Files:**
|
|||
|
|
- `version.go` — `Version = "0.2.4"`, `GetInfo()`, `GetInfo2()`
|
|||
|
|
- `handlers.go` — `Versionsinfo`, `SystemInfo`
|
|||
|
|
- `routes.go` — Route registration (both protected and public)
|
|||
|
|
|
|||
|
|
**HTTP Endpoints:**
|
|||
|
|
|
|||
|
|
| Method | Path | Handler | Auth |
|
|||
|
|
|--------|------|---------|------|
|
|||
|
|
| GET | `/api/version` | `Versionsinfo` | Auth |
|
|||
|
|
| GET | `/api/systeminfo` | `SystemInfo` | Auth |
|
|||
|
|
| GET | `/api/public/version` | `Versionsinfo` | Public |
|
|||
|
|
| GET | `/api/public/systeminfo` | `SystemInfo` | Public |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.11 `logger/`
|
|||
|
|
|
|||
|
|
**Purpose:** Custom leveled logger with timestamp prefixing.
|
|||
|
|
|
|||
|
|
**Key API:**
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
logger.Debug(format, args...)
|
|||
|
|
logger.Info(format, args...)
|
|||
|
|
logger.Warn(format, args...)
|
|||
|
|
logger.Error(format, args...)
|
|||
|
|
logger.SetDebugMode(bool)
|
|||
|
|
logger.SetMinLogLevel(logger.DEBUG | INFO | WARN | ERROR)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- Outputs to `os.Stdout` with format: `[YYYY-MM-DD HH:MM:SS] LEVEL: message`
|
|||
|
|
- Debug messages are suppressed unless both `debugEnabled=true` AND `minLevel<=DEBUG`.
|
|||
|
|
- Configured once in `main()` from `config.Cfg`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.12 `mail/`
|
|||
|
|
|
|||
|
|
**Purpose:** SMTP email client used exclusively for password-reset emails.
|
|||
|
|
|
|||
|
|
**Key File:** `smtp.go`
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
type Client struct {
|
|||
|
|
host, username, password, from string
|
|||
|
|
port int
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
func NewClient() *Client // reads from config.Cfg
|
|||
|
|
func (c *Client) Send(msg Message) error
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- Port 465: Direct TLS (`tls.Dial`)
|
|||
|
|
- Port 587: STARTTLS (`smtp.Dial` + `TLSConfig`)
|
|||
|
|
- If `host == ""`: logs the email content instead of sending (fallback for unconfigured environments).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.13 `router/`
|
|||
|
|
|
|||
|
|
**Purpose:** Central Gin setup and base route group creation.
|
|||
|
|
|
|||
|
|
**Files:**
|
|||
|
|
- `setup.go` — `SetupGin(r)` — CORS middleware
|
|||
|
|
- `routes.go` — `BaseRouterGrp(r)` — public auth routes + protected `/api` group
|
|||
|
|
- `routes_test.go` — router tests
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.14 `config/`
|
|||
|
|
|
|||
|
|
**Purpose:** Application configuration loading and validation.
|
|||
|
|
|
|||
|
|
**Key Functions:**
|
|||
|
|
- `init()` — auto-loads config on package import
|
|||
|
|
- `LoadConfig()` — reads `.env`/`.env.local`, then env vars
|
|||
|
|
- `loadEnvFile()` / `loadEnvFileContent()` — parse `KEY=VALUE` lines
|
|||
|
|
- `cfg.IsProduction() bool`
|
|||
|
|
- `cfg.GetServerAddress() string` — returns `":PORT"` format
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.15 `database/`
|
|||
|
|
|
|||
|
|
**Purpose:** Database connection management, test helpers, and migration execution.
|
|||
|
|
|
|||
|
|
**Key Functions:**
|
|||
|
|
- `ConnectDatabase()` — routes to `SetupTestDB()` or `ConnectDatabaseOrig()` based on env
|
|||
|
|
- `ConnectDatabaseOrig()` — opens MySQL or SQLite with GORM
|
|||
|
|
- `SetupTestDB(opts ...bool)` — copies snapshot `testdata/prepared_test_data.db` → temp dir, opens it
|
|||
|
|
- `MigrateStructure(db)` — migrates `schema_version` + `migration_history`
|
|||
|
|
- `MigrateDataIfNeeded(db)` — ensures schema version record exists
|
|||
|
|
- `GetDB()` — lazy init getter
|
|||
|
|
|
|||
|
|
**Path Constants:**
|
|||
|
|
```go
|
|||
|
|
PreparedTestDB = filepath.Join(backendDir, "testdata", "prepared_test_data.db")
|
|||
|
|
TestDataDir = filepath.Join(backendDir, "maintenance", "testdata")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.16 `testutils/`
|
|||
|
|
|
|||
|
|
**Purpose:** Shared test environment setup utility.
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
func SetupTestEnvironment(t *testing.T)
|
|||
|
|
func SetupTestEnvironmentWithConfig(t *testing.T, envVars map[string]string)
|
|||
|
|
func EnsureTestEnvironment(t *testing.T)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- Sets `ENVIRONMENT=test` to redirect DB connection to SQLite test snapshot.
|
|||
|
|
- Registers `t.Cleanup()` to restore original env vars after each test.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 8.17 `api/`
|
|||
|
|
|
|||
|
|
**Purpose:** Integration tests that test multi-module interactions via full HTTP stack.
|
|||
|
|
|
|||
|
|
Key test: `TestListCharacters` — spins up Gin with all essential routes, uses `database.SetupTestDB(true)`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. Complete API Route Listing
|
|||
|
|
|
|||
|
|
### Public (No Authentication)
|
|||
|
|
|
|||
|
|
| Method | Path | Module | Purpose |
|
|||
|
|
|--------|------|--------|---------|
|
|||
|
|
| POST | `/register` | user | Register a new user |
|
|||
|
|
| POST | `/login` | user | Login, get token |
|
|||
|
|
| POST | `/password-reset/request` | user | Request password reset email |
|
|||
|
|
| GET | `/password-reset/validate/:token` | user | Validate reset token |
|
|||
|
|
| POST | `/password-reset/reset` | user | Set new password |
|
|||
|
|
| GET | `/api/pdf/file/:filename` | pdfrender | Download generated PDF |
|
|||
|
|
| GET | `/api/public/version` | appsystem | App version (no auth) |
|
|||
|
|
| GET | `/api/public/systeminfo` | appsystem | System info (no auth) |
|
|||
|
|
|
|||
|
|
### Protected — All Authenticated Users (`/api/...`)
|
|||
|
|
|
|||
|
|
**User Management:**
|
|||
|
|
|
|||
|
|
| Method | Path | Purpose |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| GET | `/api/user/profile` | Own profile |
|
|||
|
|
| PUT | `/api/user/display-name` | Update display name |
|
|||
|
|
| PUT | `/api/user/email` | Update email |
|
|||
|
|
| PUT | `/api/user/password` | Change password |
|
|||
|
|
| PUT | `/api/user/language` | Set preferred language |
|
|||
|
|
|
|||
|
|
**Characters:**
|
|||
|
|
|
|||
|
|
| Method | Path | Purpose |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| GET | `/api/characters` | List own + shared + public characters |
|
|||
|
|
| POST | `/api/characters` | Create character |
|
|||
|
|
| GET | `/api/characters/:id` | Get full character (FeChar) |
|
|||
|
|
| PUT/PATCH | `/api/characters/:id` | Update character |
|
|||
|
|
| DELETE | `/api/characters/:id` | Delete character |
|
|||
|
|
| PUT | `/api/characters/:id/image` | Upload character image |
|
|||
|
|
| GET | `/api/characters/:id/datasheet-options` | PDF datasheet options |
|
|||
|
|
| GET | `/api/characters/:id/shares` | List share recipients |
|
|||
|
|
| PUT | `/api/characters/:id/shares` | Update share recipients |
|
|||
|
|
| GET | `/api/characters/:id/available-users` | Users available to share with |
|
|||
|
|
| GET | `/api/characters/:id/experience-wealth` | Current EP + wealth |
|
|||
|
|
| PUT | `/api/characters/:id/experience` | Update experience points |
|
|||
|
|
| PUT | `/api/characters/:id/wealth` | Update wealth |
|
|||
|
|
| GET | `/api/characters/:id/audit-log` | Change history |
|
|||
|
|
| GET | `/api/characters/:id/audit-log/stats` | Change statistics |
|
|||
|
|
| POST | `/api/characters/lerncost` | Calculate learn/improve cost |
|
|||
|
|
| POST | `/api/characters/lerncost-new` | (Alias) Calculate learn/improve cost |
|
|||
|
|
| POST | `/api/characters/improve-skill` | Apply skill improvement |
|
|||
|
|
| POST | `/api/characters/improve-skill-new` | (Alias) Apply skill improvement |
|
|||
|
|
| POST | `/api/characters/:id/learn-skill` | Learn new skill |
|
|||
|
|
| POST | `/api/characters/:id/learn-skill-new` | (Alias) Learn new skill |
|
|||
|
|
| POST | `/api/characters/:id/learn-spell` | Learn new spell |
|
|||
|
|
| POST | `/api/characters/:id/learn-spell-new` | (Alias) Learn new spell |
|
|||
|
|
| POST | `/api/characters/available-skills` | Available skills to learn |
|
|||
|
|
| POST | `/api/characters/available-skills-new` | (Alias) |
|
|||
|
|
| POST | `/api/characters/available-skills-creation` | Skills for creation wizard |
|
|||
|
|
| POST | `/api/characters/available-spells` | Available spells to learn |
|
|||
|
|
| POST | `/api/characters/available-spells-new` | (Alias) |
|
|||
|
|
| POST | `/api/characters/available-spells-creation` | Spells for creation wizard |
|
|||
|
|
| GET | `/api/characters/spell-details` | Spell detail lookup |
|
|||
|
|
| GET | `/api/characters/:id/reward-types` | Reward options for this context |
|
|||
|
|
| GET | `/api/characters/:id/practice-points` | Current practice points |
|
|||
|
|
| PUT | `/api/characters/:id/practice-points` | Update practice points |
|
|||
|
|
| POST | `/api/characters/:id/practice-points/add` | Add a practice point |
|
|||
|
|
| POST | `/api/characters/:id/practice-points/use` | Use a practice point |
|
|||
|
|
| GET | `/api/characters/skill-categories` | Static skill category listing |
|
|||
|
|
| GET | `/api/characters/create-sessions` | List creation wizard sessions |
|
|||
|
|
| POST | `/api/characters/create-session` | Start creation wizard session |
|
|||
|
|
| GET | `/api/characters/create-session/:sessionId` | Get session data |
|
|||
|
|
| PUT | `/api/characters/create-session/:sessionId/basic` | Save basic info |
|
|||
|
|
| PUT | `/api/characters/create-session/:sessionId/attributes` | Save attributes |
|
|||
|
|
| PUT | `/api/characters/create-session/:sessionId/derived` | Save derived values |
|
|||
|
|
| PUT | `/api/characters/create-session/:sessionId/skills` | Save skills selection |
|
|||
|
|
| POST | `/api/characters/create-session/:sessionId/finalize` | Finalize creation |
|
|||
|
|
| DELETE | `/api/characters/create-session/:sessionId` | Discard session |
|
|||
|
|
| GET | `/api/characters/races` | Available races |
|
|||
|
|
| GET | `/api/characters/classes` | Available character classes |
|
|||
|
|
| GET | `/api/characters/classes/learning-points` | LP by class |
|
|||
|
|
| GET | `/api/characters/origins` | Available origins |
|
|||
|
|
| GET | `/api/characters/beliefs` | Faith search |
|
|||
|
|
| POST | `/api/characters/calculate-static-fields` | Calc derived values (no dice) |
|
|||
|
|
| POST | `/api/characters/calculate-rolled-field` | Calc derived value (with dice) |
|
|||
|
|
|
|||
|
|
**Equipment:**
|
|||
|
|
|
|||
|
|
| Method | Path | Purpose |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| POST | `/api/equipment` | Add equipment item |
|
|||
|
|
| GET | `/api/equipment/character/:character_id` | List equipment for character |
|
|||
|
|
| PUT | `/api/equipment/:ausruestung_id` | Update equipment |
|
|||
|
|
| DELETE | `/api/equipment/:ausruestung_id` | Delete equipment |
|
|||
|
|
| POST | `/api/weapons` | Add weapon |
|
|||
|
|
| GET | `/api/weapons/character/:character_id` | List weapons for character |
|
|||
|
|
| PUT | `/api/weapons/:waffe_id` | Update weapon |
|
|||
|
|
| DELETE | `/api/weapons/:waffe_id` | Delete weapon |
|
|||
|
|
|
|||
|
|
**Master Data (read — all authenticated, write — maintainers only):**
|
|||
|
|
|
|||
|
|
| Method | Path | Auth | Purpose |
|
|||
|
|
|--------|------|------|---------|
|
|||
|
|
| GET | `/api/maintenance` | Auth | All master data overview |
|
|||
|
|
| GET | `/api/maintenance/skills` | Auth | List skills |
|
|||
|
|
| GET | `/api/maintenance/skills/:id` | Auth | Get skill |
|
|||
|
|
| GET | `/api/maintenance/skills-enhanced` | Auth | List skills (rich) |
|
|||
|
|
| GET | `/api/maintenance/skills-enhanced/:id` | Auth | Get skill (rich) |
|
|||
|
|
| POST | `/api/maintenance/skills` | Maintainer | Create skill |
|
|||
|
|
| POST | `/api/maintenance/skills-enhanced` | Maintainer | Create skill (rich) |
|
|||
|
|
| PUT | `/api/maintenance/skills/:id` | Maintainer | Update skill |
|
|||
|
|
| PUT | `/api/maintenance/skills-enhanced/:id` | Maintainer | Update skill (rich) |
|
|||
|
|
| DELETE | `/api/maintenance/skills/:id` | Maintainer | Delete skill |
|
|||
|
|
| GET | `/api/maintenance/weaponskills[/:id]` | Auth | Weapon skill(s) |
|
|||
|
|
| GET | `/api/maintenance/weaponskills-enhanced[/:id]` | Auth | Weapon skill(s) (rich) |
|
|||
|
|
| POST/PUT/DELETE | `/api/maintenance/weaponskills[/:id]` | Maintainer | Weapon skill CRUD |
|
|||
|
|
| GET | `/api/maintenance/spells[/:id]` | Auth | Spell(s) |
|
|||
|
|
| GET | `/api/maintenance/spells-enhanced[/:id]` | Auth | Spell(s) (rich) |
|
|||
|
|
| POST/PUT/DELETE | `/api/maintenance/spells[/:id]` | Maintainer | Spell CRUD |
|
|||
|
|
| GET | `/api/maintenance/equipment[/:id]` | Auth | Equipment item(s) |
|
|||
|
|
| GET | `/api/maintenance/equipment-enhanced[/:id]` | Auth | Equipment (rich) |
|
|||
|
|
| POST/PUT/DELETE | `/api/maintenance/equipment[/:id]` | Maintainer | Equipment CRUD |
|
|||
|
|
| GET | `/api/maintenance/weapons[/:id]` | Auth | Master weapon(s) |
|
|||
|
|
| GET | `/api/maintenance/weapons-enhanced[/:id]` | Auth | Master weapon(s) (rich) |
|
|||
|
|
| POST/PUT/DELETE | `/api/maintenance/weapons[/:id]` | Maintainer | Weapon CRUD |
|
|||
|
|
|
|||
|
|
**Maintenance Admin (Maintainer required):**
|
|||
|
|
|
|||
|
|
| Method | Path | Purpose |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| GET | `/api/maintenance/gsm-believes` | List faith entries |
|
|||
|
|
| PUT | `/api/maintenance/gsm-believes/:id` | Update faith entry |
|
|||
|
|
| GET | `/api/maintenance/game-systems` | List game systems |
|
|||
|
|
| PUT | `/api/maintenance/game-systems/:id` | Update game system |
|
|||
|
|
| GET | `/api/maintenance/gsm-lit-sources` | List source books |
|
|||
|
|
| PUT | `/api/maintenance/gsm-lit-sources/:id` | Update source book |
|
|||
|
|
| GET | `/api/maintenance/gsm-misc` | MiscLookup entries |
|
|||
|
|
| PUT | `/api/maintenance/gsm-misc/:id` | Update misc entry |
|
|||
|
|
| GET/PUT | `/api/maintenance/skill-improvement-cost2[/:id]` | Improvement cost table |
|
|||
|
|
| GET | `/api/maintenance/setupcheck` | DB structure validation |
|
|||
|
|
| GET | `/api/maintenance/setupcheck-dev` | Extended setup check |
|
|||
|
|
| GET | `/api/maintenance/mktestdata` | Generate test snapshot from live DB |
|
|||
|
|
| GET | `/api/maintenance/reconndb` | Reconnect database |
|
|||
|
|
| GET | `/api/maintenance/reloadenv` | Reload .env config |
|
|||
|
|
| POST | `/api/maintenance/transfer-sqlite-to-mariadb` | Migrate data |
|
|||
|
|
|
|||
|
|
**PDF:**
|
|||
|
|
|
|||
|
|
| Method | Path | Auth | Purpose |
|
|||
|
|
|--------|------|------|---------|
|
|||
|
|
| GET | `/api/pdf/templates` | Auth | List available PDF templates |
|
|||
|
|
| GET | `/api/pdf/export/:id` | Auth | Export character to PDF |
|
|||
|
|
| POST | `/api/pdf/cleanup` | Auth | Clean up old PDFs |
|
|||
|
|
| GET | `/api/pdf/file/:filename` | Public | Download PDF file |
|
|||
|
|
|
|||
|
|
**Import/Export:**
|
|||
|
|
|
|||
|
|
| Method | Path | Purpose |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| POST | `/api/importer/upload` | Import character from VTT JSON |
|
|||
|
|
| POST | `/api/importer/spells/csv` | Import spells from CSV |
|
|||
|
|
| GET | `/api/importer/export/vtt/:id` | Export character as VTT JSON (response body) |
|
|||
|
|
| GET | `/api/importer/export/vtt/:id/file` | Export character as downloadable VTT JSON |
|
|||
|
|
| GET | `/api/importer/export/csv/:id` | Export character as CSV |
|
|||
|
|
| GET | `/api/importer/export/spells/csv` | Export all spells as CSV |
|
|||
|
|
| GET | `/api/transfer/export/:id` | Export character as BaMoRT JSON |
|
|||
|
|
| GET | `/api/transfer/download/:id` | Download character as JSON file |
|
|||
|
|
| POST | `/api/transfer/import` | Import character from BaMoRT JSON |
|
|||
|
|
| POST | `/api/transfer/database/export` | Full DB export to JSON |
|
|||
|
|
| POST | `/api/transfer/database/import` | Full DB import from JSON |
|
|||
|
|
|
|||
|
|
**System:**
|
|||
|
|
|
|||
|
|
| Method | Path | Auth | Purpose |
|
|||
|
|
|--------|------|------|---------|
|
|||
|
|
| GET | `/api/version` | Auth | App version + git commit |
|
|||
|
|
| GET | `/api/systeminfo` | Auth | Version + user/char counts + DB version |
|
|||
|
|
|
|||
|
|
**Admin (Admin role required):**
|
|||
|
|
|
|||
|
|
| Method | Path | Purpose |
|
|||
|
|
|--------|------|---------|
|
|||
|
|
| GET | `/api/users` | List all users |
|
|||
|
|
| GET | `/api/users/:id` | Get user by ID |
|
|||
|
|
| PUT | `/api/users/:id/role` | Change user role |
|
|||
|
|
| PUT | `/api/users/:id/password` | Change user password |
|
|||
|
|
| DELETE | `/api/users/:id` | Delete user |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. Testing Approach
|
|||
|
|
|
|||
|
|
### Test Environment Setup
|
|||
|
|
|
|||
|
|
Every test file that touches the database must call:
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
func setupTestEnvironment(t *testing.T) {
|
|||
|
|
original := os.Getenv("ENVIRONMENT")
|
|||
|
|
os.Setenv("ENVIRONMENT", "test")
|
|||
|
|
t.Cleanup(func() { os.Setenv("ENVIRONMENT", original) })
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Or the shared utility:
|
|||
|
|
```go
|
|||
|
|
testutils.SetupTestEnvironment(t)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
This causes `database.ConnectDatabase()` to open the SQLite test snapshot instead of MariaDB.
|
|||
|
|
|
|||
|
|
### Test Database Mechanism
|
|||
|
|
|
|||
|
|
1. `testdata/prepared_test_data.db` — a SQLite snapshot with real-world test data.
|
|||
|
|
2. `database.SetupTestDB(true)` copies this to a `os.MkdirTemp` location and opens it.
|
|||
|
|
3. Tests run against this isolated copy — no pollution of live data.
|
|||
|
|
4. Character ID 18 ("Fanjo Vetrani") is guaranteed to exist in the test DB.
|
|||
|
|
|
|||
|
|
### Test Structure Conventions
|
|||
|
|
|
|||
|
|
- All test files use `_test.go` suffix.
|
|||
|
|
- Test functions call `database.SetupTestDB(true)` or `testutils.SetupTestEnvironment(t)` first.
|
|||
|
|
- Integration tests use `testify/assert`.
|
|||
|
|
- Many module tests (`character_test.go`, `handlers_test.go`, etc.) use helper constructors from `test_data_helper.go`.
|
|||
|
|
- The `api/api_test.go` package runs HTTP tests using `httptest.NewRecorder()`.
|
|||
|
|
- `maintenance/copy_db_test.go` tests the DB snapshot refresh mechanism.
|
|||
|
|
- Test data helpers (`character/test_data_helper.go`) provide `CreateTestCharacter()`, etc.
|
|||
|
|
|
|||
|
|
### Key Test Files by Module
|
|||
|
|
|
|||
|
|
| Module | Test Files |
|
|||
|
|
|--------|-----------|
|
|||
|
|
| `api/` | `api_test.go` — Integration |
|
|||
|
|
| `character/` | `character_test.go`, `handlers_test.go`, `lerncost_handler_test.go`, `skill_update_test.go`, `learn_spell_test.go`, etc. |
|
|||
|
|
| `database/` | `database_test.go`, `testhelper_test.go` |
|
|||
|
|
| `gsmaster/` | `gsmaster_test.go`, `learning_costs_test.go`, `export_import_test.go` |
|
|||
|
|
| `importer/` | `importer_test.go`, `charimport_test.go`, `upload_test.go` |
|
|||
|
|
| `maintenance/` | `handlers_test.go`, `masterdata_handlers_test.go`, `copy_db_test.go` |
|
|||
|
|
| `models/` | `model_character_test.go`, `model_char_skills_test.go`, `model_learning_costs_test.go` |
|
|||
|
|
| `pdfrender/` | `chromedp_test.go`, `mapper_test.go`, `pagination_test.go`, `integration_test.go` |
|
|||
|
|
| `transfer/` | `database_test.go`, `exporter_test.go`, `importer_test.go` |
|
|||
|
|
| `user/` | `handlers_test.go`, `role_test.go` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 11. Key Dependencies
|
|||
|
|
|
|||
|
|
| Dependency | Version | Purpose |
|
|||
|
|
|-----------|---------|---------|
|
|||
|
|
| `github.com/gin-gonic/gin` | v1.10.0 | HTTP framework |
|
|||
|
|
| `github.com/gin-contrib/cors` | v1.7.3 | CORS middleware |
|
|||
|
|
| `gorm.io/gorm` | v1.25.12 | ORM |
|
|||
|
|
| `gorm.io/driver/mysql` | v1.5.7 | MySQL/MariaDB driver |
|
|||
|
|
| `gorm.io/driver/sqlite` | v1.5.7 | SQLite driver (tests + dev) |
|
|||
|
|
| `github.com/chromedp/chromedp` | v0.14.2 | Headless Chrome for PDF rendering |
|
|||
|
|
| `github.com/pdfcpu/pdfcpu` | v0.11.1 | PDF merging |
|
|||
|
|
| `github.com/stretchr/testify` | v1.10.0 | Test assertions |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 12. Security Observations
|
|||
|
|
|
|||
|
|
### Critical Issues
|
|||
|
|
|
|||
|
|
1. **Weak Token Authentication**: The custom token embeds the user ID in a predictable location. Any token with any valid user ID at position `7 + len("Bearer ")` is accepted. There is **no HMAC or digital signature**. An attacker can forge tokens.
|
|||
|
|
|
|||
|
|
2. **MD5 Password Hashing**: Passwords are stored as MD5 hashes. MD5 is cryptographically broken for password storage; brute-force and rainbow-table attacks are trivial. Should be replaced with bcrypt, argon2id, or scrypt.
|
|||
|
|
|
|||
|
|
3. **Token Leaks User ID**: The token format encodes the user ID in plaintext, revealing enumerable user IDs to clients.
|
|||
|
|
|
|||
|
|
### Moderate Concerns
|
|||
|
|
|
|||
|
|
4. **Debug Logging of Passwords**: `handlers.go` has `fmt.Printf("pwdh: %s", ...)` that prints password hashes to stdout on every login — a security logging issue.
|
|||
|
|
|
|||
|
|
5. **Hardcoded Origins in CORS**: Local network IPs (`192.168.0.48`, `192.168.0.36`) are hardcoded — appropriate for development but should be env-driven for production.
|
|||
|
|
|
|||
|
|
6. **Importer File Upload**: `UploadFiles` saves files to `./uploads/` relative path without sanitizing filenames for path traversal. The extension validation (`isValidFileType`) only checks the suffix.
|
|||
|
|
|
|||
|
|
7. **SQL Injection via `fieldName`**: `GetMiscLookupByKeyForSystem` constructs `query.Order(orderBy)` from a user-supplied `order` parameter — however the value is mapped to a safe set of constants before use, so actual injection risk is mitigated.
|
|||
|
|
|
|||
|
|
8. **No rate limiting**: Login and registration endpoints have no rate limiting, making them susceptible to brute-force attacks.
|
|||
|
|
|
|||
|
|
### Notes
|
|||
|
|
|
|||
|
|
- The bcrypt implementation is commented out in `handlers.go` with the MD5 hash in use — this is intentional but documents the known deficit.
|
|||
|
|
- Password reset tokens use `crypto/rand` (secure, 32 bytes), which is correct.
|
|||
|
|
- GORM parameterized queries protect most DB operations from SQL injection.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 13. Cross-Module Relationships Diagram
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
cmd/main.go
|
|||
|
|
├── config ──────────────────────────────────── read by all modules
|
|||
|
|
├── logger ──────────────────────────────────── used by all modules
|
|||
|
|
├── database ─────────────────────────────────── .DB used by all models
|
|||
|
|
│ └── testutils ────────────────────────── test env setup
|
|||
|
|
├── router
|
|||
|
|
│ └── user (AuthMiddleware, role guards)
|
|||
|
|
├── user ─────────────────── handlers, model, auth
|
|||
|
|
│ └── mail (SMTP for password reset)
|
|||
|
|
├── models ────────────────── GORM entities, MigrateStructure
|
|||
|
|
│ ├── user.User (FK in Char)
|
|||
|
|
│ └── database.DB (queries)
|
|||
|
|
├── character ─────────────── CRUD + learning + creation wizard
|
|||
|
|
│ ├── models (Char, SkFertigkeit, SkZauber, etc.)
|
|||
|
|
│ ├── gsmaster (LerncostRequest, skill lookups)
|
|||
|
|
│ └── database.DB
|
|||
|
|
├── equipment ─────────────── Equipment/Weapon CRUD
|
|||
|
|
│ ├── models (EqAusruestung, EqWaffe)
|
|||
|
|
│ └── database.DB
|
|||
|
|
├── gsmaster ──────────────── Master data (skills/spells/weapons)
|
|||
|
|
│ ├── models (Skill, Spell, Weapon, etc.)
|
|||
|
|
│ ├── user (RequireMaintainer guard)
|
|||
|
|
│ └── database.DB
|
|||
|
|
├── gamesystem ────────────── GameSystem seed/migration
|
|||
|
|
│ └── models.GameSystem
|
|||
|
|
├── maintenance ───────────── Admin tooling, migration orchestration
|
|||
|
|
│ ├── database, gamesystem, user, models (all MigrateStructure)
|
|||
|
|
│ └── user (RequireMaintainer guard)
|
|||
|
|
├── pdfrender ─────────────── HTML→PDF pipeline
|
|||
|
|
│ ├── models.Char (character data)
|
|||
|
|
│ └── config (TemplatesDir, ExportTempDir)
|
|||
|
|
├── importer ──────────────── VTT/CSV import/export
|
|||
|
|
│ └── models (Char, Skill, Spell)
|
|||
|
|
├── transfer ──────────────── JSON character + DB backup
|
|||
|
|
│ └── models.Char
|
|||
|
|
└── appsystem ─────────────── Version info
|
|||
|
|
└── database.DB (count queries)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
*End of findings — /home/de31a2/bamort/backend_findings.md*
|