full/module/base/feedback/README.md

Feedback Service

一个高性能、可扩展的微服务，基于 gRPC 和 HTTP Gateway 架构，提供用户反馈管理、问题跟踪、附件处理等完整的反馈系统功能。

🚀 特性

• 📝 反馈管理: 完整的用户反馈创建、查询、修改、删除功能
• 📎 附件支持: 图片和文件附件上传与管理
• 🏷️ 分类管理: 灵活的反馈分类和状态管理
• 👥 用户关联: 支持多用户、多机构的反馈管理
• 📊 状态跟踪: 反馈处理状态跟踪和备注管理
• ⚡ 高性能: Redis缓存 + 数据库优化
• 🐳 容器化: 完整的Docker支持
• 📊 监控: 健康检查和APM集成
• 🔒 安全: 完善的错误处理和输入验证

📋 目录

• 快速开始
• 项目结构
• 核心功能
• API文档
• 开发指南
• 部署说明
• 性能优化
• 故障排除

🚀 快速开始

环境要求

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

快速安装

# 克隆项目
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 快速启动

# 启动完整服务栈
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)

rpc Add(AddRequest) returns (AddReply)

• 功能: 创建新的用户反馈记录
• 特性:
  • 支持图片和附件上传
  • 自动生成唯一标识
  • 用户身份关联
  • 分类和状态管理

📋 获取反馈列表 (List)

rpc List(ListRequest) returns (ListReply)

• 功能: 分页查询反馈记录列表
• 特性:
  • 支持多条件筛选（用户、状态、分类、机构）
  • 分页查询优化
  • 按创建时间排序
  • 预加载关联图片

🔍 获取反馈详情 (Get)

rpc Get(GetRequest) returns (GetReply)

• 功能: 根据ID获取反馈记录详情
• 特性: 完整记录信息、关联图片和附件

✏️ 修改反馈 (Modify)

rpc Modify(ModifyRequest) returns (StatusReply)

• 功能: 更新反馈记录信息
• 特性:
  • 支持部分字段更新
  • 关联数据同步更新
  • 事务性操作保证

🗑️ 删除反馈 (Delete)

rpc Delete(DeleteRequest) returns (StatusReply)

• 功能: 删除反馈记录
• 特性: 级联删除关联的图片和附件

📝 添加备注 (Remark)

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 文档

🛠️ 开发指南

开发环境设置

# 安装开发工具
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

代码生成

# 生成 protobuf 代码
make proto

# 生成 Swagger 文档
make swagger

测试

# 运行所有测试
go test ./...

# 测试覆盖率
go test -cover ./...

# 代码检查
make lint

# 安全扫描
make security

数据库管理

# 初始化数据库
make init-db

# 备份数据库
make backup-db

🚀 部署说明

Docker 部署

# 构建镜像
make docker-build

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

# 查看日志
make docker-compose-logs

# 停止服务
make docker-compose-down

生产环境部署

1. 环境准备

   # 创建生产配置
   cp etc/feedback_dev.yaml etc/feedback_prod.yaml
   # 编辑生产配置...
   

2. 数据库初始化

   # 执行数据库迁移
   go run cmd/main/main.go migrate
   

3. 服务启动

   # 构建生产版本
   make build-linux
   
   # 启动服务
   ./build/feedback-linux-amd64
   

Kubernetes 部署

# 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查询
• 连接池: 配置合适的连接池大小
• 读写分离: 支持主从数据库配置

监控指标

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

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

🔧 配置说明

环境配置文件

# 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. 服务启动失败

   # 检查端口占用
   netstat -tlnp | grep :12101
   
   # 检查配置文件
   make lint
   

2. 数据库连接失败

   # 测试数据库连接
   psql -h your-db-host -U postgres -d feedback_db -c "SELECT 1;"
   

3. Redis连接失败

   # 测试Redis连接
   redis-cli -h your-redis-host ping
   

日志分析

# 查看服务日志
tail -f logs/feedback.log

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

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

性能调优

1. 内存优化

   # 监控内存使用
   go tool pprof http://localhost:6060/debug/pprof/heap
   

2. CPU优化

   # CPU性能分析
   go tool pprof http://localhost:6060/debug/pprof/profile
   

📊 数据模型

核心表结构

feedback_item - 反馈主表

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 - 反馈图片表

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 - 反馈附件表

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

🔗 相关链接

• BSM SDK
• API 文档
• 问题反馈

---

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

Made with ❤️ by BSM Team