diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..890c4c0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,137 @@
+# AGENTS.md - geMoldInsight 开发规范
+
+> 本文件是给开发 agent（Claude / Codex / …）和协作开发者的项目入口约定。**开始任何实现前先读本文件**。
+> 人类入口见 [README.md](README.md)；当前实现状态见 [docs/STATUS.md](docs/STATUS.md)；当前架构与边界见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
+
+## 1. 项目定位
+
+**geMoldInsight** 是一个面向模具制造场景的综合系统，围绕：
+
+- STEP / STP 模型分析
+- 模具方案生成
+- 分析结果沉淀与导出
+- 成品创建
+- BOM / 库存 / 采购 / 销售闭环
+
+当前整体形态为：
+
+> **单仓库 + 单数据库 + 多模块 + 可独立部署**
+
+核心模块：
+- `moldinsight`：模具分析、几何处理、批量分析、成本估算、结果导出
+- `inventory`：产品、BOM、库存、采购、销售、财务
+- `frontend`：Vue 3 前端工程
+- `shared`：配置、数据库、认证、日志、应用工厂等共享平台层
+
+## 2. 硬约束速览（违反即返工）
+
+- **执行前必须先同步方案到文档**：开始实施前，必须先把方案写入对应文档，再按照文档中的步骤逐项执行，不能先改代码后补文档。
+- **每次完成需求都必须更新文档**：每完成一个需求，都必须同步更新相关文档，保持文档为最新状态，避免实现与文档漂移。
+- **README 只做导航入口**：不在 README 重复维护状态、架构、规划、部署细节。
+- **当前实现状态只在 [docs/STATUS.md](docs/STATUS.md) 维护**。
+- **架构边界只在 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 维护**。
+- **规划路线只在 [docs/ROADMAP.md](docs/ROADMAP.md) 维护**。
+- **技术债只在 [docs/TECH_DEBT.md](docs/TECH_DEBT.md) 维护**。
+- **部署入口只在 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) 与 [docs/deployment/LINUX_SETUP.md](docs/deployment/LINUX_SETUP.md) 维护**。
+- **历史材料统一进入 [docs/archive/](docs/archive/)**，不与当前权威文档混放。
+- **新增业务逻辑优先进入对应模块**，不要继续把业务逻辑堆进 `shared`。
+- **接口变更优先补契约与请求模型**，减少手写 `request.json()` 风格解析。
+
+## 3. 代码地图
+
+```text
+geMoldInsight/
+├── src/
+│   ├── entrypoints/               # 独立部署入口（moldinsight / inventory / unified）
+│   ├── moldinsight/               # 模具分析模块
+│   │   ├── api/                   # 模具分析 API
+│   │   ├── services/              # 业务服务层
+│   │   ├── core/                  # 几何 / 算法 / OCC 核心能力
+│   │   └── ...
+│   ├── inventory/                 # 进销存模块
+│   │   ├── api/                   # 进销存 API
+│   │   ├── services/              # 业务服务层
+│   │   └── ...
+│   ├── shared/                    # 当前共享平台层（配置 / DB / 认证 / 日志 / app factory）
+│   ├── celery_app.py              # Celery app
+│   └── celery_tasks.py            # moldinsight 异步任务
+├── frontend/                      # Vue 3 独立前端工程
+├── alembic/                       # 数据库迁移
+├── deploy/                        # Docker / Nginx / 部署辅助文件
+├── docs/                          # 当前权威文档与主题文档
+├── tests/                         # 测试
+└── README.md                      # 人类入口与最短启动说明
+```
+
+## 4. 开发规范
+
+### 4.1 文档先行
+
+所有非微小改动都遵循：
+
+1. 先明确改动范围与目标
+2. 先把实施方案同步到文档
+3. 再按文档步骤执行实现
+4. 完成后回填结果、状态、约束变化
+
+如果方案变化，必须先更新文档，再继续实现。
+
+### 4.2 文档更新规则
+
+完成需求后，至少检查并更新这些文档中的相关项：
+
+- 实现状态变化：更新 [docs/STATUS.md](docs/STATUS.md)
+- 架构边界变化：更新 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- 规划变化：更新 [docs/ROADMAP.md](docs/ROADMAP.md)
+- 技术债状态变化：更新 [docs/TECH_DEBT.md](docs/TECH_DEBT.md)
+- 部署方式变化：更新 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) 与 [docs/deployment/LINUX_SETUP.md](docs/deployment/LINUX_SETUP.md)
+- 历史/阶段性材料：必要时迁入 [docs/archive/README.md](docs/archive/README.md) 所索引的位置
+
+### 4.3 代码组织规则
+
+- `moldinsight` 业务代码进入 `src/moldinsight/`
+- `inventory` 业务代码进入 `src/inventory/`
+- 真正跨模块复用的基础能力才进入 `src/shared/`
+- 尽量避免继续扩大 `shared` 的业务组合职责
+- 新增 API 时优先考虑模块归属、service 复用与请求模型规范化
+
+### 4.4 API 与契约规则
+
+- 优先使用明确的请求模型和参数校验
+- 尽量减少手写 `await request.json()` / `request.json()` 解析
+- 路由文件过大时按职责拆分，避免单 router 混合过多领域能力
+- 返回结构、接口路径、前后端契约发生变化时，要同步更新相关文档
+
+### 4.5 文档体系规则
+
+- README 只做导航与最短入门
+- 当前状态只在 [docs/STATUS.md](docs/STATUS.md)
+- 当前架构只在 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- 当前规划只在 [docs/ROADMAP.md](docs/ROADMAP.md)
+- 当前技术债只在 [docs/TECH_DEBT.md](docs/TECH_DEBT.md)
+- 当前部署入口只在 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)
+- 历史材料统一进入 [docs/archive/](docs/archive/)
+
+## 5. 开发完成后的最小检查清单
+
+每次完成需求后，至少确认：
+
+- 代码已按模块边界落位
+- 相关测试已执行或说明未执行原因
+- 相关文档已同步更新
+- `STATUS / ARCHITECTURE / ROADMAP / TECH_DEBT / DEPLOYMENT` 没有与实现冲突的地方
+- 新增历史性说明没有误放进当前权威文档
+
+## 6. 文档导航
+
+| 文档 | 用途 |
+|---|---|
+| [AGENTS.md](AGENTS.md) | 项目开发规范、开发约束、文档同步要求 |
+| [README.md](README.md) | 人类入口、最短启动说明、文档导航 |
+| [docs/STATUS.md](docs/STATUS.md) | 当前实现状态与当前推荐方案 |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 当前架构、模块边界、结构原则 |
+| [docs/ROADMAP.md](docs/ROADMAP.md) | 后续演进路线与阶段计划 |
+| [docs/TECH_DEBT.md](docs/TECH_DEBT.md) | 当前活跃技术债与治理顺序 |
+| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | 部署主题入口 |
+| [docs/deployment/LINUX_SETUP.md](docs/deployment/LINUX_SETUP.md) | Linux 详细部署步骤 |
+| [docs/archive/README.md](docs/archive/README.md) | 历史文档与阶段性材料归档入口 |
diff --git a/README.md b/README.md
index cc961d0..637738d 100644
--- a/README.md
+++ b/README.md
@@ -108,6 +108,7 @@ geMoldInsight/
 
 | 文档 | 解决什么问题 |
 |---|---|
