Phase 0 - 项目初始化

建立统一的开发环境、代码结构与协作规范，让团队可以稳定开始开发。

⁋ 0.1 - 建立代码仓库与组织结构

完成 lab-edu 组织及基础仓库搭建，建立统一代码协作环境。

创建 GitHub Organization

需要在 GitHub 上创建一个名为 lab-edu 的 Organization，并将所有项目成员统一纳入该组织中进行集中管理。这里的关键不是 “创建组织” 本身，而是要解决权限与协作边界问题：需要明确谁拥有 Owner 权限（通常 1~2 人），谁是普通成员，避免后期误删仓库或权限混乱。同时需要考虑仓库是 public 还是 private（建议开发期 private，展示或开源时再转 public），并提前规划团队结构（如是否按前端 / 后端分 Team），为后续多人协作打好基础。

创建基础仓库

在 Organization 下创建最小必要的核心仓库：web、core、docs、infra。每个仓库都需要进行 “标准初始化”，包括添加 README（说明该仓库职责）、合理的 .gitignore（避免无关文件提交）以及基础目录结构（例如 web 初始化前端项目骨架，core 初始化 Spring Boot 项目）。这一环节的核心工程问题是：避免后期仓库职责混乱，例如把前端代码写进后端仓库，或者文档散落各处，因此必须在一开始就明确 “每个仓库只做一件事”。

分支策略初始化

