full/module/base/initial/README.md

# Initial Service

[![Go Version](https://img.shields.io/badge/Go-1.25.1-blue.svg)](https://golang.org/)
[![License](https://img.shields.io/badge/License-Internal-red.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/Build-Passing-green.svg)](https://bsm/full/module/base/initial)

一个高性能、可扩展的微服务，基于 gRPC 和 HTTP Gateway 架构，提供应用配置管理、版本更新检查、国家地区数据等基础服务功能。

## 🚀 特性

- **🔧 配置管理**: 多应用、多平台配置参数管理
- **📱 版本控制**: 智能应用版本更新检查
- **🌍 地理数据**: 完整的全球国家和地区层级数据
- **🏷️ 系统数据**: 灵活的系统标签和分类管理
- **⚡ 高性能**: Redis缓存 + 数据库优化
- **🐳 容器化**: 完整的Docker支持
- **📊 监控**: 健康检查和APM集成
- **🔒 安全**: 完善的错误处理和输入验证

## 📋 目录

- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [核心功能](#-核心功能)
- [API文档](#-api文档)
- [开发指南](#-开发指南)
- [部署说明](#-部署说明)
- [性能优化](#-性能优化)
- [故障排除](#-故障排除)

## 🚀 快速开始

### 环境要求

- **Go**: 1.25.1+
- **PostgreSQL**: 12+
- **Redis**: 6+
- **Docker**: 20.10+ (可选)
- **Protocol Buffers**: 3.15+ (开发需要)

### 快速安装

```bash
# 克隆项目
git clone bsm/full/module/base/initial.git
cd initial

# 安装依赖
make deps

# 生成代码
make proto

# 构建应用
make build

# 运行服务
make run
```

### Docker 快速启动

```bash
# 启动完整服务栈
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f initial-service
```

## 📁 项目结构

```
initial/
├── 📁 cmd/                     # 应用程序入口
│   ├── 📁 main/               # 主服务入口
│   └── 📁 cli/                # 命令行工具
├── 📁 internal/               # 内部包
│   ├── 📁 cache/              # 缓存服务
│   ├── 📁 config/             # 配置管理
│   ├── 📁 excode/             # 错误码定义
│   ├── 📁 impl/               # 实现层
│   ├── 📁 logic/              # 业务逻辑
│   │   ├── 📁 check/          # 检查相关逻辑
│   │   └── 📁 data/           # 数据相关逻辑
│   ├── 📁 models/             # 数据模型
│   └── 📁 server/             # 服务器实现
├── 📁 pb/                     # Protocol Buffers 生成代码
├── 📁 proto/                  # Protocol Buffers 定义文件
├── 📁 swagger/                # API 文档
├── 📁 scripts/                # 脚本和SQL文件
├── 📁 test/                   # 测试文件
├── 📁 etc/                    # 配置文件
├── 🐳 Dockerfile              # Docker 镜像构建
├── 🐳 docker-compose.yml      # Docker 编排
├── 🔧 Makefile               # 构建脚本
└── 📖 README.md              # 项目文档
```

## 🔧 核心功能

### 1. 检查服务 (Check Service)

#### 🏥 健康检查 (Hello)
```protobuf
rpc Hello(Crc) returns (StatusReply)
```
- **功能**: 服务健康状态检查
- **特性**: 输入验证、状态监控
- **用途**: 负载均衡器健康检查、服务发现

#### ⚙️ 配置管理 (Config)
```protobuf
rpc Config(ConfigRequest) returns (ConfigReply)
```
- **功能**: 多应用配置参数管理
- **特性**:
  - 支持多操作系统配置
  - 配置优先级处理
  - 自动去重机制
  - Redis缓存加速

#### 🔄 版本更新 (Updates)
```protobuf
rpc Updates(CheckForUpdatesRequest) returns (CheckForUpdatesReply)
```
- **功能**: 智能版本更新检查
- **特性**:
  - 多平台支持 (Windows/Linux/macOS)
  - 架构区分 (amd64/arm64)
  - 版本比较算法
  - 更新文件管理

### 2. 数据服务 (Data Service)

#### 🌍 国家数据 (Country)
```protobuf
rpc Country(Empty) returns (CountryReply)
```
- **数据**: ISO代码、货币、时区、电话区号
- **特性**: 启用状态过滤、排序优化
- **缓存**: 24小时长期缓存

#### 🗺️ 地区数据 (Areas)
```protobuf
rpc Areas(AreasRequest) returns (AreasReply)
```
- **功能**: 层级地区数据查询
- **层级**: 国家 → 省/州 → 市 → 区/县 → 乡镇
- **特性**:
  - 按国家筛选
  - 层级深度控制
  - 拼音支持

#### 🏷️ 系统数据 (Datas)
```protobuf
rpc Datas(Empty) returns (DatasReply)
```
- **功能**: 系统标签和分类管理
- **用途**: 下拉选项、分类标签、系统配置

## 📚 API文档

### gRPC 服务

| 服务 | 方法 | 描述 | 端口 |
|------|------|------|------|
| Check | Hello | 健康检查 | 12101 |
| Check | Config | 配置获取 | 12101 |
| Check | Updates | 更新检查 | 12101 |
| Data | Country | 国家数据 | 12101 |
| Data | Areas | 地区数据 | 12101 |
| Data | Datas | 系统数据 | 12101 |

### HTTP Gateway

| 端点 | 方法 | 描述 |
|------|------|------|
| `/initial.Check/Hello` | POST | 健康检查 |
| `/initial.Check/Config` | POST | 获取配置 |
| `/initial.Check/Updates` | POST | 检查更新 |
| `/initial.Data/Country` | POST | 国家列表 |
| `/initial.Data/Areas` | POST | 地区数据 |
| `/initial.Data/Datas` | POST | 系统数据 |

### Swagger 文档

- **本地**: http://localhost:12102/initial.swagger.json
- **在线**: 通过 HTTP Gateway 访问完整的 API 文档

## 🛠️ 开发指南

### 开发环境设置

```bash
# 安装开发工具
make install-tools

# 设置Git钩子
git config core.hooksPath .githooks

# 启动开发模式
make dev
```

### 代码生成

```bash
# 生成 protobuf 代码
make proto

# 生成 Swagger 文档
make swagger
```

### 测试

```bash
# 运行所有测试
make test

# 测试覆盖率
make test-coverage

# gRPC 功能测试
make test-grpc

# 代码检查
make lint

# 安全扫描
make security
```

### 数据库管理

```bash
# 初始化数据库
make init-db

# 备份数据库
make backup-db
```

## 🚀 部署说明

### Docker 部署

```bash
# 构建镜像
make docker-build

# 启动服务栈
make docker-compose-up

# 查看日志
make docker-compose-logs

# 停止服务
make docker-compose-down
```

### 生产环境部署

1. **环境准备**
   ```bash
   # 创建生产配置
   cp etc/initial_dev.yaml etc/initial_prod.yaml
   # 编辑生产配置...
   ```

2. **数据库初始化**
   ```bash
   # 执行SQL脚本
   psql -h your-db-host -U postgres -d initial_db -f scripts/initial_country_202509081640.sql
   psql -h your-db-host -U postgres -d initial_db -f scripts/initial_areas_202509081640.sql
   ```

3. **服务启动**
   ```bash
   # 构建生产版本
   make build-linux

   # 启动服务
   ./build/initial-linux-amd64
   ```

### Kubernetes 部署

```yaml
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: initial-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: initial-service
  template:
    metadata:
      labels:
        app: initial-service
    spec:
      containers:
      - name: initial-service
        image: initial:latest
        ports:
        - containerPort: 12101
        - containerPort: 12102
        env:
        - name: SERVICE_ENV
          value: "production"
```

## ⚡ 性能优化

### 缓存策略

| 数据类型 | 缓存时间 | 策略 |
|----------|----------|------|
| 配置数据 | 10分钟 | 按应用+OS缓存 |
| 国家数据 | 24小时 | 全量缓存 |
| 地区数据 | 12小时 | 按国家缓存 |
| 系统数据 | 6小时 | 全量缓存 |

### 数据库优化

- **索引优化**: 关键字段建立复合索引
- **查询优化**: 使用 CASE WHEN 进行优先级排序
- **连接池**: 配置合适的连接池大小
- **读写分离**: 支持主从数据库配置

### 监控指标

```bash
# 服务健康检查
curl http://localhost:12102/health

# 性能指标
curl http://localhost:12102/metrics
```

## 🔧 配置说明

### 环境配置文件

```yaml
# etc/initial_prod.yaml
Service: initial
Port: 12101

# 数据库配置
Databases:
  Driver: postgres
  Source:
    - host=db-host user=postgres password=*** dbname=initial_db port=5432 sslmode=require

# 缓存配置
Cache: redis://username:password@redis-host:6379/0

# 网关配置
Gateway:
  Enable: true
  Port: 12102

# 微服务配置
MicroService:
  Enable: true
  Registry: etcd://etcd-cluster:2379

# APM监控
APM:
  Platform: elasticAPM
  Endpoint: http://apm-server:8200
```

### 环境变量

| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| `SERVICE_ENV` | 运行环境 | `development` |
| `CONFIG_FILE` | 配置文件路径 | `etc/initial_dev.yaml` |
| `LOG_LEVEL` | 日志级别 | `info` |
| `TZ` | 时区设置 | `Asia/Shanghai` |

## 🐛 故障排除

### 常见问题

1. **服务启动失败**
   ```bash
   # 检查端口占用
   netstat -tlnp | grep :12101

   # 检查配置文件
   make lint
   ```

2. **数据库连接失败**
   ```bash
   # 测试数据库连接
   psql -h your-db-host -U postgres -d initial_db -c "SELECT 1;"
   ```

3. **Redis连接失败**
   ```bash
   # 测试Redis连接
   redis-cli -h your-redis-host ping
   ```

### 日志分析

```bash
# 查看服务日志
tail -f logs/initial.log

# 查看错误日志
grep ERROR logs/initial.log

# 查看性能日志
grep "slow query" logs/initial.log
```

### 性能调优

1. **内存优化**
   ```bash
   # 监控内存使用
   go tool pprof http://localhost:6060/debug/pprof/heap
   ```

2. **CPU优化**
   ```bash
   # CPU性能分析
   go tool pprof http://localhost:6060/debug/pprof/profile
   ```

## 📊 数据模型

### 核心表结构

#### initial_config - 配置表
```sql
CREATE TABLE initial_config (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    app VARCHAR(255) NOT NULL,
    os VARCHAR(255) DEFAULT '',
    key TEXT DEFAULT '',
    value TEXT DEFAULT '',
    version BIGINT DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### initial_apps - 应用版本表
```sql
CREATE TABLE initial_apps (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    version VARCHAR(255) DEFAULT '',
    app VARCHAR(255) DEFAULT '',
    os VARCHAR(255) DEFAULT '',
    arch VARCHAR(255) DEFAULT '',
    summary TEXT DEFAULT '',
    files TEXT DEFAULT '',
    pubdate TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### initial_country - 国家表
```sql
CREATE TABLE initial_country (
    id SERIAL PRIMARY KEY,
    iso2 VARCHAR(2) UNIQUE NOT NULL,
    iso3 VARCHAR(3) UNIQUE NOT NULL,
    num_code VARCHAR(3),
    phone_code VARCHAR(10),
    currency VARCHAR(24) NOT NULL,
    currency_symbol VARCHAR(24) NOT NULL,
    region VARCHAR(24) NOT NULL,
    name VARCHAR(255) NOT NULL,
    local_name VARCHAR(255) NOT NULL,
    timezones TEXT,
    translations TEXT,
    enabled BOOLEAN DEFAULT true,
    sort_order INTEGER DEFAULT 0
);
```

## 🤝 贡献指南

### 开发流程

1. **Fork 项目**
2. **创建特性分支**: `git checkout -b feature/amazing-feature`
3. **提交更改**: `git commit -m 'Add amazing feature'`
4. **推送分支**: `git push origin feature/amazing-feature`
5. **创建 Pull Request**

### 代码规范

- 遵循 Go 官方代码规范
- 使用 `gofmt` 格式化代码
- 添加必要的注释和文档
- 编写单元测试

### 提交规范

```
type(scope): description

[optional body]

[optional footer]
```

类型:
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建过程或辅助工具的变动

## 📄 许可证

本项目采用内部许可证，仅供 BSM 内部使用。

## 👥 团队

- **作者**: David Yan (david.yan@qq.com)
- **维护者**: BSM 开发团队
- **项目地址**: [bsm/full/module/base/initial](https://bsm/full/module/base/initial)

## 🔗 相关链接

- [BSM SDK](https://git.apinb.com/bsm-sdk)
- [API 文档](https://docs.apinb.com/initial)
- [问题反馈](https://bsm/full/module/base/initial/issues)

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给它一个星标！**

Made with ❤️ by BSM Team

</div>