耍起最队——代码规范、Alpha冲刺任务与计划

本文是Alpha阶段的执行计划。D1—D7表示相对开发日，具体日期以团队实际安排和工作项为准；任务进度、测试结果及贡献以真实记录为准。

目录

一、团队代码规范

StudyDay采用Vue 3前端、Go＋Gin＋GORM后端和MySQL持久化。8人并行开发时，先统一命名、接口、数据和合并规则，避免各模块分别维护一套身份处理和错误格式。以下内容在既有团队代码规范基础上，适配当前Go技术栈。

规范参考作业指定的《阿里巴巴Java开发手册》终极版v1.3.0，提取可读性、异常日志、测试、安全、数据库及工程管理等通用要求；华为部分采用可公开核验的方舟编译器编程规范中的清晰表达、模块职责、复用与验证原则。具体Go命名和格式按Go官方代码审查建议执行。本文列出的条款是本团队约定，不把Java或C++专用写法直接作为Go规则。

1. 命名规范

避免无意义的data1、temp2及拼音名称。金额、时间和数量等字段写清单位；本项目专注时长用Seconds或Minutes区分，前端不猜测后端返回的是秒还是分钟。API中的长整型ID按字符串传输，Go字段与JSON名字通过标签明确映射。

2. 代码格式与工程文件

1. 源文件统一UTF-8、LF换行；提交前移除无用空白，保留文件末尾换行。
2. Go代码执行gofmt，缩进和基础排版交给工具；Vue、JS/TS、JSON、CSS及配置文件采用项目统一格式配置，默认2个空格。
3. 函数围绕一项明确职责组织，复杂分支拆成可理解的方法；状态码和时间上限使用具名常量。
4. 同一次提交围绕一个目的，避免把功能修复和全仓库重排混在一起。
5. 保留go.mod、go.sum及前端依赖锁文件；工具链、依赖和构建镜像按工程清单固定。前端使用锁文件安装，配置示例不包含真实凭证。

Go格式、注释和Context传递的语言习惯以官方代码审查建议为参考；本轮工程使用的具体版本以仓库锁定结果为准。

3. 注释规范

导出类型和函数写清业务用途，注释以对应标识符开头。权限、版本、任务类别、专注结算和事务等逻辑，重点说明“为什么要这样处理”及约束来源。接口变更、状态调整时同步更新注释；TODO注明关联工作项和待完成内容。

本项目尤其需要注释说明：为什么结束专注不自动完成任务、为什么历史使用开始时快照、为什么AI回答生成与业务保存分别判断。避免对简单赋值逐行复述，或用注释掩盖未实现的功能。

4. Go错误处理、日志与配置

1. 返回的err必须按场景处理或向上返回；禁止忽略数据库错误后继续响应成功。普通业务错误使用明确类型/错误码，panic仅保留给非正常故障，Gin恢复中间件承担兜底。
2. 错误携带必要操作背景，需保留原错误关系时使用包装；对外按接口约定返回可读信息，不暴露堆栈和数据库细节。
3. 日志使用统一封装或log/slog，记录requestId、操作、资源标识、状态和耗时。密码、token、AI密钥及完整私人笔记/聊天正文不进日志。
4. 配置从服务端环境变量或受控配置加载，提供无真实口令的示例；本地和测试环境分别配置。
5. 数据库与上游模型调用传递请求context.Context，并设置超时；响应体等资源及时关闭。前端请求失败保留输入，确认保存结果后再显示成功。

注册登录沿用Argon2id口令散列和既定JWT方案；密码不明文保存、不静默trim或截断，8—64字符按Unicode码点校验。认证从服务端确定当前用户，所有资源及关联目标仍需核对归属。

Handler取得请求Context后传给Service和DAO，Service不依赖gin.Context。不跨goroutine持有原始Gin上下文，异步任务须明确生命周期与取消行为。相关生命周期说明见Gin官方文档。

5. Gin分层与接口约定

接口沿用统一/api前缀、Bearer认证和Result结构（code、message、data、requestId）。时间使用带+08:00的约定格式，服务端按Asia/Shanghai处理；列表使用既定分页。参数、未登录、权限、业务/版本冲突和系统错误按共同错误码区分。

前端负责即时提示，后端逐项校验本人及关联对象。接口变动先更新共同说明并通知对接人，再同步实现和测试。本轮AI可先完整非流式返回，在接口对照表说明与最终SSE方案的差异；若采用SSE，收到delta只表示生成中，提交后saved才表示成功保存。

6. GORM、SQL与事务规范

