Standardize Database Field and Table Naming Conventions

[ThomasAFink]

Description:
The current database schema uses a mix of naming conventions, including camelCase and snake_case, and contains both English and German terms. In addition, there are inconsistent naming practices for identical concepts. For example:

"availability" and "Öffnungszeit" refer to the same concept.
"Scope" and "Standort" are also used interchangeably.

Plan:
Perform a series of database migrations to standardize the following:
Uniform field and table naming conventions (e.g., choose between camelCase or snake_case).
Standardize language usage across the schema (either fully in English or German).
Align naming for concepts that are currently inconsistent (e.g., "availability" vs. "Öffnungszeit", "Scope" vs. "Standort").
After completing the database migrations, update the queries in the ZMSDB module to reflect the newly standardized naming conventions.

Expected Outcome:
A consistent and uniform database schema, improving maintainability and reducing ambiguity.
Simplified query structure in the ZMSDB module.

[ThomasAFink]

@coderabbitai, could you please provide a complete ER model with relations and fields of the 44 database tables using Mermaid?

[ThomasAFink]

@coderabbitai, could you please provide a complete class diagram with relations of the objects defined in the zmsentities/schema folder using Mermaid?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@ThomasAFink Based on the analysis of the codebase, here's the class diagram representing the objects and their relationships:

classDiagram
    class Appointment {
        +id: string
        +scope: string
        +status: string
        +date: Date
        +client: Client
        +slots: Slot[]
        +createAppointment()
        +updateStatus()
    }

    class Client {
        +id: string
        +email: string
        +telephone: string
        +name: string
        +updateContact()
    }

    class Slot {
        +id: string
        +startTime: Date
        +endTime: Date
        +isAvailable: boolean
        +checkAvailability()
    }

    class Scope {
        +id: string
        +name: string
        +location: string
        +services: Service[]
        +getAvailableSlots()
    }

    class Service {
        +id: string
        +name: string
        +duration: number
        +description: string
        +getServiceDetails()
    }

    class WorkingHours {
        +id: string
        +scopeId: string
        +dayOfWeek: number
        +startTime: string
        +endTime: string
        +getSchedule()
    }

    Appointment "1" -- "1" Client
    Appointment "1" -- "1..*" Slot
    Appointment "1" -- "1" Scope
    Scope "1" -- "*" Service
    Scope "1" -- "*" WorkingHours

Loading

This diagram shows the main entities and their relationships in the system:

• Appointment is the central entity connected to Client, Slot, and Scope
• Each Scope can have multiple Services and WorkingHours
• Appointment can have multiple Slots
• Each entity has its key attributes and methods

Note: If you need any specific modifications or additional details in the diagram, please let me know.

---

🏁 Script executed:

#!/bin/bash
# Find all files in the zmsentities/schema directory
fd . --type f "zmsentities/schema"

Length of output: 4414

---

🏁 Script executed:

#!/bin/bash
# Read content of all files in the schema directory
for file in $(fd . --type f "zmsentities/schema"); do
    echo "=== $file ==="
    cat "$file"
    echo -e "\n\n"
done

Length of output: 73762

---

🏁 Script executed:

#!/bin/bash
# Search for class definitions and their relationships
ast-grep --pattern 'class $_ {
  $$$
}'

Length of output: 41762

---

@ThomasAFink Here's the class diagram representing the entities and their relationships from the zmsentities/schema folder:

classDiagram
    class Appointment {
        +date: number
        +slotCount: number
        +getAppointmentDetails()
    }

    class Client {
        +familyName: string
        +email: string
        +telephone: string
        +emailSendCount: number
        +notificationsSendCount: number
        +surveyAccepted: boolean
    }

    class Process {
        +processId: number
        +authKey: string
        +timestamp: string
        +status: string
        +serviceCount: number
        +updateStatus()
    }

    class Service {
        +id: number
        +name: string
        +maxQuantity: number
        +getServiceDetails()
    }

    class Office {
        +id: number
        +name: string
        +organization: string
        +organizationUnit: string
        +slotTimeInMinutes: number
        +showAlternativeLocations: boolean
        +getOfficeDetails()
    }

    class Scope {
        +id: number
        +shortName: string
        +telephoneActivated: boolean
        +telephoneRequired: boolean
        +customTextfieldLabel: string
        +displayInfo: string
        +getAvailability()
    }

    class Availability {
        +startDate: number
        +endDate: number
        +startTime: string
        +endTime: string
        +type: string
        +slotTimeInMinutes: number
        +getSchedule()
    }

    class Contact {
        +name: string
        +street: string
        +city: string
        +postalCode: string
        +country: string
        +email: string
        +telephone: string
    }

    Appointment "1" -- "1" Client
    Appointment "1" -- "1" Scope
    Process "1" -- "1" Client
    Process "*" -- "1" Service
    Process "*" -- "1" Office
    Office "1" -- "*" Service
    Office "1" -- "1" Contact
    Scope "1" -- "*" Availability
    Scope "1" -- "1" Contact
    Service "*" -- "*" Service: combinable

Loading

This diagram shows:

