# eshop-class1-group7

**Repository Path**: grade24-fullstack-class1/eshop-class1-group7

## Basic Information

- **Project Name**: eshop-class1-group7
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

E-Shop 是一个单店 B2C 教学项目，正式交付边界为 **PC Web + 后端 Web API**。
购物端、商家端和管理端均通过浏览器接入同一套业务模块、接口契约和
PostgreSQL 事实源。Electron 与 Android 只属于后续扩展，不在当前骨架中创建。

当前仓库已经从旧模板重新建立前后端与运行基础设施，但**尚未实现业务模块**：
没有业务实体、业务接口、业务页面、业务 Worker、数据库 Migration 或种子数据，
也不以模拟成功响应冒充完成度。

## 唯一实施基线

需求、流程、接口和数据库必须按以下事实源向代码派生，不能让流程反向追随现有
接口或旧骨架：

- [需求规格说明书](docs/01-需求文档/需求规格说明书.md)
- [业务流程](docs/02-设计文档/process/)
- [接口设计](docs/02-设计文档/interface/接口设计.md)
- [数据库设计](docs/02-设计文档/数据库设计.md)

跨技术栈名称统一遵守
[命名规范](docs/02-设计文档/命名规范.md)。`docs/00-项目要求/` 是教师发布的
只读基线。

## 技术与版本基线

| 范围 | 技术 | 当前锁定版本 |
|---|---|---|
| PC Web | Vue、Vue Router、Pinia、Axios、Element Plus | `3.5.40`、`5.2.0`、`4.0.2`、`1.18.1`、`2.14.3` |
| 前端构建与测试 | Node.js、npm、TypeScript、Vite、Vitest、Playwright | `24.15.0`、`11.12.1`、`6.0.3`、`8.1.5`、`4.1.10`、`1.62.0` |
| 后端 | .NET SDK、ASP.NET Core、EF Core、Npgsql | `10.0.301`、`10.0.10`、`10.0.10`、`10.0.3` |
| 本地编排 | .NET Aspire | `13.4.4` |
| 运行依赖 | PostgreSQL、Redis、RabbitMQ、SeaweedFS | `18.4`、`8.2.7`、`4.3.4`、`4.29` |
| 入口与部署 | Docker Compose、Nginx | Compose v2+、Nginx `1.28.0` |

NuGet 使用中央版本和每项目锁文件；npm 使用精确版本和
`package-lock.json`。不得改回浮动版本或 `latest` 镜像。

## 仓库结构

```text
.
├─ backend/
│  ├─ src/
│  │  ├─ Mall.Domain/
│  │  ├─ Mall.Application/
│  │  ├─ Mall.Infrastructure/
│  │  ├─ Mall.Api/
│  │  ├─ Mall.Worker/
│  │  ├─ Mall.Migrator/
│  │  └─ Mall.AppHost/
│  └─ tests/
│     ├─ Mall.UnitTests/
│     └─ Mall.IntegrationTests/
├─ frontend/
│  ├─ src/
│  │  ├─ api/
│  │  ├─ components/
│  │  ├─ router/
│  │  ├─ styles/
│  │  └─ types/
│  └─ tests/
│     ├─ unit/
│     └─ e2e/
├─ deploy/
│  ├─ nginx/
│  └─ postgres/
├─ scripts/
├─ compose.yaml
├─ docs/
└─ reports/
```

不提前创建十个空业务模块项目或目录。首个真实用例出现时，再按模块纵向加入
数据库映射、应用用例、API、前端和测试，并使用显式依赖与端点注册。

## 开发实施入口

业务实现前必须阅读：

- [开发实施手册](docs/02-设计文档/开发实施手册.md)：从 M/F/X/C、Axxx、DBxxx
  到真实目录、注册、Migration、测试和完成定义；
- 目标路径上的模块级 `AGENTS.md`；
- 对应模块的冻结需求、流程、接口和数据库完整定义。

一个功能的标准纵向交付链为：

```text
需求与验收
→ 业务流程、状态、异常和模块交接
→ Axxx 与 DBxxx 实施清单
→ Domain 与 Application
→ Infrastructure、EF Mapping 与事务
→ Endpoint、ProblemDetails 与运行时 OpenAPI
→ 同一 PC Web 中的页面、路由、真实 API 和交互状态
→ 单元、集成、组件、浏览器及高风险专项测试
→ 可复现验收证据
```

