vtuber-awards/update_v2_docx_stack.py

from docx import Document
from docx.shared import Pt


DOC_PATH = "/Users/azu/Desktop/VTubeAwards/VTuber Star Awards - Website V2.docx"


def add_paragraph(doc: Document, text: str):
    p = doc.add_paragraph()
    p.paragraph_format.space_after = Pt(6)
    p.paragraph_format.line_spacing = 1.1
    p.add_run(text)


def add_bullet(doc: Document, text: str):
    p = doc.add_paragraph(style="List Bullet")
    p.paragraph_format.space_after = Pt(4)
    p.paragraph_format.line_spacing = 1.15
    p.add_run(text)


def add_number(doc: Document, text: str):
    p = doc.add_paragraph(style="List Number")
    p.paragraph_format.space_after = Pt(4)
    p.paragraph_format.line_spacing = 1.15
    p.add_run(text)


def add_table(doc: Document, headers: list[str], rows: list[list[str]]):
    table = doc.add_table(rows=1, cols=len(headers))
    table.style = "Table Grid"
    for index, header in enumerate(headers):
        table.rows[0].cells[index].text = header
    for row in rows:
        cells = table.add_row().cells
        for index, value in enumerate(row):
            cells[index].text = value


def main():
    doc = Document(DOC_PATH)

    doc.add_heading("15. Festgelegte Produktentscheidungen seit V2", level=1)
    add_bullet(doc, "Award-Kategorien und Unterkategorien werden nicht hart im Code festgelegt, sondern vom Team pro Jahr im Admin-Bereich gepflegt.")
    add_bullet(doc, "Das Endergebnis ist fuer den aktuellen MVP-Stand rein community-basiert. Eine spaetere Jury-/Panel-Gewichtung bleibt technisch als Erweiterung offen.")
    add_bullet(doc, "Die technische Umsetzung wird als Monorepo mit getrenntem Frontend und Backend aufgebaut.")
    add_bullet(doc, "Dieses Dokument bleibt die fachliche Referenz fuer weitere Iterationen. Code und Architektur sollen sich an den hier beschriebenen Produktregeln orientieren.")

    doc.add_heading("16. Finaler Tech-Stack fuer die Umsetzung", level=1)
    add_paragraph(
        doc,
        "Die Implementierung wird in zwei klar getrennten Anwendungen aufgebaut: ein Vue-basiertes Frontend fuer Public- und Admin-Oberflaechen sowie ein ASP.NET-Core-Backend fuer API, Datenmodell und Persistenz. Damit bleibt die Awards-Plattform spaeter erweiterbar fuer Auth, Moderation, CMS und Analytics."
    )
    add_table(
        doc,
        ["Schicht", "Technologie", "Rolle im System"],
        [
            ["Frontend", "Vue 3 + Vite", "SPA fuer Landingpage, Voting, Nominierung, Gewinnerarchiv und Admin-Oberflaechen"],
            ["State", "Pinia", "Zentraler Client-State fuer Overview-, Voting-, Nominierungs- und Admin-Daten"],
            ["Styling", "Tailwind CSS", "Token-basierte Layout-, Spacing- und Komponenten-Styling-Schicht"],
            ["UI Library", "PrimeVue", "Tabellen, Accordions, Form Controls und datenlastige Admin-Bausteine"],
            ["UI Patterns", "shadcn-inspirierte Vue Komponenten", "Buttons, Cards und leichtgewichtige, konsistente Primitive fuer das Designsystem"],
            ["Backend", "ASP.NET Core 8", "REST API, Domänenlogik, Validierung und Integrationsschicht"],
            ["ORM", "EF Core 8", "Mapping des Awards-Datenmodells und Query-/Persistenzlogik"],
            ["Datenbank", "PostgreSQL", "Primäre relationale Persistenz fuer Seasons, Kategorien, Kandidaten, Nominierungen und Votes"],
        ],
    )

    doc.add_heading("17. Frontend-Architektur", level=1)
    add_paragraph(
        doc,
        "Das Frontend wird als Vite-Vue-Anwendung mit Router und Pinia aufgebaut. Die oeffentlichen Bereiche und der Admin-Bereich teilen sich dieselbe Design-Basis, werden aber als getrennte Views organisiert. PrimeVue kommt dort zum Einsatz, wo datenlastige oder interaktive Controls den Entwicklungsaufwand senken; leichtgewichtige Basis-UI wie Buttons und Cards werden als shadcn-artige Vue-Primitives lokal gepflegt."
    )
    add_number(doc, "AppShell mit globaler Navigation, Branding und CTA-Struktur fuer oeffentliche und interne Oberflaechen.")
    add_number(doc, "Router-basierte Views fuer Home, Nominierung, Voting, Gewinner und Admin.")
    add_number(doc, "Pinia Store als API-Orchestrator fuer Overview, Saisonkategorien, Gewinnerarchiv und Admin Dashboard.")
    add_number(doc, "API-Layer mit konfigurierbarer Backend-URL ueber Vite-Environment-Variable.")
    add_number(doc, "Fallback-Daten im Frontend, damit UI-Entwicklung und Demo-Zustaende nicht vom sofort verfuegbaren Backend abhaengen.")

    doc.add_heading("18. Backend-Architektur", level=1)
    add_paragraph(
        doc,
        "Das Backend wird als ASP.NET-Core-Web-API mit EF Core 8 und PostgreSQL aufgebaut. Die erste Version priorisiert ein sauberes Domänenmodell und lesbare Public-/Admin-Endpunkte vor Auth-, Moderations- oder CMS-Komplexität. Die API ist damit spaeter gut erweiterbar fuer Twitch OAuth, Session-Management, Missbrauchsschutz und Review-Workflows."
    )
    add_table(
        doc,
        ["Bereich", "Implementationsidee"],
        [
            ["Public API", "Overview fuer Landingpage, saisonbezogene Kategorien, Gewinnerarchiv, Nominierungs- und Voting-Endpunkte"],
            ["Admin API", "Dashboard-Metriken, Aktivitaeten und spaeter Management-Endpunkte fuer Kategorien, Reviews und Risk Flags"],
            ["Persistenz", "EF-Core-DbContext mit PostgreSQL Provider und relationalem Datenmodell"],
            ["Seed Data", "Starterdaten fuer aktuelle und vergangene Seasons, Kategorien, Kandidaten und Gewinner"],
            ["CORS", "Explizite Freigabe fuer lokale Frontend-Hosts waehrend der Entwicklung"],
        ],
    )

    doc.add_heading("19. Finales Datenmodell fuer den MVP", level=1)
    add_bullet(doc, "Season: Jahr, Phase, Show-Datum, Community-only-Flag und Zeitfenster fuer Nominierung/Voting/Review.")
    add_bullet(doc, "Category: saisongebundene Kategorie mit Grouping, Beschreibung, Sortierung und Nominierungslimits.")
    add_bullet(doc, "Candidate: saison- und kategorienbezogene Kandidatenbasis fuer Voting und Archiv.")
    add_bullet(doc, "AwardResult: Gewinnerabbildung fuer Archiv und Rueckblicke.")
    add_bullet(doc, "Nomination: vom User eingereichte Nominierungen inkl. Freitext-/Alias-Faellen.")
    add_bullet(doc, "VoteBallot + VoteEntry: eingereichte Votes pro User und Kategorie.")

    doc.add_heading("20. API-Schnittstellen fuer den aktuellen Stand", level=1)
    add_bullet(doc, "GET /api/public/overview - Landingpage- und Event-Zusammenfassung.")
    add_bullet(doc, "GET /api/public/seasons/{year}/categories - Kategorien und Kandidaten eines Jahres.")
    add_bullet(doc, "GET /api/public/seasons/{year}/winners - Gewinnerarchiv je Jahr.")
    add_bullet(doc, "POST /api/public/nominations - Speichern von Nominierungs-Entwuerfen/Einreichungen.")
    add_bullet(doc, "POST /api/public/votes - Speichern eines Voting-Ballots.")
    add_bullet(doc, "GET /api/admin/dashboard - Kennzahlen und Aktivitaeten fuer die Admin-Uebersicht.")

    doc.add_heading("21. Projektstruktur im Repository", level=1)
    add_bullet(doc, "frontend/ - Vue 3 + Vite Anwendung")
    add_bullet(doc, "Backend/ - ASP.NET Core 8 Web API")
    add_bullet(doc, "prototype/ - fruehere visuelle Prototyping-Artefakte und Designexperimente")
    add_bullet(doc, "README.md - lokaler Startpunkt fuer Setup und Entwicklungsworkflow")

    doc.add_heading("22. Implementierungsstatus", level=1)
    add_bullet(doc, "Frontend-Grundgeruest aufgebaut: Router, Pinia Store, AppShell, Public Views und Admin View.")
    add_bullet(doc, "PrimeVue und Tailwind in die Frontend-Basis integriert.")
    add_bullet(doc, "shadcn-artige Basis-Komponenten fuer Buttons und Cards lokal angelegt.")
    add_bullet(doc, "Backend-Web-API mit EF-Core-Domänenmodell, Seed-Daten und Public-/Admin-Endpunkten implementiert.")
    add_bullet(doc, "Frontend und Backend kompilieren erfolgreich. Datenbank-Migrationen und produktive Auth-/Session-Flows sind der naechste technische Schritt.")

    doc.add_heading("23. Empfohlene naechste technische Schritte", level=1)
    add_number(doc, "PostgreSQL lokal oder in einer Dev-Umgebung bereitstellen und erste EF-Core-Migration erzeugen.")
    add_number(doc, "Twitch OAuth serverseitig ins Backend integrieren und Session-Management anschliessen.")
    add_number(doc, "Nominierungs- und Voting-Endpunkte um echte User-Identitaet, Limits und Idempotenz erweitern.")
    add_number(doc, "Admin-Endpunkte fuer Season-/Category-Management, Reviews und Risk Flags ausbauen.")
    add_number(doc, "Frontend-Design auf final freigegebene visuelle Richtung und Assets angleichen.")

    doc.save(DOC_PATH)


if __name__ == "__main__":
    main()