256 lines
7.4 KiB
Markdown
256 lines
7.4 KiB
Markdown
# 外卖SaaS系统 (TakeoutSaaS)
|
||
|
||
## 项目简介
|
||
|
||
外卖SaaS系统是一个基于.NET 10的多租户外卖管理平台，为中小型餐饮企业提供完整的外卖业务解决方案。系统采用现代化的技术栈，支持商家管理、菜品管理、订单处理、配送管理、支付集成等核心功能。
|
||
|
||
### 核心特性
|
||
|
||
- **多租户架构**：支持多租户数据隔离，SaaS模式运营
|
||
- **商家管理**：完善的商家入驻、门店管理、菜品管理功能
|
||
- **订单管理**：订单全生命周期管理，实时状态跟踪
|
||
- **配送管理**：配送任务、路线规划、第三方配送对接
|
||
- **支付集成**：支持微信、支付宝等多种支付方式
|
||
- **营销功能**：优惠券、满减活动、会员积分
|
||
- **字典管理**：系统字典、租户覆盖、批量导入导出、缓存监控
|
||
- **数据分析**：实时数据统计、经营报表、趋势分析
|
||
- **安全可靠**：JWT认证、权限控制、数据加密
|
||
|
||
## 技术栈
|
||
|
||
### 后端技术
|
||
- **.NET 10**：最新的.NET平台
|
||
- **ASP.NET Core Web API**：RESTful API服务
|
||
- **Entity Framework Core 10**：最新ORM框架
|
||
- **Dapper 2.1+**：高性能数据访问
|
||
- **PostgreSQL 16+**：主数据库
|
||
- **Redis 7.0+**：分布式缓存
|
||
- **RabbitMQ 3.12+**：消息队列
|
||
|
||
### 开发框架
|
||
- **AutoMapper**：对象映射
|
||
- **FluentValidation**：数据验证
|
||
- **Serilog**：结构化日志
|
||
- **MediatR**：CQRS模式
|
||
- **Hangfire**：后台任务
|
||
- **Swagger**：API文档
|
||
|
||
## 运行条件
|
||
|
||
### 开发环境要求
|
||
* .NET SDK 10.0 或更高版本
|
||
* PostgreSQL 16+
|
||
* Redis 7.0+
|
||
* RabbitMQ 3.12+（可选）
|
||
* Docker Desktop（推荐，用于容器化开发）
|
||
|
||
### 推荐IDE
|
||
* Visual Studio 2022
|
||
* JetBrains Rider
|
||
* Visual Studio Code
|
||
|
||
## 快速开始
|
||
|
||
### 1. 克隆仓库（已拆分为多仓 + 子模块）
|
||
|
||
> 推荐使用 `--recurse-submodules` 一次性拉取共享库与文档子模块。
|
||
|
||
**管理后台 AdminApi**
|
||
```bash
|
||
git clone --recurse-submodules -b dev git@github.com:msumshk/TakeoutSaaS.AdminApi.git
|
||
cd TakeoutSaaS.AdminApi
|
||
```
|
||
|
||
**租户端 TenantApi（MiniApi/UserApi）**
|
||
```bash
|
||
git clone --recurse-submodules -b dev git@github.com:msumshk/TakeoutSaaS.TenantApi.git
|
||
cd TakeoutSaaS.TenantApi
|
||
```
|
||
|
||
**若未使用 `--recurse-submodules`**
|
||
```bash
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
### 2. 使用Docker Compose启动依赖服务（推荐）
|
||
```bash
|
||
# 在你的 docker-compose.yml 所在目录执行（示例）
|
||
# 启动 PostgreSQL、Redis、RabbitMQ 等服务
|
||
docker-compose up -d
|
||
|
||
# 查看服务状态
|
||
docker-compose ps
|
||
```
|
||
|
||
### 3. 配置数据库连接
|
||
编辑各服务的配置文件：
|
||
- AdminApi：`src/Api/TakeoutSaaS.AdminApi/appsettings.Development.json`
|
||
- MiniApi：`src/Api/TakeoutSaaS.MiniApi/appsettings.Development.json`
|
||
- UserApi：`src/Api/TakeoutSaaS.UserApi/appsettings.Development.json`
|
||
|
||
### 4. 执行数据库迁移（如需）
|
||
|
||
迁移执行与设计期 DbContext 配置请参考：`Document/10_设计期DbContext配置指引.md`。
|
||
|
||
### 5. 运行项目
|
||
```bash
|
||
# AdminApi
|
||
dotnet run --project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj
|
||
|
||
# MiniApi（TenantApi 仓库内）
|
||
dotnet run --project src/Api/TakeoutSaaS.MiniApi/TakeoutSaaS.MiniApi.csproj
|
||
|
||
# UserApi（TenantApi 仓库内）
|
||
dotnet run --project src/Api/TakeoutSaaS.UserApi/TakeoutSaaS.UserApi.csproj
|
||
```
|
||
|
||
访问 API 文档：
|
||
- Swagger UI：`/api/docs`（旧入口 `/swagger` 仍保留）
|
||
- 端口以各项目 `Properties/launchSettings.json` 或部署配置为准
|
||
|
||
## 字典管理
|
||
|
||
> 最后更新日期：2025-12-30
|
||
|
||
### 功能概述
|
||
|
||
- 系统/业务字典分组与字典项管理
|
||
- 租户覆盖：隐藏系统项、自定义字典项、拖拽排序
|
||
- CSV/JSON 批量导入导出
|
||
- 两级缓存（Memory + Redis）与缓存监控指标
|
||
|
||
### 配置要点
|
||
|
||
- `ConnectionStrings:Redis`：Redis 连接字符串
|
||
- `Database:DataSources:DictionaryDatabase`：字典库读写连接
|
||
- `Dictionary:Cache:SlidingExpiration`：字典缓存滑动过期
|
||
- `CacheWarmup:DictionaryCodes`：缓存预热字典编码列表
|
||
|
||
## 公告管理
|
||
|
||
> 最后更新日期：2025-12-20
|
||
|
||
### 功能概述
|
||
|
||
- 支持平台公告与租户公告统一管理（TenantId=0 代表平台公告）
|
||
- 状态机：草稿 → 已发布 → 已撤销（已发布不可编辑）
|
||
- 支持目标受众过滤与未读/已读能力
|
||
|
||
### 快速开始（示例流程）
|
||
|
||
1. 创建公告（草稿）
|
||
2. 发布公告（进入 Published）
|
||
3. 应用端获取可见公告列表与未读公告
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Draft
|
||
Draft --> Published: publish
|
||
Published --> Revoked: revoke
|
||
Revoked --> Published: republish
|
||
```
|
||
|
||
### 关键概念
|
||
|
||
- `Status`：Draft/Published/Revoked，已发布不可编辑
|
||
- `RowVersion`：并发控制字段（Base64）
|
||
- `TargetType/TargetParameters`：目标受众过滤
|
||
|
||
### 相关文档
|
||
|
||
- `docs/api/announcements-api.md`
|
||
- `docs/permissions/announcement-permissions.md`
|
||
- `docs/adr/0001-announcement-status-state-machine.md`
|
||
- `docs/observability/announcement-events.md`
|
||
- `docs/migrations/announcement-status-migration.md`
|
||
- `docs/technical-debt.md`
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
TakeoutSaaS/
|
||
├── 0_Document/ # 项目文档
|
||
│ ├── 01_项目概述.md
|
||
│ ├── 02_技术架构.md
|
||
│ ├── 03_数据库设计.md
|
||
│ ├── 04A_管理后台API.md
|
||
│ ├── 04B_小程序API.md
|
||
│ ├── 05_部署运维.md
|
||
│ └── 06_开发规范.md
|
||
├── src/
|
||
│ ├── TakeoutSaaS.AdminApi/ # 管理后台 Web API
|
||
│ ├── TakeoutSaaS.MiniApi/ # 小程序/用户端 Web API
|
||
│ ├── TakeoutSaaS.Application/ # 应用层
|
||
│ ├── TakeoutSaaS.Domain/ # 领域层
|
||
│ ├── TakeoutSaaS.Infrastructure/ # 基础设施层
|
||
│ └── TakeoutSaaS.Shared/ # 共享层
|
||
├── tests/
|
||
│ ├── TakeoutSaaS.UnitTests/ # 单元测试
|
||
│ └── TakeoutSaaS.IntegrationTests/ # 集成测试
|
||
├── docker-compose.yml # Docker编排文件
|
||
└── README.md
|
||
```
|
||
|
||
## 测试说明
|
||
|
||
### 运行单元测试
|
||
```bash
|
||
dotnet test tests/TakeoutSaaS.UnitTests
|
||
```
|
||
|
||
### 运行集成测试
|
||
```bash
|
||
dotnet test tests/TakeoutSaaS.IntegrationTests
|
||
```
|
||
|
||
## 部署说明
|
||
|
||
### Docker部署
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t takeout-saas-api:latest .
|
||
|
||
# 运行容器
|
||
docker run -d -p 8080:80 --name takeout-api takeout-saas-api:latest
|
||
```
|
||
|
||
详细部署文档请参考：[部署运维文档](0_Document/05_部署运维.md)
|
||
|
||
## 文档
|
||
|
||
- [项目概述](0_Document/01_项目概述.md) - 系统介绍和业务说明
|
||
- [技术架构](0_Document/02_技术架构.md) - 技术栈和架构设计
|
||
- [数据库设计](0_Document/03_数据库设计.md) - 数据模型和表结构
|
||
- [API接口设计](0_Document/04_API接口设计.md) - RESTful API规范
|
||
- [部署运维](0_Document/05_部署运维.md) - 部署和运维指南
|
||
- [开发规范](0_Document/06_开发规范.md) - 代码规范和最佳实践
|
||
|
||
## 开发规范
|
||
|
||
请遵循项目的[开发规范](0_Document/06_开发规范.md)
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 创建 Pull Request
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证
|
||
|
||
## 联系方式
|
||
|
||
- 项目地址：https://github.com/your-org/takeout-saas
|
||
- 问题反馈：https://github.com/your-org/takeout-saas/issues
|
||
|
||
## 协作者
|
||
|
||
感谢所有为本项目做出贡献的开发者！
|
||
|
||
---
|
||
|
||
⭐ 如果这个项目对你有帮助，请给我们一个星标！
|