394 lines
16 KiB
Markdown
394 lines
16 KiB
Markdown
# 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/)
|