# 全端统一架构规划（最终定稿·APP主体版）

本文档为项目**全终端统一架构最终规范（APP主体修正版）**，重新定义各端主次关系：**用户端、骑手端以 Flutter APP 为核心主体、功能基准
**，Web/H5/小程序为轻量化适配端；商家端、平台端以 Web 为核心主体、功能基准。全程保持**同角色所有终端功能100%一致**
，仅交互与设备适配不同，完全符合大厂多端统一体验标准，彻底解决多端体验割裂、配置混乱、迭代不同步问题，统一域名、接口、跨域、部署、迭代规范，作为项目永久执行标准。

---

# 一、全终端技术栈 & 版本主次规划（最终修正版）

## 核心原则（本次关键修正）

1. **用户端、骑手端：APP 是主端、功能基准端**，H5、小程序、未来Web 全部复刻 APP 功能，做轻量化适配

2. **商家端、平台端：Web 是主端、功能基准端**，APP、Windows、收银机、小程序 全部复刻 Web 功能

3. **所有端严格遵守：主端定功能，从端全复刻，业务无差异，仅交互适配**

## 1. 商家端 全版本规划（Web为主，多端同步）

核心定位：商家运营管理终端，**Web端为唯一功能基准**，其余终端全量复刻对齐，仅做设备交互适配，业务功能无删减、无差异

- **Web端（主力/基准）**：merchant.fengzhongxing.com，全量商家管理功能，所有版本功能迭代以Web为准

- **商家APP**：移动端辅助管理，**100%复刻Web端全部功能**，适配手机触控与屏幕尺寸

- **商家收银机版**：线下专用终端，完整继承全量商家功能，仅新增收银快捷操作适配

- **商家Windows版**：桌面客户端，功能、逻辑、权限、数据与Web端完全一致，优化桌面端操作体验

## 2. 平台端 全版本规划（Web为主，多端同步）

核心定位：全局后台管控终端，**Web端为唯一功能基准**，其余终端全量对齐复刻

- **Web端（主力/基准）**：platform.fengzhongxing.com，全量平台管控、配置、审核、监控功能，迭代基准

- **平台APP**：移动端运维管理，完整复刻Web所有功能

- **平台Windows版**：桌面运维客户端，功能完全对齐Web/APP

- **平台小程序**：轻量化入口，核心业务、流程、数据与主端完全一致，仅受平台规则做极简UI适配

## 3. 用户端 全版本规划（APP为主，多端适配）

核心定位：C端用户消费终端，**Flutter APP 为核心主体、功能基准**，H5、小程序为轻量化引流适配端，全部功能对齐APP

- **用户Flutter APP（主力/基准）**：全功能体验，完整业务逻辑、交互流程、功能模块，所有用户端迭代、功能新增、逻辑修改以APP为准

- **用户H5网页（轻量化适配）**：h5.fengzhongxing.com，**100%对齐APP功能**，仅适配移动端网页布局与交互，无功能阉割、无逻辑差异

- **用户微信小程序（轻量化适配）**：完全复用APP业务功能与流程，仅适配小程序平台特性，保证用户体验统一

## 4. 骑手端 全版本规划（APP为主，多端适配）

核心定位：骑手配送服务终端，**Flutter APP 为核心主体、功能基准**，H5为备用轻量化入口，功能完全对齐APP

- **骑手Flutter APP（主力/基准）**：核心接单、配送、结算、消息、任务管理全功能，迭代与功能标准基准

- **骑手H5网页（备用/轻量化）**：rider.fengzhongxing.com，**功能、流程、数据、权限完全复刻APP**，仅做网页端适配，用于临时替代、设备兼容场景

## 5. 公共端

- **官网Web**：www.fengzhongxing.com，品牌展示、招商介绍、用户引导（纯展示端，无业务功能）

- **统一API网关**：api.fengzhongxing.com，全终端唯一接口入口，保障全端数据、功能、逻辑统一

---

# 二、全端域名统一规范（永久不变·适配APP主体架构）

## 规范原则

**业务角色区分终端，主端为APP的用户/骑手，仅轻量化H5保留二级域名；管理类终端以Web为主，保留角色二级域名**
，所有APP/Windows/收银机/小程序无独立域名，统一复用API网关，架构极简、无冗余。

