# eshop-class2-group1

**Repository Path**: grade24-fullstack-class2/eshop-class2-group1

## Basic Information

- **Project Name**: eshop-class2-group1
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 3
- **Created**: 2026-07-21
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 电子商城（E-Shop）暑期企业级综合项目实战

> 班级：24级软件技术2班　组别：1组　组名：E-Shop项目组

## 一、项目简介

本项目为软件技术专业暑期企业级综合项目实战，目标是以小组协作方式，在 **4 周** 内完成一个功能完整、可演示、可部署的 **电子商城系统**，全程模拟企业真实研发流程：需求分析 → 系统设计 → 编码实现 → 测试 → 部署 → 验收答辩。

### 在线访问（当前验收环境）

| 入口        | 地址                                                                                             | 用途                                     |
| ----------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| Web / PWA   | [https://8.148.246.97/eshop/](https://8.148.246.97/eshop/)                                       | 商城前台、个人中心与后台管理入口         |
| 业务 API    | `https://8.148.246.97/eshop-api/api/v1/`                                                         | REST API 基地址；具体端点以 OpenAPI 为准 |
| Liveness    | [https://8.148.246.97/eshop-api/health](https://8.148.246.97/eshop-api/health)                   | 检查 API 进程是否存活                    |
| Readiness   | [https://8.148.246.97/eshop-api/health/ready](https://8.148.246.97/eshop-api/health/ready)       | 检查 API 及 PostgreSQL 等依赖是否就绪    |
| OpenAPI 3.1 | [https://8.148.246.97/eshop-api/openapi/v1.json](https://8.148.246.97/eshop-api/openapi/v1.json) | 查看当前公开接口契约                     |
| 上传资源    | `https://8.148.246.97/eshop-api/uploads/`                                                        | 商品图片等上传资源的公开路径前缀         |

> 以上为课程验收环境的固定登记入口，不承诺长期在线；实际状态以 Liveness 与 Readiness 检查为准。E-Shop 固定挂载在 `/eshop/` 与 `/eshop-api/`，同一服务器的根路径 `/` 和根 `/api/` 属于另一套应用。构建、发布、验收、回滚及安全边界见[部署说明](docs/02-设计文档/部署说明.md)。仓库不提供默认管理员凭据，也不得记录密码、Token、私钥或数据库连接串。

## 二、小组成员与分工（模块负责制）

本项目采用 **模块负责制**：不按前后端分工，每人认领业务模块，独立负责该模块的 **数据库表 + 后端接口 + 前端页面** 完整链路。

| 姓名   | 学号       | 角色                           | 负责模块（全栈）                                                                                                                                         | 固定 Reviewer |
| ------ | ---------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| 林佳音 | 2444310212 | 组长/架构员、唯一集成人        | 公共基建与集成、鉴权基础设施与管线装配、测试/部署汇总、X02 后台操作日志、C09 数据统计看板；Coupon（C02）为扩展技术实现；登录与账号业务归 Identity 负责人 | 赵晓叶        |
| 陈源   | 2444310219 | 商品模块负责人                 | Catalog 商品模块（分类/列表/搜索/详情、库存与后台商品管理）+ X01 收藏与浏览历史                                                                          | 林佳音        |
| 赵晓叶 | 2444310237 | 用户交易主链负责人、备份集成人 | Identity + Cart + Ordering + Payment，以及 Shop、Settlement、CustomerService 扩展模块                                                                    | 陈源          |

> 分工规则详见 `docs/00-项目要求/项目要求.md` 第三节，模块难度权重与考核挂钩。
> 本组三人编制及上述合并分工已获指导教师批准，自项目创建日 **2026-07-22** 起生效；批准人姓名与确认渠道未在仓库材料中记录，见[三人组资格与分工确认记录](docs/04-会议记录/2026-07-22-三人组资格与分工确认.md)。
> 固定交叉 Review 关系按“作者 → Reviewer”记录为：林佳音 → 赵晓叶、陈源 → 林佳音、赵晓叶 → 陈源。作者不得自审，实际 Review 必须绑定候选提交并留痕。
> Coupon（C02）、Shop、Settlement、CustomerService 等为当前实现中的扩展模块；这里的负责人只表示技术维护所有权，不会把它们自动计入教师冻结的 F01～F13、X01、X02、C09 验收包。

## 三、技术栈（已冻结基线）

| 分层              | 技术选型                                                                      | 当前精确基线                                                            |
| ----------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Web / PWA         | Vue + strict TypeScript + Vite + Pinia + Vue Router                           | Vue 3.5.40、TypeScript 5.9.3、Vite 8.1.5、Pinia 3.0.4、Vue Router 4.6.4 |
| Windows 桌面端    | 共享 Vue Renderer + Tauri 2 薄壳                                              | Tauri JS API 2.11.1、CLI 2.11.4、Rust crate 2.11.5                      |
| Android 顾客端    | Kotlin + Jetpack Compose + Material 3                                         | AGP 9.2.1、内置 Kotlin 2.2.10、Compose BOM 2026.06.01、SDK 37           |
| JavaScript 工具链 | Node.js + pnpm                                                                | Node.js 24.14.0、pnpm 11.17.0                                           |
| 后端              | .NET 10 LTS + ASP.NET Core + EF Core + Npgsql                                 | SDK 10.0.302、ASP.NET Core/EF Core 10.0.10、Npgsql EF Core 10.0.3       |
| 数据库            | PostgreSQL                                                                    | 18.4                                                                    |
| Rust 工具链       | rustup + rustfmt + clippy + MSVC target                                       | Rust 1.97.1、`x86_64-pc-windows-msvc`                                   |
| 部署              | Nginx 静态资源与反向代理 + systemd 托管的自包含 ASP.NET Core API + PostgreSQL | Ubuntu 24.04、Nginx 1.24、linux-x64、PostgreSQL 18.4                    |

> 上表是当前仓库基线；可复现构建仍以 `global.json`、`frontend/package.json`、`frontend/pnpm-lock.yaml`、`frontend/src-tauri/Cargo.toml`、`frontend/src-tauri/Cargo.lock`、`rust-toolchain.toml`、`android/gradle/libs.versions.toml`、`android/gradle/wrapper/gradle-wrapper.properties`、`.postgresql-version`、`backend/Directory.Packages.props` 和 NuGet 锁文件为准。变更任一基线版本时必须在同一次独立修订中同步版本文件、锁文件、CI 和文档。

### 架构与协作基线

- [系统架构设计](docs/02-设计文档/系统架构设计.md)
- [技术栈与多 Agent 协作约束](docs/02-设计文档/技术栈与多Agent协作约束.md)
- [Android 原生客户端与 Jetpack Compose 技术路线](docs/02-设计文档/ADR-AND01-Android原生客户端与JetpackCompose技术路线.md)
- [部署说明](docs/02-设计文档/部署说明.md)

## 四、快速启动

### 4.1 先决条件

- .NET SDK 10.0.302
- Node.js 24.14.0
- pnpm 11.17.0
- PostgreSQL 18.4；运行真实数据库门禁还需要同版本 `psql`
- Android 构建需要 JDK 17、Android SDK Platform 37 与 Build Tools；仓库自带 Gradle Wrapper，不依赖全局 Gradle
- Git

Tauri 原生桌面构建还需要 Rust 1.97.1、`rustfmt`、`clippy`、`x86_64-pc-windows-msvc` target、Windows WebView2 Runtime 和 MSVC `cl`/`link` 构建工具。只启动 API 和 Web 前端时不需要这些桌面工具。

### 4.2 获取代码与安装依赖

```bash
git clone <repo-url>
cd eshop-class2-group1
git switch develop

dotnet restore backend/EShop.slnx --locked-mode
dotnet tool restore
pnpm --dir frontend install --frozen-lockfile

# 首次 Android 构建会由受校验的 Wrapper 获取锁定 Gradle 发行版
(cd android && ./gradlew --version)
```

### 4.3 准备数据库与本地配置

先在 PostgreSQL 18.4 中创建本地数据库和一个开发专用的非超级用户登录角色。下例使用 `eshop_dev` 同时完成本地 Migration 与 API 调试；它只是开发便利账号，不能照搬为生产运行账号。仓库根目录的 `.env.example` 是配置清单，不会由 .NET 自动载入；真实密码、JWT 密钥和 Refresh Token pepper 不得提交。

数据库连接有两个明确入口：

- `ESHOP_DATABASE_CONNECTION`：只供 `dotnet-ef` 设计时工厂读取，用于列出、生成、检查和应用 Migration。
- `ConnectionStrings__DefaultConnection`：供 API 运行时、健康检查和应用服务读取。

本地开发时二者通常指向同一个数据库和开发专用角色，但必须分别设置，不能假定一个变量会自动回填另一个变量。生产环境必须按[部署说明](docs/02-设计文档/部署说明.md)把 `eshop_migrator` 与最小权限 `eshop_app` 分开。

可在本地管理员会话中先创建开发角色与数据库；占位密码只应替换为本地 Secret，不得提交：

```sql
CREATE ROLE eshop_dev LOGIN PASSWORD 'replace-locally';
CREATE DATABASE eshop_dev OWNER eshop_dev;
```

仓库 `appsettings.json` 中的 `DefaultConnection` 只是指向 `127.0.0.1:1` 的明确不可达、非秘密占位值，用于让 liveness、OpenAPI 和无数据库测试场景能够启动，同时使 readiness 正确报告数据库未就绪。它不是可用数据库连接，也不包含真实凭据；本地开发和部署必须显式设置 `ConnectionStrings__DefaultConnection`，执行 EF 设计时命令还必须另行设置 `ESHOP_DATABASE_CONNECTION`。

PowerShell 示例：

```powershell
$databaseConnection = "Host=localhost;Port=5432;Database=eshop_dev;Username=eshop_dev;Password=replace-locally"

$env:ASPNETCORE_ENVIRONMENT = "Development"
$env:ASPNETCORE_URLS = "http://localhost:5080"
$env:ESHOP_DATABASE_CONNECTION = $databaseConnection
$env:ConnectionStrings__DefaultConnection = $databaseConnection
$env:Jwt__SigningKey = "replace-with-at-least-32-random-bytes"
$env:RefreshToken__Pepper = "replace-with-at-least-32-random-bytes"
$env:Cors__AllowedOrigins__0 = "http://localhost:5173"
```

Bash 示例：

```bash
database_connection='Host=localhost;Port=5432;Database=eshop_dev;Username=eshop_dev;Password=replace-locally'

export ASPNETCORE_ENVIRONMENT=Development
export ASPNETCORE_URLS=http://localhost:5080
export ESHOP_DATABASE_CONNECTION="$database_connection"
export ConnectionStrings__DefaultConnection="$database_connection"
export Jwt__SigningKey='replace-with-at-least-32-random-bytes'
export RefreshToken__Pepper='replace-with-at-least-32-random-bytes'
export Cors__AllowedOrigins__0=http://localhost:5173
```

`Jwt__Issuer`、`Jwt__Audience` 和 `RefreshToken__PepperVersion` 已有非敏感默认值；需要覆盖时按 `.env.example` 配置。生产环境必须使用密钥管理服务或部署平台 Secret。

### 4.4 显式应用 Migration、可选 Seed 并启动 API

应用程序启动时**不会**自动创建、迁移或 Seed 数据库。先从仓库根目录显式执行已经提交并审阅的 Migration：

```bash
# 先按 4.3 节设置 ESHOP_DATABASE_CONNECTION；设计时工厂不会读取运行时连接变量。
dotnet tool run dotnet-ef database update \
  --project backend/src/EShop.Infrastructure/EShop.Infrastructure.csproj \
  --startup-project backend/src/EShop.Api/EShop.Api.csproj \
  --context EShopDbContext
```

PowerShell 可使用同一条命令并把续行符改为反引号，或写成单行。

当前最新迁移 `20260810154915_AddCustomerServiceConversationGuards` 在既有 Settlement/Shop 约束之后，为客服 `SHOP`、`PRODUCT`、`ORDER` 三种上下文增加“每组至多一个 `OPEN` 会话”的部分唯一索引，并把消息内容上限从 1000 扩至 2000。迁移会先锁表并拒绝既有重复 `OPEN` 会话；发现重复数据时停止发布并人工修复，不能自动删除或合并历史记录。生产部署、预检、验证与回滚步骤见[部署说明](docs/02-设计文档/部署说明.md)。

如需课程演示用的 Catalog 基础数据，必须在 Migration 已全部应用后，以单独的一次性进程同时打开“命令参数 + 配置”双门：

```powershell
$env:CatalogSeed__MaterialRoot = "C:\reviewed-artifact\scripts\seed"
$env:CatalogSeed__Enabled = "true"
dotnet run --project backend/src/EShop.Api/EShop.Api.csproj -- --seed-catalog
$env:CatalogSeed__Enabled = "false"
Remove-Item Env:CatalogSeed__MaterialRoot
```

```bash
CatalogSeed__MaterialRoot=/path/to/reviewed-artifact/scripts/seed \
  CatalogSeed__Enabled=true \
  dotnet run --project backend/src/EShop.Api/EShop.Api.csproj -- --seed-catalog
```

运行前先用 `node scripts/seed/create-runtime-artifact.mjs <develop-seed-dir> <new-output-dir>` 从受审的 develop 未跟踪商品素材构建制品；父目录可以存在，但 `<new-output-dir>` 本身必须尚不存在。当前冻结制品包含 39 条本地商品物料、1158 张本地图片、图片总字节数 939296835；`mi-catalog.json` SHA-256 为 `ed1e0694ffcbe42aa381d0abda156906d4d890bbfc02ac28fdbf4a38c1e48c76`，`SHA256SUMS` SHA-256 为 `ac1eed5e5b022c5ecccbe186d45dcbc12b4304520a1fbd626caab4c13be86090`。制品必须同时包含 `ARTIFACT.json`、`SHA256SUMS`、`mi-catalog.json` 与 `media/`；运行时会逐文件校验清单、摘要、计数、路径和符号链接边界，任一缺失或漂移都 fail-closed。

只设置 `CatalogSeed__Enabled=true` 不会触发 Seed；只传 `--seed-catalog` 而未显式启用配置也会立即失败。命令先拒绝任何仍有待执行 Migration 的数据库，再合并内置 43 类/77 商品与物料 39 商品（31 个 SKU 重叠、8 个新增），干净数据库目标为 43 个分类、85 个商品、1158 张物料图片与 46 张内置商品生成封面，共约 1204 条 `product_image`。它只幂等补缺，不覆盖既有商品，也不创建账号、订单或支付；成功后进程直接退出，不启动 HTTP API 或后台任务。完整 PostgreSQL 18.4 首次、重复与失败恢复仍须以最终候选实测结果为准。

首次部署需要管理员时，必须在 Migration 全部应用后，通过一次性双门命令创建系统唯一管理员：

```powershell
$env:AdminProvisioning__Enabled = "true"
$env:AdminProvisioning__Username = "admin01"
$env:AdminProvisioning__Password = "Replace-Strong1!"
dotnet run --project backend/src/EShop.Api/EShop.Api.csproj -- --provision-admin
$env:AdminProvisioning__Enabled = "false"
Remove-Item Env:AdminProvisioning__Password
```

用户名须为 4-20 位 ASCII 字母或数字；密码须为 12-64 个字符，并包含 ASCII 大写、小写、数字和符号，且不得含空白或控制字符。命令拒绝待执行 Migration、已有管理员或重复用户名，在 Serializable 事务和表锁内创建账号；成功后直接退出，不启动 HTTP API 或后台任务。只设置配置或只传参数均不会创建账号，凭据必须来自 Secret，不能提交或写入日志。

重置既有管理员密码时使用安全脚本传入用户名，并通过交互方式输入新密码；脚本不会把密码放进命令行或日志，也不会加载启动 Profile：

```powershell
pwsh -NoProfile -File scripts/reset-admin.ps1 -Username admin01
```

确认 Migration 成功，并按需完成上述一次性 Seed 后，正常启动 API：

```bash
dotnet run --project backend/src/EShop.Api/EShop.Api.csproj --launch-profile http
```

API 地址为 `http://localhost:5080`。普通启动不会自动 Migration、Seed 或创建管理员，也没有默认管理员账号；不得把文档示例密码当成真实凭据。

### 4.5 启动 Web 前端

在另一个终端中执行：

```powershell
$env:VITE_API_BASE_URL = "http://localhost:5080"
pnpm --dir frontend dev:web
```

或：

```bash
VITE_API_BASE_URL=http://localhost:5080 pnpm --dir frontend dev:web
```

访问入口：

- Web：`http://localhost:5173`
- API liveness：`http://localhost:5080/health`
- API readiness：`http://localhost:5080/health/ready`
- OpenAPI 3.1 JSON：`http://localhost:5080/openapi/v1.json`

项目当前没有 Swagger UI。

Web 本地开发显式设置 `VITE_API_BASE_URL` 时直接访问该 API origin；不设置时则通过 Vite 的同源 `/eshop-api` 代理访问 `http://localhost:5080`。服务器构建不注入 `VITE_API_BASE_URL`，而是使用 `VITE_PUBLIC_BASE_PATH=/eshop/` 与 `VITE_WEB_API_PROXY_PATH=/eshop-api`，具体命令和 Nginx 路由见[部署说明](docs/02-设计文档/部署说明.md)。

### 4.6 启动或构建 Windows 桌面端

桌面开发复用已启动的本地 API。首次运行前确认 Rust/MSVC/WebView2 先决条件齐全：

```powershell
$env:VITE_API_BASE_URL = "http://localhost:5080"
pnpm --dir frontend tauri dev
```

`VITE_API_BASE_URL` 必须是 `scheme://host[:port]` 形式的纯 origin：不得包含 `/api/v1` 或其他路径、查询、片段、用户名或密码。共享请求层会统一追加 `/api/v1` 与端点路径，配置中不得重复携带。开发环境允许 loopback HTTP；`pnpm --dir frontend build:desktop` 只构建桌面 Renderer 静态产物，不编译 Rust，也不产生安装包。正式原生构建必须注入经评审的非 loopback HTTPS API origin：

```powershell
$env:VITE_API_BASE_URL = "https://api.example.com"
pnpm --dir frontend tauri build
```

仓库内的 Renderer 构建和平台 Mock 测试不能替代 Rust 编译、Windows 安装包构建及安装/启动/登录/API/退出/卸载冒烟；没有相应证据时必须明确记录“未验证”。

### 4.7 构建 Android 顾客端

Android 是独立的原生 Kotlin/Compose 工程，默认访问 `https://8.148.246.97/eshop-api/`。如需切换受控环境，只能用 `ESHOP_ANDROID_API_BASE_URL` 或 Gradle 属性 `eshopApiBaseUrl` 注入干净的 HTTPS 目录 URL；不得携带用户名、密码、查询或片段。

```powershell
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-17.0.18.8-hotspot"
$env:ANDROID_HOME = "$env:LOCALAPPDATA\Android\Sdk"
$env:ANDROID_SDK_ROOT = $env:ANDROID_HOME
Push-Location android
try {
  .\gradlew.bat --no-daemon --no-parallel --max-workers=1 `
    :app:testDebugUnitTest :app:lintDebug :app:assembleDebugAndroidTest :app:assembleDebug
} finally {
  Pop-Location
}
```

Debug APK 输出到 `android/app/build/outputs/apk/debug/app-debug.apk`。该命令会运行 JVM 测试、Lint、编译 instrumentation 测试 APK并构建 Debug APK；它不会运行 instrumentation、不会证明真机视觉，也不代表 release 签名或 Play 上架完成。对应技术与安全边界见 ADR-AND01。

### 4.8 测试与质量门禁

```bash
dotnet test backend/EShop.slnx --filter "Category!=PostgreSql"
pnpm --dir frontend test

# 完整基础门禁（需 Bash；会执行前后端静态检查、测试、构建、
# Chromium E2E、OpenAPI 生成与运行时契约对比）
bash .workflow/ci-quality-gate.sh
```

真实 PostgreSQL 18.4 门禁必须使用脚本要求的隔离、空、可丢弃数据库，并显式设置 `.workflow/ci-postgresql-18-4.sh` 顶部校验的全部 `ESHOP_CI_*` 变量；脚本会拒绝默认数据库、超级用户、版本不符或目标不明确的连接。配置完成后执行：

```bash
bash .workflow/ci-postgresql-18-4.sh
```

Tauri Windows 原生门禁应在 x64 MSVC Developer Shell 中设置非 loopback HTTPS `VITE_API_BASE_URL` 后执行：

```powershell
& .workflow/ci-tauri-windows.ps1
```

`.workflow/ci-tauri-windows.sh` 只是 Git Bash/MSYS/Cygwin 到上述 PowerShell 脚本的 Windows 包装器，不是 WSL/Linux 门禁。这些专项门禁需要对应数据库、浏览器或原生构建工具，不能用基础单元测试结果替代。

## 五、仓库目标目录结构

以下仅为方便浏览的当前目录摘要；省略某个路径不表示它不存在，也不表示可由任意 Agent 修改。可执行的完整目录、文件所有权和单写者清单以[技术栈与多 Agent 协作约束](docs/02-设计文档/技术栈与多Agent协作约束.md)第三、五节为唯一事实源。

```
├── README.md                              # 项目入口
├── global.json                            # 从仓库根锁定 .NET SDK 精确版本
├── contracts/
│   └── openapi/
│       ├── eshop-v1.yaml                  # 组合入口：引用模块片段
│       ├── modules/                       # 各业务模块的 OpenAPI 源片段
│       └── dist/
│           └── eshop-v1.yaml              # 受跟踪的单文件 bundle 生成物
├── frontend/
│   ├── src/
│   │   ├── app/                           # 启动、根路由、布局与组合入口
│   │   ├── modules/                       # 按业务模块组织的垂直切片
│   │   ├── platform/                      # Web / Tauri 平台端口与适配器
│   │   └── shared/                        # 经评审的跨模块通用能力
│   ├── src-tauri/                         # Tauri 2 桌面薄壳与权限配置
│   └── tests/                             # 前端集成与端到端测试
├── backend/
│   ├── Directory.Packages.props           # NuGet 依赖集中版本
│   ├── EShop.slnx
│   ├── src/
│   │   ├── EShop.Api/                     # 组合根与 HTTP 宿主
│   │   ├── EShop.Contracts/               # 跨模块应用契约
│   │   ├── EShop.SharedKernel/            # 最小共享内核
│   │   ├── EShop.Infrastructure/           # DbContext 与外部系统适配器
│   │   └── EShop.Modules.<Module>/        # Identity、Catalog、Cart 等模块项目
│   └── tests/                             # 后端单元与集成测试
├── android/                               # Kotlin + Jetpack Compose 顾客端
│   ├── app/src/main/                      # 原生 UI、网络、会话与 KeyStore 适配器
│   ├── app/src/test/                      # JVM 契约、会话与 ViewModel 回归
│   ├── app/src/androidTest/               # Compose / instrumentation 测试源码
│   └── gradle/                            # 版本目录与受校验 Wrapper
├── docs/
│   ├── 00-项目要求/                       # 教师发布，勿改
│   ├── 01-需求文档/
│   ├── 02-设计文档/
│   ├── 03-测试文档/
│   ├── 04-会议记录/
│   └── 05-总结答辩/
└── reports/
    ├── daily/姓名/                        # 每人每日一份，按姓名归档
    └── weekly/                            # 每组每周一份
```

## 六、关键时间节点（4 周）

| 阶段    | 时间             | 交付物                                                       |
| ------- | ---------------- | ------------------------------------------------------------ |
| 第 1 周 | 需求与设计       | 需求规格说明书、架构/数据库/接口设计                         |
| 第 2 周 | 核心功能开发     | 用户、商品模块可演示                                         |
| 第 3 周 | 完整功能开发     | 购物车、订单、支付（模拟）模块可演示；选做功能与挑战模块开发 |
| 第 4 周 | 测试、部署与答辩 | 测试报告、挑战模块压测/边界验证、部署上线、总结报告、答辩    |

## 七、Git 协作规范

以下规则为组长冻结规则，优先于旧计划中的通用分支示例：

1. 远端长期只保留 `main` 与 `develop` 两个分支。所有日常开发与文档整理都进入 `develop`；`main` 只接收已经完成整理和验证的 `develop` 快进晋升，不另建长期功能、修复、文档或临时分支。
2. 功能完成或 BUG 修复完成，并且相关测试确认通过后必须提交。一次完整修订记录就是一个提交；实现、测试、Migration、生成物及随实现变化的文档应在同一提交中闭环，不混入无关改动。
3. 测试确认完成后，必须在用户开始下一轮不相关改进之前先把该完成提交推送到远端 `develop`；需要发布或课程归档时，再将同一提交快进到 `main`，禁止强推改写共享历史。
4. 提交前必须确认当前分支为 `develop`，只暂存本次修订的精确文件，核对测试结果、作者信息和远端差异；禁止用空提交、伪造作者或拆分无意义提交制造过程记录。
5. 提交信息格式为 `<type>: <描述>`，type 使用 `feat`、`fix`、`refactor`、`docs`、`test` 或 `chore`。涉及代码的变更须保留交叉 Review 和测试留痕。

## 八、如何开始

1. 全组阅读 `docs/00-项目要求/` 下的全部文档。
2. 完成分工表、确定技术栈并填入本文件。
3. 按 `docs/01-需求文档/` 模板开始编写需求文档。
4. 每天下班前提交个人日报到 `reports/daily/姓名/`。