# full-stack demo

**Repository Path**: EloiseJulia/full-stack-demo

## Basic Information

- **Project Name**: full-stack demo
- **Description**: a demo project comprised of REACT + TS + .NET（C#）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-12-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 任务管理全栈应用

一个基于 React + TypeScript 前端和 .NET 8 后端的任务管理应用，使用 PostgreSQL 作为数据库。

## 技术栈

### 前端
- **React 18** - UI框架
- **TypeScript** - 类型安全
- **Vite** - 构建工具
- **Axios** - HTTP客户端
- **React Router** - 路由管理

### 后端
- **.NET 8** - Web API框架
- **Entity Framework Core** - ORM
- **PostgreSQL** - 数据库
- **JWT Bearer** - 身份认证
- **BCrypt** - 密码加密

## 功能特性

- ✅ 用户注册和登录（JWT认证）
- ✅ 任务列表展示（支持状态筛选）
- ✅ 任务的创建、编辑、删除
- ✅ 任务状态管理（待办/已完成）
- ✅ 任务优先级设置（低/中/高）
- ✅ 任务截止日期设置
- ✅ 响应式设计，支持移动端

## 企业级特性

本项目采用企业级开发最佳实践，展示生产环境就绪的代码质量：

- 🐳 **Docker 容器化** - 完整的 Docker 和 Docker Compose 配置，支持一键部署
- 🧪 **测试覆盖** - 后端 xUnit 单元测试，前端 Vitest 测试框架
- 🔍 **健康检查** - API 健康检查端点，监控服务状态
- 🛡️ **异常处理** - 全局异常处理中间件，统一错误响应格式
- 📝 **API 文档** - Swagger/OpenAPI 自动生成 API 文档
- 🔐 **安全性** - JWT 认证、密码加密、输入验证、CORS 配置
- 📦 **环境配置** - 生产环境配置管理，支持环境变量注入
- 🚀 **性能优化** - Nginx 反向代理、Gzip 压缩、静态资源缓存

详细信息请参考 [DOCKER.md](DOCKER.md)

## 项目结构

```
full-stack-demo/
├── frontend/                    # React + TypeScript 前端
│   ├── src/
│   │   ├── components/          # React组件
│   │   ├── pages/               # 页面组件
│   │   ├── services/            # API服务（axios）
│   │   ├── types/               # TypeScript类型定义
│   │   ├── utils/               # 工具函数（JWT处理等）
│   │   ├── test/                # 测试配置
│   │   └── App.tsx
│   ├── Dockerfile               # 前端 Docker 镜像配置
│   ├── nginx.conf               # Nginx 配置
│   ├── package.json
│   ├── vitest.config.ts         # Vitest 测试配置
│   └── vite.config.ts
├── backend/                     # .NET 8 Web API 后端
│   ├── Controllers/             # API控制器
│   ├── Models/                  # 数据模型
│   ├── Data/                    # DbContext和数据库配置
│   ├── Services/                # 业务逻辑服务
│   ├── DTOs/                    # 数据传输对象
│   ├── Middleware/              # 中间件（异常处理等）
│   ├── Migrations/              # 数据库迁移
│   ├── backend.Tests/           # 测试项目
│   ├── Dockerfile               # 后端 Docker 镜像配置
│   ├── Program.cs
│   └── appsettings.json
├── docker-compose.yml           # Docker Compose 配置
├── .dockerignore                # Docker 忽略文件
├── .env.example                 # 环境变量示例
├── DOCKER.md                    # Docker 部署文档
└── README.md
```

## 快速开始

### 方式一：Docker Compose（推荐）

最简单的方式，一键启动所有服务：

```bash
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env 文件设置数据库密码和 JWT 密钥

# 2. 启动所有服务
docker-compose up -d

# 3. 访问应用
# 前端: http://localhost:3000
# 后端 API: http://localhost:5000
# 健康检查: http://localhost:5000/health
# API 文档: http://localhost:5000/swagger (开发环境)
```

详细说明请参考 [DOCKER.md](DOCKER.md)

### 方式二：本地开发

#### 前置要求

