模块拆分 init

2026-08-27 14:53:22 +08:00
parent e6ddea33a2
commit 3ea59551db
15 changed files with 2191 additions and 1399 deletions
@@ -3,11 +3,12 @@ HOST=0.0.0.0
 # ================================
 # 端口配置 - 唯一修改端口的地方
 # ================================
-# 应用端口（容器内端口）
-
+# gemold（moldinsight）API 对外端口
+MOLDINSIGHT_PORT=10003
+# inventory API 对外端口
+INVENTORY_PORT=10004
+# 应用内部监听端口（通常无需修改）
 PORT=10003
-# Docker映射到宿主机的端口（docker-compose使用）
-HOST_PORT=10001
 # ================================


@@ -29,7 +30,7 @@ DB_HOST=szcjw
 DB_PORT=5432
 DB_NAME=moldinsight
 DB_USER=moldinsight
-DB_PASSWORD=Qqs1996*
+DB_PASSWORD=Qqs1996

 # RustFS 对象存储配置 (S3v4 API)
 RUSTFS_ENDPOINT=http://szcjw:8010
@@ -46,12 +47,12 @@ ACCESS_TOKEN_EXPIRE_MINUTES=1440
 # Redis配置
 REDIS_HOST=szcjw
 REDIS_PORT=6379
-REDIS_PASSWORD=Qqs1996*
+REDIS_PASSWORD=Qqs1996
 REDIS_DB=0

 # 管理员配置
 ADMIN_USERNAME=cjw
-ADMIN_PASSWORD=Qqs1996*
+ADMIN_PASSWORD=Qqs1996
 ADMIN_EMAIL=792430652@qq.com
 ADMIN_FULL_NAME=管理员

@@ -60,7 +61,7 @@ ADMIN_FULL_NAME=管理员
 # LLM 增强分析配置（可选）
 # 启用后自动生成模具设计评审报告和分模方向推荐
 # 支持 OpenAI 兼容 API（OpenAI / DeepSeek / vLLM / Ollama 等）
-LLM_ENABLED=true
+LLM_ENABLED=false
 LLM_API_URL=https://api.deepseek.com/v1
 LLM_API_KEY=sk-509f968af3e2466bbef8b5949180782c
 LLM_MODEL=deepseek-v4-flash
@@ -2,13 +2,16 @@
 HOST=0.0.0.0

 # ================================
-# 端口配置 - 唯一修改端口的地方
+# 模块 API 对外端口
 # ================================
-# 应用端口（容器内端口）
+# gemold（moldinsight）API 对外端口
+MOLDINSIGHT_PORT=8000
+# inventory API 对外端口
+INVENTORY_PORT=8001
+# ================================
+
+# 应用内部监听端口（通常无需修改；compose 内已固定为 8000/8001）
 PORT=8000
-# Docker映射到宿主机的端口（docker-compose使用）
-HOST_PORT=10001
-# ================================

 DEBUG=false

@@ -28,27 +31,33 @@ POINTCLOUD_SAMPLE_COUNT=10000
 MESH_QUALITY=high
 PARALLEL_PROCESSING=true

-# 数据库配置
+# 数据库配置（服务器已部署，请填写真实地址）
 DB_HOST=localhost
 DB_PORT=5432
 DB_NAME=moldinsight
 DB_USER=moldinsight_user
 DB_PASSWORD=moldinsight_password

-# RustFS 对象存储配置 (S3v4 API)
+# RustFS / MinIO 兼容对象存储配置（服务器已部署，请填写真实地址）
 RUSTFS_ENDPOINT=http://localhost:9000
 RUSTFS_ACCESS_KEY=your-access-key
 RUSTFS_SECRET_KEY=your-secret-key
 RUSTFS_TIMEOUT=30
 RUSTFS_PRESIGNED_URL_EXPIRES=3600

+# Redis 配置（服务器已部署，请填写真实地址）
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+
 # JWT认证配置
 SECRET_KEY=your-secret-key-change-in-production-min-32-chars
 ALGORITHM=HS256
 ACCESS_TOKEN_EXPIRE_MINUTES=1440

 # CORS 白名单（逗号分隔，不设置则默认为 [*]，生产环境务必设置）
-# CORS_ORIGINS=http://localhost:5173,http://localhost:10001,https://your-domain.com
+# CORS_ORIGINS=http://localhost:5173,http://localhost:8000,http://localhost:8001,https://your-domain.com

 # 管理员账户配置
 ADMIN_USERNAME=admin
@@ -1,29 +1,28 @@
-# Dockerfile for MoldInsight
+# Legacy Dockerfile for geMoldInsight
+#
+# 说明：
+# 该文件保留为历史/兼容用途，仍按旧的单体入口 `src/main.py` 组织。
+# 当前模块化部署的主入口应优先使用：
+# - deploy/Dockerfile.moldinsight
+# - deploy/Dockerfile.inventory
+# - deploy/Dockerfile.celery
+# 以及 deploy/docker-compose.yml
+
 FROM continuumio/miniconda3:latest

-# 设置工作目录
 WORKDIR /app
-
-# 复制项目文件
 COPY . .

-# 更新conda并创建环境
 RUN conda update -n base -c defaults conda -y && \
    conda create -n moldinsight python=3.11 pythonocc-core=7.9.0 -c conda-forge -y

-# 激活环境并安装Python依赖
 RUN . /opt/conda/etc/profile.d/conda.sh && \
    conda activate moldinsight && \
    pip install -r requirements.txt

-# 创建必要的目录
 RUN mkdir -p uploads html_output logs
-
-# 设置启动脚本
 RUN chmod +x start.sh

-# 暴露端口
 EXPOSE 8000

-# 启动命令（使用shell形式确保环境激活）
-CMD ["/bin/bash", "-c", "source /opt/conda/etc/profile.d/conda.sh && conda activate moldinsight && python src/main.py"]
+CMD ["/bin/bash", "-c", "source /opt/conda/etc/profile.d/conda.sh && conda activate moldinsight && python src/main.py"]
@@ -1,4 +1,4 @@
-# Gemold - 模具制造管理系统
+# geMoldInsight

 <div align="center">

