Authorization Service 架构文档
目录
- 概述
- 架构设计
- 分层架构
- 领域模型
- 技术栈
- 目录结构
概述
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）
// 用户命令
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）
消息队列（Messaging）
外部服务（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 # 项目配置
参考资料