chore(merge): merge pull request #8 from feat/multiplayer-api

feat: 增加mp房间相关接口
2025-08-10 00:00:47 +08:00
parent dbb7c7b5c6 1330f90b4c
commit bee0befc26
50 changed files with 5066 additions and 551 deletions
--- a/app/database/init.py
+++ b/app/database/init.py
@@ -16,10 +16,22 @@ from .lazer_user import (
    User,
    UserResp,
 )
+from .multiplayer_event import MultiplayerEvent, MultiplayerEventResp
+from .playlist_attempts import (
+    ItemAttemptsCount,
+    ItemAttemptsResp,
+    PlaylistAggregateScore,
+)
+from .playlist_best_score import PlaylistBestScore
+from .playlists import Playlist, PlaylistResp
 from .pp_best_score import PPBestScore
 from .relationship import Relationship, RelationshipResp, RelationshipType
+from .room import APIUploadedRoom, Room, RoomResp
+from .room_participated_user import RoomParticipatedUser
 from .score import (
+    MultiplayerScores,
    Score,
+    ScoreAround,
    ScoreBase,
    ScoreResp,
    ScoreStatistics,
@@ -37,6 +49,7 @@ from .user_account_history import (
 )

 __all__ = [
+    "APIUploadedRoom",
    "Beatmap",
    "BeatmapPlaycounts",
    "BeatmapPlaycountsResp",
@@ -46,12 +59,25 @@ __all__ = [
    "DailyChallengeStats",
    "DailyChallengeStatsResp",
    "FavouriteBeatmapset",
+    "ItemAttemptsCount",
+    "ItemAttemptsResp",
+    "MultiplayerEvent",
+    "MultiplayerEventResp",
+    "MultiplayerScores",
    "OAuthToken",
    "PPBestScore",
+    "Playlist",
+    "PlaylistAggregateScore",
+    "PlaylistBestScore",
+    "PlaylistResp",
    "Relationship",
    "RelationshipResp",
    "RelationshipType",
+    "Room",
+    "RoomParticipatedUser",
+    "RoomResp",
    "Score",
+    "ScoreAround",
    "ScoreBase",
    "ScoreResp",
    "ScoreStatistics",
--- a/app/database/beatmap.py
+++ b/app/database/beatmap.py
@@ -2,7 +2,6 @@ from datetime import datetime
 from typing import TYPE_CHECKING

 from app.models.beatmap import BeatmapRankStatus
-from app.models.model import UTCBaseModel
 from app.models.score import MODE_TO_INT, GameMode

 from .beatmap_playcounts import BeatmapPlaycounts
@@ -23,7 +22,7 @@ class BeatmapOwner(SQLModel):
    username: str


-class BeatmapBase(SQLModel, UTCBaseModel):
+class BeatmapBase(SQLModel):
    # Beatmap
    url: str
    mode: GameMode
@@ -63,7 +62,7 @@ class BeatmapBase(SQLModel, UTCBaseModel):

 class Beatmap(BeatmapBase, table=True):
    __tablename__ = "beatmaps"  # pyright: ignore[reportAssignmentType]
-    id: int | None = Field(default=None, primary_key=True, index=True)
+    id: int = Field(primary_key=True, index=True)
    beatmapset_id: int = Field(foreign_key="beatmapsets.id", index=True)
    beatmap_status: BeatmapRankStatus
    # optional
--- a/app/database/beatmapset.py
+++ b/app/database/beatmapset.py
@@ -2,7 +2,6 @@ from datetime import datetime
 from typing import TYPE_CHECKING, TypedDict, cast

 from app.models.beatmap import BeatmapRankStatus, Genre, Language
-from app.models.model import UTCBaseModel
 from app.models.score import GameMode

 from .lazer_user import BASE_INCLUDES, User, UserResp
@@ -14,6 +13,8 @@ from sqlmodel import Field, Relationship, SQLModel, col, func, select
 from sqlmodel.ext.asyncio.session import AsyncSession

 if TYPE_CHECKING:
+    from app.fetcher import Fetcher
+
    from .beatmap import Beatmap, BeatmapResp
    from .favourite_beatmapset import FavouriteBeatmapset

@@ -87,7 +88,7 @@ class BeatmapTranslationText(BaseModel):
    id: int | None = None


-class BeatmapsetBase(SQLModel, UTCBaseModel):
+class BeatmapsetBase(SQLModel):
    # Beatmapset
    artist: str = Field(index=True)
    artist_unicode: str = Field(index=True)
@@ -186,6 +187,16 @@ class Beatmapset(AsyncAttrs, BeatmapsetBase, table=True):
        await Beatmap.from_resp_batch(session, resp.beatmaps, from_=from_)
        return beatmapset

+    @classmethod
+    async def get_or_fetch(
+        cls, session: AsyncSession, fetcher: "Fetcher", sid: int
+    ) -> "Beatmapset":
+        beatmapset = await session.get(Beatmapset, sid)
+        if not beatmapset:
+            resp = await fetcher.get_beatmapset(sid)
+            beatmapset = await cls.from_resp(session, resp)
+        return beatmapset
+

 class BeatmapsetResp(BeatmapsetBase):
    id: int
--- a/app/database/best_score.py
+++ b/app/database/best_score.py
@@ -29,9 +29,7 @@ class BestScore(SQLModel, table=True):
    )
    beatmap_id: int = Field(foreign_key="beatmaps.id", index=True)
    gamemode: GameMode = Field(index=True)
-    total_score: int = Field(
-        default=0, sa_column=Column(BigInteger, ForeignKey("scores.total_score"))
-    )
+    total_score: int = Field(default=0, sa_column=Column(BigInteger))
    mods: list[str] = Field(
        default_factory=list,
        sa_column=Column(JSON),
--- a/app/database/multiplayer_event.py
+++ b/app/database/multiplayer_event.py
@@ -0,0 +1,56 @@
+from datetime import UTC, datetime
+from typing import Any
+
+from app.models.model import UTCBaseModel
+
+from sqlmodel import (
+    JSON,
+    BigInteger,
+    Column,
+    DateTime,
+    Field,
+    ForeignKey,
+    SQLModel,
+)
+
+
+class MultiplayerEventBase(SQLModel, UTCBaseModel):
+    playlist_item_id: int | None = None
+    user_id: int | None = Field(
+        default=None,
+        sa_column=Column(BigInteger, ForeignKey("lazer_users.id"), index=True),
+    )
+    created_at: datetime = Field(
+        sa_column=Column(
+            DateTime(timezone=True),
+        ),
+        default=datetime.now(UTC),
+    )
+    event_type: str = Field(index=True)
+
+
+class MultiplayerEvent(MultiplayerEventBase, table=True):
+    __tablename__ = "multiplayer_events"  # pyright: ignore[reportAssignmentType]
+    id: int | None = Field(
+        default=None,
+        sa_column=Column(BigInteger, primary_key=True, autoincrement=True, index=True),
+    )
+    room_id: int = Field(foreign_key="rooms.id", index=True)
+    updated_at: datetime = Field(
+        sa_column=Column(
+            DateTime(timezone=True),
+        ),
+        default=datetime.now(UTC),
+    )
+    event_detail: dict[str, Any] | None = Field(
+        sa_column=Column(JSON),
+        default_factory=dict,
+    )
+
+
+class MultiplayerEventResp(MultiplayerEventBase):
+    id: int
+
+    @classmethod
+    def from_db(cls, event: MultiplayerEvent) -> "MultiplayerEventResp":
+        return cls.model_validate(event)
--- a/app/database/playlist_attempts.py
+++ b/app/database/playlist_attempts.py
@@ -0,0 +1,151 @@
+from .lazer_user import User, UserResp
+from .playlist_best_score import PlaylistBestScore
+
+from pydantic import BaseModel
+from sqlmodel import (
+    BigInteger,
+    Column,
+    Field,
+    ForeignKey,
+    Relationship,
+    SQLModel,
+    col,
+    func,
+    select,
+)
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+
+class ItemAttemptsCountBase(SQLModel):
+    room_id: int = Field(foreign_key="rooms.id", index=True)
+    attempts: int = Field(default=0)
+    completed: int = Field(default=0)
+    user_id: int = Field(
+        sa_column=Column(BigInteger, ForeignKey("lazer_users.id"), index=True)
+    )
+    accuracy: float = 0.0
+    pp: float = 0
+    total_score: int = 0
+
+
+class ItemAttemptsCount(ItemAttemptsCountBase, table=True):
+    __tablename__ = "item_attempts_count"  # pyright: ignore[reportAssignmentType]
+    id: int | None = Field(default=None, primary_key=True)
+
+    user: User = Relationship()
+
+    async def get_position(self, session: AsyncSession) -> int:
+        rownum = (
+            func.row_number()
+            .over(
+                partition_by=col(ItemAttemptsCountBase.room_id),
+                order_by=col(ItemAttemptsCountBase.total_score).desc(),
+            )
+            .label("rn")
+        )
+        subq = select(ItemAttemptsCountBase, rownum).subquery()
+        stmt = select(subq.c.rn).where(subq.c.user_id == self.user_id)
+        result = await session.exec(stmt)
+        return result.one()
+
+    async def update(self, session: AsyncSession):
+        playlist_scores = (
+            await session.exec(
+                select(PlaylistBestScore).where(
+                    PlaylistBestScore.room_id == self.room_id,
+                    PlaylistBestScore.user_id == self.user_id,
+                )
+            )
+        ).all()
+        self.attempts = sum(score.attempts for score in playlist_scores)
+        self.total_score = sum(score.total_score for score in playlist_scores)
+        self.pp = sum(score.score.pp for score in playlist_scores)
+        self.completed = len(playlist_scores)
+        self.accuracy = (
+            sum(score.score.accuracy for score in playlist_scores) / self.completed
+            if self.completed > 0
+            else 0.0
+        )
+        await session.commit()
+        await session.refresh(self)
+
+    @classmethod
+    async def get_or_create(
+        cls,
+        room_id: int,
+        user_id: int,
+        session: AsyncSession,
+    ) -> "ItemAttemptsCount":
+        item_attempts = await session.exec(
+            select(cls).where(
+                cls.room_id == room_id,
+                cls.user_id == user_id,
+            )
+        )
+        item_attempts = item_attempts.first()
+        if item_attempts is None:
+            item_attempts = cls(room_id=room_id, user_id=user_id)
+            session.add(item_attempts)
+            await session.commit()
+            await session.refresh(item_attempts)
+        await item_attempts.update(session)
+        return item_attempts
+
+
+class ItemAttemptsResp(ItemAttemptsCountBase):
+    user: UserResp | None = None
+    position: int | None = None
+
+    @classmethod
+    async def from_db(
+        cls,
+        item_attempts: ItemAttemptsCount,
+        session: AsyncSession,
+        include: list[str] = [],
+    ) -> "ItemAttemptsResp":
+        resp = cls.model_validate(item_attempts.model_dump())
+        resp.user = await UserResp.from_db(
+            item_attempts.user,
+            session=session,
+            include=["statistics", "team", "daily_challenge_user_stats"],
+        )
+        if "position" in include:
+            resp.position = await item_attempts.get_position(session)
+        # resp.accuracy *= 100
+        return resp
+
+
+class ItemAttemptsCountForItem(BaseModel):
+    id: int
+    attempts: int
+    passed: bool
+
+
+class PlaylistAggregateScore(BaseModel):
+    playlist_item_attempts: list[ItemAttemptsCountForItem] = Field(default_factory=list)
+
+    @classmethod
+    async def from_db(
+        cls,
+        room_id: int,
+        user_id: int,
+        session: AsyncSession,
+    ) -> "PlaylistAggregateScore":
+        playlist_scores = (
+            await session.exec(
+                select(PlaylistBestScore).where(
+                    PlaylistBestScore.room_id == room_id,
+                    PlaylistBestScore.user_id == user_id,
+                )
+            )
+        ).all()
+        playlist_item_attempts = []
+        for score in playlist_scores:
+            playlist_item_attempts.append(
+                ItemAttemptsCountForItem(
+                    id=score.playlist_id,
+                    attempts=score.attempts,
+                    passed=score.score.passed,
+                )
+            )
+        return cls(playlist_item_attempts=playlist_item_attempts)
--- a/app/database/playlist_best_score.py
+++ b/app/database/playlist_best_score.py
@@ -0,0 +1,110 @@
+from typing import TYPE_CHECKING
+
+from .lazer_user import User
+
+from redis.asyncio import Redis
+from sqlmodel import (
+    BigInteger,
+    Column,
+    Field,
+    ForeignKey,
+    Relationship,
+    SQLModel,
+    col,
+    func,
+    select,
+)
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+if TYPE_CHECKING:
+    from .score import Score
+
+
+class PlaylistBestScore(SQLModel, table=True):
+    __tablename__ = "playlist_best_scores"  # pyright: ignore[reportAssignmentType]
+
+    user_id: int = Field(
+        sa_column=Column(BigInteger, ForeignKey("lazer_users.id"), index=True)
+    )
+    score_id: int = Field(
+        sa_column=Column(BigInteger, ForeignKey("scores.id"), primary_key=True)
+    )
+    room_id: int = Field(foreign_key="rooms.id", index=True)
+    playlist_id: int = Field(foreign_key="room_playlists.id", index=True)
+    total_score: int = Field(default=0, sa_column=Column(BigInteger))
+    attempts: int = Field(default=0)  # playlist
+
+    user: User = Relationship()
+    score: "Score" = Relationship(
+        sa_relationship_kwargs={
+            "foreign_keys": "[PlaylistBestScore.score_id]",
+            "lazy": "joined",
+        }
+    )
+
+
+async def process_playlist_best_score(
+    room_id: int,
+    playlist_id: int,
+    user_id: int,
+    score_id: int,
+    total_score: int,
+    session: AsyncSession,
+    redis: Redis,
+):
+    previous = (
+        await session.exec(
+            select(PlaylistBestScore).where(
+                PlaylistBestScore.room_id == room_id,
+                PlaylistBestScore.playlist_id == playlist_id,
+                PlaylistBestScore.user_id == user_id,
+            )
+        )
+    ).first()
+    if previous is None:
+        previous = PlaylistBestScore(
+            user_id=user_id,
+            score_id=score_id,
+            room_id=room_id,
+            playlist_id=playlist_id,
+            total_score=total_score,
+        )
+        session.add(previous)
+    elif not previous.score.passed or previous.total_score < total_score:
+        previous.score_id = score_id
+        previous.total_score = total_score
+    previous.attempts += 1
+    await session.commit()
+    if await redis.exists(f"multiplayer:{room_id}:gameplay:players"):
+        await redis.decr(f"multiplayer:{room_id}:gameplay:players")
+
+
+async def get_position(
+    room_id: int,
+    playlist_id: int,
+    score_id: int,
+    session: AsyncSession,
+) -> int:
+    rownum = (
+        func.row_number()
+        .over(
+            partition_by=(
+                col(PlaylistBestScore.playlist_id),
+                col(PlaylistBestScore.room_id),
+            ),
+            order_by=col(PlaylistBestScore.total_score).desc(),
+        )
+        .label("row_number")
+    )
+    subq = (
+        select(PlaylistBestScore, rownum)
+        .where(
+            PlaylistBestScore.playlist_id == playlist_id,
+            PlaylistBestScore.room_id == room_id,
+        )
+        .subquery()
+    )
+    stmt = select(subq.c.row_number).where(subq.c.score_id == score_id)
+    result = await session.exec(stmt)
+    s = result.one_or_none()
+    return s if s else 0
--- a/app/database/playlists.py
+++ b/app/database/playlists.py
@@ -0,0 +1,143 @@
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from app.models.model import UTCBaseModel
+from app.models.mods import APIMod
+from app.models.multiplayer_hub import PlaylistItem
+
+from .beatmap import Beatmap, BeatmapResp
+
+from sqlmodel import (
+    JSON,
+    BigInteger,
+    Column,
+    DateTime,
+    Field,
+    ForeignKey,
+    Relationship,
+    SQLModel,
+    func,
+    select,
+)
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+if TYPE_CHECKING:
+    from .room import Room
+
+
+class PlaylistBase(SQLModel, UTCBaseModel):
+    id: int = Field(index=True)
+    owner_id: int = Field(sa_column=Column(BigInteger, ForeignKey("lazer_users.id")))
+    ruleset_id: int = Field(ge=0, le=3)
+    expired: bool = Field(default=False)
+    playlist_order: int = Field(default=0)
+    played_at: datetime | None = Field(
+        sa_column=Column(DateTime(timezone=True)),
+        default=None,
+    )
+    allowed_mods: list[APIMod] = Field(
+        default_factory=list,
+        sa_column=Column(JSON),
+    )
+    required_mods: list[APIMod] = Field(
+        default_factory=list,
+        sa_column=Column(JSON),
+    )
+    beatmap_id: int = Field(
+        foreign_key="beatmaps.id",
+    )
+    freestyle: bool = Field(default=False)
+
+
+class Playlist(PlaylistBase, table=True):
+    __tablename__ = "room_playlists"  # pyright: ignore[reportAssignmentType]
+    db_id: int = Field(default=None, primary_key=True, index=True, exclude=True)
+    room_id: int = Field(foreign_key="rooms.id", exclude=True)
+
+    beatmap: Beatmap = Relationship(
+        sa_relationship_kwargs={
+            "lazy": "joined",
+        }
+    )
+    room: "Room" = Relationship()
+
+    @classmethod
+    async def get_next_id_for_room(cls, room_id: int, session: AsyncSession) -> int:
+        stmt = select(func.coalesce(func.max(cls.id), -1) + 1).where(
+            cls.room_id == room_id
+        )
+        result = await session.exec(stmt)
+        return result.one()
+
+    @classmethod
+    async def from_hub(
+        cls, playlist: PlaylistItem, room_id: int, session: AsyncSession
+    ) -> "Playlist":
+        next_id = await cls.get_next_id_for_room(room_id, session=session)
+        return cls(
+            id=next_id,
+            owner_id=playlist.owner_id,
+            ruleset_id=playlist.ruleset_id,
+            beatmap_id=playlist.beatmap_id,
+            required_mods=playlist.required_mods,
+            allowed_mods=playlist.allowed_mods,
+            expired=playlist.expired,
+            playlist_order=playlist.playlist_order,
+            played_at=playlist.played_at,
+            freestyle=playlist.freestyle,
+            room_id=room_id,
+        )
+
+    @classmethod
+    async def update(cls, playlist: PlaylistItem, room_id: int, session: AsyncSession):
+        db_playlist = await session.exec(
+            select(cls).where(cls.id == playlist.id, cls.room_id == room_id)
+        )
+        db_playlist = db_playlist.first()
+        if db_playlist is None:
+            raise ValueError("Playlist item not found")
+        db_playlist.owner_id = playlist.owner_id
+        db_playlist.ruleset_id = playlist.ruleset_id
+        db_playlist.beatmap_id = playlist.beatmap_id
+        db_playlist.required_mods = playlist.required_mods
+        db_playlist.allowed_mods = playlist.allowed_mods
+        db_playlist.expired = playlist.expired
+        db_playlist.playlist_order = playlist.playlist_order
+        db_playlist.played_at = playlist.played_at
+        db_playlist.freestyle = playlist.freestyle
+        await session.commit()
+
+    @classmethod
+    async def add_to_db(
+        cls, playlist: PlaylistItem, room_id: int, session: AsyncSession
+    ):
+        db_playlist = await cls.from_hub(playlist, room_id, session)
+        session.add(db_playlist)
+        await session.commit()
+        await session.refresh(db_playlist)
+        playlist.id = db_playlist.id
+
+    @classmethod
+    async def delete_item(cls, item_id: int, room_id: int, session: AsyncSession):
+        db_playlist = await session.exec(
+            select(cls).where(cls.id == item_id, cls.room_id == room_id)
+        )
+        db_playlist = db_playlist.first()
+        if db_playlist is None:
+            raise ValueError("Playlist item not found")
+        await session.delete(db_playlist)
+        await session.commit()
+
+
+class PlaylistResp(PlaylistBase):
+    beatmap: BeatmapResp | None = None
+
+    @classmethod
+    async def from_db(
+        cls, playlist: Playlist, include: list[str] = []
+    ) -> "PlaylistResp":
+        data = playlist.model_dump()
+        if "beatmap" in include:
+            data["beatmap"] = await BeatmapResp.from_db(playlist.beatmap)
+        resp = cls.model_validate(data)
+        return resp
--- a/app/database/room.py
+++ b/app/database/room.py
@@ -1,6 +1,177 @@
-from sqlmodel import Field, SQLModel
+from datetime import UTC, datetime
+
+from app.database.playlist_attempts import PlaylistAggregateScore
+from app.database.room_participated_user import RoomParticipatedUser
+from app.models.model import UTCBaseModel
+from app.models.multiplayer_hub import ServerMultiplayerRoom
+from app.models.room import (
+    MatchType,
+    QueueMode,
+    RoomCategory,
+    RoomDifficultyRange,
+    RoomPlaylistItemStats,
+    RoomStatus,
+)
+
+from .lazer_user import User, UserResp
+from .playlists import Playlist, PlaylistResp
+
+from sqlalchemy.ext.asyncio import AsyncAttrs
+from sqlmodel import (
+    BigInteger,
+    Column,
+    DateTime,
+    Field,
+    ForeignKey,
+    Relationship,
+    SQLModel,
+    col,
+    select,
+)
+from sqlmodel.ext.asyncio.session import AsyncSession


-class RoomIndex(SQLModel, table=True):
-    __tablename__ = "mp_room_index"  # pyright: ignore[reportAssignmentType]
-    id: int | None = Field(default=None, primary_key=True, index=True)  # pyright: ignore[reportCallIssue]
+class RoomBase(SQLModel, UTCBaseModel):
+    name: str = Field(index=True)
+    category: RoomCategory = Field(default=RoomCategory.NORMAL, index=True)
+    duration: int | None = Field(default=None)  # minutes
+    starts_at: datetime | None = Field(
+        sa_column=Column(
+            DateTime(timezone=True),
+        ),
+        default=datetime.now(UTC),
+    )
+    ends_at: datetime | None = Field(
+        sa_column=Column(
+            DateTime(timezone=True),
+        ),
+        default=None,
+    )
+    participant_count: int = Field(default=0)
+    max_attempts: int | None = Field(default=None)  # playlists
+    type: MatchType
+    queue_mode: QueueMode
+    auto_skip: bool
+    auto_start_duration: int
+    status: RoomStatus
+    # TODO: channel_id
+
+
+class Room(AsyncAttrs, RoomBase, table=True):
+    __tablename__ = "rooms"  # pyright: ignore[reportAssignmentType]
+    id: int = Field(default=None, primary_key=True, index=True)
+    host_id: int = Field(
+        sa_column=Column(BigInteger, ForeignKey("lazer_users.id"), index=True)
+    )
+
+    host: User = Relationship()
+    playlist: list[Playlist] = Relationship(
+        sa_relationship_kwargs={
+            "lazy": "selectin",
+            "cascade": "all, delete-orphan",
+            "overlaps": "room",
+        }
+    )
+
+
+class RoomResp(RoomBase):
+    id: int
+    has_password: bool = False
+    host: UserResp | None = None
+    playlist: list[PlaylistResp] = []
+    playlist_item_stats: RoomPlaylistItemStats | None = None
+    difficulty_range: RoomDifficultyRange | None = None
+    current_playlist_item: PlaylistResp | None = None
+    current_user_score: PlaylistAggregateScore | None = None
+    recent_participants: list[UserResp] = Field(default_factory=list)
+
+    @classmethod
+    async def from_db(
+        cls,
+        room: Room,
+        session: AsyncSession,
+        include: list[str] = [],
+        user: User | None = None,
+    ) -> "RoomResp":
+        resp = cls.model_validate(room.model_dump())
+
+        stats = RoomPlaylistItemStats(count_active=0, count_total=0)
+        difficulty_range = RoomDifficultyRange(
+            min=0,
+            max=0,
+        )
+        rulesets = set()
+        for playlist in room.playlist:
+            stats.count_total += 1
+            if not playlist.expired:
+                stats.count_active += 1
+            rulesets.add(playlist.ruleset_id)
+            difficulty_range.min = min(
+                difficulty_range.min, playlist.beatmap.difficulty_rating
+            )
+            difficulty_range.max = max(
+                difficulty_range.max, playlist.beatmap.difficulty_rating
+            )
+            resp.playlist.append(await PlaylistResp.from_db(playlist, ["beatmap"]))
+        stats.ruleset_ids = list(rulesets)
+        resp.playlist_item_stats = stats
+        resp.difficulty_range = difficulty_range
+        resp.current_playlist_item = resp.playlist[-1] if resp.playlist else None
+        resp.recent_participants = []
+        for recent_participant in await session.exec(
+            select(RoomParticipatedUser)
+            .where(
+                RoomParticipatedUser.room_id == room.id,
+                col(RoomParticipatedUser.left_at).is_(None),
+            )
+            .limit(8)
+            .order_by(col(RoomParticipatedUser.joined_at).desc())
+        ):
+            resp.recent_participants.append(
+                await UserResp.from_db(
+                    await recent_participant.awaitable_attrs.user,
+                    session,
+                    include=["statistics"],
+                )
+            )
+        resp.host = await UserResp.from_db(
+            await room.awaitable_attrs.host, session, include=["statistics"]
+        )
+        if "current_user_score" in include and user:
+            resp.current_user_score = await PlaylistAggregateScore.from_db(
+                room.id, user.id, session
+            )
+        return resp
+
+    @classmethod
+    async def from_hub(cls, server_room: ServerMultiplayerRoom) -> "RoomResp":
+        room = server_room.room
+        resp = cls(
+            id=room.room_id,
+            name=room.settings.name,
+            type=room.settings.match_type,
+            queue_mode=room.settings.queue_mode,
+            auto_skip=room.settings.auto_skip,
+            auto_start_duration=int(room.settings.auto_start_duration.total_seconds()),
+            status=server_room.status,
+            category=server_room.category,
+            # duration = room.settings.duration,
+            starts_at=server_room.start_at,
+            participant_count=len(room.users),
+        )
+        return resp
+
+
+class APIUploadedRoom(RoomBase):
+    def to_room(self) -> Room:
+        """
+        将 APIUploadedRoom 转换为 Room 对象，playlist 字段需单独处理。
+        """
+        room_dict = self.model_dump()
+        room_dict.pop("playlist", None)
+        # host_id 已在字段中
+        return Room(**room_dict)
+
+    id: int | None
+    host_id: int | None = None
+    playlist: list[Playlist] = Field(default_factory=list)
--- a/app/database/room_participated_user.py
+++ b/app/database/room_participated_user.py
@@ -0,0 +1,39 @@
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from sqlalchemy.ext.asyncio import AsyncAttrs
+from sqlmodel import (
+    BigInteger,
+    Column,
+    DateTime,
+    Field,
+    ForeignKey,
+    Relationship,
+    SQLModel,
+)
+
+if TYPE_CHECKING:
+    from .lazer_user import User
+    from .room import Room
+
+
+class RoomParticipatedUser(AsyncAttrs, SQLModel, table=True):
+    __tablename__ = "room_participated_users"  # pyright: ignore[reportAssignmentType]
+
+    id: int | None = Field(
+        default=None, sa_column=Column(BigInteger, primary_key=True, autoincrement=True)
+    )
+    room_id: int = Field(sa_column=Column(ForeignKey("rooms.id"), nullable=False))
+    user_id: int = Field(
+        sa_column=Column(BigInteger, ForeignKey("lazer_users.id"), nullable=False)
+    )
+    joined_at: datetime = Field(
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+        default=datetime.now(UTC),
+    )
+    left_at: datetime | None = Field(
+        sa_column=Column(DateTime(timezone=True), nullable=True), default=None
+    )
+
+    room: "Room" = Relationship()
+    user: "User" = Relationship()
--- a/app/database/score.py
+++ b/app/database/score.py
@@ -3,7 +3,7 @@ from collections.abc import Sequence
 from datetime import UTC, date, datetime
 import json
 import math
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any

 from app.calculator import (
    calculate_pp,
@@ -14,7 +14,7 @@ from app.calculator import (
    clamp,
 )
 from app.database.team import TeamMember
-from app.models.model import UTCBaseModel
+from app.models.model import RespWithCursor, UTCBaseModel
 from app.models.mods import APIMod, mods_can_get_pp
 from app.models.score import (
    INT_TO_MODE,
@@ -89,10 +89,11 @@ class ScoreBase(AsyncAttrs, SQLModel, UTCBaseModel):
        default=0, sa_column=Column(BigInteger), exclude=True
    )
    type: str
+    beatmap_id: int = Field(index=True, foreign_key="beatmaps.id")

    # optional
    # TODO: current_user_attributes
-    position: int | None = Field(default=None)  # multiplayer
+    # position: int | None = Field(default=None)  # multiplayer


 class Score(ScoreBase, table=True):
@@ -100,7 +101,6 @@ class Score(ScoreBase, table=True):
    id: int | None = Field(
        default=None, sa_column=Column(BigInteger, autoincrement=True, primary_key=True)
    )
-    beatmap_id: int = Field(index=True, foreign_key="beatmaps.id")
    user_id: int = Field(
        default=None,
        sa_column=Column(
@@ -163,6 +163,8 @@ class ScoreResp(ScoreBase):
    maximum_statistics: ScoreStatistics | None = None
    rank_global: int | None = None
    rank_country: int | None = None
+    position: int | None = None
+    scores_around: "ScoreAround | None" = None

    @classmethod
    async def from_db(cls, session: AsyncSession, score: Score) -> "ScoreResp":
@@ -234,6 +236,16 @@ class ScoreResp(ScoreBase):
        return s


+class MultiplayerScores(RespWithCursor):
+    scores: list[ScoreResp] = Field(default_factory=list)
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+class ScoreAround(SQLModel):
+    higher: MultiplayerScores | None = None
+    lower: MultiplayerScores | None = None
+
+
 async def get_best_id(session: AsyncSession, score_id: int) -> None:
    rownum = (
        func.row_number()
@@ -329,6 +341,10 @@ async def get_leaderboard(
        self_query = (
            select(BestScore)
            .where(BestScore.user_id == user.id)
+            .where(
+                col(BestScore.beatmap_id) == beatmap,
+                col(BestScore.gamemode) == mode,
+            )
            .order_by(col(BestScore.total_score).desc())
            .limit(1)
        )
@@ -616,6 +632,8 @@ async def process_score(
    fetcher: "Fetcher",
    session: AsyncSession,
    redis: Redis,
+    item_id: int | None = None,
+    room_id: int | None = None,
 ) -> Score:
    assert user.id
    can_get_pp = info.passed and ranked and mods_can_get_pp(info.ruleset_id, info.mods)
@@ -647,6 +665,8 @@ async def process_score(
        nsmall_tick_hit=info.statistics.get(HitResult.SMALL_TICK_HIT, 0),
        nlarge_tick_hit=info.statistics.get(HitResult.LARGE_TICK_HIT, 0),
        nslider_tail_hit=info.statistics.get(HitResult.SLIDER_TAIL_HIT, 0),
+        playlist_item_id=item_id,
+        room_id=room_id,
    )
    if can_get_pp:
        beatmap_raw = await fetcher.get_or_fetch_beatmap_raw(redis, beatmap_id)
@@ -678,4 +698,5 @@ async def process_score(
            await session.refresh(score)
    await session.refresh(score_token)
    await session.refresh(user)
+    await redis.publish("score:processed", score.id)
    return score