msumshk/TakeoutSaaS.Docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 初始化 Docs 仓库

Browse Source
This commit is contained in:
MSuMshk
2026-01-29 01:58:15 +00:00
commit 88ad71041b
37 changed files with 25416 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
Document/01_项目概述.md Normal file
View File

@@ -0,0 +1,188 @@
# 外卖SaaS系统 - 项目概述
## 1. 项目简介
### 1.1 项目背景
外卖SaaS系统是一个面向餐饮企业的多租户外卖管理平台，旨在为中小型餐饮企业提供完整的外卖业务解决方案。系统支持商家入驻、菜品管理、订单处理、配送管理等核心功能。
### 1.2 项目目标
- 提供稳定、高效的外卖业务管理平台
- 支持多租户架构，实现数据隔离和资源共享
- 提供完善的商家管理和运营工具
- 支持灵活的配送模式（自配送、第三方配送）
- 提供实时数据分析和报表功能
### 1.3 核心价值
- **降低成本**：SaaS模式降低企业IT投入成本
- **快速上线**：开箱即用，快速开展外卖业务
- **灵活扩展**：支持业务增长和功能定制
- **数据驱动**：提供数据分析，辅助经营决策
## 2. 业务模块
### 2.1 租户管理模块
- 租户注册与认证
- 租户信息管理
- 套餐订阅管理
- 权限与配额管理
### 2.2 商家管理模块
- 商家入驻审核
- 商家信息管理
- 门店管理（支持多门店）
- 营业时间设置
- 配送范围设置
### 2.3 菜品管理模块
- 菜品分类管理
- 菜品信息管理（名称、价格、图片、描述）
- 菜品规格管理（大份、小份等）
- 菜品库存管理
- 菜品上下架管理
### 2.4 订单管理模块
- 订单创建与支付
- 订单状态流转（待支付、待接单、制作中、配送中、已完成、已取消）
- 订单查询与筛选
- 订单退款处理
- 订单统计分析
### 2.5 配送管理模块
- 配送员管理
- 配送任务分配
- 配送路线规划
- 配送状态跟踪
- 配送费用计算
### 2.6 用户管理模块
- 用户注册与登录
- 用户信息管理
- 收货地址管理
- 用户订单历史
- 用户评价管理
### 2.7 支付管理模块
- 多支付方式支持（微信、支付宝、余额）
- 支付回调处理
- 退款处理
- 账单管理
### 2.8 营销管理模块
- 优惠券管理
- 满减活动
- 会员积分
- 推广活动
### 2.9 数据分析模块
- 销售数据统计
- 订单趋势分析
- 用户行为分析
- 商家经营报表
- 平台运营大盘
### 2.10 系统管理模块
- 系统配置管理
- 日志管理
- 权限管理
- 消息通知管理
## 3. 用户角色
### 3.1 平台管理员（Web管理端）
- 管理所有租户和商家
- 系统配置和维护
- 数据监控和分析
- 审核商家入驻
- 平台运营管理
### 3.2 租户管理员（Web管理端）
- 管理租户下的所有商家
- 查看租户数据报表
- 管理租户套餐和权限
- 租户配置管理
### 3.3 商家管理员（Web管理端）
- 管理门店信息
- 管理菜品和订单
- 查看经营数据
- 管理配送（自配送或第三方配送对接）
- 营销活动管理
### 3.4 商家员工（Web管理端）
- 处理订单（接单/出餐/发货）
- 更新菜品状态
- 订单打印与出餐看板
### 3.5 普通用户/消费者（小程序端 + Web用户端）
- 浏览商家和菜品
- 下单和支付
- 查看订单状态
- 评价和反馈
- 收货地址管理
- 优惠券领取和使用
## 4. 系统特性
### 4.1 多租户架构
- 数据隔离：每个租户数据完全隔离
- 资源共享：共享基础设施，降低成本
- 灵活配置：支持租户级别的个性化配置
### 4.2 高可用性
- 服务高可用：支持集群部署
- 数据高可用：数据库主从复制
- 故障自动恢复
### 4.3 高性能
- 缓存策略：Redis缓存热点数据
- 数据库优化：索引优化、查询优化
- 异步处理：消息队列处理耗时任务
### 4.4 安全性
- 身份认证：JWT Token认证
- 权限控制：基于角色的访问控制（RBAC）
- 数据加密：敏感数据加密存储
- 接口防护：限流、防重放攻击
### 4.5 可扩展性
- 微服务架构：支持服务独立扩展
- 插件化设计：支持功能模块插拔
- API开放：提供开放API接口
## 5. 技术选型
- **后端框架**：.NET 10
- **ORM框架**：Entity Framework Core 10 + Dapper
- **数据库**：PostgreSQL 16+
- **缓存**：Redis 7.0+
- **消息队列**：RabbitMQ 3.12+
- **API文档**：Swagger/OpenAPI
- **日志**：Serilog
- **认证授权**：JWT + OAuth2.0
## 6. 项目里程碑
### Phase 1：基础功能（1-2个月）
- 租户管理
- 商家管理
- 菜品管理
- 订单管理（基础流程）
### Phase 2：核心功能（2-3个月）
- 配送管理
- 支付集成
- 用户管理
- 基础营销功能
### Phase 3：高级功能（3-4个月）
- 数据分析
- 高级营销
- 系统优化
- 性能调优
### Phase 4：完善与上线（1个月）
- 测试与修复
- 文档完善
- 部署上线
- 运维监控

253
Document/02_技术架构.md Normal file
View File

@@ -0,0 +1,253 @@
# 外卖SaaS系统 - 技术架构
## 1. 技术栈
### 1.1 后端技术栈
- **.NET 10**：最新的.NET平台，提供高性能和现代化开发体验
- **ASP.NET Core Web API**：构建RESTful API服务
- **Entity Framework Core 10**：最新ORM框架，用于复杂查询和实体管理
- **Dapper 2.1+**：轻量级ORM，用于高性能查询和批量操作
- **PostgreSQL 16+**：主数据库，支持JSON、全文搜索等高级特性
- **Redis 7.0+**：缓存和会话存储
- **RabbitMQ 3.12+**：消息队列，处理异步任务
### 1.2 开发工具和框架
- **AutoMapper**：对象映射
- **FluentValidation**：数据验证
- **Serilog**：结构化日志
- **MediatR**：CQRS和中介者模式实现
- **Hangfire**：后台任务调度
- **Polly**：弹性和瞬态故障处理
- **Swagger/Swashbuckle**：API文档生成
### 1.3 认证授权
- **JWT (JSON Web Token)**：无状态身份认证
- **IdentityServer/Duende IdentityServer**：OAuth2.0和OpenID Connect
- **ASP.NET Core Identity**：用户身份管理
### 1.4 测试框架
- **xUnit**：单元测试框架
- **Moq**：Mock框架
- **FluentAssertions**：断言库
- **Testcontainers**：集成测试容器化
### 1.5 DevOps工具
- **Docker**：容器化部署
- **Docker Compose**：本地开发环境
- **GitHub Actions/GitLab CI**：CI/CD流水线
- **Nginx**：反向代理和负载均衡
## 2. 系统架构
### 2.1 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Web管理端 │ │ Web用户端 │ │ 小程序端（用户） │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ API网关层 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Nginx / API Gateway (路由、限流、认证、日志) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 应用服务层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │租户服务 │ │商家服务 │ │订单服务 │ │配送服务 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │用户服务 │ │支付服务 │ │营销服务 │ │通知服务 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 基础设施层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │PostgreSQL │ │ Redis │ │ RabbitMQ │ │ MinIO │ │
│ │ (主库) │ │ (缓存) │ │ (消息队列)│ │(对象存储) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 2.2 分层架构
#### 2.2.1 表现层 (Presentation Layer)
- **TakeoutSaaS.AdminApi**：管理后台 Web API 项目（/api/admin/v1）
- Controllers：后台管理API控制器
- Filters：过滤器（异常处理、日志、验证）
- Middleware：中间件（认证、租户识别、RBAC）
- Models：请求/响应DTO
- **TakeoutSaaS.MiniApi**：小程序/用户端 Web API 项目（/api/mini/v1）
- Controllers：用户端API控制器
- Filters：过滤器（异常处理、限流、签名校验）
- Middleware：中间件（小程序登录态、租户识别、CORS）
- Models：请求/响应DTO
#### 2.2.2 应用层 (Application Layer)
- **TakeoutSaaS.Application**：应用逻辑
- Services：应用服务
- DTOs：数据传输对象
- Interfaces：服务接口
- Validators：FluentValidation验证器
- Mappings：AutoMapper配置
- Commands/Queries：CQRS命令和查询
#### 2.2.3 领域层 (Domain Layer)
- **TakeoutSaaS.Domain**：领域模型
- Entities：实体类
- ValueObjects：值对象
- Enums：枚举
- Events：领域事件
- Interfaces：仓储接口
- Specifications：规约模式
#### 2.2.4 基础设施层 (Infrastructure Layer)
- **TakeoutSaaS.Infrastructure**：基础设施实现
- Data：数据访问
- EFCore：EF Core DbContext和配置
- Dapper：Dapper查询实现
- Repositories：仓储实现
- Migrations：数据库迁移
- Cache：Redis缓存实现
- MessageQueue：RabbitMQ实现
- ExternalServices：第三方服务集成
#### 2.2.5 共享层 (Shared Layer)
- **TakeoutSaaS.Shared**：共享组件
- Constants：常量定义
- Exceptions：自定义异常
- Extensions：扩展方法
- Helpers：辅助类
- Results：统一返回结果
## 3. 核心设计模式
### 3.1 多租户模式
- **数据隔离策略**：每个租户独立Schema
- **租户识别**：通过HTTP Header或JWT Token识别租户
- **动态切换**：运行时动态切换数据库连接
### 3.2 CQRS模式
- **命令（Command）**：处理写操作，修改数据
- **查询（Query）**：处理读操作，不修改数据
- **分离优势**：读写分离，优化性能
### 3.3 仓储模式
- **抽象数据访问**：统一数据访问接口
- **EF Core仓储**：复杂查询和事务处理
- **Dapper仓储**：高性能查询和批量操作
### 3.4 工作单元模式
- **事务管理**：统一管理数据库事务
- **批量提交**：减少数据库往返次数
### 3.5 领域驱动设计（DDD）
- **聚合根**：定义实体边界
- **值对象**：不可变对象
- **领域事件**：解耦业务逻辑
## 4. 数据访问策略
### 4.1 EF Core使用场景
- 复杂的实体关系查询
- 需要变更跟踪的操作
- 事务性操作
- 数据库迁移管理
### 4.2 Dapper使用场景
- 高性能查询（大数据量）
- 复杂SQL查询
- 批量插入/更新
- 报表统计查询
- 存储过程调用
### 4.3 混合使用策略
```csharp
// EF Core - 复杂查询和实体管理
public async Task<Order> GetOrderWithDetailsAsync(Guid orderId)
{
return await _dbContext.Orders
.Include(o => o.OrderItems)
.Include(o => o.Customer)
.FirstOrDefaultAsync(o => o.Id == orderId);
}
// Dapper - 高性能统计查询
public async Task<OrderStatistics> GetOrderStatisticsAsync(DateTime startDate, DateTime endDate)
{
var sql = @"
SELECT
COUNT(*) as TotalOrders,
SUM(total_amount) as TotalAmount,
AVG(total_amount) as AvgAmount
FROM orders
WHERE created_at BETWEEN @StartDate AND @EndDate";
return await _connection.QueryFirstOrDefaultAsync<OrderStatistics>(sql,
new { StartDate = startDate, EndDate = endDate });
}
```
## 5. 缓存策略
### 5.1 缓存层次
- **L1缓存**：内存缓存（IMemoryCache）- 进程内缓存
- **L2缓存**：Redis缓存 - 分布式缓存
### 5.2 缓存场景
- 商家信息缓存（30分钟）
- 菜品信息缓存（15分钟）
- 用户会话缓存（2小时）
- 配置信息缓存（1小时）
- 热点数据缓存（动态过期）
### 5.3 缓存更新策略
- **Cache-Aside**：旁路缓存，先查缓存，未命中查数据库
- **Write-Through**：写入时同步更新缓存
- **Write-Behind**：异步更新缓存
## 6. 消息队列应用
### 6.1 异步任务
- 订单状态变更通知
- 短信/邮件发送
- 数据统计计算
- 日志持久化
### 6.2 事件驱动
- 订单创建事件
- 支付成功事件
- 配送状态变更事件
## 7. 安全设计
### 7.1 认证机制
- JWT Token认证
- Refresh Token刷新
- Token过期管理
### 7.2 授权机制
- 基于角色的访问控制（RBAC）
- 基于策略的授权
- 资源级权限控制
### 7.3 数据安全
- 敏感数据加密（密码、支付信息）
- HTTPS传输加密
- SQL注入防护
- XSS防护
### 7.4 接口安全
- 请求签名验证
- 接口限流（Rate Limiting）
- 防重放攻击
- CORS跨域配置

641
Document/03_数据库设计.md Normal file
View File