## 域名清单

| 终端类型         | 访问域名                       | 端口   | 终端定位说明                |
|--------------|----------------------------|------|-----------------------|
| 官网           | www.fengzhongxing.com      | 80   | 纯展示Web端               |
| 平台端Web（基准）   | platform.fengzhongxing.com | 80   | 后台管理主端，功能基准           |
| 商家端Web（基准）   | merchant.fengzhongxing.com | 80   | 商家运营主端，功能基准           |
| 用户端H5（轻量化）   | h5.fengzhongxing.com       | 80   | 用户APP配套网页端，仅适配引流、临时访问 |
| 骑手端H5（轻量化）   | rider.fengzhongxing.com    | 80   | 骑手APP配套网页端，备用访问入口     |
| 统一API网关      | api.fengzhongxing.com      | 8080 | 全终端唯一接口入口，统一所有业务数据    |
| Prometheus监控 | monitor.fengzhongxing.com  | 9090 | 指标采集与监控告警             |
| Grafana仪表板   | monitor.fengzhongxing.com  | 3000 | 可视化监控仪表板              |

## 核心规则（APP主体专属）

用户端APP、骑手端APP、所有桌面客户端、收银机端、小程序，**无任何独立访问域名**，全部直连统一API网关（
`http://api.fengzhongxing.com:8080`），业务功能完全跟随各自主端（APP/Web），从底层杜绝多端差异。

---

# 三、核心架构统一原则（全端通用）

## 1. 接口统一规则（多端一致核心保障）

- 全终端统一接口前缀：`/api/**`，所有端调用完全一致的接口地址

- 全终端统一认证方式：`Authorization: Bearer {token}`（JWT），权限体系全端同步

- 全终端统一请求格式：`application/json`，参数、返回值全端统一

- 后端仅维护一套接口、一套业务逻辑、一套数据模型，**主端定义功能，全端自动同步**，无差异化开发

## 2. 跨域终极统一方案

- **所有Web端**：通过Nginx反向代理转发`/api`请求，同源访问、彻底无跨域，生产环境禁止前端直连API域名

- **用户/骑手 Flutter APP、Windows、收银机客户端**：客户端无浏览器跨域限制，直接调用API网关

- **小程序**：微信后台配置API网关为唯一合法域名，直接调用接口

- **后端CORS定位**：仅为小程序、测试环境、第三方调用提供跨域白名单，Web生产环境不依赖CORS

## 3. 前端Web统一配置规范

所有Vite开发的Web端项目统一配置，杜绝资源404、MIME错误、样式错乱，轻量化H5完全对齐APP业务逻辑

```ts
export default defineConfig({
  base: '/',
  build: {
    assetsDir: 'assets',
    outDir: 'dist'
  },
  server: {
    proxy: {
      '/api': {
        target: 'http://127.0.0.1:8880',
        changeOrigin: true,
      },
      '/ws': {
        target: 'http://127.0.0.1:8880',
        changeOrigin: true,
        ws: true,
      }
    }
  }
})
```

### API请求路径规范

**强制要求**：所有Web端接口请求必须使用**相对路径**：`/api/xxx`，禁止写死域名、端口，一套代码适配全环境。

| 文件                                               | 配置                            | 状态   |
|--------------------------------------------------|-------------------------------|------|
| `platform_web/src/services/fetch.ts`             | `VITE_API_BASE_URL` 默认 `/api` | ✅ 合规 |
| `merchant_web/src/services/fetch.ts`             | `baseUrl` 默认 `/api`           | ✅ 合规 |
| `merchant_web/src/services/orderNotification.ts` | WebSocket 默认 `/ws`            | ✅ 合规 |

---

# 四、多端功能一致性规范（APP主体·大厂标准）

## 1. 主次端功能基准规则（最终强制执行）

**✅ 用户端、骑手端：APP 定标准，Web/H5/小程序跟随**

所有下单、支付、配送、订单、会员、权益、消息流程，以 Flutter APP 功能、交互、逻辑为唯一标准，H5 和小程序只做**屏幕适配、平台适配**
，不允许删减、修改、新增业务功能。

