Skip to content

Commit 3ef3123

Browse files
xv1rcnxv1rcn
authored
Merge pull request #1 from lab-edu/dev
docs: 完成 Phase 0 文档体系重构与发布流程
2 parents 2d1ec38 + b48478f commit 3ef3123

26 files changed

Lines changed: 1579 additions & 208 deletions

‎.github/pull_request_template.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<!-- 标题请写本次改动的简要总结 -->
2+
3+
## 变更说明
4+
<!-- 详细描述本次改动 -->
5+
6+
## 变更动机与背景
7+
<!-- 为什么需要这个改动？解决了什么问题？ -->
8+
<!-- 如果修复了某个 Issue，请在这里关联。 -->
9+
10+
## 测试方式
11+
<!-- 详细说明你如何测试本次改动。 -->
12+
<!-- 包括测试环境、执行过的测试，以及对其他模块的影响验证。 -->
13+
14+
## 变更类型
15+
<!-- 请选择所有适用项，在方框内填 x -->
16+
- [ ] Bug 修复（不破坏现有功能）
17+
- [ ] 新功能（不破坏现有功能）
18+
- [ ] 破坏性变更（会影响现有功能行为）
19+
20+
## 检查清单
21+
<!-- 请逐项确认，在方框内填 x -->
22+
<!-- 如不确定，可在 PR 中说明。 -->
23+
- [ ] 代码遵循本项目代码风格。
24+
- [ ] 本次改动需要更新文档。
25+
- [ ] 已同步更新相关文档。
26+
- [ ] 已添加覆盖本次改动的测试。
27+
- [ ] 所有新旧测试均已通过。

‎.github/workflows/pages.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Deploy docs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Check out repository
22+
uses: actions/checkout@v4
23+
24+
- name: Set up uv
25+
uses: astral-sh/setup-uv@v5
26+
27+
- name: Install dependencies
28+
run: uv sync --locked
29+
30+
- name: Build site
31+
run: uv run mkdocs build --strict
32+
33+
- name: Configure GitHub Pages
34+
uses: actions/configure-pages@v5
35+
36+
- name: Upload artifact
37+
uses: actions/upload-pages-artifact@v3
38+
with:
39+
path: site
40+
41+
deploy:
42+
needs: build
43+
runs-on: ubuntu-latest
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
steps:
48+
- name: Deploy to GitHub Pages
49+
id: deployment
50+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# lab-edu docs
2+
3+
lab-edu 项目的文档仓库，使用 MkDocs 构建站点。
4+
5+
## 仓库用途
6+
7+
- 维护项目的阶段规划（Phase 0 ~ Phase 4）
8+
- 沉淀架构设计、开发指南、参考资料
9+
- 作为团队协作的统一知识入口
10+
11+
## 目录结构
12+
13+
```text
14+
docs/
15+
├── docs/ # Markdown 文档源文件
16+
│ ├── index.md
17+
│ ├── phases/
18+
│ ├── guides/
19+
│ ├── architecture/
20+
│ └── reference/
21+
├── mkdocs.yml # MkDocs 配置
22+
├── pyproject.toml # Python 依赖配置
23+
└── uv.lock # 依赖锁文件
24+
```
25+
26+
## 如何构建
27+
28+
### 1) 安装依赖
29+
30+
使用 uv：
31+
32+
```bash
33+
uv sync
34+
```
35+
36+
### 2) 本地预览
37+
38+
```bash
39+
uv run mkdocs serve
40+
```
41+
42+
### 3) 生成静态站点
43+
44+
```bash
45+
uv run mkdocs build
46+
```
47+
48+
构建产物默认输出到 `site/` 目录。

‎docs/architecture/communication.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# 通信方式
2+
3+
这一页说明各模块之间如何通信，以及哪些约定必须先统一。
4+
5+
## 当前约定
6+
7+
- web 通过同源入口访问 core 暴露的接口
8+
- core 对外使用统一的 HTTP API
9+
- api 路径统一使用 `/api/v1` 前缀
10+
- 返回结构统一为 `code`、`message`、`data`
11+
12+
## 预留原则
13+
14+
- core 与 ai-service、fpga-service 之间先按“接口通信”处理
15+
- 具体协议先不在 Phase 0 里锁死
16+
- 如果后续业务需要更高吞吐或更强约束，再单独评估 gRPC 或其他方案
17+
18+
## 设计目标
19+
20+
- 降低模块间耦合
21+
- 让前后端和预留服务都能独立演进
22+
- 让接口文档先于实现存在，减少联调摩擦

