bsm-infra/full
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
full/module/base/feedback/README.md

542 lines
12 KiB
Markdown
Raw Permalink Blame History

# Feedback 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/feedback)
一个高性能、可扩展的微服务，基于 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/feedback.git
cd feedback
# 安装依赖
go mod download
# 生成代码
make proto
# 构建应用
go build -o bin/feedback cmd/main/main.go
# 运行服务
./bin/feedback
```
### Docker 快速启动
```bash
# 启动完整服务栈
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f feedback-service
```
## 📁 项目结构
```
feedback/
├── 📁 cmd/ # 应用程序入口
│ ├── 📁 main/ # 主服务入口
│ └── 📁 cli/ # 命令行工具
├── 📁 internal/ # 内部包
│ ├── 📁 config/ # 配置管理
│ ├── 📁 impl/ # 实现层
│ ├── 📁 logic/ # 业务逻辑
│ │ └── 📁 method/ # 反馈相关逻辑
│ ├── 📁 models/ # 数据模型
│ └── 📁 server/ # 服务器实现
├── 📁 pb/ # Protocol Buffers 生成代码
├── 📁 proto/ # Protocol Buffers 定义文件
├── 📁 swagger/ # API 文档
├── 📁 scripts/ # 脚本文件
├── 📁 test/ # 测试文件
├── 📁 etc/ # 配置文件
├── 🐳 Dockerfile # Docker 镜像构建
├── 🐳 docker-compose.yml # Docker 编排
├── 🔧 Makefile # 构建脚本
└── 📖 README.md # 项目文档
```
## 🔧 核心功能
### 1. 反馈管理服务 (Method Service)
#### 📝 添加反馈 (Add)
```protobuf
rpc Add(AddRequest) returns (AddReply)
```
- **功能**: 创建新的用户反馈记录
- **特性**:
- 支持图片和附件上传
- 自动生成唯一标识
- 用户身份关联
- 分类和状态管理
#### 📋 获取反馈列表 (List)
```protobuf
rpc List(ListRequest) returns (ListReply)
```
- **功能**: 分页查询反馈记录列表
- **特性**:
- 支持多条件筛选（用户、状态、分类、机构）
- 分页查询优化
- 按创建时间排序
- 预加载关联图片
#### 🔍 获取反馈详情 (Get)
```protobuf
rpc Get(GetRequest) returns (GetReply)
```
- **功能**: 根据ID获取反馈记录详情
- **特性**: 完整记录信息、关联图片和附件
#### ✏️ 修改反馈 (Modify)
```protobuf
rpc Modify(ModifyRequest) returns (StatusReply)
```
- **功能**: 更新反馈记录信息
- **特性**:
- 支持部分字段更新
- 关联数据同步更新
- 事务性操作保证
#### 🗑️ 删除反馈 (Delete)
```protobuf
rpc Delete(DeleteRequest) returns (StatusReply)
```
- **功能**: 删除反馈记录
- **特性**: 级联删除关联的图片和附件
#### 📝 添加备注 (Remark)
```protobuf
rpc Remark(RemarkRequest) returns (StatusReply)
```
- **功能**: 为反馈记录添加备注和更新状态
- **特性**: 支持状态变更和备注记录
## 📚 API文档
### gRPC 服务
| 服务 | 方法 | 描述 | 端口 |
|------|------|------|------|
| Method | Add | 添加反馈 | 12101 |
| Method | List | 获取列表 | 12101 |
| Method | Get | 获取详情 | 12101 |
| Method | Modify | 修改反馈 | 12101 |
| Method | Delete | 删除反馈 | 12101 |
| Method | Remark | 添加备注 | 12101 |
### HTTP Gateway
| 端点 | 方法 | 描述 |
|------|------|------|
| `/feedback.Method/Add` | POST | 添加反馈 |
| `/feedback.Method/List` | POST | 获取列表 |
| `/feedback.Method/Get` | POST | 获取详情 |
| `/feedback.Method/Modify` | POST | 修改反馈 |
| `/feedback.Method/Delete` | POST | 删除反馈 |
| `/feedback.Method/Remark` | POST | 添加备注 |
### Swagger 文档
- **本地**: http://localhost:12102/feedback.swagger.json
- **在线**: 通过 HTTP Gateway 访问完整的 API 文档
## 🛠️ 开发指南
### 开发环境设置
```bash
# 安装开发工具
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
# 设置Git钩子
git config core.hooksPath .githooks
# 启动开发模式
go run cmd/main/main.go
```
### 代码生成
```bash
# 生成 protobuf 代码
make proto
# 生成 Swagger 文档
make swagger
```
### 测试
```bash
# 运行所有测试
go test ./...
# 测试覆盖率
go test -cover ./...
# 代码检查
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/feedback_dev.yaml etc/feedback_prod.yaml
# 编辑生产配置...
```
2. **数据库初始化**
```bash
# 执行数据库迁移
go run cmd/main/main.go migrate
```
3. **服务启动**
```bash
# 构建生产版本
make build-linux
# 启动服务
./build/feedback-linux-amd64
```
### Kubernetes 部署
```yaml
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: feedback-service
spec:
replicas: 3
selector:
matchLabels:
app: feedback-service
template:
metadata:
labels:
app: feedback-service
spec:
containers:
- name: feedback-service
image: feedback:latest
ports:
- containerPort: 12101
- containerPort: 12102
env:
- name: SERVICE_ENV
value: "production"
```
## ⚡ 性能优化
### 缓存策略
| 数据类型 | 缓存时间 | 策略 |
|----------|----------|------|
| 反馈列表 | 5分钟 | 按用户+条件缓存 |
| 反馈详情 | 10分钟 | 按ID缓存 |
| 用户信息 | 30分钟 | 按用户ID缓存 |
### 数据库优化
- **索引优化**: 关键字段建立复合索引
- **查询优化**: 使用预加载减少N+1查询
- **连接池**: 配置合适的连接池大小
- **读写分离**: 支持主从数据库配置
### 监控指标
```bash
# 服务健康检查
curl http://localhost:12102/health
# 性能指标
curl http://localhost:12102/metrics
```
## 🔧 配置说明
### 环境配置文件
```yaml
# etc/feedback_prod.yaml
Service: feedback
Port: 12101
# 数据库配置
Databases:
Driver: postgres
Source:
- host=db-host user=postgres password=*** dbname=feedback_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/feedback_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 feedback_db -c "SELECT 1;"
```
3. **Redis连接失败**
```bash
# 测试Redis连接
redis-cli -h your-redis-host ping
```
### 日志分析
```bash
# 查看服务日志
tail -f logs/feedback.log
# 查看错误日志
grep ERROR logs/feedback.log
# 查看性能日志
grep "slow query" logs/feedback.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
```
## 📊 数据模型
### 核心表结构
#### feedback_item - 反馈主表
```sql
CREATE TABLE feedback_item (
id SERIAL PRIMARY KEY,
identity VARCHAR(255) NOT NULL,
passport_id VARCHAR(255) DEFAULT '',
passport_identity VARCHAR(255) DEFAULT '',
category VARCHAR(255) DEFAULT '',
user_name VARCHAR(20) DEFAULT '',
email VARCHAR(255) DEFAULT '',
phone VARCHAR(20) DEFAULT '',
status INTEGER DEFAULT 1,
title VARCHAR(255) DEFAULT '',
content VARCHAR(500) DEFAULT '',
remark VARCHAR(500) DEFAULT '',
agency VARCHAR(255) DEFAULT '',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
#### feedback_images - 反馈图片表
```sql
CREATE TABLE feedback_images (
id SERIAL PRIMARY KEY,
identity VARCHAR(255) NOT NULL,
item_identity VARCHAR(36) DEFAULT '',
url VARCHAR(255) DEFAULT '',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
#### feedback_accessory - 反馈附件表
```sql
CREATE TABLE feedback_accessory (
id SERIAL PRIMARY KEY,
identity VARCHAR(255) NOT NULL,
item_identity VARCHAR(36) DEFAULT '',
title VARCHAR(255) DEFAULT '',
file_path VARCHAR(500) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
## 🤝 贡献指南
### 开发流程
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/feedback](https://bsm/full/module/base/feedback)
## 🔗 相关链接
- [BSM SDK](https://git.apinb.com/bsm-sdk)
- [API 文档](https://docs.apinb.com/feedback)
- [问题反馈](https://bsm/full/module/base/feedback/issues)
---
<div align="center">
**⭐ 如果这个项目对你有帮助，请给它一个星标！**
Made with ❤️ by BSM Team
</div>
Reference in New Issue View Git Blame Copy Permalink