@@ -0,0 +1,641 @@
# 外卖SaaS系统 - 数据库设计
## 1. 数据库设计原则
### 1.1 命名规范
- **表名**：小写字母，下划线分隔，复数形式（如：`orders`, `order_items`）
- **字段名**：小写字母，下划线分隔（如：`created_at`, `total_amount`）
- **主键**：统一使用 `id`，类型为 UUID
- **外键**：`表名_id`（如：`order_id`, `merchant_id`）
- **索引**：`idx_表名_字段名`（如：`idx_orders_merchant_id`）
### 1.2 通用字段
所有表都包含以下字段：
- `id`：UUID，主键
- `created_at`：TIMESTAMP，创建时间
- `updated_at`：TIMESTAMP，更新时间
- `deleted_at`：TIMESTAMP，软删除时间（可选）
- `tenant_id`：UUID，租户ID（多租户隔离）
### 1.3 数据类型规范
- **金额**：DECIMAL(18,2)
- **时间**：TIMESTAMP WITH TIME ZONE
- **布尔**：BOOLEAN
- **枚举**：VARCHAR 或 INTEGER
- **JSON数据**：JSONB
## 2. 核心表结构
### 2.1 租户管理
#### tenants（租户表）
```sql
CREATE TABLE tenants (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(100) NOT NULL,
code VARCHAR(50) UNIQUE NOT NULL,
contact_name VARCHAR(50),
contact_phone VARCHAR(20),
contact_email VARCHAR(100),
status INTEGER NOT NULL DEFAULT 1, -- 1:正常 2:冻结 3:过期
subscription_plan VARCHAR(50), -- 订阅套餐
subscription_start_date TIMESTAMP WITH TIME ZONE,
subscription_end_date TIMESTAMP WITH TIME ZONE,
max_merchants INTEGER DEFAULT 10, -- 最大商家数
max_orders_per_day INTEGER DEFAULT 1000, -- 每日订单限额
settings JSONB, -- 租户配置
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_tenants_code ON tenants(code);
CREATE INDEX idx_tenants_status ON tenants(status);
```
### 2.2 商家管理
#### merchants（商家表）
```sql
CREATE TABLE merchants (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
name VARCHAR(100) NOT NULL,
logo_url VARCHAR(500),
description TEXT,
contact_phone VARCHAR(20),
contact_person VARCHAR(50),
business_license VARCHAR(100), -- 营业执照号
status INTEGER NOT NULL DEFAULT 1, -- 1:正常 2:休息 3:停业
rating DECIMAL(3,2) DEFAULT 0, -- 评分
total_sales INTEGER DEFAULT 0, -- 总销量
settings JSONB, -- 商家配置
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_merchants_tenant_id ON merchants(tenant_id);
CREATE INDEX idx_merchants_status ON merchants(status);
```
#### merchant_stores（门店表）
```sql
CREATE TABLE merchant_stores (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
merchant_id UUID NOT NULL REFERENCES merchants(id),
name VARCHAR(100) NOT NULL,
address VARCHAR(500) NOT NULL,
latitude DECIMAL(10,7), -- 纬度
longitude DECIMAL(10,7), -- 经度
phone VARCHAR(20),
business_hours JSONB, -- 营业时间 {"monday": {"open": "09:00", "close": "22:00"}}
delivery_range INTEGER DEFAULT 3000, -- 配送范围（米）
min_order_amount DECIMAL(18,2) DEFAULT 0, -- 起送价
delivery_fee DECIMAL(18,2) DEFAULT 0, -- 配送费
status INTEGER NOT NULL DEFAULT 1,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_merchant_stores_merchant_id ON merchant_stores(merchant_id);
CREATE INDEX idx_merchant_stores_location ON merchant_stores USING GIST(point(longitude, latitude));
```
### 2.3 菜品管理
#### categories（菜品分类表）
```sql
CREATE TABLE categories (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
merchant_id UUID NOT NULL REFERENCES merchants(id),
name VARCHAR(50) NOT NULL,
sort_order INTEGER DEFAULT 0,
status INTEGER NOT NULL DEFAULT 1,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_categories_merchant_id ON categories(merchant_id);
```
#### dishes（菜品表）
```sql
CREATE TABLE dishes (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
merchant_id UUID NOT NULL REFERENCES merchants(id),
category_id UUID REFERENCES categories(id),
name VARCHAR(100) NOT NULL,
description TEXT,
image_url VARCHAR(500),
price DECIMAL(18,2) NOT NULL,
original_price DECIMAL(18,2), -- 原价
unit VARCHAR(20) DEFAULT '份', -- 单位
stock INTEGER, -- 库存（NULL表示不限）
sales_count INTEGER DEFAULT 0, -- 销量
rating DECIMAL(3,2) DEFAULT 0, -- 评分
sort_order INTEGER DEFAULT 0,
status INTEGER NOT NULL DEFAULT 1, -- 1:上架 2:下架
tags JSONB, -- 标签 ["热销", "新品"]
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_dishes_merchant_id ON dishes(merchant_id);
CREATE INDEX idx_dishes_category_id ON dishes(category_id);
CREATE INDEX idx_dishes_status ON dishes(status);
```
#### dish_specs（菜品规格表）
```sql
CREATE TABLE dish_specs (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
dish_id UUID NOT NULL REFERENCES dishes(id),
name VARCHAR(50) NOT NULL, -- 规格名称（如：大份、小份）
price DECIMAL(18,2) NOT NULL,
stock INTEGER,
status INTEGER NOT NULL DEFAULT 1,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_dish_specs_dish_id ON dish_specs(dish_id);
```
### 2.4 用户管理
#### users（用户表）
```sql
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
phone VARCHAR(20) UNIQUE NOT NULL,
nickname VARCHAR(50),
avatar_url VARCHAR(500),
gender INTEGER, -- 0:未知 1:男 2:女
birthday DATE,
balance DECIMAL(18,2) DEFAULT 0, -- 余额
points INTEGER DEFAULT 0, -- 积分
status INTEGER NOT NULL DEFAULT 1,
last_login_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_users_phone ON users(phone);
```
#### user_addresses（用户地址表）
```sql
CREATE TABLE user_addresses (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id),
contact_name VARCHAR(50) NOT NULL,
contact_phone VARCHAR(20) NOT NULL,
province VARCHAR(50),
city VARCHAR(50),
district VARCHAR(50),
address VARCHAR(500) NOT NULL,
house_number VARCHAR(50), -- 门牌号
latitude DECIMAL(10,7),
longitude DECIMAL(10,7),
is_default BOOLEAN DEFAULT FALSE,
label VARCHAR(20), -- 标签：家、公司等
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_user_addresses_user_id ON user_addresses(user_id);
```
### 2.5 订单管理
#### orders（订单表）
```sql
CREATE TABLE orders (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
order_no VARCHAR(50) UNIQUE NOT NULL, -- 订单号
merchant_id UUID NOT NULL REFERENCES merchants(id),
store_id UUID NOT NULL REFERENCES merchant_stores(id),
user_id UUID NOT NULL REFERENCES users(id),
-- 收货信息
delivery_address VARCHAR(500) NOT NULL,
delivery_latitude DECIMAL(10,7),
delivery_longitude DECIMAL(10,7),
contact_name VARCHAR(50) NOT NULL,
contact_phone VARCHAR(20) NOT NULL,
-- 金额信息
dish_amount DECIMAL(18,2) NOT NULL, -- 菜品金额
delivery_fee DECIMAL(18,2) DEFAULT 0, -- 配送费
package_fee DECIMAL(18,2) DEFAULT 0, -- 打包费
discount_amount DECIMAL(18,2) DEFAULT 0, -- 优惠金额
total_amount DECIMAL(18,2) NOT NULL, -- 总金额
actual_amount DECIMAL(18,2) NOT NULL, -- 实付金额
-- 订单状态
status INTEGER NOT NULL DEFAULT 1, -- 1:待支付 2:待接单 3:制作中 4:待配送 5:配送中 6:已完成 7:已取消
payment_status INTEGER DEFAULT 0, -- 0:未支付 1:已支付 2:已退款
payment_method VARCHAR(20), -- 支付方式
payment_time TIMESTAMP WITH TIME ZONE,
-- 时间信息
estimated_delivery_time TIMESTAMP WITH TIME ZONE, -- 预计送达时间
accepted_at TIMESTAMP WITH TIME ZONE, -- 接单时间
cooking_at TIMESTAMP WITH TIME ZONE, -- 开始制作时间
delivered_at TIMESTAMP WITH TIME ZONE, -- 送达时间
completed_at TIMESTAMP WITH TIME ZONE, -- 完成时间
cancelled_at TIMESTAMP WITH TIME ZONE, -- 取消时间
remark TEXT, -- 备注
cancel_reason TEXT, -- 取消原因
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_orders_tenant_id ON orders(tenant_id);
CREATE INDEX idx_orders_order_no ON orders(order_no);
CREATE INDEX idx_orders_merchant_id ON orders(merchant_id);
CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_status ON orders(status);
CREATE INDEX idx_orders_created_at ON orders(created_at);
```
#### order_items（订单明细表）
```sql
CREATE TABLE order_items (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
order_id UUID NOT NULL REFERENCES orders(id),
dish_id UUID NOT NULL REFERENCES dishes(id),
dish_name VARCHAR(100) NOT NULL, -- 冗余字段，防止菜品被删除
dish_image_url VARCHAR(500),
spec_id UUID REFERENCES dish_specs(id),
spec_name VARCHAR(50),
price DECIMAL(18,2) NOT NULL, -- 单价
quantity INTEGER NOT NULL, -- 数量
amount DECIMAL(18,2) NOT NULL, -- 小计
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_order_items_order_id ON order_items(order_id);
CREATE INDEX idx_order_items_dish_id ON order_items(dish_id);
```
### 2.6 配送管理
#### delivery_drivers（配送员表）
```sql
CREATE TABLE delivery_drivers (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
merchant_id UUID REFERENCES merchants(id), -- NULL表示平台配送员
name VARCHAR(50) NOT NULL,
phone VARCHAR(20) UNIQUE NOT NULL,
id_card VARCHAR(18), -- 身份证号
vehicle_type VARCHAR(20), -- 车辆类型：电动车、摩托车
vehicle_number VARCHAR(20), -- 车牌号
status INTEGER NOT NULL DEFAULT 1, -- 1:空闲 2:配送中 3:休息 4:离线
current_latitude DECIMAL(10,7), -- 当前位置
current_longitude DECIMAL(10,7),
rating DECIMAL(3,2) DEFAULT 0,
total_deliveries INTEGER DEFAULT 0, -- 总配送单数
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_delivery_drivers_merchant_id ON delivery_drivers(merchant_id);
CREATE INDEX idx_delivery_drivers_status ON delivery_drivers(status);
```
#### delivery_tasks（配送任务表）
```sql
CREATE TABLE delivery_tasks (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
order_id UUID NOT NULL REFERENCES orders(id),
driver_id UUID REFERENCES delivery_drivers(id),
pickup_address VARCHAR(500) NOT NULL, -- 取餐地址
pickup_latitude DECIMAL(10,7),
pickup_longitude DECIMAL(10,7),
delivery_address VARCHAR(500) NOT NULL, -- 送餐地址
delivery_latitude DECIMAL(10,7),
delivery_longitude DECIMAL(10,7),
distance INTEGER, -- 配送距离（米）
estimated_time INTEGER, -- 预计时长（分钟）
status INTEGER NOT NULL DEFAULT 1, -- 1:待分配 2:待取餐 3:配送中 4:已送达 5:异常
assigned_at TIMESTAMP WITH TIME ZONE, -- 分配时间
picked_at TIMESTAMP WITH TIME ZONE, -- 取餐时间
delivered_at TIMESTAMP WITH TIME ZONE, -- 送达时间
delivery_fee DECIMAL(18,2) DEFAULT 0, -- 配送费
remark TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_delivery_tasks_order_id ON delivery_tasks(order_id);
CREATE INDEX idx_delivery_tasks_driver_id ON delivery_tasks(driver_id);
CREATE INDEX idx_delivery_tasks_status ON delivery_tasks(status);
```
### 2.7 支付管理
#### payments（支付记录表）
```sql
CREATE TABLE payments (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
order_id UUID NOT NULL REFERENCES orders(id),
user_id UUID NOT NULL REFERENCES users(id),
payment_no VARCHAR(50) UNIQUE NOT NULL, -- 支付单号
payment_method VARCHAR(20) NOT NULL, -- 支付方式：wechat、alipay、balance
amount DECIMAL(18,2) NOT NULL,
status INTEGER NOT NULL DEFAULT 0, -- 0:待支付 1:支付中 2:成功 3:失败 4:已退款
third_party_no VARCHAR(100), -- 第三方支付单号
paid_at TIMESTAMP WITH TIME ZONE,
callback_data JSONB, -- 回调数据
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_payments_order_id ON payments(order_id);
CREATE INDEX idx_payments_payment_no ON payments(payment_no);
CREATE INDEX idx_payments_user_id ON payments(user_id);
```
#### refunds（退款记录表）
```sql
CREATE TABLE refunds (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
order_id UUID NOT NULL REFERENCES orders(id),
payment_id UUID NOT NULL REFERENCES payments(id),
refund_no VARCHAR(50) UNIQUE NOT NULL,
amount DECIMAL(18,2) NOT NULL,
reason TEXT,
status INTEGER NOT NULL DEFAULT 0, -- 0:待审核 1:退款中 2:成功 3:失败
third_party_no VARCHAR(100),
refunded_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_refunds_order_id ON refunds(order_id);
CREATE INDEX idx_refunds_payment_id ON refunds(payment_id);
```
### 2.8 营销管理
#### coupons（优惠券表）
```sql
CREATE TABLE coupons (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
merchant_id UUID REFERENCES merchants(id), -- NULL表示平台券
name VARCHAR(100) NOT NULL,
type INTEGER NOT NULL, -- 1:满减券 2:折扣券 3:代金券
discount_type INTEGER NOT NULL, -- 1:固定金额 2:百分比
discount_value DECIMAL(18,2) NOT NULL, -- 优惠值
min_order_amount DECIMAL(18,2) DEFAULT 0, -- 最低消费
max_discount_amount DECIMAL(18,2), -- 最大优惠金额（折扣券用）
total_quantity INTEGER NOT NULL, -- 总数量
received_quantity INTEGER DEFAULT 0, -- 已领取数量
used_quantity INTEGER DEFAULT 0, -- 已使用数量
valid_start_time TIMESTAMP WITH TIME ZONE NOT NULL,
valid_end_time TIMESTAMP WITH TIME ZONE NOT NULL,
status INTEGER NOT NULL DEFAULT 1, -- 1:正常 2:停用
description TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_coupons_merchant_id ON coupons(merchant_id);
CREATE INDEX idx_coupons_status ON coupons(status);
```
#### user_coupons（用户优惠券表）
```sql
CREATE TABLE user_coupons (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id),
coupon_id UUID NOT NULL REFERENCES coupons(id),
status INTEGER NOT NULL DEFAULT 1, -- 1:未使用 2:已使用 3:已过期
used_order_id UUID REFERENCES orders(id),
received_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
used_at TIMESTAMP WITH TIME ZONE,
expired_at TIMESTAMP WITH TIME ZONE NOT NULL
);
CREATE INDEX idx_user_coupons_user_id ON user_coupons(user_id);
CREATE INDEX idx_user_coupons_coupon_id ON user_coupons(coupon_id);
CREATE INDEX idx_user_coupons_status ON user_coupons(status);
```
### 2.9 评价管理
#### reviews（评价表）
```sql
CREATE TABLE reviews (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
order_id UUID NOT NULL REFERENCES orders(id),
user_id UUID NOT NULL REFERENCES users(id),
merchant_id UUID NOT NULL REFERENCES merchants(id),
rating INTEGER NOT NULL, -- 评分 1-5
taste_rating INTEGER, -- 口味评分
package_rating INTEGER, -- 包装评分
delivery_rating INTEGER, -- 配送评分
content TEXT,
images JSONB, -- 评价图片
is_anonymous BOOLEAN DEFAULT FALSE,
reply_content TEXT, -- 商家回复
reply_at TIMESTAMP WITH TIME ZONE,
status INTEGER NOT NULL DEFAULT 1, -- 1:正常 2:隐藏
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_reviews_order_id ON reviews(order_id);
CREATE INDEX idx_reviews_user_id ON reviews(user_id);
CREATE INDEX idx_reviews_merchant_id ON reviews(merchant_id);
```
### 2.10 系统管理
#### system_users（系统用户表）
```sql
CREATE TABLE system_users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID REFERENCES tenants(id), -- NULL表示平台管理员
merchant_id UUID REFERENCES merchants(id), -- NULL表示租户管理员
username VARCHAR(50) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
real_name VARCHAR(50),
phone VARCHAR(20),
email VARCHAR(100),
role_id UUID REFERENCES roles(id),
status INTEGER NOT NULL DEFAULT 1,
last_login_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_system_users_username ON system_users(username);
CREATE INDEX idx_system_users_tenant_id ON system_users(tenant_id);
```
#### roles（角色表）
```sql
CREATE TABLE roles (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID REFERENCES tenants(id),
name VARCHAR(50) NOT NULL,
code VARCHAR(50) NOT NULL,
description TEXT,
permissions JSONB, -- 权限列表
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_roles_tenant_id ON roles(tenant_id);
```
#### operation_logs（操作日志表）
```sql
CREATE TABLE operation_logs (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID REFERENCES tenants(id),
user_id UUID,
user_type VARCHAR(20), -- system_user, merchant_user, customer
module VARCHAR(50), -- 模块
action VARCHAR(50), -- 操作
description TEXT,
ip_address VARCHAR(50),
user_agent TEXT,
request_data JSONB,
response_data JSONB,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_operation_logs_tenant_id ON operation_logs(tenant_id);
CREATE INDEX idx_operation_logs_user_id ON operation_logs(user_id);
CREATE INDEX idx_operation_logs_created_at ON operation_logs(created_at);
```
## 3. 数据库索引策略
### 3.1 主键索引
- 所有表使用UUID作为主键，自动创建主键索引
### 3.2 外键索引
- 所有外键字段创建索引，提升关联查询性能
### 3.3 业务索引
- 订单号、支付单号等唯一业务字段创建唯一索引
- 状态字段创建普通索引
- 时间字段（created_at）创建索引，支持时间范围查询
### 3.4 复合索引
```sql
-- 订单查询常用复合索引
CREATE INDEX idx_orders_merchant_status_created ON orders(merchant_id, status, created_at DESC);
-- 用户订单查询
CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at DESC);
```
### 3.5 地理位置索引
```sql
-- 使用PostGIS扩展支持地理位置查询
CREATE EXTENSION IF NOT EXISTS postgis;
-- 门店位置索引
CREATE INDEX idx_merchant_stores_location ON merchant_stores
USING GIST(ST_MakePoint(longitude, latitude));
```
## 4. 数据库优化
### 4.1 分区策略
```sql
-- 订单表按月分区
CREATE TABLE orders_2024_01 PARTITION OF orders
FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
CREATE TABLE orders_2024_02 PARTITION OF orders
FOR VALUES FROM ('2024-02-01') TO ('2024-03-01');
```
### 4.2 物化视图
```sql
-- 商家统计物化视图
CREATE MATERIALIZED VIEW merchant_statistics AS
SELECT
m.id as merchant_id,
m.name,
COUNT(DISTINCT o.id) as total_orders,
SUM(o.actual_amount) as total_revenue,
AVG(r.rating) as avg_rating
FROM merchants m
LEFT JOIN orders o ON m.id = o.merchant_id AND o.status = 6
LEFT JOIN reviews r ON m.id = r.merchant_id
GROUP BY m.id, m.name;
CREATE UNIQUE INDEX ON merchant_statistics(merchant_id);
```
### 4.3 查询优化建议
- 避免SELECT *，只查询需要的字段
- 使用EXPLAIN分析查询计划
- 合理使用JOIN，避免过多关联
- 大数据量查询使用分页
- 使用prepared statement防止SQL注入
## 5. 数据备份策略
### 5.1 备份方案
- **全量备份**：每天凌晨2点执行
- **增量备份**：每4小时执行一次
- **WAL归档**：实时归档，支持PITR
### 5.2 备份脚本示例
```bash
#!/bin/bash
# 全量备份
pg_dump -h localhost -U postgres -d takeout_saas -F c -f /backup/full_$(date +%Y%m%d).dump
# 保留最近30天的备份
find /backup -name "full_*.dump" -mtime +30 -delete
```
## 6. 数据迁移
### 6.1 EF Core Migrations
```bash
# 添加迁移
dotnet ef migrations add InitialCreate --project TakeoutSaaS.Infrastructure
# 更新数据库
dotnet ef database update --project TakeoutSaaS.Infrastructure
```
### 6.2 版本控制
- 所有数据库变更通过Migration管理
- Migration文件纳入版本控制
- 生产环境变更需要审核

885
Document/04_API接口设计.md Normal file
View File

