前端开发日志（第 4 周）——迭代中期：流程对齐与下一 Sprint 规划

0. 本周定位（项目尚未收尾，处于构造与加固阶段）

前三周已完成：最小闭环（第 1 周）、核心交互与 SSE（第 2 周）、结构与可配置化等改进思路（第 3 周，含文档层面的 backlog）。第 4 周我把叙述从「准备答辩收尾」调整为更符合当前进度的说法：开发中期——主路径已通，但仍有一批工程化与体验项要在后续迭代落地。

本周日志侧重两件事：一是用软件工程生命周期的视角，对照现有前端代码说明「我们现在处在哪一环」；二是列出下一迭代优先级，方便和第 3 周文档、Issue/备忘录对齐。

和「收尾周写答辩脚本」不同，中期文档更强调双向对齐：前端认定的「已完成」要以可运行代码为准；后端若变更 SSE 字段或新增路由，前端的生命周期表里「需求/集成」两行也要跟着改。写日志时顺手记下接口版本或约定（哪怕只是一句话），后面排查联调问题会省很多时间。

---

1. 软件工程视角：前端在各阶段做什么

课设体量虽小，仍可套用常见生命周期（需求 → 设计 → 实现 → 集成 → 测试 → 运维/演进），便于写周报或课程报告时用语规范；若课程采用敏捷叙事，也可以把每一周看成一轮短迭代，每轮都覆盖表中若干列，而不是「前几周只做实现、最后一周只做测试」。

阶段	含义（简化）	本项目前端对应现状
需求理解	弄清用户场景与接口契约	以后端真实路由为准：/session、/start、/state、/advance、/action/wolf、/action/witch；人类可操作范围与后端一致
概要/详细设计	页面结构、状态归属、数据流	两路由：Lobby / Game；全局会话与局面在 Pinia session；next[0] 驱动是否展示行动面板
实现	编码与联调	大厅创建会话与启动；游戏页推进 + 流式拼消息；狼/女巫提交；App.vue 壳与主题变量
集成	前后端拼在一起验证	本地双进程联调；SSE 与 JSON 兜底分支已在 api.fetchStream 体现
测试（可轻量）	手工路径 + 关键边界	建议固定一条冒烟路径：建会话 → 进游戏 → 推进 → 必要时行动；刷新 /game 行为需单独记在「已知风险」
运维与演进	配置、可观测性、迭代 backlog	localhost:8000 仍分散硬编码；错误多停留在 console.error；Game.vue 内 refresh() 尚未接 UI/生命周期

可见：实现与集成已有实质进展，测试与演进型工作仍是中期重点，而不是「已经全部做完只等归档」。

1.1 为什么在中期也要谈「生命周期」

课程项目很容易不知不觉变成「瀑布式心智」：前几周狂写页面，最后一周才想起来补配置和报错。实际上业界更常见的是迭代增量：每一轮都在需求—设计—实现—验证的小循环里前进。第 4 周刻意把生命周期写成表格，不是为了贴教科书名词，而是提醒自己：中期就该为测试、配置、错误路径预留带宽，否则后期会被技术债挤占答辩准备时间。

若小组多人协作，这张表还可以当成范围评审的提纲：哪些列已经绿灯、哪些是黄灯（例如「测试」只覆盖 happy path）、哪些是红灯（例如缺少统一 apiBase），避免各人心里对「进度」的定义不一致。

1.2 简易里程碑（中期自检用）

不必做成正式 MS Project，用几句话即可和后面对齐：

• M1（已达）：大厅可建会话、可启动并进入游戏页，接口不通时有基本感知（健康检查）。
• M2（已达）：游戏页可推进、可看 SSE 流式消息，狼/女巫回合可提交并与后端一致。
• M3（进行中）：环境与错误路径工程化——统一后端地址、关键接口失败可读提示、刷新/直达 /game 可恢复局面。
• M4（后续）：结构重构（流式封装）、体验 polish（滚动、折叠、守卫）及文档与演示脚本定稿。

把里程碑写在日志里，本质是范围基线：中期开会时可以指着 M3 问「这周有没有往 M3 挪」，而不是只讨论「界面好不好看」。

1.3 质量属性（非功能需求）点到为止

软件工程里除了「有没有功能」，还会提可靠性、可维护性、可移植性等。本项目前端中期最值得点名的两条：

