full/module/base/passport/README.md

# BSM 通行证服务

基于 Go、gRPC 和 Protocol Buffers 构建的综合用户认证和账户管理服务。

## 🚀 功能特性

- **用户认证**: 支持密码登录和验证码登录
- **账户管理**: 完整的用户资料和数据管理
- **标签系统**: 用户标签和分类管理
- **KYC 集成**: 与 Jumio 的身份验证集成
- **密码找回**: 安全的密码重置功能
- **统计分析**: 用户活动和参与度指标
- **gRPC 和 REST API**: 通过 gRPC-Gateway 支持双协议
- **微服务架构**: 可扩展和可维护的设计
- **数据库支持**: 兼容 PostgreSQL 和 MySQL
- **缓存**: Redis 集成以优化性能
- **服务发现**: Etcd 集成用于微服务协调

## 📋 系统要求

- Go 1.26.5 或更高版本
- PostgreSQL 或 MySQL 数据库
- Redis 服务器
- Etcd（微服务模式需要）
- Protocol Buffers 编译器 (protoc)
- Buf CLI（用于 proto 管理）

## 🛠️ 安装部署

1. **克隆仓库**
   ```bash
   git clone bsm/full/module/base/passport
   cd passport
   ```

2. **安装依赖**
   ```bash
   go mod download
   ```

3. **安装开发工具**
   ```bash
   go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
   go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
   go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
   go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
   ```

4. **生成 Protocol Buffer 文件**
   ```bash
   # Buf 配置已移除；请使用团队约定的 protoc 生成命令
   ```

## ⚙️ 配置说明

服务使用位于 `etc/` 目录下的 YAML 配置文件：

- `passport_dev.yaml` - 开发环境
- `passport_prod.yaml` - 生产环境  
- `passport_test.yaml` - 测试环境

### 配置结构

```yaml
Service: passport
Port: 12426

# 数据库配置
Databases:
  Driver: postgres  # 或 mysql
  Source:
    - host=localhost user=postgres password=yourpassword dbname=bsm_dev port=5432 sslmode=disable TimeZone=Asia/Shanghai

# Redis 缓存
Cache: redis://null:yourpassword@localhost:6379/

# 微服务设置
MicroService: 
  Enable: false
  Anonymous:
    - passport.ping.hello

# 微信集成
WeChatConf:
  AppID: your_wechat_app_id
  AppSecret: your_wechat_app_secret

# KYC 配置
Kyc:
  Provider: jumio
  BaseUrl: https://api.jumio.com
  ApiSecret: your_api_secret
  ApiToken: your_api_token
  ApiArgs: additional_args

# 网关设置
Gateway:
  Enable: true
  Port: 12425

# JWT Token 配置
Token:
  Prefix: "/token/"
  Expire: 86400  # 24小时（秒）

# 服务密钥
SecretKey: your_32_character_secret_key_here
```

## 🚀 运行服务

### 开发模式

1. **启动主服务**
   ```bash
   go run cmd/main/main.go
   ```

2. **访问服务**
   - gRPC: `localhost:12426`
   - REST API: `localhost:12425`
   - Swagger UI: `http://localhost:12425/passport.swagger.json`

### 生产环境部署

1. **构建二进制文件**
   ```bash
   go build -o passport cmd/main/main.go
   ```

2. **使用生产配置运行**
   ```bash
   ./passport -env=prod
   ```

## 📚 API 文档

### gRPC 服务

服务提供以下 gRPC 服务：

#### 账户服务 (Account Service)
- `Get()` - 获取完整用户信息
- `SetData()` - 更新用户资料数据
- `SetPassword()` - 修改用户密码
- `TagCreate()` - 创建用户标签
- `TagRemove()` - 删除用户标签
- `Statistics()` - 获取用户统计信息

#### 登录服务 (Login Service)
- `Pwd()` - 密码登录
- `Code()` - 验证码登录

#### 注册服务 (Register Service)
- `Code()` - 发送注册验证码
- `Pwd()` - 密码注册
- `Do()` - 完成注册流程

#### 找回密码服务 (Forget Service)
- `Verify()` - 验证密码重置请求
- `Reset()` - 重置密码

#### KYC 服务 (KYC Service)
- `Request()` - 发起 KYC 验证
- `JumioCallback()` - 处理 KYC 提供商回调