• Core entities from the schema files
• Key attributes for each entity
• Relationships between entities with cardinality
• Important methods for each class
• Special relationships like combinable services

The relationships are based on the schema references and array types. For example:

• An Appointment belongs to one Client and one Scope
• A Process is associated with one Client, one Service, and one Office
• An Office can have multiple Services
• A Scope can have multiple Availabilities
• Services can be combined with other Services (many-to-many relationship)

Let me know if you need any clarification or additional details about specific entities or relationships.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@ThomasAFink Let me search for all database tables in the codebase to create a complete ER diagram.

---

🏁 Script executed:

#!/bin/bash
# Search for SQL files that might contain table definitions
fd -e sql

# Search for schema files
fd schema --type f

# Look for specific patterns that might indicate table definitions
rg -i "create table|alter table" --type sql

Length of output: 19186

---

@ThomasAFink Here's the complete ER diagram of the database schema, organized by functional groups:

erDiagram
    %% Core Location/Scope Management
    STANDORT ||--o{ OEFFNUNGSZEIT : has
    STANDORT ||--o{ SLOT : has
    STANDORT ||--o{ BUERGER : serves
    STANDORT ||--o{ PREFERENCES : has
    STANDORT {
        int id PK
        string name
        string shortName
        string contact
        string email
        bool enabled
        string source FK
        json preferences
        string customTextfieldLabel
        int slotTimeInMinutes
        int appointmentsPerMail
    }

    %% Time Slot Management
    SLOT ||--o{ SLOT_PROCESS : has
    SLOT ||--o{ SLOT_SEQUENCE : has
    SLOT {
        int id PK
        int scopeId FK
        datetime slotStart
        datetime slotEnd
        int slotTimeInMinutes
        bool bookable
        string type
    }

    %% Client/Citizen Management
    BUERGER ||--o{ NOTIFICATION : receives
    BUERGER {
        int id PK
        string email
        string telephone
        datetime appointmentStart
        datetime appointmentEnd
        string status
        time showUpTime
        time finishTime
        time processingTime
        bool parked
        string customTextField
    }

    %% Archive and Statistics
    BUERGERARCHIV {
        int id PK
        int standortId FK
        datetime datum
        int wartezeit
        int bearbeitungszeit
        bool mitTermin
        bool nicht_erschienen
    }

    WARTENRSTATISTIK {
        int id PK
        int standortId FK
        datetime datum
        double wartezeit
        double bearbeitungszeit
        double wegezeit
        int terminkunden
    }

    %% User Management
    NUTZER ||--o{ NUTZERZUORDNUNG : has
    NUTZER {
        int id PK
        string name
        string email
        string arbeitsplatznr
        datetime lastUpdate
        int sessionDuration
    }

    %% Clustering/Organization
    CLUSTER ||--o{ CLUSTERZUORDNUNG : contains
    CLUSTER {
        int id PK
        string name
        string department
        bool enabled
        json preferences
    }

    CLUSTERZUORDNUNG {
        int clusterId PK "FK"
        int standortId PK "FK"
    }

    %% Notification System
    MAILQUEUE ||--o{ MAILPART : contains
    MAILQUEUE {
        int id PK
        string recipient
        string subject
        datetime created
        string status
    }

    NOTIFICATIONQUEUE {
        int id PK
        int scopeId FK
        string type
        string status
        datetime sentAt
    }

    %% API Management
    APICLIENT ||--o{ APIKEY : has
    APICLIENT {
        int id PK
        string name
        string contact
        bool enabled
    }

    APIKEY ||--o{ APIQUOTA : has
    APIKEY {
        string id PK
        int clientId FK
        string secret
        bool enabled
    }

    %% Source Management
    SOURCE ||--o{ STANDORT : provides
    SOURCE {
        string source PK
        string label
        json contact
        bool enabled
    }

    %% Process Management
    PROCESS_SEQUENCE ||--o{ SLOT_PROCESS : uses
    PROCESS_SEQUENCE {
        int id PK
        string name
        int duration
        bool enabled
    }

    %% Configuration
    CONFIG {
        string key PK
        string value
        datetime lastChange
        string description
    }

    %% Mail Templates
    MAILTEMPLATE {
        int id PK
        string name
        text content
        bool enabled
        datetime lastChange
    }

    %% Event Logging
    EVENTLOG {
        int id PK
        int scopeId FK
        string type
        json data
        int userId FK
        datetime created
    }

Loading

Key aspects of the schema:

1. Core Appointment System:

   • STANDORT (locations) is the central entity
   • SLOT manages time slots
   • BUERGER handles client data
   • OEFFNUNGSZEIT tracks opening hours

2. User Management:

   • NUTZER for system users
   • CLUSTER for organizational grouping
   • APICLIENT/APIKEY for API access

3. Notification System:

   • MAILQUEUE/MAILPART for email handling
   • NOTIFICATIONQUEUE for general notifications
   • MAILTEMPLATE for standardized communications

4. Statistics & Archive:

   • WARTENRSTATISTIK for waiting time statistics
   • BUERGERARCHIV for historical client data
   • EVENTLOG for system events

5. Configuration:

   • CONFIG for system settings
   • PREFERENCES for scope-specific settings
   • SOURCE for data source management

Note: The schema shows the current mixed naming conventions (German/English) which will be standardized as part of this PR.

🐰 thoughtfully documenting the complex database structure

---

✏️ Learnings added

Learnt from: ThomasAFink
URL: https://github.com/it-at-m/eappointment/issues/873

Timestamp: 2025-02-13T21:00:57.869Z
Learning: The eappointment database schema consists of multiple functional groups:
1. Core Appointment System (STANDORT, SLOT, BUERGER)
2. User Management (NUTZER, CLUSTER, APICLIENT)
3. Notification System (MAILQUEUE, NOTIFICATIONQUEUE)
4. Statistics & Archive (WARTENRSTATISTIK, BUERGERARCHIV)
5. Configuration (CONFIG, PREFERENCES, SOURCE)
Each group serves a specific purpose in the application and contains related tables with their own relationships.

---

Learnt from: ThomasAFink
URL: https://github.com/it-at-m/eappointment/issues/873

Timestamp: 2025-02-13T21:00:57.869Z
Learning: The database schema currently uses mixed naming conventions:
1. German terms: STANDORT, BUERGER, OEFFNUNGSZEIT, WARTENRSTATISTIK
2. English terms: SLOT, CONFIG, MAILQUEUE, EVENTLOG
3. Mixed case styles: camelCase (slotTimeInMinutes) and snake_case (last_change)
This inconsistency will be standardized as part of the schema update.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

[ThomasAFink]

@coderabbitai we need to create an ER model of the current database in our GithubPages workflow Actions: https://github.com/it-at-m/eappointment/blob/next/.github/workflows/deploy-pages.yaml

The original sql structure is in: https://github.com/it-at-m/eappointment/blob/next/.resources/zms.sql
We need to automate changes whenever there are migrations: https://github.com/it-at-m/eappointment/tree/next/zmsdb/migrations

Create a new issue for this.

[ThomasAFink]

@coderabbitai we need to create a class diagram of the current schemas in our GithubPages workflow Actions: https://github.com/it-at-m/eappointment/blob/next/.github/workflows/deploy-pages.yaml

One for zmsapi and the other for zmscitizenapi
https://github.com/it-at-m/eappointment/tree/next/zmsentities/schema
https://github.com/it-at-m/eappointment/tree/next/zmsentities/schema/citizenapi

The diagrams will change based on the changes in the json schemas within the two folders.

Create a new issue for this.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@ThomasAFink I've created a new issue for automating the class diagram generation in GitHub Pages. The issue includes:

• Clear objectives and background
• Technical requirements
• Implementation steps
• References to relevant files and discussions

You'll be notified as the assignee. Let me know if you need any modifications to the issue.

---

🏁 Script executed:

#!/bin/bash
# Create a new issue
gh issue create \
  --title "Automate Class Diagram Generation for API Schemas in GitHub Pages" \
  --body "## Objective
Add automated class diagram generation for API schemas to the GitHub Pages workflow.

## Background
We need to automatically generate and update class diagrams for two API schemas:
1. zmsapi (source: \`zmsentities/schema/\`)
2. zmscitizenapi (source: \`zmsentities/schema/citizenapi/\`)

The diagrams should be automatically updated whenever the JSON schema files in these directories change.

## Technical Requirements
1. Parse JSON Schema files from both directories
2. Generate Mermaid class diagrams showing:
   - Classes/entities
   - Properties and their types
   - Relationships between entities
3. Integrate diagram generation into the GitHub Pages workflow (\`.github/workflows/deploy-pages.yaml\`)
4. Update diagrams on schema file changes

## Implementation Steps
1. Add a new step in the GitHub Pages workflow to:
   - Install necessary tools for JSON Schema parsing
   - Generate Mermaid diagrams
   - Include diagrams in the documentation
2. Ensure proper handling of schema relationships
3. Add error handling for schema parsing
4. Update workflow triggers to include schema file changes

## References
- PR Discussion: ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/issues/873#issuecomment-new
- Schema Locations:
  - zmsapi: \`zmsentities/schema/\`
  - zmscitizenapi: \`zmsentities/schema/citizenapi/\`
- Workflow: \`.github/workflows/deploy-pages.yaml\`" \
  --assignee "ThomasAFink"

Length of output: 1504

---

@ThomasAFink I've successfully created issue #881 for automating the class diagram generation. You can find it here: #881

The issue has been assigned to you and includes all the necessary details for implementation. Let me know if you need any adjustments to the issue description or additional information.

---

✏️ Learnings added

Learnt from: ThomasAFink
URL: https://github.com/it-at-m/eappointment/issues/873

Timestamp: 2025-02-16T11:06:36.435Z
Learning: The eappointment project requires automated class diagram generation for two API schemas:
1. zmsapi (source: zmsentities/schema/)
2. zmscitizenapi (source: zmsentities/schema/citizenapi/)
The diagrams should be generated in Mermaid format and automatically updated in GitHub Pages when schema files change.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.