# 外卖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. 克隆项目
```bash
git clone https://github.com/your-org/takeout-saas.git
cd takeout-saas
```

### 2. 使用Docker Compose启动依赖服务（推荐）
```bash
# 启动PostgreSQL、Redis、RabbitMQ等服务
docker-compose up -d

# 查看服务状态
docker-compose ps
```

### 3. 配置数据库连接
编辑 `src/TakeoutSaaS.Api/appsettings.Development.json`

### 4. 执行数据库迁移
```bash
cd src/TakeoutSaaS.Api
dotnet ef database update
```

### 5. 运行项目
```bash
dotnet run
```

访问 API 文档：
- 管理后台 AdminApi Swagger：http://localhost:5001/swagger
- 小程序/用户端 MiniApi Swagger：http://localhost:5002/swagger

## 公告管理

> 最后更新日期：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

## 协作者

感谢所有为本项目做出贡献的开发者！

---

⭐ 如果这个项目对你有帮助，请给我们一个星标！