‎docs/architecture/data-model.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# 数据模型
2+
3+
这一页只做核心实体的初步抽象，不写完整 SQL，也不展开表结构细节。Phase 0 的目标是先把概念讲清楚，避免后面反复重构。
4+
5+
## 核心实体
6+
7+
- Organization: 组织或团队边界
8+
- Role: 角色与权限范围
9+
- User: 用户账户与登录身份
10+
- Course: 课程或业务主线容器
11+
- Experiment: 实验或任务定义
12+
- Submission: 提交记录与执行结果
13+
14+
## 关系约束
15+
16+
- Organization 管理成员和协作边界
17+
- Role 决定用户能做什么
18+
- Course 组织多个 Experiment
19+
- Experiment 可以有多个 Submission
20+
- Submission 记录每次提交的状态、结果与时间
21+
22+
## 约束原则
23+
24+
- 先保证概念稳定，再考虑表结构优化
25+
- 需要历史追踪的对象要保留版本或记录能力
26+
- 任何字段命名都要能被前后端共同理解

‎docs/architecture/index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# 架构设计
2+
3+
系统整体设计与技术边界说明，用于统一团队的架构认知。
4+
5+
## 核心文档
6+
7+
- [模块边界](modules.md): web / core / ai-service / fpga-service 的职责边界
8+
- [技术选型](tech-stack.md): 前端、后端、数据库与预留服务的基线
9+
- [通信方式](communication.md): 模块之间的接口约定与版本规则
10+
- [数据模型](data-model.md): 核心实体关系与演进约束
11+
12+
## 架构约束
13+
14+
- 统一 API 版本前缀: `/api/v1`
15+
- 统一响应结构: `code` / `message` / `data`
16+
- 服务间通过接口通信，避免跨模块内部耦合

‎docs/architecture/modules.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# 模块边界
2+
3+
这一页说明系统里每个模块负责什么、不负责什么。当前阶段的目标不是把边界画得极其复杂，而是先把职责分开，避免后续代码和流程互相越界。
4+
5+
## web
6+
7+
- 负责页面展示、表单交互、前端状态管理与请求发起
8+
- 只通过接口调用 core，不直接访问数据库
9+
- 不承载业务规则的最终判断，不承担数据持久化
10+
11+
## core
12+
13+
- 负责业务规则、权限校验、数据读写与对外 API
14+
- 为 web 提供统一的 HTTP 接口
15+
- 未来如果接入 ai-service 或 fpga-service，也由 core 作为协调层进行调用
16+
17+
## ai-service
18+
19+
- 预留给智能分析、模型推理、内容生成等能力
20+
- 目前只定义边界，不要求马上落实现有业务
21+
- 与 core 的交互方式先按接口通信预留，具体协议后续再定
22+
23+
## fpga-service
24+
25+
- 预留给硬件实验、加速执行或专用设备能力
26+
- 负责封装底层执行细节，对外只暴露稳定接口
27+
- 不直接暴露给 web，由 core 统一编排
28+
29+
## 边界原则
30+
31+
- 模块之间只通过接口通信
32+
- 模块内部实现不跨仓库共享
33+
- 业务逻辑优先放在 core，前端只做展示和交互
34+
- 预留模块先定义名字和职责，不提前塞进复杂实现

‎docs/architecture/tech-stack.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# 技术选型
2+
3+
这一页记录 Phase 0 需要先固定下来的技术基线，避免后续频繁更换技术栈。
4+
5+
## 前端
6+
7+
- 采用 Next.js
8+
- 适合页面路由、同源请求和后续扩展
9+
- 当前以 web 作为唯一前端入口
10+
11+
## 后端
12+
13+
- 采用 Spring Boot
14+
- 适合 REST API、权限控制和常规业务编排
15+
- 当前以 core 作为唯一主业务后端
16+
17+
## 数据库
18+
19+
- 采用 PostgreSQL 作为统一基线
20+
- 先保证结构化数据与演进能力，再考虑其他存储
21+
- 数据库设计优先围绕课程、实验、提交与权限展开
22+
23+
## 预留服务
24+
25+
- ai-service 预留给 Python 生态相关能力
26+
- fpga-service 预留给硬件实验或加速执行能力
27+
- Phase 0 只保留接口和命名，不强行实现全部功能
28+
29+
## 选择原则
30+
31+
- 优先稳定和可维护，不优先追求炫技
32+
- 技术栈之间要能无缝协作
33+
- 团队成员需要能在短时间内接手和修改

