🌊 Underwater Image Processing System (UIPS)

水下图像处理系统 - 基于 .NET 8 的高性能模块化单体应用

📖 项目简介

UIPS (Underwater Image Processing System) 是一个专为水下图像数据管理与处理设计的集成化解决方案。项目采用 模块化单体架构 (Modular Monolith)，在保持单体应用部署便捷性的同时，通过严格的模块边界实现高内聚、低耦合的代码组织。

核心特性

🎯 模块化单体架构 - 清晰的代码边界，易于维护与扩展
🔐 JWT 身份认证 - 基于 Token 的安全认证机制
� 类型安全通信 - 前后端通过 DTO 实现强类型协作
🎨 现代化 UI - Material Design 风格的深海主题界面
🚀 高性能存储 - SQLite 数据库 + 文件系统混合存储
🔄 自动化 CI/CD - GitHub Actions 持续集成与部署

🏗️ 技术架构

架构模式

┌─────────────────────────────────────────────────────────┐
│                    UIPS.Client (WPF)                    │
│  ┌──────────┐   ┌──────────┐   ┌────────────────────┐   │
│  │  Views   │   │ViewModels│   │ Services (Refit)   │   │
│  └──────────┘   └──────────┘   └────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                          │ HTTPS/REST
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   UIPS.API (ASP.NET Core)               │
│  ┌────────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Controllers│  │ Services │  │   DTOs   │  │ Models │ │
│  └────────────┘  └──────────┘  └──────────┘  └────────┘ │
│                          │                              │
│                          ▼                              │
│              ┌────────────────────┐                     │
│              │  EF Core + SQLite  │                     │
│              └────────────────────┘                     │
└─────────────────────────────────────────────────────────┘

技术栈

后端 (Backend)

框架: ASP.NET Core 8.0 Web API
ORM: Entity Framework Core 8.0
数据库: SQLite 3
认证: JWT Bearer Authentication
密码加密: BCrypt.Net-Next 4.0.3
API 文档: Swashbuckle (Swagger/OpenAPI)

前端 (Frontend)

框架: WPF (.NET 8.0-windows)
MVVM: CommunityToolkit.Mvvm 8.4.0
UI 库: MaterialDesignThemes 5.3.0
HTTP 客户端: Refit 8.0.0
依赖注入: Microsoft.Extensions.Hosting 10.0.0

开发工具

IDE: Visual Studio 2022 (v17.8+)
版本控制: Git + GitHub
CI/CD: GitHub Actions

📂 项目结构

解决方案组织

UnderwaterImageProcessingSystem/
├── src/
│   ├── UIPS.API/                    # 后端 API 项目
│   │   ├── Controllers/             # API 控制器
│   │   │   ├── AuthController.cs    # 认证接口
│   │   │   └── ImageController.cs   # 图像管理接口
│   │   ├── DTOs/                    # 数据传输对象
│   │   │   ├── LoginRequestDto.cs
│   │   │   ├── LoginResponseDto.cs
│   │   │   ├── ImageDto.cs
│   │   │   ├── ImageResponseDto.cs
│   │   │   ├── PaginatedRequestDto.cs
│   │   │   └── PaginatedResult.cs
│   │   ├── Models/                  # 数据库实体模型
│   │   ├── Services/                # 业务逻辑服务
│   │   ├── Migrations/              # EF Core 迁移文件
│   │   ├── Program.cs               # 应用入口
│   │   └── appsettings.json         # 配置文件
│   │
│   └── UIPS.Client/                 # 前端 WPF 项目
│       ├── Views/                   # XAML 视图
│       ├── ViewModels/              # 视图模型
│       ├── Services/                # HTTP 服务 (Refit)
│       ├── Converters/              # 值转换器
│       ├── Resources/               # 样式与资源
│       ├── App.xaml                 # 应用程序定义
│       └── MainWindow.xaml          # 主窗口
│
├── tests/
│   └── UIPS.API.Tests/              # 单元测试项目
│
├── .github/
│   └── workflows/                   # CI/CD 工作流
│       ├── ci-cd.yml                # 主流水线
│       └── pr-check.yml             # PR 检查
│
├── UIPS.sln                         # Visual Studio 解决方案
└── README.md                        # 项目文档

模块职责划分

模块	项目	职责
Backend	`UIPS.API`	RESTful API 服务、数据持久化、业务逻辑、JWT 认证
Frontend	`UIPS.Client`	用户界面、MVVM 架构、HTTP 通信、状态管理
Tests	`UIPS.API.Tests`	单元测试、集成测试、API 测试

🚀 快速开始

环境要求

操作系统: Windows 10/11 (推荐) 或 macOS/Linux (需调整 WPF 部分)
IDE: Visual Studio 2022 (v17.8 或更高版本)
.NET SDK: .NET 8.0 SDK
Git: 用于版本控制

