# eagle

**Repository Path**: anyin891/eagle

## Basic Information

- **Project Name**: eagle
- **Description**: No description available
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-15
- **Last Updated**: 2026-01-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Eagle - 中电信量子用户核心服务

Eagle 是一个基于 Go 语言开发的用户核心服务，提供用户、部门、组织等核心业务功能，采用 gRPC 协议提供服务。

## 📋 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [代码生成](#代码生成)
- [API 文档](#api-文档)
- [开发指南](#开发指南)

## ✨ 功能特性

- **用户管理**：提供用户信息查询、用户部门关系查询等功能
- **部门管理**：支持部门层级结构管理
- **组织管理**：组织架构管理
- **身份管理**：用户身份和特征信息管理
- **gRPC 服务**：基于 gRPC 的高性能 RPC 服务
- **服务发现**：集成 Nacos 服务注册与发现
- **配置中心**：支持 Nacos 配置中心动态配置
- **数据库访问**：基于 GORM 的数据库访问层，支持代码生成

## 🛠 技术栈

- **语言**: Go 1.23.8
- **框架**: 
  - KingArthur（内部框架）
  - gRPC
- **数据库**: 
  - MySQL
  - GORM（ORM 框架）
  - GORM Gen（代码生成工具）
- **配置中心**: Nacos
- **服务发现**: Nacos Service Discovery
- **缓存**: Redis（通过 KingArthur 框架）
- **日志**: 基于 KingArthur Logger

## 📁 项目结构

```
eagle/
├── api/                    # API 层
│   └── grpc/              # gRPC 接口定义和实现
│       ├── router.go      # gRPC 路由和拦截器
│       └── user/          # 用户服务
│           ├── user.go     # 用户服务实现
│           └── proto/      # Protocol Buffers 定义
├── cmd/                    # 命令行程序入口
│   ├── eagle/             # 主服务入口
│   │   └── main.go
│   └── gormgen/           # 数据库模型生成工具
│       └── main.go
├── configs/                # 配置文件
│   └── config.yaml        # 默认配置文件
├── internal/               # 内部代码
│   ├── driver/            # 驱动层（数据库、缓存、服务发现等）
│   ├── repository/        # 数据访问层
│   │   ├── model/         # 数据模型（自动生成）
│   │   └── persistence/   # 持久化层（自动生成）
│   ├── service/           # 业务逻辑层
│   │   ├── user/          # 用户服务
│   │   ├── department/    # 部门服务
│   │   ├── organization/  # 组织服务
│   │   └── dto/           # 数据传输对象
│   └── pkg/               # 内部工具包
└── go.mod                  # Go 模块定义
```

## 核心架构

### 服务分层架构

```
gRPC API Layer (Protobuf)
        ↓
DDD Application Services (业务编排)
        ↓
Domain Layer (业务规则)
        ↓
Infrastructure Layer (数据持久化)
```

### 职责分离

- **gRPC服务层**: 协议转换、参数校验、错误处理
- **应用服务层**: 业务流程编排、跨聚合协调
- **领域层**: 业务规则封装、领域事件发布
- **基础设施层**: 数据持久化、外部服务集成

### 工作单元分层
```
Application Service (应用服务)
        ↓
    Unit of Work (工作单元)
        ↓
    Repository Adapters (仓储适配器)
        ↓
    GORM Gen Query (生成的查询对象)
        ↓
    Database (数据库)
```

## 服务实现说明

### UserServer - 用户服务

基于 `user.proto` 实现的用户管理服务：

```go
// 核心业务接口
- Invite      // 邀请用户入职
- SetUserInfo // 设置用户信息
- SetUserDept // 设置用户所属部门
- Freeze      // 冻结用户
- Unfreeze    // 解冻用户
- Leave       // 用户离职
- Import      // 导入用户
- Settings    // 用户设置
- Find        // 查询用户
- Search      // 用户列表
```

### DepartmentServer - 部门服务

基于 `department.proto` 实现的部门管理服务：

```go
// 组织/运营管理接口
- Create         // 创建部门
- Update         // 更新部门信息
- Delete         // 删除部门
- UpdateDeptOrder // 更新部门排列
- Freeze         // 冻结部门
- Unfreeze       // 解冻部门
- AddUser        // 添加用户到部门
- RemoveUser     // 从部门移除用户
- Import         // 导入部门

// 查询接口
- Get            // 查询部门详情
- SubDepts       // 查询子部门列表
- SubTree        // 获取部门树结构
```

### OrganizationServer - 组织服务

基于 `organization.proto` 实现的组织管理服务：

```go
// 组织/运营管理接口
- Create    // 创建组织
- Update    // 更新组织信息
- Settings  // 组织设置
- Freeze    // 冻结组织
- Unfreeze  // 解冻组织
- Binding   // 绑定用户到组织

// 查询接口
- Find      // 根据ID查询组织
- List      // 获取组织列表
```

### 应用服务 (Application Service)

应用服务是领域层的客户端，负责：
- 协调多个聚合根的业务操作
- 处理跨聚合的业务规则
- 管理事务和工作单元
- 发布领域事件
- 转换DTO和领域对象

### 工作单元 (Unit of Work)

工作单元模式保证：
- 跨聚合操作的原子性
- 领域事件在事务提交后发布
- 资源的一致性管理

### 命令和查询 (Command Query Separation)

- **命令 (Command)**: 修改系统状态的操作
- **查询 (Query)**: 只读操作，不修改状态

## 🚀 快速开始

### 前置要求

- Go 1.23.8 或更高版本
- MySQL 数据库
- Nacos 服务（用于配置中心和服务发现）
- Redis（可选，用于缓存）

### 安装依赖

```bash
go mod download
```

### 配置数据库

1. 修改 `cmd/gormgen/main.go` 中的数据库连接字符串：
```go
const USER_MySQLDSN = "user:password@(host:port)/database?charset=utf8mb4&parseTime=True&loc=Local"
```

2. 生成数据库模型：
```bash
go run ./cmd/gormgen
```

### 配置服务

编辑 `configs/config.yaml` 文件，配置以下内容：

- Nacos 连接信息
- 数据库连接信息（通过 CMDB 或直接配置）
- Redis 连接信息（通过 CMDB 或直接配置）
- 日志配置
- gRPC 服务端口

### 运行服务

```bash
# 使用默认配置
go run ./cmd/eagle

# 指定环境
go run ./cmd/eagle -e dev

# 指定配置文件
go run ./cmd/eagle -c ./configs/config.yaml

# 指定主机地址
go run ./cmd/eagle -host 127.0.0.1
```

### 编译二进制

```bash
go build -o eagle ./cmd/eagle
./eagle -e prod
```

## ⚙️ 配置说明

### 配置文件结构

```yaml
# 主机地址（代码自动获取，获取失败取该配置）
host: "127.0.0.11"

# Nacos 配置
nacos:
  name: "eagle"              # 服务名称
  env: "dev"                  # 环境
  addr: "nacos://10.10.10.35:8848"  # Nacos 地址
  user-name: "nacos"          # 用户名
  secret: "your-secret"        # 密码
  name-space: "dev"           # 命名空间

# 日志配置
logger-config:
  logger-level: "debug"       # 日志级别
  log-file: ""                # 日志文件路径（空则输出到控制台）
  rotation:
    max-size: 1000            # 最大文件大小(MB)
    max-age: 7                # 最大保留天数
    max-backups: 10           # 最大备份文件数
    compress: true            # 是否压缩旧文件

# CMDB 配置（用于获取数据库和缓存配置）
cmdb:
  address: "http://10.10.10.35"
  application: "eagle"
  secret: "your-secret"
  env: "dev"
  tenant: "default"
  mysql-config:
    name: "eagle@mysql@vrr"
  cache-config:
    name: "eagle@redis@vrr"
    key-serializer: "json"
    value-serializer: "json"
```

### 命令行参数

- `-env, -e`: 运行环境 (dev|test|fat|pre|prod)
- `-config, -c`: 配置文件路径
- `-host`: 本地 IP 地址
- `-help, -h`: 显示帮助信息

## 🔧 代码生成

项目使用 GORM Gen 自动生成数据库模型和持久化层代码。

### 生成数据库模型

1. 修改 `cmd/gormgen/main.go` 中的数据库连接字符串
2. 运行生成命令：

```bash
go run ./cmd/gormgen
```

生成的代码将输出到 `internal/repository/persistence/` 目录。

### 生成配置说明

在 `cmd/gormgen/main.go` 中可以配置：

- `OutPath`: 输出路径
- `Mode`: 生成模式
- `FieldNullable`: 字段是否可为空（false 表示不生成指针类型）

## 📡 API 文档

### gRPC 服务

服务默认监听端口由配置中的 `GrpcPort` 指定。

### 用户服务

#### ListAllUserDeptInfo

查询用户部门信息列表

**请求参数**:
```protobuf
message ListAllUserDeptInfoReq {
  int64 dept_id = 1;        // 部门ID
  string dept_code = 2;     // 部门编码
  bool query_all = 3;       // 是否查询全部（忽略分页）
  int32 page_size = 4;      // 每页大小
  int32 page_num = 5;       // 页码
}
```

**响应参数**:
```protobuf
message ListAllUserDeptInfoRes {
  int32 code = 1;           // 状态码（1000 表示成功）
  string msg = 2;           // 消息
  ListAllUserDeptInfoData data = 3;  // 数据
}
```

## 👨‍💻 开发指南

### 添加新的 gRPC 服务

1. 在 `api/grpc/user/proto/usercore.proto` 中定义新的 RPC 方法
2. 重新生成 protobuf 代码：
```bash
protoc --proto_path=api/grpc/user/proto \
  --go_out=api/grpc/user/proto \
  --go_opt=paths=source_relative \
  --go-grpc_out=api/grpc/user/proto \
  --go-grpc_opt=paths=source_relative \
  api/grpc/user/proto/*.proto


protoc --proto_path=api/grpc \
  --go_out=api/grpc/v1 \
  --go_opt=paths=source_relative \
  --go-grpc_out=api/grpc/v1 \
  --go-grpc_opt=paths=source_relative \
  api/grpc/*.proto
```
3. 在 `api/grpc/router.go` 中注册服务
4. 在 `internal/service/` 中实现业务逻辑

### 添加新的数据库表

1. 在数据库中创建表
2. 在 `cmd/gormgen/main.go` 的 `ApplyBasic` 中添加新表：
```go
g.ApplyBasic(
    g.GenerateModel("new_table_name"),
    // ... 其他表
)
```
3. 运行代码生成工具
4. 在 `internal/repository/` 中使用生成的模型

### 代码规范

- 遵循 Go 官方代码规范
- 使用有意义的变量和函数名
- 添加必要的注释
- 错误处理要完整

## 📝 数据库表结构

主要数据表：

- `cp_user`: 用户表
- `cp_department`: 部门表
- `cp_dept_user`: 用户部门关系表
- `cp_organization`: 组织表
- `cp_identity`: 身份表
- `cp_identity_traits`: 身份特征表

## 🔍 日志

服务使用 KingArthur Logger 进行日志记录，支持：

- 日志级别控制
- 文件输出和轮转
- 结构化日志
- gRPC 请求/响应日志

日志格式包含：
- 时间戳
- 日志级别
- 请求方法
- 客户端 IP
- 请求参数
- 响应结果
- 耗时

## 🐛 问题排查

### 常见问题

1. **服务启动失败**
   - 检查 Nacos 连接是否正常
   - 检查数据库连接配置
   - 查看日志文件获取详细错误信息

2. **数据库连接失败**
   - 确认数据库服务运行正常
   - 检查连接字符串格式
   - 确认网络连通性

3. **代码生成失败**
   - 检查数据库连接字符串
   - 确认表结构存在
   - 检查输出路径权限

## 📄 许可证

内部项目，版权所有。

## 👥 贡献

欢迎提交 Issue 和 Pull Request。

---

**注意**: 这是一个内部服务，请勿将敏感信息（如密码、密钥等）提交到代码仓库。

**待完善**
- 业务错误统一处理
- 错误日志统一处理
- 日志traceId