# Authorization Service 架构文档

## 目录

1. [概述](#概述)
2. [架构设计](#架构设计)
3. [分层架构](#分层架构)
4. [领域模型](#领域模型)
5. [技术栈](#技术栈)
6. [目录结构](#目录结构)

---

## 概述

Authorization Service（授权服务）是 RWAdurian 平台的核心微服务之一，负责管理用户的授权角色，包括省代公司、市代公司和社区授权。该服务采用 **领域驱动设计（DDD）** 和 **六边形架构（Hexagonal Architecture）** 模式构建，确保业务逻辑的清晰性和系统的可维护性。

### 核心功能

- **授权角色管理**：省代公司、市代公司、社区授权的申请、审核、激活和撤销
- **月度考核评估**：基于阶梯目标的月度业绩考核和排名
- **团队验证**：推荐链路中的授权冲突检测
- **事件驱动**：通过 Kafka 发布领域事件，实现服务间解耦

---

## 架构设计

### 六边形架构（端口与适配器）

```
                    ┌─────────────────────────────────────────┐
                    │              API Layer                   │
                    │    (Controllers, DTOs, Guards)          │
                    └──────────────────┬──────────────────────┘
                                       │
                    ┌──────────────────▼──────────────────────┐
                    │          Application Layer               │
                    │  (Commands, Services, Schedulers)       │
                    └──────────────────┬──────────────────────┘
                                       │
    ┌──────────────────────────────────▼──────────────────────────────────┐
    │                         Domain Layer                                 │
    │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐│
    │  │ Aggregates  │  │  Entities   │  │Value Objects│  │   Events    ││
    │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘│
    │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │
    │  │ Repositories│  │  Services   │  │    Enums    │                 │
    │  │ (Interfaces)│  │  (Domain)   │  │             │                 │
    │  └─────────────┘  └─────────────┘  └─────────────┘                 │
    └──────────────────────────────────┬──────────────────────────────────┘
                                       │
                    ┌──────────────────▼──────────────────────┐
                    │         Infrastructure Layer             │
                    │  ┌─────────────┐  ┌─────────────┐       │
                    │  │   Prisma    │  │    Redis    │       │
                    │  │ Repositories│  │   Cache     │       │
                    │  └─────────────┘  └─────────────┘       │
                    │  ┌─────────────┐  ┌─────────────┐       │
                    │  │   Kafka     │  │  External   │       │
                    │  │  Publisher  │  │  Services   │       │
                    │  └─────────────┘  └─────────────┘       │
                    └─────────────────────────────────────────┘
```

### 依赖方向

- 外层依赖内层，内层不依赖外层
- Domain Layer 是核心，不依赖任何外部框架
- Infrastructure Layer 实现 Domain Layer 定义的接口
- Application Layer 编排领域对象完成用例

---

## 分层架构

### 1. Domain Layer（领域层）

领域层是系统的核心，包含所有业务逻辑。

#### 聚合根（Aggregates）

| 聚合根 | 说明 |
|--------|------|
| `AuthorizationRole` | 授权角色聚合根，管理授权的完整生命周期 |
| `MonthlyAssessment` | 月度考核聚合根，管理考核评估和排名 |

#### 实体（Entities）

| 实体 | 说明 |
|------|------|
| `LadderTargetRule` | 阶梯目标规则，定义省代/市代/社区的考核目标 |

#### 值对象（Value Objects）

| 值对象 | 说明 |
|--------|------|
| `AuthorizationId` | 授权ID |
| `AssessmentId` | 考核ID |
| `UserId` | 用户ID |
| `AdminUserId` | 管理员用户ID |
| `RegionCode` | 区域代码（省/市） |
| `Month` | 月份（YYYY-MM格式） |
| `ValidationResult` | 验证结果 |

#### 领域服务（Domain Services）

| 服务 | 说明 |
|------|------|
| `AuthorizationValidatorService` | 授权验证服务，检查推荐链路冲突 |
| `AssessmentCalculatorService` | 考核计算服务，计算业绩和排名 |

#### 领域事件（Domain Events）

| 事件 | 触发时机 |
|------|----------|
| `AuthorizationAppliedEvent` | 授权申请提交 |
| `AuthorizationApprovedEvent` | 授权审核通过 |
| `AuthorizationRejectedEvent` | 授权审核拒绝 |
| `AuthorizationActivatedEvent` | 授权激活 |
| `AuthorizationRevokedEvent` | 授权撤销 |
| `MonthlyAssessmentPassedEvent` | 月度考核通过 |
| `MonthlyAssessmentFailedEvent` | 月度考核失败 |
| `MonthlyBypassGrantedEvent` | 授予考核豁免 |
| `FirstPlaceAchievedEvent` | 获得区域第一名 |

### 2. Application Layer（应用层）

应用层负责编排领域对象，实现用例。

#### 命令（Commands）

```typescript
// 用户命令
ApplyProvincialAuthorizationCommand   // 申请省代授权
ApplyCityAuthorizationCommand         // 申请市代授权
ApplyCommunityAuthorizationCommand    // 申请社区授权

// 管理员命令
AdminApproveAuthorizationCommand      // 审核通过
AdminRejectAuthorizationCommand       // 审核拒绝
AdminRevokeAuthorizationCommand       // 撤销授权
AdminGrantBypassCommand               // 授予豁免

// 系统命令
RunMonthlyAssessmentCommand           // 执行月度考核
```

#### 应用服务（Application Services）

| 服务 | 说明 |
|------|------|
| `AuthorizationCommandService` | 处理授权相关命令 |
| `AuthorizationQueryService` | 处理授权相关查询 |
| `AssessmentCommandService` | 处理考核相关命令 |
| `AssessmentQueryService` | 处理考核相关查询 |

#### 定时任务（Schedulers）

| 任务 | 说明 |
|------|------|
| `MonthlyAssessmentScheduler` | 每月1日执行上月考核 |

### 3. Infrastructure Layer（基础设施层）

基础设施层提供技术实现。

#### 持久化（Persistence）

- **Prisma ORM**：PostgreSQL 数据库访问
- **Repository 实现**：实现领域层定义的仓储接口

#### 缓存（Cache）

- **Redis**：缓存热点数据，如用户授权信息

#### 消息队列（Messaging）

- **Kafka**：发布领域事件到其他服务

#### 外部服务（External Services）

- **Identity Service**：用户身份验证
- **Referral Service**：推荐关系查询
- **Statistics Service**：团队统计数据查询

### 4. API Layer（接口层）

API 层处理 HTTP 请求和响应。

#### 控制器（Controllers）

| 控制器 | 路由前缀 | 说明 |
|--------|----------|------|
| `AuthorizationController` | `/authorizations` | 用户授权操作 |
| `AdminAuthorizationController` | `/admin/authorizations` | 管理员授权操作 |
| `AssessmentController` | `/assessments` | 考核查询 |
| `AdminAssessmentController` | `/admin/assessments` | 管理员考核操作 |

---

## 领域模型

### 授权角色状态机

```
          ┌─────────┐
          │ PENDING │ ◄─── 用户申请
          └────┬────┘
               │
       ┌───────┴───────┐
       ▼               ▼
  ┌─────────┐    ┌──────────┐
  │APPROVED │    │ REJECTED │
  └────┬────┘    └──────────┘
       │
       ▼
  ┌─────────┐
  │ ACTIVE  │ ◄─── 首月考核通过后激活
  └────┬────┘
       │
       ▼
  ┌─────────┐
  │ REVOKED │ ◄─── 管理员撤销或考核失败
  └─────────┘
```

### 考核规则

#### 省代公司阶梯目标

| 月份 | 月度目标 | 累计目标 |
|------|----------|----------|
| 1 | 150 | 150 |
| 2 | 300 | 450 |
| 3 | 600 | 1,050 |
| 4 | 1,200 | 2,250 |
| 5 | 2,400 | 4,650 |
| 6 | 4,700 | 9,350 |
| 7 | 6,900 | 16,250 |
| 8 | 10,000 | 26,250 |
| 9+ | 11,750 | 50,000 |

#### 市代公司阶梯目标

| 月份 | 月度目标 | 累计目标 |
|------|----------|----------|
| 1 | 30 | 30 |
| 2 | 60 | 90 |
| 3 | 120 | 210 |
| 4 | 240 | 450 |
| 5 | 480 | 930 |
| 6 | 940 | 1,870 |
| 7 | 1,380 | 3,250 |
| 8 | 2,000 | 5,250 |
| 9+ | 2,350 | 10,000 |

#### 社区授权目标

固定目标：10（无阶梯）

---

## 技术栈

| 技术 | 用途 |
|------|------|
| **NestJS** | Node.js 后端框架 |
| **TypeScript** | 编程语言 |
| **Prisma** | ORM 数据库访问 |
| **PostgreSQL** | 关系型数据库 |
| **Redis** | 缓存 |
| **Kafka** | 消息队列 |
| **Jest** | 测试框架 |
| **Docker** | 容器化部署 |

---

## 目录结构

```
authorization-service/
├── src/
│   ├── domain/                    # 领域层
│   │   ├── aggregates/            # 聚合根
│   │   │   ├── authorization-role.aggregate.ts
│   │   │   └── monthly-assessment.aggregate.ts
│   │   ├── entities/              # 实体
│   │   │   └── ladder-target-rule.entity.ts
│   │   ├── value-objects/         # 值对象
│   │   │   ├── authorization-id.vo.ts
│   │   │   ├── assessment-id.vo.ts
│   │   │   ├── user-id.vo.ts
│   │   │   ├── region-code.vo.ts
│   │   │   ├── month.vo.ts
│   │   │   └── validation-result.vo.ts
│   │   ├── events/                # 领域事件
│   │   │   ├── authorization-applied.event.ts
│   │   │   ├── authorization-approved.event.ts
│   │   │   └── ...
│   │   ├── services/              # 领域服务
│   │   │   ├── authorization-validator.service.ts
│   │   │   └── assessment-calculator.service.ts
│   │   ├── repositories/          # 仓储接口
│   │   │   ├── authorization-role.repository.ts
│   │   │   └── monthly-assessment.repository.ts
│   │   └── enums/                 # 枚举
│   │       ├── role-type.enum.ts
│   │       ├── authorization-status.enum.ts
│   │       └── assessment-result.enum.ts
│   │
│   ├── application/               # 应用层
│   │   ├── commands/              # 命令
│   │   │   ├── apply-provincial-authorization.command.ts
│   │   │   └── ...
│   │   ├── services/              # 应用服务
│   │   │   ├── authorization-command.service.ts
│   │   │   ├── authorization-query.service.ts
│   │   │   ├── assessment-command.service.ts
│   │   │   └── assessment-query.service.ts
│   │   └── schedulers/            # 定时任务
│   │       └── monthly-assessment.scheduler.ts
│   │
│   ├── infrastructure/            # 基础设施层
│   │   ├── persistence/           # 持久化
│   │   │   ├── prisma/
│   │   │   │   └── prisma.service.ts
│   │   │   └── repositories/      # 仓储实现
│   │   │       ├── authorization-role.repository.impl.ts
│   │   │       └── monthly-assessment.repository.impl.ts
│   │   ├── cache/                 # 缓存
│   │   │   └── redis.service.ts
│   │   ├── messaging/             # 消息队列
│   │   │   └── kafka/
│   │   │       └── event-publisher.service.ts
│   │   └── external/              # 外部服务
│   │       ├── referral.service.ts
│   │       └── statistics.service.ts
│   │
│   ├── api/                       # 接口层
│   │   ├── controllers/           # 控制器
│   │   │   ├── authorization.controller.ts
│   │   │   ├── admin-authorization.controller.ts
│   │   │   ├── assessment.controller.ts
│   │   │   └── admin-assessment.controller.ts
│   │   ├── dtos/                  # 数据传输对象
│   │   │   ├── apply-authorization.dto.ts
│   │   │   └── ...
│   │   └── guards/                # 守卫
│   │       ├── jwt-auth.guard.ts
│   │       └── admin.guard.ts
│   │
│   ├── shared/                    # 共享模块
│   │   ├── filters/               # 异常过滤器
│   │   │   └── global-exception.filter.ts
│   │   ├── interceptors/          # 拦截器
│   │   │   └── transform.interceptor.ts
│   │   └── exceptions/            # 自定义异常
│   │       └── domain.exception.ts
│   │
│   ├── app.module.ts              # 应用模块
│   └── main.ts                    # 入口文件
│
├── prisma/
│   ├── schema.prisma              # 数据库模型
│   └── migrations/                # 数据库迁移
│
├── test/                          # 测试
│   ├── app.e2e-spec.ts            # E2E 测试
│   └── domain-services.integration-spec.ts  # 集成测试
│
├── docs/                          # 文档
│   ├── ARCHITECTURE.md            # 架构文档
│   ├── API.md                     # API 文档
│   ├── DEVELOPMENT.md             # 开发指南
│   ├── TESTING.md                 # 测试文档
│   └── DEPLOYMENT.md              # 部署文档
│
├── docker-compose.test.yml        # 测试环境配置
├── Dockerfile                     # 生产镜像
├── Dockerfile.test                # 测试镜像
├── Makefile                       # 常用命令
└── package.json                   # 项目配置
```

---

## 参考资料

- [Domain-Driven Design Reference](https://www.domainlanguage.com/ddd/reference/)
- [Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture/)
- [NestJS Documentation](https://docs.nestjs.com/)
- [Prisma Documentation](https://www.prisma.io/docs/)