木鸡SteadyGame——代码规范、冲刺任务与计划

一、项目与冲刺目标

木鸡 SteadyGame 是一个基于普通摄像头和浏览器端姿态识别的 Web 体感运动平台。首版包含三个玩法：平衡体感小球、手腕轨迹切水果、八段锦两式跟练。用户不需要专用体感设备，打开浏览器、授权摄像头、完成站位校准后，就能用身体动作控制游戏或跟练。

本次 Alpha 冲刺不继续扩写设计文档，目标是把设计变成可运行、可演示、可验收的版本。冲刺结束时应具备以下主链路：

打开大厅
  → 阅读摄像头用途与隐私说明
  → 授权摄像头并校准
  → 创建并开始训练轮次
  → 小球/切水果/八段锦两式
  → 暂停、恢复、退出与异常恢复
  → 唯一结算
  → 登录后明确同意保存
  → 个人历史、统计与导出

本文写于本次 Alpha 冲刺启动前，内容是团队已经商定的执行计划。团队计划按 Day1 至 Day7 推进：Day1 计划完成代码规范、上次答辩问题回应、八人分工、正式工程起步、契约冻结、数据库迁移、共享类型与端口、Issue 与分支准备；Day2 计划进入摄像头/姿态、三玩法固定输入、账号/CSRF/轮次基础；Day3 至 Day7 按后文计划继续推进。实际完成情况和证据将在对应日期结束后更新，不在计划阶段提前填写。

Day1 计划安排

Day1 计划以代码规范、答辩改进方案和八人分工为启动内容，同时建立可启动的正式工程、可执行的数据库迁移、共享类型/端口和 Issue/分支规范。燃尽图以 SGA-01 至 SGA-12 任务草案作为初始计划，暂估 87 SP；理想线只表示平均下降参考，D1 及之后的实际剩余点要等每日验收后按看板更新。本文不预填会议时间、参会人数或尚未产生的完成数据。

图片说明：本图是冲刺启动前的计划示意。图中只展示 87 SP 暂估、理想线和计划分工，实际会议时长、参会人数及剩余点均在冲刺开始后另行补充。

图片说明：可使用系统设计中的组件图或模块层次图，标出浏览器端摄像头、姿态识别、动作映射、游戏协调、业务后端、数据库和导出文件的位置。重点看模块边界，不需要堆满接口细节。

二、代码规范

2.1 规范来源与阅读说明

本文写作前已实际阅读《阿里巴巴 Java 开发手册》v1.3.0 PDF 终极版（阿里巴巴集团技术团队，2017-09-25，共 39 页）。该版本按编程规约、异常日志、单元测试、安全规约、MySQL 数据库、工程结构六个维度组织，条目分为【强制】【推荐】【参考】三类。

华为内部代码规范属于内部资料，公开渠道无法获得原文。团队实际参照的是华为云 CodeArts Check 的公开检查规则集；本文只描述可核对的规则方向，不冒充引用内部原文。如果课程下发了内部版本，团队再按文件条目补充。

团队的原则是：手册中的【强制】条目全部执行；【推荐】条目结合课程项目实际采用；与课程项目规模不适用的条款，在评审记录中说明取舍，不静默忽略。

2.2 命名、常量与格式

• 命名不能以下划线或美元符号开头、结尾；不使用拼音与英文混合，也不直接用中文命名。类名用 UpperCamelCase，方法、参数、成员变量和局部变量用 lowerCamelCase，常量用 UPPER_SNAKE_CASE。
• 不允许魔法值直接出现在代码中。时长、置信度、死区、目标数量、重试次数等参数必须定义为常量或集中配置，并标明单位。
• 大括号遵循手册约定：左大括号前不换行、左大括号后换行、右大括号前换行；if/for/while/do 即使只有一行也必须使用大括号。
• switch 的每个 case 必须通过 break/return 终止，必须包含 default；if/for/while/switch 等保留字与括号之间加空格。
• 类、类属性和类方法使用 Javadoc；注释解释约束、边界和原因，不重复代码字面意思。涉及隐私、幂等、归属和事务的代码必须写清前提与后果。
• 前端保持仓库现有格式：2 个空格缩进、单引号、无分号；组件、类和类型用 PascalCase，变量和函数用 camelCase，常量全大写加下划线。Java 后端以 Alibaba v1.3.0 与 CodeArts Check 规则为准。

