# Fengling Microservices Architecture Design

**Date**: 2025-02-01
**Status**: Approved

## Overview
风灵(Fengling)系统从单体架构重构为微服务架构,采用核心业务微服务拆分策略,每服务独立数据库,通过RabbitMQ异步通信。

## Core Business Services

### 1. 会员服务
- **Database**: `fengling_member`
- **Entities**: Member, MemberLevel, MemberTag, MemberGroup
- **Responsibilities**: 会员信息管理、会员等级、会员分组、标签管理

### 2. 推广员服务
- **Database**: `fengling_promoter`
- **Entities**: Promoter, PromotersActivity, PromoterStore
- **Responsibilities**: 推广员管理、推广员活动、推广员积分

### 3. 营销活动服务
- **Database**: `fengling_activity`
- **Entities**: Activity, ActivityAward, ActivitySign, AfeActivity
- **Responsibilities**: 活动创建、活动报名、签到、抽奖、礼品发放

### 4. 优惠券服务
- **Database**: `fengling_coupon`
- **Entities**: Coupon, CouponExpense, CouponTask
- **Responsibilities**: 优惠券发放、核销、任务配置

### 5. 礼品服务
- **Database**: `fengling_gift`
- **Entities**: Gift, GiftCategory, GiftExpense
- **Responsibilities**: 礼品管理、礼品发放记录

### 6. 订单服务
- **Database**: `fengling_order`
- **Entities**: Order, VirtualOrder, StoreshopOrders
- **Responsibilities**: 订单创建、订单状态管理

### 7. 渠道服务
- **Database**: `fengling_channel`
- **Entities**: Channel, ChannelQrCode, ChannelApply, ChannelTag
- **Responsibilities**: 渠道管理、二维码生成、渠道申请审核

### 8. 门店服务
- **Database**: `fengling_store`
- **Entities**: Store, StoreCategory, StoreLevel, StoreApply
- **Responsibilities**: 门店管理、门店等级、门店申请审核

### 9. 账户服务
- **Database**: `fengling_account`
- **Entities**: Account, CustomerBalance, WalletBalance
- **Responsibilities**: 资金账户、积分账户、钱包余额管理

### 10. 积分服务
- **Database**: `fengling_points`
- **Entities**: Points, IntegralRule, IntegralDetail, PointClearConfig
- **Responsibilities**: 积分规则配置、积分发放/扣减、积分明细

## Infrastructure Services

### 1. 认证授权服务
- **Technology**: OpenIddict (开源免费)
- **Responsibilities**:
  - 用户认证(JWT Token签发)
  - OAuth2/OIDC标准支持
  - 多租户认证(TenantId嵌入Token)
  - 权限验证
- **Gateway Integration**: 网关验证Token并传递TenantId到下游服务

### 2. 配置管理
- **Approach**: K8s ConfigMap + appsettings环境变量
- **Shared Library**: `Fengling.Configuration`
  - 统一配置读取
  - 环境变量覆盖支持
  - 无需额外部署
- **Benefits**: 简单可靠,零额外组件

### 3. 日志服务
- **Technology**: Serilog + 云厂商日志服务
- **Collection**:
  - 应用输出JSON到stdout
  - 云厂商Agent抓取日志
- **Format**: JSON结构化(TraceId, SpanId, TenantId)

### 4. 链路追踪
- **Technology**: OpenTelemetry + Jaeger
- **Scope**: HTTP/RabbitMQ/DB/Redis
- **Retention**: 30天

### 5. 消息队列
- **Technology**: RabbitMQ (集群部署)
- **Exchanges**:
  - `activity.exchange`: 营销活动相关消息
  - `order.exchange`: 订单相关消息
  - `member.exchange`: 会员相关消息
  - `points.exchange`: 积分相关消息
- **Persistence**: 开启持久化
- **Dead Letter Queue**: 每个队列配置DLQ

## Communication Pattern

**All services use RabbitMQ for asynchronous communication**

### Message Flows

1. **Order Created**:
   - Order Service → `order.exchange` → Points Service (add points)
   - Order Service → `order.exchange` → Coupon Service (consume coupon)

2. **Activity Signed**:
   - Activity Service → `activity.exchange` → Points Service (add sign points)
   - Activity Service → `activity.exchange` → Gift Service (issue gift)

3. **Member Registered**:
   - Member Service → `member.exchange` → Channel Service (bind channel)
   - Member Service → `member.exchange` → Points Service (init account)

## Database Strategy

**Each microservice has its own PostgreSQL database**

- Naming convention: `fengling_<service_name>`
- No cross-service joins allowed
- Data consistency via eventual consistency (message queue)
- Tenant isolation via `TenantId` column in all tables

## Security

1. **Authentication**: JWT Token via OpenIddict
2. **Authorization**: Role-based access control (RBAC)
3. **Tenant Isolation**: TenantId in JWT + TenantId column in all tables
4. **API Security**: Gateway validates all incoming requests

## Deployment

- **Infrastructure**: Kubernetes
- **Gateway**: YARP Gateway (already implemented)
- **Load Balancing**: Kubernetes Service + Ingress
- **Configuration**: K8s ConfigMap
- **Logging**: Cloud provider log aggregation
- **Monitoring**: Prometheus + Grafana (optional)

## Implementation Priority

### Phase 1: Infrastructure (Current)
1. ✅ YARP Gateway
2. 🔄 Authentication Service (in progress)
3. RabbitMQ Setup
4. OpenTelemetry + Jaeger Setup

### Phase 2: Core Services
5. Member Service
6. Promoter Service
7. Activity Service
8. Order Service

### Phase 3: Supporting Services
9. Coupon Service
10. Gift Service
11. Channel Service
12. Store Service
13. Account Service
14. Points Service

## Technology Stack

- **.NET Version**: .NET 9.0
- **Language**: C# 13
- **Database**: PostgreSQL
- **ORM**: Entity Framework Core 9.0
- **Cache**: Redis (StackExchange.Redis)
- **Message Queue**: RabbitMQ (MassTransit)
- **Authentication**: OpenIddict
- **Logging**: Serilog
- **Tracing**: OpenTelemetry
- **API Gateway**: YARP
- **Container**: Docker
- **Orchestration**: Kubernetes

## Reference Architecture

```
[Client App]
     |
     v
[YARP Gateway]
     |
     |---[Tenant Routing]--->
     |
[Authentication Service] (OpenIddict)
     |
     v
[Service Mesh (RabbitMQ)]
     |
     +---[Member Service]--->[fengling_member DB]
     +---[Promoter Service]-->[fengling_promoter DB]
     +---[Activity Service]-->[fengling_activity DB]
     +---[Order Service]----->[fengling_order DB]
     +---[Coupon Service]--->[fengling_coupon DB]
     +---[Gift Service]----->[fengling_gift DB]
     +---[Channel Service]-->[fengling_channel DB]
     +---[Store Service]---->[fengling_store DB]
     +---[Account Service]-->[fengling_account DB]
     +---[Points Service]--->[fengling_points DB]
```

## Migration Strategy

1. **Phase 1**: Extract shared libraries (Configuration, Logging, Tracing)
2. **Phase 2**: Implement Authentication Service
3. **Phase 3**: Extract services one by one (least dependent first)
4. **Phase 4**: Migrate data from monolithic database
5. **Phase 5**: Update Gateway routing to new services
6. **Phase 6**: Decommission old monolithic application