安装步骤

1. 克隆仓库

git clone https://github.com/ekkure/UnderwaterImageProcessingSystem.git
cd UnderwaterImageProcessingSystem

2. 还原依赖

dotnet restore

3. 数据库初始化

项目使用 SQLite，数据库文件会在首次运行时自动创建并迁移。无需手动配置。

4. 配置启动项目

在 Visual Studio 中：

右键点击解决方案 → 设置启动项目
选择 多个启动项目
将 UIPS.API 和 UIPS.Client 设置为启动

5. 运行项目

按 F5 或点击启动按钮：

后端: 将在 https://localhost:7xxx 启动，Swagger UI 自动打开
前端: WPF 应用程序窗口将启动

默认账户

首次运行时，系统会自动创建管理员账户：

用户名: admin
密码: admin123

安全提示: 生产环境请立即修改默认密码！

🔧 开发指南

项目配置

后端配置 (`appsettings.json`)

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=uips.db"
  },
  "Jwt": {
    "Key": "your-secret-key-here",
    "Issuer": "UIPS.API",
    "Audience": "UIPS.Client",
    "ExpiryMinutes": 60
  },
  "FileStorage": {
    "BasePath": "wwwroot/uploads"
  }
}

前端配置 (App.xaml.cs)

services.AddRefitClient<IUipsApiService>()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://localhost:7xxx"));

数据库迁移

# 添加新迁移
dotnet ef migrations add MigrationName --project src/UIPS.API

# 更新数据库
dotnet ef database update --project src/UIPS.API

# 回滚迁移
dotnet ef database update PreviousMigrationName --project src/UIPS.API

运行测试

# 运行所有测试
dotnet test

# 运行特定项目测试
dotnet test tests/UIPS.API.Tests

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

🎨 UI 设计规范

Deep Ocean Palette (深海主题)

项目采用深海配色方案，营造专业的水下环境氛围：

主色调: #0D47A1 (深海蓝)
次要色: #1976D2 (海洋蓝)
强调色: #00BCD4 (青色)
背景色: #263238 (深灰蓝)
文本色: #ECEFF1 (浅灰白)

资源引用顺序

App.xaml 中的资源字典合并顺序严禁修改：

<ResourceDictionary.MergedDictionaries>
    <materialDesign:BundledTheme BaseTheme="Dark" ... />
    <ResourceDictionary Source="Resources/Colors.xaml" />
    <ResourceDictionary Source="Resources/Styles.xaml" />
</ResourceDictionary.MergedDictionaries>

📜 开发规范

Git 工作流

本项目采用 Git Flow 分支策略：

main (生产分支)
  ↑
develop (开发分支)
  ↑
feature/xxx (功能分支)
hotfix/xxx (热修复分支)

分支命名规范

功能开发: feature/功能名称 (例: feature/image-upload)
Bug 修复: bugfix/问题描述 (例: bugfix/login-error)
热修复: hotfix/紧急问题 (例: hotfix/security-patch)
发布准备: release/版本号 (例: release/v1.0.0)

提交信息规范

遵循 Conventional Commits 规范：

<type>(<scope>): <subject>

<body>

<footer>

类型 (type):

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具链更新

示例:

feat(api): 添加图像批量上传接口

- 实现多文件上传功能
- 添加文件大小验证
- 更新 Swagger 文档

Closes #123

代码审查清单

🔒 安全最佳实践

敏感信息管理
- 使用 User Secrets 存储开发环境密钥
- 生产环境使用环境变量或 Azure Key Vault
JWT 配置
- 密钥长度至少 256 位
- 设置合理的过期时间
- 使用 HTTPS 传输
文件上传
- 验证文件类型和大小
- 使用随机文件名防止路径遍历
- 限制上传频率
数据库安全
- 使用参数化查询防止 SQL 注入
- 定期备份数据库
- 敏感字段加密存储

🧪 测试策略

测试金字塔

        /\
       /  \  E2E Tests (少量)
      /────\
     /      \ Integration Tests (适量)
    /────────\
   /          \ Unit Tests (大量)
  /────────────\

测试覆盖目标

单元测试: 覆盖率 > 80%
集成测试: 覆盖核心业务流程
E2E 测试: 覆盖关键用户场景

📊 性能优化

数据库索引: 为常用查询字段添加索引
分页查询: 使用 PaginatedResult<T> 避免大数据集加载
异步编程: 所有 I/O 操作使用 async/await
缓存策略: 对静态资源和频繁访问数据启用缓存
图像优化: 自动压缩上传图像，生成缩略图

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
src		src
tests/UIPS.API.Tests		tests/UIPS.API.Tests
.gitignore		.gitignore
README.md		README.md
UIPS.sln		UIPS.sln

Latest commit

History

Folders and files

Repository files navigation