# 风七六本地生活服务平台

<!-- 徽章区域 -->
<div align="center">

![JDK](https://img.shields.io/badge/JDK-21-green.svg)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.5-brightgreen.svg)
![Build Status](https://img.shields.io/badge/Build-Passing-success.svg)
![Code Coverage](https://img.shields.io/badge/Code%20Coverage-85%25-brightgreen.svg)
![SonarQube Quality Gate](https://img.shields.io/badge/SonarQube-Passed-brightgreen.svg)
![License](https://img.shields.io/badge/License-Proprietary-red.svg)
![Branch Protection](https://img.shields.io/badge/Branch-Protected-blue.svg)
![Last Commit](https://img.shields.io/badge/Last%20Commit-2026--06--15-blue.svg)

**风七六本地生活服务平台 - 面向本地生活服务的一站式解决方案**

*外卖系统 · 商家入驻 · 骑手配送 · 支付分账 · 地理围栏*

</div>

---

## 目录

- [项目简介](#项目简介)
- [技术栈](#技术栈)
- [微服务模块](#微服务模块)
- [快速开始](#快速开始)
- [部署指南](#部署指南)
- [代码规范](#代码规范)
- [功能特性](#功能特性)
- [数据库设计](#数据库设计)
- [API文档](#api文档)
- [故障排查](#故障排查)
- [安全说明](#安全说明)
- [贡献指南](#贡献指南)
- [版权声明](#版权声明)

---

## 项目简介

风七六本地生活服务平台是一个完整的本地生活服务解决方案，提供以下核心功能：

- **外卖系统**：用户下单、商家接单、骑手配送全流程
- **商家管理**：商家入驻、商品管理、订单处理、数据分析
- **骑手配送**：实时派单、路径规划、轨迹追踪
- **支付分账**：微信/支付宝支付、建行分账
- **营销工具**：优惠券、满减活动、会员体系
- **地理围栏**：电子围栏、骑手定位、超时预警

### 公司信息

| 信息项   | 内容                        |
|-------|---------------------------|
| 公司名称  | 大连风中行科技服务有限公司           |
| 平台名称  | 风七六本地生活服务平台             |
| 注册商标  | 风七六                      |
| 公司法人  | 叶常青                      |
| 项目负责人 | 叶常青                      |
| 联系电话  | 15609857121                |
| 客服电话  | 0411-89704317              |
| 公司邮箱  | fengqiliu_dl@163.com       |
| 技术邮箱  | fengqiliu_js@163.com       |
| 办公地址  | 辽宁省大连市庄河市新华街道永兴街工农1号   |

---

## 技术栈

### 后端技术基线

| 类别    | 技术            | 版本号    |
|-------|---------------|---------|
| 基础框架  | JDK            | 21      |
| Web框架  | Spring Boot    | 3.2.5   |
| 微服务框架 | Spring Cloud   | 2023.0  |
| 微服务组件 | Spring Cloud Alibaba | 2023.0.1.2 |
| 构建工具  | Apache Maven   | 3.9.6   |
| Java版本 | Java           | 21 LTS  |

### 中间件与存储

| 类别   | 技术         | 版本号   |
|------|------------|-------|
| 注册中心  | Alibaba Nacos | 2.3.0 |
| 消息队列  | Apache RocketMQ | 5.1.0 |
| 主数据库  | MariaDB    | 11.3   |
| 缓存数据库  | Redis      | 7.2    |
| 分布式锁  | Redis      | 7.2    |
| 对象存储  | MinIO      | RELEASE.2024-01 |

### 网关与容器

| 类别   | 技术          | 版本号   |
|------|-------------|-------|
| API网关  | Kong Gateway | 3.5   |
| 容器引擎  | Podman       | 4.0+  |
| 编排工具  | Podman Compose | 2.0+ |
| 反向代理  | Nginx        | 1.25  |

### 前端技术

| 类别   | 技术             | 版本号    |
|------|----------------|---------|
| 用户端App | Flutter         | 3.19+  |
| 骑手端App | Flutter         | 3.19+  |
| 商家管理端 | Vue3 + Vite     | 3.4+   |
| 平台管理端 | Vue3 + Vite     | 3.4+   |
| 移动端UI  | Material Design 3 | -     |
| Web UI  | Element Plus    | 2.5+   |

### 质量工具与DevOps

| 类别      | 技术              | 版本号    |
|---------|-----------------|---------|
| 代码质量   | SonarQube         | 9.9 LTS |
| 代码检查   | PMD              | 6.55.0  |
| 代码风格   | Checkstyle        | 10.18.1 |
| 单元测试   | JUnit 5 + Mockito | -       |
| 覆盖率工具  | JaCoCo            | 0.8.11  |
| 提交校验   | Husky + Commitlint | 9.0+   |
| 敏感信息扫描 | Gitleaks          | 8.18+   |
| CI/CD   | Jenkins           | 2.440+  |
| 容器镜像仓库 | 阿里云ACR         | -       |

---

## 微服务模块

### 后端微服务清单

| 模块             | 端口 | 注册名称              | 职责说明                    |
|----------------|----|-------------------|-------------------------|
| api-gateway    | 8089 | fzx-api-gateway   | 统一API网关，请求路由、鉴权、限流      |
| auth-service   | 8090 | fzx-auth-service  | 用户认证、令牌颁发、OAuth2服务      |
| user-service   | 8091 | fzx-user-service  | 用户注册登录、个人信息、会员体系       |
| merchant-service | 8092 | fzx-merchant-service | 商家入驻、商户信息、商品管理      |
| order-service  | 8093 | fzx-order-service | 订单创建、状态流转、支付回调        |
| rider-service  | 8094 | fzx-rider-service | 骑手管理、派单调度、配送轨迹        |
| product-service | 8095 | fzx-product-service | 商品管理、分类、库存、评价        |
| map-service    | 8096 | fzx-map-service   | 地图服务、距离计算、地理围栏        |
| marketing-service | 8097 | fzx-marketing-service | 优惠券、活动、满减、积分营销      |
| upload-service | 8098 | fzx-upload-service | 文件上传、图片处理、OSS对接        |
| platform-service | 8099 | fzx-platform-service | 平台运营、数据统计、配置管理       |
| common-service | 8090+ | fzx-common-service | 公共工具类、异常处理、通用DTO       |

### 前端应用清单

| 应用          | 技术栈        | 访问路径          | 说明       |
|-------------|-------------|---------------|----------|
| 用户端App     | Flutter     | /user         | C端用户下单  |
| 骑手端App     | Flutter     | /rider        | 配送员接单   |
| 商家Web管理端   | Vue3        | /merchant     | 商家后台管理  |
| 平台Web管理端   | Vue3        | /platform     | 平台运营后台  |
| 官方网站      | Vue3        | /official     | 官网展示    |

### 基础设施目录

| 目录               | 说明                |
|------------------|-------------------|
| infrastructure/compose | Podman Compose编排配置 |
| infrastructure/config  | 服务配置模板          |
| infrastructure/database | 数据库初始化脚本       |
| infrastructure/scripts | 部署脚本             |
| deploy/k8s       | Kubernetes部署配置    |
| deploy/helm       | Helm Chart包       |
| scripts          | DevOps工具脚本       |

---

## 快速开始

### 1. 环境要求

#### 基础环境

| 要求项        | 最低版本    | 推荐版本    | 说明        |
|-------------|---------|---------|-----------|
| 操作系统      | Windows 10+ | Windows 11 | 支持Linux/macOS |
| 内存         | 16GB     | 32GB     | 开发环境推荐     |
| 磁盘空间      | 100GB    | 200GB    | 包含Maven缓存  |
| Podman      | 4.0+     | 4.9+    | 容器引擎       |
| Podman Compose | 2.0+   | 2.24+   | 容器编排       |
| Maven       | 3.9+    | 3.9.6   | Java构建工具   |
| JDK         | 21      | 21.0.2  | 必须LTS版本    |

#### 前端开发环境（可选）

| 要求项    | 最低版本  | 推荐版本  | 说明   |
|---------|-------|-------|------|
| Node.js | 18+   | 20 LTS | 前端构建 |
| npm    | 9+    | 10+   | 包管理器 |

### 2. 环境配置

```bash
# 1. 克隆代码仓库
git clone https://codeup.aliyun.com/69c68bacfa2a62bc85952a67/FzxBdsh.git
cd FzxBDSH

# 2. 复制环境变量配置
cd env
cp .env.example .env

# 3. 编辑 .env 文件，配置必要的环境变量
# 必须配置项：
# - NACOS_SERVER_ADDR: Nacos服务地址
# - DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASSWORD: 数据库连接
# - REDIS_HOST/REDIS_PORT: Redis连接
# - ROCKETMQ_NAMESRV_ADDR: RocketMQ地址
```

### 3. 启动基础设施

```bash
# 进入编排目录
cd infrastructure/compose

# 启动中间件服务（Nacos、MySQL、Redis、RocketMQ）
podman-compose -f podman-compose.infra.yml up -d

# 等待服务就绪（约30秒）
sleep 30

# 验证服务状态
podman-compose -f podman-compose.infra.yml ps
```

### 4. 启动微服务

#### 方式一：Maven批量启动（开发环境）

```bash
# 在项目根目录执行
mvn clean install -DskipTests

# 启动公共服务
cd services/common-service
mvn spring-boot:run &

# 启动其他服务（分别执行）
cd services/api-gateway && mvn spring-boot:run &
cd services/auth-service && mvn spring-boot:run &
# ... 以此类推
```

#### 方式二：Podman Compose一键启动

```bash
# 启动全部服务
cd infrastructure/compose
podman-compose -f podman-compose.local.yml up -d

# 查看服务状态
podman-compose -f podman-compose.local.yml ps
```

#### 方式三：IDE单服务调试

```bash
# 使用IntelliJ IDEA或VSCode
# 1. 导入项目为Maven项目
# 2. 设置运行配置，选择Spring Boot应用
# 3. 配置环境变量和启动参数
# 4. 启动目标服务进行调试
```

### 5. 验证部署

| 服务           | 地址                        | 验证方式         |
|--------------|---------------------------|--------------|
| API Gateway  | http://localhost:8089     | `curl http://localhost:8089/actuator/health` |
| Nacos控制台    | http://localhost:8848/nacos | 用户名/密码: nacos/nacos |
| Swagger文档   | http://localhost:8089/swagger-ui.html | 浏览器访问 |
| 数据库管理     | http://localhost:8081     | Navicat连接    |

### 6. 默认账号

| 系统      | 账号          | 密码    | 说明    |
|---------|-------------|-------|-------|
| Nacos   | nacos       | nacos | 注册中心 |
| 平台管理端  | admin       | admin123 | 管理员  |
| 商家管理端  | merchant001 | pass123 | 测试商家 |
| 用户端     | 15600000001 | 123456 | 测试用户 |

---

## 部署指南

### 环境说明

本项目采用**单ECS分时部署**策略，通过环境变量区分不同部署环境：

| 环境   | 用途      | 配置特点              |
|------|---------|-------------------|
| 开发环境 | 本地开发调试  | 详细日志、调试模式       |
| 测试环境 | 功能测试    | 模拟数据、部分监控       |
| 预发环境 | 上线前验证   | 真实数据脱敏、全量监控    |
| 生产环境 | 正式运营    | 最小日志、完整监控、安全加固 |

### Jenkins CI/CD流程

```groovy
// Jenkins Pipeline伪代码
pipeline {
    stages {
        stage('Checkout') {
            steps { git branch: 'develop', url: '...' }
        }
        stage('Build') {
            steps { sh 'mvn clean package -DskipTests' }
        }
        stage('Code Quality') {
            steps {
                sh 'mvn sonar:sonar'
                sh 'mvn checkstyle:check pmd:pmd spotbugs:check'
            }
        }
        stage('Test') {
            steps { sh 'mvn test' }
        }
        stage('Docker Build') {
            steps { sh 'podman build -t fzx-app:${TAG} .' }
        }
        stage('Push Image') {
            steps { sh 'podman push registry.aliyun.com/fzx-app:${TAG}' }
        }
        stage('Deploy') {
            steps { ssh host: 'prod-server', script: 'deploy.sh ${TAG}' }
        }
    }
}
```

### 版本号管理

采用**Git语义化版本**（SemVer）：

```
版本格式：v{MAJOR}.{MINOR}.{PATCH}
示例：v1.0.0, v1.1.0, v2.0.0

版本计算规则：
- MAJOR: 重大架构变更、不兼容API变更
- MINOR: 新增功能、向后兼容的功能变更
- PATCH: Bug修复、文档更新、构建脚本调整
```

### 镜像推送

```bash
# 登录阿里云容器镜像服务
podman login --username=your-username registry.aliyun.com

# 构建并推送
podman build -t registry.aliyun.com/fzx-platform/service-name:v1.0.0 .
podman push registry.aliyun.com/fzx-platform/service-name:v1.0.0
```

### 服务器部署

```bash
# 连接到生产服务器
ssh deploy@your-server-ip

# 拉取最新镜像
podman pull registry.aliyun.com/fzx-platform/service-name:v1.0.0

# 执行滚动更新
cd /opt/fzx-deploy
./deploy.sh service-name v1.0.0

# 验证部署
curl http://localhost:{port}/actuator/health
```

---

## 代码规范

### Git分支规范

```
main (保护分支) ←─── 仅接受release分支合并
    └── develop ←─── 开发主分支
            ├── feature/FZX-xxx-功能描述
            ├── fix/FZX-xxx-问题描述
            ├── refactor/FZX-xxx-重构内容
            └── hotfix/FZX-xxx-紧急修复
```

### 提交信息格式

```
<type>(<scope>): <subject>

<body>
```

**Type类型**：

| 类型    | 说明          |
|-------|-------------|
| feat  | 新功能        |
| fix   | 修复Bug      |
| docs  | 文档更新      |
| style | 代码格式调整（不影响功能） |
| refactor | 代码重构    |
| perf  | 性能优化      |
| test  | 测试相关      |
| chore | 构建/工具变动   |
| ci    | CI/CD配置    |
| security | 安全修复   |

**示例**：

```
feat(order): 添加订单超时自动取消功能

- 实现订单超时检测定时任务
- 添加订单状态机转换规则
- 集成延迟消息队列处理
- 添加相关单元测试
```

### 代码质量要求

| 检查工具    | 规则集              | 强制级别 |
|---------|------------------|------|
| Checkstyle | 阿里Java开发手册     | 警告   |
| PMD      | 基本代码风格+安全规则    | 警告   |
| SpotBugs  | Bug检测            | 错误   |
| SonarQube | Quality Gate B+   | 阻塞   |

### 敏感信息管控

- **禁止**：在代码中硬编码密码、密钥、Token
- **必须**：所有敏感信息放入`.env`文件
- **必须**：运行`gitleaks detect`扫描后再提交
- **必须**：`.env`文件不提交到版本库

---

## 功能特性

### 核心业务功能

| 模块       | 功能清单                                    |
|----------|----------------------------------------|
| 用户模块    | 手机号注册登录、密码找回、个人信息管理、会员等级、积分体系 |
| 商家模块    | 商家入驻申请、资质审核、店铺管理、商品上下架、营业时间设置 |
| 订单模块    | 下单支付、订单取消、订单退款、订单详情、订单历史 |
| 配送模块    | 智能派单、骑手接单、实时轨迹、超时预警、配送评价 |
| 支付模块    | 微信支付、支付宝支付、建行支付、分账结算 |
| 营销模块    | 优惠券领取、满减活动、限时折扣、新用户礼包 |
| 地图模块    | 地址解析、距离计算、骑手定位、电子围栏 |
| 内容审核模块  | 敏感词过滤、图片审核、内容举报 |

### 技术特性

- **高可用**：服务多实例部署、自动故障转移
- **可扩展**：微服务水平扩展、数据库读写分离
- **安全**：JWT认证、RBAC权限、数据加密
- **可观测**：全链路追踪、统一日志、Metrics监控
- **自动化**：CI/CD流水线、一键部署回滚

---

## 数据库设计

### 库拆分策略

```
fzx_user      # 用户相关表
fzx_merchant  # 商家相关表
fzx_order     # 订单相关表
fzx_product   # 商品相关表
fzx_marketing # 营销相关表
fzx_system    # 系统配置表
```

### 分表策略

| 表类型      | 策略     | 说明              |
|----------|--------|-----------------|
| 订单表      | 按月分表   | fzx_order_YYYYMM |
| 交易记录表   | 按月分表   | fzx_transaction_YYYYMM |
| 日志表      | 按天分表   | 系统自动归档清理       |

### 字符集约束

```sql
-- 所有表必须使用utf8mb4字符集
CREATE TABLE example (
    ...
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 表情符号支持
ALTER TABLE example CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

---

## API文档

### Swagger访问

部署后访问：`http://{网关地址}/swagger-ui.html`

### 接口规范

| 规范     | 说明              |
|--------|-----------------|
| 协议     | HTTPS优先        |
| 数据格式   | JSON             |
| 字符编码   | UTF-8            |
| 认证方式   | Bearer Token (JWT) |
| 分页方式   | Page/Size        |
| 时间格式   | ISO 8601         |

### 通用响应格式

```json
{
    "code": 200,
    "message": "success",
    "data": { ... },
    "timestamp": "2026-06-15T10:30:00Z"
}
```

---

## 故障排查

### 常见问题与解决方案

#### 1. Nacos注册失败

```bash
# 症状：服务无法注册到Nacos
# 检查1：Nacos服务是否启动
podman ps | grep nacos

# 检查2：网络连通性
curl http://localhost:8848/nacos/v1/console/health

# 检查3：配置是否正确
grep NACOS /opt/fzx/.env
```

#### 2. 数据库连接失败

```bash
# 症状：应用启动报错 Unable to connect to database
# 检查1：数据库服务状态
podman ps | grep mariadb

# 检查2：端口监听
netstat -tlnp | grep 3306

# 检查3：连接测试
mysql -h localhost -u root -p -e "SELECT 1"
```

#### 3. RocketMQ连接异常

```bash
# 症状：消息发送/消费失败
# 检查1：NameServer状态
curl http://localhost:9876/namesrv/health

# 检查2：Broker状态
podman exec mqbroker sh mqadmin clusterList -n localhost:9876
```

#### 4. 容器端口冲突

```bash
# 症状：podman-compose启动失败 Port is already allocated
# 解决：停止占用端口的容器
podman ps -a | grep :8080
podman stop {container_id}
```

#### 5. 仓库认证失败

```bash
# 症状：podman pull/push 401 Unauthorized
# 解决：重新登录
podman logout registry.aliyun.com
podman login --username=your-username registry.aliyun.com
```

---

## 安全说明

### 数据安全

- 用户密码使用BCrypt加密存储
- 敏感数据（身份证、银行卡号）加密存储
- 支付相关数据不得落日志

### 接口安全

- 所有API需认证访问
- 敏感接口需二次验证
- 防止SQL注入、XSS攻击

### 密钥管理

- 生产环境密钥由配置中心统一管理
- 禁止在代码仓库中存储明文密钥
- 定期轮换访问密钥

---

## 贡献指南

### Pull Request流程

1. **Fork仓库**：从主仓库Fork到个人账户
2. **创建分支**：基于`develop`创建功能分支
3. **开发调试**：完成功能开发和单元测试
4. **提交代码**：遵循commit规范提交
5. **创建PR**：描述变更内容和测试结果
6. **代码审查**：等待维护者审查通过
7. **合并上线**：审查通过后合并到`develop`

### 代码审查标准

- [ ] 代码符合Checkstyle规范
- [ ] 有必要的单元测试覆盖
- [ ] 无敏感信息泄露
- [ ] 无安全漏洞
- [ ] 文档已更新（如需要）

---

## 版权声明

### 软件著作权

| 项目名称                  | 登记号   | 权利人                  |
|-----------------------|--------|---------------------|
| 风七六本地生活服务平台软件     | 待登记   | 大连风中行科技服务有限公司     |
| 风七六商家管理系统           | 待登记   | 大连风中行科技服务有限公司     |
| 风七六配送调度系统           | 待登记   | 大连风中行科技服务有限公司     |

### 许可证

本项目为**专有软件**，受中华人民共和国著作权法保护。

**未经授权，任何单位或个人不得**：
- 复制、分发、传播本软件
- 修改、翻译本软件
- 商业使用本软件或其衍生产品

### 免责声明

本软件按"原样"提供，不提供任何明示或暗示的保证。在任何情况下，作者或版权持有人均不对因软件或软件使用而导致的任何索赔、损害或其他责任负责。

---

## 联系方式

| 类型     | 内容                   |
|--------|----------------------|
| 技术支持   | fengqiliu_js@163.com |
| 商务合作   | fengqiliu_dl@163.com |
| 客服热线   | 0411-89704317        |
| 公司地址   | 辽宁省大连市庄河市新华街道永兴街工农1号 |

---

<div align="center">

**© 2024-2026 大连风中行科技服务有限公司 版权所有**

</div>