‎docs/guides/devops.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# DevOps 基础
2+
3+
这一页定义 Phase 0 里最小可用的运行与启动方式。
4+
5+
## 开发环境
6+
7+
- 使用 Docker 保证环境一致性
8+
- core、web、db 通过 Compose 编排
9+
- 入口由 nginx 统一转发
10+
11+
## 启动方式
12+
13+
- 通过 `infra/scripts/start.sh` 启动开发环境
14+
- 通过 `infra/scripts/stop.sh` 停止开发环境
15+
- `.env` 负责注入数据库、端口和运行参数
16+
17+
## 运行约定
18+
19+
- `dev` 用于日常开发
20+
- `main` 用于稳定发布
21+
- 开发期优先保证一条命令能跑起来
22+
23+
## 预留内容
24+
25+
- ai-service 和 fpga-service 先保留编排位置
26+
- 暂时只需要网络连通和健康检查占位
27+
- 不在 Phase 0 里引入过重的部署复杂度

‎docs/guides/git-workflow.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Git 工作流
2+
3+
这一页是团队 Git 协作的唯一规则页面，覆盖分支、提交、PR 与评审门禁。
4+
5+
## 分支策略
6+
7+
- `main` 作为稳定分支，只用于可发布代码
8+
- `dev` 作为日常开发主分支
9+
- 新功能使用 `feature/*` 分支
10+
- 问题修复使用 `fix/*` 分支
11+
12+
## 开发流程
13+
14+
1. 从 `dev` 切出 `feature/*` 或 `fix/*`
15+
2. 在个人分支完成开发与自测
16+
3. 提交 Pull Request 合并回 `dev`
17+
4. 验证通过后再由负责人从 `dev` 合并到 `main`
18+
19+
## PR 规则
20+
21+
- 所有代码变更必须通过 PR 合并
22+
- 禁止直接向 `main` 推送业务改动
23+
- 合并前至少 1 人 Review
24+
- PR 描述必须写明改动内容与验证方式
25+
26+
## PR 模板示例
27+
28+
以下是可直接复用的 Pull Request 模板，可放在仓库的 `.github/pull_request_template.md` 中。
29+
30+
```text
31+
<!-- 标题请写本次改动的简要总结 -->
32+
33+
## 变更说明
34+
<!-- 详细描述本次改动 -->
35+
36+
## 变更动机与背景
37+
<!-- 为什么需要这个改动？解决了什么问题？ -->
38+
<!-- 如果修复了某个 Issue，请在这里关联。 -->
39+
40+
## 测试方式
41+
<!-- 详细说明你如何测试本次改动。 -->
42+
<!-- 包括测试环境、执行过的测试，以及对其他模块的影响验证。 -->
43+
44+
## 变更类型
45+
<!-- 请选择所有适用项，在方框内填 x -->
46+
- [ ] Bug 修复（不破坏现有功能）
47+
- [ ] 新功能（不破坏现有功能）
48+
- [ ] 破坏性变更（会影响现有功能行为）
49+
50+
## 检查清单
51+
<!-- 请逐项确认，在方框内填 x -->
52+
<!-- 如不确定，可在 PR 中说明。 -->
53+
- [ ] 代码遵循本项目代码风格。
54+
- [ ] 本次改动需要更新文档。
55+
- [ ] 已同步更新相关文档。
56+
- [ ] 已添加覆盖本次改动的测试。
57+
- [ ] 所有新旧测试均已通过。
58+
```
59+
60+
## Commit 规则
61+
62+
- 使用清晰的结构化前缀，例如 `feat:`、`fix:`、`docs:`、`refactor:`
63+
- 一次提交只做一类变更
64+
- 禁止使用含糊描述，例如 `update`、`change`
65+
66+
## Review 检查项
67+
68+
- 逻辑是否正确
69+
- 接口或数据结构是否与既有约定一致
70+
- 是否破坏已有行为
71+
- 文档是否需要同步更新
72+
73+
## 合并门禁
74+
75+
- `dev` 用于集成和联调，不通过检查不进入 `main`
76+
- `main` 只接收经过评审和验证的改动
77+
- 质量门禁不通过时，不允许例外合并

0 commit comments

Comments
 (0)