bsm-infra/full
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9f6f318bbb215827f7ea8d95e7284ec87088d0f8
full/module/ec/mall/README.md

615 lines
14 KiB
Markdown
Raw Blame History

# Mall 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/ec/mall)
一个高性能、可扩展的商城微服务，基于 gRPC 和 HTTP Gateway 架构，提供完整的电商业务功能，包括商品管理、订单处理、用户管理、店铺运营等核心服务。
## 🚀 特性
- **🛍️ 商品管理**: 完整的商品信息管理，支持多规格、多分类、多图片
- **👥 用户系统**: 员工账号管理、权限控制、登录验证
- **🏪 店铺管理**: 多店铺支持、店铺设置、申请入驻
- **📦 分类管理**: 灵活的商品分类体系
- **🚚 物流管理**: 运费模板、区域限制、配送管理
- **📢 营销功能**: 广告管理、公告通知
- **💬 评价系统**: 商品评论、评分管理
- **⚡ 高性能**: Redis缓存 + 数据库优化
- **🐳 容器化**: 完整的Docker支持
- **📊 监控**: 健康检查和APM集成
- **🔒 安全**: 完善的错误处理和输入验证
## 📋 目录
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [核心功能](#-核心功能)
- [API文档](#-api文档)
- [开发指南](#-开发指南)
- [部署说明](#-部署说明)
- [性能优化](#-性能优化)
- [故障排除](#-故障排除)
## 🚀 快速开始
### 环境要求
- **Go**: 1.25.1+
- **MySQL**: 8.0+
- **Redis**: 6+
- **Docker**: 20.10+ (可选)
- **Protocol Buffers**: 3.15+ (开发需要)
### 快速安装
```bash
# 克隆项目
git clone bsm/full/module/ec/mall.git
cd mall
# 安装依赖
go mod tidy
# 生成代码
make proto
# 构建应用
make build
# 运行服务
make run
```
### Docker 快速启动
```bash
# 启动完整服务栈
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f mall-service
```
## 📁 项目结构
```
mall/
├── 📁 cmd/ # 应用程序入口
│ ├── 📁 main/ # 主服务入口
│ └── 📁 cli/ # 命令行工具
├── 📁 internal/ # 内部包
│ ├── 📁 config/ # 配置管理
│ ├── 📁 excode/ # 错误码定义
│ ├── 📁 impl/ # 实现层
│ ├── 📁 logic/ # 业务逻辑
│ │ ├── 📁 ads/ # 广告管理
│ │ ├── 📁 category/ # 分类管理
│ │ ├── 📁 freight/ # 物流管理
│ │ ├── 📁 notice/ # 公告管理
│ │ ├── 📁 product/ # 商品管理
│ │ ├── 📁 staff/ # 员工管理
│ │ └── 📁 store/ # 店铺管理
│ ├── 📁 models/ # 数据模型
│ └── 📁 server/ # 服务器实现
├── 📁 pb/ # Protocol Buffers 生成代码
├── 📁 proto/ # Protocol Buffers 定义文件
├── 📁 swagger/ # API 文档
├── 📁 test/ # 测试文件
├── 📁 etc/ # 配置文件
├── 📁 sdk/ # SDK文件
├── 📁 scripts/ # 脚本文件
└── 📖 README.md # 项目文档
```
## 🔧 核心功能
### 1. 商品管理 (Product Service)
#### 📦 商品操作
```protobuf
rpc ItemCreate(ProductItem) returns (StatusReply)
rpc ItemModify(ProductItem) returns (StatusReply)
rpc ItemDelete(DeleteRequest) returns (StatusReply)
rpc ItemFetch(ItemFetchRequest) returns (ItemFetchReply)
```
- **功能**: 商品的增删改查操作
- **特性**:
- 支持多规格商品
- 多图片管理
- 分类关联
- 库存管理
- 价格管理
#### 🖼️ 图片管理
```protobuf
rpc PhotoCreate(PhotoCreateRequest) returns (StatusReply)
rpc PhotoDelete(DeleteRequest) returns (StatusReply)
rpc PhotoList(PhotoListRequest) returns (PhotoListReply)
```
#### 💬 评论管理
```protobuf
rpc CommentCreate(CommentCreateRequest) returns (StatusReply)
rpc CommentModify(CommentModifyRequest) returns (StatusReply)
rpc CommentDelete(DeleteRequest) returns (StatusReply)
rpc CommentFetch(CommentFetchRequest) returns (CommentFetchReply)
```
### 2. 员工管理 (Staff Service)
#### 🔐 登录认证
```protobuf
rpc Login(LoginRequest) returns (LoginReply)
```
- **功能**: 员工登录验证
- **特性**:
- 账号密码登录
- 手机验证码登录
- JWT Token生成
- 权限验证
#### 👤 员工信息
```protobuf
rpc GetProfile(Empty) returns (GetProfileReply)
rpc SetProfile(SetProfileRequest) returns (StatusReply)
rpc SetPassword(SetPasswordRequest) returns (StatusReply)
```
### 3. 店铺管理 (Store Service)
#### 🏪 店铺操作
```protobuf
rpc ApplyJoin(ApplyJoinRequest) returns (StatusReply)
rpc GetSetting(Empty) returns (GetSettingReply)
rpc SetSetting(SetSettingRequest) returns (StatusReply)
rpc Search(SearchRequest) returns (SearchReply)
```
### 4. 分类管理 (Category Service)
#### 📂 分类操作
```protobuf
rpc Create(CreateRequest) returns (StatusReply)
rpc Modify(ModifyRequest) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)
```
### 5. 物流管理 (Freight Service)
#### 🚚 运费管理
```protobuf
rpc Create(CreateRequest) returns (StatusReply)
rpc Modify(ModifyRequest) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)
```
### 6. 广告管理 (Ads Service)
#### 📢 广告操作
```protobuf
rpc Create(CreateRequest) returns (StatusReply)
rpc Modify(ModifyRequest) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)
rpc ByPos(ByPosRequest) returns (ByPosReply)
```
### 7. 公告管理 (Notice Service)
#### 📢 公告操作
```protobuf
rpc Create(CreateRequest) returns (StatusReply)
rpc Modify(ModifyRequest) returns (StatusReply)
rpc Delete(DeleteRequest) returns (StatusReply)
rpc Fetch(FetchRequest) returns (FetchReply)
```
## 📚 API文档
### gRPC 服务
| 服务 | 方法 | 描述 | 端口 |
|------|------|------|------|
| Product | ItemCreate | 创建商品 | 12101 |
| Product | ItemModify | 修改商品 | 12101 |
| Product | ItemDelete | 删除商品 | 12101 |
| Product | ItemFetch | 查询商品 | 12101 |
| Staff | Login | 员工登录 | 12101 |
| Staff | GetProfile | 获取资料 | 12101 |
| Store | ApplyJoin | 申请入驻 | 12101 |
| Category | Create | 创建分类 | 12101 |
| Freight | Create | 创建运费 | 12101 |
| Ads | Create | 创建广告 | 12101 |
| Notice | Create | 创建公告 | 12101 |
### HTTP Gateway
| 端点 | 方法 | 描述 |
|------|------|------|
| `/mall.Product/ItemCreate` | POST | 创建商品 |
| `/mall.Product/ItemFetch` | POST | 查询商品 |
| `/mall.Staff/Login` | POST | 员工登录 |
| `/mall.Store/ApplyJoin` | POST | 申请入驻 |
| `/mall.Category/Create` | POST | 创建分类 |
| `/mall.Freight/Create` | POST | 创建运费 |
| `/mall.Ads/Create` | POST | 创建广告 |
| `/mall.Notice/Create` | POST | 创建公告 |
### Swagger 文档
- **本地**: http://localhost:12102/mall.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
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
# 生成 protobuf 代码
make proto
# 启动开发模式
make dev
```
### 代码生成
```bash
# 生成 protobuf 代码
make proto
# 生成 Swagger 文档
make swagger
```
### 测试
```bash
# 运行所有测试
make test
# 测试覆盖率
make test-coverage
# gRPC 功能测试
make test-grpc
# 代码检查
make lint
```
### 数据库管理
```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/mall_dev.yaml etc/mall_prod.yaml
# 编辑生产配置...
```
2. **数据库初始化**
```bash
# 执行数据库迁移
make migrate
```
3. **服务启动**
```bash
# 构建生产版本
make build-linux
# 启动服务
./build/mall-linux-amd64
```
### Kubernetes 部署
```yaml
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mall-service
spec:
replicas: 3
selector:
matchLabels:
app: mall-service
template:
metadata:
labels:
app: mall-service
spec:
containers:
- name: mall-service
image: mall:latest
ports:
- containerPort: 12101
- containerPort: 12102
env:
- name: SERVICE_ENV
value: "production"
```
## ⚡ 性能优化
### 缓存策略
| 数据类型 | 缓存时间 | 策略 |
|----------|----------|------|
| 商品信息 | 30分钟 | 按商品ID缓存 |
| 分类数据 | 1小时 | 全量缓存 |
| 用户信息 | 15分钟 | 按用户ID缓存 |
| 店铺信息 | 1小时 | 按店铺ID缓存 |
### 数据库优化
- **索引优化**: 关键字段建立复合索引
- **查询优化**: 使用预加载减少N+1查询
- **连接池**: 配置合适的连接池大小
- **读写分离**: 支持主从数据库配置
### 监控指标
```bash
# 服务健康检查
curl http://localhost:12102/health
# 性能指标
curl http://localhost:12102/metrics
```
## 🔧 配置说明
### 环境配置文件
```yaml
# etc/mall_prod.yaml
Service: mall
Port: 12101
# 数据库配置
Databases:
Driver: mysql
Source:
- user:password@tcp(db-host:3306)/mall_db?charset=utf8mb4&parseTime=True&loc=Local
# 缓存配置
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/mall_dev.yaml` |
| `LOG_LEVEL` | 日志级别 | `info` |
| `TZ` | 时区设置 | `Asia/Shanghai` |
## 🐛 故障排除
### 常见问题
1. **服务启动失败**
```bash
# 检查端口占用
netstat -tlnp | grep :12101
# 检查配置文件
make lint
```
2. **数据库连接失败**
```bash
# 测试数据库连接
mysql -h your-db-host -u username -p mall_db
```
3. **Redis连接失败**
```bash
# 测试Redis连接
redis-cli -h your-redis-host ping
```
### 日志分析
```bash
# 查看服务日志
tail -f logs/mall.log
# 查看错误日志
grep ERROR logs/mall.log
# 查看性能日志
grep "slow query" logs/mall.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
```
## 📊 数据模型
### 核心表结构
#### mall_product - 商品表
```sql
CREATE TABLE mall_product (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
identity VARCHAR(36) UNIQUE NOT NULL,
store_id BIGINT NOT NULL,
store_identity VARCHAR(36) NOT NULL,
serial_id VARCHAR(36),
title VARCHAR(255) NOT NULL,
sub_title VARCHAR(255) NOT NULL,
measuring_name VARCHAR(255),
sell_max INT DEFAULT 0,
sell_min INT DEFAULT 0,
status INT DEFAULT 0,
cover_image VARCHAR(255),
content TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```
#### mall_staff - 员工表
```sql
CREATE TABLE mall_staff (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
identity VARCHAR(36) UNIQUE NOT NULL,
store_id BIGINT NOT NULL,
store_identity VARCHAR(36) NOT NULL,
account VARCHAR(100) UNIQUE NOT NULL,
password VARCHAR(255) NOT NULL,
salt VARCHAR(32) NOT NULL,
name VARCHAR(100) NOT NULL,
phone VARCHAR(20),
role VARCHAR(50) NOT NULL,
status INT DEFAULT 1,
last_login_at TIMESTAMP,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```
#### mall_store - 店铺表
```sql
CREATE TABLE mall_store (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
identity VARCHAR(36) UNIQUE NOT NULL,
title VARCHAR(255) NOT NULL,
description TEXT,
logo VARCHAR(255),
status INT DEFAULT 0,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE 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/ec/mall](https://bsm/full/module/ec/mall)
## 🔗 相关链接
- [BSM SDK](https://git.apinb.com/bsm-sdk)
- [API 文档](https://docs.apinb.com/mall)
- [问题反馈](https://bsm/full/module/ec/mall/issues)
---
<div align="center">
**⭐ 如果这个项目对你有帮助，请给它一个星标！**
Made with ❤️ by BSM Team
</div>
Reference in New Issue View Git Blame Copy Permalink