# 前端独立部署 + 统一后端入口实施计划

> 目标：在已经切换到“前端独立部署 + 同域反代”的基础上，进一步取消前端 Nginx 对 `/api` 的路径级分流，改为反代到一个真正的 **unified backend**，一次性解决长期维护成本。

---

## 1. 背景

当前项目已经完成了两项关键演进：

1. 前端从历史 `static/` 托管模式中抽离，开始走独立构建与独立部署
2. 前端通过同域 Nginx 反代访问后端 API 与分析产物

但当前 Nginx 仍然承担了“后端路由所有权判断”的职责：

- 一部分 `/api/...` 被转发到 `moldinsight`
- 另一部分 `/api/...` 被转发到 `inventory`

这虽然能跑通当前功能，但长期存在明显问题：

- 每新增一个 gemold API，Nginx 都要同步改配置
- Nginx 配置承担了业务边界知识，维护成本高
- `/health` 只能代表某一套后端，而不是统一入口
- 与“unified / gemold-only / inventory-only”三种部署模式的目标不完全一致

因此，本轮改造的目标是：

> 把前端入口反代逻辑从“按路径分流到两套后端”升级为“统一反代到一个 unified backend”。

---

## 2. 目标状态

### 浏览器视角

浏览器始终只访问一个同域入口：

- `/` → 前端静态页面
- `/api/*` → unified backend
- `/health` → unified backend
- `/html/*` → unified backend（由 unified backend 再提供 gemold 产物访问）

### Nginx 视角

Nginx 不再负责理解 gemold / inventory 的业务边界。

它只做两件事：

1. 提供前端静态文件与 SPA fallback
2. 把 `/api`、`/health`、`/html` 统一转发给一个 backend upstream

### 后端视角

后端新增一个统一入口，负责组合：

- auth
- moldinsight routes
- inventory routes
- `/health`
- `/html`

同时继续保留：

- `moldinsight-only`
- `inventory-only`

以满足模块独立部署场景。

---

## 3. 设计决策

### 3.1 为什么要引入 unified backend

因为前端与网关层最适合面对的是一个统一后端，而不是两套需要网关手工分流的内部模块。

收益：

- Nginx 配置显著简化
- 新增 API 不需要修改网关规则
- 文档和运维认知更简单
- 前端保持统一 `/api` 契约
- 更符合模块化蓝图中对 `unified` 模式的定义

### 3.2 为什么不直接把 split 模式删掉

因为：

- `gemold-only` 和 `inventory-only` 仍然有独立部署价值
- 当前仓库已经形成了清晰模块边界
- 统一入口应该成为**前端同域反代的默认方案**，而不是抹掉模块部署模式

所以最终保留三类入口：

- `src/entrypoints/unified.py`
- `src/entrypoints/moldinsight.py`
- `src/entrypoints/inventory.py`

---

## 4. 需要改动的核心文件

## 4.1 新增 unified 入口

新增：
- `src/entrypoints/unified.py`

职责：
- 基于 `shared.app_factory.create_app()` 创建应用
- 统一挂载：
  - `moldinsight.api.router`（prefix=`/api`）
  - `inventory.api.inventory_router`
- 使用：
  - `mount_html=True`
  - `serve_frontend_static=False`
- 不额外挂载 auth（交给 `app_factory`）
- 不手工重复定义 `/health`

## 4.2 简化前端 Nginx

修改：
- `deploy/nginx/frontend.conf`

从当前：
- 双 upstream：`moldinsight` / `inventory`
- 多个 `location /api/...` 手工分流

改成：
- 单 upstream：例如 `gemold_backend_upstream`
- 统一转发：
  - `/api/` → unified backend
  - `/health` → unified backend
  - `/html/` → unified backend

保留：
- `/` 的 SPA fallback
- `/assets/` 的静态缓存策略

## 4.3 调整 Compose

修改：
- `docker-compose.yml`

目标：
- 增加 unified backend 服务
- `frontend` 只依赖 unified backend
- 保留 `moldinsight-celery`
- 按需保留 split backend 入口作为独立 profile

建议最终 profile 语义：

- `full`：frontend + unified + celery
- `frontend`：仅前端入口
- `moldinsight`：仅 gemold-only
- `inventory`：仅 inventory-only
- （可选）`unified`：仅 unified backend

