模块/服务设计文档

服务架构概览

井云服务中心后端采用微服务架构，包含以下核心服务：

Gateway（网关服务）：系统统一入口，负责路由、认证、负载均衡
Auth（认证服务）：用户认证和授权
User（用户服务）：用户管理、素材管理、分销系统、点数管理
Agent（智能体服务）：智能体管理、分类、配置和工作流
Tenant（租户服务）：多租户管理、版本管理、权限管理、菜单管理
Payment（支付服务）：支付处理、订单管理、租户购买
Integration（集成服务）：第三方服务集成
Cron（定时任务服务）：定时任务调度

各服务详细设计

1. Gateway 网关服务

服务职责

作为系统的统一入口，处理所有外部请求的路由、认证和负载均衡。

API 列表

代理所有内部服务的 HTTP API
提供统一的认证和鉴权
请求限流和熔断保护
跨域处理和安全防护

核心功能

路由转发：根据请求路径转发到对应的后端服务
认证拦截：验证 JWT Token 和用户权限
负载均衡：支持多种负载均衡策略
监控和日志：记录所有请求日志和性能指标

依赖的外部服务

Consul：服务注册发现
所有内部微服务

关键设计决策

使用 Kratos Gateway 框架
支持动态路由配置
实现服务级别的熔断和降级

2. Auth 认证服务

服务职责

处理用户认证、授权和会话管理，支持多种登录方式。

API 列表

/auth/wechat/login：微信登录
/auth/sms/send：发送短信验证码
/auth/sms/login：短信验证码登录
/auth/refresh：刷新 Token
/auth/logout：用户登出

核心数据模型

type User struct {
    ID       int64  `json:"id"`
    Phone    string `json:"phone"`
    Nickname string `json:"nickname"`
    Avatar   string `json:"avatar"`
    Status   int32  `json:"status"`
}

type AuthToken struct {
    AccessToken  string `json:"access_token"`
    RefreshToken string `json:"refresh_token"`
    ExpiresIn    int64  `json:"expires_in"`
}

关键流程

微信登录流程：
- 生成微信登录二维码
- 用户扫码后获取微信用户信息
- 创建或更新用户记录
- 生成 JWT Token
短信登录流程：
- 发送短信验证码
- 验证短信验证码
- 创建或更新用户记录
- 生成 JWT Token

依赖的外部服务

Redis：存储登录状态和验证码
微信 API：微信登录接口
PostgreSQL：用户数据存储

幂等性、事务、并发处理

幂等性：相同的登录请求返回相同结果
事务：用户创建和 Token 生成在同一事务中
并发：使用 Redis 分布式锁防止重复登录

3. User 用户服务

服务职责

处理用户管理、素材管理、分销系统、点数管理等业务逻辑。

API 列表

/user/profile：获取用户信息
/user/materials：素材管理
/user/distribution：分销相关
/user/points：点数管理
/user/transactions：交易记录

核心数据模型

type User struct {
    ID           int64  `json:"id"`
    Phone        string `json:"phone"`
    Nickname     string `json:"nickname"`
    Avatar       string `json:"avatar"`
    Status       int32  `json:"status"`
    TenantID     int64  `json:"tenant_id,omitempty"`
    InviterID    int64  `json:"inviter_id,omitempty"`
}

type Material struct {
    ID          int64  `json:"id"`
    UserID      int64  `json:"user_id"`
    Title       string `json:"title"`
    Content     string `json:"content"`
    CategoryID  int64  `json:"category_id,omitempty"`
}

type UserPointLedger struct {
    ID        int64     `json:"id"`
    UserID    int64     `json:"user_id"`
    Balance   int64     `json:"balance"`
    ExpiresAt time.Time `json:"expires_at"`
}

关键流程

点数消费流程：
- FIFO 策略选择即将过期的点数
- 扣减点数余额
- 记录消费流水
- 更新用户总点数
分销佣金计算：
- 查询用户分销等级
- 计算直推和间推佣金
- 生成佣金记录
- 更新用户佣金余额

依赖的外部服务

PostgreSQL：用户数据存储
Redis：缓存和会话存储
RabbitMQ：异步消息处理

幂等性、事务、并发处理

幂等性：点数消费使用唯一订单号
事务：点数操作使用数据库事务保证一致性
并发：使用乐观锁防止并发修改

4. Agent 智能体服务

服务职责

处理智能体管理、分类、配置和工作流等业务逻辑，支持多种智能体类型。

API 列表

