# eshop-class1-group6

**Repository Path**: wuhfly/eshop-class1-group6

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 9
- **Created**: 2026-07-22
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

> 班级：____ 组号：____ 组名：____

## 一、项目简介

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

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

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

| 姓名 | 学号 | 角色 | 负责模块（全栈） |
|------|------|------|------------------|
|      |      | 组长/架构员 | 项目脚手架、登录鉴权、统一响应、公共组件、集成联调 |
|      |      | 模块负责人 | 用户模块（注册/登录/个人信息/地址 + 后台用户管理） |
|      |      | 模块负责人 | 商品模块（分类/列表/搜索/详情 + 后台商品管理） |
|      |      | 模块负责人 | 购物车模块（加购/改数量/删除/结算） |
|      |      | 模块负责人 | 订单 + 支付模块（下单/订单状态/模拟支付 + 后台订单管理） |
|      |      | 模块负责人 | 测试 + 部署 + 选做/挑战模块 |

> 分工规则详见 `docs/00-项目要求/项目要求.md` 第三节，模块难度权重与考核挂钩。
> 4 人组时，测试与部署职责分摊到各模块负责人，选做功能由认领者负责。

## 三、技术栈（各组自选，确定后填写）

| 分层 | 技术选型 | 版本 |
|------|----------|------|
| 前端 | Vue 3 + Vite + TypeScript + Element Plus + Pinia + Axios | 见 `frontend/package.json` |
| 后端 | C# + ASP.NET Core Web API | .NET 10 |
| 数据库 | MySQL | 8.x |
| 数据访问 | MySqlConnector 轻量 SQL 访问 | 见 `backend/src/Eshop.Api/Eshop.Api.csproj` |
| 鉴权 | HttpOnly Cookie JWT + PBKDF2 密码哈希 | 已接入登录鉴权、CSRF 与角色权限 |
| 接口文档 | Swagger / OpenAPI | ASP.NET OpenAPI |
| 配置 | `appsettings.json` + 本地配置模板 | 见 `backend/src/Eshop.Api/appsettings.Local.example.json` |
| 日志 | ASP.NET Core Logging | 内置 |
| 部署 | Docker Compose | 见 `docker-compose.yml` |

## 四、仓库目录结构

```
├── README.md                 # 项目说明（本文件）
├── docs/                     # 项目文档
│   ├── 00-项目要求/          # 项目要求、验收标准、评分标准（教师发布，勿改）
│   ├── 01-需求文档/          # 需求规格说明书
│   ├── 02-设计文档/          # 架构设计、数据库设计、接口设计
│   ├── 03-测试文档/          # 测试计划、测试报告
│   ├── 04-会议记录/          # 小组会议纪要
│   ├── 05-总结答辩/          # 项目总结报告、答辩材料
│   └── 06-模块实现说明/      # 每个模块的技术栈说明与实现记录
├── reports/                  # 日报周报
│   ├── daily/                # 日报（每人每天一份）
│   └── weekly/               # 周报（每组每周一份，组长汇总）
├── frontend/                 # Vue 前端代码
├── backend/                  # ASP.NET Core 后端代码与 SQL
├── AGENT.md                  # 小组成员使用 AI 前必读规范
├── .env.example              # 环境变量示例
├── docker-compose.yml        # MySQL + ASP.NET Core API 容器编排
└── global.json               # .NET SDK 版本锁定
```

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

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

## 六、Git 协作规范

1. 主分支 `main` 只存放可运行代码，禁止直接 push。
2. 功能开发使用 `feature/功能名` 分支，完成后经组长 Code Review 合并。
3. 提交信息格式：`<type>: <描述>`，type 取值：`feat` `fix` `refactor` `docs` `test` `chore`。
4. **每人每天至少一次有效提交**，提交记录将作为个人考核依据。
5. **交叉 Code Review**：每人的功能分支由相邻模块负责人审查后方可合并（审查人在合并说明中留名）。

## 七、如何开始

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

## 八、本地启动

### 后端

先启动 MySQL：

```bash
docker compose up -d mysql
```

然后启动后端 API：

```bash
cd backend
dotnet restore Eshop.slnx
dotnet build Eshop.slnx
dotnet run --project src/Eshop.Api/Eshop.Api.csproj
```

本地开发默认连接 `appsettings.Development.json`。如需连接 Docker Compose 中的 MySQL，可设置连接串：

```powershell
$env:ConnectionStrings__DefaultConnection="Server=localhost;Port=3306;Database=eshop;User=root;Password=change_me;"
$env:Jwt__SigningKey="replace-with-at-least-32-random-characters"
$env:PaymentCallback__SigningKey="replace-with-another-32-character-random-secret"
dotnet run --project src/Eshop.Api/Eshop.Api.csproj
```

后端健康检查：

```text
GET http://localhost:5213/api/health
```

OpenAPI 地址：

```text
http://localhost:5213/swagger
```

### 前端

```bash
cd frontend
npm install
npm run dev
```

前端默认地址：

```text
http://localhost:5173
```

Live 联调必须显式启用真实 API，不能依赖 mock 回退：

```powershell
$env:VITE_DATA_MODE="live"
npm run dev
```

生产与 Live 环境不提供公开演示账号。管理员由 `BootstrapAdmin__Username` 和
`BootstrapAdmin__Password` 在启动时引导创建；如需本地商家账号，同时配置
`BootstrapMerchant__Username` 和 `BootstrapMerchant__Password`。账号配置只放在本机 `.env`，不要提交到 Git。

### Docker Compose

拉取仓库后的推荐启动方式（Windows PowerShell）：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start-local.ps1
```

脚本会自动生成本机 `.env`、启动 Docker、补齐商品、安装前端依赖并启动商城。首次运行会在终端显示本机随机生成的管理员和商家密码；`.env` 已被 Git 忽略，不要手动提交。

```bash
docker compose up --build
```

若本机 `8080` 被其他项目占用，可临时映射为 `8082`：

```powershell
$env:ESHOP_API_PORT="8082"
docker compose up --build
```

`db-migrate` 每次启动都会补齐缺失的分类和商品，但不会覆盖已有商品的价格、库存、状态或描述，
因此组员拉取代码后不需要共享你的 MySQL 数据卷。首次使用时先复制 `.env.example` 为 `.env` 并填写本机密码、JWT 密钥和引导账号。
不要使用 `docker compose down -v`，除非确认可以删除本机数据库数据。

局域网完整验收使用前端 Nginx 同源入口：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start-acceptance.ps1 -Build
```

默认访问 `http://本机IPv4:8088`。该模式只用于受信任局域网 HTTP 验收；生产必须在 HTTPS 反向代理后运行，并设置 `Auth__CookieSecure=true`。

## 九、AI 使用要求

全组成员使用 AI 前必须阅读 `AGENT.md`。制作任何模块时，必须在 `docs/06-模块实现说明/` 下维护对应模块说明，回答：

1. 这个模块用了什么技术栈？
2. 为什么使用这个技术栈？
3. 是否还有其他实现方式？