@@ -0,0 +1,885 @@
# 外卖SaaS系统 - API接口设计
## 1. API设计规范
### 1.1 RESTful规范
- 使用标准HTTP方法：GET、POST、PUT、DELETE、PATCH
- URL使用名词复数形式，如：`/api/orders`
- 使用HTTP状态码表示请求结果
- 版本控制：`/api/v1/orders`
### 1.2 请求规范
- **Content-Type**：`application/json`
- **认证方式**：Bearer Token (JWT)
- **租户识别**：通过Header `X-Tenant-Id` 或从Token中解析
### 1.3 响应规范
```json
{
"success": true,
"code": 200,
"message": "操作成功",
"data": {},
"timestamp": "2024-01-01T12:00:00Z"
}
```
### 1.4 错误响应
```json
{
"success": false,
"code": 400,
"message": "参数错误",
"errors": [
{
"field": "phone",
"message": "手机号格式不正确"
}
],
"timestamp": "2024-01-01T12:00:00Z"
}
```
### 1.5 HTTP状态码
- **200 OK**：请求成功
- **201 Created**：创建成功
- **204 No Content**：删除成功
- **400 Bad Request**：参数错误
- **401 Unauthorized**：未认证
- **403 Forbidden**：无权限
- **404 Not Found**：资源不存在
- **409 Conflict**：资源冲突
- **422 Unprocessable Entity**：业务逻辑错误
- **500 Internal Server Error**：服务器错误
### 1.6 分页规范
```json
// 请求参数
{
"pageIndex": 1,
"pageSize": 20,
"sortBy": "createdAt",
"sortOrder": "desc"
}
// 响应格式
{
"success": true,
"data": {
"items": [],
"totalCount": 100,
"pageIndex": 1,
"pageSize": 20,
"totalPages": 5
}
}
```
## 2. 认证授权接口
### 2.1 用户登录
```http
POST /api/v1/auth/login
Content-Type: application/json
{
"phone": "13800138000",
"password": "password123",
"loginType": "customer" // customer, merchant, system
}
Response:
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"expiresIn": 7200,
"tokenType": "Bearer",
"userInfo": {
"id": "uuid",
"phone": "13800138000",
"nickname": "张三",
"avatar": "https://..."
}
}
}
```
### 2.2 刷新Token
```http
POST /api/v1/auth/refresh
Content-Type: application/json
{
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
Response:
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"expiresIn": 7200
}
}
```
### 2.3 用户注册
```http
POST /api/v1/auth/register
Content-Type: application/json
{
"phone": "13800138000",
"password": "password123",
"verificationCode": "123456",
"nickname": "张三"
}
```
### 2.4 发送验证码
```http
POST /api/v1/auth/send-code
Content-Type: application/json
{
"phone": "13800138000",
"type": "register" // register, login, reset_password
}
```
## 3. 商家管理接口
### 3.1 获取商家列表
```http
GET /api/v1/merchants?pageIndex=1&pageSize=20&keyword=&status=1
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"items": [
{
"id": "uuid",
"name": "美味餐厅",
"logo": "https://...",
"rating": 4.5,
"totalSales": 1000,
"status": 1,
"createdAt": "2024-01-01T12:00:00Z"
}
],
"totalCount": 50,
"pageIndex": 1,
"pageSize": 20
}
}
```
### 3.2 获取商家详情
```http
GET /api/v1/merchants/{id}
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"id": "uuid",
"name": "美味餐厅",
"logo": "https://...",
"description": "专注美食20年",
"contactPhone": "400-123-4567",
"rating": 4.5,
"totalSales": 1000,
"status": 1,
"stores": [
{
"id": "uuid",
"name": "总店",
"address": "北京市朝阳区...",
"phone": "010-12345678"
}
]
}
}
```
### 3.3 创建商家
```http
POST /api/v1/merchants
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "美味餐厅",
"logo": "https://...",
"description": "专注美食20年",
"contactPhone": "400-123-4567",
"contactPerson": "张三",
"businessLicense": "91110000..."
}
```
### 3.4 更新商家信息
```http
PUT /api/v1/merchants/{id}
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "美味餐厅",
"logo": "https://...",
"description": "专注美食20年"
}
```
### 3.5 删除商家
```http
DELETE /api/v1/merchants/{id}
Authorization: Bearer {token}
```
## 4. 菜品管理接口
### 4.1 获取菜品列表
```http
GET /api/v1/dishes?merchantId={merchantId}&categoryId={categoryId}&keyword=&status=1&pageIndex=1&pageSize=20
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"items": [
{
"id": "uuid",
"name": "宫保鸡丁",
"description": "经典川菜",
"image": "https://...",
"price": 38.00,
"originalPrice": 48.00,
"salesCount": 500,
"rating": 4.8,
"status": 1,
"tags": ["热销", "招牌菜"]
}
],
"totalCount": 100
}
}
```
### 4.2 获取菜品详情
```http
GET /api/v1/dishes/{id}
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"id": "uuid",
"name": "宫保鸡丁",
"description": "经典川菜，选用优质鸡肉...",
"image": "https://...",
"price": 38.00,
"originalPrice": 48.00,
"unit": "份",
"stock": 100,
"salesCount": 500,
"rating": 4.8,
"status": 1,
"tags": ["热销", "招牌菜"],
"specs": [
{
"id": "uuid",
"name": "大份",
"price": 48.00,
"stock": 50
},
{
"id": "uuid",
"name": "小份",
"price": 28.00,
"stock": 50
}
]
}
}
```
### 4.3 创建菜品
```http
POST /api/v1/dishes
Authorization: Bearer {token}
Content-Type: application/json
{
"merchantId": "uuid",
"categoryId": "uuid",
"name": "宫保鸡丁",
"description": "经典川菜",
"image": "https://...",
"price": 38.00,
"originalPrice": 48.00,
"unit": "份",
"stock": 100,
"tags": ["热销", "招牌菜"],
"specs": [
{
"name": "大份",
"price": 48.00,
"stock": 50
}
]
}
```
### 4.4 更新菜品
```http
PUT /api/v1/dishes/{id}
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "宫保鸡丁",
"price": 38.00,
"stock": 100,
"status": 1
}
```
### 4.5 批量上下架
```http
PATCH /api/v1/dishes/batch-status
Authorization: Bearer {token}
Content-Type: application/json
{
"dishIds": ["uuid1", "uuid2"],
"status": 1 // 1:上架 2:下架
}
```
## 5. 订单管理接口
### 5.1 创建订单
```http
POST /api/v1/orders
Authorization: Bearer {token}
Content-Type: application/json
{
"merchantId": "uuid",
"storeId": "uuid",
"items": [
{
"dishId": "uuid",
"specId": "uuid",
"quantity": 2,
"price": 38.00
}
],
"deliveryAddress": {
"contactName": "张三",
"contactPhone": "13800138000",
"address": "北京市朝阳区...",
"latitude": 39.9042,
"longitude": 116.4074
},
"remark": "少辣",
"couponId": "uuid"
}
Response:
{
"success": true,
"data": {
"orderId": "uuid",
"orderNo": "202401010001",
"totalAmount": 76.00,
"deliveryFee": 5.00,
"discountAmount": 10.00,
"actualAmount": 71.00,
"paymentInfo": {
"paymentNo": "PAY202401010001",
"qrCode": "https://..." // 支付二维码
}
}
}
```
### 5.2 获取订单列表
```http
GET /api/v1/orders?status=&startDate=&endDate=&pageIndex=1&pageSize=20
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"items": [
{
"id": "uuid",
"orderNo": "202401010001",
"merchantName": "美味餐厅",
"totalAmount": 76.00,
"actualAmount": 71.00,
"status": 2,
"statusText": "待接单",
"createdAt": "2024-01-01T12:00:00Z",
"items": [
{
"dishName": "宫保鸡丁",
"specName": "大份",
"quantity": 2,
"price": 38.00
}
]
}
],
"totalCount": 50
}
}
```
### 5.3 获取订单详情
```http
GET /api/v1/orders/{id}
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"id": "uuid",
"orderNo": "202401010001",
"merchant": {
"id": "uuid",
"name": "美味餐厅",
"phone": "400-123-4567"
},
"items": [
{
"dishName": "宫保鸡丁",
"dishImage": "https://...",
"specName": "大份",
"quantity": 2,
"price": 38.00,
"amount": 76.00
}
],
"deliveryAddress": {
"contactName": "张三",
"contactPhone": "13800138000",
"address": "北京市朝阳区..."
},
"dishAmount": 76.00,
"deliveryFee": 5.00,
"packageFee": 2.00,
"discountAmount": 10.00,
"totalAmount": 83.00,
"actualAmount": 73.00,
"status": 2,
"statusText": "待接单",
"paymentStatus": 1,
"paymentMethod": "wechat",
"estimatedDeliveryTime": "2024-01-01T13:00:00Z",
"createdAt": "2024-01-01T12:00:00Z",
"paidAt": "2024-01-01T12:05:00Z",
"remark": "少辣",
"timeline": [
{
"status": "created",
"statusText": "订单创建",
"time": "2024-01-01T12:00:00Z"
},
{
"status": "paid",
"statusText": "支付成功",
"time": "2024-01-01T12:05:00Z"
}
]
}
}
```
### 5.4 商家接单
```http
POST /api/v1/orders/{id}/accept
Authorization: Bearer {token}
Content-Type: application/json
{
"estimatedTime": 30 // 预计制作时长（分钟）
}
```
### 5.5 开始制作
```http
POST /api/v1/orders/{id}/cooking
Authorization: Bearer {token}
```
### 5.6 订单完成
```http
POST /api/v1/orders/{id}/complete
Authorization: Bearer {token}
```
### 5.7 取消订单
```http
POST /api/v1/orders/{id}/cancel
Authorization: Bearer {token}
Content-Type: application/json
{
"reason": "用户取消",
"cancelBy": "customer" // customer, merchant, system
}
```
## 6. 支付接口
### 6.1 创建支付
```http
POST /api/v1/payments
Authorization: Bearer {token}
Content-Type: application/json
{
"orderId": "uuid",
"paymentMethod": "wechat", // wechat, alipay, balance
"amount": 71.00
}
Response:
{
"success": true,
"data": {
"paymentNo": "PAY202401010001",
"qrCode": "https://...", // 支付二维码
"deepLink": "weixin://..." // 唤起支付的深度链接
}
}
```
### 6.2 查询支付状态
```http
GET /api/v1/payments/{paymentNo}
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"paymentNo": "PAY202401010001",
"status": 2, // 0:待支付 1:支付中 2:成功 3:失败
"amount": 71.00,
"paidAt": "2024-01-01T12:05:00Z"
}
}
```
### 6.3 支付回调（第三方调用）
```http
POST /api/v1/payments/callback/wechat
Content-Type: application/json
{
"out_trade_no": "PAY202401010001",
"transaction_id": "4200001234567890",
"total_fee": 7100,
"result_code": "SUCCESS"
}
```
### 6.4 申请退款
```http
POST /api/v1/refunds
Authorization: Bearer {token}
Content-Type: application/json
{
"orderId": "uuid",
"amount": 71.00,
"reason": "不想要了"
}
```
## 7. 配送管理接口
### 7.1 获取配送任务列表
```http
GET /api/v1/delivery-tasks?status=&driverId=&pageIndex=1&pageSize=20
Authorization: Bearer {token}
```
### 7.2 分配配送员
```http
POST /api/v1/delivery-tasks/{id}/assign
Authorization: Bearer {token}
Content-Type: application/json
{
"driverId": "uuid"
}
```
### 7.3 配送员接单
```http
POST /api/v1/delivery-tasks/{id}/accept
Authorization: Bearer {token}
```
### 7.4 确认取餐
```http
POST /api/v1/delivery-tasks/{id}/pickup
Authorization: Bearer {token}
```
### 7.5 确认送达
```http
POST /api/v1/delivery-tasks/{id}/deliver
Authorization: Bearer {token}
Content-Type: application/json
{
"deliveryCode": "123456" // 取餐码
}
```
### 7.6 更新配送员位置
```http
POST /api/v1/delivery-drivers/location
Authorization: Bearer {token}
Content-Type: application/json
{
"latitude": 39.9042,
"longitude": 116.4074
}
```
## 8. 营销管理接口
### 8.1 获取优惠券列表
```http
GET /api/v1/coupons?merchantId=&status=1&pageIndex=1&pageSize=20
Authorization: Bearer {token}
```
### 8.2 领取优惠券
```http
POST /api/v1/coupons/{id}/receive
Authorization: Bearer {token}
```
### 8.3 获取用户优惠券
```http
GET /api/v1/user-coupons?status=1&pageIndex=1&pageSize=20
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"items": [
{
"id": "uuid",
"couponName": "满50减10",
"discountValue": 10.00,
"minOrderAmount": 50.00,
"status": 1,
"expiredAt": "2024-12-31T23:59:59Z"
}
]
}
}
```
### 8.4 获取可用优惠券
```http
GET /api/v1/user-coupons/available?merchantId={merchantId}&amount={amount}
Authorization: Bearer {token}
```
## 9. 评价管理接口
### 9.1 创建评价
```http
POST /api/v1/reviews
Authorization: Bearer {token}
Content-Type: application/json
{
"orderId": "uuid",
"rating": 5,
"tasteRating": 5,
"packageRating": 5,
"deliveryRating": 5,
"content": "非常好吃",
"images": ["https://...", "https://..."],
"isAnonymous": false
}
```
### 9.2 获取商家评价列表
```http
GET /api/v1/reviews?merchantId={merchantId}&rating=&pageIndex=1&pageSize=20
Response:
{
"success": true,
"data": {
"items": [
{
"id": "uuid",
"userName": "张三",
"userAvatar": "https://...",
"rating": 5,
"content": "非常好吃",
"images": ["https://..."],
"createdAt": "2024-01-01T12:00:00Z",
"replyContent": "感谢支持",
"replyAt": "2024-01-01T13:00:00Z"
}
],
"totalCount": 100,
"statistics": {
"avgRating": 4.8,
"totalReviews": 100,
"rating5Count": 80,
"rating4Count": 15,
"rating3Count": 3,
"rating2Count": 1,
"rating1Count": 1
}
}
}
```
### 9.3 商家回复评价
```http
POST /api/v1/reviews/{id}/reply
Authorization: Bearer {token}
Content-Type: application/json
{
"replyContent": "感谢您的支持"
}
```
## 10. 数据统计接口
### 10.1 商家数据概览
```http
GET /api/v1/statistics/merchant/overview?merchantId={merchantId}&startDate=&endDate=
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"totalOrders": 1000,
"totalRevenue": 50000.00,
"avgOrderAmount": 50.00,
"completionRate": 0.95,
"todayOrders": 50,
"todayRevenue": 2500.00,
"orderTrend": [
{
"date": "2024-01-01",
"orders": 50,
"revenue": 2500.00
}
],
"topDishes": [
{
"dishId": "uuid",
"dishName": "宫保鸡丁",
"salesCount": 200,
"revenue": 7600.00
}
]
}
}
```
### 10.2 平台数据大盘
```http
GET /api/v1/statistics/platform/dashboard?startDate=&endDate=
Authorization: Bearer {token}
Response:
{
"success": true,
"data": {
"totalMerchants": 100,
"totalUsers": 10000,
"totalOrders": 50000,
"totalRevenue": 2500000.00,
"activeMerchants": 80,
"activeUsers": 5000,
"todayOrders": 500,
"todayRevenue": 25000.00
}
}
```
## 11. 文件上传接口
### 11.1 上传图片
```http
POST /api/v1/files/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data
file: <binary>
type: dish_image // dish_image, merchant_logo, user_avatar, review_image
Response:
{
"success": true,
"data": {
"url": "https://cdn.example.com/images/xxx.jpg",
"fileName": "xxx.jpg",
"fileSize": 102400
}
}
```
## 12. WebSocket实时通知
### 12.1 连接WebSocket
```javascript
// 连接地址
ws://api.example.com/ws?token={jwt_token}
// 订阅主题
{
"action": "subscribe",
"topics": ["order.new", "order.status", "delivery.location"]
}
// 接收消息
{
"topic": "order.new",
"data": {
"orderId": "uuid",
"orderNo": "202401010001",
"merchantId": "uuid"
},
"timestamp": "2024-01-01T12:00:00Z"
}
```
### 12.2 消息主题
- `order.new`：新订单通知
- `order.status`：订单状态变更
- `delivery.location`：配送员位置更新
- `payment.success`：支付成功通知

1058
Document/05_部署运维.md Normal file
View File

File diff suppressed because it is too large Load Diff

395
Document/06_开发规范.md Normal file
View File