六人并行开发不得按成员到岗顺序或前后端层次任意开工。开始业务任务前，先按
[开发实施手册 6.0](docs/02-设计文档/开发实施手册.md#60-全项目开发批次与阶段门禁)
确认当前批次、上游公开契约、允许并行范围和退出门禁，再执行上述单功能纵向链。
统一 Migration、Seed、全链路联调和验收分别在对应全局批次集中完成。

“最小”只表示不扩大无关文件和无关模块范围，不表示缩减已确认功能。用户要求
完整交付某个功能时，所有适用正常流程、异常、权限、状态、数据、接口、PC Web
和测试都必须闭环；只完成 Controller、页面、实体或测试中的一层只能标记为
“部分实现”。

购物端、商家端和管理端属于同一个 PC Web 应用，不创建三个前端工程。后端除
Web API 外，还包括 Worker、一次性 Migrator 和开发 AppHost。数据库首次落地
必须等 44 张表及跨模块约束完整映射后统一生成唯一 `InitialEshopSchema`，不得
由个人模块提交零散初始 Migration。

## 本机开发

### 后端

```powershell
cd backend
dotnet restore Mall.sln --locked-mode
dotnet build Mall.sln -c Release --no-restore
dotnet test Mall.sln -c Release --no-build
dotnet run --project src/Mall.Api/Mall.Api.csproj
```

Development 环境提供：

- OpenAPI：`http://localhost:5000/openapi/v1.json`
- Swagger UI：`http://localhost:5000/swagger`
- A506：`http://localhost:5000/health/live`
- A507：`http://localhost:5000/health/ready`

A507 当前应返回 `503 notReady`，因为完整 `InitialEshopSchema` 尚不存在。这是
真实流量门禁，不得改成固定 200。

### 前端

```powershell
cd frontend
npm ci
npm run dev
```

前端状态页只证明 Vue 工程可挂载，不代表任何商城功能已经完成。业务模块不得
依赖该页面或模拟数据。

## 质量门禁

一键验证：

```powershell
./scripts/Verify-Repository.ps1
```

已安装依赖且不运行浏览器时：

```powershell
./scripts/Verify-Repository.ps1 -SkipInstall -SkipBrowser -SkipContainers
```

门禁包含：

- 冻结需求、流程、接口和数据库基线防改；
- NuGet 锁定还原、格式、Release 构建与测试；
- npm 锁定安装、Prettier、ESLint、类型检查、单测、构建和官方安全审计；
- Chromium 冒烟；
- Compose 必需服务、同版本双 API、端口暴露和非 `latest` 检查；
- PostgreSQL、Redis、RabbitMQ、SeaweedFS 精确标签与摘要拉取，以及五个交付
  镜像的实际构建和非 root 检查；API 及两层 Nginx 另做只读根文件系统运行检查；
- Git 空白与冲突标记检查。

Gitee Go 启用后会由平台生成 `.workflow` 文件；流水线应直接调用上述脚本。
在平台尚未生成工作流前，不在仓库中编造无法验证的 CI 配置。

## 容器基础设施

首次生成仅保存在本机、不会输出到终端的随机 Secret：

```powershell
./scripts/Initialize-LocalEnvironment.ps1
```

本地入口默认只监听 `127.0.0.1:8080`。Redis、RabbitMQ 和对象写入能力开关
默认保持 `false`，因为对应业务缓存、可靠事件与对象用例尚未实现；以后只能由
相应纵向模块在实现与验证完成后通过 `.env` 开启，不能靠修改 A507 伪装可用。

只启动 PostgreSQL、Redis、RabbitMQ 与 SeaweedFS：

```powershell
./scripts/Start-Infrastructure.ps1
```

停止全部 Compose 服务并保留数据卷：

```powershell
./scripts/Stop-Infrastructure.ps1
```

`compose.yaml` 已定义 Nginx、前端、双 API、Worker、Migrator 和四个共享依赖。
但是，在完整数据库映射与 `InitialEshopSchema` 到位前，Migrator 会失败并阻止
API/Worker/Nginx 开放，这符合 C10 冻结流程。更多边界见
[部署说明](deploy/README.md)。

## Git 协作

`master` 是稳定发布分支，`dev` 是日常集成分支，均禁止直接开发和直接 Push。
普通任务从最新 `dev` 创建短生命周期分支，经真实验证与至少一名成员交叉
Review 后通过 PR 合入。完整规则见
[Git 团队协作流程](docs/02-设计文档/Git团队协作流程.md)。