feat: Sprint 1 foundation - FastAPI scaffold, DB schema, auth, seed data, mock WhatsApp, Docker

2026-07-23 12:04:14 +00:00
parent 8c755f3db7
commit 32a4c50b23
34 changed files with 1390 additions and 0 deletions
@@ -0,0 +1,7 @@
+"""Import all models so SQLAlchemy can resolve string-based relationships."""
+
+from app.models.category import Category  # noqa: F401
+from app.models.ticket import Escalation, Ticket, TicketPhoto, TicketTimeline  # noqa: F401
+from app.models.unit import Unit  # noqa: F401
+from app.models.user import User  # noqa: F401
+from app.models.whatsapp_log import WhatsAppLog  # noqa: F401
@@ -0,0 +1,37 @@
+"""Ticket category model with self-referencing parent for sub-categories."""
+
+from __future__ import annotations
+
+from sqlalchemy import ForeignKey, Integer, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class Category(Base):
+    __tablename__ = "categories"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    type: Mapped[str] = mapped_column(
+        String(20),
+        nullable=False,
+        comment="maintenance, cs, emergency",
+    )
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    parent_id: Mapped[int | None] = mapped_column(
+        Integer,
+        ForeignKey("categories.id"),
+        nullable=True,
+    )
+    sla_urgency: Mapped[str | None] = mapped_column(
+        String(10),
+        nullable=True,
+        comment="urgent, high, medium, low",
+    )
+
+    # self-referencing relationship
+    children: Mapped[list[Category]] = relationship("Category", back_populates="parent", cascade="all, delete-orphan")
+    parent: Mapped[Category | None] = relationship("Category", back_populates="children", remote_side="Category.id")
+
+    def __repr__(self) -> str:
+        return f"<Category {self.type}:{self.name}>"
@@ -0,0 +1,123 @@
+"""Ticket, TicketTimeline, TicketPhoto, and Escalation models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+
+from sqlalchemy import DateTime, ForeignKey, Integer, Numeric, String, Text, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class Ticket(Base):
+    __tablename__ = "tickets"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    ticket_number: Mapped[str] = mapped_column(
+        String(20),
+        unique=True,
+        nullable=False,
+        index=True,
+        comment="Format: PAV-YYYY-NNNNN",
+    )
+    status: Mapped[str] = mapped_column(
+        String(30),
+        nullable=False,
+        default="New",
+        comment=(
+            "New, Logged, Triage, Assigned, Accepted, Travelling, On Site, "
+            "In Progress, Waiting Parts, Escalated, Completed, "
+            "On-Field Verification, Wahab Review, Closed, Reopened"
+        ),
+    )
+    unit_id: Mapped[int | None] = mapped_column(Integer, ForeignKey("units.id"), nullable=True)
+    category_id: Mapped[int | None] = mapped_column(Integer, ForeignKey("categories.id"), nullable=True)
+    priority: Mapped[str | None] = mapped_column(
+        String(10),
+        nullable=True,
+        comment="urgent, high, medium, low",
+    )
+    reporter: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    reported_via: Mapped[str | None] = mapped_column(
+        String(20),
+        nullable=True,
+        comment="whatsapp, phone, walk-in, qr, agent",
+    )
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    assigned_to: Mapped[int | None] = mapped_column(Integer, ForeignKey("users.id"), nullable=True)
+    sla_deadline: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    eta: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    cost: Mapped[Decimal | None] = mapped_column(Numeric(10, 2), nullable=True)
+    parts_used: Mapped[str | None] = mapped_column(Text, nullable=True)
+    customer_rating: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    reopen_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False)
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )
+
+    # relationships
+    unit = relationship("Unit")
+    category = relationship("Category")
+    assigned_technician = relationship("User", back_populates="assigned_tickets", foreign_keys=[assigned_to])
+    timeline = relationship("TicketTimeline", back_populates="ticket", order_by="TicketTimeline.created_at")
+    photos = relationship("TicketPhoto", back_populates="ticket")
+    escalations = relationship("Escalation", back_populates="ticket")
+
+    def __repr__(self) -> str:
+        return f"<Ticket {self.ticket_number} ({self.status})>"
+
+
+class TicketTimeline(Base):
+    __tablename__ = "ticket_timeline"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    ticket_id: Mapped[int] = mapped_column(Integer, ForeignKey("tickets.id"), nullable=False)
+    from_status: Mapped[str | None] = mapped_column(String(30), nullable=True)
+    to_status: Mapped[str | None] = mapped_column(String(30), nullable=True)
+    note: Mapped[str | None] = mapped_column(Text, nullable=True)
+    user_id: Mapped[int | None] = mapped_column(Integer, ForeignKey("users.id"), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    ticket = relationship("Ticket", back_populates="timeline")
+    user = relationship("User", back_populates="timeline_entries")
+
+    def __repr__(self) -> str:
+        return f"<TicketTimeline {self.ticket_id}: {self.from_status} → {self.to_status}>"
+
+
+class TicketPhoto(Base):
+    __tablename__ = "ticket_photos"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    ticket_id: Mapped[int] = mapped_column(Integer, ForeignKey("tickets.id"), nullable=False)
+    photo_url: Mapped[str] = mapped_column(String(500), nullable=False)
+    is_before: Mapped[bool] = mapped_column(nullable=False, default=True)
+
+    ticket = relationship("Ticket", back_populates="photos")
+
+    def __repr__(self) -> str:
+        return f"<TicketPhoto {self.id} ticket={self.ticket_id}>"
+
+
+class Escalation(Base):
+    __tablename__ = "escalations"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    ticket_id: Mapped[int] = mapped_column(Integer, ForeignKey("tickets.id"), nullable=False)
+    escalated_to: Mapped[int] = mapped_column(Integer, ForeignKey("users.id"), nullable=False)
+    reason: Mapped[str | None] = mapped_column(Text, nullable=True)
+    resolved_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+
+    ticket = relationship("Ticket", back_populates="escalations")
+    escalated_to_user = relationship("User", back_populates="escalations", foreign_keys=[escalated_to])
+
+    def __repr__(self) -> str:
+        return f"<Escalation ticket={self.ticket_id} → user={self.escalated_to}>"
@@ -0,0 +1,21 @@
+"""Unit model — an apartment at Pavilion East/West."""
+
+from __future__ import annotations
+
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.database import Base
+
+
+class Unit(Base):
+    __tablename__ = "units"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    property: Mapped[str] = mapped_column(String(10), nullable=False, comment="East or West")
+    apartment_code: Mapped[str] = mapped_column(String(20), unique=True, nullable=False, index=True)
+    building: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    floor: Mapped[int | None] = mapped_column(nullable=True)
+
+    def __repr__(self) -> str:
+        return f"<Unit {self.apartment_code}>"
@@ -0,0 +1,32 @@
+"""User model."""
+
+from __future__ import annotations
+
+from sqlalchemy import Boolean, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False, index=True)
+    password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
+    full_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    phone: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    role: Mapped[str] = mapped_column(
+        String(50),
+        nullable=False,
+        comment="CS Rep, CS Manager, FM Dispatcher, Admin/Jerome, Admin/Wahab, Tech, CEO, Director",
+    )
+    active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+
+    # relationships
+    assigned_tickets = relationship("Ticket", back_populates="assigned_technician", foreign_keys="Ticket.assigned_to")
+    timeline_entries = relationship("TicketTimeline", back_populates="user")
+    escalations = relationship("Escalation", back_populates="escalated_to_user", foreign_keys="Escalation.escalated_to")
+
+    def __repr__(self) -> str:
+        return f"<User {self.id}:{self.email} ({self.role})>"
@@ -0,0 +1,23 @@
+"""WhatsApp log model for mock endpoint."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Integer, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.database import Base
+
+
+class WhatsAppLog(Base):
+    __tablename__ = "whatsapp_log"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    command: Mapped[str] = mapped_column(Text, nullable=False)
+    from_number: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    ticket_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    received_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+
+    def __repr__(self) -> str:
+        return f"<WhatsAppLog {self.id}: {self.command[:50]}>"