**✅ 商家端、平台端：Web 定标准，APP/桌面端跟随**

所有后台配置、审核、管理、统计、店铺操作，以 Web 端为唯一标准，其他终端100%复刻。

## 2. 严格统一差异边界

**只允许交互适配差异，禁止任何业务功能差异**

- **允许差异**：页面布局、按钮尺寸、触控逻辑、桌面快捷键、收银快捷操作、小程序平台限制适配

- **禁止差异**：功能模块、接口逻辑、数据展示、权限范围、业务流程、报错提示、审核规则

## 3. 版本迭代同步规则

- 用户/骑手端：APP 新增功能、优化、修复，必须同步适配 H5、小程序

- 商家/平台端：Web 新增功能、优化、修复，必须同步适配 APP、Windows、收银机、小程序

- 绝不允许出现「主端有、从端无」「从端逻辑不一致」的体验割裂问题

---

# 五、Nginx统一部署规范（全Web端通用）

## 标准配置模板

所有Web站点仅替换域名与资源目录，配置完全统一，保证轻量化H5稳定、无报错、体验一致

```nginx
server {
    listen 80;
    server_name 对应站点域名;

    root /usr/share/nginx/html/对应站点文件夹;
    index index.html;

    # 安全防护头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self' api.fengzhongxing.com ws: wss:" always;

    # 解决SPA刷新404、静态资源404、MIME类型错误
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存策略
    location ~* \.(js|css|json|svg|png|jpg|jpeg|gif|ico|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        add_header Vary "Accept-Encoding";
    }

    # 统一接口代理，彻底消除Web端跨域
    location /api/ {
        proxy_pass http://api-gateway:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket代理
    location /ws/ {
        proxy_pass http://api-gateway:8080/ws/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}
```

## 全局配置优化

```nginx
http {
    # Gzip压缩配置
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript application/javascript application/json;
    gzip_comp_level 6;

    # 连接优化
    keepalive_timeout 65;
    keepalive_requests 100;

    # 日志格式（支持JSON格式便于监控分析）
    log_format json '{"timestamp":"$time_iso8601","remote_addr":"$remote_addr","remote_user":"$remote_user",'
                    '"request_method":"$request_method","request_uri":"$request_uri","status":"$status",'
                    '"body_bytes_sent":"$body_bytes_sent","http_referer":"$http_referer",'
                    '"http_user_agent":"$http_user_agent","request_time":"$request_time"}';
}
```

---

# 六、API网关统一配置规范

统一承接APP、Web、小程序、桌面端所有请求，统一跨域、统一转发、统一权限校验

```nginx
server {
    listen 8080;
    server_name api.fengzhongxing.com;

    # 适配小程序、APP、第三方跨域请求
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods GET,POST,PUT,DELETE,OPTIONS,PATCH;
    add_header Access-Control-Allow-Headers Content-Type,Authorization,token,x-request-start,x-request-id,x-request-time,x-user-id,x-app-id;
    add_header Access-Control-Expose-Headers Authorization,token;

    # 预检请求直接放行，不转发后端
    if ($request_method = OPTIONS) {
        return 204;
    }

    # 统一转发后端服务
    location / {
        proxy_pass http://api-gateway:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket支持
    location /ws/ {
        proxy_pass http://api-gateway:8080/ws/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 86400;
    }

    # 健康检查端点
    location /actuator/ {
        proxy_pass http://api-gateway:8080/actuator/;
        proxy_set_header Host $host;
    }
}
```

---

# 七、监控告警体系规范（Prometheus+Grafana）

## 监控架构