+| [AGENTS.md](AGENTS.md) | 项目开发规范、开发约束、文档同步要求 |
 | [docs/STATUS.md](docs/STATUS.md) | 当前实现状态、当前推荐方案、近期完成项 |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 当前架构、模块边界、结构原则 |
 | [docs/ROADMAP.md](docs/ROADMAP.md) | 后续演进路线与阶段计划 |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index ebcbf56..fd27ad6 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -196,17 +196,11 @@ geMoldInsight/
 
 以下文档仍可作为专题补充参考，但不再承担默认入口职责：
 
-- AI / FreeCAD 方向：
-  - [topics/ai/AI_ENGINE_DESIGN.md](topics/ai/AI_ENGINE_DESIGN.md)
-  - [topics/ai/AI_FREECAD_INTEGRATION.md](topics/ai/AI_FREECAD_INTEGRATION.md)
 - 存储方向：
   - [topics/storage/RUSTFS_STORAGE.md](topics/storage/RUSTFS_STORAGE.md)
   - [topics/storage/STORAGE_SETUP.md](topics/storage/STORAGE_SETUP.md)
-- 铝泡沫模具专题：
-  - [topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md](topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md)
-- 性能专题：
-  - [topics/performance/PERFORMANCE_SCALABILITY_PLAN.md](topics/performance/PERFORMANCE_SCALABILITY_PLAN.md)
-  - [topics/performance/PERFORMANCE_BENCHMARKS.md](topics/performance/PERFORMANCE_BENCHMARKS.md)
+
+AI、性能、铝泡沫等更偏历史设计/规划性质的专题材料已迁入 [archive/README.md](archive/README.md)。
 
 阶段性任务清单、迁移计划、历史总结等文档会逐步迁入 [archive/README.md](archive/README.md)。
 
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index 4faf282..2907c98 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -9,7 +9,7 @@
 
 当前推荐模式为：
 
-- **unified**：frontend + unified backend + moldinsight celery
+- **unified**：frontend + unified backend + moldinsight Celery worker
 
 原因：
 - 适合本地开发与集成环境
@@ -66,11 +66,15 @@
 
 ### 3.2 端口与配置说明
 
-以下文档当前仍保留，但后续会继续收敛：
+以下文档作为当前部署补充说明保留：
 - [deployment/DEPLOY_PORT.md](deployment/DEPLOY_PORT.md)
 - [deployment/PORT_CONFIG.md](deployment/PORT_CONFIG.md)
 
-它们描述的是端口与环境配置细节，不应替代部署入口文档。
+它们的职责分别是：
+- `DEPLOY_PORT.md`：端口暴露、端口规划与 Nginx / 防火墙层面的说明
+- `PORT_CONFIG.md`：环境变量、端口配置项与 direct run / compose 映射补充
+
+它们是部署入口文档的补充参考，不替代本文或 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md)。
 
 ### 3.3 历史/阶段性部署材料
 
@@ -78,7 +82,7 @@
 - [archive/PORT_REFACTOR_SUMMARY.md](archive/PORT_REFACTOR_SUMMARY.md)
 - [archive/FRONTEND_UNIFIED_DEPLOYMENT_PLAN.md](archive/FRONTEND_UNIFIED_DEPLOYMENT_PLAN.md)
 