/agent/categories：智能体分类管理
/agent/agents：智能体管理
/agent/bots：机器人管理
/agent/workflows：工作流管理
/agent/prompts：提示词管理

核心数据模型

type Agent struct {
    ID          int64                  `json:"id"`
    TenantID    int64                  `json:"tenant_id"`
    Name        string                 `json:"name"`
    Description string                 `json:"description"`
    Type        AgentType              `json:"type"`
    Status      AgentStatus            `json:"status"`
    Config      map[string]interface{} `json:"config"`
}

type AgentCategory struct {
    ID          int64  `json:"id"`
    TenantID    int64  `json:"tenant_id"`
    Name        string `json:"name"`
    Description string `json:"description"`
    SortOrder   int32  `json:"sort_order"`
    IsFeatured  bool   `json:"is_featured"`
    IsActive    bool   `json:"is_active"`
}

关键流程

智能体创建流程：
- 验证用户权限
- 创建智能体记录
- 根据类型创建对应配置
- 更新分类统计
平台资产同步：
- 从 Coze 等平台获取资产列表
- 更新本地数据库
- 处理冲突和重复数据

依赖的外部服务

PostgreSQL：智能体数据存储
Coze API：智能体平台集成
RabbitMQ：异步任务处理

幂等性、事务、并发处理

幂等性：使用外部平台 ID 作为唯一标识
事务：智能体创建和配置更新在同一事务中
并发：使用分布式锁防止重复同步

5. Tenant 租户服务

服务职责

处理多租户架构相关的业务逻辑，支持版本管理、权限管理、平台集成和菜单管理。

API 列表

/tenant/tenants：租户管理
/tenant/versions：版本管理
/tenant/permissions：权限管理
/tenant/menus：菜单管理
/tenant/integrations：平台集成

核心数据模型

type Tenant struct {
    ID          int64     `json:"id"`
    Name        string    `json:"name"`
    Domain      string    `json:"domain"`
    Status      int32     `json:"status"`
    ExpiresAt   time.Time `json:"expires_at"`
    VersionID   int64     `json:"version_id,omitempty"`
}

type Version struct {
    ID          int64                    `json:"id"`
    Name        string                   `json:"name"`
    Price       int64                    `json:"price"`
    Duration    int32                    `json:"duration"`
    Permissions []int64                  `json:"permissions"`
    CustomExplanations []CustomExplanation `json:"custom_explanations"`
}

type TenantSnapshot struct {
    ID          int64     `json:"id"`
    TenantID    int64     `json:"tenant_id"`
    VersionID   int64     `json:"version_id"`
    Permissions []int64   `json:"permissions"`
    ExpiresAt   time.Time `json:"expires_at"`
    Status      string    `json:"status"`
}

关键流程

租户创建流程：
- 生成唯一二级域名
- 创建租户记录
- 创建租户快照
- 初始化基础数据
权限检查流程：
- 获取用户租户信息
- 查询租户快照权限
- 验证用户操作权限
- 返回权限检查结果

依赖的外部服务

PostgreSQL：租户数据存储
Redis：权限缓存
微信第三方平台 API

幂等性、事务、并发处理

幂等性：域名生成使用唯一约束
事务：租户创建和快照创建在同一事务中
并发：使用分布式锁防止域名冲突

6. Payment 支付服务

服务职责

处理支付相关业务逻辑，支持微信支付，管理订单和支付回调，处理租户购买和版本购买流程。

API 列表

/payment/orders：订单管理
/payment/wechat/pay：微信支付
/payment/wechat/notify：支付回调
/payment/purchase-version：购买版本

核心数据模型

type Order struct {
    ID         int64      `json:"id"`
    UserID     int64      `json:"user_id"`
    TenantID   int64      `json:"tenant_id,omitempty"`
    Type       OrderType  `json:"type"`
    Amount     int64      `json:"amount"`
    Status     OrderStatus `json:"status"`
    ProductID  int64      `json:"product_id,omitempty"`
    CreatedAt  time.Time  `json:"created_at"`
    UpdatedAt  time.Time  `json:"updated_at"`
}

关键流程

版本购买流程：
- 查询版本信息
- 创建租户订单
- 调用微信支付 API
- 生成支付二维码
支付回调处理：
- 验证支付回调签名
- 更新订单状态
- 创建租户和快照
- 发送成功通知

依赖的外部服务

PostgreSQL：订单数据存储
微信支付 API：支付处理
RabbitMQ：异步消息处理

幂等性、事务、并发处理

幂等性：使用微信订单号作为唯一标识
事务：订单更新和租户创建在同一事务中
并发：使用分布式锁防止重复处理

