refactor: reorganize modules and add Linux build tooling
This commit is contained in:
615
module/ec/mall/README.md
Normal file
615
module/ec/mall/README.md
Normal file
@@ -0,0 +1,615 @@
|
||||
# Mall Service
|
||||
|
||||
[](https://golang.org/)
|
||||
[](LICENSE)
|
||||
[](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
Block a user