-这些材料已迁入 `docs/archive/`。
+这些材料已迁入 `docs/archive/`，仅用于历史追溯，不替代当前的 [DEPLOYMENT.md](DEPLOYMENT.md) 、 [deployment/LINUX_SETUP.md](deployment/LINUX_SETUP.md) 与 [deployment/DEPLOY_PORT.md](deployment/DEPLOY_PORT.md)。
 
 ---
 
diff --git a/docs/STATUS.md b/docs/STATUS.md
index 821dbc5..daf2ce1 100644
--- a/docs/STATUS.md
+++ b/docs/STATUS.md
@@ -94,7 +94,7 @@ geMoldInsight 当前已从早期单体演进为：
 当前已验证：
 
 - 本地 pip 环境：**47 passed, 1 skipped**
-- gemold conda + OCC 环境：**88 passed**
+- moldinsight conda + OCC 环境：**88 passed**
 
 说明：
 - 无 OCC 环境下，依赖 pythonocc 的契约测试会自动 skip
diff --git a/docs/archive/README.md b/docs/archive/README.md
index 9150d63..d1c3eba 100644
--- a/docs/archive/README.md
+++ b/docs/archive/README.md
@@ -1,7 +1,7 @@
 # 文档归档说明（archive）
 
 > 文档定位：**历史文档与阶段性材料归档目录**。
-> 当前权威文档请优先查看：
+> archive 仅保存历史迁移说明、阶段性计划与已不再作为默认入口的旧文档；当前权威内容请优先查看 `docs/` 主骨架：
 > - [../STATUS.md](../STATUS.md)
 > - [../ARCHITECTURE.md](../ARCHITECTURE.md)
 > - [../ROADMAP.md](../ROADMAP.md)
@@ -19,3 +19,17 @@
 - [TASKS_ALUMINUM_FOAM_MOLD.md](TASKS_ALUMINUM_FOAM_MOLD.md)
 - [CHECKLIST_ALUMINUM_FOAM_MOLD.md](CHECKLIST_ALUMINUM_FOAM_MOLD.md)
 - [DELIVERABLES.md](DELIVERABLES.md)
+- [EVOLUTION_ROADMAP.md](EVOLUTION_ROADMAP.md)
+- [MOLDINSIGHT_TECH_DEBT_PLAN.md](MOLDINSIGHT_TECH_DEBT_PLAN.md)
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](BACKEND_MODULARIZATION_BLUEPRINT.md)
+- [MOLD_ERP_ANALYSIS_REPORT.md](MOLD_ERP_ANALYSIS_REPORT.md)
+- [ZERO_FINISHED_INVENTORY_CERTIFICATE.md](ZERO_FINISHED_INVENTORY_CERTIFICATE.md)
+- [CONFLUENCE_ARCHIVE_STRUCTURE.md](CONFLUENCE_ARCHIVE_STRUCTURE.md)
+- [topics/ai/](topics/ai/)：已迁移的 AI 相关专题历史材料
+- [topics/performance/](topics/performance/)：已迁移的性能专题历史材料
+- [topics/aluminum-foam/](topics/aluminum-foam/)：已迁移的铝泡沫专题历史材料
+
+部署相关的归档文档仅用于历史追溯；当前对应入口请查看：
+- [../DEPLOYMENT.md](../DEPLOYMENT.md)
+- [../deployment/LINUX_SETUP.md](../deployment/LINUX_SETUP.md)
+- [../deployment/DEPLOY_PORT.md](../deployment/DEPLOY_PORT.md)
diff --git a/docs/topics/ai/AI_ENGINE_DESIGN.md b/docs/archive/topics/ai/AI_ENGINE_DESIGN.md
similarity index 98%
rename from docs/topics/ai/AI_ENGINE_DESIGN.md
rename to docs/archive/topics/ai/AI_ENGINE_DESIGN.md
index 66e2182..26a9151 100644
--- a/docs/topics/ai/AI_ENGINE_DESIGN.md
+++ b/docs/archive/topics/ai/AI_ENGINE_DESIGN.md
@@ -1,7 +1,7 @@
 # AI 智能引擎设计文档
 
 > 文档定位：**AI 能力方向的设计性/专题性文档**。
-> 本文描述的是 AI 引擎的设计设想与能力规划，不作为当前实现状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，当前架构边界见 [../../ARCHITECTURE.md](../../ARCHITECTURE.md)，后续路线见 [../../ROADMAP.md](../../ROADMAP.md)。
+> 本文描述的是 AI 引擎的设计设想与能力规划，不作为当前实现状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，当前架构边界见 [../../../ARCHITECTURE.md](../../../ARCHITECTURE.md)，后续路线见 [../../../ROADMAP.md](../../../ROADMAP.md)。
 ## 一、AI 引擎架构
 
 ### 1.1 整体架构