• 可移植性：端口与主机写死会直接伤害「换机器演示」；配置化属于低成本高收益。
• 可靠性（对用户而言）：请求失败若只在控制台出现，等于对用户不可用；至少要在 UI 层做一次翻译。

不要求在中期写完整 NFR 规格书，但在日志里占位，有助于和后几周工作对上号。

---

2. 当前实现快照（精简，与仓库一致）

• main.ts：Pinia → Router → Element Plus，入口稳定。
• App.vue：顶栏 +「返回大厅」；全局 CSS 变量与 Element 轻覆盖。
• stores/session.ts：threadId（含 localStorage）、state、next、loading；局面未持久化到本地。
• api.ts：axios JSON + fetchStream SSE；主机写死 http://localhost:8000。
• Lobby.vue：健康检查、创建会话、进入游戏；失败时缺少面向用户的提示。
• Game.vue：阶段/身份映射、继续推进、handleStreamData、狼/女巫面板、refresh() 已实现但未绑定模板或 onMounted。

后端 server.py 中与人类操作直接相关的仍是 /action/wolf 与 /action/witch；预言家等阶段由状态机与「继续推进」驱动即可，前端不必臆造未提供的接口——这在需求边界上是清楚的，也便于和后端同学对口径。

设计上的一个取舍（仍属中期讨论范畴）：前端刻意不把狼人杀规则状态机复制一份，而以 phase、next 为单一真相来源。优点是后端改图时前端改动面小；缺点是离线演示、单元测试mock都要围绕「给定 state/next」来构造，而不是在前端推导下一步。中期接受这一取舍，有助于和后端约定「哪些字段稳定、哪些可能扩展」（例如 night_actions 下的键名）。

---

3. 中期风险与 backlog（下一迭代输入）

把「文档里写过但代码未齐」的事项明确成 backlog，符合配置管理里的可追溯：规划和实现可以不同步，但要在清单上对得上号。

高优先级（建议下一 Sprint 先做）

1. 进入 /game 时 loadThread + getState，404/网络失败时给用户可读反馈。
2. 将 refresh 接到按钮或初次挂载，降低刷新后空白的风险。
3. apiBase 单源（环境变量 + 可选本地覆盖），axios、fetchStream、大厅 health 共用。

中优先级

4. 抽取 useStreamRunner（或等价封装），收敛 advanceStep / doWolfAction / doWitchAction 重复逻辑。
5. ElMessage 或统一错误处理：覆盖创建会话、启动、推进、行动。

低优先级（体验 polish）

6. 消息区智能滚动、AI 思考区折叠、路由守卫（无 threadId 禁止裸进 /game）等。

本周可执行的轻量验证（归属「测试」阶段）

• 固定一条冒烟用例：大厅在线 → 创建会话 → 进入游戏 → 至少两次「继续推进」→ 若出现行动面板则提交一次。
• 刻意做一次「刷新 /game」或「直接地址栏进 /game」，记录当前界面是否符合预期，并把差异写回 backlog（与 getState、refresh 接线对应）。
• 临时把后端停掉再点按钮，确认现有报错是否仅出现在控制台——这是后续做用户提示的依据。

这类记录不必正式写到测试用例编号粒度，但养成习惯后，和「软件工程要可追溯」的要求是一致的。

风险登记（极简版，可与 backlog 合并维护）

风险	触发条件	缓解思路（对应 backlog）
演示时空页面	刷新 /game 或直达路由	getState + refresh 接线
联调「全员改 URL」	换端口/换机器	apiBase 单源配置
失败不可见	网络异常、404、400	统一错误提示与用户文案

表格不必每周复制全文，只要在中期建立一次，后续周志在对应行更新「是否已缓解」即可。

---

4. 本周小结

第 4 周在项目时间线上更像是构造阶段后期的盘点周：用生命周期表格把「做完 / 在做 / 待做」摊开，避免团队（或个人）误以为功能 Demo 等于工程完结。后续几周将继续落在测试意识、配置与错误路径、代码结构上，而不是只堆界面。

从软件配置管理的角度看，中期适合做两件事：一是给 backlog 编号或打标签（哪怕只在 Markdown 里用 P0/P1），二是大改动前先记下当前行为（例如刷新游戏页的现行现象），这样下一轮实现 getState 后能明确说「修复了哪条风险」，而不是笼统写「优化了体验」。