7. Integration 集成服务

服务职责

处理第三方服务集成，如文件上传服务（阿里云 OSS）、短信服务、支付服务等。

API 列表

/integration/upload：文件上传
/integration/sms/send：短信发送
/integration/wechat/third-party/*：微信第三方平台

核心功能

文件上传：支持多种存储后端
短信服务：支持多个提供商
微信集成：第三方平台功能
统一的接口封装

依赖的外部服务

阿里云 OSS：文件存储
短信服务提供商：短信发送
微信 API：第三方平台集成

8. Cron 定时任务服务

服务职责

处理定时任务调度，包括点数过期处理、分销等级检查等。

任务列表

点数过期处理：每天凌晨 2 点
分销等级检查：每天凌晨 3 点
租户过期检查：每天凌晨 4 点
统计数据更新：每天凌晨 5 点

依赖的外部服务

PostgreSQL：数据查询和更新
RabbitMQ：任务调度

服务间通信

同步通信

使用 gRPC 进行服务间同步调用
支持负载均衡和熔断保护
统一的错误处理和重试机制

异步通信

使用 RabbitMQ 进行异步消息传递
支持消息持久化和重试
完整的消息追踪和监控

数据一致性

事务管理

单服务内使用数据库事务
跨服务使用 Saga 模式
关键操作支持补偿机制

数据同步

使用事件驱动架构
支持最终一致性
完整的审计日志

服务治理

服务注册发现

使用 Consul 进行服务注册
支持健康检查
动态配置管理

监控和追踪

分布式追踪（OpenTelemetry）
指标收集（Prometheus）
日志聚合（ELK Stack）

安全管理

服务间认证（mTLS）
API 访问控制
敏感数据加密

部署和运维

容器化部署

使用 Docker 容器化
Kubernetes 编排
自动化 CI/CD 流程

配置管理

环境隔离
配置版本控制
敏感信息加密

故障处理

熔断和降级
自动恢复机制
完整的故障预案

服务架构概览​

各服务详细设计​

1. Gateway 网关服务​

服务职责​

API 列表​

核心功能​

依赖的外部服务​

关键设计决策​

2. Auth 认证服务​

服务职责​

API 列表​

核心数据模型​

关键流程​

依赖的外部服务​

幂等性、事务、并发处理​

3. User 用户服务​

服务职责​

API 列表​

核心数据模型​

关键流程​

依赖的外部服务​

幂等性、事务、并发处理​

4. Agent 智能体服务​

服务职责​

API 列表​

核心数据模型​

关键流程​

依赖的外部服务​

幂等性、事务、并发处理​

5. Tenant 租户服务​

服务职责​

API 列表​

核心数据模型​

关键流程​

依赖的外部服务​

幂等性、事务、并发处理​

6. Payment 支付服务​

服务职责​

API 列表​

核心数据模型​

关键流程​

依赖的外部服务​

幂等性、事务、并发处理​

7. Integration 集成服务​

服务职责​

API 列表​

核心功能​

依赖的外部服务​

8. Cron 定时任务服务​

服务职责​

任务列表​

依赖的外部服务​

服务间通信​

同步通信​

异步通信​

数据一致性​

事务管理​

数据同步​

服务治理​

服务注册发现​

监控和追踪​

安全管理​

部署和运维​

容器化部署​

配置管理​

故障处理​

服务架构概览

各服务详细设计

1. Gateway 网关服务

服务职责

API 列表

核心功能

依赖的外部服务

关键设计决策

2. Auth 认证服务

服务职责

API 列表

核心数据模型

关键流程

依赖的外部服务

幂等性、事务、并发处理

3. User 用户服务

服务职责

API 列表

核心数据模型

关键流程

依赖的外部服务

幂等性、事务、并发处理

4. Agent 智能体服务

服务职责

API 列表

核心数据模型

关键流程

依赖的外部服务

幂等性、事务、并发处理

5. Tenant 租户服务

服务职责

API 列表

核心数据模型

关键流程

依赖的外部服务

幂等性、事务、并发处理

6. Payment 支付服务

服务职责

API 列表

核心数据模型

关键流程

依赖的外部服务

幂等性、事务、并发处理

7. Integration 集成服务

服务职责

API 列表

核心功能

依赖的外部服务

8. Cron 定时任务服务

服务职责

任务列表

依赖的外部服务

服务间通信

同步通信

异步通信

数据一致性

事务管理

数据同步

服务治理

服务注册发现

监控和追踪

安全管理

部署和运维

容器化部署

配置管理

故障处理