diff --git a/docs/topics/ai/AI_FREECAD_INTEGRATION.md b/docs/archive/topics/ai/AI_FREECAD_INTEGRATION.md
similarity index 97%
rename from docs/topics/ai/AI_FREECAD_INTEGRATION.md
rename to docs/archive/topics/ai/AI_FREECAD_INTEGRATION.md
index fd73d66..670279e 100644
--- a/docs/topics/ai/AI_FREECAD_INTEGRATION.md
+++ b/docs/archive/topics/ai/AI_FREECAD_INTEGRATION.md
@@ -1,7 +1,7 @@
 # AI + FreeCAD 集成方案
 
 > 文档定位：**AI / FreeCAD 集成方向的专题设计文档**。
-> 本文描述的是集成设想、能力规划与差距分析，不作为当前实现状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，当前架构边界见 [../../ARCHITECTURE.md](../../ARCHITECTURE.md)，后续路线见 [../../ROADMAP.md](../../ROADMAP.md)。
+> 本文描述的是集成设想、能力规划与差距分析，不作为当前实现状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，当前架构边界见 [../../../ARCHITECTURE.md](../../../ARCHITECTURE.md)，后续路线见 [../../../ROADMAP.md](../../../ROADMAP.md)。
 ## 一、项目概述
 
 本文档描述 geMoldInsight 项目集成 AI 智能引擎和 FreeCAD 的完整方案，实现真实的模具型腔生成和 G 代码输出功能。
diff --git a/docs/topics/ai/FREECAD_SETUP.md b/docs/archive/topics/ai/FREECAD_SETUP.md
similarity index 100%
rename from docs/topics/ai/FREECAD_SETUP.md
rename to docs/archive/topics/ai/FREECAD_SETUP.md
diff --git a/docs/topics/ai/GCODE_GENERATION.md b/docs/archive/topics/ai/GCODE_GENERATION.md
similarity index 100%
rename from docs/topics/ai/GCODE_GENERATION.md
rename to docs/archive/topics/ai/GCODE_GENERATION.md
diff --git a/docs/topics/aluminum-foam/MOLD_SPLITTING_IMPROVEMENTS.md b/docs/archive/topics/aluminum-foam/MOLD_SPLITTING_IMPROVEMENTS.md
similarity index 100%
rename from docs/topics/aluminum-foam/MOLD_SPLITTING_IMPROVEMENTS.md
rename to docs/archive/topics/aluminum-foam/MOLD_SPLITTING_IMPROVEMENTS.md
diff --git a/docs/topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md b/docs/archive/topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md
similarity index 98%
rename from docs/topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md
rename to docs/archive/topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md
index fded7b1..09e33d0 100644
--- a/docs/topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md
+++ b/docs/archive/topics/aluminum-foam/SPEC_ALUMINUM_FOAM_MOLD.md
@@ -1,7 +1,7 @@
 # 铝制家电包装泡沫模具分模功能技术规格说明书
 
 > 文档定位：**铝泡沫模具分模方向的专题规格文档**。
-> 本文保留该方向的需求背景、规格设想与能力边界，不作为当前项目整体状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，总体架构见 [../../ARCHITECTURE.md](../../ARCHITECTURE.md)，活跃技术债见 [../../TECH_DEBT.md](../../TECH_DEBT.md)。
+> 本文保留该方向的需求背景、规格设想与能力边界，不作为当前项目整体状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，总体架构见 [../../../ARCHITECTURE.md](../../../ARCHITECTURE.md)，活跃技术债见 [../../../TECH_DEBT.md](../../../TECH_DEBT.md)。
 
 ## 文档信息
 
diff --git a/docs/topics/performance/PERFORMANCE_BENCHMARKS.md b/docs/archive/topics/performance/PERFORMANCE_BENCHMARKS.md
similarity index 87%
rename from docs/topics/performance/PERFORMANCE_BENCHMARKS.md
rename to docs/archive/topics/performance/PERFORMANCE_BENCHMARKS.md
index 0cb2918..d891370 100644
--- a/docs/topics/performance/PERFORMANCE_BENCHMARKS.md
+++ b/docs/archive/topics/performance/PERFORMANCE_BENCHMARKS.md
@@ -1,7 +1,7 @@
 # 性能基准定义（建议）
 
 > 文档定位：**性能基准与压测口径的专题参考文档**。
-> 本文给出建议性性能指标与测试数据口径，不作为当前实现状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，后续路线见 [../../ROADMAP.md](../../ROADMAP.md)。
+> 本文给出建议性性能指标与测试数据口径，不作为当前实现状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，后续路线见 [../../../ROADMAP.md](../../../ROADMAP.md)。
 ## 1. 核心接口基准
 
 | 场景 | 接口 | 指标 |
diff --git a/docs/topics/performance/PERFORMANCE_SCALABILITY_PLAN.md b/docs/archive/topics/performance/PERFORMANCE_SCALABILITY_PLAN.md
similarity index 94%
rename from docs/topics/performance/PERFORMANCE_SCALABILITY_PLAN.md
rename to docs/archive/topics/performance/PERFORMANCE_SCALABILITY_PLAN.md
index 866eda8..ac52a05 100644
--- a/docs/topics/performance/PERFORMANCE_SCALABILITY_PLAN.md
+++ b/docs/archive/topics/performance/PERFORMANCE_SCALABILITY_PLAN.md
@@ -1,7 +1,7 @@
 # 性能与扩展性评估补充（模具订单/采购主线）
 
 > 文档定位：**性能与扩展性方向的专题规划文档**。
