frist

Doc/Game.md

@@ -0,0 +1,399 @@
+# 《冰冷的她醒来之前》数字版开发指导文档
+
+## 1. 项目概述
+
+### 技术选型
+- **客户端**：C++20 + Qt6 (Widgets 模式，非 QML)
+- **服务端**：Go 1.22+
+- **通信层**：WebSocket + JSON（游戏逻辑与信令）；WebRTC（实时语音媒体传输）
+- **语音架构**：客户端点对点（P2P）或选择性转发（SFU），服务端提供信令中继与房间管理
+- **架构模式**：客户端-服务器架构，服务端持有绝对权威
+
+### 核心设计原则
+1. **服务端绝对权威**：所有游戏状态、逻辑判定、胜负计算、随机过程（洗牌）均由服务端完成。客户端仅负责渲染与输入采集。
+2. **状态快照同步**：服务端以完整游戏状态快照的形式向客户端广播，客户端在收到快照后更新本地视图。禁止客户端本地预测游戏结果。
+3. **信息隔离**：反面朝上的卡牌、其他玩家的手牌内容、尚未结算的质疑牌等敏感信息，在未被服务端授权前不得向客户端传输。客户端无法通过内存读取或抓包获知隐藏信息。
+4. **数据可配置化**：卡牌的具体属性（名称、人力值、优先顺序、胜利条件、效果描述、张数配置）全部外置为配置文件，由用户自行填写，程序只读取配置运行。
+
+---
+
+## 2. 客户端架构说明
+
+### 2.1 渲染框架
+采用 Qt6 Widgets + QGraphicsScene 构建游戏主场景。场景按功能划分为若干逻辑层：
+
+- **背景层**：桌面、环境装饰
+- **公共区域层**：少女的尸体牌、调和区、信息提示牌
+- **玩家区域层**：每个玩家对应一个独立面板，包含其已使用特技区、质疑区、手牌数量指示器
+- **本地手牌层**：当前玩家自己的手牌，以可交互的卡牌视图呈现
+- **动画层**：卡牌移动、翻转、传递的过渡动画覆盖在所有层之上
+- **UI控件层**：行动菜单、弹窗、倒计时、日志面板
+
+### 2.2 卡牌视图对象
+每张卡牌对应一个独立的图形对象，具备以下状态：
+- **正面/反面**：正面显示卡牌的立绘与文字，反面显示统一的卡背图案
+- **选中/未选中**：高亮边框或抬升效果
+- **可用/禁用**：根据当前回合阶段，不可操作的卡牌降低透明度或置灰
+- **锁定**：暂时退出玩家的手牌进入锁定状态，不可被交互
+
+卡牌对象的正面图像资源通过卡牌类型标识符从外部加载，程序不硬编码任何卡牌美术资源路径。
+
+### 2.3 动画系统
+关键动画效果包括：
+- **放置动画**：卡牌从手牌区飞向目标区域（调和区、质疑区、已使用区）
+- **翻转动画**：结算阶段时，反面朝上的卡牌逐渐翻转为正面，使用缩放模拟3D翻转
+- **传递动画**：新闻部等效果导致手牌在玩家之间传递时，卡牌沿贝塞尔曲线路径飞行
+- **高亮动画**：需要玩家做出选择时，可选目标脉冲闪烁
+
+动画播放期间应阻塞玩家输入，防止在动画未完成时发送操作指令。
+
+### 2.4 实时语音模块
+客户端集成独立的语音通信子系统，与游戏逻辑模块解耦。
+
+**音频采集与播放**
+- 使用平台原生音频 API 或 Qt Multimedia 模块进行麦克风采集与扬声器播放
+- 支持 16kHz/48kHz 采样率，单声道，Opus 编码
+- 本地播放其他玩家的音频流，支持独立音量调节
+
+**网络传输**
+- 媒体流通过 WebRTC 传输，信令复用现有的 WebSocket 连接
+- 支持两种拓扑模式：
+  - **P2P 网状网络**：3-4 人房间时，各客户端直接互连，服务端仅转发信令
+  - **SFU 选择性转发**：5-6 人房间或 P2P 连接失败时，由服务端语音中继模块转发混音后的音频流
+
+**信令流程**
+- 玩家加入房间后，通过 WebSocket 发送语音就绪通知
+- 服务端广播房间内其他玩家的语音端点信息（WebRTC SDP offer/answer 与 ICE candidate 通过 WebSocket 隧道传输）
+- 连接建立后，音频通道与游戏通道并行运行
+
+**语音交互界面**
+- 每位玩家头像旁显示语音状态指示器：
+  - 静音（麦克风关闭）
+  - 发言中（语音活动检测触发，显示声波动画）
+  - 连接异常
+- 全局语音开关按钮：一键关闭/开启麦克风
+- 独立音量滑块：可单独调节每位玩家的接收音量
+- 可选的按键发言模式（按住空格键说话）
+
+**语音与游戏联动**
+- 玩家暂时退出或断开连接时，自动将其语音通道静音
+- 结算阶段动画播放期间，语音保持畅通，不强制静音
+
+---
+
+## 3. 服务端架构说明
+
+### 3.1 并发模型
+服务端采用 Go 的 Goroutine + Channel 模型。每个游戏房间由一个独立的逻辑 Goroutine 管理，该 Goroutine 内部维护一个事件循环，按顺序处理玩家输入、效果结算、状态广播。同一房间内的所有操作串行执行，避免并发竞争。网络 I/O 与游戏逻辑解耦，WebSocket 连接层将玩家消息投递到对应房间的 Channel 中。
+
+### 3.2 房间管理
+服务端维护一个房间列表，每个房间包含：
+- 房间唯一标识
+- 玩家列表（含连接状态、语音就绪状态）
+- 当前游戏状态机
+- 历史日志（用于断线重连后同步）
+
+房间支持的状态：等待中、设置中、进行中、结算中、已结束。
+
+### 3.3 游戏状态机
+游戏生命周期划分为以下主阶段，顺序不可逆：
+
+1. **等待阶段**：玩家加入、准备、房主发起开始
+2. **设置阶段**：根据人数计算调和目标值，从牌库中移除指定卡牌，构建本局牌库
+3. **发牌阶段**：洗牌并均分到手牌，确定起始玩家
+4. **进行阶段**：主循环，玩家依次行动
+5. **结算阶段**：全员暂时退出后，依次执行调和判定、质疑判定、胜利判定
+6. **结束阶段**：公布结果，房间回到等待状态或自动解散
+
+进行阶段内部可细分为子状态：
+- 等待选牌
+- 等待选择行动方式（特技/调和/质疑）
+- 等待选择目标（质疑对象或特技目标）
+- 效果结算中
+- 等待效果响应（如其他玩家选牌）
+- 回合结束检查
+
+### 3.4 效果系统架构
+效果系统采用策略模式或接口驱动模式。每张卡牌的能力对应一个独立的效果处理器。效果处理器注册到全局效果表中，通过卡牌类型标识符查找触发。
+
+效果处理器需声明以下能力：
+- **触发时机**：打出时触发、回合开始时触发、回合结束时触发、结算阶段触发
+- **是否需要响应**：是否需要向其他玩家发送选择请求并等待回复
+- **响应类型**：选牌、选人、确认、二选一
+- **是否可被取消**：在何种条件下效果失效（如目标不存在、玩家已退出）
+
+效果结算采用链式或队列式处理：若一张卡牌的效果引发了另一张卡牌的条件（如外星人回应优等生），则效果管理器按顺序入队，依次处理。
+
+### 3.5 实时语音中继模块
+服务端运行一个与游戏逻辑并行的语音信令与媒体中继层。
+
+**信令中继**
+- 复用现有 WebSocket 连接，不额外开放端口
+- 定义语音专属信令消息类型：SDP offer、SDP answer、ICE candidate、语音就绪、语音断开
+- 收到某玩家的信令后，向目标玩家转发，服务端不解析 SDP 内容
+
+**SFU 媒体中继（可选）**
+- 当房间人数大于 4 人或 P2P 打洞失败时，启用 SFU 模式
+- 服务端接收各客户端的音频流，进行混音或选择性转发
+- 使用 Go 的 WebRTC 库（如 pion/webrtc）实现
+- 混音策略：最多同时转发 3 路音频，避免带宽爆炸；优先转发最近发言者
+
+**语音房间管理**
+- 语音频道生命周期与游戏房间绑定：房间创建时初始化语音会话，房间销毁时关闭
+- 玩家加入房间后，可选择是否加入语音（默认不自动开启麦克风）
+- 玩家断线时，服务端通知其他客户端移除该玩家的音频轨道
+
+---
+
+## 4. 通信协议框架
+
+### 4.1 传输层
+基于 WebSocket 的全双工通信，消息载荷为 JSON。所有消息包含统一的元数据：消息类型、时间戳、序列号（用于丢包检测与断线重连）。
+
+### 4.2 客户端向服务端发送的消息类型
+- **加入/离开房间**
+- **准备/取消准备**
+- **开始游戏**（仅房主）
+- **选择手牌**（从手牌中指定一张）
+- **确认行动**（选择特技、调和或质疑，质疑需附带目标玩家标识）
+- **效果响应**（在效果处理器要求下，选择特定卡牌或玩家，或确认/取消）
+- **聊天消息**（可选）
+- **语音信令**（WebRTC SDP/ICE，透传至目标玩家）
+- **语音状态**（麦克风开启/关闭）
+
+### 4.3 服务端向客户端广播的消息类型
+- **房间状态同步**（玩家列表、准备状态、房主）
+- **游戏开始通知**（附带初始配置）
+- **完整状态快照**（游戏进行中的核心同步消息，包含所有公开信息与当前玩家自己的私有信息）
+- **卡牌移动事件**（某张卡牌从某区域移动到某区域，是否反面朝上）
+- **卡牌翻转事件**（结算时翻开调和区或质疑区）
+- **效果触发通知**（告知所有玩家某效果正在结算，以及需要响应的玩家）
+- **请求选择**（向特定玩家发送弹窗请求，要求其在限时内做出选择）
+- **玩家暂时退出通知**
+- **结算阶段通知**（进入调和判定、质疑判定、胜利判定）
+- **游戏结束通知**（获胜者列表、结局类型）
+- **错误通知**（非法操作、超时、网络异常）
+- **语音信令转发**（将某玩家的 SDP/ICE 转发给目标玩家）
+- **语音状态同步**（广播某玩家的麦克风开启/关闭状态）
+
+### 4.4 状态快照的信息隔离策略
+状态快照是服务端向客户端同步的核心机制，必须严格遵守信息隔离：
+
+- **自己的手牌**：完整传输卡牌标识符、类型、人力值、优先顺序
+- **他人的手牌**：仅传输数量，不传输任何卡牌内容
+- **调和区**：游戏进行中仅传输卡牌标识符与放置顺序，不传输类型和人力值；结算阶段由服务端单独发送翻转事件
+- **质疑区**：对质疑对象（被放置卡牌的玩家）是否可见由服务端决定；对非对象玩家，仅传输质疑区存在卡牌的数量或标识符，不传输内容
+- **已使用区（特技区）**：正面朝上，完整传输所有信息
+- **牌库**：不传输
+
+### 4.5 语音信令消息格式
+语音相关消息复用现有 WebSocket 通道，通过消息类型字段区分：
+
+- **SDP Offer**：发起方发送，包含目标玩家 ID 与 SDP 字符串
+- **SDP Answer**：响应方发送，包含目标玩家 ID 与 SDP 字符串
+- **ICE Candidate**：双方交换网络候选路径，包含目标玩家 ID、候选类型、地址信息
+- **Voice Ready**：客户端通知服务端本地语音引擎初始化完成
+- **Voice Toggle**：客户端通知服务端麦克风开启或关闭，服务端广播给房间内其他玩家
+
+---
+
+## 5. 游戏逻辑核心流程
+
+### 5.1 设置与发牌
+根据玩家人数，从完整牌库中按配置移除指定类型和数量的卡牌，形成本局牌库。洗牌后按人数均分为手牌。持有特定起始标记卡牌的玩家成为起始玩家；若该卡牌已被移除，则随机指定。
+
+### 5.2 回合流程
+当前玩家从手牌中选择一张卡牌，并选择以下三种行动之一：
+
+1. **特技**：将卡牌正面朝上放置于自己的已使用区，并触发该卡牌的效果。部分卡牌持有即生效，无需打出；打出后可能不产生额外效果。
+2. **调和**：将卡牌反面朝上放置于调和区（尸体旁）。放置时记录先后顺序。
+3. **质疑**：将卡牌反面朝上放置于另一名玩家的质疑区。不可质疑自己。
+
+回合结束时，若玩家手牌仅剩最后一张，则该玩家暂时退出游戏。退出后不再参与回合轮转，其手牌被锁定（不再受到移动手牌类效果的影响），但仍可成为质疑目标。
+
+### 5.3 效果失效与边界情况
+效果系统需处理以下边界情况：
+- 若效果的目标已不存在（如目标玩家已退出，或目标区域为空），则效果立即中止。
+- 某些卡牌的效果需要持有者存活到特定时机才能生效；若持有者在效果生效前已退出，则效果自然失效。
+- 暂时退出的玩家跳过需要其主动响应的效果（如新闻部传递手牌时跳过已退出者，将牌传给其左手边未退出的玩家）。
+
+### 5.4 结算阶段
+当所有玩家均暂时退出后，进入结算阶段，分为三个顺序执行的判定：
+
+**调和判定**：翻开调和区所有卡牌，统计人力值总和。若总和达到或超过目标值，则调和成功；否则调和失败。
+
+**质疑判定**：将每个玩家质疑区的卡牌全部改为正面朝上，分别计算各玩家质疑区的人力值合计。合计值最高的一名或多名玩家被视为犯罪嫌疑人而受到监禁。若所有玩家的合计值相同（包括全为零），则无人被监禁。人力值为负数的卡牌在质疑判定时视为零。
+
+**胜利判定**：按照优先顺序由低到高（从第一优先到第五优先）依次检查每名玩家的最后一张手牌。若某优先顺序下有玩家满足其胜利条件，则这些玩家立即获胜，后续优先顺序不再检查。若同一优先顺序下有多名玩家满足条件，则他们共同获胜或共同失败。即使被监禁的玩家也可以参加胜利判定。
+
+### 5.5 结局类型
+- **正常胜利**：一至多名玩家满足胜利条件
+- **全灭结局**：没有任何玩家满足胜利条件
+- **混沌模式变体**：可在设置阶段开启。该模式下，玩家最后一张手牌也可以通过能力效果转移，但玩家仍然处于暂时退出状态。
+
+---
+
+## 6. 界面交互设计规范
+
+### 6.1 主界面布局
+界面采用横向宽屏布局，中央为公共区域，四周为玩家面板。
+
+- **顶部**：房间信息、当前回合玩家指示、剩余时间倒计时、全局语音开关按钮
+- **中央上方**：其他玩家的面板，以头像或名称标识，显示其手牌数量、已使用区、质疑区；头像旁显示语音状态指示灯
+- **中央**：少女的尸体牌与调和区。调和区以横向排列的卡牌槽位展示，卡牌反面朝上时显示卡背，结算时依次翻开
+- **底部**：当前玩家自己的手牌区，以扇形或横向排列展示，支持点击选中
+- **底部操作栏**：选中卡牌后弹出行动按钮（特技、调和、质疑）。选择质疑后，其他玩家头像高亮，点击目标后确认
+- **右下角**：游戏日志面板，滚动显示操作记录
+- **左侧边栏（可选）**：房间内玩家列表与独立音量控制滑块
+
+### 6.2 交互状态机
+客户端界面需维护一个与服务器对应的本地交互状态：
+- **空闲**：等待自己或他人的回合，禁止操作
+- **选牌中**：自己的回合，可点击手牌，选中后弹出行动菜单
+- **选目标中**：已选择质疑或需要指定目标的特技，等待点击目标玩家
+- **等待响应**：自己的效果处理中，或等待其他玩家响应效果
+- **选择响应中**：服务端要求自己选择卡牌或玩家作为效果响应
+- **观看结算**：结算阶段，观看动画，禁止操作
+
+### 6.3 信息提示与辅助
+- 鼠标悬停在卡牌上时，显示该卡牌的详细说明（从配置读取）
+- 调和区显示当前放置顺序编号
+- 当效果需要玩家做出选择时，界面中央弹出模态对话框，附带倒计时条
+- 超时未操作则自动执行默认行为或视为放弃（由服务端定义超时惩罚）
+
+### 6.4 语音交互细节
+- 发言者头像边框高亮或显示绿色脉冲环，直观指示当前谁在说话
+- 玩家手动关闭麦克风时，头像旁显示静音图标
+- 语音连接质量不佳时，显示弱网警告图标
+- 提供全局静音按钮（仅关闭接收，不影响发送）用于专注思考
+
+---
+
+## 7. 关键机制实现要点
+
+### 7.1 信息隔离的技术实现
+信息隔离是防止作弊的核心。服务端在构建状态快照时，必须为每个玩家生成定制化的视图：
+- 遍历所有卡牌，根据卡牌位置、朝向、以及当前接收快照的玩家身份，决定该卡牌在此快照中暴露哪些字段
+- 卡牌内容字段（类型、人力值、优先顺序）仅在卡牌正面朝上且对该玩家可见时填充；否则留空或设为占位符
+- 客户端渲染器根据卡牌内容是否存在，决定显示正面图像还是卡背图像
+
+### 7.2 断线重连
+玩家断线后，服务端保留其游戏状态一段时间。重连时，服务端向该玩家发送当前完整状态快照，客户端重建界面。若断线期间有需要该玩家响应的效果，应延长等待时间或为其选择默认选项。语音连接随游戏连接一并重建。
+
+### 7.3 时序与并发
+- 所有玩家操作必须带服务端时间戳排序
+- 效果结算期间，房间应处于“结算中”状态，拒绝新的玩家操作（聊天与语音除外）
+- 动画播放时间由客户端本地控制，但逻辑上服务端在发送事件后立即进入下一状态，不等待客户端动画完成。客户端通过队列缓冲事件，保证动画按顺序播放
+
+### 7.4 配置热加载
+卡牌库、设置规则、胜利条件等应存储于外部配置文件（如 JSON）。服务端启动时加载，游戏房间创建时复制一份配置快照，防止运行中修改配置影响已开局的房间。用户自行填写卡牌内容、人力值、优先顺序、张数、胜利条件、效果文本等字段，程序仅校验数据类型和逻辑一致性（如优先顺序范围、人力值范围）。
+
+---
+
+## 8. 开发阶段建议
+
+### 第一阶段：网络与框架
+实现 WebSocket 连接、房间管理、玩家加入离开、准备开始。客户端完成主界面布局与卡牌对象的基本显示。
+
+### 第二阶段：核心循环
+实现发牌、回合轮转、三种基础行动（特技/调和/质疑）、暂时退出机制。确保状态快照能正确同步，信息隔离生效。
+
+### 第三阶段：效果系统
+搭建效果处理器框架。逐个实现卡牌效果，重点处理需要多玩家响应的复杂效果（如手牌传递、交换、查看）。确保效果失效边界情况被覆盖。
+
+### 第四阶段：语音集成
+集成 WebRTC 或音频库，实现信令交换、P2P/SFU 媒体传输、语音状态指示器。先在等待房间中测试语音稳定性，再集成到游戏流程中。
+
+### 第五阶段：结算与动画
+实现三阶段结算流程。客户端配合完成卡牌翻转动画、结算结果展示。处理共同胜利、全灭结局等分支。
+
+### 第六阶段： polish 与变体
+添加混沌模式、音效、断线重连、观战模式、游戏日志导出。
+
+---
+
+## 9. 卡牌信息配置表
+
+以下表格为游戏核心配置模板，请对照实体卡牌逐一填写。**程序启动时读取此表，运行时不再修改。**
+
+### 9.1 基础卡牌属性表
+
+| 序号 | 卡牌类型标识符（英文，程序内使用） | 中文名称 | 人力值 (MP) | 优先顺序 | 胜利条件简述           | 效果触发时机 | 效果描述（玩家可见文本）                                     | 单卡张数 | 备注 |
+| :--: | :--------------------------------- | :------- | :---------: | :------: | :--------------------- | :----------- | :----------------------------------------------------------- | :------: | :--- |
+|  1   | honor_student                      | 优等生   |      2      |    4     | 调和成功即可获胜       |              | 除你之外的所有玩家闭上眼睛，然后持犯人牌的玩家吐出舌头。等他们将舌头收回后所有玩家睁开眼睛。（一边发号施令一边进行游戏） |    3     |      |
+|  2   | health_committee_member            | 保健委员 |      1      |    4     | 调和成功即可获胜       |              | 你可以选择1张其他玩家已使用（正面朝上）的非保健委员的牌，将它加入自己的手牌中。 |    2     |      |
+|  3   | accomplice                         | 共犯     |      0      |    3     | 犯人获胜即可获胜       |              | 将1张放在任意玩家面前质疑位置的牌转移到1名其他玩家面前。     |    1     |      |
+|  4   | library_committee_member           | 图书委员 |      1      |    4     | 调和成功即可获胜       |              | 你可以查看放在调和位置的所有卡牌。（※查看时注意不要改变卡牌的摆放顺序） |    3     |      |
+|  5   | alien                              | 外星人   |     -1      |    1     | 被监禁即可获胜         |              | 当你持有这张牌时，若有人使用了优等生的特技，你可以伸出舌头，装作是犯人来回应他。当你正面打出这张牌时，不会产生任何效果。 |    1     |      |
+|  6   | young_lady                         | 大小姐   |      1      |    4     | 调和成功即可获胜       |              | 随机抽取1名其他玩家的1张手牌，然后选择1张自己的手牌保持反面朝上的状态返还给他。（你可以将抽到的那张返还给他） |    3     |      |
+|  7   | student_council_president          | 学生会长 |      3      |    4     | 调和成功即可获胜       |              | 持有者成为起始玩家（只需宣称持有即可）。正面打出时不会产生任何效果。 |    1     |      |
+|  8   | go_home_club                       | 归宅部   |      0      |    5     | 没有任何人获胜即可获胜 |              | 你可以将1张自己的手牌和1张放在调和位置上的牌交换。           |    3     |      |
+|  9   | infected_person                    | 感染者   |      0      |    2     | 调和失败即可获胜       |              | 在你的下一个回合开始时，若这张牌仍然正面朝上摆在你面前，则可以将调和位置的1张牌加入自己的手牌中。 |    1     |      |
+|  10  | newspaper_club                     | 新闻部   |      1      |    4     | 调和成功即可获胜       |              | 每位玩家选择1张自己的手牌，将它保持反面朝上的状态传给自己左手边的玩家。 |    3     |      |
+|  11  | culprit                            | 犯人     |      0      |    3     | 不被监禁即可获胜       |              | 这张牌无论是正面朝上还是反面朝上都无法被使用。（但可因其他卡牌的能力效果而进行移动） |    1     |      |
+|  12  | class_monitor                      | 班长     |      2      |    4     | 调和成功即可获胜       |              | 选择1名玩家，双方各选择1张自己的手牌，然后保持反面朝上的状态转交给对方。(也可以选择一个人和自己换牌) |    2     |      |
+|  13  | discipline_committee_member        | 风纪委员 |      1      |    4     | 调和成功即可获胜       |              | 你可以查看一名玩家的所有手牌。                               |    2     |      |
+|  14  |                                    |          |             |          |                        |              |                                                              |          |      |
+|  15  |                                    |          |             |          |                        |              |                                                              |          |      |
+
+> **字段说明**
+>
+> - **卡牌类型标识符**：程序代码中使用的枚举名或键名，建议英文驼峰命名，如 `StudentCouncilPresident`
+> - **优先顺序**：胜利判定时的检查顺序，数字越小越早检查（1 最先，5 最后）
+> - **效果触发时机**：可选值：`持有即生效` / `打出时触发` / `回合开始时触发` / `回合结束时触发` / `结算阶段触发`
+> - **单卡张数**：该卡牌在完整牌库中的总张数
+
+### 9.2 游戏设置规则表（按人数移除卡牌）
+
+| 玩家人数 | 调和目标值 | 需移除的卡牌类型                                             | 本局总牌数 | 每人手牌数 |
+| :------: | :--------: | :----------------------------------------------------------- | :--------: | :--------: |
+|    3     |     9      | 图书委员×1、共犯×1、优等生×1、风纪委员×1、大小姐×1、新闻部×1、归宅部×1 |     18     |     6      |
+|    4     |     8      | 图书委员×1                                                   |     24     |     6      |
+|    5     |     7      | 无（使用全部卡牌）                                           |     25     |     5      |
+|    6     |     6      | 图书委员×1                                                   |     24     |     4      |
+
+> **填写说明**
+>
+> - **调和目标值**：通常为 `12 - 玩家人数`，请确认实体规则
+> - **需移除的卡牌类型标识符**：填写从完整牌库中移除的卡牌，多张请用逗号分隔
+> - **每人手牌数**：总牌数 ÷ 人数，确认是否整除
+
+### 9.3 特殊规则对照表
+
+| 规则项                     | 实体规则描述                                                 | 程序实现要点                                                 |
+| :------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
+| **起始玩家确定方式**       | 持有"学生会长"的玩家成为起始玩家，只需宣称自己持有这张牌即可，并不需要第一张就打出 | 发牌完成后，服务端遍历所有玩家手牌，找到持有学生会长卡的玩家设为当前回合玩家。若该卡被移除（本局未加入牌库），则随机指定一名玩家为起始玩家。 |
+| **犯人卡使用限制**         | 这张牌无论是正面朝上还是反面朝上都无法被使用，但可因其他卡牌的能力效果而进行移动 | 行动验证阶段，若玩家选择犯人卡进行特技/调和/质疑，服务端直接拒绝并返回错误。犯人卡仅能通过班长交换、大小姐抽牌、新闻部传递、归宅部交换、共犯转移等被动方式移动。 |
+| **感染者效果失效条件**     | 若你在剩余手牌不到2张时使用这张牌，你无法活到下一个回合，效果自然失效 | 服务端允许玩家打出感染者，但在效果系统中标记：若打出后该玩家手牌数≤1（立即退出），则感染者效果标记为失效，下回合开始时不再触发选牌请求。 |
+| **暂时退出后手牌锁定范围** | 手牌将被锁定，不再受到移动手牌的能力效果影响，但可以被质疑   | 退出玩家的手牌添加"locked"标记。效果系统处理移动手牌类效果（班长、大小姐、新闻部）时跳过这些卡牌。质疑操作不受影响，仍可正常被放置质疑牌。 |
+| **质疑区MP合计为负时处理** | 质疑的合计值不会是负数。若合计值是-1，则将它当作0            | 结算阶段计算质疑区MP总和时，对每张卡牌取 `max(0, mp)`。外星人MP=-1，在质疑区贡献0点。 |
+| **归宅部与犯人联动规则**   | 归宅部可以将1张手牌和1张调和位置的牌交换。若犯人通过归宅部效果进入调和区，则可能出现"其实根本就没有犯人"的结局 | 允许交换。若犯人牌被换入调和区，调和判定阶段统计MP时犯人牌贡献0点（与实际MP一致）。归宅部持有者手牌中不再持有犯人。 |
+| **混沌模式与基础模式差异** | 混沌模式中，玩家的最后一张手牌也可以用能力进行转移，但玩家仍然处于暂时退出的状态 | 开启混沌模式后，效果系统处理移动手牌效果时，不跳过仅剩1张手牌的玩家（允许其手牌被交换、传递、抽走）。但该玩家仍标记为已退出，不再参与回合轮转。 |
+| **全灭结局触发条件**       | 没有任何人能获得胜利而结束游戏的情况                         | 胜利判定阶段按优先顺序1→5依次检查，若所有优先顺序下均无人满足胜利条件，则广播全灭结局。 |
+
+### 9.4 卡牌效果详细规格表（供程序逻辑参考）
+
+| 卡牌名称     | 是否需要选择目标   | 目标类型                                                     |     是否影响他人手牌     |      是否影响调和区      | 是否影响质疑区 | 效果失效条件                                                 | 响应超时处理                                                 |
+| :----------- | :----------------- | :----------------------------------------------------------- | :----------------------: | :----------------------: | :------------: | :----------------------------------------------------------- | :----------------------------------------------------------- |
+| **学生会长** | 否                 | 无                                                           |            否            |            否            |       否       | 无（持有即生效，打出不产生效果）                             | 无                                                           |
+| **班长**     | 是                 | 先选择1名玩家，再双方各选1张自己的手牌                       |            是            |            否            |       否       | 目标玩家已退出；目标玩家手牌为空                             | 超时自动随机选择1张手牌完成交换                              |
+| **优等生**   | 否（自动触发）     | 无（向所有其他玩家发送闭眼指令，向持犯人牌玩家发送提示，向外星人持有者发送是否回应提示） |            否            |            否            |       否       | 其他玩家全部已退出；场上无犯人牌                             | 犯人玩家超时未确认吐舌头视为不回应；外星人持有者超时未确认视为不装作犯人 |
+| **风纪委员** | 是                 | 选择1名玩家                                                  |   否（仅查看，不移动）   |            否            |       否       | 目标玩家已退出；目标玩家手牌为空                             | 无（纯信息展示，无需超时处理）                               |
+| **大小姐**   | 是                 | 系统随机选择1名其他玩家并随机抽其1张手牌，然后自己选择1张手牌返还 |            是            |            否            |       否       | 无其他玩家；被抽牌玩家手牌为空                               | 超时自动将抽到的牌原路返还，或随机选择1张自己的手牌返还      |
+| **新闻部**   | 否（但需全员响应） | 每位未退出玩家选择自己的1张手牌                              |            是            |            否            |       否       | 无                                                           | 每位玩家超时自动随机选择1张手牌传递；已退出玩家自动跳过      |
+| **归宅部**   | 是                 | 选择自己的1张手牌 + 选择调和区1张牌                          |            否            |            是            |       否       | 调和区无卡牌；自己手牌为空                                   | 超时自动取消效果                                             |
+| **图书委员** | 否                 | 无                                                           |            否            | 否（仅查看，不改变顺序） |       否       | 调和区无卡牌                                                 | 无（纯信息展示）                                             |
+| **保健委员** | 是                 | 选择其他玩家已使用区（SkillZone）中的1张非保健委员牌         | 是（从已使用区移入手牌） |            否            |       否       | 所有玩家已使用区为空；或仅有保健委员                         | 超时自动随机选择1张符合条件的牌，若无则取消效果              |
+| **外星人**   | 否（被动触发）     | 无                                                           |            否            |            否            |       否       | 无人使用优等生特技；正面打出时无效果                         | 收到优等生触发通知后，超时未响应视为不装作犯人               |
+| **感染者**   | 是（延迟触发）     | 下回合开始时选择调和区1张牌                                  |            否            |            是            |       否       | 打出后手牌≤2（立即退出，无法活到下回合）；下回合开始时此牌不在已使用区；调和区无卡牌 | 超时自动随机选择1张调和区卡牌加入手牌，或放弃效果            |
+| **犯人**     | N/A                | N/A                                                          |           N/A            |           N/A            |      N/A       | 无法主动使用                                                 | N/A                                                          |
+| **共犯**     | 是                 | 先选择任意质疑区1张牌，再选择1名其他玩家                     |            否            |            否            |       是       | 全房间质疑区无卡牌                                           | 超时自动随机选择1张质疑区卡牌和1名随机其他玩家完成转移       |
+
+> **字段说明**
+> - **目标类型**：该效果是否需要玩家选择目标，以及目标的类型
+> - **是否影响他人手牌**：效果是否会导致其他玩家的手牌数量或内容发生变化
+> - **响应超时处理**：若需要其他玩家响应（如新闻部选牌），超时后如何处理（自动随机选择 / 跳过该玩家 / 效果取消）
+
+---
+
+> **文档说明**：本文档为框架性指导，所有涉及具体卡牌属性（人力值、优先顺序、效果描述、卡牌张数、移除规则）的字段均留空，由开发者根据实体卡牌自行填入配置文件。文档不涉及具体代码实现与项目目录结构。