2.3 分层与对象职责

Alibaba 手册的工程结构章节将应用分为开放接口层、Web 层、Service 层、Manager 层和 DAO 层。本项目按课程项目的规模做对应裁剪：

Controller 不承载计分和事务，Service 不直接拼 SQL，Repository 不接收未经校验的客户端身份字段。分层的目的，是让修改一个玩法或一个查询时，不会牵动整条链路。

2.4 集合、并发与异常日志

• 线程池不使用 Executors 创建，而使用 ThreadPoolExecutor 明确核心线程数、最大线程数、队列和拒绝策略；线程要有可识别的名称，便于排查。
• 遍历 Map 使用 entrySet；不在 foreach 中修改集合；需要去重和唯一性时优先使用 Set 或数据库唯一约束。
• 捕获具体异常，不吞异常；事务代码 catch 后如需回滚，必须手动标记回滚或重新抛出，不能留下半完成状态。
• 日志使用 SLF4J 门面，不使用 System.out；日志写请求号、资源 ID、模式和耗时，不写密码、Cookie、CSRF 令牌、原始视频或逐帧关键点。

2.5 单元测试

Alibaba 手册要求单元测试遵守 AIR 原则：Automatic（自动化）、Independent（独立）、Repeatable（可重复）。团队同时按 BCDE 原则设计用例：Border（边界）、Correct（正确）、Design（与设计一致）、Error（错误与异常）。

• 测试代码放在 src/test/java，不写在业务代码目录。
• 测试使用断言，不使用 System.out 做人肉验证；测试之间不共享可变状态，不依赖执行顺序。
• 核心业务、核心模块的增量代码必须通过单元测试；数据库测试使用自动回滚或明确的数据前缀，避免脏数据。
• 前端使用 Vitest 覆盖纯函数、状态机、碰撞和关键页面分支；后端使用 JUnit 5 覆盖校验、认证、保存和导出；接口联调用 Apifox 记录实际请求与响应。

图片说明：计划阶段可放代码规范文档、拟配置的检查项清单或工程目录规划；冲刺执行后再补实际配置、测试脚本和评审记录截图，不能提前写成“检查和评审已通过”。

2.6 安全与数据库规范

• 用户输入的 SQL 参数必须使用参数绑定或受控字段值，禁止拼接，防止 SQL 注入。
• 表单和 AJAX 写请求必须执行 CSRF 过滤；Cookie 设置 HttpOnly、SameSite，生产 HTTPS 下加 Secure。
• 密码使用专用加盐哈希，不存明文、不回显、不写日志；越权访问统一返回不泄露资源存在性的错误。
• 数据库表名、字段名使用小写字母或数字，表名用单数；主键、唯一索引、普通索引按 pk_、uk_、idx_ 命名。
• 业务上具有唯一特性的字段必须建唯一索引；高频查询按实际 SQL 设计组合索引，不凭感觉堆索引。
• 数据库结构通过版本化迁移管理，不在生产库手工改表；SQL 变更同步更新实体、接口、测试和回滚说明。

Alibaba 手册对互联网高并发场景建议不使用外键与级联，把外键关系放到应用层解决。课程项目需要同时展示数据完整性和归属校验，团队会在数据库约束与应用层校验之间做明确取舍，并在设计评审中记录原因，避免“数据库有约束、应用层却绕过”的两套规则。

2.7 前端与接口规范

• Vue 3 + TypeScript，页面使用 Composition API；组件只负责展示和交互，不把计分、碰撞、阶段判断塞进页面。
• 共享类型以 OpenAPI 生成的 src/shared/api/schema.ts 为准，不在各页面复制接口字段；接口变更先改契约，再生成类型。
• 所有请求通过统一 ApiTransport 和成员 API 文件，不在组件里手拼 URL、不重复解析统一响应信封。
• 摄像头画面、关键点和腕轨迹只在浏览器内存中处理；退出页面必须停止所有 MediaStreamTrack，模型和推理循环不能残留。
• 状态、错误、空数据和加载都用文字表达，不能只靠颜色；按钮和弹窗要支持键盘操作与可读标签。

2.8 Git、Issue 与评审