1. 沿用数据库设计V1.3和审核DDL，显式映射单数表名、列名、可空字段、复合主键及只读生成列。可以初始化现有16表，本轮只实现会使用的对象；空表不代表对应功能已完成。
2. 数据结构变更提交受审迁移脚本和影响说明，不以启动时AutoMigrate随意改写既定结构。
3. SQL值使用参数绑定，排序字段等动态标识由白名单产生。查询明确字段和分页，带本人范围，避免循环逐条查询。
4. 多步业务写入在Service开启显式事务，全部相关DAO复用同一个tx；回调返回错误则回滚，提交成功后再响应成功。外部AI调用放在数据库长事务之外。
5. 更新0、false或NULL时显式选择允许字段，防止遗漏；修改带对象归属和适用版本条件，检查影响行数，无变化按设计处理，不能把所有0行都当成同一种错误。
6. 本轮最小成功去重工具由柯镇海提供、胡加乘和范敬翔复用。认证后业务请求沿用X-Request-Id；同意图成功重放返回原结果，同标识异内容拒绝。注册/登录按独立校验和唯一约束处理。

多步写入显式事务与同一tx使用方式参考GORM事务文档；结构体更新默认忽略零值等行为参考GORM更新文档，具体字段白名单及无变化处理按本组设计执行。

7. Git提交与协作规范

沿用已确认的main稳定分支、develop集成分支及功能/修复分支约定。成员从集成版本建立与工作项对应的分支，例如feat/task-create、fix/focus-finish；公共文件由指定成员维护，修改他人模块时先与对接人确认。

提交说明采用“类型(模块): 修改说明”，并关联真实工作项：

feat(task): 新增生活任务创建与课程校验
fix(focus): 修复重复结束时的结算处理
test(auth): 增加跨用户访问回归用例
docs(plan): 更新Alpha接口和运行说明

类型使用feat、fix、docs、test、style、refactor等明确目的。工作项关联采用CodeArts中的实际编号和仓库配置；提交或合并请求中保留可追踪关系，不使用计划表D2-01等编号冒充平台编号。

每个合并请求写清目的、影响范围、关联工作项、验证方法及未完成项，至少由一名非作者复核；接口/数据库变更邀请对接成员确认。冲突由相关作者核对语义后处理，再做相关回归。main保留可复现的阶段版本及标签。

不提交依赖安装目录、无关构建产物、真实凭证、个人IDE配置和含隐私的备份/日志；保留必要依赖清单、锁文件、SQL、配置示例和README。

8. 测试与完成标准

后端提交前执行gofmt、go vet ./...、go test ./...；在支持环境运行竞态检查。前端执行项目已配置的格式/静态检查、构建及相关测试。尚未配置或未执行的检查，在记录中明确说明，不写成自动通过。

测试与开发从D1并行：先覆盖登录/本人隔离、两类任务、专注恢复/一次结算、AI保存及确认笔记。关键并发和事务在MySQL目标库验证；可控AI替身用于失败测试，真实模型调用另留集成记录。

一项任务记为“完成”前，至少满足以下条件：

• 实现与工作项范围一致，代码/文档等成果已提交。
• 权限、状态、事务和重复请求等适用规则已检查。
• 接口与数据库保存真实可用，相关前后端已经联通。
• 对应自测和必要回归有环境、版本、实际结果。
• 非作者复核完成，运行说明和变更记录可查看。

二、Alpha冲刺任务与计划

1. 本轮目标与范围

本轮计划连续7个开发日、8位成员参与。按每人每天约4小时有效投入估算，总容量约224人时，包含开发、本职测试、联调和记录返工；参考分配为2.5小时开发/本职工作、1小时联调测试、0.5小时记录/返工，具体由成员按实际调整。

Alpha先完成两条真实、可保存、刷新后能恢复的流程：

1. 注册/登录 → 最小周课表 → 从课程创建学习任务、另建生活任务 → 待办任务专注 → 刷新恢复 → 结束与历史 → 另行手动完成任务。
2. 真实AI问答 → 完整成功回答入库 → 可编辑预览/取消 → 用户确认转笔记 → 笔记列表和详情刷新可见。

页面以可读、可操作为先，完整管理页面、复杂动画和全机型精修按后续安排。全项目需求和设计仍保留；本轮测试只对实际实现的Alpha范围下结论，不宣称完整F1—F8或A1—A28已全部通过。

2. 团队分工安排

笔记的AI来源校验和预览由黄思哲负责，NoteService最小存储及初始版本由胡加乘协助实现，赵子龙统一接页面；避免AI后端独自承担所有业务。三名前端按页面归属开发，复用黄思扬维护的公共路由、请求及布局。

3. 冲刺排期表（每日计划）

下表按已有7天8人任务清单概括，一格对应一位成员当天的一条主任务，共56项。为便于阅读，拆成负责人/后端、前端/测试两张表，详细验收、依赖和风险在对应工作项中维护。

负责人和后端安排：

