一、本阶段整体工作概述

本阶段小组主要围绕三大板块开展开发优化工作，分别是房间圆桌布局与玩家准备相关功能优化、选剧本弹窗全套开发、局内玩家聊天整套前后端开发，同时在开发过程中处理前期遗留代码冲突问题、修复各类页面交互 bug，中间还出现过 AI 批量改代码误损坏部分文件的小插曲，事后完成文件恢复并统一规范后续开发方式。整体遵循先定规则、后端落地能力、前端对接页面、联调测 bug 的开发节奏，逐步完善房间对局基础能力。

二、第一部分：圆桌布局 + 玩家准备相关功能整改与开发

1、圆桌座位规则落地

前期敲定座位排布标准：房间可用座位数量等于房间最大人数减一，圆桌按照椭圆形设计，所有座位只在 0 度到 180 度上半圈分布，坐标大于 90 度的座位放在圆桌左侧，小于 90 度放在圆桌右侧；玩家进入房间就会生成固定序号，序号决定玩家位置，不管玩家点准备还是取消准备，座位永远不会变动，房主固定在圆桌最下方位置。

2、现存三大 bug 逐个修复

1. 修复准备状态变更后头像乱跑问题：原先玩家点击准备 / 取消，页面就会重新计算坐标、改动座位位置，我们删掉准备状态和座位绑定的代码，严格按照序号锁定坐标；
2. 修复准备按钮只能点一次就锁定：调整按钮可用状态逻辑，非房主用户可以反复切换准备、未准备两种状态；
3. 接入 WebSocket 实现状态实时同步：玩家修改准备状态之后，后端收到指令推送消息，所有在线玩家页面自动刷新状态，不用手动刷新页面；

3、房主专属规则落地

房主默认永久处于已准备状态，不能点击准备 / 取消按钮，头像固定展示皇冠标识；之前出现皇冠图标、开局 GO 按钮一闪就消失的问题，排查发现是多处重复的状态判断代码互相冲突，我们把多余的测试、模拟代码全部注释，只保留一套和后端数据联动的渲染逻辑，同时删掉页面右上角多余的开始游戏按钮，全项目只保留圆桌位置的 GO 按钮，两个按钮共用同一套开局接口，避免多代码链路引发异常。

三、第二部分：选择剧本弹窗全功能开发

1、弹窗结构与接口复用

弹窗整体分成两块区域，左边展示当前本局已经选定的剧本，右边是全量剧本库列表；剧本查询没有新写后端接口，全部复用之前剧本工坊已经写好的查询、筛选接口，节省开发工作量。 权限区分规则：只有房主可以点开剧本详情、点击选用按钮把剧本设为房间本局剧本，普通玩家只能查看剧本简介，选用按钮直接灰化无法点击。选中剧本之后，弹窗左侧区域同步刷新剧本信息，同时圆桌中间的封面图片自动替换成新剧本封面。

2、封面弹窗交互完善

选中剧本后，点击圆桌中间封面按钮，会弹出详情弹窗，弹窗内展示剧本背景、简介、人物基础信息，内容文字过长时复用项目现成滚动组件，不用重复开发滚动样式。

3、弹窗 UI 统一落地

整体弹窗使用深色哑光棕褐色底色，标题文字采用暖黄色，普通介绍文字用浅灰白色；所有剧本卡片增加金边卷轴样式、复古暖黄滤镜，整体贴合剧本杀的风格设计，列表滚动条沿用项目已有封装组件。

4、关键 bug 修复

原先房主选中剧本、点击选用按钮页面直接闪退，经过前后端联调排查接口传参、页面赋值逻辑，修正回闪问题，保证选剧本操作可以正常保存、同步房间数据。

四、第三部分：局内玩家对话全栈开发工作

1、整体技术选型敲定

经过小组讨论，确定聊天功能不用直接查数据库，高频聊天、实时广播用 Redis，玩家聊天记录永久存在数据库里，NPC、AI 自动回复这类耗时任务使用 Kafka 做异步处理；实时消息推送依靠 WebSocket，明确分工：玩家实时聊天走同步链路，AI 生成回复走异步链路。

2、后端数据库搭建

后端新增四张数据表：聊天会话表、会话成员表、全量消息表、异步任务记录表，分别用来存房间聊天频道、用户已读记录、所有聊天内容、NPC 回复任务状态；同步新建两个操作数据表的仓库文件，封装新增、查询、修改数据的各类方法，规定历史消息不能用分页偏移查询，全部依靠消息序号游标拉取数据。

3、后端服务与中间件开发规划

1. 新建聊天业务服务文件，封装发公聊、发私聊、系统公告、标记已读、断线同步、下发 NPC 任务等方法，固定玩家发消息的完整执行步骤；
2. 设计 Redis 各类存储键，用来缓存最新聊天记录、用户未读消息数量、房间在线人员、房间消息序号，优先读缓存，缓存没有再去查数据库；
3. 规划 Kafka 主题、生产者和消费者代码，区分玩家消息、NPC 生成消息、内容审核三类任务，NPC 生成失败会记录数据库、支持重试。

4、当前后端开发进度

四张数据表和对应仓储代码全部写完，聊天基础服务、WebSocket 收发基础逻辑已经实现，系统公告、公聊私聊入库功能可用；Redis、Kafka 目前只预留配置入口，暂时先用内存缓存临时替代，还没有接入真实中间件，NPC 异步任务目前是本地模拟执行，待后续部署中间件后替换。

5、前端聊天改造进度

1. 重构聊天全局状态管理，从单一消息列表改成按会话分类存储，区分公聊、私聊、系统消息；
2. 修改 WebSocket 收发代码，适配新的收发指令；
3. 重新编写聊天面板、会话列表、消息输入框组件；
4. 房间页面已经嵌入聊天面板，但目前还有部分功能没联调完毕：私聊创建入口、历史上滑加载、断线补齐遗漏消息、未读数字统计暂未全量闭环。

6、功能范围约定

本版本聊天只做文字公聊、私聊、系统推送、NPC 自动文字回复，语音、图片、撤回、自建群组等功能放到后续迭代开发。

五、开发踩坑总结与后续开发规范

1、本期出现的问题

开发对局相关功能时，多次使用 AI 批量生成代码，同一个功能出现多套实现代码，新旧代码混在一起造成逻辑冲突，引发皇冠消失、按钮失效、座位错乱等问题，同时 AI 误改动部分原有项目文件，事后完成受损文件恢复。

2、后续统一规范

1. 同一个功能只保留一套正式业务代码，多余测试、临时模拟代码统一注释封存；
2. 使用 AI 辅助开发时，单次只提单个小需求，逐个修改 bug，不一次性大范围批量改代码；
3. 复杂大功能拆分成多个小阶段分步开发，每做完一部分就核对代码、测试效果，避免代码越改越乱。

六、后续工作计划

1. 优先收尾圆桌、选剧本剩余细小交互问题，全房间走一遍人工测试；
2. 完成聊天模块剩余前后端联调，打通私聊创建、历史分页、未读统计、断线同步；
3. 按需部署 Redis、Kafka 环境，替换现有内存模拟代码，正式接入中间件实现 NPC 异步回复；
4. 后续继续推进局内线索、投票相关功能开发。