Project.Fengling.QoderVersion/PROJECT_DOCUMENTATION.md

# Fengling 项目完整文档

## 目录

1. [项目概述](#项目概述)
2. [技术栈](#技术栈)
3. [环境准备](#环境准备)
4. [后端开发](#后端开发)
5. [前端开发](#前端开发)
6. [第三方组件安装](#第三方组件安装)
7. [本地开发](#本地开发)
8. [测试](#测试)
9. [部署发布](#部署发布)
10. [CI/CD](#cicd)
11. [监控与维护](#监控与维护)
12. [常见问题](#常见问题)

---

## 项目概述

Fengling 是一个基于 Clean Architecture 和 DDD 设计的企业级应用系统，包含管理后台和 H5 会员端两个前端应用，以及一个功能完善的后端服务。

### 项目结构

```
Demo/
├── Backend/                 # 后端项目 (.NET 10)
│   ├── src/
│   │   ├── Fengling.Backend.Domain/        # 领域层
│   │   ├── Fengling.Backend.Infrastructure/ # 基础设施层
│   │   └── Fengling.Backend.Web/          # Web 层
│   ├── test/              # 测试项目
│   └── scripts/           # 基础设施脚本
├── Frontend/
│   ├── Fengling.Backend.Admin/  # 管理后台 (Vue 3 + TypeScript)
│   └── Fengling.H5/             # H5会员端 (Vue 3 + TypeScript)
├── docs/                  # 文档
└── tests/                 # 集成测试
```

---

## 技术栈

### 后端技术栈

| 组件 | 版本 | 用途 |
|------|------|------|
| .NET | 10.0 | 运行时框架 |
| ASP.NET Core | 10.0 | Web 框架 |
| Entity Framework Core | 10.0 | ORM 框架 |
| SQLite | 内置 | 开发数据库 |
| Redis | 7.2 | 缓存和分布式锁 |
| FastEndpoints | 最新 | 高性能 Web API 框架 |
| MediatR | 最新 | 命令查询中介者模式 |
| FluentValidation | 最新 | 模型验证 |
| CAP | 最新 | 分布式事务和事件总线 |
| Hangfire | 最新 | 后台任务调度 |
| Serilog | 最新 | 日志记录 |
| Swagger | 最新 | API 文档 |
| Prometheus | 最新 | 监控指标 |

### 前端技术栈

#### 管理后台 (Fengling.Backend.Admin)

| 组件 | 版本 | 用途 |
|------|------|------|
| Vue | 3.5.25 | 前端框架 |
| TypeScript | 5.9.3 | 类型系统 |
| Vite | 7.3.1 | 构建工具 |
| Tailwind CSS | 4.1.18 | CSS 框架 |
| shadcn-vue | 2.8.0 | UI 组件库 |
| Pinia | 3.0.4 | 状态管理 |
| Vue Router | 4.6.4 | 路由管理 |
| Axios | 1.13.5 | HTTP 客户端 |

#### H5会员端 (Fengling.H5)

| 组件 | 版本 | 用途 |
|------|------|------|
| Vue | 3.5.13 | 前端框架 |
| TypeScript | 5.7.2 | 类型系统 |
| Vite | 6.0.5 | 构建工具 |
| Tailwind CSS | 3.4.17 | CSS 框架 |
| Radix Vue | 1.9.11 | UI 组件库 |
| Pinia | 2.3.0 | 状态管理 |
| Vue Router | 4.5.0 | 路由管理 |
| Axios | 1.7.9 | HTTP 客户端 |

### 开发工具

| 工具 | 用途 |
|------|------|
| Visual Studio 2022 | 后端开发 IDE |
| VS Code | 前端开发 IDE |
| Docker Desktop | 容器化部署 |
| Node.js | 前端构建运行时 |
| pnpm | 前端包管理器 |
| Git | 版本控制 |

---

## 环境准备

### 系统要求

- **操作系统**: Windows 10/11, macOS 12+, Ubuntu 20.04+
- **内存**: 至少 8GB RAM (推荐 16GB)
- **磁盘空间**: 至少 20GB 可用空间

### 必需软件安装

#### 1. .NET SDK

```bash
# 下载并安装 .NET 10 SDK
# 访问 https://dotnet.microsoft.com/download/dotnet/10.0
# 或使用包管理器安装

# Windows (Chocolatey)
choco install dotnet-10.0-sdk

# macOS (Homebrew)
brew install dotnet

# Ubuntu/Debian
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y dotnet-sdk-10.0
```

验证安装：
```bash
dotnet --version  # 应显示 10.0.xxx
```

#### 2. Node.js 和 pnpm

```bash
# 安装 Node.js (推荐 LTS 版本 18.x 或 20.x)
# 访问 https://nodejs.org/

# 安装 pnpm (比 npm/yarn 更快的包管理器)
npm install -g pnpm

# 验证安装
node --version
pnpm --version
```

#### 3. Docker Desktop

```bash
# 下载并安装 Docker Desktop
# Windows/macOS: https://www.docker.com/products/docker-desktop/
# Linux: https://docs.docker.com/engine/install/

# 验证安装
docker --version
docker-compose --version
```

#### 4. Git

```bash
# 下载并安装 Git
# https://git-scm.com/downloads

# 配置 Git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

#### 5. IDE 配置

**Visual Studio 2022** (后端):
- 安装工作负载: ASP.NET 和 Web 开发
- 安装扩展: ReSharper (可选但推荐)

**VS Code** (前端):
```bash
# 推荐安装的扩展
code --install-extension bradlc.vscode-tailwindcss
code --install-extension Vue.volar
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension esbenp.prettier-vscode
code --install-extension ms-vscode.vscode-eslint
```

---

## 后端开发

### 项目结构说明

```
Backend/
├── src/
│   ├── Fengling.Backend.Domain/           # 领域层
│   │   ├── AggregatesModel/               # 聚合根
│   │   ├── DomainEvents/                  # 领域事件
│   │   └── IntegrationEvents/             # 集成事件
│   ├── Fengling.Backend.Infrastructure/   # 基础设施层
│   │   ├── EntityConfigurations/          # EF Core 配置
│   │   ├── Migrations/                    # 数据库迁移
│   │   └── Repositories/                  # 仓储实现
│   └── Fengling.Backend.Web/              # Web 层
│       ├── Application/                   # 应用服务
│       ├── Endpoints/                     # API 端点
│       ├── Services/                      # 业务服务
│       └── Program.cs                     # 程序入口
└── test/                                  # 测试项目
```

### 启动基础设施服务

#### 方式一：使用 Docker Compose (推荐)

```bash
# 进入脚本目录
cd Backend/scripts

# 启动基础设施 (Redis + MySQL)
docker-compose up -d

# 或选择其他数据库
docker-compose --profile sqlserver up -d    # SQL Server
docker-compose --profile postgres up -d     # PostgreSQL
docker-compose --profile kafka up -d        # Kafka (包含 Zookeeper)

# 查看运行状态
docker-compose ps

# 停止服务
docker-compose down

# 完全清理 (包括数据卷)
docker-compose down -v
```

#### 方式二：使用初始化脚本

```bash
# Windows PowerShell
cd Backend/scripts
.\init-infrastructure.ps1

# Linux/macOS
cd Backend/scripts
chmod +x init-infrastructure.sh
./init-infrastructure.sh

# 清理环境
./clean-infrastructure.sh        # Linux/macOS
.\clean-infrastructure.ps1       # Windows
```

#### 方式三：Aspire (如果启用)

```bash
# 如果项目启用了 Aspire
cd Backend/src/Fengling.Backend.AppHost
dotnet run
```

### 数据库配置

项目默认使用 SQLite 数据库进行开发，生产环境建议使用 MySQL/PostgreSQL。

#### 数据库连接配置

```json
// appsettings.json
{
  "ConnectionStrings": {
    "SQLite": "Data Source=fengling.db",
    "Redis": "localhost:6379"
  }
}
```

#### 数据库迁移

```bash
# 安装 EF Core 工具
dotnet tool install --global dotnet-ef

# 添加新的迁移
cd Backend/src/Fengling.Backend.Infrastructure
dotnet ef migrations add MigrationName

# 更新数据库
dotnet ef database update

# 查看迁移历史
dotnet ef migrations list
```

### 启动后端服务

```bash
# 进入 Web 项目目录
cd Backend/src/Fengling.Backend.Web

# 还原 NuGet 包
dotnet restore

# 构建项目
dotnet build

# 运行开发服务器 (端口 5511)
dotnet run

# 或使用 watch 模式 (文件更改时自动重启)
dotnet watch run
```

### API 文档访问

启动后端服务后，可通过以下地址访问：

- **Swagger UI**: http://localhost:5511/swagger
- **CAP Dashboard**: http://localhost:5511/cap
- **Hangfire Dashboard**: http://localhost:5511/hangfire
- **健康检查**: http://localhost:5511/health
- **监控指标**: http://localhost:5511/metrics
- **代码分析**: http://localhost:5511/code-analysis

### 代码生成器配置

项目提供丰富的代码片段模板，提高开发效率：

#### Visual Studio 配置

```powershell
# 自动安装代码片段
cd Backend/vs-snippets
.\Install-VSSnippets.ps1
```

#### VS Code 配置

代码片段已预配置在 `.vscode/csharp.code-snippets` 文件中。

#### 常用代码片段

| 快捷键 | 描述 | 生成内容 |
|--------|------|----------|
| `ncpcmd` | NetCorePal 命令 | ICommand 实现 |
| `ncpar` | 聚合根 | Entity 和 IAggregateRoot |
| `epp` | FastEndpoint | 完整端点实现 |
| `epreq` | 请求端点 | Endpoint<Request> |

---

## 前端开发

### 管理后台 (Fengling.Backend.Admin)

#### 项目初始化

```bash
# 进入项目目录
cd Frontend/Fengling.Backend.Admin

# 安装依赖
pnpm install

# 启动开发服务器 (端口 3000)
pnpm dev

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview
```

#### 环境变量配置

```bash
# 开发环境变量 (.env.development)
VITE_API_BASE_URL=http://localhost:5511
VITE_APP_TITLE=Fengling 管理后台

# 生产环境变量 (.env.production)
VITE_API_BASE_URL=https://your-production-api.com
VITE_APP_TITLE=Fengling 管理后台
```

#### 目录结构

```
Fengling.Backend.Admin/
├── src/
│   ├── api/           # API 接口定义
│   ├── components/    # 公共组件
│   ├── layouts/       # 页面布局
│   ├── pages/         # 页面组件
│   ├── router/        # 路由配置
│   ├── stores/        # 状态管理 (Pinia)
│   ├── styles/        # 全局样式
│   └── utils/         # 工具函数
├── public/            # 静态资源
└── components.json    # shadcn-vue 配置
```

### H5会员端 (Fengling.H5)

#### 项目初始化

```bash
# 进入项目目录
cd Frontend/Fengling.H5

# 安装依赖
pnpm install

# 启动开发服务器 (端口 3001)
pnpm dev

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview
```

#### 环境变量配置

```bash
# 开发环境变量 (.env.development)
VITE_API_BASE_URL=http://localhost:5511
VITE_APP_TITLE=Fengling 会员中心

# 生产环境变量 (.env.production)
VITE_API_BASE_URL=https://your-production-api.com
VITE_APP_TITLE=Fengling 会员中心
```

#### 目录结构

```
Fengling.H5/
├── src/
│   ├── api/           # API 接口定义
│   ├── components/    # 公共组件
│   ├── composables/   # Composition API 函数
│   ├── layouts/       # 页面布局
│   ├── pages/         # 页面组件
│   ├── router/        # 路由配置
│   ├── stores/        # 状态管理 (Pinia)
│   ├── styles/        # 全局样式
│   └── utils/         # 工具函数
├── public/            # 静态资源
└── components.json    # radix-vue 配置
```

### 前端开发规范

#### 代码规范

- 使用 TypeScript 严格模式
- 遵循 Composition API 风格
- 组件使用 PascalCase 命名
- 文件使用 kebab-case 命名
- API 接口使用 camelCase 命名

#### 代码质量工具

```bash
# ESLint 检查
pnpm lint

# Prettier 格式化
pnpm format

# TypeScript 类型检查
pnpm build  # 或 vue-tsc
```

#### UI 组件库

- **管理后台**: 使用 shadcn-vue (基于 Tailwind CSS)
- **H5会员端**: 使用 radix-vue (基于 Tailwind CSS)

添加新组件：
```bash
# shadcn-vue
npx shadcn-vue@latest add button

# radix-vue
# 直接从 @radix-ui/vue-icons 导入图标
```

---

## 第三方组件安装

### 后端组件

#### 数据库驱动

```xml
<!-- MySQL -->
<PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="8.0.2" />

<!-- PostgreSQL -->
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.4" />

<!-- SQL Server -->
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.8" />
```

#### 缓存和分布式锁

```xml
<!-- Redis (已包含) -->
<PackageReference Include="StackExchange.Redis" Version="2.8.16" />

<!-- 分布式锁 -->
<PackageReference Include="NetCorePal.Extensions.DistributedLocks.Redis" Version="1.0.0" />
```

#### 消息队列

```xml
<!-- RabbitMQ (已包含) -->
<PackageReference Include="DotNetCore.CAP.RabbitMQ" Version="8.3.0" />

<!-- Kafka -->
<PackageReference Include="DotNetCore.CAP.Kafka" Version="8.3.0" />
```

#### 对象存储

```xml
<!-- 阿里云 OSS -->
<PackageReference Include="Aliyun.OSS.SDK.NetCore" Version="2.13.0" />

<!-- AWS S3 -->
<PackageReference Include="AWSSDK.S3" Version="3.7.307.27" />

<!-- Azure Blob Storage -->
<PackageReference Include="Azure.Storage.Blobs" Version="12.21.2" />
```

#### 第三方服务集成

```xml
<!-- 微信支付 -->
<PackageReference Include="WeihanLi.WechatPay" Version="1.0.0" />

<!-- 支付宝 -->
<PackageReference Include="Alipay.AopSdk.Core" Version="4.4.0" />

<!-- 短信服务 -->
<PackageReference Include="Aliyun.Acs.Core" Version="4.5.15" />
<PackageReference Include="Aliyun.Acs.Dysmsapi" Version="2.2.3" />
```

### 前端组件

#### UI 组件库扩展

```bash
# 图标库
pnpm add lucide-vue-next    # 管理后台
pnpm add @radix-icons/vue   # H5会员端

# 表格组件
pnpm add @tanstack/vue-table

# 日期处理
pnpm add date-fns

# 工具库
pnpm add class-variance-authority clsx tailwind-merge
```

#### 状态管理和工具

```bash
# 状态管理 (已包含)
pnpm add pinia

# 路由 (已包含)
pnpm add vue-router

# HTTP 客户端 (已包含)
pnpm add axios

# 通知组件
pnpm add vue-sonner

# 实用工具
pnpm add @vueuse/core
```

#### 开发工具

```bash
# 类型检查
pnpm add -D vue-tsc typescript

# 代码格式化
pnpm add -D prettier eslint

# 构建工具 (已包含)
pnpm add -D vite @vitejs/plugin-vue

# CSS 框架 (已包含)
pnpm add -D tailwindcss autoprefixer postcss
```

### Docker 相关组件

#### 容器化部署

```dockerfile
# 后端 Dockerfile (已存在)
# Backend/src/Fengling.Backend.Web/Dockerfile

# 前端 Dockerfile (需要创建)
# Frontend/Fengling.Backend.Admin/Dockerfile
# Frontend/Fengling.H5/Dockerfile
```

#### Nginx 配置

```nginx
# nginx.conf
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        root /usr/share/nginx/html/admin;
        try_files $uri $uri/ /index.html;
    }
    
    location /h5/ {
        alias /usr/share/nginx/html/h5/;
        try_files $uri $uri/ /h5/index.html;
    }
    
    location /api/ {
        proxy_pass http://backend-service:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 本地开发

### 完整开发环境启动

#### 1. 启动基础设施

```bash
# 终端 1: 启动 Docker 服务
cd Backend/scripts
docker-compose up -d
```

#### 2. 启动后端服务

```bash
# 终端 2: 启动后端
cd Backend/src/Fengling.Backend.Web
dotnet watch run
```

#### 3. 启动前端服务

```bash
# 终端 3: 启动管理后台
cd Frontend/Fengling.Backend.Admin
pnpm dev

# 终端 4: 启动 H5会员端
cd Frontend/Fengling.H5
pnpm dev
```

### 开发环境访问地址

- **管理后台**: http://localhost:3000
- **H5会员端**: http://localhost:3001
- **后端 API**: http://localhost:5511
- **Swagger 文档**: http://localhost:5511/swagger
- **Redis**: localhost:6379
- **数据库**: fengling.db (SQLite 文件)

### 开发调试技巧

#### 后端调试

```bash
# 使用 Visual Studio 调试
# 设置断点 -> F5 启动调试

# 使用 VS Code 调试
# 创建 .vscode/launch.json 配置
```

#### 前端调试

```bash
# 浏览器开发者工具
# F12 打开 -> Console 查看日志
# Network 查看 API 请求
# Vue DevTools 查看组件状态

# VS Code 调试配置
# 创建 .vscode/launch.json
```

#### 数据库调试

```bash
# SQLite 浏览器工具
# 下载 DB Browser for SQLite

# 查看数据库内容
sqlite3 fengling.db
.tables
.schema table_name
SELECT * FROM table_name LIMIT 10;
```

---

## 测试

### 后端测试

#### 单元测试

```bash
# 运行所有单元测试
cd Backend
dotnet test

# 运行特定项目测试
dotnet test test/Fengling.Backend.Domain.Tests

# 生成测试覆盖率报告
dotnet test --collect:"XPlat Code Coverage"
```

#### 集成测试

```bash
# 运行集成测试 (包含 Testcontainers)
dotnet test test/Fengling.Backend.Web.Tests

# 运行特定测试
dotnet test --filter "FullyQualifiedName~YourTestName"
```

#### 测试项目结构

```
test/
├── Fengling.Backend.Domain.Tests/        # 领域层测试
├── Fengling.Backend.Infrastructure.Tests/ # 基础设施层测试
└── Fengling.Backend.Web.Tests/           # Web 层集成测试
```

### 前端测试

#### 单元测试

```bash
# 管理后台测试
cd Frontend/Fengling.Backend.Admin
pnpm test

# H5会员端测试
cd Frontend/Fengling.H5
pnpm test
```

#### E2E 测试

```bash
# 安装 Cypress
pnpm add -D cypress

# 运行 E2E 测试
pnpm run test:e2e
```

#### 测试最佳实践

1. **后端测试**:
   - 使用 Arrange-Act-Assert 模式
   - Mock 外部依赖
   - 测试边界条件和异常情况
   - 保持测试独立性

2. **前端测试**:
   - 组件测试使用 Vue Test Utils
   - 端到端测试使用 Cypress
   - 测试用户交互场景
   - 模拟 API 响应

---

## 部署发布

### 生产环境配置

#### 后端生产配置

```json
// appsettings.Production.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "SQLite": "Data Source=/app/data/fengling.db",
    "Redis": "redis-host:6379,password=your-password"
  },
  "AppConfiguration": {
    "Secret": "YourProductionSecretKeyHere!!!",
    "TokenExpiryInMinutes": 1440,
    "JwtIssuer": "FenglingBackend",
    "JwtAudience": "FenglingBackend"
  }
}
```

#### 前端生产配置

```bash
# 管理后台 .env.production
VITE_API_BASE_URL=https://api.yourdomain.com
VITE_APP_TITLE=Fengling 管理后台

# H5会员端 .env.production
VITE_API_BASE_URL=https://api.yourdomain.com
VITE_APP_TITLE=Fengling 会员中心
```

### Docker 部署

#### 后端 Docker 部署

```dockerfile
# Backend/src/Fengling.Backend.Web/Dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
WORKDIR /app
EXPOSE 80

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
# ... 构建步骤

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "Fengling.Backend.Web.dll"]
```

构建和运行：
```bash
# 构建镜像
cd Backend
docker build -t fengling-backend:latest -f src/Fengling.Backend.Web/Dockerfile .

# 运行容器
docker run -d \
  --name fengling-backend \
  -p 8080:80 \
  -e ASPNETCORE_ENVIRONMENT=Production \
  fengling-backend:latest
```

#### 前端 Docker 部署

创建前端 Dockerfile：

```dockerfile
# Frontend/Fengling.Backend.Admin/Dockerfile
FROM node:18-alpine AS build
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm
RUN pnpm install
COPY . .
RUN pnpm build

FROM nginx:alpine AS runtime
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

构建和运行：
```bash
# 构建管理后台
cd Frontend/Fengling.Backend.Admin
docker build -t fengling-admin:latest .

# 构建 H5会员端
cd Frontend/Fengling.H5
docker build -t fengling-h5:latest .

# 运行容器
docker run -d -p 3000:80 fengling-admin:latest
docker run -d -p 3001:80 fengling-h5:latest
```

### Kubernetes 部署 (推荐生产环境)

#### Helm Chart 结构

```
helm-chart/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── configmap.yaml
│   └── secret.yaml
└── README.md
```

#### 部署命令

```bash
# 添加 Helm 仓库
helm repo add fengling https://your-helm-repo.com

# 部署应用
helm install fengling-app fengling/fengling \
  --set image.tag=v1.0.0 \
  --set replicaCount=3 \
  --set service.type=LoadBalancer

# 升级应用
helm upgrade fengling-app fengling/fengling --set image.tag=v1.0.1

# 回滚
helm rollback fengling-app 1

# 卸载
helm uninstall fengling-app
```

### 云平台部署

#### Azure App Service

```bash
# 部署后端
az webapp deploy \
  --resource-group myResourceGroup \
  --name fengling-backend \
  --src-path ../Backend/src/Fengling.Backend.Web/bin/Release/net10.0/publish.zip

# 配置应用设置
az webapp config appsettings set \
  --resource-group myResourceGroup \
  --name fengling-backend \
  --settings ASPNETCORE_ENVIRONMENT=Production
```

#### AWS Elastic Beanstalk

```bash
# 初始化 EB 应用
eb init -p docker fengling-backend

# 部署应用
eb create fengling-backend-env
eb deploy
```

#### 阿里云容器服务

```bash
# 构建并推送镜像
docker build -t registry.cn-hangzhou.aliyuncs.com/your-namespace/fengling-backend:v1.0.0 .
docker push registry.cn-hangzhou.aliyuncs.com/your-namespace/fengling-backend:v1.0.0

# 使用阿里云 ACK 部署
kubectl apply -f k8s-manifests/
```

---

## CI/CD

### GitHub Actions 示例

```yaml
# .github/workflows/ci-cd.yml
name: CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    # 后端构建测试
    - name: Setup .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: 10.0.x
        
    - name: Restore dependencies
      run: dotnet restore
      
    - name: Build
      run: dotnet build --no-restore
      
    - name: Test
      run: dotnet test --no-build --verbosity normal
      
    # 前端构建测试
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'
        
    - name: Install pnpm
      run: npm install -g pnpm
      
    - name: Install frontend dependencies
      run: |
        cd Frontend/Fengling.Backend.Admin
        pnpm install
        cd ../Fengling.H5
        pnpm install
                
    - name: Build frontend
      run: |
        cd Frontend/Fengling.Backend.Admin
        pnpm build
        cd ../Fengling.H5
        pnpm build        

  deploy:
    needs: build-and-test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    
    steps:
    - name: Deploy to production
      run: |
        # 部署脚本
        echo "Deploying to production..."        
```

### Jenkins Pipeline

```groovy
pipeline {
    agent any
    
    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        
        stage('Backend Build') {
            steps {
                sh 'dotnet restore'
                sh 'dotnet build --configuration Release'
                sh 'dotnet test'
            }
        }
        
        stage('Frontend Build') {
            steps {
                dir('Frontend/Fengling.Backend.Admin') {
                    sh 'pnpm install'
                    sh 'pnpm build'
                }
                dir('Frontend/Fengling.H5') {
                    sh 'pnpm install'
                    sh 'pnpm build'
                }
            }
        }
        
        stage('Docker Build') {
            steps {
                sh 'docker build -t fengling-backend:${BUILD_NUMBER} .'
                sh 'docker push fengling-backend:${BUILD_NUMBER}'
            }
        }
        
        stage('Deploy') {
            steps {
                sh './deploy.sh ${BUILD_NUMBER}'
            }
        }
    }
}
```

### 部署策略

1. **蓝绿部署**: 准备两套环境，切换流量
2. **滚动更新**: 逐步替换实例
3. **金丝雀发布**: 小范围用户先行体验
4. **A/B 测试**: 对比不同版本效果

---

## 监控与维护

### 日志管理

#### 后端日志配置

```csharp
// Program.cs
builder.Host.UseSerilog((context, configuration) => configuration
    .ReadFrom.Configuration(context.Configuration)
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .WriteTo.File("logs/app-.txt", rollingInterval: RollingInterval.Day));
```

#### 结构化日志

```csharp
// 使用 Serilog 结构化日志
logger.Information("User {UserId} logged in from {IpAddress}", userId, ipAddress);
logger.Error(ex, "Failed to process order {OrderId}", orderId);
```

### 性能监控

#### Prometheus 指标

```csharp
// 内置指标端点
// http://localhost:5511/metrics

// 自定义指标
var counter = Metrics.CreateCounter("myapp_orders_total", "Total orders processed");
counter.Inc();
```

#### 应用性能监控 (APM)

```xml
<!-- 添加 Application Insights -->
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.22.0" />
```

### 健康检查

```csharp
// Program.cs
builder.Services.AddHealthChecks()
    .AddDbContextCheck<ApplicationDbContext>()
    .AddRedis(builder.Configuration.GetConnectionString("Redis"))
    .ForwardToPrometheus();
```

访问健康检查端点：
- http://localhost:5511/health

### 数据备份

#### 数据库备份脚本

```bash
#!/bin/bash
# backup-db.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups"
DB_FILE="fengling.db"

# SQLite 备份
cp "$DB_FILE" "$BACKUP_DIR/fengling_$DATE.db"

# 压缩备份
gzip "$BACKUP_DIR/fengling_$DATE.db"

# 删除 7 天前的备份
find "$BACKUP_DIR" -name "fengling_*.db.gz" -mtime +7 -delete
```

#### 自动化备份

```cron
# crontab -e
0 2 * * * /path/to/backup-db.sh  # 每天凌晨 2 点备份
```

### 故障排除

#### 常见问题诊断

1. **数据库连接失败**:
   ```bash
   # 检查连接字符串
   # 验证数据库服务状态
   docker-compose ps
   ```

2. **Redis 连接问题**:
   ```bash
   # 测试 Redis 连接
   redis-cli ping
   ```

3. **API 响应慢**:
   ```bash
   # 查看性能指标
   curl http://localhost:5511/metrics
   ```

4. **前端白屏**:
   ```bash
   # 检查控制台错误
   # 验证 API 连接
   # 检查环境变量配置
   ```

---

## 常见问题

### 开发环境问题

**Q: 后端启动时报数据库连接错误？**
A: 确保 Docker 服务已启动，并且数据库容器正在运行：
```bash
docker-compose ps
docker-compose up -d mysql redis
```

**Q: 前端无法连接到后端 API？**
A: 检查以下几点：
1. 后端服务是否正常运行 (http://localhost:5511/health)
2. Vite 代理配置是否正确
3. CORS 配置是否允许跨域请求

**Q: 缺少某些 NuGet 包？**
A: 还原包依赖：
```bash
dotnet restore
```

### 部署问题

**Q: Docker 镜像构建失败？**
A: 检查 Dockerfile 路径和上下文：
```bash
docker build -t app-name .  # 注意最后的点
```

**Q: 容器启动后立即退出？**
A: 查看容器日志：
```bash
docker logs container-name
```

**Q: 环境变量未生效？**
A: 确认环境变量传递方式：
```bash
# Docker run
docker run -e ENV_VAR=value image-name

# Docker Compose
environment:
  - ENV_VAR=value
```

### 性能优化

**Q: 如何优化数据库查询性能？**
A:
1. 添加适当的索引
2. 使用 Include 预加载关联数据
3. 分页查询大数据集
4. 启用查询缓存

**Q: 前端打包体积过大？**
A:
1. 启用代码分割
2. 移除未使用的依赖
3. 使用 CDN 加载大型库
4. 启用 gzip/brotli 压缩

### 安全考虑

**Q: 如何保护 API 接口？**
A:
1. 实施 JWT 身份验证
2. 添加请求频率限制
3. 验证所有输入参数
4. 启用 HTTPS
5. 配置 CORS 策略

**Q: 敏感信息如何管理？**
A:
1. 使用 Secret Manager (开发)
2. 环境变量 (生产)
3. Azure Key Vault/AWS Secrets Manager
4. 不在代码中硬编码密码

---

## 附录

### 有用的命令集合

#### 后端常用命令

```bash
# 项目管理
dotnet new sln                      # 创建解决方案
dotnet sln add **/*.csproj         # 添加项目到解决方案
dotnet restore                     # 还原 NuGet 包
dotnet build                       # 构建项目
dotnet run                         # 运行项目
dotnet watch run                   # 热重载运行

# 测试
dotnet test                        # 运行测试
dotnet test --filter "Category=Unit"  # 运行特定类别测试

# EF Core
dotnet ef migrations add Name      # 添加迁移
dotnet ef database update          # 更新数据库
dotnet ef database drop            # 删除数据库

# 发布
dotnet publish -c Release          # 发布项目
dotnet publish -r win-x64 --self-contained  # 自包含发布
```

#### 前端常用命令

```bash
# 依赖管理
pnpm install                       # 安装依赖
pnpm add package-name             # 添加依赖
pnpm remove package-name          # 移除依赖
pnpm update                       # 更新依赖

# 开发
pnpm dev                          # 启动开发服务器
pnpm build                        # 构建生产版本
pnpm preview                      # 预览构建结果

# 代码质量
pnpm lint                         # ESLint 检查
pnpm format                       # Prettier 格式化
pnpm type-check                   # TypeScript 检查
```

#### Docker 常用命令

```bash
# 镜像操作
docker build -t image-name .      # 构建镜像
docker images                     # 查看镜像列表
docker rmi image-name             # 删除镜像

# 容器操作
docker run -d -p 8080:80 image-name  # 运行容器
docker ps                         # 查看运行中的容器
docker ps -a                      # 查看所有容器
docker logs container-name        # 查看容器日志
docker exec -it container-name sh # 进入容器

# Compose
docker-compose up -d              # 后台启动服务
docker-compose down               # 停止服务
docker-compose logs               # 查看日志
```

### 参考资料

- [.NET 10 官方文档](https://learn.microsoft.com/zh-cn/dotnet/)
- [Vue 3 官方文档](https://vuejs.org/)
- [Tailwind CSS 文档](https://tailwindcss.com/)
- [Docker 官方文档](https://docs.docker.com/)
- [Kubernetes 官方文档](https://kubernetes.io/)

---

*文档最后更新时间: 2026年2月13日*
*版本: 1.0.0*