@@ -0,0 +1,395 @@
# 外卖SaaS系统 - 开发规范
## 1. 代码规范
### 1.1 命名规范
#### C#命名规范
```csharp
// 类名：PascalCase
public class OrderService { }
// 接口：I + PascalCase
public interface IOrderRepository { }
// 方法：PascalCase
public async Task<Order> CreateOrderAsync() { }
// 私有字段：_camelCase
private readonly IOrderRepository _orderRepository;
// 公共属性：PascalCase
public string OrderNo { get; set; }
// 局部变量：camelCase
var orderTotal = 100.00m;
// 常量：PascalCase
public const int MaxOrderItems = 50;
// 枚举：PascalCase
public enum OrderStatus
{
Pending = 1,
Confirmed = 2,
Completed = 3
}
```
#### 数据库命名规范
```sql
-- 表名：小写，下划线分隔，复数
orders
order_items
merchant_stores
-- 字段名：小写，下划线分隔
order_no
created_at
total_amount
-- 索引：idx_表名_字段名
idx_orders_merchant_id
idx_orders_created_at
-- 外键：fk_表名_引用表名
fk_orders_merchants
```
### 1.2 代码组织
#### 项目结构
```
TakeoutSaaS/
├── src/
│ ├── TakeoutSaaS.Api/ # Web API层
│ │ ├── Controllers/ # 控制器
│ │ ├── Filters/ # 过滤器
│ │ ├── Middleware/ # 中间件
│ │ ├── Models/ # DTO模型
│ │ └── Program.cs
│ ├── TakeoutSaaS.Application/ # 应用层
│ │ ├── Services/ # 应用服务
│ │ ├── DTOs/ # 数据传输对象
│ │ ├── Interfaces/ # 服务接口
│ │ ├── Validators/ # 验证器
│ │ ├── Mappings/ # 对象映射
│ │ └── Commands/ # CQRS命令
│ │ └── Queries/ # CQRS查询
│ ├── TakeoutSaaS.Domain/ # 领域层
│ │ ├── Entities/ # 实体
│ │ ├── ValueObjects/ # 值对象
│ │ ├── Enums/ # 枚举
│ │ ├── Events/ # 领域事件
│ │ └── Interfaces/ # 仓储接口
│ ├── TakeoutSaaS.Infrastructure/ # 基础设施层
│ │ ├── Data/ # 数据访问
│ │ │ ├── EFCore/ # EF Core实现
│ │ │ ├── Dapper/ # Dapper实现
│ │ │ └── Repositories/ # 仓储实现
│ │ ├── Cache/ # 缓存实现
│ │ ├── MessageQueue/ # 消息队列
│ │ └── ExternalServices/ # 外部服务
│ └── TakeoutSaaS.Shared/ # 共享层
│ ├── Constants/ # 常量
│ ├── Exceptions/ # 异常
│ ├── Extensions/ # 扩展方法
│ └── Results/ # 统一返回结果
├── tests/
│ ├── TakeoutSaaS.UnitTests/ # 单元测试
│ ├── TakeoutSaaS.IntegrationTests/ # 集成测试
│ └── TakeoutSaaS.PerformanceTests/ # 性能测试
└── docs/ # 文档
```
### 1.3 代码注释
```csharp
/// <summary>
/// 订单服务接口
/// </summary>
public interface IOrderService
{
/// <summary>
/// 创建订单
/// </summary>
/// <param name="request">订单创建请求</param>
/// <returns>订单信息</returns>
/// <exception cref="BusinessException">业务异常</exception>
Task<OrderDto> CreateOrderAsync(CreateOrderRequest request);
}
// 复杂业务逻辑添加注释
public async Task<decimal> CalculateOrderAmount(Order order)
{
// 1. 计算菜品总金额
var dishAmount = order.Items.Sum(x => x.Price * x.Quantity);
// 2. 计算配送费（距离 > 3km，每公里加收2元）
var deliveryFee = CalculateDeliveryFee(order.Distance);
// 3. 应用优惠券折扣
var discount = await ApplyCouponDiscountAsync(order.CouponId, dishAmount);
// 4. 计算最终金额
return dishAmount + deliveryFee - discount;
}
```
### 1.4 异常处理
```csharp
// 自定义业务异常
public class BusinessException : Exception
{
public int ErrorCode { get; }
public BusinessException(int errorCode, string message)
: base(message)
{
ErrorCode = errorCode;
}
}
// 全局异常处理中间件
public class ExceptionHandlingMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<ExceptionHandlingMiddleware> _logger;
public async Task InvokeAsync(HttpContext context)
{
try
{
await _next(context);
}
catch (BusinessException ex)
{
_logger.LogWarning(ex, "业务异常：{Message}", ex.Message);
await HandleBusinessExceptionAsync(context, ex);
}
catch (Exception ex)
{
_logger.LogError(ex, "系统异常：{Message}", ex.Message);
await HandleSystemExceptionAsync(context, ex);
}
}
private static Task HandleBusinessExceptionAsync(HttpContext context, BusinessException ex)
{
context.Response.StatusCode = StatusCodes.Status422UnprocessableEntity;
return context.Response.WriteAsJsonAsync(new
{
success = false,
code = ex.ErrorCode,
message = ex.Message
});
}
}
// 使用示例
public async Task<Order> GetOrderAsync(Guid orderId)
{
var order = await _orderRepository.GetByIdAsync(orderId);
if (order == null)
{
throw new BusinessException(404, "订单不存在");
}
return order;
}
```
## 2. Git工作流
### 2.1 分支管理
```
main # 主分支，生产环境代码
├── develop # 开发分支
│ ├── feature/order-management # 功能分支
│ ├── feature/payment-integration # 功能分支
│ └── bugfix/order-calculation # 修复分支
└── hotfix/critical-bug # 紧急修复分支
```
### 2.2 分支命名规范
- **功能分支**：`feature/功能名称`（如：`feature/order-management`）
- **修复分支**：`bugfix/问题描述`（如：`bugfix/order-calculation`）
- **紧急修复**：`hotfix/问题描述`（如：`hotfix/payment-error`）
- **发布分支**：`release/版本号`（如：`release/v1.0.0`）
### 2.3 提交信息规范
```bash
# 格式：<type>(<scope>): <subject>
# type类型：
# feat: 新功能
# fix: 修复bug
# docs: 文档更新
# style: 代码格式调整
# refactor: 重构
# perf: 性能优化
# test: 测试相关
# chore: 构建/工具相关
# 示例
git commit -m "feat(order): 添加订单创建功能"
git commit -m "fix(payment): 修复支付回调处理错误"
git commit -m "docs(api): 更新API文档"
git commit -m "refactor(service): 重构订单服务"
```
### 2.4 工作流程
```bash
# 1. 从develop创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/order-management
# 2. 开发并提交
git add .
git commit -m "feat(order): 添加订单创建功能"
# 3. 推送到远程
git push origin feature/order-management
# 4. 创建Pull Request到develop分支
# 5. 代码审查通过后合并
# 6. 删除功能分支
git branch -d feature/order-management
git push origin --delete feature/order-management
```
## 3. 代码审查
### 3.1 审查清单
- [ ] 代码符合命名规范
- [ ] 代码逻辑清晰，易于理解
- [ ] 适当的注释和文档
- [ ] 异常处理完善
- [ ] 单元测试覆盖
- [ ] 性能考虑（N+1查询、大数据量处理）
- [ ] 安全性考虑（SQL注入、XSS、权限校验）
- [ ] 日志记录完善
- [ ] 无硬编码配置
- [ ] 符合SOLID原则
### 3.2 审查重点
```csharp
// ❌ 不好的实践
public class OrderService
{
public Order CreateOrder(CreateOrderRequest request)
{
// 直接在服务层操作DbContext
var order = new Order();
_dbContext.Orders.Add(order);
_dbContext.SaveChanges();
// 硬编码配置
var deliveryFee = 5.0m;
// 没有异常处理
// 没有日志记录
return order;
}
}
// ✅ 好的实践
public class OrderService : IOrderService
{
private readonly IOrderRepository _orderRepository;
private readonly IUnitOfWork _unitOfWork;
private readonly ILogger<OrderService> _logger;
private readonly IOptions<OrderSettings> _settings;
public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request)
{
try
{
// 参数验证
if (request == null)
throw new ArgumentNullException(nameof(request));
_logger.LogInformation("创建订单：{@Request}", request);
// 业务逻辑
var order = new Order
{
// ... 初始化订单
DeliveryFee = _settings.Value.DefaultDeliveryFee
};
// 使用仓储
await _orderRepository.AddAsync(order);
await _unitOfWork.SaveChangesAsync();
_logger.LogInformation("订单创建成功：{OrderId}", order.Id);
return _mapper.Map<OrderDto>(order);
}
catch (Exception ex)
{
_logger.LogError(ex, "创建订单失败：{@Request}", request);
throw;
}
}
}
```
## 4. 单元测试规范
### 4.1 测试命名
- 命名格式：`MethodName_Scenario_ExpectedResult`
- 测试覆盖率要求：核心业务逻辑 >= 80%
### 4.2 测试示例
```csharp
[Fact]
public async Task CreateOrder_ValidRequest_ReturnsOrderDto()
{
// Arrange
var request = new CreateOrderRequest { /* ... */ };
// Act
var result = await _orderService.CreateOrderAsync(request);
// Assert
result.Should().NotBeNull();
result.OrderNo.Should().NotBeNullOrEmpty();
}
```
## 5. 性能优化规范
### 5.1 数据库查询优化
- 避免N+1查询，使用Include预加载
- 大数据量查询使用Dapper
- 合理使用索引
### 5.2 缓存策略
- 商家信息：30分钟
- 菜品信息：15分钟
- 配置信息：1小时
- 用户会话：2小时
## 6. 文档要求
### 6.1 代码文档
- 所有公共API必须有XML文档注释
- 复杂业务逻辑添加详细注释
- README.md说明项目结构和运行方式
### 6.2 变更日志
维护CHANGELOG.md记录版本变更

321
Document/07_系统架构图.md Normal file
View File

@@ -0,0 +1,321 @@
# 外卖SaaS系统 - 系统架构图
## 1. 整体架构图
```
┌─────────────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ Web管理端 │ │ Web用户端 │ │ 小程序端（用户） │ │
│ │ (React/Vue) │ │ (React/Vue) │ │ (微信/支付宝) │ │
│ └──────────────┘ └──────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ API网关层 │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ Nginx / API Gateway │ │
│ │ - 路由转发 │ │
│ │ - 负载均衡 │ │
│ │ - 限流熔断 │ │
│ │ - SSL终止 │ │
│ └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 应用服务层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 租户服务 │ │ 商家服务 │ │ 菜品服务 │ │
│ │ - 租户管理 │ │ - 商家管理 │ │ - 菜品管理 │ │
│ │ - 权限管理 │ │ - 门店管理 │ │ - 分类管理 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 订单服务 │ │ 配送服务 │ │ 用户服务 │ │
│ │ - 订单管理 │ │ - 配送员管理 │ │ - 用户管理 │ │
│ │ - 订单流转 │ │ - 任务分配 │ │ - 地址管理 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 支付服务 │ │ 营销服务 │ │ 通知服务 │ │
│ │ - 支付处理 │ │ - 优惠券 │ │ - 短信通知 │ │
│ │ - 退款处理 │ │ - 活动管理 │ │ - 推送通知 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 基础设施层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ RabbitMQ │ │
│ │ - 主数据库 │ │ - 缓存 │ │ - 消息队列 │ │
│ │ - 主从复制 │ │ - 会话存储 │ │ - 异步任务 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MinIO/OSS │ │ Elasticsearch│ │ Prometheus │ │
│ │ - 对象存储 │ │ - 日志存储 │ │ - 监控告警 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
## 2. 应用分层架构
```
┌─────────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ (表现层) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ TakeoutSaaS.Api │ │
│ │ - Controllers (控制器) │ │
│ │ - Filters (过滤器) │ │
│ │ - Middleware (中间件) │ │
│ │ - Models (DTO模型) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Application Layer │
│ (应用层) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ TakeoutSaaS.Application │ │
│ │ - Services (应用服务) │ │
│ │ - DTOs (数据传输对象) │ │
│ │ - Interfaces (服务接口) │ │
│ │ - Validators (验证器) │ │
│ │ - Mappings (对象映射) │ │
│ │ - Commands/Queries (CQRS) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Domain Layer │
│ (领域层) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ TakeoutSaaS.Domain │ │
│ │ - Entities (实体) │ │
│ │ - ValueObjects (值对象) │ │
│ │ - Enums (枚举) │ │
│ │ - Events (领域事件) │ │
│ │ - Interfaces (仓储接口) │ │
│ │ - Specifications (规约) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Infrastructure Layer │
│ (基础设施层) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ TakeoutSaaS.Infrastructure │ │
│ │ - Data (数据访问) │ │
│ │ - EFCore (EF Core实现) │ │
│ │ - Dapper (Dapper实现) │ │
│ │ - Repositories (仓储实现) │ │
│ │ - Cache (缓存实现) │ │
│ │ - MessageQueue (消息队列) │ │
│ │ - ExternalServices (外部服务) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## 3. 订单处理流程图
```
用户下单 → 创建订单 → 支付 → 商家接单 → 制作 → 配送 → 完成
│ │ │ │ │ │ │
│ │ │ │ │ │ └─→ 订单完成
│ │ │ │ │ └─→ 配送中
│ │ │ │ └─→ 制作中
│ │ │ └─→ 待制作
│ │ └─→ 待接单
│ └─→ 待支付
└─→ 订单创建
取消流程：
用户取消 ──→ 退款处理 ──→ 订单取消
商家拒单 ──→ 退款处理 ──→ 订单取消
超时未支付 ──→ 自动取消
```
## 4. 数据流转图
```
┌──────────┐
│ 客户端 │
└────┬─────┘
│ HTTP Request
▼
┌──────────────────┐
│ API Gateway │
│ (Nginx) │
└────┬─────────────┘
│ 路由转发
▼
┌──────────────────┐
│ Web API │
│ - 认证授权 │
│ - 参数验证 │
└────┬─────────────┘
│ 调用服务
▼
┌──────────────────┐
│ Application │
│ Service │
│ - 业务逻辑 │
└────┬─────────────┘
│ 数据访问
▼
┌──────────────────┐ ┌──────────┐
│ Repository │────→│ Cache │
│ - EF Core │ │ (Redis) │
│ - Dapper │ └──────────┘
└────┬─────────────┘
│ SQL查询
▼
┌──────────────────┐
│ PostgreSQL │
│ Database │
└──────────────────┘
```
## 5. 多租户数据隔离架构
```
┌─────────────────────────────────────────────────┐
│ 租户识别中间件 │
│ - 从JWT Token解析租户ID │
│ - 从HTTP Header获取租户ID │
└─────────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 租户上下文 │
│ - 当前租户ID │
│ - 租户配置信息 │
└─────────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 数据访问层 │
│ - 自动添加租户ID过滤 │
│ - 全局查询过滤器 │
└─────────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 数据库 │
│ 租户A数据 │ 租户B数据 │ 租户C数据 │
│ (tenant_id = A) (tenant_id = B) (tenant_id = C)│
└─────────────────────────────────────────────────┘
```
## 6. 缓存架构
```
┌──────────────┐
│ Application │
└──────┬───────┘
│
▼
┌──────────────────────────────────┐
│ Cache Aside Pattern │
│ 1. 查询缓存 │
│ 2. 缓存未命中，查询数据库 │
│ 3. 写入缓存 │
└──────┬───────────────────────────┘
│
├─→ L1 Cache (Memory Cache)
│ - 进程内缓存
│ - 热点数据
│
└─→ L2 Cache (Redis)
- 分布式缓存
- 会话数据
- 共享数据
```
## 7. 消息队列架构
```
┌──────────────┐
│ Producer │
│ (订单服务) │
└──────┬───────┘
│ 发布事件
▼
┌──────────────────┐
│ RabbitMQ │
│ Exchange │
└──────┬───────────┘
│
├─→ Queue: order.created
│ └─→ Consumer: 通知服务
│
├─→ Queue: order.paid
│ └─→ Consumer: 库存服务
│
└─→ Queue: order.completed
└─→ Consumer: 统计服务
```
## 8. 部署架构
```
┌─────────────────────────────────────────────────┐
│ 负载均衡器 (Nginx) │
└─────────────┬───────────────────────────────────┘
│
┌───────┴───────┐
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ API 1 │ │ API 2 │
│ (容器) │ │ (容器) │
└────┬─────┘ └────┬─────┘
│ │
└───────┬───────┘
│
┌───────┴────────┬──────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│PostgreSQL│ │ Redis │ │ RabbitMQ │
│ 主从 │ │ 哨兵 │ │ 集群 │
└──────────┘ └──────────┘ └──────────┘
```
## 9. 监控架构
```
┌──────────────────────────────────────────┐
│ 应用程序 │
│ - 业务指标 │
│ - 性能指标 │
│ - 日志输出 │
└─────────┬────────────────────────────────┘
│
┌─────┴─────┬──────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│Metrics │ │ Logs │ │Traces │
│ │ │ │ │ │
└───┬────┘ └───┬────┘ └───┬────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────┐
│ Prometheus │
│ Elasticsearch │
│ Jaeger │
└─────────┬────────────────────┘
│
▼
┌──────────────────────────────┐
│ Grafana │
│ Kibana │
│ - 可视化仪表板 │
│ - 告警配置 │
└──────────────────────────────┘
```

145
Document/08_AI精简开发规范.md Normal file
View File