-> 本文描述的是性能评估、慢 SQL 发现、扩展路线等补充规划，不作为当前实现状态的权威说明。当前状态见 [../../STATUS.md](../../STATUS.md)，后续路线见 [../../ROADMAP.md](../../ROADMAP.md)。
+> 本文描述的是性能评估、慢 SQL 发现、扩展路线等补充规划，不作为当前实现状态的权威说明。当前状态见 [../../../STATUS.md](../../../STATUS.md)，后续路线见 [../../../ROADMAP.md](../../../ROADMAP.md)。
 ## 1. 高并发冲突面与加固点
 
 ### 1.1 新增/修改模具订单的锁冲突来源
diff --git a/docs/deployment/DEPLOY_PORT.md b/docs/deployment/DEPLOY_PORT.md
index 28e81f2..20d0382 100644
--- a/docs/deployment/DEPLOY_PORT.md
+++ b/docs/deployment/DEPLOY_PORT.md
@@ -2,19 +2,19 @@
 
 > 文档定位：**当前部署下的端口规划补充说明**。
 > 部署入口与当前推荐方案见 [../DEPLOYMENT.md](../DEPLOYMENT.md)，Linux 部署步骤见 [LINUX_SETUP.md](LINUX_SETUP.md)。
-> 本文档描述的是 **当前模块化部署模式** 下的端口规划，不再以历史单体 `src.main:app` 作为默认前提。
+> 本文档负责 **当前模块化部署模式** 下的端口暴露、端口规划与 Nginx / 防火墙层面的补充说明，不再以历史单体 `src.main:app` 作为默认前提。
 
 当前推荐部署对象：
 
 - frontend（Nginx，同域入口）
 - unified backend
-- gemold Celery worker（无 HTTP 端口）
+- moldinsight Celery worker（无 HTTP 端口）
 
 以下基础设施默认由服务器现有服务提供，不在本项目 compose 中重复部署：
 
 - PostgreSQL
 - Redis
-- MinIO / RustFS（gemold 需要）
+- MinIO / RustFS（moldinsight 需要）
 
 ---
 
@@ -24,7 +24,7 @@
 |---|---:|---|
 | frontend | 80 | 前端 Nginx，同域入口 |
 | unified backend | 8000 | 当前推荐统一后端 |
-| gemold API | 8000 | 模具分析独立部署时使用 |
+| moldinsight API | 8000 | 模具分析独立部署时使用 |
 | inventory API | 8001 | 进销存独立部署时使用 |
 | PostgreSQL | 5432 | 共享数据库 |
 | Redis | 6379 | 共享队列/缓存 |
@@ -37,7 +37,7 @@
 
 ## 2. 三种部署模式下的端口
 
-### 2.1 gemold-only
+### 2.1 moldinsight-only
 
 - 对外开放：`8000`
 - 依赖：PostgreSQL、Redis、MinIO/RustFS
@@ -51,16 +51,13 @@
 
 ### 2.3 unified
 
-两种常见实现：
+当前推荐由 unified backend 提供单一后端入口：
 
-1. **统一网关模式**
-   - 外部只开放 80/443
-   - 网关转发到 gemold / inventory
-2. **统一应用组合模式**
-   - 统一后端监听单一端口
-   - 后续组合层重构完成后更适合采用
+- 对外开放：`8000`（或由前置 Nginx / 网关统一暴露 80/443）
+- 依赖：PostgreSQL、Redis、MinIO / RustFS
+- 配套：moldinsight Celery worker 不直接暴露 HTTP 端口
 
-当前阶段，如果需要统一对外，更推荐**网关统一**而不是继续依赖历史单体入口。
+在生产环境中，仍推荐通过同域 Nginx / 网关统一对外暴露 80/443，再反代到 unified backend。
 
 ---
 
@@ -73,7 +70,7 @@
 
 - `FRONTEND_PORT` → frontend Nginx 外部端口
 - `BACKEND_PORT` → unified backend 外部端口
-- `MOLDINSIGHT_PORT` → gemold-only 独立部署端口
+- `MOLDINSIGHT_PORT` → moldinsight-only 独立部署端口
 - `INVENTORY_PORT` → inventory-only 独立部署端口
 
 示例：
@@ -85,14 +82,14 @@ INVENTORY_PORT=8001
 
 对应 compose 行为：
 
-- gemold：`${MOLDINSIGHT_PORT:-8000}:8000`
+- moldinsight：`${MOLDINSIGHT_PORT:-8000}:8000`
 - inventory：`${INVENTORY_PORT:-8001}:8001`
 
 ---
 
 ## 4. 直接运行时的端口约定
 
-### gemold-only
+### moldinsight-only
 
 ```bash
 uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
@@ -105,7 +102,7 @@ uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
 ```
 
 如果改端口：
-- gemold 改 `--port`
+- moldinsight 改 `--port`
 - inventory 改 `--port`
 - 同步更新 Nginx / 防火墙 / 前端 base URL
 