前端和测试安排：

排期遵循“工程与契约 → 真实读写 → 跨模块联调 → 本地演示 → 修复与可选部署 → 回归彩排 → 阶段交付”。接口先定字段再并行开发，专注依赖真实任务ID，确认笔记依赖已保存成功回答；前置未通过时先修阻塞，其他独立工作继续推进。

4. 每日验收里程碑

5. 敏捷协作机制

6. 进度、风险与过程材料

每天记录实际Issue/提交、运行结果、缺陷与复测，以及真实剩余估算。燃尽图保持同一统计口径，未来实际点留空；每日4小时是容量预算，不直接作为剩余工作量或实际投入。

冲刺材料按作业安排形成：计划与代码规范随笔、7篇真实日进展、测试随笔、冲刺总结和材料集合。成员贡献依据实际完成工作、提交、测试及协作记录归纳，AI辅助单独说明。

三、引入AI技术员

AI技术员是成员使用的辅助角色，不额外算第9位组员。工具采用成员实际可用的AI编程助手或对话工具，在每日记录中注明工具/模型、具体任务、采用内容、人工修改和验证结果。以下分工是计划用途，实际使用情况按当天记录填写。

1. AI程序员：辅助重复代码与问题定位

AI先起草重复的结构和排查清单，成员把主要精力放在规则、接口及运行结果。不会仅凭AI声称“已修复”或“测试通过”就合入。

可使用的任务描述示例：

请按已确认的Go/Gin/GORM工程边界，审查专注开始与结束逻辑。
约束：本人TODO任务才能开始；同用户最多一条RUNNING；保存标题和类型快照；
同focusId只结算一次，结束不自动完成任务。
请先列出遗漏分支和需要实测的并发场景，再给最小修改建议。
不要新增数据库表、接口或独立提交事务。

2. AI测试员：辅助边界用例与回归脚本

郑宇澄统筹，相关开发成员核对业务预期。输入包括当前接口、需求规则、实际缺陷和隔离测试数据，AI协助把内容整理成“前置—操作—预期—验证位置”的用例和脚本初稿。

可使用Go测试、Gin的httptest、核心接口脚本及浏览器操作验证。AI减少从空白整理边界和脚本的重复劳动，实际执行、预期核实及结论由人负责；生成脚本不等于测试通过。全面压测和灾备目标留后续专项验收。

可使用的任务描述示例：

请根据当前接口契约，把“成功回答确认转笔记”写成测试用例。
覆盖：未登录、他人消息、生成失败、预览取消、确认成功、响应丢失后重试。
每项写前置、请求、预期响应和应检查的数据库变化。
只输出用例/脚本建议，不编造执行结果。

3. AI设计师：辅助核心页面与状态检查

由杨伟烨、赵子龙、黄思扬负责采用和复核。输入现有原型、公共Vue组件、字段约定及当前页面，AI协助起草表单、加载/空态/失败反馈和布局修复建议。

AI设计辅助优先减少状态遗漏和重复组件编写，不推动本轮新增复杂页面。模拟数据明确标记，最终演示切真实接口。

4. AI记录助理与采用流程

柯镇海可把成员实际提供的Issue、提交和测试结果交给AI整理为会议、接口差异和阶段总结草稿。成员逐项确认本人内容，补充证据及未完成项，避免文字进度与真实版本脱节。

AI代码仍由实际提交、理解和验证的成员负责。密钥、口令、令牌和私人内容不进入提示词或公开截图；没有真实计时就描述减少了哪一步重复工作，不填写未经测量的效率百分比。

四、阶段交付与计划调整

本轮交付以真实可运行结果为准：一套可复现的工程和初始化说明、两条主流程、核心测试及缺陷记录、实际版本与每日过程材料。D4先做本地演示，D6彩排，D7展示与归档；华为云、统计和流式效果按条件与余量说明结果。

每天对照工作项验收，有阻塞先明确失败环节和对接人。D4重新估算剩余量，保留最小主链路；未完成内容列后续迭代。代码规范随实现共同维护，规则变更写明原因、确认人和受影响接口/测试。

阶段展示既呈现页面，也呈现从需求到任务、提交、联调、问题修复和复测的过程。我们希望这7天结束时，团队能够清楚说明做成了什么、证据在哪里，以及下一阶段先解决什么。

参考资料

• 阿里巴巴Java开发手册终极版v1.3.0。
• 华为公开方舟编译器编程规范。
• Effective Go与Go代码审查建议。
• GORM事务与GORM更新。
• Gin上下文生命周期。
• 本组Go版需求规格说明书V0.5、系统设计V1.3、数据库设计V1.3、Alpha阶段7天8人计划和既有团队代码规范。
• 随笔结构参考，参考章节和表格组织方式。