@@ -0,0 +1,145 @@
# 编程规范_FOR_AI（TakeoutSaaS） - 终极完全体
> **核心指令**：你是一个高级 .NET 架构师。本文件是你生成代码的最高宪法。当用户需求与本规范冲突时，请先提示用户，除非用户强制要求覆盖。
## 0. AI 交互核心约束 (元规则)
1. **语言**：必须使用**中文**回复和编写注释。
2. **文件完整性**：
* **严禁**随意删除现有代码逻辑。
* **严禁**修改文件编码（保持 UTF-8 无 BOM）。
* PowerShell 读取命令必须带 `-Encoding UTF8`。
3. **Git 原子性**：每个独立的功能点或 Bug 修复完成后，必须提示用户进行 Git 提交。
4. **无乱码承诺**：确保所有输出（控制台、日志、API响应）无乱码。
5. **不确定的处理**：如果你通过上下文找不到某些配置（如数据库连接串格式），**请直接询问用户**，不要瞎编。
## 1. 技术栈详细版本
| 组件 | 版本/选型 | 用途说明 |
| :--- | :--- | :--- |
| **Runtime** | .NET 10 | 核心运行时 |
| **API** | ASP.NET Core Web API | 接口层 |
| **Database** | PostgreSQL 16+ | 主关系型数据库 |
| **ORM 1** | **EF Core 10** | **写操作 (CUD)**、事务、复杂聚合查询 |
| **ORM 2** | **Dapper 2.1+** | **纯读操作 (R)**、复杂报表、大批量查询 |
| **Cache** | Redis 7.0+ | 分布式缓存、Session |
| **MQ** | RabbitMQ 3.12+ | 异步解耦 (MassTransit) |
| **Libs** | MediatR, Serilog, FluentValidation | CQRS, 日志, 验证 |
## 2. 命名与风格 (严格匹配)
* **C# 代码**：
* 类/接口/方法/属性：`PascalCase` (如 `OrderService`)
* **布尔属性**：必须加 `Is` 或 `Has` 前缀 (如 `IsDeleted`, `HasPayment`)
* 私有字段：`_camelCase` (如 `_orderRepository`)
* 参数/变量：`camelCase` (如 `orderId`)
* **PostgreSQL 数据库**：
* 表名：`snake_case` + **复数** (如 `merchant_orders`)
* 列名：`snake_case` (如 `order_no`, `is_active`)
* 主键：`id` (类型 `bigint`)
* **文件规则**：
* **一个文件一个类**。文件名必须与类名完全一致。
## 3. 分层架构 (Clean Architecture)
**你生成的代码必须严格归类到以下目录：**
* **`src/Api`**: 仅负责路由与 DTO 转换，**禁止**包含业务逻辑。
* **`src/Application`**: 业务编排层。必须使用 **CQRS** (`IRequestHandler`) 和 **Mediator**。
* **`src/Domain`**: 核心领域层。包含实体、枚举、领域异常。**禁止**依赖 EF Core 等外部库。
* **`src/Infrastructure`**: 基础设施层。实现仓储、数据库上下文、第三方服务。
## 4. 注释与文档
* **强制 XML 注释**：所有 `public` 的类、方法、属性必须有 `<summary>`。
* **步骤注释**：超过 5 行的业务逻辑，必须分步注释：
```csharp
// 1. 验证库存
// 2. 扣减余额
```
* **Swagger**：必须开启 JWT 鉴权按钮，Request/Response 示例必须清晰。
## 5. 异常处理 (防御性编程)
* **禁止空 Catch**：严禁 `catch (Exception) {}`，必须记录日志或抛出。
* **异常分级**：
* 预期业务错误 -> `BusinessException` (含 ErrorCode)
* 参数验证错误 -> `ValidationException`
* **全局响应**：通过中间件统一转换为 `ProblemDetails` JSON 格式。
## 6. 异步与日志
* **全异步**：所有 I/O 操作必须 `await`。**严禁** `.Result` 或 `.Wait()`。
* **结构化日志**：
* ❌ `_logger.LogInfo("订单 " + id + " 创建成功");`
* ✅ `_logger.LogInformation("订单 {OrderId} 创建成功", id);`
* **脱敏**：严禁打印密码、密钥、支付凭证等敏感信息。
## 7. 依赖注入 (DI)
* **构造函数注入**：统一使用构造函数注入。
* **禁止项**：
* ❌ 禁止使用 `[Inject]` 属性注入。
* ❌ 禁止使用 `ServiceLocator` (服务定位器模式)。
* ❌ 禁止在静态类中持有 ServiceProvider。
## 8. 数据访问规范 (重点执行)
### 8.1 Entity Framework Core (写/事务)
1. **无跟踪查询**：只读查询**必须**加 `.AsNoTracking()`。
2. **杜绝 N+1**：严禁在 `foreach` 循环中查询数据库。必须使用 `.Include()`。
3. **复杂查询**：关联表超过 2 层时，考虑使用 `.AsSplitQuery()`。
### 8.2 Dapper (读/报表)
1. **SQL 注入防御**：**严禁**拼接 SQL 字符串。必须使用参数化查询 (`@Param`)。
2. **字段映射**：注意 PostgreSQL (`snake_case`) 与 C# (`PascalCase`) 的映射配置。
## 9. 多租户与 ID 策略
* **ID 生成**：
* **强制**使用 **雪花算法 (Snowflake ID)**。
* 类型：C# `long` <-> DB `bigint`。
* **禁止**使用 UUID 或 自增 INT。
* **租户隔离**：
* 所有业务表必须包含 `tenant_id`。
* 写入时自动填充，读取时强制过滤。
## 10. API 设计与序列化 (前端兼容)
* **大整数处理**：
* 所有 `long` 类型 (Snowflake ID) 在 DTO 中**必须序列化为 string**。
* 方案：DTO 属性加 `[JsonConverter(typeof(ToStringJsonConverter))]` 或全局配置。
* **DTO 规范**：
* 输入：`XxxRequest`
* 输出：`XxxDto`
* **禁止** Controller 直接返回 Entity。
## 11. 模块化与复用
* **核心模块划分**：Identity (身份), Tenancy (租户), Dictionary (字典), Storage (存储)。
* **公共库 (Shared)**：通用工具类、扩展方法、常量定义必须放在 `Core/Shared` 项目中，避免重复造轮子。
## 12. 测试规范
* **模式**：Arrange-Act-Assert (AAA)。
* **工具**：xUnit + Moq + FluentAssertions。
* **覆盖率**：核心 Domain 逻辑必须 100% 覆盖；Service 层 ≥ 70%。
## 13. Git 工作流
* **提交格式 (Conventional Commits)**：
* `feat`: 新功能
* `fix`: 修复 Bug
* `refactor`: 重构
* `docs`: 文档
* `style`: 格式调整
* **分支规范**：`feature/功能名`，`bugfix/问题描述`。
## 14. 性能优化 (显式指令)
* **投影查询**：使用 `.Select(x => new Dto { ... })` 只查询需要的字段，减少 I/O。
* **缓存策略**：Cache-Aside 模式。数据更新后必须立即失效缓存。
* **批量操作**：
* EF Core 10：使用 `ExecuteUpdateAsync` / `ExecuteDeleteAsync`。
* Dapper：使用 `ExecuteAsync` 进行批量插入。
## 15. 安全规范
* **SQL 注入**：已在第 8 条强制参数化。
* **身份认证**：Admin 端使用 JWT + RBAC；小程序端使用 Session/Token。
* **密码存储**：必须使用 PBKDF2 或 BCrypt 加盐哈希。
## 16. 绝对禁止事项 (AI 自检清单)
**生成代码前，请自查是否违反以下红线：**
1. [ ] **SQL 注入**：是否拼接了 SQL 字符串？
2. [ ] **架构违规**：是否在 Controller/Domain 中使用了 DbContext？
3. [ ] **数据泄露**：是否返回了 Entity 或打印了密码？
4. [ ] **同步阻塞**：是否使用了 `.Result` 或 `.Wait()`？
5. [ ] **性能陷阱**：是否在循环中查询了数据库 (N+1)？
6. [ ] **精度丢失**：Long 类型的 ID 是否转为了 String？
7. [ ] **配置硬编码**：是否直接写死了连接串或密钥？
---

79
Document/09_服务器文档.md Normal file
View File

@@ -0,0 +1,79 @@
# 服务器文档
> 汇总原 12~15 号服务器记录，统一追踪账号、密码、用途与到期时间，便于统一维护。
## 1. 阿里云网关服务器
### 基础信息
- IP: 47.94.199.87
- 账户: root
- 密码: cJ5q2k2iW7XnMA^!
- 配置: 2 核 CPU / 2 GB 内存（阿里云轻量应用服务器）
- 地点: 北京
- 用途: 网关
- 到期时间: 2026-12-18
### 建议补充
- 系统版本: 待补充（执行 `cat /etc/os-release`）
- 带宽/磁盘: 待补充
- 安全组/开放端口: 待补充
- 备份与监控: 待补充
- 变更记录: 待补充
## 2. 腾讯云主机 PostgreSQL 服务器
### 基础信息
- IP: 120.53.222.17
- 账户: ubuntu
- 密码: P3y$nJt#zaa4%fh5
- 配置: 2 核 CPU / 4 GB 内存
- 地点: 北京
- 用途: 主 PostgreSQL / 数据库服务器
- 到期时间: 2026-11-26 11:22:01
### 建议补充
- 系统版本: 待补充（执行 `cat /etc/os-release`）
- 带宽/磁盘: 待补充
- 数据目录: 待补充（示例 `/var/lib/postgresql`）
- 数据备份/监控: 待补充
- 安全组/开放端口: 待补充
- 变更记录: 待补充
## 3. 天翼云主机 应用服务器
### 基础信息
- IP: 49.7.179.246
- 账户: root
- 密码: 7zE&84XI6~w57W7N
- 配置: 4 核 CPU / 8 GB 内存（天翼云）
- 地点: 北京
- 用途: 主应用服务器（承载 Admin/User/Mini API 或网关实例）
- 到期时间: 2027-10-04 17:17:57
### 建议补充
- 系统版本: 待补充（执行 `cat /etc/os-release`）
- 带宽/磁盘: 待补充
- 部署路径: 待补充（示例 `/opt/takeoutsaas`）
- 进程/端口: 待补充（示例 `AdminApi/UserApi/MiniApi`、`:8080`）
- 日志/监控: 待补充（Serilog 文件目录、进程监控方式）
- 安全组/开放端口: 待补充（按 API/网关暴露的 HTTP/HTTPS 端口）
- 变更记录: 待补充
## 4. 腾讯云 Redis/RabbitMQ 服务器
### 基础信息
- IP: 49.232.6.45
- 账户: ubuntu
- 密码: Z7NsRjT&XnWg7%7X
- 配置: 2 核 CPU / 4 GB 内存
- 地点: 北京
- 用途: Redis 与 RabbitMQ
- 到期时间: 2028-11-26
### 建议补充
- 系统版本: 待补充（执行 `cat /etc/os-release`）
- 带宽/磁盘: 待补充
- 安全组/开放端口: 待补充（Redis 6379，RabbitMQ 5672/15672 等）
- 数据持久化与备份: 待补充
- 监控与告警: 待补充
- 变更记录: 待补充

131
Document/10_设计期DbContext配置指引.md Normal file
View File

@@ -0,0 +1,131 @@
# 设计时 DbContext 配置指引
> 目的：在执行 `dotnet ef` 命令时无需硬编码数据库连接，可根据 appsettings 与环境变量自动加载。本文覆盖环境变量设置、配置目录指定等细节。
## 三库迁移命令 只需更改 SnowflakeIds_App 迁移关键字
> 先生成迁移，再执行数据库更新。启动项目统一用 AdminApi 确保加载最新配置。
### 生成迁移
```bash
# App 主库
dotnet tool run dotnet-ef migrations add SnowflakeIds_App `
--project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--startup-project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj `
--context TakeoutSaaS.Infrastructure.App.Persistence.TakeoutAppDbContext
# Identity 库
dotnet tool run dotnet-ef migrations add SnowflakeIds_Identity `
--project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--startup-project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj `
--context TakeoutSaaS.Infrastructure.Identity.Persistence.IdentityDbContext
# Dictionary 库
dotnet tool run dotnet-ef migrations add SnowflakeIds_Dictionary `
--project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--startup-project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj `
--context TakeoutSaaS.Infrastructure.Dictionary.Persistence.DictionaryDbContext
```
### 更新数据库
```bash
dotnet tool run dotnet-ef database update `
--project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--startup-project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj `
--context TakeoutSaaS.Infrastructure.App.Persistence.TakeoutAppDbContext
dotnet tool run dotnet-ef database update `
--project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--startup-project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj `
--context TakeoutSaaS.Infrastructure.Identity.Persistence.IdentityDbContext
dotnet tool run dotnet-ef database update `
--project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--startup-project src/Api/TakeoutSaaS.AdminApi/TakeoutSaaS.AdminApi.csproj `
--context TakeoutSaaS.Infrastructure.Dictionary.Persistence.DictionaryDbContext
```
## 一、设计时工厂读取逻辑概述
设计时工厂（`DesignTimeDbContextFactoryBase<T>`）按下面顺序解析连接串：
1. 若设置了 `TAKEOUTSAAS_APP_CONNECTION` / `TAKEOUTSAAS_IDENTITY_CONNECTION` / `TAKEOUTSAAS_DICTIONARY_CONNECTION` 等环境变量，则优先使用。
2. 否则查找配置文件：
- 从当前目录开始向上找到含 `TakeoutSaaS.sln` 的仓库根。
- 依次检查 `src/Api/TakeoutSaaS.AdminApi`、`src/Api/TakeoutSaaS.UserApi`、`src/Api/TakeoutSaaS.MiniApi` 等目录，如果存在 `appsettings.json` 或 `appsettings.{Environment}.json` 则加载。
- 若未找到，可通过环境变量 `TAKEOUTSAAS_APPSETTINGS_DIR` 指定包含 appsettings 文件的目录。
配置结构示例（出现在 AdminApi/MiniApi/UserApi 的 appsettings）：
```json
"Database": {
"DataSources": {
"AppDatabase": {
"Write": "Host=120.53...;Database=takeout_app_db;Username=...;Password=...",
"Reads": [
"Host=120.53...;Database=takeout_app_db;Username=...;Password=..."
]
},
"IdentityDatabase": {
"Write": "...",
"Reads": [ "..." ]
},
"DictionaryDatabase": {
"Write": "...",
"Reads": [ "..." ]
}
}
}
```
设计时工厂会根据数据源名称（`DatabaseConstants.AppDataSource` 等）读取 `Write` 连接串，实现与运行时一致。
## 二、环境变量配置
### 1. Windows PowerShell
```powershell
# 指向包含 appsettings.json 的目录
$env:TAKEOUTSAAS_APPSETTINGS_DIR = \"D:\\HAZCode\\TakeOut\\src\\Api\\TakeoutSaaS.AdminApi\"
#（可选）覆盖 AppDatabase 连接串
$env:TAKEOUTSAAS_APP_CONNECTION = \"Host=120.53.222.17;Port=5432;Database=takeout_app_db;Username=app_user;Password=***\"
#（可选）覆盖 IdentityDatabase 连接串
$env:TAKEOUTSAAS_IDENTITY_CONNECTION = \"Host=...;Database=takeout_identity_db;Username=...;Password=...\"
#（可选）覆盖 DictionaryDatabase 连接串
$env:TAKEOUTSAAS_DICTIONARY_CONNECTION = "Host=...;Database=takeout_dictionary_db;Username=...;Password=..."
```
### 2. Linux / macOS
```bash
export TAKEOUTSAAS_APPSETTINGS_DIR=/home/user/TakeOut/src/Api/TakeoutSaaS.AdminApi
export TAKEOUTSAAS_APP_CONNECTION=\"Host=120.53.222.17;Port=5432;Database=takeout_app_db;Username=app_user;Password=***\"
export TAKEOUTSAAS_IDENTITY_CONNECTION=\"Host=...;Database=takeout_identity_db;Username=...;Password=...\"
export TAKEOUTSAAS_DICTIONARY_CONNECTION="Host=...;Database=takeout_dictionary_db;Username=...;Password=..."
```
> 注意：若设置了 `TAKEOUTSAAS_APP_CONNECTION`，则无需在 appsettings 中提供 `Write` 连接串，反之亦然。不要将明文密码写入代码仓库，建议使用 Secret Manager 或部署环境的安全存储。
## 三、执行脚本示例
完成上述环境变量配置后即可执行：
```powershell
# TakeoutAppDbContext（业务库）
dotnet tool run dotnet-ef database update `
--project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--startup-project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--context TakeoutSaaS.Infrastructure.App.Persistence.TakeoutAppDbContext
# IdentityDbContext（身份库）
dotnet tool run dotnet-ef database update `
--project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--startup-project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--context TakeoutSaaS.Infrastructure.Identity.Persistence.IdentityDbContext
# DictionaryDbContext（字典库）
dotnet tool run dotnet-ef database update `
--project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--startup-project src/Infrastructure/TakeoutSaaS.Infrastructure/TakeoutSaaS.Infrastructure.csproj `
--context TakeoutSaaS.Infrastructure.Dictionary.Persistence.DictionaryDbContext
```
若需迁移 Identity/Dictionary 等上下文，替换 `--context` 参数为对应类型即可。
## 四、常见问题
1. **未找到 appsettings**：确保 `TAKEOUTSAAS_APPSETTINGS_DIR` 指向存在 `appsettings.json` 的目录，或将命令在 API 项目目录中执行。
2. **密码错误**：确认远程 PostgreSQL 用户/密码是否与 appsettings 或环境变量一致，避免在 CLI 中使用默认的账号。
3. **多环境配置**：`ASPNETCORE_ENVIRONMENT` 变量可控制加载 `appsettings.{Environment}.json`；默认是 Development。