@@ -125,7 +122,7 @@ 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_MOLDINSIGHT_API_BASE_URL=https://moldinsight.example.com
 VITE_INVENTORY_API_BASE_URL=https://inventory.example.com
 ```
 
@@ -136,12 +133,12 @@ VITE_INVENTORY_API_BASE_URL=https://inventory.example.com
 
 ## 6. Nginx 示例
 
-### gemold-only
+### moldinsight-only
 
 ```nginx
 server {
     listen 80;
-    server_name gemold.example.com;
+    server_name moldinsight.example.com;
 
     location / {
         proxy_pass http://127.0.0.1:8000;
@@ -177,7 +174,7 @@ server {
 如果不通过 Nginx 统一入口而是直接暴露服务端口，则应显式开放：
 
 ```bash
-# gemold
+# moldinsight
 sudo ufw allow 8000/tcp
 
 # inventory
@@ -205,6 +202,6 @@ curl http://127.0.0.1:8001/health
 
 在当前模块化架构下：
 
-- gemold 与 inventory 应视为**两个独立后端模块**
-- 端口应按模块分配，而不是继续沿用单体“一个后端一个端口”的思路
-- unified 更适合通过**组合层或网关**实现，而不是继续让历史单体入口承载全部语义
+- moldinsight 与 inventory 应视为两个独立后端模块
+- `unified` 是当前推荐部署模式，由 unified backend 提供单一后端入口
+- 端口应按模块与部署模式清晰分配；生产环境通常通过同域 Nginx / 网关统一对外暴露 80/443
diff --git a/docs/deployment/LINUX_SETUP.md b/docs/deployment/LINUX_SETUP.md
index 73ffe2a..5663700 100644
--- a/docs/deployment/LINUX_SETUP.md
+++ b/docs/deployment/LINUX_SETUP.md
@@ -6,8 +6,8 @@
 
 当前项目支持三种部署模式：
 
-- **unified**：frontend + unified backend + celery，统一对外部署（当前推荐）
-- **gemold-only**：仅部署模具分析后端
+- **unified**：frontend + unified backend + moldinsight Celery worker，统一对外部署（当前推荐）
+- **moldinsight-only**：仅部署模具分析后端
 - **inventory-only**：仅部署进销存后端
 
 项目保持：
@@ -34,10 +34,10 @@
 
 ### 按模块附加要求
 
-#### gemold / unified 需要
+#### moldinsight / unified 需要
 - 服务器上已可访问的 MinIO 或 RustFS 兼容对象存储
 - PythonOCC 运行环境
-- Celery worker（推荐与 gemold 一起部署）
+- Celery worker（推荐与 moldinsight 一起部署）
 
 #### inventory-only 需要
 - PostgreSQL
@@ -73,7 +73,7 @@ pip install --upgrade pip
 pip install -r requirements.txt
 ```
 
-> 如果需要 gemold 分析能力，请额外准备 PythonOCC 运行环境。该依赖通常通过 conda 或预构建运行镜像提供，而不是直接由 pip 安装。
+> 如果需要 moldinsight 分析能力，请额外准备 PythonOCC 运行环境。该依赖通常通过 conda 或预构建运行镜像提供，而不是直接由 pip 安装。
 
 ---
 
@@ -117,7 +117,7 @@ RUSTFS_SECRET_KEY=minioadmin
 ```
 
 说明：
-- `RUSTFS_*` 仅 **gemold / unified** 模式需要
+- `RUSTFS_*` 仅 **moldinsight / unified** 模式需要
 - `inventory-only` 可不使用对象存储
 - 当前配置读取实现见 [settings.py](../../src/shared/config/settings.py)
 
@@ -136,7 +136,7 @@ RUSTFS_SECRET_KEY=minioadmin
 相关实现参考：
 - [init_db.py](../../src/shared/database/init_db.py)
 
-> 当前项目是 **单数据库** 设计，因此 unified / gemold-only / inventory-only 都连接到同一个数据库与同一 migration head。
+> 当前项目是 **单数据库** 设计，因此 unified / moldinsight-only / inventory-only 都连接到同一个数据库与同一 migration head。
 
 ---
 
@@ -149,7 +149,7 @@ RUSTFS_SECRET_KEY=minioadmin
 - `/` → 前端静态资源与 SPA 路由
 - `/api` → unified backend
 - `/health` → unified backend
-- `/html` → unified backend（内部再提供 gemold 分析产物）
+- `/html` → unified backend（内部再提供 moldinsight 分析产物）
 
 如果使用根目录 [docker-compose.yml](../../docker-compose.yml) 的 `frontend` 服务，则该入口已经内置在前端 Nginx 镜像中。
 
@@ -168,7 +168,7 @@ uvicorn src.entrypoints.inventory:app --host 0.0.0.0 --port 8001
 
 ---
 
-## 6.2 gemold-only
+## 6.2 moldinsight-only
 
 ```bash
 source .venv/bin/activate
@@ -179,7 +179,7 @@ uvicorn src.entrypoints.moldinsight:app --host 0.0.0.0 --port 8000
 - 单独部署模具分析能力
 - 文件上传 / 分析 / 导出 / 批量分析
 
-### gemold Celery worker
+### moldinsight Celery worker
 
 建议同时启动 worker：
 
@@ -188,18 +188,19 @@ source .venv/bin/activate
 celery -A src.celery_app.celery_app worker --loglevel=info
 ```
 
-> gemold 的异步处理链路依赖 Celery + Redis；若只启动 HTTP 服务而不启动 worker，上传分析任务可能无法完整处理。
+> moldinsight 的异步处理链路依赖 Celery + Redis；若只启动 HTTP 服务而不启动 worker，上传分析任务可能无法完整处理。
 
 ---
 
 ## 6.3 unified
 
-当前仓库历史上存在过统一入口，但它更适合作为**过渡参考**，不建议再作为长期标准入口。
+`unified` 是当前推荐的默认部署方式，适合 frontend 同域反代到单一 backend 的本地开发、集成环境与统一部署场景。
 
-在正式完成组合层重构前，如需统一部署，可优先使用反向代理或部署编排层统一暴露 gemold 与 inventory；后续会演进为显式 `unified_app.py`。
+如需按模块独立部署，则使用 `moldinsight-only` 或 `inventory-only` 入口；它们仍共享同一个仓库、同一个数据库与同一套基础设施。
 
-蓝图参考：
-- [archive/BACKEND_MODULARIZATION_BLUEPRINT.md](../archive/BACKEND_MODULARIZATION_BLUEPRINT.md)
+当前入口与部署编排见：
+- [../../docker-compose.yml](../../docker-compose.yml)
+- [../../src/entrypoints/unified.py](../../src/entrypoints/unified.py)
 
 ---
 
@@ -210,7 +211,7 @@ celery -A src.celery_app.celery_app worker --loglevel=info
 创建：
 
 ```bash
-sudo nano /etc/systemd/system/gemold-inventory.service
+sudo nano /etc/systemd/system/moldinsight-inventory.service
 ```
 
 ```ini
@@ -236,18 +237,18 @@ WantedBy=multi-user.target
 
 ```bash
 sudo systemctl daemon-reload
-sudo systemctl enable gemold-inventory
-sudo systemctl start gemold-inventory
+sudo systemctl enable moldinsight-inventory
+sudo systemctl start moldinsight-inventory
 ```
 
 ---
 
-## 7.2 gemold-only API 服务
+## 7.2 moldinsight-only API 服务
 
 创建：
 
 ```bash
-sudo nano /etc/systemd/system/gemold-moldinsight.service
+sudo nano /etc/systemd/system/moldinsight-moldinsight.service
 ```
 
 ```ini
@@ -271,12 +272,12 @@ WantedBy=multi-user.target
 
 ---
 
-## 7.3 gemold Celery worker 服务
+## 7.3 moldinsight Celery worker 服务
 
 创建：
 
 ```bash
-sudo nano /etc/systemd/system/gemold-celery.service
+sudo nano /etc/systemd/system/moldinsight-celery.service
 ```
 
 ```ini
@@ -309,7 +310,7 @@ WantedBy=multi-user.target
 - `/` 提供前端静态资源与 SPA fallback
 - `/api/` 反代后端
 - `/health` 反代后端
-- `/html/` 反代 gemold
+- `/html/` 反代 moldinsight
 
 ### 8.1 inventory-only
 
@@ -328,12 +329,12 @@ server {
 }
 ```
 
-### 8.2 gemold-only
+### 8.2 moldinsight-only
 
 ```nginx
 server {
     listen 80;
-    server_name gemold.example.com;
+    server_name moldinsight.example.com;
 
     location / {
         proxy_pass http://127.0.0.1:8000;
@@ -361,7 +362,7 @@ inventory-only：
 curl http://127.0.0.1:8001/health
 ```
 
-gemold-only：
+moldinsight-only：
 
 ```bash
 curl http://127.0.0.1:8000/health
@@ -374,7 +375,7 @@ curl http://127.0.0.1:8000/health
 - `/api/products` 返回数据
 - `/api/inventory` 返回数据
 
-#### gemold-only
+#### moldinsight-only
 - 登录接口可用
 - `/api/upload` 可访问
 - 上传后 worker 能正常消费任务
@@ -388,9 +389,9 @@ curl http://127.0.0.1:8000/health
 因为当前项目已演进为模块化结构，`src.main:app` 更适合作为过渡兼容入口，而不是长期部署标准。应优先围绕 [entrypoints/](../../src/entrypoints/) 部署。
 
 ### 2. inventory-only 为什么不需要对象存储？
-因为对象存储主要服务于 gemold 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。
+因为对象存储主要服务于 moldinsight 分析产物（HTML、导出文件等）。纯 inventory 部署不需要这部分基础设施。
 
-### 3. gemold-only 为什么建议同时部署 Celery？
+### 3. moldinsight-only 为什么建议同时部署 Celery？
 因为模具分析任务通常走异步处理链路，仅启动 API 而不启动 worker，会影响上传后的任务处理。
 
 ---
diff --git a/docs/deployment/PORT_CONFIG.md b/docs/deployment/PORT_CONFIG.md
index 462cd08..44b1bf7 100644
--- a/docs/deployment/PORT_CONFIG.md
+++ b/docs/deployment/PORT_CONFIG.md
@@ -2,17 +2,15 @@
 
 > 文档定位：**模块化部署下的端口与环境变量配置补充说明**。
 > 当前部署主题入口见 [../DEPLOYMENT.md](../DEPLOYMENT.md)，详细 Linux 部署步骤见 [LINUX_SETUP.md](LINUX_SETUP.md)。
-> 本文档说明当前 geMoldInsight 在**模块化部署**下的端口配置方式。
+> 本文只补充环境变量、端口配置项与 direct run / compose 的映射；端口规划与对外暴露方式以 [DEPLOY_PORT.md](./DEPLOY_PORT.md) 为准。
 
-当前架构中应区分：
+当前配置中主要需要区分：
 
-- **gemold API 端口**
+- **moldinsight API 端口**
 - **inventory API 端口**
-- **数据库/Redis/对象存储端口**
+- **数据库 / Redis / 对象存储端口**
 - **前端访问地址**
 
-不再推荐把所有部署场景都抽象成“单应用单端口”。
-
 ---
 
 ## 1. 当前主配置位置
@@ -54,7 +52,7 @@ RUSTFS_ENDPOINT=http://localhost:9000
 |---|---|
 | `FRONTEND_PORT` | 前端 Nginx 宿主机暴露端口 |
 | `BACKEND_PORT` | unified backend 宿主机暴露端口 |
-| `MOLDINSIGHT_PORT` | gemold-only 独立部署端口 |
+| `MOLDINSIGHT_PORT` | moldinsight-only 独立部署端口 |
 | `INVENTORY_PORT` | inventory-only 独立部署端口 |
 | `DB_PORT` | PostgreSQL 端口 |
 | `REDIS_PORT` | Redis 端口 |
@@ -65,7 +63,7 @@ RUSTFS_ENDPOINT=http://localhost:9000
 
 ## 3. 推荐配置方式
 
-### 3.1 gemold-only
+### 3.1 moldinsight-only
 
 ```env
 MOLDINSIGHT_PORT=8000
@@ -92,30 +90,13 @@ REDIS_PORT=6379
 
 ---
 
-## 4. 为什么不再强调单一 `PORT` 变量
+## 4. direct run 与 Compose 的映射
 
-历史单体部署通常只有一个后端入口，因此 `PORT=8000` 足够。
+通过直接运行或 Docker Compose 部署时，端口含义保持一致，但映射方式不同。
 
-当前项目已经是：
-- gemold 独立入口
-- inventory 独立入口
-- unified 作为组合模式而非默认单体入口
+### direct run
 
-因此端口配置必须模块化：
-
-- gemold 一个端口
-- inventory 一个端口
-- 如果 unified 对外存在，可以由网关统一暴露 80/443
-
-这比继续强行把所有模式压成一个 `PORT` 更清晰，也更符合真实部署方式。
-
----
-
-## 5. 直接运行与 Compose 的区别
-
-### 直接运行
-
-gemold：
+moldinsight：
 
 ```bash
 uvicorn src.entrypoints.moldinsight:app --port 8000
@@ -131,7 +112,7 @@ uvicorn src.entrypoints.inventory:app --port 8001
 
 Compose 通过端口映射暴露服务：
 
-- gemold → `${MOLDINSIGHT_PORT}:8000`
+- moldinsight → `${MOLDINSIGHT_PORT}:8000`
 - inventory → `${INVENTORY_PORT}:8001`
 
 当前实际定义见：
@@ -139,7 +120,7 @@ Compose 通过端口映射暴露服务：
 
 ---
 
-## 6. 与前端配置的关系
+## 5. 与前端配置的关系
 
 前端是否使用 unified / split deployment，会影响前端 API 地址配置。
 
@@ -147,7 +128,7 @@ Compose 通过端口映射暴露服务：
 - 一个 API 基地址
 
 ### split
-- gemold 与 inventory 各自基地址
+- moldinsight 与 inventory 各自基地址
 
 因此，修改后端端口后，可能还需要同步：
 
@@ -157,22 +138,21 @@ Compose 通过端口映射暴露服务：
 
 ---
 
-## 7. 推荐实践
+## 6. 推荐实践
 
 1. **本地开发**
-   - gemold：8000
+   - moldinsight：8000
    - inventory：8001
 
 2. **服务器部署**
    - 外网只暴露 80/443
    - Nginx 反代到 8000 / 8001
 
-3. **不要继续把所有部署模式都写成 `src.main:app + PORT=8000`**
-   - 这已不符合当前架构
+3. 修改端口后，同步检查 `.env`、Compose 端口映射、前端环境变量与反向代理配置
 
 ---
 
-## 8. 关联文档
+## 7. 关联文档
 
 - [LINUX_SETUP.md](./LINUX_SETUP.md)
 - [DEPLOY_PORT.md](./DEPLOY_PORT.md)
diff --git a/docs/topics/storage/STORAGE_SETUP.md b/docs/topics/storage/STORAGE_SETUP.md
index 20c29df..effd29a 100644
--- a/docs/topics/storage/STORAGE_SETUP.md
+++ b/docs/topics/storage/STORAGE_SETUP.md
@@ -25,7 +25,7 @@
 
 ```text
 ┌─────────────────────────────────────────────────────────────┐
-│                  应用层 (gemold / inventory)                │
+│                  应用层 (moldinsight / inventory)            │
 └──────────────────────┬──────────────────────────────────────┘
                        │
         ┌──────────────┴──────────────┐
@@ -50,7 +50,7 @@
 - `users` - 用户信息
 - `roles` / `permissions` - 权限体系
 
-### gemold 相关
+### moldinsight 相关
 - `stp_files` - STP 文件元数据
 - `html_files` - HTML 报告元数据
 - `geometry_data` - 几何分析数据