• 分支从集成分支拉出：feature/<Issue号>-<简短描述> 或 fix/<Issue号>-<简短描述>，不直接向主分支推送。
• 提交说明写“改了什么、为什么改”，例如 feat(auth): add csrf guest context and login rotation；一个提交只解决一个可验收问题。
• Issue 写清目标、范围、依赖、验收步骤、提交/PR、评审人和结果证据；提交必须能关联到 Issue。
• 合并前至少一名其他成员交叉评审；修改共享类型、碰撞、校验或数据库迁移时，要通知所有调用方并补跑相关测试。

三、八人分工

四、七天冲刺计划

每日协作节奏

每天一次站会，按“昨天到现在做了什么、证据在哪里、遇到什么问题、下一次站会前做什么”逐人汇报。站会后开发，晚间留 30 至 60 分钟做联合冒烟、更新燃尽图和整理日报。

每天交接至少给出四样东西：已提交代码和提交号、输入输出样例、成功与失败运行方式、未完成边界和对应 Issue。固定样例只是开发工具，不能在博客里写成真实摄像头或真实后端已经通过。

五、AI 技术员

本次冲刺计划设置 AI 技术员，拟使用 Codex（GPT-5）辅助设计审查、代码实现、测试用例生成和文档整理。AI 不替代成员做最终判断，所有输出都要由成员复核、运行和取舍。

5.1 角色设置

文档整理作为 AI 设计师或 AI 程序员的辅助产出，由李想、林晨等成员人工定稿，不单独设置角色。

5.2 如何驱动 AI

团队采用“给上下文 → 要边界和测试 → 人工审查 → 实际运行 → 记录采用结果”的流程：

1. 给目标与约束：说明模块、接口版本、输入输出、禁止事项和相关代码，不把整个仓库和敏感数据一次性丢给 AI。
2. 要求可验证产出：不只让 AI 写代码，还要它列出触发条件、失败场景、测试断言和未确认的假设。
3. 人工审查：成员检查是否符合设计、是否符合手册、是否存在安全或性能问题；不采纳的也要记录原因。
4. 实际运行：编译、单元测试、接口请求或真机验证通过后，代码才进入提交；AI 生成的代码不能未经运行直接合并。
5. 记录证据：日期、工具/模型、输入摘要、产出、采用与否、人工修改、测试结果和 Issue 都要留下记录。

提示词示例：

按冻结的暂停恢复契约，检查这段游戏状态机是否会出现跨暂停轨迹、重复结算或旧帧驱动；列出触发步骤、期望行为和最小测试断言，不假定未提供的函数存在。

为 ResultValidator 生成边界用例，覆盖分数上下界、时长越界、模式不一致和八段锦阶段乱序；每个用例给出前置条件、输入、期望错误码和断言，不要修改计分公式。

5.3 边界与记录

• 不上传密码、Cookie、CSRF 令牌、真实用户数据、原始摄像头画面或逐帧关键点。
• AI 不替代真实站会照片、真实代码提交和真实测试记录；没有发生的活动不能写成已完成。
• AI 输出中的事实、接口字段和命令必须人工核对；无法验证的内容标注“待确认”，不能直接写成结论。
• 每天单列 AI 技术员工作；没有使用 AI 就如实写“未使用”，不虚构贡献。

上表是冲刺期间的 AI 使用计划，不代表这些产出已经发生。每天结束后，由负责人在当天随笔补充实际采用内容、人工修改和验证证据；未发生的活动保持空白，不提前填写完成状态。

六、协作机制与风险应对

图片说明：计划阶段可放分支与 MR/PR 流程图；实际分支和评审截图在冲刺执行中补充，并且要能看到关联 Issue、评审人和检查结果。不要用空分支截图冒充评审记录。

七、参考

1. 第一次作业：团队介绍
2. 第二次作业：需求与原型
3. 第三次作业：系统与数据库设计
4. 本次作业：站立式会议+α冲刺
5. 《SteadyGame Alpha 七天开发与协作计划》
6. 《阿里巴巴 Java 开发手册》v1.3.0 PDF 终极版
7. 华为云 CodeArts Check 代码检查规则集
8. 《构建之法》
9. Vue 3、TypeScript、MediaPipe Pose Landmarker、OpenAPI 3.1 官方文档