67
Document/11_SystemTodo.md Normal file
View File

@@ -0,0 +1,67 @@
# TODO Roadmap
> 当前列表为原 11 号文档中的待办事项，已迁移到此处并统一以复选框形式标记。若无特殊说明，均尚未完成。
## 1. 配置与基础设施（高优）
- [x] Development/Production 数据库连接与 Secret 落地（Staging 暂不需要）。
- [x] Redis 服务部署完毕并记录配置。
- [x] RabbitMQ 服务部署完毕并记录配置。
- [x] COS 密钥配置补录完毕。
- [ ] OSS 密钥配置补录完毕（已忽略，待采购后再补录）。
- [ ] SMS 平台密钥配置补录完毕（已忽略，待采购后再补录）。
- [x] WeChat Mini 程序密钥配置补录完毕（AppID：wx30f91e6afe79f405，AppSecret：64324a7f604245301066ba7c3add488e，已同步到 admin/mini 配置并登记更新人）。
- [x] PostgreSQL 基础实例部署完毕并记录配置。
- [x] Postgres/Redis 接入文档 + IaC/脚本补齐（见 Document/infra/postgres_redis.md 与 deploy/postgres|redis）。
- [x] RabbitMQ/Redis/Hangfire storage scripts available (see deploy/postgres and deploy/redis).
- [ ] admin/mini/user/gateway 网关域名、证书、CORS 列表整理完成。(忽略，暂时不用完成)
- [ ] Hangfire Dashboard 启用并新增 Admin 角色验证/网关白名单。(忽略，暂时不用完成)
## 2. 数据与迁移（高优）
- [x] App/Identity/Dictionary/Hangfire 四个 DbContext 均生成初始 Migration 并成功 update database。
- [x] 商户/门店/商品/订单/支付/配送等实体与仓储实现完成，提供 CRUD + 查询。
- [x] 系统参数、默认租户、管理员账号、基础字典的种子脚本可重复执行。
## 3. 稳定性与质量(低优先级)
- [ ] Dictionary/Identity/Storage/Sms/Messaging/Scheduler 的 xUnit+FluentAssertions 单元测试框架搭建。
- [ ] WebApplicationFactory + Testcontainers 拉起 Postgres/Redis/RabbitMQ 的集成测试模板。
- [ ] .editorconfig、.globalconfig、Roslyn 分析器配置仓库通用规则并启用 CI 检查。
## 4. 安全与合规
- [x] RBAC 权限、租户隔离、用户/权限洞察 API 完整演示并在 Swagger 中提供示例。
- [x] 现状梳理：租户解析/过滤已具备（TenantResolutionMiddleware、TenantAwareDbContext），JWT 已写入 roles/permissions/tenant_id（JwtTokenService），PermissionAuthorize 已在 Admin API 使用，CurrentUserProfile 含角色/权限/租户；但仅有内嵌 string[] 权限存储，无角色/权限表与洞察查询，Swagger 缺少示例与多租户示例。
- [x] 差距与步骤：
- [x] 增加权限/租户洞察查询（按用户、按租户分页）并确保带 tenant 过滤（TenantAwareDbContext 或 Dapper 参数化）。
- [x] 输出可读的角色/权限列表（基于现有种子/配置的只读查询）。【已落地：RBAC1 模型 + 角色/权限管理 API；Swagger 示例后续补充】
- [x] 为洞察接口和 /auth/profile 增加 Swagger 示例，包含 tenant_id、roles、permissions，展示 Bearer 示例与租户 Header 示例。
- [ ] 若用 Dapper 读侧，SQL 必须参数化并显式过滤 tenant_id。
- [x] 计划顺序：Step A 设计应用层洞察 DTO/Query；Step B Admin API 只读端点（Authorize/PermissionAuthorize）；Step C Swagger 示例扩展；Step D 校验租户过滤与忽略路径配置。
- [x] Step D 校验：Admin API 管道已在 Auth 之前使用 TenantResolution，中间件未忽略新接口；查询使用 TenantAwareDbContext + ITenantProvider 双重租户校验，暂无需调整。后续若加 Dapper 读侧需显式带 tenant 过滤。
- [ ] 登录/刷新流程增加 IP 校验、租户隔离、验证码/频率限制。
- [ ] 登录/权限/敏感操作日志可追溯，提供查询接口或 Kibana Saved Search。
- [ ] Secret Store/KeyVault/KMS 管理敏感配置，禁止密钥写入 Git/数据库明文。
## 5. 观测与运维
- [x] TraceId 贯通，Serilog 输出 Console/File（ELK 待后续配置）。
- [x] Prometheus exporter 暴露关键指标，/health 探针与告警规则同步推送。
- [ ] PostgreSQL 全量/增量备份脚本及一次真实恢复演练报告。
## 6. 业务能力补全
- [ ] 商户/门店/菜品 API 完成并在 MQ 中投递上架/支付成功事件。
- [ ] 配送对接 API 支持下单/取消/查询并完成签名验签中间件。
- [ ] 小程序端商品浏览、下单、支付、评价、图片直传等 API 可闭环跑通。
## 7. 前后台 UI 对接
- [ ] Admin UI 通过 OpenAPI 生成或手写界面，接入 Hangfire Dashboard/MQ 监控只读模式。
- [ ] 小程序端完成登录、菜单浏览、下单、支付、物流轨迹、素材直传闭环。
## 8. CI/CD 与发布
- [ ] CI/CD 流水线覆盖构建、发布、静态扫描、数据库迁移。
- [x] `.github/workflows/ci-cd.yml` 已覆盖 Admin/Mini/User API 的变更检测、Docker Build/Push 与 SSH 部署。
- [ ] 尚未集成静态代码扫描、安全扫描与数据库迁移自动化。
- [ ] Dev/Staging/Prod 多环境配置矩阵 + 基础设施 IaC 脚本。
- [ ] 版本与发布说明模板整理并在仓库中提供示例。
## 9. 文档与知识库
- [ ] 接口文档、领域模型、关键约束使用 Markdown 或 API Portal 完整记录。
- [ ] 运行手册包含部署步骤、资源拓扑、故障排查手册。
- [ ] 安全合规模板覆盖数据分级、密钥管理、审计流程并形成可复用表格。

73
Document/12_BusinessTodo.md Normal file
View File

@@ -0,0 +1,73 @@
# 里程碑待办追踪
> 按“小程序版模块规划”划分四个里程碑；每个里程碑只含对应范围的任务，便于分阶段推进。
---
## Phase 1（当前阶段）：租户/商家入驻、门店与菜品、扫码堂食、基础下单支付、预购自提、第三方配送骨架
- [x] 管理端租户 API：注册、实名认证、套餐订阅/续费/升降配、审核流，Swagger ≥6 个端点，含审核日志。
- 已交付：`src/Api/TakeoutSaaS.AdminApi/Controllers/TenantsController.cs` 暴露注册、详情、实名提交、审核、订阅创建/升降配、审核日志 8 个端点；对应命令/查询位于 `src/Application/TakeoutSaaS.Application/App/Tenants`，仓储实现 `EfTenantRepository`，并写入 `TenantAuditLog` 记录。Swagger 自动收录上述接口，满足 Phase1 租户管理要求。
- [x] 商家入驻 API：证照上传、合同管理、类目选择，驱动待审/审核/驳回/通过状态机，文件持久在 COS。
- 已交付：`src/Api/TakeoutSaaS.AdminApi/Controllers/MerchantsController.cs` 新增证照上传/审核、合同创建与状态更新、商户审核、审核日志、类目列表等 8 个端点；应用层新增 `AddMerchantDocumentCommand`、`CreateMerchantContractCommand`、`ReviewMerchantCommand` 等 Handler；`MerchantDocument/Contract/Audit` DTO 完整返回详情，文件 URL 仍通过 `/api/admin/v1/files/upload` 上 COS。仓储实现扩展 `EfMerchantRepository` 支持文档/合同/AuditLog 持久化，`TakeoutAppDbContext` 新增 `merchant_audit_logs` 表实现状态机追踪。
- [x] RBAC 模板：平台管理员、租户管理员、店长、店员四角色模板；API 可复制并允许租户自定义扩展。
- 已交付：角色模板改为数据库驱动，新增 `RoleTemplate/RoleTemplatePermission` 实体与仓储接口/实现；应用层提供模板列表/详情/创建/更新/删除、按模板复制与租户批量初始化命令/查询；Admin 端 `RolesController` 暴露模板 CRUD 与复制/初始化端点（`src/Api/TakeoutSaaS.AdminApi/Controllers/RolesController.cs`），复制时补齐缺失权限且保留租户自定义授权；预置模板/权限种子写入 `src/Api/TakeoutSaaS.AdminApi/appsettings.Seed.*.json`。
- [x] 配额与套餐：TenantPackage CRUD、订阅/续费/配额校验（门店/账号/短信/配送单量），超额返回 409 并记录 TenantQuotaUsage。
- 已交付：新增套餐仓储与命令/查询/DTO（`src/Application/TakeoutSaaS.Application/App/Tenants`），Admin 端新增 `TenantPackagesController` 提供套餐列表/详情/创建/更新/删除接口。新增配额校验命令与租户接口 `/api/admin/v1/tenants/{id}/quotas/check`，基于当前订阅套餐限额校验并占用配额，超额抛出 409 并写入 `TenantQuotaUsage`。仓储注册于 `AddAppInfrastructure`。
- [x] 租户运营面板：欠费/到期告警、账单列表、公告通知接口，支持已读状态并在 Admin UI 展示。
- 已交付：新增账单/公告/通知实体与仓储，Admin 端提供 `/tenants/{id}/billings`（列表/详情/创建/标记支付）、`/announcements`（列表/详情/创建/更新/删除/已读）、`/notifications`（列表/已读）端点；权限码补充 `tenant-bill:*`、`tenant-announcement:*`、`tenant-notification:*`，种子模板更新；配额/订阅告警可通过通知表承载。
- [x] 门店管理：Store/StoreBusinessHour/StoreDeliveryZone/StoreHoliday CRUD 完整，含 GeoJSON 配送范围及能力开关。
- 已交付：营业时间/配送区/节假日命令、查询、验证与处理器齐全，Admin API 子路由完成 CRUD，门店能力开关（预约/排队）对外暴露，仓储读写删除均带租户过滤。
- [x] 桌码管理：批量生成桌码、绑定区域/容量、导出二维码 ZIP（POST /api/admin/stores/{id}/tables 可下载）。
- 已交付：桌台区域/桌码 DTO、命令、查询、验证与处理器完善，支持批量生成、区域绑定/更新；Admin API 增加区域/桌码 CRUD 与二维码 ZIP 导出（QRCoder 生成 SVG 打包），仓储补齐查找、更新、删除。
- [x] 员工排班：创建员工、绑定门店角色、维护 StoreEmployeeShift，可查询未来 7 日排班。
- 已交付：门店员工 DTO/命令/查询/验证/处理器完成，支持创建/更新/删除/查询；排班 CRUD（默认未来 7 天）含归属与时间冲突校验；Admin API 增加员工与排班控制器及权限种子，仓储含排班查询/更新/删除。
- [x] 桌码扫码入口：Mini 端解析二维码，GET /api/mini/tables/{code}/context 返回门店、桌台、公告。
- 已交付：桌码上下文查询 DTO/验证/处理器完成，可按桌码返回门店名称/公告/标签与桌台信息；MiniApi 新增 `TablesController` `/context` 端点，仓储支持按桌码查询。
- [x] 菜品建模：分类、SPU、SKU、规格/加料组、价格策略、媒资 CRUD + 上下架流程；Mini 端可拉取完整 JSON。
- 已交付：Admin 侧补齐 SKU/规格/加料/媒资/定价替换命令、验证与端点，并新增上/下架接口与全量详情；权限种子补充 `product:publish` 与子资源读写。Mini 侧新增门店菜单接口，按门店返回分类 + 商品全量 JSON（含 SKU/规格/加料/媒资/定价），支持 `updatedAfter` 增量。
- [x] 库存体系：SKU 库存、批次、调整、售罄管理，支持预售/档期锁定并在订单中扣减/释放。
- 已交付：库存模型补充预售/限购/并发字段与批次策略（FIFO/FEFO），新增锁定记录与幂等、过期释放；应用层提供调整/锁定/释放/扣减/批次维护命令与查询，Admin API 暴露库存与批次端点及权限种子。需后续生成迁移落库，并可按需将过期释放接入定时任务。
- [x] 自提档期：门店配置自提时间窗、容量、截单时间；Mini 端据此限制下单时间。
- 已交付：新增自提设置与档期实体/表、并发控制，Admin 端提供自提配置与档期 CRUD 权限/接口；Mini 端提供按日期查询可用档期，包含截单与容量校验。下单限制待后续与订单流程联调。
- [ ] 购物车服务：ShoppingCart/CartItem/CartItemAddon API 支持并发锁、限购、券/积分预校验，保证并发无脏数据。
- 当前：领域层与表结构已有 `ShoppingCart/CartItem/CartItemAddon`，但缺少 CQRS 命令/查询、并发锁/限购/券积分预校验以及任何 Admin/Mini 端接口。
- [ ] 订单与支付：堂食/自提/配送下单、微信/支付宝支付、优惠券/积分抵扣、订单状态机与通知链路齐全。
- 当前：Admin 端 `OrdersController`/`PaymentsController` 仅提供基础 CRUD，未覆盖堂食/自提/配送业务流、微信/支付宝支付、优惠券/积分抵扣、订单状态机、通知链路及与库存/配送的集成，Mini 端也无下单/支付接口。
- [ ] 桌台账单：合单/拆单、结账、电子小票、桌台释放，完成结账后恢复 Idle 并生成票据 URL。
- 当前：无桌台账单/合单/拆单/结账或电子小票逻辑，桌台仅有基础实体定义。
- [ ] 自配送骨架：骑手管理、取送件信息录入、费用补贴记录，Admin 端可派单并更新 DeliveryOrder。
- 当前：`DeliveryOrder` CRUD 支持录入 `CourierName/Phone`，但缺少骑手管理、派单流程、取送件详情与补贴记录等自配送骨架。
- [ ] 第三方配送抽象：统一下单/取消/加价/查询接口，支持达达、美团、闪送等，含回调验签与异常补偿骨架。
- 当前：尚未提供第三方配送抽象、回调验签或补偿逻辑，配送模块仅有基础 CRUD。
- [ ] 预购自提核销：提货码生成、手机号/二维码核销、自提柜/前台流程，超时自动取消或退款，记录操作者与时间。
- 当前：存在 `Reservation` 实体及订单字段 `ReservationId/CheckInCode`，但未实现提货码生成、核销接口、超时取消/退款或核销人记录，未与订单支付联动。
- [ ] 指标与日志：Prometheus 输出订单创建、支付成功率、配送回调耗时等，Grafana ≥8 个图表；关键流程日志记录 TraceId + 业务 ID。
- 当前：Admin/Mini/User API 与网关已接入 OpenTelemetry（OTLP 与 Prometheus 导出）和 TraceId 结构化日志，但缺少订单/支付/配送等业务指标定义、Prometheus 爬取路径说明及 Grafana 图表配置。
- [ ] 测试：Phase 1 核心 API 具备 ≥30 条自动化用例（单元 + 集成），覆盖租户→商户→下单链路。
- 当前：仓库尚无自动化测试项目/用例，Phase 1 链路未覆盖 xUnit/Moq/FluentAssertions 的单元或集成测试。
---
## Phase 2（下一阶段）：拼单、优惠券与基础营销、会员积分/会员日、客服聊天、同城自配送调度、搜索
- [ ] 拼单引擎：GroupOrder/Participant CRUD、发起/加入/成团条件、自动解散与退款、团内消息与提醒。
- [ ] 优惠券与基础营销：模板管理、领券、核销、库存/有效期/叠加规则，基础抽奖/秒杀/满减活动。
- [ ] 会员与积分：会员档案、等级/成长值、会员日通知；积分获取/消耗、有效期、黑名单。
- [ ] 客服聊天：实时会话、机器人/人工切换、排队/转接、消息模板、敏感词审查、工单流转与评价。
- [ ] 同城自配送调度：骑手智能指派、路线估时、无接触配送、费用补贴策略、调度看板。
- [ ] 搜索：门店/菜品/活动/优惠券搜索，过滤/排序、热门/历史记录、联想与纠错。
---
## Phase 3：分销返利、签到打卡、预约预订、地图导航、社区、高阶营销、风控与补偿
- [ ] 分销返利：AffiliatePartner/Order/Payout 管理，佣金阶梯、结算周期、税务信息、违规处理。
- [ ] 签到打卡：CheckInCampaign/Record、连签奖励、补签、积分/券/成长值奖励、反作弊机制。
- [ ] 预约预订：档期/资源占用、预约下单/支付、提醒/改期/取消、到店核销与履约记录。
- [ ] 地图导航扩展：附近门店/推荐、距离/路线规划、跳转原生导航、导航请求埋点。
- [ ] 社区：动态发布、评论、点赞、话题/标签、图片/视频审核、举报与风控，店铺口碑展示。
- [ ] 高阶营销：秒杀/抽奖/裂变、裂变海报、爆款推荐位、多渠道投放分析。
- [ ] 风控与审计：黑名单、频率限制、异常行为监控、审计日志、补偿与告警体系。
---
## Phase 4：性能优化、缓存、运营大盘、测试与文档、上线与监控
- [ ] 性能与缓存：热点接口缓存、慢查询治理、批处理优化、异步化改造。
- [ ] 可靠性：幂等与重试策略、任务调度补偿、链路追踪、告警联动。
- [ ] 运营大盘：交易/营销/履约/用户维度的细分报表、GMV/成本/毛利分析。
- [ ] 文档与测试：完整测试矩阵、性能测试报告、上线手册、回滚方案。
- [ ] 监控与运维：上线发布流程、灰度/回滚策略、系统稳定性指标、24x7 监控与告警。

