cosmo/backend/app/models/db/terminal_device.py

71 lines
2.4 KiB
Python

"""
TerminalDevice ORM model - ESP32 terminals paired with a user account
"""
from sqlalchemy import Column, String, Integer, TIMESTAMP, ForeignKey, Index, CheckConstraint
from sqlalchemy.sql import func
from sqlalchemy.orm import relationship
from app.database import Base
class TerminalDevice(Base):
"""
A physical terminal (ESP32-S3) that can be bound to exactly one user.
Pairing state machine:
pending - a 6 digit code was issued and can be redeemed by one user
bound - a user owns it, the code is expired and can no longer bind
"""
__tablename__ = "terminal_devices"
id = Column(String(50), primary_key=True, comment="Device id reported by the terminal")
name = Column(String(100), nullable=True, comment="Device name shown to the user")
user_id = Column(
Integer,
ForeignKey("users.id", ondelete="CASCADE"),
nullable=True,
comment="Owner, NULL when unbound",
)
status = Column(
String(20),
nullable=False,
default="pending",
comment="pending | bound",
)
pairing_code = Column(
String(6),
nullable=True,
unique=True,
comment="Last 6 digit pairing code (kept for audit after binding)",
)
code_expires_at = Column(TIMESTAMP, nullable=True, comment="Pairing code expiry (UTC)")
token_delivered_at = Column(
TIMESTAMP,
nullable=True,
comment="When the long lived terminal token was handed to the device",
)
bound_at = Column(TIMESTAMP, nullable=True)
last_seen_at = Column(TIMESTAMP, nullable=True, comment="Last poll from the device (UTC)")
firmware_version = Column(
String(32),
nullable=True,
comment="Version string last reported by the terminal itself",
)
board = Column(
String(40),
nullable=True,
comment="BOARD_NAME compiled into the running firmware",
)
created_at = Column(TIMESTAMP, server_default=func.now())
updated_at = Column(TIMESTAMP, server_default=func.now(), onupdate=func.now())
user = relationship("User")
__table_args__ = (
CheckConstraint("status IN ('pending', 'bound')", name="chk_terminal_device_status"),
Index("idx_terminal_devices_user", "user_id"),
)
def __repr__(self):
return f"<TerminalDevice(id='{self.id}', status='{self.status}', user_id={self.user_id})>"