## 4.4 视实现需要调整 Dockerfile

可能新增：
- `deploy/Dockerfile.unified`

或复用已有：
- `deploy/Dockerfile.moldinsight`

取决于是否希望 unified backend 使用单独镜像名。

统一要求：
- unified backend 镜像必须包含：
  - `src/moldinsight/`
  - `src/inventory/`
  - `src/shared/`
  - `src/entrypoints/unified.py`

## 4.5 文档同步

需要更新：
- `README.md`
- `frontend/README.md`
- `docs/deployment/LINUX_SETUP.md`
- `docs/deployment/DEPLOY_PORT.md`
- `docs/deployment/PORT_CONFIG.md`

重点改动：
- 当前推荐部署方式改为“frontend + unified backend + celery”
- 说明 split 模式仍保留，但不再是前端同域反代默认方式
- 端口说明中要区分：
  - 前端入口端口
  - unified backend 内部/对外端口
  - gemold-only / inventory-only 模块端口

---

## 5. 路由与冲突评估

根据当前代码结构，unified 模式可行，主要原因：

- inventory 所有业务路由都挂在 `/api` 下，并且以独立业务前缀区分
- moldinsight 业务路由同样挂在 `/api` 下，但使用不同子路径
- auth 路由使用 `/api/auth`
- top-level `/health` 由 `app_factory` 提供
- moldinsight 内部还有 `/api/health`，与 top-level `/health` 不冲突
- `/html` 只有 moldinsight 需要

关键约束：

1. unified 入口中不要重复 include auth
2. unified 入口中不要手工再定义 top-level `/health`
3. unified 入口必须 `mount_html=True`

---

## 6. 风险与控制

### 风险 1：统一入口与现有 split 入口行为不一致
**控制：**
- 保留现有 `moldinsight.py` 与 `inventory.py`
- 只把 unified 作为前端默认 upstream

### 风险 2：`/health` 语义变化
当前前端只请求一个 `/health`，但 split 时代它实际上只代表某个后端。

**控制：**
- unified 上的 `/health` 明确作为“前端默认 backend 健康入口”
- 文档中明确其语义

### 风险 3：`/html` 丢失或不可达
**控制：**
- unified backend 继续 `mount_html=True`
- 前端 Nginx 保留 `/html/` 反代

### 风险 4：Compose、Nginx、文档不同步
**控制：**
- 先写本计划文档
- 再改 unified 入口、Nginx、Compose
- 最后统一 README 与 deployment docs

---

## 7. 验证方案

## 7.1 路由验证

unified backend 启动后应验证：

- `/api/auth/login`
- `/api/auth/me`
- `/api/upload`
- `/api/status/{task_id}`
- `/api/history`
- `/api/cost-estimate`
- `/api/products`
- `/api/inventory`
- `/api/dashboard`
- `/api/finance/*`
- `/health`
- `/html/...`

## 7.2 前端验证

前端同域访问应验证：

- `/login`
- `/moldinsight`
- `/inventory`
- `/moldinsight/result/:taskId`

关键交互：

- 登录
- 模具上传
- 任务轮询
- 成本估算
- 产品/库存/订单页面加载
- `/html` 分析结果页访问

## 7.3 Compose 验证

完整系统：

```bash
docker compose --profile full up -d
```

应满足：
- `frontend` 正常提供页面
- `frontend` 只反代一个 unified backend
- `moldinsight-celery` 正常运行
- 不再依赖 Nginx 路径级业务分流

---

## 8. 实施顺序

1. 新增 `docs/FRONTEND_UNIFIED_DEPLOYMENT_PLAN.md`
2. 新增 `src/entrypoints/unified.py`
3. 修改 `deploy/nginx/frontend.conf`
4. 修改 `docker-compose.yml`
5. 按需要修改 Dockerfile / 构建脚本
6. 更新 README 与 deployment docs
7. 做一致性验证

---

## 9. 最终预期

完成后，系统对外部署形态将变成：

- 前端：独立 Nginx 静态站点
- 网关：同域同入口
- 后端：一个 unified backend 作为前端默认 upstream
- worker：保留 gemold Celery 异步处理
- split 模式：继续作为模块独立部署能力保留

这能一次性解决当前“前端入口依赖 Nginx 路径级业务分流”的长期维护问题。