62
Document/13_AppSeed说明.md Normal file
View File

@@ -0,0 +1,62 @@
# App 数据种子使用说明（App:Seed）
> 作用：在启动时自动创建默认租户与基础字典，便于本地/测试环境快速落地必备数据。由 `AppDataSeeder` 执行，支持幂等多次运行。
## 配置入口
- 文件位置：`appsettings.Seed.{Environment}.json`（AdminApi 下新增独立种子文件，示例已写入 Development）
- 配置节：`App:Seed`
示例（已写入 `src/Api/TakeoutSaaS.AdminApi/appsettings.Seed.Development.json`）：
```json
{
"App": {
"Seed": {
"Enabled": true,
"DefaultTenant": {
"TenantId": 1000000000001,
"Code": "demo",
"Name": "Demo租户",
"ShortName": "Demo",
"ContactName": "DemoAdmin",
"ContactPhone": "13800000000"
},
"DictionaryGroups": [
{
"Code": "order_status",
"Name": "订单状态",
"Scope": "Business",
"Items": [
{ "Key": "pending", "Value": "待支付", "SortOrder": 10 },
{ "Key": "paid", "Value": "已支付", "SortOrder": 20 },
{ "Key": "finished", "Value": "已完成", "SortOrder": 30 }
]
},
{
"Code": "store_tags",
"Name": "门店标签",
"Scope": "Business",
"Items": [
{ "Key": "hot", "Value": "热门", "SortOrder": 10 },
{ "Key": "new", "Value": "新店", "SortOrder": 20 }
]
}
]
}
}
}
```
## 字段说明
- `Enabled`: 是否启用种子
- `DefaultTenant`: 默认租户（使用雪花 long ID；0 表示让雪花生成）
- `DictionaryGroups`: 基础字典，`Scope` 可选 `System`/`Business`，`Items` 支持幂等运行更新
## 运行方式
1. 确保 Admin API 已调用 `AddAppInfrastructure`（Program.cs 已注册，会启用 `AppDataSeeder`）。
2. 修改 `appsettings.Seed.{Environment}.json` 的 `App:Seed` 后，启动 Admin API，即会自动执行种子逻辑（幂等）。
3. 查看日志：`AppSeed` 前缀会输出创建/更新结果。
## 注意事项
- ID 必须用 long（雪花），不要再使用 Guid/自增。
- 系统租户使用 `TenantId = 0`；业务租户请填写实际雪花 ID。
- 字典分组编码需唯一；重复运行会按编码合并更新。
- 生产环境请按需开启 `Enabled`，避免误写入。

40
Document/14_OpenTelemetry接入指引.md Normal file
View File

@@ -0,0 +1,40 @@
# 14_OpenTelemetry 接入指引
> 现状：Admin/Mini/User API 已集成 OTel 埋点，可导出到 Collector/控制台/文件日志，默认关闭 OTLP 导出。
## 1. 依赖与版本
- NuGet：`OpenTelemetry.Extensions.Hosting`、`OpenTelemetry.Instrumentation.AspNetCore`、`OpenTelemetry.Instrumentation.Http`、`OpenTelemetry.Instrumentation.EntityFrameworkCore`、`OpenTelemetry.Instrumentation.Runtime`、`OpenTelemetry.Exporter.OpenTelemetryProtocol`、`OpenTelemetry.Exporter.Console`。
- 当前 EF Core instrumentation 由 NuGet 回退到 `1.10.0-beta.1`（会提示 NU1603/NU1902），待可用时统一升级到稳定版以消除告警。
## 2. 程序内配置（Admin/Mini/User API）
- Resource：`ServiceName` 分别为 `TakeoutSaaS.AdminApi|MiniApi|UserApi`，`ServiceInstanceId = Environment.MachineName`。
- Tracing：开启 ASP.NET Core、HttpClient、EF Core（禁用 SQL 文本）、Runtime；采样器默认 `ParentBased + AlwaysOn`。
- Metrics：开启 ASP.NET Core、HttpClient、Runtime。
- Exporter：
- OTLP（可选）：读取 `Otel:Endpoint`，非空时启用。
- Console：`Otel:UseConsoleExporter`（默认 Dev 开启，Prod 关闭）。
- 日志：Serilog 输出 Console + 文件（按天滚动，保留 7 天），模板已包含 TraceId/SpanId（通过 Enrich FromLogContext）。
## 3. appsettings 配置键
```json
"Otel": {
"Endpoint": "", // 为空则不推 OTLP，例如 http://otel-collector:4317
"Sampling": "ParentBasedAlwaysOn",
"UseConsoleExporter": true // Dev 默认 true，Prod 建议 false
}
```
- 环境变量可覆盖：`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_ENDPOINT` 等。
## 4. Collector/后端接入建议
- Collector 监听 4317/4318（gRPC/HTTP OTLP），做采样/脱敏/分流，再转发 Jaeger/Tempo/ELK/Datadog 等。
- 生产注意：限制导出 SQL 文本（已关闭）、对敏感字段脱敏，必要时在 Collector 做 TraceIdRatioBased 采样以控量。
## 5. 验证步骤
1) 开启 `Otel:UseConsoleExporter=true`，本地运行 API，观察控制台是否输出 Span/Metric。
2) 配置 `Otel:Endpoint=http://localhost:4317` 并启动 Collector，使用 Jaeger/Tempo UI 或 `curl http://localhost:4318/v1/traces` 验证链路。
3) 文件日志：查看 `logs/admin-api-*.log` 等，确认包含 TraceId/SpanId。
## 6. 后续工作
- 待 NuGet 源更新后，升级到稳定版 OTel 包并消除 NU1603/NU1902 告警。
- 如需采集日志到 ELK，可直接用 Filebeat/Vector 读取 `logs/*.log` 推送，无需改代码。
- 如需控制采样率或关闭某些 instrumentation，调整 appsettings 中的 Sampling/开关后重启即可。

53
Document/15_API边界与自检清单.md Normal file
View File

@@ -0,0 +1,53 @@
# API 边界与自检清单
> 目的：明确 Admin/User/Mini 三个 API 的职责边界，避免跨端耦合。开发新接口或改动现有控制器时请对照自检，确保租户、安全、DTO、路由符合约定。
## 1. AdminApi（管理后台）
- **面向对象**：运营、客服、商户管理员。
- **职责**：租户/门店/商品/订单/支付/配送/字典/权限/RBAC/审计/任务调度等后台管理与洞察。
- **鉴权**：JWT + RBAC（`[Authorize]` + `PermissionAuthorize`），必须带租户头 `X-Tenant-Id/Code`。
- **路由前缀**：`api/admin/v{version}/...`。
- **DTO/约束**：仅管理字段，禁止返回 C 端敏感信息；long -> string；严禁实体直接返回。
- **现有控制器**：`AuthController`、`DeliveriesController`、`DictionaryController`、`FilesController`、`MerchantsController`、`OrdersController`、`PaymentsController`、`PermissionsController`、`RolesController`、`StoresController`、`SystemParametersController`、`TenantPackagesController`、`TenantsController`、`TenantBillingsController`、`TenantAnnouncementsController`、`TenantNotificationsController`、`UserPermissionsController`、`HealthController`。
- **自检清单**：
1. 是否需要权限/租户过滤？未加则补 `[Authorize]` + 租户解析。
2. 是否调用了应用层 CQRS，而非在 Controller 写业务？
3. DTO 是否按管理口径，未暴露用户端字段？
4. 是否使用参数化/AsNoTracking/投影，避免 N+1？
5. 路由和 Swagger 示例是否含租户/权限说明？
- **自检记录**：RolesController 新增模板列表/详情/复制/初始化端点，均已套用 `[Authorize]` + `PermissionAuthorize`、仅调用 CQRS/DTO，依赖租户头隔离。TenantPackagesController 与 TenantsController(配额校验) 均使用权限码、DTO 映射，配额校验要求携带租户头防越权。新增租户账单/公告/通知控制器，全部采用 CQRS、权限校验与租户参数，列表分页、未暴露实体。
## 2. UserApi（C 端用户）
- **面向对象**：App/H5 普通用户。
- **职责**：菜单浏览、下单、支付、评价、地址、售后、订单查询、支付/配送回调（验证签名）等用户闭环。
- **鉴权**：用户 JWT，租户隔离；幂等接口需校验。
- **路由前缀**：`api/user/v{version}/...`。
- **DTO/约束**：仅用户侧可见字段，屏蔽后台配置字段；long -> string。
- **现有控制器**：当前仅 `HealthController`（业务接口待补）。
- **自检清单**：
1. 是否暴露给用户的纯前台功能？后台配置请放 AdminApi。
2. 是否做租户隔离、用户鉴权、签名/幂等校验？
3. 响应是否脱敏且只含用户需要的字段？
4. 是否避免跨端复用后台 DTO/命令？
5. 回调路由是否验证签名/防重放？
## 3. MiniApi（小程序端）
- **面向对象**：微信/小程序前端。
- **职责**：小程序登录/刷新、当前用户档案、订阅消息、直传凭证、小程序场景特定的下单/浏览等。
- **鉴权**：小程序登录态/Token，租户隔离；必要时区分渠道。
- **路由前缀**：`api/mini/v{version}/...`。
- **DTO/约束**：遵循小程序接口规范，错误码与前端对齐；long -> string。
- **现有控制器**：`AuthController`、`MeController`、`FilesController`、`HealthController`。
- **自检清单**：
1. 是否为小程序特有流程（code2session、订阅消息、直传等）？通用用户接口放 UserApi。
2. 是否完成租户/鉴权校验，区分渠道标识？
3. 请求/响应是否符合小程序对错误码与字段的约定？
4. 是否避免使用后台管理 DTO/权限模型？
5. 上传/直传接口是否限制 MIME/大小并做鉴权？
## 4. 共通约束
- **分层**：Controller 仅做路由/DTO 转换，业务放 Application 层 Handler。
- **租户**：所有写/读需租户过滤；严禁跨租户访问。
- **日志/观测**：TraceId/SpanId 已贯通；/metrics、/healthz 按服务暴露。
- **命名**：输入 `XxxRequest`、输出 `XxxDto`；文件名与类名一致；布尔属性加 `Is/Has`。
- **发布前检查**：运行 `dotnet build`，必要时补 Swagger 示例、单元测试（核心逻辑 100% 覆盖，服务 ≥70%）。

79
Document/Completed/后端套餐管理.md Normal file
View File

@@ -0,0 +1,79 @@
# TakeoutSaaS 开发 TODO（自动维护）
> 说明：该文档用于记录本仓库待办与进度。我会在完成每个任务后更新标记状态，并尽量保持“一个功能点一个原子提交”。
>
> 状态标记：[x] 已完成 / [~] 部分完成 / [ ] 未开始
## 一期：套餐管理 MVP（已落地 + 待收口）
[x] 1. 套餐增删改：新建/编辑/复制套餐，支持草稿保存
- [x] 新建套餐（表单：基础信息 + 定价 + 权益配额）
- [x] 编辑套餐（同新增表单）
- [x] 复制套餐（基于现有套餐快速创建新套餐）
- [x] 删除套餐（软删）
- [x] 草稿保存（草稿/发布状态、草稿发布、回滚草稿）
- [x] 修复“保存草稿却变发布”根因（EF 默认值哨兵导致 insert 省略字段，已将发布状态默认值调整为草稿并补齐哨兵配置）
[x] 2. 上架体系：上架/下架、是否对外可见、是否允许新租户购买
- [x] 上架/下架（启用/禁用套餐，含二次确认与提示）
- [x] 是否对外可见（展示与可售解耦）
- [x] 是否允许新租户购买（可售开关与可见开关解耦）
- [x] 修复“新增时开关 false 无法落库”根因（EF 默认值哨兵导致 insert 省略字段，已将哨兵改为 true）
[~] 3. 价格与计费周期：月付/年付、阶梯价/按量计费
- [x] 月付/年付价格（`monthlyPrice` / `yearlyPrice`）
- [ ] 阶梯价/按量计费
[x] 4. 权益/配额配置：功能开关 + 数值配额（门店/账号/存储/短信/配送单量/更多）
- [x] 数值配额（门店数、账号数、存储、短信、配送单量）
- [x] 功能策略（`featurePoliciesJson`：可视化编辑 + JSON 预览，保留未知字段）
- [x] 商品/菜单上限
- [x] API 调用次数
- [x] 报表/导出权限
- [x] 打印/小票能力
- [x] 营销功能（优惠券/满减/会员/积分等开关）
[~] 5. 展示配置：卖点文案、推荐标识、排序、标签、对比页字段
- [x] 排序（`sortOrder`）
- [~] 卖点/描述（`description`）
- [x] 推荐标识（Recommended）
- [x] 标签（推荐/性价比/旗舰）
- [ ] （已移除）对比页展示字段配置（对比维度/顺序）
- [ ] 自助入驻选套餐页展示推荐/标签（公共套餐列表接口返回 isRecommended/tags + 前端展示/置顶）
[x] 6. 订阅关联视图：当前使用该套餐的租户数量、MRR/ARR 粗看、到期分布（运营常用）
- [x] 订阅/租户数量：活跃订阅数、总订阅数、使用租户数
- [x] 使用租户列表入口：抽屉列表（支持分页与搜索）
- [x] MRR/ARR 粗看
- [x] 到期分布（7/15/30 天到期租户数、到期列表入口）
[x] 7. 后端接口补齐（套餐使用统计/使用租户分页查询等）
[x] 8. 前端联调与回归（包含权限、空态、错误提示）
## 二期：上架与配置完善（建议）
- [x] 1. 草稿保存与发布流程（草稿/发布、回滚到草稿）
- [x] 2. 可见性/可售开关拆分（对外可见、允许新租户购买、已订阅不受影响说明）
- [x] 4. 权益/配额可视化编辑器（JSON 结构化编辑、Schema 校验、预设模板）
- [x] 5. 更多常用配额字段补齐（商品/菜单、API 次数、导出/报表、打印等）
## 三期：计费与权益策略（建议）
- [ ] 1. 阶梯价/按量计费（超配计费、账单明细）
- [ ] 2. 权益变更影响说明：升配/降配规则（立即/次周期）、影响范围提示
- [ ] 3. 超配策略（禁止/只读/按量计费/宽限期）
## 四期：商业化与合规增强（建议）
- [ ] 1. 附加计费（Add-ons）：短信包、存储包、额外门店/账号包、配送单量包（可叠加、单独定价）
- [ ] 2. 版本与历史：套餐版本号、变更记录、回滚、对已订阅租户的影响范围提示
- [ ] 3. 购买限制：可购买地区/行业、仅邀请可见、最大购买数量、是否允许叠加订阅
- [ ] 4. 订阅关联视图增强：MRR/ARR、到期分布、续费转化漏斗（运营常用）
- [ ] 5. 操作审计：谁改了套餐、何时改、改了什么（合规必备）

195
Document/README.md Normal file
View File