为每个仓库建立统一的分支策略，至少包括 main（稳定分支）和 dev（开发主分支），并将默认分支设置为 dev。需要在 GitHub 中开启 main 分支保护（禁止直接 push），确保所有变更必须通过 Pull Request 合并。这里的核心是解决多人并行开发的代码冲突与稳定性问题：开发人员在 feature/* 分支上工作，合并到 dev，最终再由负责人合并到 main，从而保证主分支始终可发布、可演示。执行上应以 dev 分支的 CI 检查通过作为合并 main 的前置条件。

Pull Request 流程配置

需要在所有仓库中统一 Pull Request（PR）流程，包括创建 PR 模板（说明需要填写的内容，如改动说明、测试情况）、设置至少 1 人 Review 才能合并，以及明确 Review 规范（例如是否需要跑通项目、是否检查接口变更）。这一部分的核心工程问题是：避免 “代码直接合并导致质量失控”，并让团队形成基本的代码评审文化。通过规范 PR 流程，可以在早期就发现接口不一致、逻辑错误或设计问题，大幅降低后期维护成本。

⁋ 0.2 - 系统架构设计与技术选型

完成系统整体架构设计与技术选型，明确各模块边界与技术路线，避免后期因设计不清导致的大规模重构。

定义系统模块边界

需要明确整个系统由哪些核心模块组成，以及每个模块 “负责什么、不负责什么”。至少要划分出 web（前端）、core（后端）、ai-service（智能服务，预留）、fpga-service（硬件实验服务，预留）。关键工程问题在于：防止模块职责重叠或耦合过高，例如前端直接处理业务逻辑、后端同时承担 AI 任务等。需要为每个模块写清楚输入输出（例如 core 提供 API，web 只调用 API），并约定模块之间只能通过接口通信，而不能直接共享内部实现。

设计系统整体架构图

需要绘制一张清晰的系统架构图（建议包含组件图 + 数据流图），描述前端、后端、数据库以及未来 AI / FPGA 服务之间的关系。重点不是“画图好看”，而是解决数据如何流动、请求如何走、系统如何扩展的问题。需要标明：用户请求从 web 发起，经由 HTTP 到 core，再访问数据库；以及未来如何接入 AI 服务（例如 core 调用 ai-service）。这一步还需要提前考虑：是否会用 WebSocket（为实时功能预留），是否需要网关（后期扩展）。

技术选型确认

需要为每个模块确定技术栈，并说明选择理由，避免后期频繁更换技术。需要明确：前端使用 Next.js（便于快速构建页面与路由）、后端使用 Spring Boot（稳定、适合 REST API）、数据库使用 PostgreSQL（结构化数据，作为当前统一基线）、AI 使用 Python（生态成熟）。关键工程问题是：保证技术栈之间兼容且团队成员能掌握，不要为了 “炫技” 选复杂技术（如一开始就上微服务或 K8s）。同时需要考虑开发效率、学习成本以及部署复杂度。

定义服务间通信方式

需要明确不同模块之间如何通信，例如 web 与 core 使用 HTTP / REST API，core 与 ai-service 使用 HTTP 或 gRPC（后期再决定）。这一部分的核心是解决模块解耦与扩展性问题：不能让模块之间产生强依赖（例如直接调用数据库或共享代码）。同时需要统一数据格式（JSON 结构）、接口版本（如 /api/v1/），避免后期接口混乱或升级困难。

数据模型与核心实体初步抽象

需要在架构层面提前定义系统的核心数据对象，例如：用户（User）、课程（Course）、实验（Experiment）、提交记录（Submission）。这一步不需要写完整 SQL，但需要解决系统核心概念是否清晰的问题，例如：实验是否属于课程？提交是否允许多次？是否需要版本记录？这些设计如果后期才考虑，会导致数据库重构成本极高。

输出架构与技术文档

需要将以上所有设计沉淀到 docs 仓库中，形成可共享的文档，包括：architecture.md（系统架构说明）、tech-stack.md（技术选型说明）、以及简单的图示（可以用 draw.io 或 Markdown）。核心目标是解决信息同步问题：确保所有团队成员对系统理解一致，而不是只存在于某个人脑中。同时这些文档也将直接用于后期答辩或展示。

⁋ 0.3 - 开发规范与协作流程制定

建立统一的开发规范与协作流程，确保多人开发过程中代码风格一致、协作顺畅，并避免因流程混乱导致的质量问题。

Git 工作流设计

需要为团队明确一套简单但可执行的 Git 工作流，建议采用 “简化版 Git Flow”，即以 dev 作为日常开发主分支，main 作为稳定发布分支。开发人员必须基于 dev 创建 feature/* 分支进行开发，完成后通过 Pull Request 合并回 dev，严禁直接在主分支上开发。这里的核心工程问题是：避免多人同时修改同一分支导致混乱，以及保证主分支始终可用。同时需要约定分支命名规则（如 feature/login、fix/auth-bug），提高可读性和可维护性。

Commit 提交规范

需要统一 Commit Message 格式，推荐使用结构化前缀（如 feat:、fix:、docs:、refactor: 等），并要求每次提交描述清晰具体（说明 “做了什么改动”，而不是简单写 “update”）。这一规范的核心是解决代码历史不可读的问题：当后期需要定位 bug 或回滚功能时，清晰的提交记录会极大降低成本。同时可以在仓库中提供示例，并在 Code Review 时进行约束，逐步形成团队习惯。

接口设计与返回规范

需要统一后端 API 的设计风格，采用 RESTful 规范，并统一接口路径结构（例如 /api/v1/...），避免接口命名混乱。同时必须规定统一的返回数据结构，例如包含 code、message、data 字段，以便前端统一处理。这里的核心工程问题是：防止接口风格不一致导致前端适配成本暴增，以及避免后期接口升级时出现兼容性问题。还需要明确分页、错误返回、鉴权等常见场景的统一处理方式。

错误处理与错误码规范

需要设计一套统一的错误码体系，并在后端实现全局异常处理机制。基本要求包括：成功返回统一 code（如 0），业务错误使用区间编号（如 1000+），系统错误使用另一段区间。同时需要规定错误信息的返回格式（对用户友好，对开发可调试）。这一部分的核心是解决错误处理混乱、难以定位问题的情况，让前端可以根据错误码做逻辑处理（如提示用户或重试），而不是依赖字符串判断。

代码规范与项目结构约定

需要为前端和后端分别制定代码结构规范，例如后端按 controller / service / repository 分层，前端按 app / components / services 划分模块。同时需要引入基础的代码规范工具（如 ESLint、Prettier 或 Java Checkstyle），并在项目中提供基础配置。核心工程问题是：防止代码风格混乱、目录结构失控，否则随着代码量增加，维护成本会迅速上升。

Pull Request 与 Code Review 规范

需要明确 PR 的使用方式和 Review 标准，包括：所有代码必须通过 PR 合并、PR 必须包含改动说明、至少一人 Review 通过后才能合并。还需要规定 Review 时关注的重点（如逻辑正确性、接口一致性、是否破坏已有功能）。这一部分的核心是建立最基本的代码质量控制机制，避免低质量代码直接进入主分支，同时通过 Review 提升团队整体技术水平。

⁋ 0.4 - 文档体系初始化

建立统一的文档体系与维护机制，确保项目知识可共享、可追溯、可持续更新，并避免文档与代码脱节。

编写项目 README（入口文档）

需要在 docs 仓库（以及各子仓库）中编写清晰的 README，作为所有开发者进入项目的第一入口。README 不只是 “介绍项目”，而是要解决新成员如何快速理解并运行项目的问题。内容应包括：项目简介、技术栈说明、仓库结构、快速启动步骤（如何运行 web / core）、以及基本开发流程说明。这一步的核心工程问题是：避免知识只存在于口头沟通中，让任何人都可以通过 README 快速上手项目。

建立系统架构文档

需要将 0.2 中设计的系统架构正式整理成文档（如 architecture.md），包括模块划分说明、服务关系图、数据流说明等。这不仅是 “记录”，更是解决团队对系统理解不一致的问题。文档中应明确每个模块的职责（web / core / ai等）以及它们之间的交互方式（HTTP / WebSocket），并配合图示（推荐 draw.io）。这份文档在后期开发、调试以及答辩中都会被频繁使用。

建立 API 文档模板（接口先行）

需要在项目初期就定义 API 文档格式，推荐使用 Swagger / OpenAPI 标准，并约定接口描述方式（路径、参数、返回结构），并统一使用 /api/v1 版本前缀。核心目标是实现 “接口先行” 开发：后端在实现前先定义接口，前端可以基于文档进行开发或 mock 数据。这里要解决的工程问题是：前后端不同步、接口反复修改，通过统一文档可以显著减少沟通成本与返工。

建立数据库设计文档

需要在 docs 中建立数据库设计文档（如 database.md），记录核心表结构与字段含义，而不是只依赖代码中的实体类。文档应包含：表说明、字段定义、字段类型、是否可为空、业务含义等。这一步的核心是解决数据结构不透明和后期难以维护的问题，尤其是在多人协作时，可以避免随意改表或重复建表。

建立开发文档结构与目录规范

需要对 docs 仓库本身进行结构设计，例如划分为 phases/、architecture/、guides/、reference/ 等目录，避免文档堆积混乱。核心工程问题是：随着项目推进文档会快速增长，如果没有结构，很快就不可用。同时可以约定命名规范（如英文命名、使用 Markdown），确保文档统一可读。

建立文档更新与维护机制

需要明确文档不是 “一次性工作”，而是需要持续维护。需要规定：当接口变更、数据库修改或架构调整时，必须同步更新文档；可以在 PR 流程中加入检查（如 “是否更新 docs”）。这一部分解决的是文档与代码脱节的问题，否则文档很快会失去参考价值。

⁋ 0.5 - DevOps 基础环境搭建

建立最小可用的 DevOps 基础设施，实现统一开发环境与一键启动能力，确保所有成员可以快速运行项目并进入开发状态。

构建统一的 Docker 开发环境

需要为项目建立基于 Docker 的统一开发环境，确保所有成员在相同环境下运行服务，避免 “在我电脑上是好的” 的问题。核心工作是为 core（后端）和 web（前端）编写基础 Dockerfile，并选择合适的基础镜像（如 Node、OpenJDK）。这里的关键工程问题是：不同操作系统、不同依赖版本带来的环境不一致问题，通过容器化可以彻底隔离环境差异。

编写 docker-compose 开发编排配置

需要在 infra 仓库中编写 docker-compose.dev.yml，统一管理多个服务的启动，包括数据库（PostgreSQL）、后端（core）和前端（web）。需要明确服务依赖关系（如 core 依赖 db），配置端口映射，并保证一条命令（docker-compose up）即可启动整个系统。这一步的核心是解决多服务项目启动复杂、步骤繁琐的问题，让开发从 “手动配置” 变为 “自动编排”。同时建议在编排层预留 ai-service 与 fpga-service 的容器位（可先空实现），只做网络连通与健康检查占位，避免在 Phase 0 引入过多业务复杂度。

配置环境变量管理机制

需要设计统一的环境变量管理方式（如 .env 文件），用于管理数据库连接、端口号、密钥等配置项。必须明确哪些配置写在代码中，哪些必须通过环境变量注入。核心工程问题是：避免敏感信息泄露以及不同环境配置混乱（开发/测试/生产），同时让项目具备可迁移性（换一台机器也能运行）。

提供项目启动与停止脚本

需要在 infra/scripts 中编写基础脚本（如 start.sh、stop.sh），封装 docker-compose 命令，降低使用门槛。脚本应包含基础检查（如 Docker 是否安装）、日志输出等，确保开发者无需记忆复杂命令即可启动项目。这里的核心是解决开发体验问题：让团队成员用最少的学习成本进入开发状态。

建立基础 CI（持续集成）流程

需要在 .github/workflows 中配置基础的 GitHub Actions 工作流，实现代码提交后的自动检查，例如：代码能否成功构建、是否存在明显错误。初期不需要复杂流程，只需保证 “代码不会一提交就坏”，并将其作为 dev 合并质量门禁，再作为 main 合并前置校验。核心工程问题是：避免不稳定代码进入主分支，并为后续自动化测试与部署打基础。

验证 “一键运行” 目标

需要在 Phase 0 结束前进行一次完整验证：由一名 “未参与环境配置” 的成员，按照 README 从零开始运行项目，确保可以在最短时间内成功启动。这一步非常关键，用于验证前面所有工作的有效性。核心工程问题是：检验环境配置是否真正可复现，避免出现“只有搭建者能运行”的情况。阶段完成判定应同时满足 “规范可执行” 和 “运行可复现”。