### REST API

所有 gRPC 服务通过 gRPC-Gateway 自动暴露为 REST 端点：

- `POST /v1/account` - 获取用户账户
- `POST /v1/account/data` - 更新用户数据
- `POST /v1/account/password` - 修改密码
- `POST /v1/login/pwd` - 密码登录
- `POST /v1/login/code` - 验证码登录
- `POST /v1/register` - 用户注册

## 🏗️ 系统架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   gRPC 客户端   │    │   REST 客户端   │    │   Web 客户端    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  gRPC 网关      │
                    └─────────────────┘
                                 │
                    ┌─────────────────┐
                    │  gRPC 服务器    │
                    └─────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   PostgreSQL    │    │      Redis      │    │      Etcd       │
│     MySQL       │    │      缓存       │    │    服务发现     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## 🔧 开发指南

### 项目结构

```
passport/
├── cmd/                    # Application entry points
│   ├── main/              # Main service
│   └── cli/               # CLI tools
├── internal/              # Private application code
│   ├── config/           # Configuration management
│   ├── impl/             # Service implementations
│   ├── logic/            # Business logic
│   ├── models/           # Database models
│   ├── server/           # gRPC server setup
│   └── vars/             # Constants and variables
├── pb/                   # Generated Protocol Buffer files
├── proto/                # Protocol Buffer definitions
├── etc/                  # Configuration files
├── swagger/              # OpenAPI/Swagger documentation
├── scripts/              # Build and deployment scripts
└── test/                 # Test files and examples
```

### Adding New Features

1. **Define Protocol Buffers**
   ```bash
   # Edit proto files in proto/
   vim proto/your_service.proto
   ```

2. **Generate Code**
   ```bash
   # Buf 配置已移除；请使用团队约定的 protoc 生成命令
   ```

3. **Implement Business Logic**
   ```bash
   # Add logic in internal/logic/
   vim internal/logic/your_service/your_method.go
   ```

4. **Register Service**
   ```bash
   # Update server registration in internal/server/
   vim internal/server/new.go
   ```

### Testing

```bash
# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Test specific package
go test ./internal/logic/login/
```

### Code Generation

```bash
# Generate Protocol Buffer files
# Buf 配置已移除；请使用团队约定的 protoc 生成命令

# Lint proto files
# 使用团队约定的 proto lint 工具

# Format proto files
# 使用团队约定的 proto 格式化工具
```

## 🔒 Security Features

- **Password Hashing**: bcrypt with salt for secure password storage
- **JWT Tokens**: Secure token-based authentication
- **Input Validation**: Comprehensive request validation
- **SQL Injection Protection**: Parameterized queries with GORM
- **Rate Limiting**: Built-in request rate limiting
- **CORS Support**: Configurable cross-origin resource sharing

## 📊 Monitoring & Observability

- **Structured Logging**: JSON-formatted logs with different levels
- **Metrics**: Built-in metrics collection
- **Health Checks**: Service health monitoring endpoints
- **Distributed Tracing**: APM integration support
- **Performance Monitoring**: Request/response time tracking

## 🐳 Docker Support

```dockerfile
# Build stage
FROM golang:1.26.5-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download
RUN go build -o passport cmd/main/main.go

# Runtime stage
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/passport .
COPY --from=builder /app/etc ./etc
COPY --from=builder /app/swagger ./swagger
CMD ["./passport"]
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Code Style

- Follow Go conventions and best practices
- Use `gofmt` for code formatting
- Add comments for exported functions
- Write tests for new features
- Update documentation as needed

## 📝 License

This project is proprietary software. All rights reserved.

## 🆘 Support

For support and questions:

- Create an issue in the repository
- Contact the development team
- Check the documentation in `/docs`

## 🔄 Version History

- **v1.0.0** - Initial release with core authentication features
- **v1.1.0** - Added KYC integration and tag system
- **v1.2.0** - Enhanced security and performance optimizations
- **Current** - Go 1.26.5 compatibility and bug fixes

## 🚀 Roadmap

- [ ] OAuth2 integration
- [ ] Multi-factor authentication
- [ ] Advanced user analytics
- [ ] Mobile SDK support
- [ ] GraphQL API support
- [ ] Kubernetes deployment manifests

---

**Built with ❤️ by the BSM Development Team**