1. **.NET 8 SDK** - [下载地址](https://dotnet.microsoft.com/download/dotnet/8.0)
   - macOS 用户推荐使用 Homebrew：`brew install dotnet@8`
   - 验证安装：`dotnet --version`（应该显示 8.x.x）
2. **Node.js 18+** - [下载地址](https://nodejs.org/)
3. **PostgreSQL 12+** - [下载地址](https://www.postgresql.org/download/)
   - macOS 用户：`brew install postgresql@14` 或 `brew install postgresql`
   - 启动服务：`brew services start postgresql@14`
4. **Entity Framework Core Tools** (用于数据库迁移)
   ```bash
   dotnet tool install --global dotnet-ef
   ```

### 数据库配置

1. 启动 PostgreSQL 服务
   - macOS: `brew services start postgresql@14` 或 `brew services start postgresql`
   - 验证服务：`pg_isready -h localhost`
2. 创建数据库（可选，迁移会自动创建）：
   ```sql
   CREATE DATABASE TaskManagerDb;
   ```
3. 更新 `backend/appsettings.json` 中的数据库连接字符串：
   ```json
   "ConnectionStrings": {
     "DefaultConnection": "Host=localhost;Port=5432;Database=TaskManagerDb;Username=postgres;Password=your_password"
   }
   ```
   - macOS 用户：如果使用本地信任认证，可以使用当前系统用户名，无需密码

#### 后端设置

1. 进入后端目录：
   ```bash
   cd backend
   ```

2. 恢复 NuGet 包：
   ```bash
   dotnet restore
   ```

3. 创建数据库迁移：
   ```bash
   dotnet ef migrations add InitialCreate
   ```

4. 应用数据库迁移：
   ```bash
   dotnet ef database update
   ```

5. 运行后端：
   ```bash
   dotnet run
   ```

后端 API 将运行在：
- HTTP: `http://localhost:5000`
- HTTPS: `https://localhost:5001`
- Swagger 文档: `https://localhost:5001/swagger`
- 健康检查: `http://localhost:5000/health`

#### 前端设置

1. 进入前端目录：
   ```bash
   cd frontend
   ```

2. 安装依赖：
   ```bash
   npm install
   ```

3. 创建环境变量文件（可选）：
   创建 `frontend/.env.local` 文件：
   ```env
   VITE_API_BASE_URL=http://localhost:5000
   ```

4. 运行前端开发服务器：
   ```bash
   npm run dev
   ```

5. 运行测试（可选）：
   ```bash
   npm test
   ```

前端应用将运行在 `http://localhost:5173`（Vite默认端口）

#### 运行测试

**后端测试**：
```bash
cd backend
dotnet test
```

**前端测试**：
```bash
cd frontend
npm test
```

## API 文档

### 认证接口

#### 注册
- **URL**: `POST /api/auth/register`
- **请求体**:
  ```json
  {
    "username": "string (3-20字符, 字母数字下划线)",
    "email": "string (有效邮箱格式)",
    "password": "string (至少8字符, 包含字母和数字)"
  }
  ```
- **响应**: 
  ```json
  {
    "token": "JWT Token",
    "userId": 1,
    "username": "string",
    "email": "string"
  }
  ```

#### 登录
- **URL**: `POST /api/auth/login`
- **请求体**:
  ```json
  {
    "usernameOrEmail": "string",
    "password": "string"
  }
  ```
- **响应**: 同注册接口

### 任务接口（需要JWT认证）

所有任务接口都需要在请求头中包含：
```
Authorization: Bearer {token}
```

#### 获取任务列表
- **URL**: `GET /api/tasks`
- **查询参数**:
  - `status` (可选): `0` (待办) 或 `1` (已完成)
- **响应**: 
  ```json
  [
    {
      "id": 1,
      "title": "string",
      "description": "string",
      "priority": 0,  // 0=低, 1=中, 2=高
      "dueDate": "2024-01-01T00:00:00Z",
      "status": 0,  // 0=待办, 1=已完成
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
  ```

#### 获取单个任务
- **URL**: `GET /api/tasks/{id}`

#### 创建任务
- **URL**: `POST /api/tasks`
- **请求体**:
  ```json
  {
    "title": "string (必填, 1-100字符)",
    "description": "string (可选, 最多500字符)",
    "priority": 0,  // 0=低, 1=中, 2=高
    "dueDate": "2024-01-01"  // 可选, ISO日期格式
  }
  ```

#### 更新任务
- **URL**: `PUT /api/tasks/{id}`
- **请求体**: 同创建任务

#### 删除任务
- **URL**: `DELETE /api/tasks/{id}`

#### 更新任务状态
- **URL**: `PATCH /api/tasks/{id}/status`
- **请求体**:
  ```json
  {
    "status": 0  // 0=待办, 1=已完成
  }
  ```

## 数据库设计

### Users 表
- `Id` (int, 主键)
- `Username` (string, 唯一索引)
- `Email` (string, 唯一索引)
- `PasswordHash` (string, BCrypt加密)
- `CreatedAt` (DateTime)

### Tasks 表
- `Id` (int, 主键)
- `Title` (string, 必填)
- `Description` (string, 可选)
- `Priority` (enum: Low=0, Medium=1, High=2)
- `DueDate` (DateTime?, 可选)
- `Status` (enum: Pending=0, Completed=1)
- `UserId` (int, 外键, 索引)
- `CreatedAt` (DateTime)
- `UpdatedAt` (DateTime)

**索引**:
- `Users.Username` (唯一索引)
- `Users.Email` (唯一索引)
- `Tasks.UserId` (索引)
- `Tasks.Status` (索引)
- `Tasks.UserId + Status` (复合索引)

## 安全特性

- ✅ 密码使用 BCrypt 加密存储
- ✅ JWT Token 认证
- ✅ API 请求需要认证（除注册/登录外）
- ✅ 用户只能访问自己的任务
- ✅ 输入验证（前后端双重验证）
- ✅ CORS 配置（允许前端域名）

## 开发说明

### 后端开发

- 使用 Entity Framework Core 进行数据库迁移
- JWT 配置在 `appsettings.json` 中
- 所有任务 API 都需要 `[Authorize]` 特性

### 前端开发

- 使用 Vite 作为构建工具
- API 基础 URL 可通过环境变量 `VITE_API_BASE_URL` 配置
- JWT Token 存储在 localStorage 中
- 使用 React Router 进行路由管理

## 常见问题

### 数据库连接失败
- 检查 PostgreSQL 服务是否启动
  - macOS: `brew services list` 查看服务状态
  - 验证服务：`pg_isready -h localhost`
- 验证 `appsettings.json` 中的连接字符串是否正确
- 确认数据库用户有创建数据库的权限
- macOS 用户：如果使用本地信任认证，确保用户名正确

### 前端无法连接后端
- 检查后端是否正在运行
- 确认 CORS 配置允许前端域名
- 检查 `VITE_API_BASE_URL` 环境变量

### JWT Token 过期
- Token 默认过期时间为 60 分钟（可在 `appsettings.json` 中配置）
- Token 过期后需要重新登录

### .NET SDK 未找到（macOS）
确保已安装并添加到 PATH：
```bash
export PATH="/opt/homebrew/share/dotnet:$PATH"
# 或添加到 ~/.zshrc 使其永久生效
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！