```
┌─────────────────────────────────────────────────────────────┐
│                      监控体系架构                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
│  │   Grafana    │◄───│  Prometheus  │◄───│   各服务     │   │
│  │  (可视化)    │    │  (指标采集)  │    │  (actuator) │   │
│  │  端口:3000   │    │  端口:9090   │    │   端口:8080 │   │
│  └──────────────┘    └──────────────┘    └──────────────┘   │
│         │                   │                               │
│         ▼                   ▼                               │
│  ┌──────────────┐    ┌──────────────┐                       │
│  │  仪表板      │    │   告警规则   │                       │
│  │  (Dashboard) │    │  (Alerts)   │                       │
│  └──────────────┘    └──────────────┘                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## 监控目标配置

```yaml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'spring-boot'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['api-gateway:8080']

  - job_name: 'nacos'
    metrics_path: '/nacos/actuator/prometheus'
    static_configs:
      - targets: ['nacos:8848']

  - job_name: 'redis'
    static_configs:
      - targets: ['redis:6379']

  - job_name: 'mariadb'
    static_configs:
      - targets: ['mariadb:3306']

  - job_name: 'nginx'
    metrics_path: '/metrics'
    static_configs:
      - targets: ['nginx:80']
```

## 监控访问信息

| 服务         | 地址                                    | 用户名   | 密码               |
|------------|---------------------------------------|-------|------------------|
| Prometheus | http://monitor.fengzhongxing.com:9090 | -     | -                |
| Grafana    | http://monitor.fengzhongxing.com:3000 | admin | fzx@2024!grafana |

## 关键监控指标

| 指标类型    | 监控内容            | 告警阈值   |
|---------|-----------------|--------|
| 服务健康    | Spring Boot健康状态 | DOWN告警 |
| CPU使用率  | 各服务CPU占用        | >80%告警 |
| 内存使用率   | 各服务内存占用         | >85%告警 |
| 接口响应时间  | API接口响应时长       | >1s告警  |
| 错误率     | API接口错误占比       | >5%告警  |
| 数据库连接   | 连接池使用情况         | >90%告警 |
| Redis内存 | Redis内存占用       | >80%告警 |

## 告警分级策略

| 级别     | 触发条件                  | 响应时间 |
|--------|-----------------------|------|
| P1（紧急） | Jenkins服务宕机、服务器磁盘>90% | 15分钟 |
| P2（重要） | 构建连续失败≥3次、证书有效期<7天    | 30分钟 |
| P3（一般） | 容器异常退出、资源使用率>80%      | 1小时  |

## 钉钉告警集成

```bash
#!/bin/bash
# /root/fzx-dev/scripts/health-check.sh

DINGTALK_WEBHOOK="https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN"

send_alert() {
    local message=$1
    curl -s -X POST $DINGTALK_WEBHOOK \
      -H 'Content-Type: application/json' \
      -d "{\"msgtype\":\"text\",\"text\":{\"content\":\"$message\"}}"
}

# 磁盘监控
DISK_USED=$(df -h / | awk 'NR==2{print $5}' | sed 's/%//')
if [ $DISK_USED -gt 80 ]; then
    send_alert "【告警】开发服务器磁盘使用率超过80%！当前: ${DISK_USED}%"
fi

# Jenkins状态检查
JENKINS_STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/login)
if [ "$JENKINS_STATUS" -ne 200 ]; then
    send_alert "【告警】Jenkins服务异常 (HTTP状态码: ${JENKINS_STATUS})"
fi
```

---

# 八、CI/CD效率优化规范

## Maven依赖缓存配置

```groovy
pipeline {
    agent any

    options {
        cache(path: '~/.m2/repository',
              key: 'maven-${MD5SUM(pom.xml)}',
              restoreKeys: ['maven-'])
    }

    stages {
        stage('Build') {
            steps {
                sh "mvn clean package -DskipTests -Dmaven.repo.local=~/.m2/repository"
            }
        }
    }
}
```

## Docker镜像分层缓存

```groovy
stage('Build & Push Image') {
    steps {
        script {
            def dockerImage = docker.build("fzx-platform:${IMAGE_TAG}",
                "--cache-from fzx-platform:latest .")
            dockerImage.push()
            dockerImage.push("latest")
        }
    }
}
```

## 流水线并行化

```groovy
stage('Parallel Tests') {
    parallel {
        stage('Unit Test') {
            steps { sh 'mvn test' }
        }
        stage('Code Quality') {
            steps { sh 'mvn checkstyle:check pmd:check' }
        }
    }
}
```

---

# 九、质量左移规范

## Pre-commit钩子配置

```yaml
repos:
  - repo: https://github.com/pre-commit/mirrors-checkstyle
    rev: 'google_checks'
    hooks:
      - id: checkstyle
        args: ['-c', 'checkstyle/checkstyle.xml']

  - repo: https://github.com/Lucas-C/pre-commit-hooks
    rev: v1.1.10
    hooks:
      - id: remove-tabs
      - id: trailing-whitespace