@@ -0,0 +1,195 @@
# 外卖SaaS系统 - 文档中心
欢迎查阅外卖SaaS系统的完整文档。本文档中心包含了项目的所有技术文档和开发指南。
## 📚 文档目录
### 1. [项目概述](01_项目概述.md)
- 项目简介与背景
- 核心业务模块介绍
- 用户角色说明
- 系统特性
- 技术选型
- 项目里程碑
**适合人群**：项目经理、产品经理、新加入的开发人员
---
### 2. [技术架构](02_技术架构.md)
- 技术栈详解
- 系统架构设计
- 分层架构说明
- 核心设计模式
- 数据访问策略（EF Core + Dapper）
- 缓存策略
- 消息队列应用
- 安全设计
**适合人群**：架构师、技术负责人、高级开发人员
---
### 3. [数据库设计](03_数据库设计.md)
- 数据库设计原则
- 命名规范
- 核心表结构
- 租户管理
- 商家管理
- 菜品管理
- 订单管理
- 配送管理
- 支付管理
- 营销管理
- 系统管理
- 索引策略
- 数据库优化
- 备份策略
**适合人群**：数据库管理员、后端开发人员
---
### 4A. [管理后台 API 设计](04A_管理后台API.md)
- 角色与权限（平台/租户/商家）
- 租户与商家管理
- 菜品与分类管理
- 订单流转与售后
- 优惠券与评价管理
- 统计报表与文件上传
### 4B. [小程序/用户端 API 设计](04B_小程序API.md)
- 小程序登录与用户信息
- 商家与门店浏览
- 菜品与分类列表
- 购物车同步
- 订单创建/查询/取消
- 支付对接（微信/支付宝）
- 优惠券领取与使用、评价发布
**适合人群**：前端开发人员（小程序/Web用户端）、后端开发人员、接口对接人员
---
### 5. [部署运维](05_部署运维.md)
- 环境要求
- 本地开发环境搭建
- Docker部署
- Nginx配置
- 数据库部署（主从复制）
- Redis部署（哨兵模式）
- CI/CD配置
- 监控告警（Prometheus + Grafana）
- 日志管理（ELK Stack）
- 安全加固
- 性能优化
- 故障恢复
**适合人群**：运维工程师、DevOps工程师、系统管理员
---
### 6. [开发规范](06_开发规范.md)
- 代码规范
- 命名规范
- 代码组织
- 代码注释
- 异常处理
- Git工作流
- 分支管理
- 提交信息规范
- 代码审查标准
- 单元测试规范
- 性能优化规范
- 安全规范
- 日志规范
- 配置管理
- API设计规范
**适合人群**：所有开发人员
---
### 7. [系统架构图](07_系统架构图.md)
- 整体架构图
- 应用分层架构
- 订单处理流程图
- 数据流转图
- 多租户数据隔离架构
- 缓存架构
- 消息队列架构
- 部署架构
- 监控架构
**适合人群**：架构师、技术负责人、所有开发人员
---
## 🚀 快速导航
### 我是新人，从哪里开始？
1. 先阅读 [项目概述](01_项目概述.md) 了解项目背景和业务
2. 查看 [系统架构图](07_系统架构图.md) 理解系统整体架构
3. 阅读 [开发规范](06_开发规范.md) 了解开发要求
4. 参考 [部署运维](05_部署运维.md) 搭建本地开发环境
### 我要开发新功能
1. 查看 [数据库设计](03_数据库设计.md) 了解数据模型
2. 参考 [API接口设计](04_API接口设计.md) 设计接口
3. 遵循 [开发规范](06_开发规范.md) 编写代码
4. 参考 [技术架构](02_技术架构.md) 选择合适的技术方案
### 我要部署系统
1. 阅读 [部署运维](05_部署运维.md) 了解部署流程
2. 参考 [系统架构图](07_系统架构图.md) 理解部署架构
3. 按照文档配置监控和日志系统
### 我要对接API
1. 查看 [API接口设计](04_API接口设计.md) 了解接口规范
2. 参考接口文档进行开发和测试
---
## 📖 文档更新记录
### v1.0.0 (2024-01-01)
- ✅ 完成项目概述文档
- ✅ 完成技术架构文档
- ✅ 完成数据库设计文档
- ✅ 完成API接口设计文档
- ✅ 完成部署运维文档
- ✅ 完成开发规范文档
- ✅ 完成系统架构图文档
---
## 💡 文档贡献
如果您发现文档有任何问题或需要改进的地方，欢迎：
1. 提交 Issue 反馈问题
2. 提交 Pull Request 改进文档
3. 联系项目负责人
---
## 📞 联系方式
- 项目地址：https://github.com/your-org/takeout-saas
- 问题反馈：https://github.com/your-org/takeout-saas/issues
- 邮箱：dev@example.com
---
## 📝 文档规范
本文档使用 Markdown 格式编写，遵循以下规范：
- 使用清晰的标题层级
- 代码示例使用语法高亮
- 重要内容使用加粗或引用
- 保持文档简洁易读
- 及时更新文档内容
---
**最后更新时间**：2024-01-01
**文档版本**：v1.0.0

101
Document/infra/postgres_redis.md Normal file
View File

@@ -0,0 +1,101 @@
# PostgreSQL 与 Redis 接入手册
> 本文档补齐 `Document/10_TODO.md` 中“Postgres/Redis 接入文档与 IaC/脚本”的要求，统一描述连接信息、账号权限、运维流程，以及可复用的部署脚本位置。
## 1. 运行环境总览
| 组件 | 地址/端口 | 主要数据库/实例 | 说明 |
| --- | --- | --- | --- |
| PostgreSQL | `120.53.222.17:5432` | `takeout_app_db`、`takeout_identity_db`、`takeout_dictionary_db`、`takeout_hangfire_db` | 线上实例，所有业务上下文共用。 |
| Redis | `49.232.6.45:6379` | 单节点 | 业务缓存/登录限流/刷新令牌存储。 |
> 注意：所有业务账号都只具备既有库的读写权限，无 `CREATEDB`。若需新库，需使用平台管理员账号（`postgres`）或联系 DBA。
## 2. 账号与库映射
| 数据库 | 角色 | 密码 | 用途 |
| --- | --- | --- | --- |
| `takeout_app_db` | `app_user` | `AppUser112233` | 业务域 (`TakeoutAppDbContext`) |
| `takeout_identity_db` | `identity_user` | `IdentityUser112233` | 身份域 (`IdentityDbContext`) |
| `takeout_dictionary_db` | `dictionary_user` | `DictionaryUser112233` | 字典域 (`DictionaryDbContext`) |
| `takeout_hangfire_db` | `hangfire_user` | `HangFire112233` | 后台调度/Hangfire |
Redis 密码：`MsuMshk112233`，见 `appsettings.*.json -> Redis`。
## 3. 环境变量/配置注入
### PowerShell
```powershell
$env:TAKEOUTSAAS_APPSETTINGS_DIR = "D:\HAZCode\TakeOut\src\Api\TakeoutSaaS.AdminApi"
$env:TAKEOUTSAAS_APP_CONNECTION = "Host=120.53.222.17;Port=5432;Database=takeout_app_db;Username=app_user;Password=AppUser112233;Pooling=true"
$env:TAKEOUTSAAS_IDENTITY_CONNECTION = "Host=120.53.222.17;Port=5432;Database=takeout_identity_db;Username=identity_user;Password=IdentityUser112233;Pooling=true"
$env:TAKEOUTSAAS_DICTIONARY_CONNECTION = "Host=120.53.222.17;Port=5432;Database=takeout_dictionary_db;Username=dictionary_user;Password=DictionaryUser112233;Pooling=true"
```
### Bash
```bash
export TAKEOUTSAAS_APPSETTINGS_DIR=/home/user/TakeOut/src/Api/TakeoutSaaS.AdminApi
export TAKEOUTSAAS_APP_CONNECTION="Host=120.53.222.17;Port=5432;Database=takeout_app_db;Username=app_user;Password=AppUser112233;Pooling=true"
export TAKEOUTSAAS_IDENTITY_CONNECTION="Host=120.53.222.17;Port=5432;Database=takeout_identity_db;Username=identity_user;Password=IdentityUser112233;Pooling=true"
export TAKEOUTSAAS_DICTIONARY_CONNECTION="Host=120.53.222.17;Port=5432;Database=takeout_dictionary_db;Username=dictionary_user;Password=DictionaryUser112233;Pooling=true"
```
Redis 连接字符串直接写入 `appsettings.*.json` 即可，如：
```jsonc
"Redis": "49.232.6.45:6379,password=MsuMshk112233,abortConnect=false"
```
## 4. 运维指南
### PostgreSQL
1. **只读账号验证**
```powershell
psql "host=120.53.222.17 port=5432 dbname=takeout_app_db user=app_user password=AppUser112233"
```
2. **备份**
```bash
pg_dump -h 120.53.222.17 -p 5432 -U postgres -F c -d takeout_app_db -f backup/takeout_app_db_$(date +%Y%m%d).dump
pg_dumpall -h 120.53.222.17 -p 5432 -U postgres > backup/all_$(date +%Y%m%d).sql
```
3. **恢复**
```bash
pg_restore -h 120.53.222.17 -p 5432 -U postgres -d takeout_app_db backup/takeout_app_db_xxx.dump
psql -h 120.53.222.17 -p 5432 -U postgres -f backup/all_yyyymmdd.sql
```
4. **账号/权限策略**
- `app_user` / `identity_user` / `dictionary_user` 拥有 `CONNECT`、`TEMP`、Schema `public` 的 CRUD 权限。
- `hangfire_user` 仅能访问 `takeout_hangfire_db`，不可访问业务库。
- 创建新表/列时，通过 EF Migration 自动添加 COMMENT。
### Redis
1. **连接验证**
```bash
redis-cli -h 49.232.6.45 -p 6379 -a MsuMshk112233 ping
```
2. **备份**
```bash
redis-cli -h 49.232.6.45 -p 6379 -a MsuMshk112233 save # 触发 RDB
redis-cli -h 49.232.6.45 -p 6379 -a MsuMshk112233 bgsave # 后台
```
RDB/AOF 文件在服务器 `redis.conf` 定义的目录（默认 `/var/lib/redis`）。
3. **常见运维项**
- `CONFIG GET dir` / `CONFIG GET dbfilename` 可查看持久化路径。
- `INFO memory` 监控内存；开启 `maxmemory` + `allkeys-lru` 保护。
## 5. IaC / 脚本
| 文件 | 说明 |
| --- | --- |
| `deploy/postgres/create_databases.sql` | 基于 `postgres` 管理员执行，创建四个业务库及角色、授予权限、补 COMMENT。 |
| `deploy/postgres/bootstrap.ps1` | PowerShell 包装脚本，调用 `psql` 执行上面的 SQL（默认读取 `postgres` 管理员账号）。 |
| `deploy/postgres/README.md` | 介绍如何在本地/测试环境执行 bootstrap 并校验连接。 |
| `deploy/redis/docker-compose.yml` | 可复用的 Redis 部署（Redis 7 + AOF），便于本地或测试环境一键拉起。 |
| `deploy/redis/redis.conf` | compose/裸机均可共用的配置（`requirepass`、持久化等已写好）。 |
| `deploy/redis/README.md` | 说明如何使用 compose 或将 `redis.conf` 部署到现有实例。 |
> 线上目前为裸机安装（非容器），如需创建新环境/快速恢复，可直接运行上述脚本达到同样配置；即使在现有机器上，也可把 SQL/配置当作“最终规范”确保环境一致性。

19254
Document/swagger/swagger20251215095917.json Normal file
View File

File diff suppressed because it is too large Load Diff

89
Document/xmind_小程序版模块规划.md Normal file
View File

@@ -0,0 +1,89 @@
# 外卖SaaS（小程序导向）模块脑图
## 1. 目标
- 聚焦小程序用户体验：高效点单、扫码堂食、同城履约、实时状态
- 平台/租户多租户隔离，支持商家快速入驻与运营
- 门店同城即时配送为主，第三方配送对接兜底，统一回调验签
## 2. 端侧
- 小程序用户端：扫码进店/堂食点餐、店铺浏览、菜品/套餐、购物车、下单支付、拼单、预购自提、同城配送、订单跟踪、优惠券/积分/会员、营销活动、评价、地址管理、搜索、签到、预约、社区、客服聊天、地图导航
- 管理后台（商家/店员）：门店配置、桌码管理、菜品与库存、订单/拼单/自提处理、配送调度与回调、营销配置、分销配置、客服工单/会话、数据看板
- 平台运营后台：租户/商家审核、套餐与配额、全局配置、日志审计、监控看板、分销/返利策略、活动审核
## 3. 核心业务模块
- 租户与平台
- 租户生命周期：注册、实名认证/资质审核、套餐订阅、续费/升降配、停用/注销
- 配额与权限：门店数/账号数/存储/短信/配送单量，RBAC 角色模板，租户级配置继承与覆盖
- 平台运营：租户监控、账单/计费/催缴、公告/通知、合规与风控（黑名单/频率限制）
- 商家与门店
- 入驻与资质审核：证照上传、合同、店铺类目、品牌与连锁
- 门店配置：多店管理、营业时间、休息/打烊、门店状态、区域/配送范围、到店导航信息
- 桌码/场景：桌码生成与绑定、桌台容量/区域、桌码标签（堂食/快餐/档口）
- 门店运营：员工账号与分工（前台/后厨/配送）、交班与收银、公告/售罄提示
- 菜品与库存
- 菜品建模：分类/标签/排序、规格与属性（辣度/份量）、套餐与组合、加料/做法/备注
- 价格策略：会员价、门店价、时间段价、限时折扣、区域价
- 库存与可售：总库存/门店库存/档期库存、售罄/预售、批量导入与同步、条码/编码
- 媒资：图片/视频、SPU/SKU 编码、营养/过敏源/溯源信息
- 扫码点餐/堂食
- 桌码入口：扫码识别门店/桌台、桌台上下文、预加载菜单
- 点餐流程：购物车并发锁、加菜/催单、口味备注、拆单/并单、多人同桌分付/代付
- 账单与核销：桌台账单合并、结账/买单、电子小票、发票抬头、桌台释放
- 预购自提
- 档期配置：自提时间窗/容量、预售库存、截单时间
- 下单与支付：自提地址确认、档期校验、预售与现制、库存锁定
- 提货核销：提货码/手机号核销、自提柜/前台、超时/取消/退款、代取人
- 下单与支付
- 购物车与校验：库存/限购/门店状态/配送范围/桌台状态、券和积分叠加规则
- 支付与结算：微信/支付宝/余额/优惠券/积分抵扣、回调幂等、预授权、分账/对账
- 售后与状态机：退单/部分退款、异常单处理、状态机（待付→待接→制作→配送/自提→完成/取消）
- 同城即时配送（门店履约）
- 自配送：骑手管理、取/送件信息、路线估时、导航、取餐码、费用与补贴
- 第三方配送：统一抽象（下单/取消/加价/查询）、多渠道择优、回调验签、异常重试与补偿
- 配送体验：预计送达/计价、配送进度推送、无接触配送、收货码、投诉与赔付
- 拼单
- 团单规则：发起/加入、成团条件（人数/金额/时间）、拼主与参团人、支付/锁单策略
- 失败与退款：超时/人数不足自动解散、自动退款/原路退、通知
- 履约：同单配送至拼主地址、收件信息可见范围、团内消息/提醒
- 优惠券与营销工具
- 券种与发放：满减/折扣/新人券/裂变券/桌码专属券/会员券，渠道（领券中心/活动/分享/桌码）
- 核销规则：适用范围（门店/品类/菜品）、叠加/互斥、最低消费、有效期、库存与风控
- 活动组件：抽奖、分享裂变、秒杀/限时抢购、满减活动、爆款/推荐位、裂变海报
- 会员与积分/会员营销
- 会员体系：付费会员/积分会员、等级/成长值、会员权益（专享价/券/运费/客服）
- 积分运营：获取（消费/签到/任务/活动）、消耗（抵扣/兑换）、有效期、黑名单
- 会员运营：会员日、续费提醒、沉睡唤醒、专属活动、分层运营与 A/B
- 客服工具
- 会话：实时聊天、机器人/人工切换、快捷回复、排队/转接、消息模板/通知
- 质量与风控：会话记录与审计、敏感词、评价与回访、工单流转
- 分销返利
- 规则：商品/类目返利、佣金阶梯、结算周期、税务信息、违规处理
- 链路：分享链接/小程序码、点击与下单跟踪、确认收货后结算、售后扣回
- 地图导航
- 门店/自提点定位、距离/路况、路线规划、附近门店/推荐、跳转原生导航
- 签到打卡
- 规则：每日/任务签到、连签奖励、补签、积分/券/成长值奖励、反作弊
- 预约预订
- 档期/资源：时间段、人员/座位/设备占用、容量校验
- 流程：预约下单/支付、提醒/改期/取消、到店核销与履约记录
- 搜索查询
- 内容：门店/菜品/活动/优惠券搜索，过滤/排序，热门/历史搜索
- 体验：纠错/联想、推荐、结果埋点与转化分析
- 用户社区
- 社区运营：动态发布/评论/点赞、话题/标签、图片/视频审核、举报与风控
- 互动：店铺口碑、菜品晒图、官方/商家号发布、置顶与精选
- 数据与分析
- 交易分析：销售/订单/客单/转化漏斗、支付与退款、品类/单品分析
- 营销分析：券发放与核销、活动效果（拼单/秒杀/抽奖/分销）、会员留存与复购
- 履约分析：配送时效、超时/异常、堂食与自提拆分、投诉与赔付
- 运营大盘：租户/商家健康度、活跃度、留存、GMV、成本与毛利
- 系统与运维
- 安全与合规：RBAC、租户隔离、限流与风控（设备/IP/账户/店铺）、敏感词与内容安全
- 配置与网关：字典/参数、灰度/开关、网关限流/鉴权/租户透传
- 可靠性：任务调度（订单/拼单超时、券过期、回调补偿）、幂等与重试、健康检查/告警、日志/链路追踪、备份恢复
## 4. 里程碑（建议）
- Phase 1：租户/商家入驻、门店与菜品、桌码扫码堂食、基础下单支付、预购自提、第三方配送骨架
- Phase 2：拼单、优惠券与基础营销组件、会员积分/会员日、客服聊天、同城自配送调度、搜索
- Phase 3：分销返利、签到打卡、预约预订、地图导航、社区、营销活动丰富（秒杀/抽奖等）、风控与审计、补偿与告警体系
- Phase 4：性能优化与缓存、运营大盘与细分报表、测试与文档完善、上线与监控

BIN
Document/xmind_小程序版模块规划.xmind Normal file
View File

Binary file not shown.