@@ -7,319 +7,441 @@
 ![FastAPI](https://img.shields.io/badge/fastapi-0.100.0-green)
 ![Vue.js](https://img.shields.io/badge/vue.js-3-green)
 ![PostgreSQL](https://img.shields.io/badge/postgresql-15-blue)
-![License](https://img.shields.io/badge/license-Mit-green)
+![License](https://img.shields.io/badge/license-MIT-green)

 </div>

-## 项目简介
+geMoldInsight 是一个面向模具制造场景的综合系统，围绕 **STP/STEP 模型分析、模具方案生成、分析结果沉淀、成品创建、BOM/库存/采购/销售闭环** 展开。

-**Gemold** 是一个面向模具制造行业的综合性管理系统，集成了STP文件分析、模具设计建议、用户权限管理和进销存功能。 系统采用现代化的技术栈，提供高效、稳定、易扩展的解决方案。
+当前项目已经从早期单体演进为：

-### 核心功能
+- **gemold（moldinsight）模块**：模具分析、几何处理、批量分析、成本估算、结果导出
+- **inventory 模块**：产品、BOM、库存、采购、销售、财务
+- **frontend 模块**：Vue 3 前端工程
+- **shared 平台层**：配置、数据库、认证、日志、应用工厂

-| 功能模块 | 描述 |
-|---------|------|
-| 🔷 STP文件分析 | 使用PythonOCC解析STP文件，提取几何特征 |
-| 📊 模具设计建议 | 自动生成型腔、型芯、工艺参数等设计方案 |
-| 🎨 3D可视化 | 实时预览产品模型和模具结构 |
-| 👥 用户权限管理 | 完整的角色权限控制系统 |
-| 📦 进销存管理 | 库存、供应商、客户管理 |
-| 💾 数据持久化 | PostgreSQL + RustFS存储 |
+项目当前采用：
+
+> **单仓库 + 单数据库 + 多模块 + 可独立部署**
+
+详细重构方向见：[BACKEND_MODULARIZATION_BLUEPRINT.md](docs/BACKEND_MODULARIZATION_BLUEPRINT.md)
+
+---
+
+## 核心能力
+
+| 模块 | 能力 |
+|---|---|
+| gemold | STP/STEP 上传、几何分析、特征识别、模具方案、批量分析、成本估算、结果导出 |
+| inventory | 成品/物料、BOM、库存、库存流水、采购订单、销售订单、财务、采购建议 |
+| integration | 分析结果一键创建成品，打通“模具分析 → 成品 → BOM → 销售/采购/库存” |
+| platform | 用户、角色、权限、JWT 鉴权、数据库连接、日志、健康检查 |

 ---

 ## 技术栈

 ### 后端
- **FastAPI** - 笷性能异步Web框架
- **PythonOCC** - 专业CAD几何处理
- **SQLAlchemy** - ORM框架
- **PostgreSQL** - 关系型数据库
- **RustFS** - 高性能文件存储
+- **FastAPI**
+- **SQLAlchemy 2.0**
+- **PostgreSQL**
+- **Alembic**
+- **Redis**
+- **Celery**
+- **PythonOCC / trimesh / pyvista**
+- **RustFS / MinIO 兼容对象存储**

 ### 前端
- **Vue.js 3** - 渐进式JavaScript框架
- **Three.js** - 3D可视化库
- **原生CSS** - 白色简约现代风格
+- **Vue 3**
+- **Vite**
+- **TypeScript**
+- **Pinia**
+- **Vue Router**
+- **TDesign Vue Next**

 ### 基础设施
- **Docker** - 容器化部署
- **Systemd** - 服务管理
- **Conda** - 环境管理
+- **Docker / Docker Compose**
+- **结构化日志 / request_id**
+- **OpenAPI → TypeScript 类型生成**

 ---

-## 项目结构
+## 当前项目结构

-```
+> 下述结构反映的是**当前代码现状**，不是历史单体结构。
+
+```text
 geMoldInsight/
-├── src/                        # 源代码目录
-│   ├── main.py                # 主程序入口
-│   ├── api/                   # API路由层
-│   │   ├── routes.py          # 模具分析API路由聚合
-│   │   ├── auth_routes.py     # 认证API
-│   │   ├── v1/                # MoldInsight API (v1)
-│   │   │   ├── upload_router.py    # 文件上传
-│   │   │   ├── task_router.py      # 任务状态查询
-│   │   │   └── history_router.py   # 分析历史
-│   │   └── inventory/         # 进销存API
-│   │       ├── product_routes.py   # 产品管理
-│   │       ├── sales_order_routes.py # 销售订单
-│   │       ├── purchase_order_routes.py # 采购订单
-│   │       ├── finance_routes.py   # 财务管理
-│   │       ├── material_routes.py  # 物料管理
-│   │       └── schemas/       # 请求/响应模型
-│   ├── core/                  # 核心业务逻辑
-│   │   ├── stp_parser.py          # STP文件解析
-│   │   ├── geometry_analyzer.py   # 几何分析
-│   │   ├── mesh_generator.py      # 网格生成
-│   │   ├── mold_generator.py      # 普通塑料模具生成
-│   │   ├── aluminum_foam_mold.py  # 铝泡沫模具生成
-│   │   ├── mold_quality_inspector.py # 模具质量检测
-│   │   └── ai_mold_assistant.py   # AI模具助手
-│   ├── models/                # 数据模型
-│   │   ├── database.py        # SQLAlchemy ORM模型
-│   │   └── schemas.py         # Pydantic模式
-│   ├── services/              # 服务层
-│   │   ├── auth_service.py    # 认证服务
-│   │   ├── processing_service.py  # STP处理流程编排
-│   │   ├── calculation_service.py # 工程参数计算
-│   │   ├── material_service.py    # 材料属性管理
-│   │   ├── task_query_service.py  # 任务状态查询
-│   │   ├── storage_integration_rustfs.py # RustFS存储集成
-│   │   ├── redis_task_manager.py  # Redis任务管理
-│   │   └── verification_service.py # FreeCAD几何验证
-│   ├── database/              # 数据库管理
-│   │   ├── database.py        # 数据库连接池
-│   │   ├── init_db.py         # 数据库初始化
-│   │   └── migrate_db.py      # 数据库迁移
-│   ├── storage/               # 对象存储
-│   │   ├── rustfs_storage.py  # RustFS S3客户端
-│   │   └── object_storage.py  # 通用对象存储
-│   └── utils/                 # 工具类
-│       ├── logger.py          # 日志工具
-│       ├── file_handler.py    # 文件处理
-│       └── html_generator.py  # 3D可视化HTML生成
-├── static/                    # 前端静态资源
-│   ├── vue-app.js             # Vue3 SPA应用
-│   ├── style.css              # 全局样式
-│   └── index.html             # 入口页面
-├── templates/                 # Jinja2模板
-├── config/                    # 配置模块
-│   └── settings.py            # 环境变量配置
-├── scripts/                   # 脚本工具
-│   ├── db/                    # SQL脚本
-│   ├── migrations/            # 数据迁移脚本
-│   ├── tools/                 # 临时检查/清理工具
-│   └── verify_stp.py          # STP验证脚本
-├── docs/                      # 项目文档
-│   └── deployment/            # 部署相关文档
-├── tests/                     # 测试用例
-├── uploads/                   # 上传文件目录 (gitignore)
-├── html_output/               # 3D可视化输出 (gitignore)
-├── requirements.txt           # Python依赖
-├── docker-compose.yml         # Docker编排配置
-├── Dockerfile                 # Docker构建文件
-├── start.sh                   # Linux启动脚本
-├── .env.example               # 环境变量模板
-└── .env                       # 环境变量 (gitignore)
+├── src/
+│   ├── entrypoints/               # 独立部署入口
+│   │   ├── moldinsight.py         # gemold-only 入口
+│   │   └── inventory.py           # inventory-only 入口
+│   │
+│   ├── shared/                    # 共享平台层（当前形态）
+│   │   ├── app_factory.py         # FastAPI 应用工厂
+│   │   ├── config/                # 配置
+│   │   ├── database/              # DB engine / session / init
+│   │   ├── models/                # 共享 ORM 模型（当前最大耦合点）
+│   │   ├── services/              # 认证、Redis 等共享服务
+│   │   └── utils/                 # 日志、文件、HTML 工具
+│   │
+│   ├── moldinsight/               # gemold 模块
+│   │   ├── api/
+│   │   ├── core/
+│   │   ├── services/
+│   │   └── storage/
+│   │
+│   ├── inventory/                 # inventory 模块
+│   │   ├── api/
+│   │   ├── schemas/
+│   │   └── services/
+│   │
+│   ├── celery_app.py              # Celery app
+│   ├── celery_tasks.py            # gemold 异步任务
+│   └── main.py                    # 旧统一入口（兼容/过渡）
+│
+├── frontend/                      # 独立前端工程
+│   ├── src/
+│   │   ├── modules/
+│   │   │   ├── moldinsight/
+│   │   │   ├── inventory/
+│   │   │   ├── login/
+│   │   │   ├── users/
+│   │   │   └── home/
+│   │   ├── router/
+│   │   ├── shared/
+│   │   ├── stores/
+│   │   └── types/
+│   └── package.json
+│
+├── alembic/                       # Alembic migrations
+├── deploy/                        # 镜像构建与部署辅助文件
+│   ├── Dockerfile.base
+│   ├── Dockerfile.moldinsight
+│   ├── Dockerfile.inventory
+│   └── Dockerfile.celery
+│
+├── docs/
+├── tests/
+├── requirements.txt
+└── .env.example
 ```

 ---

+## 模块说明
+
+### 1. gemold（moldinsight）
+
+主要负责：
+- STP/STEP 上传与任务管理
+- 几何分析与特征识别
+- 模具方案、型腔/型芯/工艺建议
+- 批量分析
+- 成本估算
+- 导出与结果查询
+- Celery 异步处理
+
+关键目录：
+- [src/moldinsight/](src/moldinsight/)
+- [src/celery_app.py](src/celery_app.py)
+- [src/celery_tasks.py](src/celery_tasks.py)
+
+### 2. inventory
+
+主要负责：
+- 成品/物料管理
+- BOM
+- 库存与库存流水
+- 采购订单 / 销售订单
+- 财务与对账
+- 采购建议推导
+
+关键目录：
+- [src/inventory/](src/inventory/)
+
+### 3. frontend
+
+主要负责：
+- 模具分析页面
+- 进销存页面
+- 登录/用户管理
+- 统一路由与状态管理
+- 基于 OpenAPI 生成类型的前端 API 调用
+
+关键目录：
+- [frontend/](frontend/)
+
+### 4. shared（当前平台层）
+
+主要负责：
+- 配置
+- 数据库连接与 session
+- 认证与权限
+- 日志与 request_id
+- 应用工厂与通用中间件
+
+关键目录：
+- [src/shared/](src/shared/)
+
+> 说明：后续会逐步将 `shared` 收敛为更清晰的 `platform` 语义，见 [BACKEND_MODULARIZATION_BLUEPRINT.md](docs/BACKEND_MODULARIZATION_BLUEPRINT.md)。
+
+---
+
+## 部署模式
+
+当前项目设计上支持三种模式：
+
+### 1. unified
+一个统一后端同时挂载 gemold + inventory。
+
+适合：
+- 本地开发
+- 集成环境
+- 小团队统一部署
+
+### 2. gemold-only
+只部署模具分析后端。
+
+适合：
+- 单独开放分析能力
+- 分析任务独立扩容
+- 文件处理与异步任务独立部署
+
+入口参考：
+- [src/entrypoints/moldinsight.py](src/entrypoints/moldinsight.py)
+
+### 3. inventory-only
+只部署进销存后端。
+
+适合：
+- 仅使用 ERP / 库存能力
+- 与 gemold 分开部署节奏
+
+入口参考：
+- [src/entrypoints/inventory.py](src/entrypoints/inventory.py)
+
+---
+
 ## 快速开始

-### 1. 环境要求
- Python 3.10+
- PostgreSQL 13+
- Conda (推荐)
+## 1. 环境要求

-### 2. 安装依赖
+- Python 3.12
+- PostgreSQL 15+（服务器已部署或自行提供）
+- Redis（服务器已部署或自行提供）
+- 对象存储（MinIO / RustFS 兼容；gemold 模块需要，服务器已部署或自行提供）
+- Node.js 20+（前端开发需要）
+- 推荐使用 `docker-compose.yml` 仅启动项目自身服务，复用服务器已有 PostgreSQL / Redis / 对象存储
+
+---
+
+## 2. 安装后端依赖

 ```bash
-# 创建Conda环境
-conda create -n py_3.12 python=3.12
-
-# 激活环境
-conda activate py_3.12
-
-# 安装依赖
 pip install -r requirements.txt
 ```

-### 3. 配置环境变量
+如果需要几何分析能力，还需确保 PythonOCC 运行环境可用。项目中已说明其通常通过 conda 提供，而不是直接由 pip 安装。

-创建 `.env` 文件：
+---
+
+## 3. 配置环境变量
+
+复制并编辑：
+
+- [`.env.example`](.env.example)
+- 部署场景也可参考 [deploy/.env.example](deploy/.env.example)
+
+最少需要关注：

 ```env
-# 数据库配置
-DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/gemold
-
-# 服务配置
-SECRET_KEY=your-secret-key-here
+HOST=0.0.0.0
 PORT=8000

-# 管理员配置
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=moldinsight
+DB_USER=moldinsight_user
+DB_PASSWORD=moldinsight_password
+
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+
+SECRET_KEY=change-me
 ADMIN_USERNAME=admin
-ADMIN_PASSWORD=admin123
+ADMIN_PASSWORD=change-me
+
+RUSTFS_ENDPOINT=http://localhost:9000
+RUSTFS_ACCESS_KEY=your-access-key
+RUSTFS_SECRET_KEY=your-secret-key
 ```

-### 4. 初始化数据库
-
-```bash
-python src/database/init_db.py
-```
-
-### 5. 启动服务
-
-**Linux:**
-```bash
-chmod +x start.sh
-./start.sh
-```
-
-**Windows:**
-```cmd
-start.bat
-```
-
-**Docker:**
-```bash
-docker-compose up -d
-```
-
-### 6. 访问服务
-
- 服务地址: http://localhost:8000
- 默认管理员: admin / admin123
+更多配置项见：
+- [settings.py](src/shared/config/settings.py)
+- [.env.example](.env.example)

 ---

-## 核心功能详解
+## 4. 初始化数据库

-### STP文件分析
+项目当前使用 Alembic 管理迁移。应用启动时也会执行初始化逻辑，但首次部署建议显式执行迁移流程。

-系统使用PythonOCC解析STP文件，提取以下几何特征：
-
-| 特征类型 | 描述 |
-|---------|------|
-| 边界框 | 产品整体尺寸 |
-| 体积 | 产品体积计算 |
-| 表面积 | 产品表面积计算 |
-| 壁厚 | 壁厚分布分析 |
-| 加强筋 | 加强筋位置和密度 |
-| 孔洞 | 孔洞和凹槽位置 |
-| 倒扣 | 倒扣区域检测 |
-| 对称性 | 对称性分析 |
-| 重心 | 重心位置计算 |
-
-### 模具设计建议
-
-系统自动生成以下设计建议。
-
-| 建议类型 | 描述 |
-|---------|------|
-| 型腔数量 | 单腔或多腔建议 |
-| 模架尺寸 | 基于产品尺寸推荐 |
-| 顶出系统 | 顶针顶出布局 |
-| 冷却水路 | 冷却需求分析 |
-| 材料选择 | 基于产量推荐材料 |
-
-### 3D可视化
-
- **点云模型** - 从STP提取的真实几何形状
- **模具型腔** - 型腔和型芯可视化
- **分型面** - 分型面位置显示
- **交互控制** - 旋转、缩放、平移
-
- - **视图切换** - 显示/隐藏各组件
+如需查看初始化实现，可参考：
+- [init_db.py](src/shared/database/init_db.py)

 ---

-## API文档
+## 5. 启动方式

-### 认证API
+### 方式 A：使用根目录 Compose（推荐）

-```
-POST /api/auth/login     # 用户登录
-POST /api/auth/logout    # 用户登出
-GET  /api/auth/me         # 获取当前用户信息
+当前唯一 Compose 入口：
+- [docker-compose.yml](docker-compose.yml)
+
+该 compose 文件**只启动项目自身容器**：
+- `moldinsight`
+- `moldinsight-celery`
+- `inventory`
+
+并通过 `.env` 连接服务器上**已经存在**的：
+- PostgreSQL
+- Redis
+- RustFS / MinIO 兼容对象存储
+
+示例：
+
+```bash
+docker compose --profile full up -d
 ```

-### 文件分析API
+可选 profile：
+- `full`
+- `moldinsight`
+- `inventory`

-```
-POST /api/upload           # 上传STP文件
-POST /api/status/{task_id} # 获取分析状态
-GET  /api/history            # 获取分析历史
+> 说明：`docker-compose.yml` 不再重复部署 postgres / redis / minio，而是复用服务器现有基础设施。
+
+### 方式 B：直接启动后端入口
+
+gemold-only：
+
+```bash
+uvicorn src.entrypoints.moldinsight:app --reload --host 0.0.0.0 --port 8000
 ```

-### 进销存API
+inventory-only：

+```bash
+uvicorn src.entrypoints.inventory:app --reload --host 0.0.0.0 --port 8001
 ```
-GET  /api/inventory/dashboard    # 仪表盘数据
-GET  /api/inventory/products     # 产品列表
-POST /api/inventory/products     # 创建产品
+
+### 方式 C：启动前端
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+生产构建：
+
+```bash
+cd frontend
+npm run build
 ```

 ---

-## 部署指南
+## 健康检查与接口

-### Systemd服务 (Linux)
+### 健康检查

-```bash
-# 复制服务文件
-sudo cp gemoldinsight.service /etc/systemd/system/
+两类后端都通过共享 app factory 暴露健康检查：

-# 启用服务
-sudo systemctl enable gemoldinsight
+- `GET /health`
+- `POST /health`

-# 启动服务
-sudo systemctl start gemoldinsight
-```
+参考实现：
+- [app_factory.py](src/shared/app_factory.py)

-### Docker部署
+### 认证接口

-```bash
-# 构建镜像
-docker build -t gemold:latest .
+- `POST /api/auth/login`
+- `POST /api/auth/logout`
+- `GET /api/auth/me`

-# 启动容器
-docker-compose up -d
-```
+### gemold 典型接口
+
+- `POST /api/upload`
+- `POST /api/batch-upload`
+- `GET /api/status/{task_id}`
+- `GET /api/history`
+- `POST /api/cost-estimate`
+
+### inventory 典型接口
+
+- `GET /api/products`
+- `GET /api/inventory`
+- `GET /api/purchase-orders`
+- `GET /api/sales-orders`
+- `GET /api/finance/*`
+
+统一契约输出可参考：
+- [openapi.json](openapi.json)
+- [frontend/src/types/api.ts](frontend/src/types/api.ts)

 ---

-## 开发指南
+## 当前架构重点说明

-### 代码风格
- 遵循PEP 8规范
- 使用类型注解
- 保持函数简洁
+### 1. gemold 与 inventory 已基本模块化

-### 提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- refactor: 代码重构
- test: 测试相关
+当前代码层面，`src/moldinsight/` 与 `src/inventory/` 已基本无直接互相依赖，说明业务边界已经初步成型。
+
+### 2. 当前最大耦合点在 shared + 共享 ORM
+
+需要特别注意：
+
+- [src/shared/models/database.py](src/shared/models/database.py) 同时定义了 identity、gemold、inventory 的 ORM 模型
+- [src/shared/app_factory.py](src/shared/app_factory.py) 仍承担较多平台与模块组合职责
+
+这也是下一阶段重构的重点。
+
+### 3. 单数据库是刻意选择
+
+项目不是把 gemold 与 inventory 拆成两个数据库，而是保留一个共享数据库，用于支撑完整业务闭环：
+
+- 分析结果
+- 创建成品
+- 成品 BOM
+- 销售 / 采购 / 库存
+
+典型桥接点：
+- `STPFile.product_id -> Product.id`
+
+---
+
+## 开发与演进文档
+
+推荐先阅读：
+
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](docs/BACKEND_MODULARIZATION_BLUEPRINT.md) — 当前模块化重构蓝图
+- [EVOLUTION_ROADMAP.md](docs/EVOLUTION_ROADMAP.md) — 历史演进与阶段任务
+- [docs/deployment/](docs/deployment/) — 现有部署文档（部分仍在对齐中）
+
+---
+
+## 开发建议
+
+- 新增业务逻辑优先放入对应业务模块，不要继续堆进 `shared`
+- 新增 API 时优先考虑模块归属，而不是“能放就放”
+- 前端优先通过域 API client 调用接口，而不是散落裸 `/api/...` 路径
+- 数据模型改动要同时考虑表归属与 Alembic 迁移影响

 ---

 ## 许可证

-本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
-
---
-
-## 贡献者
-
-感谢所有为这个项目做出贡献的开发者。
-
---
-
-## 联系方式
-
- 项目地址: [GitHub](https://github.com/your-org/gemold)
- 问题反馈: [Issues](https://github.com/your-org/gemold/issues)
+本项目采用 MIT 许可证，详见 [LICENSE](LICENSE)。
@@ -1,23 +1,41 @@
 # ============================================
-# 环境变量模板 — 独立部署版
+# 环境变量模板 — 复用服务器已有基础设施
 # ============================================
-# 复制为 .env 并修改配置
+# 复制为 .env 并按服务器实际服务地址修改

-# 数据库
-DB_HOST=postgres
+# API 对外端口
+MOLDINSIGHT_PORT=8000
+INVENTORY_PORT=8001
+
+# 数据库（服务器已部署）
+DB_HOST=127.0.0.1
 DB_PORT=5432
 DB_NAME=moldinsight
-DB_USER=moldinsight_user
-DB_PASSWORD=moldinsight_password
+DB_USER=moldinsight
+DB_PASSWORD=change-me

-# Redis
-REDIS_HOST=redis
+# Redis（服务器已部署）
+REDIS_HOST=127.0.0.1
 REDIS_PORT=6379
 REDIS_PASSWORD=
+REDIS_DB=0

-# MinIO (RustFS 兼容存储)
-MINIO_ACCESS_KEY=minioadmin
-MINIO_SECRET_KEY=minioadmin
+# RustFS / MinIO 兼容对象存储（服务器已部署）
+RUSTFS_ENDPOINT=http://127.0.0.1:9000
+RUSTFS_ACCESS_KEY=change-me
+RUSTFS_SECRET_KEY=change-me
+RUSTFS_TIMEOUT=30
+RUSTFS_PRESIGNED_URL_EXPIRES=3600
+
+# 服务配置
+HOST=0.0.0.0
+DEBUG=false
+UPLOAD_DIR=./uploads
+MAX_FILE_SIZE=104857600
+ALLOWED_EXTENSIONS=.stp,.step,.stp.gz
+POINTCLOUD_SAMPLE_COUNT=10000
+MESH_QUALITY=high
+PARALLEL_PROCESSING=true

 # 认证
 SECRET_KEY=your-secret-key-change-in-production-min-32-chars
@@ -30,35 +48,14 @@ ADMIN_PASSWORD=change-this-to-a-secure-password
 ADMIN_EMAIL=admin@gemold.com
 ADMIN_FULL_NAME=系统管理员

-# 端口
-MOLDINSIGHT_PORT=8000
-INVENTORY_PORT=8001
+# FreeCAD 验证（可选）
+ENABLE_FREECAD_VERIFICATION=false
+FREECAD_VERIFICATION_TIMEOUT=120

-# 文件上传
-UPLOAD_DIR=./uploads
-MAX_FILE_SIZE=104857600
-ALLOWED_EXTENSIONS=.stp,.step,.stp.gz
-
-# 几何处理
-POINTCLOUD_SAMPLE_COUNT=10000
-MESH_QUALITY=high
-PARALLEL_PROCESSING=true
-
-# RustFS 对象存储
-RUSTFS_ENDPOINT=http://minio:9000
-RUSTFS_ACCESS_KEY=minioadmin
-RUSTFS_SECRET_KEY=minioadmin
-RUSTFS_TIMEOUT=30
-RUSTFS_PRESIGNED_URL_EXPIRES=3600
-
-# LLM (可选)
+# LLM（可选）
 LLM_ENABLED=false
 LLM_API_URL=https://api.openai.com/v1
 LLM_API_KEY=sk-your-api-key
 LLM_MODEL=gpt-4o-mini
 LLM_TIMEOUT=60
 LLM_MAX_TOKENS=2000
-
-# FreeCAD 验证 (可选)
-ENABLE_FREECAD_VERIFICATION=false
-FREECAD_VERIFICATION_TIMEOUT=120
@@ -1,165 +0,0 @@
-services:
-  postgres:
-    image: postgres:15
-    container_name: gemold_postgres
-    environment:
-      POSTGRES_DB: ${DB_NAME:-moldinsight}
-      POSTGRES_USER: ${DB_USER:-moldinsight_user}
-      POSTGRES_PASSWORD: ${DB_PASSWORD:-moldinsight_password}
-    ports:
-      - "5432:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-moldinsight_user} -d ${DB_NAME:-moldinsight}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    restart: unless-stopped
-    networks:
-      - gemold_network
-
-  redis:
-    image: redis:7-alpine
-    container_name: gemold_redis
-    ports:
-      - "6379:6379"
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    restart: unless-stopped
-    networks:
-      - gemold_network
-
-  minio:
-    image: minio/minio:latest
-    container_name: gemold_minio
-    command: server /data --console-address ":9001"
-    environment:
-      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY:-minioadmin}
-      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY:-minioadmin}
-    ports:
-      - "9000:9000"
-      - "9001:9001"
-    volumes:
-      - minio_data:/data
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
-      interval: 30s
-      timeout: 20s
-      retries: 3
-    restart: unless-stopped
-    networks:
-      - gemold_network
-
-  moldinsight:
-    build:
-      context: ..
-      dockerfile: deploy/Dockerfile.moldinsight
-    image: gemold-moldinsight:latest
-    container_name: gemold_moldinsight
-    ports:
-      - "${MOLDINSIGHT_PORT:-8000}:8000"
-    environment:
-      HOST: 0.0.0.0
-      PORT: "8000"
-      DB_HOST: postgres
-      DB_PORT: "5432"
-      DB_NAME: ${DB_NAME:-moldinsight}
-      DB_USER: ${DB_USER:-moldinsight_user}
-      DB_PASSWORD: ${DB_PASSWORD:-moldinsight_password}
-      REDIS_HOST: redis
-      REDIS_PORT: "6379"
-      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
-      RUSTFS_ENDPOINT: http://minio:9000
-      RUSTFS_ACCESS_KEY: ${MINIO_ACCESS_KEY:-minioadmin}
-      RUSTFS_SECRET_KEY: ${MINIO_SECRET_KEY:-minioadmin}
-      SECRET_KEY: ${SECRET_KEY:-change-me-in-production}
-      ADMIN_USERNAME: ${ADMIN_USERNAME:-admin}
-      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-admin123}
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-      minio:
-        condition: service_healthy
-    restart: unless-stopped
-    profiles:
-      - full
-      - moldinsight
-    networks:
-      - gemold_network
-
-  moldinsight-celery:
-    build:
-      context: ..
-      dockerfile: deploy/Dockerfile.celery
-    container_name: gemold_celery
-    environment:
-      DB_HOST: postgres
-      DB_PORT: "5432"
-      DB_NAME: ${DB_NAME:-moldinsight}
-      DB_USER: ${DB_USER:-moldinsight_user}
-      DB_PASSWORD: ${DB_PASSWORD:-moldinsight_password}
-      REDIS_HOST: redis
-      REDIS_PORT: "6379"
-      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
-      RUSTFS_ENDPOINT: http://minio:9000
-      RUSTFS_ACCESS_KEY: ${MINIO_ACCESS_KEY:-minioadmin}
-      RUSTFS_SECRET_KEY: ${MINIO_SECRET_KEY:-minioadmin}
-      RUSTFS_TIMEOUT: ${RUSTFS_TIMEOUT:-30}
-    depends_on:
-      - moldinsight
-    restart: unless-stopped
-    profiles:
-      - full
-      - moldinsight
-    networks:
-      - gemold_network
-
-  inventory:
-    build:
-      context: ..
-      dockerfile: deploy/Dockerfile.inventory
-    image: gemold-inventory:latest
-    container_name: gemold_inventory
-    ports:
-      - "${INVENTORY_PORT:-8001}:8001"
-    environment:
-      HOST: 0.0.0.0
-      PORT: "8001"
-      DB_HOST: postgres
-      DB_PORT: "5432"
-      DB_NAME: ${DB_NAME:-moldinsight}
-      DB_USER: ${DB_USER:-moldinsight_user}
-      DB_PASSWORD: ${DB_PASSWORD:-moldinsight_password}
-      REDIS_HOST: redis
-      REDIS_PORT: "6379"
-      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
-      SECRET_KEY: ${SECRET_KEY:-change-me-in-production}
-      ADMIN_USERNAME: ${ADMIN_USERNAME:-admin}
-      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-admin123}
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-    restart: unless-stopped
-    profiles:
-      - full
-      - inventory
-    networks:
-      - gemold_network
-
-volumes:
-  postgres_data:
-    driver: local
-  minio_data:
-    driver: local
-
-networks:
-  gemold_network:
-    driver: bridge
@@ -1,119 +1,137 @@
-# docker-compose.yml - 完整版（包含PostgreSQL和MinIO）
 services:
-  postgres:
-    image: postgres:15
-    container_name: moldinsight_postgres
-    environment:
-      POSTGRES_DB: ${DB_NAME:-moldinsight}
-      POSTGRES_USER: ${DB_USER:-moldinsight_user}
-      POSTGRES_PASSWORD: ${DB_PASSWORD:-moldinsight_password}
-    ports:
-      - "5432:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-moldinsight_user} -d ${DB_NAME:-moldinsight}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    restart: unless-stopped
-    networks:
-      - moldinsight_network
-
-  minio:
-    image: minio/minio:latest
-    container_name: moldinsight_minio
-    command: server /data --console-address ":9001"
-    environment:
-      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY:-minioadmin}
-      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY:-minioadmin}
-    ports:
-      - "9000:9000"   # API端口
-      - "9001:9001"   # 控制台端口
-    volumes:
-      - minio_data:/data
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
-      interval: 30s
-      timeout: 20s
-      retries: 3
-    restart: unless-stopped
-    networks:
-      - moldinsight_network
-
  moldinsight:
-    build: .
-    container_name: moldinsight_app
+    build:
+      context: .
+      dockerfile: deploy/Dockerfile.moldinsight
+    image: gemold-moldinsight:latest
+    container_name: gemold_moldinsight
    ports:
-      - "${HOST_PORT:-10001}:${CONTAINER_PORT:-8000}"  # 宿主机端口:容器端口
-    volumes:
-      - ./uploads:/app/uploads
-      - ./html_output:/app/html_output
-      - ./logs:/app/logs
-      - ./.env:/app/.env:ro
+      - "${MOLDINSIGHT_PORT:-8000}:8000"
    environment:
-      # 应用端口配置（从settings.py读取）
-      - HOST=${HOST:-0.0.0.0}
-      - PORT=${CONTAINER_PORT:-8000}
-      # 数据库配置
-      - DB_HOST=postgres
-      - DB_PORT=5432
-      - DB_NAME=${DB_NAME:-moldinsight}
-      - DB_USER=${DB_USER:-moldinsight_user}
-      - DB_PASSWORD=${DB_PASSWORD:-moldinsight_password}
-      # RustFS配置
-      - RUSTFS_ENDPOINT=http://minio:9000
-      - RUSTFS_ACCESS_KEY=${MINIO_ACCESS_KEY:-minioadmin}
-      - RUSTFS_SECRET_KEY=${MINIO_SECRET_KEY:-minioadmin}
-    depends_on:
-      postgres:
-        condition: service_healthy
-      minio:
-        condition: service_healthy
+      HOST: 0.0.0.0
+      PORT: "8000"
+      DB_HOST: ${DB_HOST}
+      DB_PORT: ${DB_PORT:-5432}
+      DB_NAME: ${DB_NAME:-moldinsight}
+      DB_USER: ${DB_USER}
+      DB_PASSWORD: ${DB_PASSWORD}
+      REDIS_HOST: ${REDIS_HOST}
+      REDIS_PORT: ${REDIS_PORT:-6379}
+      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
+      RUSTFS_ENDPOINT: ${RUSTFS_ENDPOINT}
+      RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY}
+      RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY}
+      RUSTFS_TIMEOUT: ${RUSTFS_TIMEOUT:-30}
+      SECRET_KEY: ${SECRET_KEY:-change-me-in-production}
+      ADMIN_USERNAME: ${ADMIN_USERNAME:-admin}
+      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-admin123}
+      ADMIN_EMAIL: ${ADMIN_EMAIL:-admin@gemold.com}
+      ADMIN_FULL_NAME: ${ADMIN_FULL_NAME:-系统管理员}
+      ALGORITHM: ${ALGORITHM:-HS256}
+      ACCESS_TOKEN_EXPIRE_MINUTES: ${ACCESS_TOKEN_EXPIRE_MINUTES:-1440}
+      DEBUG: ${DEBUG:-false}
+      UPLOAD_DIR: ${UPLOAD_DIR:-./uploads}
+      MAX_FILE_SIZE: ${MAX_FILE_SIZE:-104857600}
+      ALLOWED_EXTENSIONS: ${ALLOWED_EXTENSIONS:-.stp,.step,.stp.gz}
+      POINTCLOUD_SAMPLE_COUNT: ${POINTCLOUD_SAMPLE_COUNT:-10000}
+      MESH_QUALITY: ${MESH_QUALITY:-high}
+      PARALLEL_PROCESSING: ${PARALLEL_PROCESSING:-true}
+      RUSTFS_PRESIGNED_URL_EXPIRES: ${RUSTFS_PRESIGNED_URL_EXPIRES:-3600}
+      ENABLE_FREECAD_VERIFICATION: ${ENABLE_FREECAD_VERIFICATION:-false}
+      FREECAD_VERIFICATION_TIMEOUT: ${FREECAD_VERIFICATION_TIMEOUT:-120}
+      LLM_ENABLED: ${LLM_ENABLED:-false}
+      LLM_API_URL: ${LLM_API_URL:-https://api.openai.com/v1}
+      LLM_API_KEY: ${LLM_API_KEY:-}
+      LLM_MODEL: ${LLM_MODEL:-gpt-4o-mini}
+      LLM_TIMEOUT: ${LLM_TIMEOUT:-60}
+      LLM_MAX_TOKENS: ${LLM_MAX_TOKENS:-2000}
    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 60s
+    profiles:
+      - full
+      - moldinsight
    networks:
-      - moldinsight_network
+      - gemold_network

-  celery-worker:
-    build: .
-    container_name: moldinsight_celery
-    command: >
-      /bin/bash -c "source /opt/conda/etc/profile.d/conda.sh && conda activate moldinsight && cd /app/src && celery -A celery_app worker --concurrency=2 --loglevel=info"
-    volumes:
-      - ./uploads:/app/uploads
-      - ./html_output:/app/html_output
-      - ./logs:/app/logs
-      - ./.env:/app/.env:ro
+  moldinsight-celery:
+    build:
+      context: .
+      dockerfile: deploy/Dockerfile.celery
+    container_name: gemold_celery
    environment:
-      - DB_HOST=postgres
-      - DB_PORT=5432
-      - DB_NAME=${DB_NAME:-moldinsight}
-      - DB_USER=${DB_USER:-moldinsight_user}
-      - DB_PASSWORD=${DB_PASSWORD:-moldinsight_password}
-      - RUSTFS_ENDPOINT=http://minio:9000
-      - RUSTFS_ACCESS_KEY=${MINIO_ACCESS_KEY:-minioadmin}
-      - RUSTFS_SECRET_KEY=${MINIO_SECRET_KEY:-minioadmin}
+      DB_HOST: ${DB_HOST}
+      DB_PORT: ${DB_PORT:-5432}
+      DB_NAME: ${DB_NAME:-moldinsight}
+      DB_USER: ${DB_USER}
+      DB_PASSWORD: ${DB_PASSWORD}
+      REDIS_HOST: ${REDIS_HOST}
+      REDIS_PORT: ${REDIS_PORT:-6379}
+      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
+      RUSTFS_ENDPOINT: ${RUSTFS_ENDPOINT}
+      RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY}
+      RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY}
+      RUSTFS_TIMEOUT: ${RUSTFS_TIMEOUT:-30}
+      SECRET_KEY: ${SECRET_KEY:-change-me-in-production}
+      ALGORITHM: ${ALGORITHM:-HS256}
+      ACCESS_TOKEN_EXPIRE_MINUTES: ${ACCESS_TOKEN_EXPIRE_MINUTES:-1440}
+      DEBUG: ${DEBUG:-false}
+      UPLOAD_DIR: ${UPLOAD_DIR:-./uploads}
+      MAX_FILE_SIZE: ${MAX_FILE_SIZE:-104857600}
+      ALLOWED_EXTENSIONS: ${ALLOWED_EXTENSIONS:-.stp,.step,.stp.gz}
+      POINTCLOUD_SAMPLE_COUNT: ${POINTCLOUD_SAMPLE_COUNT:-10000}
+      MESH_QUALITY: ${MESH_QUALITY:-high}
+      PARALLEL_PROCESSING: ${PARALLEL_PROCESSING:-true}
+      RUSTFS_PRESIGNED_URL_EXPIRES: ${RUSTFS_PRESIGNED_URL_EXPIRES:-3600}
+      ENABLE_FREECAD_VERIFICATION: ${ENABLE_FREECAD_VERIFICATION:-false}
+      FREECAD_VERIFICATION_TIMEOUT: ${FREECAD_VERIFICATION_TIMEOUT:-120}
+      LLM_ENABLED: ${LLM_ENABLED:-false}
+      LLM_API_URL: ${LLM_API_URL:-https://api.openai.com/v1}
+      LLM_API_KEY: ${LLM_API_KEY:-}
+      LLM_MODEL: ${LLM_MODEL:-gpt-4o-mini}
+      LLM_TIMEOUT: ${LLM_TIMEOUT:-60}
+      LLM_MAX_TOKENS: ${LLM_MAX_TOKENS:-2000}
    depends_on:
-      postgres:
-        condition: service_healthy
-      minio:
-        condition: service_healthy
+      - moldinsight
    restart: unless-stopped
+    profiles:
+      - full
+      - moldinsight
    networks:
-      - moldinsight_network
+      - gemold_network

-volumes:
-  postgres_data:
-    driver: local
-  minio_data:
-    driver: local
+  inventory:
+    build:
+      context: .
+      dockerfile: deploy/Dockerfile.inventory
+    image: gemold-inventory:latest
+    container_name: gemold_inventory
+    ports:
+      - "${INVENTORY_PORT:-8001}:8001"
+    environment:
+      HOST: 0.0.0.0
+      PORT: "8001"
+      DB_HOST: ${DB_HOST}
+      DB_PORT: ${DB_PORT:-5432}
+      DB_NAME: ${DB_NAME:-moldinsight}
+      DB_USER: ${DB_USER}
+      DB_PASSWORD: ${DB_PASSWORD}
+      REDIS_HOST: ${REDIS_HOST}
+      REDIS_PORT: ${REDIS_PORT:-6379}
+      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
+      SECRET_KEY: ${SECRET_KEY:-change-me-in-production}
+      ADMIN_USERNAME: ${ADMIN_USERNAME:-admin}
+      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-admin123}
+      ADMIN_EMAIL: ${ADMIN_EMAIL:-admin@gemold.com}
+      ADMIN_FULL_NAME: ${ADMIN_FULL_NAME:-系统管理员}
+      ALGORITHM: ${ALGORITHM:-HS256}
+      ACCESS_TOKEN_EXPIRE_MINUTES: ${ACCESS_TOKEN_EXPIRE_MINUTES:-1440}
+      DEBUG: ${DEBUG:-false}
+    restart: unless-stopped
+    profiles:
+      - full
+      - inventory
+    networks:
+      - gemold_network

 networks:
-  moldinsight_network:
+  gemold_network:
    driver: bridge
@@ -0,0 +1,908 @@
+# geMoldInsight 后端模块化重构蓝图
+
+> 目标：在**同一 Git 仓库**、**同一数据库**前提下，将当前代码结构整理为**可独立部署的多模块架构**，明确 gemold、inventory、frontend 的边界与演进路径。本文档是后续实施的权威蓝图，不是历史记录。
+
+---
+
+## 1. 背景与目标
+
+当前项目已经从早期单体演进为“双应用 + 共享层”的形态：
+
+- 业务模块：`src/moldinsight/`、`src/inventory/`
+- 共享层：`src/shared/`
+- 部署入口：`src/entrypoints/moldinsight.py`、`src/entrypoints/inventory.py`
+- 前端工程：`frontend/`
+
+从代码现状看，`moldinsight` 与 `inventory` 已基本无直接互引，说明模块边界已经初步形成；但同时，数据库模型、认证、配置、应用工厂等仍集中在 `shared/`，导致当前更接近“**模块化中的单体**”，而不是“**可独立部署的模块化单体**”。
+
+本次蓝图的目标不是拆库、拆仓、微服务化，而是：
+
+1. 保持**单仓库（monorepo）**
+2. 保持**单数据库**
+3. 将后端正式整理为多个模块：
+   - **gemold**（模具分析 / moldinsight）
+   - **inventory**（进销存）
+   - **identity / platform**（共享基础设施与认证）
+4. 保持前端为**独立模块工程**，并增强其对多部署模式的兼容
+5. 支持三种部署模式：
+   - **unified**：gemold + inventory 同时部署
+   - **gemold-only**：仅部署 gemold
+   - **inventory-only**：仅部署 inventory
+
+---
+
+## 2. 范围与非目标
+
+### 2.1 本次蓝图覆盖范围
+
+- 后端模块边界
+- 共享层职责重新定义
+- 单数据库下的模型归属与表所有权
+- 独立部署模式设计
+- 前端 API 边界强化策略
+- 分阶段迁移路径
+- 风险与验证方法
+
+### 2.2 非目标
+
+本蓝图**不包含**以下方向：
+
+- 多 Git 仓库拆分
+- 多数据库拆分
+- 分布式微服务重构
+- 全量 DDD 重写
+- 全量前端重构
+- 事件驱动或消息总线主导的跨服务通信改造
+
+换句话说，目标架构是：
+
+> **单仓库 + 单数据库 + 多模块 + 可独立部署的 modular monolith**
+
+而不是微服务系统。
+
+---
+
+## 3. 当前架构快照
+
+### 3.1 后端现状
+
+当前核心目录结构如下：
+
+```text
+src/
+  entrypoints/
+    moldinsight.py
+    inventory.py
+  shared/
+    app_factory.py
+    config/
+    database/
+    models/
+    services/
+    utils/
+  moldinsight/
+    api/
+    core/
+    services/
+    storage/
+  inventory/
+    api/
+    schemas/
+    services/
+```
+
+其中：
+
+- [app_factory.py](../src/shared/app_factory.py) 已统一 CORS、日志中间件、startup/shutdown、认证路由、健康检查与 SPA fallback。
+- [moldinsight.py](../src/entrypoints/moldinsight.py) 与 [inventory.py](../src/entrypoints/inventory.py) 已提供独立入口。
+- [database.py](../src/shared/models/database.py) 同时包含 identity、moldinsight、inventory 三类模型，是当前最强耦合点。
+
+### 3.2 前端现状
+
+前端已是独立 Vite/Vue 工程：
+
+```text
+frontend/
+  src/
+    modules/
+      moldinsight/
+      inventory/
+      login/
+      users/
+      home/
+    router/
+    shared/
+    stores/
+    types/
+```
+
+特点：
+
+- 已按页面/业务模块组织
+- 已有共享 API 层雏形：[api-client.ts](../frontend/src/shared/api-client.ts)
+- 已接入 OpenAPI 生成类型：[api.ts](../frontend/src/types/api.ts)
+- 当前仍有大量相对路径 `/api/...` 与 raw `fetch()` 的同源假设
+
+### 3.3 现状判断
+
+当前架构可概括为：
+
+> **HTTP 入口已分离，业务代码已分组，但平台层与数据层仍共享。**
+
+因此，它适合继续朝“可独立部署的模块化单体”演进，而不适合直接跳到微服务。
+
+---
+
+## 4. 目标架构：可独立部署的模块化单体
+
+### 4.1 架构原则
+
+目标态采用以下原则：
+
+1. **组合优先于复制**：不同部署模式通过组合不同模块得到，而不是复制多套代码。
+2. **平台与业务分离**：`platform` 只承载技术性共享能力，不继续承载业务逻辑。
+3. **模块所有权清晰**：每张表、每条 API、每个服务类都应有明确归属。
+4. **单数据库但显式边界**：允许共享 DB，但不允许“共享数据库 = 没有边界”。
+5. **统一前端，兼容多后端部署形态**：前端继续是一套工程，通过 API client 适配 unified / split deployment。
+
+### 4.2 架构定位
+
+目标架构不是“多个服务各自拥有数据库”的微服务，而是：
+
+- 同一个仓库
+- 同一个数据库
+- 多个模块
+- 多个部署入口
+- 同一套迁移历史
+- 同一套共享基础设施能力
+
+这是一种适合当前项目阶段的**治理性重构**，而不是组织级拆分。
+
+---
+
+## 5. 目标目录结构
+
+以下结构是**目标态**，不要求一次性到位：
+
+```text
+src/
+  platform/
+    app/
+      app_factory.py
+      lifecycle.py
+      middleware/
+    config/
+    auth/
+    database/
+      engine.py
+      session.py
+      migrations/
+    observability/
+    contracts/
+      api/
+      events/
+    shared_kernel/
+      types/
+      exceptions/
+      utils/
+
+  modules/
+    moldinsight/
+      application/
+        services/
+        use_cases/
+      domain/
+        models/
+        policies/
+        repositories/
+      infrastructure/
+        persistence/
+        storage/
+        adapters/
+      interfaces/
+        api/
+        schemas/
+      module.py
+
+    inventory/
+      application/
+        services/
+        use_cases/
+      domain/
+        models/
+        policies/
+        repositories/
+      infrastructure/
+        persistence/
+        adapters/
+      interfaces/
+        api/
+        schemas/
+      module.py
+
+    identity/
+      application/
+      domain/
+      infrastructure/
+      interfaces/
+      module.py
+
+  compositions/
+    unified_app.py
+    gemold_app.py
+    inventory_app.py
+
+  legacy/
+    main.py
+```
+
+### 5.1 当前目录到目标目录的映射
+
+| 当前路径 | 目标路径 | 说明 |
+|---|---|---|
+| `src/shared/*` | `src/platform/*` | 共享基础设施重新命名与归位 |
+| `src/moldinsight/*` | `src/modules/moldinsight/*` | gemold 业务模块 |
+| `src/inventory/*` | `src/modules/inventory/*` | inventory 业务模块 |
+| `src/entrypoints/*` | `src/compositions/*` | 部署组合层 |
+| `src/main.py` | `src/legacy/main.py` | 过渡期兼容入口 |
+
+### 5.2 为什么要引入 `compositions/`
+
+当前 [entrypoints/](../src/entrypoints/) 已经承担“部署入口”角色，但语义更偏“启动文件”。
+
+引入 `compositions/` 的意义是明确：
+
+- 它不是业务模块
+- 它不是平台能力
+- 它是“**按部署模式装配模块**”的组合层
+
+例如：
+
+- `gemold_app.py`：平台 + identity + moldinsight
+- `inventory_app.py`：平台 + identity + inventory
+- `unified_app.py`：平台 + identity + moldinsight + inventory
+
+---
+
+## 6. 模块职责边界
+
+### 6.1 platform
+
+`platform` 是技术共享层，只承载**跨模块公共基础设施能力**。
+
+#### 归属范围
+- app factory / middleware / 生命周期
+- config
+- 数据库 engine / session / Alembic 接线
+- auth / JWT / 权限
+- 日志 / request_id / observability
+- 通用 contracts / utilities
+
+#### 可复用现有实现
+- [app_factory.py](../src/shared/app_factory.py)
+- [settings.py](../src/shared/config/settings.py)
+- [database.py](../src/shared/database/database.py)
+- [auth_service.py](../src/shared/services/auth_service.py)
+- [auth_routes.py](../src/shared/services/auth_routes.py)
+
+#### 规则
+`platform` 不得继续吸收业务规则代码，否则新的 `platform` 会变成旧的 `shared`。
+
+---
+
+### 6.2 moldinsight（gemold）
+
+`moldinsight` 模块负责模具分析、几何处理和分析结果生命周期。
+
+#### 归属范围
+- 上传、任务、历史、批量分析、成本估算、CAM、分析结果
+- 几何分析、特征检测、模具方案、报告
+- RustFS / 对象存储接入
+- Celery 异步处理链路
+
+#### 可复用现有实现
+- [moldinsight/api/__init__.py](../src/moldinsight/api/__init__.py)
+- [processing_service.py](../src/moldinsight/services/processing_service.py)
+- [task_query_service.py](../src/moldinsight/services/task_query_service.py)
+- [moldinsight/core/](../src/moldinsight/core/)
+- [celery_app.py](../src/celery_app.py)
+- [celery_tasks.py](../src/celery_tasks.py)
+
+---
+
+### 6.3 inventory
+
+`inventory` 模块负责 ERP / 进销存类业务流程。
+
+#### 归属范围
+- 产品、物料、供应商、客户、仓库
+- 库存、库存流水
+- 销售订单、采购订单、财务、采购建议
+- BOM / 采购需求推导
+
+#### 可复用现有实现
+- [inventory/api/__init__.py](../src/inventory/api/__init__.py)
+- [inventory_service.py](../src/inventory/services/inventory_service.py)
+- [sales_order_service.py](../src/inventory/services/sales_order_service.py)
+- [purchase_order_service.py](../src/inventory/services/purchase_order_service.py)
+- [finance_service.py](../src/inventory/services/finance_service.py)
+
+---
+
+### 6.4 identity
+
+`identity` 负责用户、角色、权限与认证授权。
+
+#### 归属范围
+- User / Role / Permission
+- 登录、鉴权、管理员接口
+- 统一授权能力
+
+在物理目录上，identity 可以先靠近 platform；但逻辑上应从一开始就被视为独立边界，而不是“moldinsight 的一部分”或“inventory 的一部分”。
+
+---
+
+## 7. 允许的依赖方向
+
+这是本蓝图最重要的治理规则之一。
+
+### 7.1 依赖规则
+
+```text
+compositions -> platform
+compositions -> modules/*
+
+platform -> 不依赖业务模块
+
+modules/*/interfaces -> modules/*/application
+modules/*/application -> modules/*/domain
+modules/*/infrastructure -> modules/*/domain
+
+modules/*/interfaces -> platform
+modules/*/infrastructure -> platform
+```
+
+### 7.2 跨模块约束
+
+- `inventory` 不能直接 import `moldinsight.api` / `moldinsight.services`
+- `moldinsight` 不能直接 import `inventory.api` / `inventory.services`
+- `platform` 不得依赖任一业务模块
+- 跨模块协作只能通过：
+  - 显式 contract / query service
+  - composition wiring
+  - 受控的共享数据库引用
+
+### 7.3 当前代码与规则的差距
+
+从代码检查看，当前 `moldinsight` 与 `inventory` 基本没有直接互引，这说明上述规则在业务代码层**已经接近成立**。
+
+当前主要问题集中在：
+
+- [database.py](../src/shared/models/database.py) 集中承载所有 ORM 模型
+- [app_factory.py](../src/shared/app_factory.py) 同时知道通用平台逻辑与 moldinsight 专属 startup 行为
+
+因此，后续实施的重点不是“切断业务模块互引”，而是“**把共享层与数据层的边界拉直**”。
+
+---
+
+## 8. 单数据库下的模型与表归属策略
+
+### 8.1 核心原则
+
+数据库继续保持为**一个 PostgreSQL 数据库**，但代码中的模型归属必须显式化。
+
+也就是说：
+
+> **数据库不拆，模型归属要拆。**
+
+### 8.2 当前最强耦合点
+
+当前 [database.py](../src/shared/models/database.py) 同时包含：
+
+- identity / 平台相关模型
+- moldinsight 业务模型
+- inventory 业务模型
+
+这会带来两个问题：
+
+1. 代码层看不出模型所有权
+2. 开发者更容易跨模块直接访问整套 ORM 图谱
+
+因此，后续实施应优先将这个文件按归属拆分。
+
+### 8.3 推荐表归属矩阵
+
+#### platform / identity-owned
+- users
+- roles
+- permissions
+- user_roles
+- role_permissions
+- （可选）system_logs
+
+#### moldinsight-owned
+- stp_files
+- geometry_data
+- mesh_data
+- html_files
+- processing_tasks
+- mold_cavity_data
+- feature_detections
+- design_recommendations
+- analysis_metrics
+
+#### inventory-owned
+- products
+- product_materials
+- material_price_history
+- material_suppliers
+- suppliers
+- customers
+- warehouses
+- inventory
+- stock_movements
+- purchase_orders
+- purchase_order_items
+- sales_orders
+- sales_order_items
+- finance_transactions
+- finance_allocations
+
+### 8.4 目标代码形态
+
+推荐逐步演进到：
+
+```text
+platform/database/base.py
+modules/identity/infrastructure/persistence/models.py
+modules/moldinsight/infrastructure/persistence/models.py
+modules/inventory/infrastructure/persistence/models.py
+```
+
+同时保持：
+
+- 同一个 SQLAlchemy `Base`
+- 同一个 metadata
+- 同一条 Alembic 历史链
+- 同一个数据库连接
+
+### 8.5 跨模块 FK 的处理策略
+
+当前存在真实跨模块业务桥：
+
+- `STPFile.product_id -> Product.id`
+
+这是合理的，因为它反映了真实业务关系：模具分析结果可以创建成品，并与 inventory 中的产品建立连接。
+
+原则上允许保留这类稳定 FK，但应遵守：
+
+1. 跨模块 FK 是**业务桥**，不是“任意跨模块查询”的许可
+2. 模块之间应逐步通过 query service / repository contract 暴露需要的读取能力
+3. 避免一个模块直接依赖另一个模块的整套 ORM 图谱
+
+---
+
+## 9. 部署模式设计
+
+本项目必须支持三种部署模式。
+
+### 9.1 unified
+
+#### 组成
+- platform + identity + moldinsight + inventory
+
+#### 适用场景
+- 本地开发
+- 小团队部署
+- 集成环境
+- 一体化业务场景
+
+#### 说明
+新的 unified 组合层应接替旧 [main.py](../src/main.py) 的语义，但应通过 `compositions/unified_app.py` 的方式实现，而不是继续维持旧单体式入口。
+
+---
+
+### 9.2 gemold-only
+
+#### 组成
+- platform + identity + moldinsight
+
+#### 适用场景
+- 仅开放模具分析能力
+- 分析服务独立扩容
+- 单独部署算法/文件处理能力
+
+#### 说明
+- 只暴露 gemold 路由
+- 可保留对共享数据库中 `products` 的受控引用
+- RustFS / Celery 等专属基础设施只在该模式启用
+
+当前入口基线：
+- [moldinsight.py](../src/entrypoints/moldinsight.py)
+
+---
+
+### 9.3 inventory-only
+
+#### 组成
+- platform + identity + inventory
+
+#### 适用场景
+- 仅提供 ERP / 进销存能力
+- 不需要模具分析链路的后台场景
+
+#### 说明
+- 只暴露 inventory 路由
+- 不要求启动 RustFS 等 moldinsight 专属基础设施
+
+当前入口基线：
+- [inventory.py](../src/entrypoints/inventory.py)
+
+---
+
+### 9.4 当前共享工厂的边界问题
+
+需要特别指出：当前 [app_factory.py](../src/shared/app_factory.py) 通过 `mount_html=True` 分支初始化 RustFS，这说明共享工厂仍然知道 moldinsight 模块专属基础设施。
+
+这意味着：
+
+- `shared` / `platform` 还不够纯
+- 模块专属 startup hook 还没有完全从平台层剥离
+
+后续实施时，这应是**优先解决的问题之一**：
+
+> app factory 只负责通用平台装配；模块专属生命周期应由 module hook 或 composition layer 决定。
+
+---
+
+## 10. 前端 API 边界策略
+
+### 10.1 设计原则
+
+前端已经是独立工程，不需要再拆目录或拆仓。后续重点应放在：
+
+- 强化域 API 边界
+- 消除对单一同源 `/api/...` 的强依赖
+- 兼容 unified / split deployment
+
+### 10.2 当前可复用基础
+
+当前前端已经具备良好基础：
+
+- 域客户端入口：[api-client.ts](../frontend/src/shared/api-client.ts)
+- 生成类型：[api.ts](../frontend/src/types/api.ts)
+- 模块目录：[frontend/src/modules/moldinsight/](../frontend/src/modules/moldinsight/) 与 [frontend/src/modules/inventory/](../frontend/src/modules/inventory/)
+
+因此，后续策略应是“**边界强化**”，不是“前端重写”。
+
+### 10.3 建议的客户端边界
+
+应继续收敛为：
+
+- `authApi`
+- `moldinsightApi`
+- `inventoryApi`
+
+并要求：
+
+- 页面/组件尽量不直接写裸 `/api/...` 字符串
+- multipart upload / download / export 也尽量通过域客户端封装
+- 统一利用 OpenAPI 生成类型，而不是额外维护平行手写类型
+
+### 10.4 支持两类部署配置
+
+#### unified 模式
+- `VITE_API_BASE_URL`
+
+#### split 模式
+- `VITE_AUTH_API_BASE_URL`
+- `VITE_MOLDINSIGHT_API_BASE_URL`
+- `VITE_INVENTORY_API_BASE_URL`
+
+客户端实现上应支持：
+
+- unified 下三个 client 指向同一个 base URL
+- split 下各 client 指向不同服务
+
+### 10.5 capability-aware UI
+
+在 gemold-only 或 inventory-only 部署模式下，前端不应假设所有模块总是存在。
+
+因此建议：
+
+- 后端通过 `/health` 或单独 capability endpoint 暴露已启用模块信息
+- 前端根据 capability 隐藏未部署模块入口或禁用对应页面
+
+这样可避免“前端路由还在，但后端根本没部署”的硬失败场景。
+
+---
+
+## 11. 分阶段迁移计划
+
+### Phase 0：蓝图冻结
+
+目标：冻结目标结构与边界规则，防止迁移过程中继续长出新的耦合。
+
+动作：
+- 确认模块边界
+- 确认依赖规则
+- 确认三种部署模式
+- 确认 shared/platform 的使用边界
+
+---
+
+### Phase 1：组合层标准化
+
+目标：将部署模式从“若干入口脚本”升级为“正式的 composition layer”。
+
+动作：
+- 将 `entrypoints/*` 升级为 `compositions/*`
+- 定义 `unified_app.py` / `gemold_app.py` / `inventory_app.py`
+- 将 module-specific startup hooks 从通用 app factory 中迁出
+
+重点问题：
+- 当前 `mount_html -> RustFS connect` 属于模块专属逻辑，必须从 shared factory 中剥离
+
+---
+
+### Phase 2：platform 与业务代码分治
+
+目标：把“共享基础设施”从“共享杂项”中真正分离出来。
+
+动作：
+- 从 `shared` 语义切换到更清晰的 `platform`
+- 归位 config / auth / db / observability / utils
+- 禁止新业务逻辑继续沉积到 `shared`
+
+---
+
+### Phase 3：ORM 按归属拆分
+
+目标：解决当前最大的代码耦合源。
+
+动作：
+- 拆分 [database.py](../src/shared/models/database.py)
+- 保持单 Base / 单 Alembic / 单 DB
+- 先完成代码层归属拆分，再处理更深层的业务隔离
+
+这是整个重构中最关键的一步。
+
+---
+
+### Phase 4：模块内部继续分层
+
+目标：让每个模块内部的“路由 / 服务 / 领域 / 基础设施”边界更清晰。
+
+动作：
+- inventory：从现有 service 层继续向 `application / domain / infrastructure / interfaces` 拉开
+- moldinsight：逐步理顺 `api / services / core / storage` 的边界
+
+原则：
+- 不要求一步完成 DDD 化
+- 先把层次职责清楚，再考虑更纯粹的领域对象抽象
+
+---
+
+### Phase 5：建立跨模块集成规则
+
+目标：把当前 ad hoc 跨表访问逐步收敛成显式桥接能力。
+
+动作：
+- 定义跨模块 query services / repository contracts
+- 明确“从分析创建成品”等桥接能力的正式入口
+- 收敛直接穿透跨模块 ORM 图谱的做法
+
+重点桥接场景：
+- `STPFile.product_id`
+- [product_routes.py](../src/inventory/api/product_routes.py) 中的“按 task 创建产品”逻辑
+
+---
+
+### Phase 6：前端边界加固
+
+目标：让前端真正适配 unified / split deployment。
+
+动作：
+- 强制域 API client 收口
+- 支持 per-module base URL
+- 支持 capability-aware UI
+- 减少页面中裸 `fetch('/api/...')`
+
+---
+
+### Phase 7：部署与文档收尾
+
+目标：使架构蓝图与部署事实一致。
+
+动作：
+- 固化 unified / gemold-only / inventory-only 部署说明
+- 更新 README / deployment docs / frontend docs
+- 明确旧入口、旧 Dockerfile、旧部署说明的地位（兼容 / 历史 / 废弃）
+
+---
+
+## 12. 风险与缓解措施
+
+### 风险 1：共享模型文件继续隐藏领域归属
+
+**现象**：所有模型集中在 [database.py](../src/shared/models/database.py)
+
+**风险**：边界无法落实，任何模块都能自然跨领域访问
+
+**缓解**：
+- 先产出表归属矩阵
+- 再拆 ORM 文件
+- 拆归属优先于改业务逻辑
+
+---
+
+### 风险 2：`shared` 继续变成杂物间
+
+**风险**：shared/platform 成为“不知道放哪就放这里”的位置
+
+**缓解**：
+- 以 `platform` 重新定义共享层
+- 明确只有技术性共享能力可进入 platform
+- 代码 review 中禁止新增业务逻辑进入 platform
+
+---
+
+### 风险 3：模块专属启动逻辑继续留在 app factory
+
+**现象**：当前 `mount_html` 分支控制 RustFS 连接
+
+**风险**：平台层继续了解业务模块内部基础设施
+
+**缓解**：
+- module lifecycle hook
+- composition 层控制模块 startup/shutdown
+- 通用 app factory 保持纯平台化
+
+---
+
+### 风险 4：独立部署后，前端仍假设所有模块存在
+
+**风险**：前端路由可见，但后端未部署，造成运行时错误
+
+**缓解**：
+- capability metadata
+- feature gating
+- 前端按模块部署形态动态隐藏入口
+
+---
+
+### 风险 5：单数据库导致开发者随意跨模块查表
+
+**风险**：虽然数据库未拆，但代码边界被绕开
+
+**缓解**：
+- 表归属规则文档化
+- code review 要求说明跨模块访问理由
+- 逐步通过 query services 收口
+
+---
+
+### 风险 6：大爆炸式目录迁移导致 import churn
+
+**风险**：一次性移动所有目录，修改面过大，回归成本高
+
+**缓解**：
+- 分阶段迁移
+- 保留兼容 import 过渡层
+- 先稳定组合层与模型层，再做深层目录调整
+
+---
+
+## 13. 验证清单
+
+### 13.1 结构验证
+
+- `platform` 不 import 业务模块
+- `moldinsight` / `inventory` 无直接 api/services 互引
+- ORM 文件已按归属拆分，或至少表归属矩阵已文档化并被遵守
+
+### 13.2 运行验证
+
+#### unified
+- 两类路由都能正常挂载
+- 统一 health / auth / request-id 机制生效
+
+#### gemold-only
+- inventory 路由未挂载
+- gemold 路由可用
+- RustFS / Celery 等专属依赖正常初始化
+
+#### inventory-only
+- moldinsight 路由未挂载
+- inventory 路由可用
+- 不依赖 moldinsight 专属基础设施即可启动
+
+### 13.3 数据验证
+
+- 三种部署模式使用同一 migration head
+- 单数据库中的跨模块 FK 保持有效
+- Alembic 无分叉历史
+
+### 13.4 前端验证
+
+- unified 模式下，一个 base URL 即可跑通
+- split 模式下，各模块 base URL 可独立配置
+- 未部署模块能被隐藏或优雅失败
+
+---
+
+## 14. 文档联动更新计划
+
+本蓝图批准后，以下文档应逐步对齐：
+
+- [EVOLUTION_ROADMAP.md](./EVOLUTION_ROADMAP.md)
+- [LINUX_SETUP.md](./deployment/LINUX_SETUP.md)
+- [DEPLOY_PORT.md](./deployment/DEPLOY_PORT.md)
+- [PORT_CONFIG.md](./deployment/PORT_CONFIG.md)
+- [PORT_REFACTOR_SUMMARY.md](./deployment/PORT_REFACTOR_SUMMARY.md)
+- `README.md`
+- `frontend/README.md`
+
+其中需要特别注意：
+
+- `README.md` 当前仍主要描述旧单体结构，与当前实际代码已有明显漂移。
+- 本文档应作为“当前目标架构”的权威蓝图，路线图与部署文档随后对齐。
+
+---
+
+## 15. 附录：实施热点文件
+
+以下文件是后续实际重构时最关键的热点：
+
+### 平台与组合层
+- [app_factory.py](../src/shared/app_factory.py)
+- [settings.py](../src/shared/config/settings.py)
+- [database.py](../src/shared/database/database.py)
+- [init_db.py](../src/shared/database/init_db.py)
+- [moldinsight.py](../src/entrypoints/moldinsight.py)
+- [inventory.py](../src/entrypoints/inventory.py)
+- [main.py](../src/main.py)
+
+### 模型与边界
+- [database.py](../src/shared/models/database.py)
+- [product_routes.py](../src/inventory/api/product_routes.py)
+
+### gemold 模块
+- [moldinsight/api/__init__.py](../src/moldinsight/api/__init__.py)
+- [processing_service.py](../src/moldinsight/services/processing_service.py)
+- [task_query_service.py](../src/moldinsight/services/task_query_service.py)
+
+### inventory 模块
+- [inventory/api/__init__.py](../src/inventory/api/__init__.py)
+- [inventory_service.py](../src/inventory/services/inventory_service.py)
+- [sales_order_service.py](../src/inventory/services/sales_order_service.py)
+- [purchase_order_service.py](../src/inventory/services/purchase_order_service.py)
+- [finance_service.py](../src/inventory/services/finance_service.py)
+
+### 前端边界
+- [api-client.ts](../frontend/src/shared/api-client.ts)
+- [api.ts](../frontend/src/types/api.ts)
+
+### 演进与部署参考
+- [EVOLUTION_ROADMAP.md](./EVOLUTION_ROADMAP.md)
+- [docker-compose.yml](../docker-compose.yml)
+
+---
+
+## 16. 最终结论
+
+本项目当前最适合的演进路径不是微服务，而是：
+
+> **单仓库 + 单数据库 + 多模块 + 可独立部署的 modular monolith**
+
+它既能保留当前业务闭环（模具分析 → 成品 → BOM → 销售/采购/库存），又能逐步降低共享层和模型层的结构耦合。
+
+后续实施时，应优先按以下顺序推进：
+
+1. 固化组合层（deployment composition）
+2. 纯化 platform/shared 边界
+3. 拆分共享 ORM 文件
+4. 再继续模块内部细分层次
+5. 最后收口前端 API 与部署文档
+
+这条路径风险最低、收益最大，也最符合当前代码现状与团队演进成本。
@@ -18,7 +18,7 @@

 ### P0-1 Celery worker 不连 Redis/RustFS，异步任务全坏
 - **现象**：任务进度写进 Celery 私有内存，web 端永远读不到；首次上传 RustFS 直接抛 `RuntimeError("RustFS 未连接")`。
- **证据**：`redis_task_manager.connect()` / `rustfs_manager.connect()` 只在 FastAPI startup 调用（`entrypoints/moldinsight.py:42,48`），Celery 进程不跑 startup；`processing_service.py` 在 celery 内调 `update_task` 时 `is_connected=False` 走 `_fallback_set`；`rustfs_storage.py:125-126` 未连接直接抛错。`deploy/docker-compose.yml` 的 `moldinsight-celery` 服务块缺 `REDIS_PASSWORD`。
+- **证据**：`redis_task_manager.connect()` / `rustfs_manager.connect()` 只在 FastAPI startup 调用（`entrypoints/moldinsight.py:42,48`），Celery 进程不跑 startup；`processing_service.py` 在 celery 内调 `update_task` 时 `is_connected=False` 走 `_fallback_set`；`rustfs_storage.py:125-126` 未连接直接抛错。`docker-compose.yml` 的 `moldinsight-celery` 服务块缺 `REDIS_PASSWORD`。
 - **修法**：`celery_tasks.py` 加 `@worker_process_init` 信号，显式 `connect()` redis 与 rustfs；补齐 celery 服务的 `REDIS_PASSWORD`/`SECRET_KEY` 等环境变量，与主应用对齐。
 - **验证**：上传一个 STP，Celery 路径下任务进度能从 web 端 `/api/status/{task_id}` 读到；上传后 RustFS 中能看到对象。
 - **状态**：- [ ]
@@ -70,7 +70,7 @@

 ### P0 执行结果（2026-07-13）

- ✅ **P0-1 Celery 连接**：`celery_tasks.py` 在任务内显式 `redis_task_manager.reconnect()` + `rustfs_manager.connect()`（Redis 客户端绑定事件循环，每任务 reconnect；RustFS 同步客户端连一次复用）；`deploy/docker-compose.yml` celery 服务补 `REDIS_PASSWORD`/`RUSTFS_TIMEOUT`
+- ✅ **P0-1 Celery 连接**：`celery_tasks.py` 在任务内显式 `redis_task_manager.reconnect()` + `rustfs_manager.connect()`（Redis 客户端绑定事件循环，每任务 reconnect；RustFS 同步客户端连一次复用）；`docker-compose.yml` celery 服务补 `REDIS_PASSWORD`/`RUSTFS_TIMEOUT`
 - ✅ **P0-2 LLM NameError**：`llm_service.py:339` `trimmed` -> `features`
 - ✅ **P0-3 前端字段错配**：FinanceTab 全字段对齐 schema（summary/statement/product-statement/transaction 共 16 处）；`UserResponse` 加 `is_superuser` + 统一 `_build_user_response` 构造（修用户管理菜单不显示）；DashboardTab `product_count`->`finished_product_count`；PurchaseOrdersTab `received_at/paid_at`->`received_date/paid_date`；后端 `FinanceTransactionResponse` 补 `partner_name` 并批量查询客户/供应商名称
 - ✅ **P0-4 OCC 线程安全**：`geometry_analyzer._detect_features` `max_workers` 4->1
@@ -1,255 +1,154 @@
 # 存储架构说明

+> 本文档主要解释 geMoldInsight 的存储分层与数据流。其历史中的“本项目自行拉起 PostgreSQL / MinIO 并通过 `python src/main.py` 启动单体”的部分，**已不再代表当前默认部署方式**。
+
+当前默认部署前提是：
+
+- PostgreSQL 由服务器已有服务提供
+- Redis 由服务器已有服务提供
+- RustFS / MinIO 兼容对象存储由服务器已有服务提供
+- 项目自身只部署：`moldinsight` / `moldinsight-celery` / `inventory`
+
+如需查看当前部署方式，请优先参考：
+- [README.md](../README.md)
+- [LINUX_SETUP.md](./deployment/LINUX_SETUP.md)
+- [DEPLOY_PORT.md](./deployment/DEPLOY_PORT.md)
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](./BACKEND_MODULARIZATION_BLUEPRINT.md)
+
+---
+
 ## 架构概述

-本项目采用 **RustFS (S3兼容)** 作为对象存储和 **PostgreSQL** 作为元数据存储的双层存储架构。
+本项目采用 **RustFS（S3兼容）对象存储** + **PostgreSQL 元数据存储** 的双层存储架构。

-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
-│                     应用层 (FastAPI)                    │
+│                  应用层 (gemold / inventory)                │
 └──────────────────────┬──────────────────────────────────────┘
                       │
        ┌──────────────┴──────────────┐
        │                              │
 ┌───────▼────────┐        ┌─────────▼─────────┐
-│   PostgreSQL    │        │     RustFS/S3     │
+│   PostgreSQL    │        │     RustFS / S3   │
 │   (元数据)      │        │   (对象存储)       │
 │                │        │                  │
 │ - users        │        │ - stp-files      │
 │ - stp_files    │        │ - geometry       │
 │ - geometry_data│        │ - mold-cavities │
-│ - mold_cavity  │        │ - html-files     │
-│ - features     │        │ - user-files     │
-│ - logs        │        │                  │
+│ - processing   │        │ - html-files     │
+│ - logs         │        │ - user-files     │
 └────────────────┘        └──────────────────┘
 ```

-## PostgreSQL 数据表
+---
+
+## PostgreSQL 数据表（摘要）

 ### 用户管理
- `users` - 用户信息（用户名、邮箱、密码等）
+- `users` - 用户信息
+- `roles` / `permissions` - 权限体系

-### 文件管理
- `stp_files` - STP文件元数据（文件名、哈希、大小、状态等）
- `html_files` - HTML报告文件元数据
-
-### 几何数据
- `geometry_data` - 几何分析数据（体积、表面积、边界框等）
- `mold_cavity_data` - 模具型腔数据（工艺参数、质量评估等）
- `feature_detections` - 特征检测结果（壁厚、拔模角等）
- `design_recommendations` - 设计建议（优先级、参数等）
-
-### 任务和日志
+### gemold 相关
+- `stp_files` - STP 文件元数据
+- `html_files` - HTML 报告元数据
+- `geometry_data` - 几何分析数据
+- `mold_cavity_data` - 模具型腔数据
+- `feature_detections` - 特征检测结果
+- `design_recommendations` - 设计建议
 - `processing_tasks` - 处理任务记录
- `user_activities` - 用户活动日志
- `system_logs` - 系统日志
+- `analysis_metrics` - 分析指标

-## RustFS 存储桶
+### inventory 相关
+- `products` - 产品/物料
+- `product_materials` - BOM
+- `inventory` - 库存
+- `stock_movements` - 库存流水
+- `purchase_orders` / `sales_orders` - 订单
+- `finance_transactions` - 财务流水
+
+---
+
+## RustFS / S3 存储桶

 | 存储桶名称 | 用途 | 存储内容 |
-|-------------|------|---------|
-| `moldinsight-stp-files` | STP/STEP文件 | 用户上传的原始3D模型文件 |
-| `moldinsight-geometry` | 几何数据 | 几何分析结果的JSON数据 |
-| `moldinsight-mold-cavities` | 模具型腔数据 | 模具设计的详细JSON数据 |
-| `moldinsight-html` | HTML文件 | 生成的HTML报告文件 |
-| `moldinsight-user-files` | 用户文件 | 其他用户上传的文件 |
+|---|---|---|
+| `moldinsight-stp-files` | STP/STEP 文件 | 用户上传的原始 3D 模型 |
+| `moldinsight-geometry` | 几何结果 | 几何分析 JSON |
+| `moldinsight-mold-cavities` | 模具结果 | 模具设计 JSON |
+| `moldinsight-html` | HTML 报告 | 生成的 HTML 报告文件 |
+| `moldinsight-user-files` | 用户文件 | 其他附件/用户文件 |

-## 快速开始
+---

-### 1. 安装依赖
+## 当前推荐初始化方式
+
+### 1. 准备环境变量

 ```bash
-pip install -r requirements.txt
-```
-
-### 2. 启动 PostgreSQL
-
-使用 Docker Compose（推荐）：
-```bash
-docker-compose up -d postgres
-```
-
-或手动启动：
-```bash
-# 创建数据库
-createdb moldinsight
-
-# 运行数据库容器
-docker run -d \
-  --name postgres \
-  -e POSTGRES_DB=moldinsight \
-  -e POSTGRES_USER=moldinsight_user \
-  -e POSTGRES_PASSWORD=your_password \
-  -p 5432:5432 \
-  postgres:15
-```
-
-### 3. 启动 MinIO
-
-使用 Docker Compose（推荐）：
-```bash
-docker-compose up -d minio
-```
-
-或手动启动：
-```bash
-docker run -d \
-  --name minio \
-  -p 9000:9000 \
-  -p 9001:9001 \
-  -e MINIO_ROOT_USER=minioadmin \
-  -e MINIO_ROOT_PASSWORD=minioadmin \
-  minio/minio server /data --console-address ":9001"
-```
-
-### 4. 配置环境变量
-
-```bash
-# 复制示例配置
 cp .env.example .env
-
-# 编辑 .env 文件，修改数据库和MinIO配置
 nano .env
 ```

-### 5. 初始化数据库和存储
+确保以下变量指向**服务器上已存在的真实服务**：

-```bash
-# 初始化数据库
-python src/database/init_db.py
+```env
+DB_HOST=your-db-host
+DB_PORT=5432
+DB_NAME=moldinsight
+DB_USER=moldinsight
+DB_PASSWORD=change-me

-# 初始化MinIO存储
-python src/storage/init_storage.py
+REDIS_HOST=your-redis-host
+REDIS_PORT=6379
+REDIS_PASSWORD=
+
+RUSTFS_ENDPOINT=http://your-storage-host:9000
+RUSTFS_ACCESS_KEY=change-me
+RUSTFS_SECRET_KEY=change-me
 ```

-### 6. 启动服务
+### 2. 初始化数据库

-```bash
-python src/main.py
-```
+当前初始化入口参考：
+- [init_db.py](../src/shared/database/init_db.py)

-## 使用示例
+### 3. 启动项目服务

-### 保存STP文件
+当前推荐通过：
+- [docker-compose.yml](../docker-compose.yml)
+- 或 [src/entrypoints/](../src/entrypoints/)

-```python
-from services.storage_integration import storage_integration
-from database.database import db_manager
+而不是继续使用历史单体 `python src/main.py` 作为默认方式。

-async def upload_file(file_path: str):
-    async with db_manager.get_session() as session:
-        stp_file = await storage_integration.save_stp_file(
-            session=session,
-            file_path=Path(file_path),
-            original_filename="model.stp",
-            user_id=1
-        )
-        print(f"文件已保存，ID: {stp_file.id}")
-```
+---

-### 保存几何数据
+## 监控与维护

-```python
-async def save_geometry(stp_file_id: int, geometry_data: dict):
-    async with db_manager.get_session() as session:
-        geo_data = await storage_integration.save_geometry_data(
-            session=session,
-            stp_file_id=stp_file_id,
-            geometry_json=geometry_data,
-            analysis_method="pythonocc"
-        )
-        print(f"几何数据已保存，ID: {geo_data.id}")
-```
-
-### 获取文件数据
-
-```python
-async def get_file_data(stp_file_id: int):
-    async with db_manager.get_session() as session:
-        data = await storage_integration.get_stp_file_with_data(
-            session=session,
-            stp_file_id=stp_file_id
-        )
-        
-        # 访问几何数据
-        geometry = data['geometry_data']
-        print(f"体积: {geometry['volume']}")
-        print(f"表面积: {geometry['surface_area']}")
-        
-        # 访问模具型腔数据
-        cavity = data['mold_cavity_data']
-        print(f"模具材料: {cavity['mold_material']}")
-        
-        # 访问特征和建议
-        for feature in data['features']:
-            print(f"特征: {feature['feature_type']}")
-```
-
-## 数据清理策略
-
-### MinIO 对象存储
- 设置生命周期策略自动删除旧文件
- 示例：删除30天前的临时文件
+### 对象存储
+- 检查对象存储服务可达性
+- 定期清理历史产物
+- 配置生命周期策略

 ### PostgreSQL
- 定期清理已删除用户的记录
- 归档超过6个月的日志数据
+- 定期备份
+- 监控连接池与慢查询
+- 保持 Alembic 迁移链一致

-## 监控和维护
-
-### 检查存储使用情况
-```bash
-# MinIO控制台
-# http://localhost:9001
-# 用户名: minioadmin
-# 密码: minioadmin
-```
-
-### 数据库备份
-```bash
-# 备份数据库
-pg_dump -h localhost -U moldinsight_user moldinsight > backup.sql
-
-# 恢复数据库
-psql -h localhost -U moldinsight_user moldinsight < backup.sql
-```
-
-## 性能优化
-
-### PostgreSQL
- 创建适当的索引（已在模型中定义）
- 定期运行 VACUUM 和 ANALYZE
- 考虑使用连接池（已配置）
-
-### MinIO
- 启用缓存层
- 配置CDN分发静态文件
- 使用多区域复制
-
-## 安全建议
-
-1. **更改默认密码**：生产环境必须更改所有默认密码
-2. **启用TLS**：生产环境启用 HTTPS
-3. **访问控制**：配置适当的用户权限
-4. **数据加密**：敏感数据加密存储
-5. **定期备份**：设置自动备份策略
+---

 ## 故障排除

-### 连接MinIO失败
-```
-错误: 对象存储连接失败
-解决: 检查 MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY 配置
-```
+### 对象存储连接失败
+- 检查 `RUSTFS_ENDPOINT`
+- 检查 access key / secret key
+- 检查服务端口与网络策略

 ### 数据库连接失败
-```
-错误: 数据库连接失败
-解决: 检查 DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD 配置
-```
+- 检查 `DB_HOST` / `DB_PORT`
+- 检查数据库账号密码
+- 检查防火墙与白名单

 ### 文件上传失败
-```
-错误: STP文件上传失败
-解决: 检查磁盘空间、网络连接、MinIO权限
-```
+- 检查对象存储可用性
+- 检查 Celery worker 是否运行
+- 检查 Redis 是否可达
@@ -1,170 +1,204 @@
-# 部署时端口配置说明
+# 模块化部署端口说明

-## 生产环境部署端口配置
+> 本文档描述的是 **当前模块化部署模式** 下的端口规划，不再以历史单体 `src.main:app` 作为默认前提。

-本项目现在使用统一的端口配置文件 `.env`，部署时需要相应调整配置。
+当前推荐部署对象：

-### Gunicorn 启动配置
+- gemold API
+- gemold Celery worker（无 HTTP 端口）
+- inventory API

-**推荐方式（使用 .env 配置）：**
+以下基础设施默认由服务器现有服务提供，不在本项目 compose 中重复部署：
+
+- PostgreSQL
+- Redis
+- MinIO / RustFS（gemold 需要）
+
+---
+
+## 1. 推荐端口规划
+
+| 组件 | 默认端口 | 说明 |
+|---|---:|---|
+| gemold API | 8000 | 模具分析后端 |
+| inventory API | 8001 | 进销存后端 |
+| PostgreSQL | 5432 | 共享数据库 |
+| Redis | 6379 | 共享队列/缓存 |
+| MinIO API | 9000 | 对象存储接口 |
+| MinIO Console | 9001 | 对象存储控制台 |
+
+> Celery worker 不直接暴露 HTTP 端口。
+
+---
+
+## 2. 三种部署模式下的端口
+
+### 2.1 gemold-only
+
+- 对外开放：`8000`
+- 依赖：PostgreSQL、Redis、MinIO/RustFS
+- 可选：前置 Nginx 暴露 80/443
+
+### 2.2 inventory-only
+
+- 对外开放：`8001`
+- 依赖：PostgreSQL、Redis
+- 不要求对象存储
+
+### 2.3 unified
+
+两种常见实现：
+
+1. **统一网关模式**
+   - 外部只开放 80/443
+   - 网关转发到 gemold / inventory
+2. **统一应用组合模式**
+   - 统一后端监听单一端口
+   - 后续组合层重构完成后更适合采用
+
+当前阶段，如果需要统一对外，更推荐**网关统一**而不是继续依赖历史单体入口。
+
+---
+
+## 3. Docker Compose 端口来源
+
+当前主部署文件：
+- [docker-compose.yml](../../docker-compose.yml)
+
+关键端口映射：
+
+- `MOLDINSIGHT_PORT` → gemold API 外部端口
+- `INVENTORY_PORT` → inventory API 外部端口
+
+示例：
+
+```env
+MOLDINSIGHT_PORT=8000
+INVENTORY_PORT=8001
+```
+
+对应 compose 行为：
+
+- gemold：`${MOLDINSIGHT_PORT:-8000}:8000`
+- inventory：`${INVENTORY_PORT:-8001}:8001`
+
+---
+
+## 4. 直接运行时的端口约定
+
+### gemold-only

 ```bash
-# 创建启动脚本
-cat > start_production.sh << 'EOF'
-#!/bin/bash
-cd /opt/moldinsight/moldinsight_project
-source venv/bin/activate
-
-# 从 .env 读取端口配置
-if [ -f .env ]; then
-    PORT=$(grep '^PORT=' .env | cut -d'=' -f2)
-else
-    PORT=8000
-fi
-
-# 启动服务
-gunicorn src.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:${PORT}
-EOF
-
-chmod +x start_production.sh
-./start_production.sh
+uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
 ```

-### systemd 服务配置
+### inventory-only

-创建 `/etc/systemd/system/moldinsight.service`：
-
-```ini
-[Unit]
-Description=MoldInsight Geometry Analysis Service
-After=network.target postgresql.service
-
-[Service]
-Type=simple
-User=www-data
-Group=www-data
-WorkingDirectory=/opt/moldinsight/moldinsight_project
-Environment=PATH=/opt/moldinsight/moldinsight_project/venv/bin
-Environment="PORT=8000"
-ExecStart=/opt/moldinsight/moldinsight_project/venv/bin/gunicorn src.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:${PORT}
-Restart=always
-
-[Install]
-WantedBy=multi-user.target
+```bash
+uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
 ```

-**重要：** 在 `[Service]` 部分添加 `Environment="PORT=8000"`，或在 `.env` 文件中配置 `PORT=8000`。
+如果改端口：
+- gemold 改 `--port`
+- inventory 改 `--port`
+- 同步更新 Nginx / 防火墙 / 前端 base URL

-### Nginx 反向代理配置
+---
+
+## 5. 前端联动
+
+如果前端与后端分开部署，需要与前端环境变量保持一致。
+
+建议前端支持：
+
+### unified 模式
+```env
+VITE_API_BASE_URL=https://api.example.com
+```
+
+### split 模式
+```env
+VITE_AUTH_API_BASE_URL=https://auth.example.com
+VITE_MOLDINSIGHT_API_BASE_URL=https://gemold.example.com
+VITE_INVENTORY_API_BASE_URL=https://inventory.example.com
+```
+
+当前详细策略见：
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](../BACKEND_MODULARIZATION_BLUEPRINT.md)
+
+---
+
+## 6. Nginx 示例
+
+### gemold-only

 ```nginx
-upstream moldinsight_backend {
-    server 127.0.0.1:8000;  # 对应 .env 中的 PORT
-}
-
 server {
    listen 80;
-    server_name your-domain.com;
+    server_name gemold.example.com;

    location / {
-        proxy_pass http://moldinsight_backend;
+        proxy_pass http://127.0.0.1:8000;
        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;
    }
+}
+```

-    location /static {
-        alias /opt/moldinsight/moldinsight_project/static;
-    }
+### inventory-only

-    location /html_output {
-        alias /opt/moldinsight/moldinsight_project/html_output;
+```nginx
+server {
+    listen 80;
+    server_name inventory.example.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:8001;
+        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;
    }
 }
 ```

-### Docker 部署
+---

-Docker 部署自动从 `.env` 读取配置，无需额外设置：
+## 7. 防火墙建议
+
+如果不通过 Nginx 统一入口而是直接暴露服务端口，则应显式开放：

 ```bash
-# .env 文件配置
-PORT=8000          # 容器内端口
-HOST_PORT=8080     # 宿主机端口
+# gemold
+sudo ufw allow 8000/tcp

-# 启动
-docker-compose up -d
+# inventory
+sudo ufw allow 8001/tcp
 ```

-### 修改生产环境端口
+生产环境更推荐：
+- 外部只开放 80/443
+- 内部仅开放 8000/8001 给 Nginx 或内网访问

-1. **编辑 .env 文件**
-   ```bash
-   PORT=9000  # 修改应用端口
-   ```
+---

-2. **重启服务**
-   ```bash
-   # systemd
-   sudo systemctl restart moldinsight
-
-   # Docker
-   docker-compose down && docker-compose up -d
-
-   # 手动启动
-   ./start_production.sh
-   ```
-
-3. **更新 Nginx 配置（如果使用）**
-   ```nginx
-   upstream moldinsight_backend {
-       server 127.0.0.1:9000;  # 更新为新端口
-   }
-   ```
-   ```bash
-   sudo nginx -t && sudo nginx -s reload
-   ```
-
-### 防火墙配置
-
-如果修改了端口，需要更新防火墙规则：
+## 8. 快速检查

 ```bash
-# UFW (Ubuntu/Debian)
-sudo ufw allow 9000/tcp
-sudo ufw delete allow 8000/tcp  # 删除旧端口
-
-# firewall-cmd (CentOS/RHEL)
-sudo firewall-cmd --permanent --add-port=9000/tcp
-sudo firewall-cmd --permanent --remove-port=8000/tcp
-sudo firewall-cmd --reload
+curl http://127.0.0.1:8000/health
+curl http://127.0.0.1:8001/health
 ```

-### 健康检查
+如果只部署单模块，只检查对应服务即可。

-修改端口后，更新健康检查命令：
+---

-```bash
-# 检查服务状态
-curl http://localhost:9000/health
-curl http://your-domain.com/health
-```
+## 9. 结论

-## 快速参考
+在当前模块化架构下：

-| 部署方式 | 端口配置位置 | 重启命令 |
-|---------|------------|---------|
-| 直接运行 | `.env` 中的 `PORT` | Ctrl+C 后重新运行 |
-| Gunicorn | `.env` 中的 `PORT` | `systemctl restart moldinsight` |
-| Docker | `.env` 中的 `PORT` 和 `HOST_PORT` | `docker-compose restart` |
-| Nginx代理 | Nginx配置中的 `proxy_pass` | `nginx -s reload` |
-
-## 注意事项
-
-⚠️ **重要：**
-1. 所有端口配置统一在 `.env` 文件中管理
-2. 修改端口后需要同步更新相关配置（Nginx、防火墙等）
-3. 确保新端口没有被其他服务占用
-4. 生产环境建议使用 Nginx 反向代理，对外提供 80/443 端口
-5. .env 文件不应提交到版本控制系统，使用 `.env.example` 作为模板
+- gemold 与 inventory 应视为**两个独立后端模块**
+- 端口应按模块分配，而不是继续沿用单体“一个后端一个端口”的思路
+- unified 更适合通过**组合层或网关**实现，而不是继续让历史单体入口承载全部语义
@@ -1,177 +1,315 @@
-# MoldInsight Linux 部署指南
+# geMoldInsight Linux 部署指南

-## 系统要求
- Linux 系统 (Ubuntu 20.04+ / CentOS 8+)
- Python 3.8+
- PostgreSQL 12+
+> 本文档描述的是 **当前模块化架构** 下的 Linux 部署方式，而不是历史单体 `src.main:app` 方案。
+
+当前项目支持三种部署模式：
+
+- **unified**：gemold + inventory 统一部署
+- **gemold-only**：仅部署模具分析后端
+- **inventory-only**：仅部署进销存后端
+
+项目保持：
+
+- **同一 Git 仓库**
+- **同一 PostgreSQL 数据库**
+- **共享认证体系**
+- **按模块独立部署**
+- **复用服务器上已存在的 PostgreSQL / Redis / RustFS(或 MinIO 兼容存储)**
+
+详细架构蓝图见：
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](../BACKEND_MODULARIZATION_BLUEPRINT.md)
+
+---
+
+## 1. 系统要求
+
+### 基础要求
+- Linux（Ubuntu 22.04+ / Debian 12+ / CentOS Stream 9+）
+- Python 3.12
 - Git
+- 服务器上已可访问的 PostgreSQL 15+
+- 服务器上已可访问的 Redis 7+

-## 1. 环境准备
+### 按模块附加要求
+
+#### gemold / unified 需要
+- 服务器上已可访问的 MinIO 或 RustFS 兼容对象存储
+- PythonOCC 运行环境
+- Celery worker（推荐与 gemold 一起部署）
+
+#### inventory-only 需要
+- PostgreSQL
+- Redis
+- 不依赖 MinIO / RustFS
+- 不依赖 Celery worker
+
+---
+
+## 2. 代码获取与目录约定

-### 安装系统依赖
 ```bash
-# Ubuntu/Debian
-sudo apt update
-sudo apt install python3 python3-pip python3-venv postgresql postgresql-contrib git
-
-# CentOS/RHEL
-sudo yum update
-sudo yum install python3 python3-pip postgresql postgresql-server git
-```
-
-### 配置PostgreSQL
-```bash
-# 启动PostgreSQL服务
-sudo systemctl start postgresql
-sudo systemctl enable postgresql
-
-# 创建数据库和用户
-sudo -u postgres psql
-```
-
-在PostgreSQL中执行：
-```sql
-CREATE DATABASE moldinsight;
-CREATE USER molduser WITH PASSWORD 'moldpassword';
-GRANT ALL PRIVILEGES ON DATABASE moldinsight TO molduser;
-\q
-```
-
-## 2. 项目部署
-
-### 克隆或复制项目
-```bash
-# 如果使用Git
 cd /opt
-sudo git clone <your-repo-url> moldinsight
-sudo chown -R $USER:$USER moldinsight
-cd moldinsight
-
-# 或者直接复制项目文件到Linux服务器
+sudo git clone <your-repo-url> geMoldInsight
+sudo chown -R $USER:$USER geMoldInsight
+cd geMoldInsight
 ```

-### 创建Python虚拟环境
+后续示例默认项目位于：
+
 ```bash
-cd moldinsight_project
-python3 -m venv venv
-source venv/bin/activate
+/opt/geMoldInsight
 ```

-### 安装依赖
+---
+
+## 3. Python 环境准备
+
 ```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
 pip install --upgrade pip
 pip install -r requirements.txt
 ```

-## 3. 环境配置
+> 如果需要 gemold 分析能力，请额外准备 PythonOCC 运行环境。该依赖通常通过 conda 或预构建运行镜像提供，而不是直接由 pip 安装。
+
+---
+
+## 4. 环境变量配置
+
+复制模板：

-### 修改环境配置文件
-编辑 `.env` 文件：
 ```bash
-nano .env
+cp .env.example .env
 ```

-修改为Linux环境的配置：
-```env
-# 数据库配置（Linux环境）
-DATABASE_URL=postgresql+asyncpg://molduser:moldpassword@localhost:5432/moldinsight
+或部署场景参考：

-# 服务配置
-DEBUG=false
+```bash
+cp deploy/.env.example .env
+```
+
+至少需要配置（并指向服务器上已存在的基础设施）：
+
+```env
 HOST=0.0.0.0
 PORT=8000

-# Redis配置（可选）
-REDIS_HOST=localhost
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_NAME=moldinsight
+DB_USER=moldinsight_user
+DB_PASSWORD=change-me
+
+REDIS_HOST=127.0.0.1
 REDIS_PORT=6379
 REDIS_PASSWORD=

-# Kafka配置（可选）
-KAFKA_BOOTSTRAP_SERVERS=localhost:9092
-KAFKA_SECURITY_PROTOCOL=PLAINTEXT
+SECRET_KEY=change-me-in-production
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=change-me
+
+RUSTFS_ENDPOINT=http://127.0.0.1:9000
+RUSTFS_ACCESS_KEY=minioadmin
+RUSTFS_SECRET_KEY=minioadmin
 ```

-### 创建必要的目录
+说明：
+- `RUSTFS_*` 仅 **gemold / unified** 模式需要
+- `inventory-only` 可不使用对象存储
+- 当前配置读取实现见 [settings.py](../../src/shared/config/settings.py)
+
+---
+
+## 5. 数据库初始化
+
+项目当前使用 Alembic 管理迁移，应用启动时也会执行初始化流程。
+
+首次部署建议：
+
+1. 确保服务器上的 PostgreSQL / Redis / 对象存储服务已可访问
+2. 启动应用前确认 `.env` 中的 `DB_HOST` / `REDIS_HOST` / `RUSTFS_ENDPOINT` 指向真实服务地址
+3. 让应用执行初始化/升级逻辑
+
+相关实现参考：
+- [init_db.py](../../src/shared/database/init_db.py)
+
+> 当前项目是 **单数据库** 设计，因此 unified / gemold-only / inventory-only 都连接到同一个数据库与同一 migration head。
+
+---
+
+## 6. 启动方式
+
+## 6.1 inventory-only
+
 ```bash
-mkdir -p uploads html_output logs
-chmod 755 uploads html_output logs
+source .venv/bin/activate
+uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
 ```

-## 4. 启动服务
+适合：
+- 只提供进销存能力
+- 不需要模具分析与异步任务
+
+---
+
+## 6.2 gemold-only

-### 开发模式启动
 ```bash
-cd moldinsight_project
-source venv/bin/activate
-python src/main.py
+source .venv/bin/activate
+uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
 ```

-### 生产环境启动（使用Gunicorn）
+适合：
+- 单独部署模具分析能力
+- 文件上传 / 分析 / 导出 / 批量分析
+
+### gemold Celery worker
+
+建议同时启动 worker：
+
 ```bash
-# 安装Gunicorn
-pip install gunicorn uvloop httptools
-
-# 启动服务
-cd moldinsight_project
-source venv/bin/activate
-gunicorn src.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
+source .venv/bin/activate
+celery -A src.celery_app.celery_app worker --loglevel=info
 ```

-## 5. 系统服务配置（可选）
+> gemold 的异步处理链路依赖 Celery + Redis；若只启动 HTTP 服务而不启动 worker，上传分析任务可能无法完整处理。
+
+---
+
+## 6.3 unified
+
+当前仓库仍保留历史统一入口 [main.py](../../src/main.py)，但它更适合作为**过渡参考**，不建议作为长期标准入口。
+
+在正式完成组合层重构前，如需统一部署，可优先使用反向代理或部署编排层统一暴露 gemold 与 inventory；后续会演进为显式 `unified_app.py`。
+
+蓝图参考：
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](../BACKEND_MODULARIZATION_BLUEPRINT.md)
+
+---
+
+## 7. systemd 部署示例
+
+## 7.1 inventory-only 服务
+
+创建：

-### 创建systemd服务文件
 ```bash
-sudo nano /etc/systemd/system/moldinsight.service
+sudo nano /etc/systemd/system/gemold-inventory.service
 ```

-添加以下内容：
 ```ini
 [Unit]
-Description=MoldInsight Geometry Analysis Service
-After=network.target postgresql.service
+Description=geMoldInsight Inventory API
+After=network.target postgresql.service redis.service

 [Service]
 Type=simple
 User=www-data
 Group=www-data
-WorkingDirectory=/opt/moldinsight/moldinsight_project
-Environment=PATH=/opt/moldinsight/moldinsight_project/venv/bin
-ExecStart=/opt/moldinsight/moldinsight_project/venv/bin/gunicorn src.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
+WorkingDirectory=/opt/geMoldInsight
+Environment=PATH=/opt/geMoldInsight/.venv/bin
+ExecStart=/opt/geMoldInsight/.venv/bin/uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
 Restart=always
+RestartSec=5

 [Install]
 WantedBy=multi-user.target
 ```

-### 启用并启动服务
+启用：
+
 ```bash
 sudo systemctl daemon-reload
-sudo systemctl enable moldinsight
-sudo systemctl start moldinsight
-sudo systemctl status moldinsight
+sudo systemctl enable gemold-inventory
+sudo systemctl start gemold-inventory
 ```

-## 6. Nginx反向代理配置（可选）
+---
+
+## 7.2 gemold-only API 服务
+
+创建：

-### 安装Nginx
 ```bash
-# Ubuntu/Debian
-sudo apt install nginx
-
-# CentOS/RHEL
-sudo yum install nginx
+sudo nano /etc/systemd/system/gemold-moldinsight.service
 ```

-### 创建Nginx配置文件
+```ini
+[Unit]
+Description=geMoldInsight MoldInsight API
+After=network.target postgresql.service redis.service
+
+[Service]
+Type=simple
+User=www-data
+Group=www-data
+WorkingDirectory=/opt/geMoldInsight
+Environment=PATH=/opt/geMoldInsight/.venv/bin
+ExecStart=/opt/geMoldInsight/.venv/bin/uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+---
+
+## 7.3 gemold Celery worker 服务
+
+创建：
+
 ```bash
-sudo nano /etc/nginx/sites-available/moldinsight
+sudo nano /etc/systemd/system/gemold-celery.service
 ```

-添加以下内容：
+```ini
+[Unit]
+Description=geMoldInsight MoldInsight Celery Worker
+After=network.target postgresql.service redis.service
+
+[Service]
+Type=simple
+User=www-data
+Group=www-data
+WorkingDirectory=/opt/geMoldInsight
+Environment=PATH=/opt/geMoldInsight/.venv/bin
+ExecStart=/opt/geMoldInsight/.venv/bin/celery -A src.celery_app.celery_app worker --loglevel=info
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+---
+
+## 8. Nginx 反向代理示例
+
+### 8.1 inventory-only
+
 ```nginx
 server {
    listen 80;
-    server_name your-domain.com;
+    server_name inventory.example.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:8001;
+        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;
+    }
+}
+```
+
+### 8.2 gemold-only
+
+```nginx
+server {
+    listen 80;
+    server_name gemold.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
@@ -180,102 +318,86 @@ server {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
-
-    location /static {
-        alias /opt/moldinsight/moldinsight_project/static;
-        expires 30d;
-    }
 }
 ```

-### 启用站点并重启Nginx
-```bash
-sudo ln -s /etc/nginx/sites-available/moldinsight /etc/nginx/sites-enabled/
-sudo nginx -t
-sudo systemctl restart nginx
-```
+### 8.3 unified（示意）

-## 7. 防火墙配置
+统一对外时，可由网关做模块路由，也可直接暴露统一组合后的应用入口。组合层标准化完成前，更推荐通过部署编排或网关来实现统一对外访问。
+
+---
+
+## 9. 验证部署
+
+### 9.1 健康检查
+
+inventory-only：

 ```bash
-# Ubuntu/Debian (ufw)
-sudo ufw allow 80
-sudo ufw allow 8000
-sudo ufw allow ssh
-sudo ufw enable
-
-# CentOS/RHEL (firewalld)
-sudo firewall-cmd --permanent --add-port=80/tcp
-sudo firewall-cmd --permanent --add-port=8000/tcp
-sudo firewall-cmd --permanent --add-service=ssh
-sudo firewall-cmd --reload
+curl http://127.0.0.1:8001/health
 ```

-## 8. 验证部署
+gemold-only：

-### 检查服务状态
 ```bash
-# 检查应用服务
-curl http://localhost:8000/health
-
-# 检查数据库连接
-sudo -u postgres psql -d moldinsight -c "SELECT version();"
+curl http://127.0.0.1:8000/health
 ```

-### 测试文件上传
-访问 `http://your-server-ip:8000` 上传STP文件测试功能。
+### 9.2 基础能力验证

-## 9. 故障排除
+#### inventory-only
+- 登录接口可用
+- `/api/products` 返回数据
+- `/api/inventory` 返回数据

-### 常见问题
+#### gemold-only
+- 登录接口可用
+- `/api/upload` 可访问
+- 上传后 worker 能正常消费任务
+- `/api/status/{task_id}` 能看到进度

-1. **数据库连接失败**
-   - 检查PostgreSQL服务状态：`sudo systemctl status postgresql`
-   - 验证数据库连接：`psql -h localhost -U molduser -d moldinsight`
+---

-2. **端口被占用**
-   - 检查端口使用：`netstat -tulpn | grep 8000`
-   - 修改端口或停止占用进程
+## 10. 常见问题

-3. **权限问题**
-   - 确保目录权限正确：`chmod 755 uploads html_output logs`
-   - 检查文件所有者：`ls -la`
+### 1. 为什么不再推荐 `src.main:app`？
+因为当前项目已演进为模块化结构，`src.main:app` 更适合作为过渡兼容入口，而不是长期部署标准。应优先围绕 [entrypoints/](../../src/entrypoints/) 部署。

-4. **依赖安装失败**
-   - 更新pip：`pip install --upgrade pip`
-   - 使用国内镜像：`pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`
+### 2. inventory-only 为什么不需要对象存储？
+因为对象存储主要服务于 gemold 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。

-## 10. 备份和恢复
+### 3. gemold-only 为什么建议同时部署 Celery？
+因为模具分析任务通常走异步处理链路，仅启动 API 而不启动 worker，会影响上传后的任务处理。
+
+---
+
+## 11. Docker Compose 说明
+
+当前 [docker-compose.yml](../../docker-compose.yml) 仅启动：
+
+- `moldinsight`
+- `moldinsight-celery`
+- `inventory`
+
+它**不会**再拉起：
+
+- PostgreSQL
+- Redis
+- MinIO
+
+这些基础设施应由服务器现有服务提供，并通过 `.env` 传入连接信息。
+
+示例：

-### 数据库备份
 ```bash
-# 备份数据库
-sudo -u postgres pg_dump moldinsight > moldinsight_backup.sql
-
-# 恢复数据库
-sudo -u postgres psql -d moldinsight < moldinsight_backup.sql
+docker compose --profile full up -d
 ```

-### 文件备份
-```bash
-# 备份上传的文件和配置
-tar -czf moldinsight_backup.tar.gz uploads/ html_output/ .env requirements.txt
-```
+---

-## 快速启动脚本
+## 12. 推荐阅读

-创建启动脚本 `start.sh`：
-```bash
-#!/bin/bash
-cd /opt/moldinsight/moldinsight_project
-source venv/bin/activate
-python src/main.py
-```
-
-赋予执行权限：
-```bash
-chmod +x start.sh
-./start.sh
-```
-
-现在您的MoldInsight项目已经可以在Linux环境下正常运行！
+- [README.md](../../README.md)
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](../BACKEND_MODULARIZATION_BLUEPRINT.md)
+- [DEPLOY_PORT.md](./DEPLOY_PORT.md)
+- [PORT_CONFIG.md](./PORT_CONFIG.md)
@@ -1,107 +1,174 @@
-# 端口配置说明
+# 端口配置说明（模块化架构）

-## ⚠️ 重要提示
+> 本文档说明当前 geMoldInsight 在**模块化部署**下的端口配置方式。

-本项目现在采用**统一端口配置管理**，所有端口配置集中在一个地方：
+当前架构中应区分：

-**唯一修改端口的地方：** `.env` 文件中的端口配置部分
+- **gemold API 端口**
+- **inventory API 端口**
+- **数据库/Redis/对象存储端口**
+- **前端访问地址**

-## 配置说明
+不再推荐把所有部署场景都抽象成“单应用单端口”。

-编辑项目根目录下的 `.env` 文件：
+---

-```bash
-# ================================
-# 端口配置 - 唯一修改端口的地方
-# ================================
-# 应用端口（容器内端口）
-PORT=8000
-# Docker映射到宿主机的端口（docker-compose使用）
-HOST_PORT=10001
-# ================================
+## 1. 当前主配置位置
+
+对于 Docker Compose 部署，当前主要端口配置来源于：
+
+- [docker-compose.yml](../../docker-compose.yml)
+- `.env` / `deploy/.env.example`
+
+注意：该 compose 文件仅负责项目应用容器，不负责 PostgreSQL / Redis / 对象存储容器。
+
+核心环境变量：
+
+```env
+MOLDINSIGHT_PORT=8000
+INVENTORY_PORT=8001
 ```

-### 端口含义
+其余基础设施通常为：

-| 变量 | 用途 | 默认值 | 说明 |
-|------|------|--------|------|
-| `PORT` | 应用监听端口 | 8000 | FastAPI/Uvicorn 服务监听的端口 |
-| `HOST_PORT` | 宿主机映射端口 | 10001 | Docker Compose 映射到宿主机的端口 |
-
-### 使用场景
-
-#### 1. 本地直接运行（Python）
-```bash
-python src/main.py
+```env
+DB_PORT=5432
+REDIS_PORT=6379
 ```
-服务将在 `http://localhost:8000` 启动（使用 `PORT` 配置）

-#### 2. Docker Compose 运行
-```bash
-docker-compose up
+对象存储常见端口（由服务器既有服务提供）：
+
+```env
+RUSTFS_ENDPOINT=http://localhost:9000
 ```
-服务将在 `http://localhost:10001` 访问（使用 `HOST_PORT` 配置）
-容器内部使用 `PORT` 配置的端口（8000）

-#### 3. 修改端口
+---

-**场景A：只想修改外部访问端口（Docker）**
-```bash
-# .env 文件
-PORT=8000          # 容器内不变
-HOST_PORT=8080     # 宿主机改为8080
+## 2. 各端口的含义
+
+| 变量 / 端口 | 用途 |
+|---|---|
+| `MOLDINSIGHT_PORT` | gemold API 宿主机暴露端口 |
+| `INVENTORY_PORT` | inventory API 宿主机暴露端口 |
+| `DB_PORT` | PostgreSQL 端口 |
+| `REDIS_PORT` | Redis 端口 |
+| `9000` | MinIO/RustFS S3 兼容 API |
+| `9001` | MinIO 控制台 |
+
+---
+
+## 3. 推荐配置方式
+
+### 3.1 gemold-only
+
+```env
+MOLDINSIGHT_PORT=8000
+DB_PORT=5432
+REDIS_PORT=6379
 ```
-访问地址：`http://localhost:8080`

-**场景B：修改应用端口（容器内/本地运行）**
-```bash
-# .env 文件
-PORT=9000          # 应用改为9000
-HOST_PORT=10001    # 宿主机映射到10001
+### 3.2 inventory-only
+
+```env
+INVENTORY_PORT=8001
+DB_PORT=5432
+REDIS_PORT=6379
 ```
- 本地运行：`http://localhost:9000`
- Docker运行：`http://localhost:10001` （映射到容器内9000）

-**场景C：同时修改两个端口**
-```bash
-# .env 文件
-PORT=9000
-HOST_PORT=9000
+### 3.3 full / 模块同时部署
+
+```env
+MOLDINSIGHT_PORT=8000
+INVENTORY_PORT=8001
+DB_PORT=5432
+REDIS_PORT=6379
 ```
- 本地运行：`http://localhost:9000`
- Docker运行：`http://localhost:9000`

-## 配置文件说明
+---

-### 配置读取优先级
+## 4. 为什么不再强调单一 `PORT` 变量

-1. **`config/settings.py`** - 从 `.env` 读取 `PORT` 和 `HOST`
-2. **`src/main.py`** - 从 `settings` 获取端口配置
-3. **`docker-compose.yml`** - 从 `.env` 读取 `HOST_PORT` 和 `PORT`
+历史单体部署通常只有一个后端入口，因此 `PORT=8000` 足够。

-### 相关文件
+当前项目已经是：
+- gemold 独立入口
+- inventory 独立入口
+- unified 作为组合模式而非默认单体入口

- **`.env`** - ⭐ 唯一需要修改的配置文件
- **`config/settings.py`** - 配置读取逻辑（无需修改）
- **`src/main.py`** - 使用配置启动服务（无需修改）
- **`docker-compose.yml`** - Docker端口映射（自动读取 `.env`）
- **`start.sh` / `start_fixed.sh`** - 启动脚本（自动读取 `.env`）
+因此端口配置必须模块化：

-## 常见问题
+- gemold 一个端口
+- inventory 一个端口
+- 如果 unified 对外存在，可以由网关统一暴露 80/443

-### Q: 为什么 Docker 宿主机端口和应用端口分开配置？
-A: 这样可以灵活调整容器端口而不影响外部访问，也避免端口冲突。
+这比继续强行把所有模式压成一个 `PORT` 更清晰，也更符合真实部署方式。

-### Q: 修改后需要重启吗？
-A: 是的，修改 `.env` 后需要重启服务才能生效：
- 本地运行：Ctrl+C 停止后重新 `python src/main.py`
- Docker: `docker-compose down && docker-compose up`
+---

-### Q: 如何避免端口冲突？
-A: 确保 `HOST_PORT` 不与其他服务冲突，可以使用 `netstat -an | grep <端口>` 检查端口占用情况。
+## 5. 直接运行与 Compose 的区别

-### Q: 可以使用 80 端口吗？
-A: 可以，但需要管理员权限：
- Linux/Mac: 使用 sudo
- Docker: 需要容器有足够权限
- 生产环境建议使用反向代理（如 Nginx）
+### 直接运行
+
+gemold：
+
+```bash
+uvicorn src.entrypoints.moldinsight:app --port 8000
+```
+
+inventory：
+
+```bash
+uvicorn src.entrypoints.inventory:app --port 8001
+```
+
+### Docker Compose
+
+Compose 通过端口映射暴露服务：
+
+- gemold → `${MOLDINSIGHT_PORT}:8000`
+- inventory → `${INVENTORY_PORT}:8001`
+
+当前实际定义见：
+- [docker-compose.yml](../../docker-compose.yml)
+
+---
+
+## 6. 与前端配置的关系
+
+前端是否使用 unified / split deployment，会影响前端 API 地址配置。
+
+### unified
+- 一个 API 基地址
+
+### split
+- gemold 与 inventory 各自基地址
+
+因此，修改后端端口后，可能还需要同步：
+
+- 前端 `.env`
+- Nginx 反向代理
+- 浏览器访问地址
+
+---
+
+## 7. 推荐实践
+
+1. **本地开发**
+   - gemold：8000
+   - inventory：8001
+
+2. **服务器部署**
+   - 外网只暴露 80/443
+   - Nginx 反代到 8000 / 8001
+
+3. **不要继续把所有部署模式都写成 `src.main:app + PORT=8000`**
+   - 这已不符合当前架构
+
+---
+
+## 8. 关联文档
+
+- [LINUX_SETUP.md](./LINUX_SETUP.md)
+- [DEPLOY_PORT.md](./DEPLOY_PORT.md)
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](../BACKEND_MODULARIZATION_BLUEPRINT.md)
+- [README.md](../../README.md)
@@ -1,192 +1,39 @@
-# 端口配置重构总结
+# 端口配置历史说明（已被模块化部署文档取代）

-## 修改内容
+本文件保留为历史说明。

-本次重构将项目的端口配置统一到 `.env` 文件中，确保整个项目只有一个地方需要修改端口。
+它所描述的“单体应用单一端口配置”思路，已经不再能完整代表当前 geMoldInsight 的模块化架构。

-## 修改的文件
+当前项目已演进为：

-### 1. ⭐ `.env` - 唯一配置入口
-**变更：** 添加了统一的端口配置区域
-```bash
-# ================================
-# 端口配置 - 唯一修改端口的地方
-# ================================
-# 应用端口（容器内端口）
-PORT=8000
-# Docker映射到宿主机的端口（docker-compose使用）
-HOST_PORT=10001
-# ================================
-```
+- gemold 模块可独立部署
+- inventory 模块可独立部署
+- unified 作为组合模式存在
+- gemold 与 inventory 应分别考虑端口与网关暴露方式

-### 2. `src/main.py`
-**变更：** 从硬编码的环境变量读取改为从 `config.settings` 读取
-```python
-# 修改前
-host = os.getenv('HOST', '0.0.0.0')
-port = int(os.getenv('PORT', '8000'))
+因此，端口配置的权威说明已转移到以下文档：

-# 修改后
-from config.settings import settings
-# ...
-host=settings.HOST,
-port=settings.PORT
-```
+- [LINUX_SETUP.md](./LINUX_SETUP.md)
+- [DEPLOY_PORT.md](./DEPLOY_PORT.md)
+- [PORT_CONFIG.md](./PORT_CONFIG.md)
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](../BACKEND_MODULARIZATION_BLUEPRINT.md)

-### 3. `docker-compose.yml`
-**变更：** 端口映射从硬编码改为从环境变量读取
-```yaml
-# 修改前
-ports:
-  - "10001:8000"
-environment:
-  - PORT=8000
+---

-# 修改后
-ports:
-  - "${HOST_PORT:-10001}:${CONTAINER_PORT:-8000}"
-environment:
-  - HOST=${HOST:-0.0.0.0}
-  - PORT=${CONTAINER_PORT:-8000}
-```
+## 当前结论

-### 4. `start.sh` 和 `start_fixed.sh`
-**变更：** 自动从 `.env` 读取端口并显示正确的访问地址
-```bash
-# 添加
-PORT=$(grep '^PORT=' .env 2>/dev/null | cut -d'=' -f2 || echo '8000')
-echo "🌐 服务将在 http://localhost:${PORT} 启动"
-```
+1. 不再默认以历史单体 `src.main:app` 作为部署中心。
+2. 不再假设整个系统只有一个后端端口。
+3. gemold 与 inventory 应按模块分别规划端口。
+4. unified 更适合通过组合层或网关统一暴露，而不是继续沿用旧单体部署语义。

-### 5. `README.md`
-**变更：** 更新访问说明，提示端口配置位置
+---

-### 6. 新增文件
- `.env.example` - 配置文件模板
- `PORT_CONFIG.md` - 端口配置详细说明
- `DEPLOY_PORT.md` - 部署时端口配置指南
+## 建议

-## 配置读取流程
+如果你正在查找当前有效的端口/部署方式，请不要继续参考旧的单体端口说明，而应直接查看：

-```
-.env 文件
-    ↓
-config/settings.py (读取 PORT 和 HOST)
-    ↓
-src/main.py (使用 settings.PORT)
-    ↓
-uvicorn 启动服务
-```
-
-Docker 部署流程：
-```
-.env 文件
-    ↓
-docker-compose.yml (读取 HOST_PORT 和 PORT)
-    ↓
-容器映射和内部启动
-```
-
-## 如何修改端口
-
-### 方法 1：修改应用端口
-```bash
-# 编辑 .env
-PORT=9000  # 修改此行
-```
- 本地运行：`http://localhost:9000`
- Docker运行：需同时修改 `HOST_PORT=9000`
-
-### 方法 2：修改 Docker 外部访问端口
-```bash
-# 编辑 .env
-HOST_PORT=8080  # 修改此行（PORT 保持不变）
-```
- Docker运行：`http://localhost:8080`
- 容器内仍使用 PORT 配置的端口
-
-## 测试验证
-
-### 测试 1：本地运行
-```bash
-# 修改 .env 中的 PORT
-PORT=9999
-
-# 启动服务
-python src/main.py
-
-# 验证
-curl http://localhost:9999/health
-```
-
-### 测试 2：Docker 运行
-```bash
-# 修改 .env
-PORT=8000
-HOST_PORT=9999
-
-# 启动容器
-docker-compose up -d
-
-# 验证
-curl http://localhost:9999/health
-```
-
-### 测试 3：启动脚本
-```bash
-# 修改 .env
-PORT=8888
-
-# 运行启动脚本
-./start.sh
-
-# 检查输出是否显示正确的端口
-```
-
-## 注意事项
-
-1. ✅ 所有端口配置集中在 `.env` 文件
-2. ✅ 无需修改代码文件即可更改端口
-3. ✅ 支持本地运行和 Docker 部署两种场景
-4. ✅ 提供了详细的配置文档
-5. ⚠️ 修改端口后需要重启服务
-6. ⚠️ Docker 部署时需要同时考虑容器内外端口
-7. ⚠️ 确保新端口没有被占用
-
-## 文件清单
-
-### 修改的文件
- `.env` - 添加端口配置区域
- `src/main.py` - 统一使用 settings 配置
- `docker-compose.yml` - 支持环境变量配置端口
- `start.sh` - 自动读取和显示端口
- `start_fixed.sh` - 自动读取和显示端口
- `README.md` - 更新访问说明
-
-### 新增的文件
- `.env.example` - 配置模板
- `PORT_CONFIG.md` - 端口配置详细说明
- `DEPLOY_PORT.md` - 部署配置指南
- `PORT_REFACTOR_SUMMARY.md` - 本文档
-
-## 回滚方案
-
-如果需要回滚，按以下步骤操作：
-
-```bash
-git checkout -- src/main.py
-git checkout -- docker-compose.yml
-git checkout -- start.sh start_fixed.sh
-git checkout -- .env
-git checkout -- README.md
-
-# 删除新增文件
-rm .env.example PORT_CONFIG.md DEPLOY_PORT.md PORT_REFACTOR_SUMMARY.md
-```
-
-## 联系支持
-
-如有问题，请查看：
- `PORT_CONFIG.md` - 端口配置详细说明
- `DEPLOY_PORT.md` - 部署配置指南
- `.env.example` - 配置示例
+- [README.md](../../README.md)
+- [LINUX_SETUP.md](./LINUX_SETUP.md)
+- [DEPLOY_PORT.md](./DEPLOY_PORT.md)
+- [PORT_CONFIG.md](./PORT_CONFIG.md)
@@ -1,66 +0,0 @@
-#!/bin/bash
-
-# MoldInsight 启动脚本 - 修复版
-# 适用于Linux miniforge环境
-
-echo "🚀 启动 MoldInsight 模具几何分析系统..."
-
-# 检查Python版本
-python_version=$(python3 -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
-echo "📋 Python版本: $python_version"
-
-# 初始化miniforge环境
-echo "🔧 初始化miniforge环境..."
-source /opt/miniforge3/etc/profile.d/conda.sh
-
-# 激活conda环境
-echo "🔧 激活py_3.12环境..."
-conda activate py_3.12
-
-# 验证PythonOCC是否可用
-echo "🔍 验证PythonOCC..."
-python3 -c "import OCC; print('✅ PythonOCC可用')" || {
-    echo "❌ PythonOCC不可用，请先安装PythonOCC"
-    exit 1
-}
-
-# 检查是否已经安装依赖
-echo "📦 检查依赖包..."
-pip install --upgrade -r requirements.txt
-
-# 创建必要目录
-echo "📁 创建必要目录..."
-mkdir -p uploads html_output logs
-
-# 检查环境配置文件
-if [ ! -f ".env" ]; then
-    echo "❌ 错误: 未找到.env配置文件"
-    echo "📋 请创建.env文件并配置数据库连接信息:"
-    echo "   1. 创建.env文件: touch .env"
-    echo "   2. 编辑配置文件: nano .env"
-    echo "   3. 添加数据库配置:"
-    echo "      DATABASE_URL=postgresql+asyncpg://username:password@localhost:5432/database_name"
-    echo ""
-    echo "💡 提示: 请根据实际的PostgreSQL连接信息修改上述配置"
-    exit 1
-fi
-
-echo "🔧 检查数据库连接..."
-
-# 启动服务
-echo "🚀 启动 MoldInsight 服务..."
-PORT=$(grep '^PORT=' .env 2>/dev/null | cut -d'=' -f2 || echo '8000')
-echo "🌐 服务将在 http://localhost:${PORT} 启动"
-echo "📊 功能特性:"
-echo "  - STP文件解析和几何分析"
-echo "  - JSON数据导出"
-echo "  - PostgreSQL数据库存储"
-echo "  - 3D可视化HTML生成"
-echo "  - Web界面文件上传"
-echo "  - 任务状态跟踪"
-echo ""
-echo "按 Ctrl+C 停止服务"
-echo ""
-
-# 启动应用
-python3 src/main.py