```

## 钩子安装与使用

```bash
# 安装pre-commit
pip install pre-commit

# 安装钩子
pre-commit install

# 手动执行检查
pre-commit run --all-files
```

---

# 十、运维操作标准化

## 流水线化环境切换

```groovy
stage('Switch Environment') {
    parameters {
        string(name: 'TARGET_ENV', defaultValue: 'dev', description: '目标环境')
    }
    steps {
        script {
            echo "🔄 切换到 ${TARGET_ENV} 环境..."
            sh "/root/fzx-dev/scripts/switch-environment.sh ${TARGET_ENV}"

            // 记录操作日志
            writeFile file: 'environment-switch.log',
                text: "${BUILD_NUMBER},${TARGET_ENV},${BUILD_TIMESTAMP}"
        }
    }
}
```

## 巡检闭环流程

```bash
#!/bin/bash
# /root/fzx-dev/scripts/inspection.sh

INSPECTION_LOG="/root/fzx-dev/logs/inspection-$(date +%Y%m%d).log"

echo "=== 巡检开始 ===" >> $INSPECTION_LOG
echo "时间: $(date)" >> $INSPECTION_LOG

# CPU检查
CPU_USAGE=$(top -bn1 | grep 'Cpu(s)' | sed 's/.*, *\([0-9.]*\)%* id.*/\1/' | awk '{print 100 - $1}')
echo "CPU使用率: ${CPU_USAGE}%" >> $INSPECTION_LOG
if (( $(echo "$CPU_USAGE > 80" | bc -l) )); then
    echo "⚠️ CPU使用率超过80%" >> $INSPECTION_LOG
fi

# 内存检查
MEM_USAGE=$(free | grep Mem | awk '{print $3/$2 * 100.0}')
echo "内存使用率: ${MEM_USAGE}%" >> $INSPECTION_LOG

# 容器状态检查
echo "=== 容器状态 ===" >> $INSPECTION_LOG
podman ps >> $INSPECTION_LOG

echo "=== 巡检结束 ===" >> $INSPECTION_LOG
```

---

# 十一、最终架构优势（APP主体架构专属）

- **贴合真实业务场景**：用户、骑手核心流量来自APP，以APP为功能基准，符合产品用户体量与运营重心

- **完全符合大厂规范**：C端以原生APP为标准，多端轻量化跟随；B端以Web后台为标准，客户端跟随，是美团/饿了么/电商类项目标准架构

- **彻底解决体验割裂**：主端定标、从端复刻，全端业务逻辑100%统一，无功能偏差

- **开发迭代高效**：不用多端重复定义功能，统一标准、统一迭代、统一修复

- **运维极简安全**：内网后端不暴露端口，Web代理隔离，APP直连网关，域名体系清晰无冗余

- **扩展性极强**：未来新增任意终端，只需适配交互，无需改动业务架构与功能逻辑

- **监控体系完善**：集成Prometheus+Grafana，实现全链路监控告警，保障系统稳定性

---

# 附录：配置检查清单

## 前端Web配置检查

- ✅ 所有API请求使用相对路径 `/api/xxx`
- ✅ WebSocket请求使用相对路径 `/ws/xxx`
- ✅ 禁止硬编码域名和端口
- ✅ Vite开发代理配置正确

## Nginx配置检查

- ✅ SSL证书配置（生产环境）
- ✅ 安全防护头配置
- ✅ Gzip压缩配置
- ✅ 静态资源缓存策略
- ✅ API反向代理配置
- ✅ WebSocket代理配置

## 监控配置检查

- ✅ Prometheus服务运行正常
- ✅ Grafana服务运行正常
- ✅ 数据源配置正确
- ✅ 告警规则配置完成
- ✅ 仪表板配置完成

---

> 文档版本：v2.2.0
> 生效日期：2026-05-28
> 适用范围：风七六本地生活服务平台所有开发团队
> （注：文档部分内容可能由 AI 生成）