快速上手 - OpenECP

安装说明

OpenECP（Enterprise Collaboration Platform）是一款面向制造业的开源工程协作平台，提供了完整的前端与后端一体化解决方案，覆盖产品设计、工艺规划、协作管理全流程。本平台基于微服务架构设计，支持分布式部署，可灵活适配中小企业到大型企业的不同应用场景。通过以下标准化步骤，您可快速完成环境搭建、依赖安装与项目运行，即刻开启工程协作数字化转型。

安装前请确保您已完成基础环境的预检：确认操作系统版本（推荐Linux/Ubuntu 20.04+ 或 Windows 10/11）、网络通畅（需拉取依赖包与镜像）、磁盘空间充足（建议预留至少10GB），并具备基础的命令行操作能力。对于企业级部署，建议提前规划服务器架构（如前端、后端、数据库分离部署），并配置防火墙与安全组策略。

技术栈

技术栈	版本要求	核心优势
Python	3.8+	兼容最新语法特性，长期支持（LTS），生态丰富
FastAPI	最新稳定版	高性能异步API，自带Swagger文档，类型注解支持
SQLAlchemy	最新稳定版	强大ORM框架，多数据库适配，简化数据操作
PostgreSQL	12+	企业级数据库，JSON/几何类型支持优异
Redis	6.x+	高性能缓存，支撑实时协作场景
React	18.2.0	并发渲染，自动批处理，复杂交互性能优异
Three.js	0.178.0	WebGL三维可视化，满足工程模型预览需求
Antd	5.26.2	企业级UI组件，交互体验统一，开发效率高

项目结构

backendV7/ # 后端主目录，包含所有服务端代码与配置
├── app/ # 主要应用代码，遵循模块化设计原则，按功能维度拆分
│ ├── crud/ # 数据库操作层（增删改查），封装所有数据库交互逻辑，与路由层解耦
│ │ ├── base.py # 通用CRUD基类，提供基础的增删改查方法，减少重复代码
│ │ ├── product.py # 产品模块专属CRUD方法
│ │ └── process.py # 工艺模块专属CRUD方法
│ ├── models/ # 数据库模型层，定义数据表结构与关联关系
│ │ ├── base.py # 模型基类，包含通用字段（如创建时间、更新时间、主键）
│ │ ├── product.py # 产品相关数据表模型
│ │ └── process.py # 工艺相关数据表模型
│ ├── routers/ # API路由层，定义接口路径、请求方法、权限校验
│ │ ├── api.py # 路由汇总文件，统一注册所有子路由
│ │ ├── product.py # 产品模块接口路由
│ │ └── process.py # 工艺模块接口路由
│ ├── schemas/ # 数据模型定义层，用于接口参数验证与序列化
│ │ ├── product.py # 产品模块数据结构（请求/响应模型）
│ │ └── process.py # 工艺模块数据结构（请求/响应模型）
│ ├── utils/ # 工具函数层，提供通用功能支持
│ │ ├── auth.py # 认证相关工具（JWT生成/验证、密码加密）
│ │ ├── logger.py # 日志配置与封装
│ │ └── file.py # 文件上传/下载/解析工具
│ └── database/ # 数据库配置层，管理数据库连接与会话
│ ├── base.py # 数据库连接配置
│ └── session.py # 数据库会话管理
├── docs/ # 文档目录，包含接口文档、部署文档、使用手册
├── tests/ # 测试代码目录，遵循单元测试/集成测试规范
│ ├── unit/ # 单元测试用例
│ └── integration/ # 集成测试用例
├── start_service.sh # 启动脚本，封装启动命令、环境变量配置，支持生产环境快速部署
└── requirements.txt # 依赖列表，按功能分组管理第三方库，标注版本号确保环境一致性

已实现的API模块

核心功能模块

三维设计模型管理：支持STEP/IGES/STL等主流三维模型格式的上传、解析、预览与版本管理；提供模型轻量化处理接口，降低前端加载压力；支持模型属性提取（如尺寸、材质、体积），满足工程分析需求。优势：兼容多格式、轻量化预览、属性自动提取，提升模型管理效率。
装配体管理：实现装配体层级结构解析、零部件关联管理、装配关系定义；支持装配体的拆解与重组，提供零部件替换、版本追溯接口；支持装配体BOM自动生成。优势：可视化层级管理、装配关系智能解析，减少人工维护成本。
PMI（产品制造信息）管理：解析并存储模型中的PMI信息（尺寸公差、几何公差、表面粗糙度等）；提供PMI信息的增删改查、批量导入导出接口；支持PMI与工艺路线的关联映射。优势：标准化PMI数据存储，打通设计与工艺的数据壁垒。
工艺集成：对接CAD/CAPP系统，实现设计数据到工艺数据的自动流转；提供工艺卡片生成、工艺路线编辑、工艺参数配置接口；支持工艺文档的版本管理与审批流程。优势：设计工艺一体化，减少数据重复录入，提升工艺编制效率。
特征定义与映射：支持自定义工程特征（如孔、槽、螺纹）；提供特征库管理、特征参数配置接口；实现设计特征到工艺特征的自动映射，支撑智能工艺规划。优势：特征标准化，为智能工艺推荐提供数据基础。

产品管理模块

产品分类管理：支持多级产品分类体系（如按行业、类型、规格）；提供分类的增删改查、排序、启用/禁用接口；支持分类模板自定义，适配不同企业的分类规范。优势：灵活的分类体系，支持企业个性化配置，提升产品检索效率。
产品信息管理：管理产品基础信息（名称、型号、规格、描述、图片等）；提供产品信息的批量导入导出、模糊查询、高级筛选接口；支持产品状态（设计中/已发布/已下架）管理。优势：标准化信息管理，多维度检索，提升产品数据治理能力。
产品版本管理：记录产品的版本迭代历史，支持版本对比、版本回滚；提供版本号自动生成（如语义化版本）、版本备注、版本审批接口；支持多版本并行管理。优势：全流程版本追溯，避免版本混乱，满足产品迭代管理需求。
产品参数管理：管理产品的技术参数、性能参数、检验参数等；支持参数模板自定义、参数批量赋值、参数对比接口；提供参数单位标准化管理。优势：参数结构化存储，支持多维度对比分析，提升产品选型效率。
产品BOM管理：管理产品的物料清单（EBOM/MBOM/PBOM）；提供BOM层级编辑、BOM对比、BOM批量导入导出接口；支持BOM与工艺路线的关联。优势：多类型BOM统一管理，层级可视化，打通产品与生产的数据链路。

工艺规划模块

工艺模板管理：支持工艺模板的创建、编辑、复制、删除；提供模板分类管理、模板参数配置、模板版本控制接口；支持模板快速套用生成工艺文件。优势：标准化工艺模板，减少重复编制工作，提升工艺规范性。
工艺路线规划：管理产品的加工工序、工序顺序、工序参数；提供工艺路线的可视化编辑、工序拆分/合并、工序校验接口；支持工艺路线与设备、人员的关联。优势：可视化路线规划，工序逻辑校验，降低工艺编制错误率。
工艺参数配置：管理各工序的加工参数（如切削速度、进给量、切削深度）；提供参数范围校验、参数优化建议、参数批量调整接口；支持参数与设备型号的关联适配。优势：参数标准化配置，结合工艺知识库提供优化建议，提升加工质量。
工艺资源管理：管理工艺所需的设备、刀具、夹具、量具等资源；提供资源台账管理、资源状态监控、资源占用调度接口；支持资源与工艺路线的关联匹配。优势：资源统一管理，避免资源冲突，提升生产资源利用率。
工艺BOM管理：基于产品BOM生成工艺BOM（PBOM）；提供PBOM的编辑、对比、版本管理接口；支持PBOM与工艺路线、资源的关联。优势：PBOM与产品BOM联动更新，确保物料与工艺的一致性。

协作与版本控制

特征定义管理：支持协作场景下的特征库共享、特征权限管理；提供特征修改记录、特征审核、特征发布接口；支持多用户协同编辑特征库。优势：特征库协同管理，权限精细化控制，提升团队协作效率。
推荐模型管理：管理智能推荐算法的模型参数、训练数据、推荐规则；提供模型训练、模型测试、模型上线/下线接口；支持推荐效果统计分析。优势：推荐模型全生命周期管理，可量化推荐效果，持续优化推荐精度。
特征值映射：支持多系统间特征值的自动映射与转换；提供映射规则配置、映射校验、映射日志接口；支持自定义映射模板。优势：跨系统特征值统一，减少人工转换成本，提升数据互通性。
推荐日志记录：记录推荐模型的调用记录、推荐结果、用户反馈；提供日志查询、日志分析、日志导出接口；支持基于日志优化推荐规则。优势：全链路日志追溯，基于用户反馈持续迭代推荐模型，提升推荐精准度。

智能推荐系统

编辑会话管理：管理多用户协同编辑的会话信息；提供会话创建、会话加入/退出、会话状态同步接口；支持会话超时自动清理。优势：会话级别的协同管理，确保多用户操作的一致性，避免冲突。
区域锁定机制：支持对模型/文档的指定区域进行锁定编辑；提供锁定申请、锁定释放、锁定超时提醒接口；支持锁定权限分级管理。优势：精细化区域锁定，避免多用户同时编辑同一区域，减少冲突。
操作提交与冲突检测：管理用户操作的提交、合并、冲突解决；提供操作日志记录、冲突自动检测、冲突可视化对比接口；支持手动/自动冲突解决。优势：实时冲突检测，可视化冲突解决，保障协同编辑的数据一致性。
版本历史与回滚：记录协同编辑的版本历史，支持版本快照、版本对比、版本回滚；提供版本备注、版本审批、版本清理接口；支持多版本并行编辑与合并。优势：全版本追溯，灵活回滚，满足协同编辑的版本管理需求。

系统管理

用户活动日志：记录用户的登录、操作、退出等行为；提供日志查询、日志过滤、日志导出、日志审计接口；支持异常行为告警（如多次登录失败、敏感操作）。优势：全维度行为审计，满足合规要求，便于问题追溯与安全管控。
系统通知：管理系统级、业务级通知（如审批提醒、任务提醒、异常提醒）；提供通知创建、推送、已读/未读管理、通知设置接口；支持多渠道推送（站内信、邮件、短信）。优势：多维度通知体系，确保重要信息及时触达，提升协作效率。
配置管理：管理系统的基础配置（如端口、域名、存储路径）、业务配置（如审批流程、权限规则）、第三方配置（如API密钥、回调地址）；提供配置项的增删改查、配置生效、配置备份/恢复接口；支持配置权限分级管理。优势：配置可视化管理，无需修改代码即可调整系统行为，提升运维效率。

安装与运行

1 环境要求

Node.js 14.0 或以上版本：前端工程构建与运行的基础环境，建议使用16.x LTS版本，通过nvm/nvm-windows管理多版本Node.js
Java Development Kit (JDK) 8 或以上版本：部分第三方工具（如CAD文件解析组件）依赖JDK，建议使用JDK 8或11 LTS版本
MySQL 5.7 或以上版本：可选备用数据库（默认使用PostgreSQL），用于适配已有MySQL生态的企业场景，需开启InnoDB引擎
Python 3.8+：后端运行核心环境，推荐3.9.x LTS版本，建议通过虚拟环境（venv/conda）隔离项目依赖
PostgreSQL 12+：主数据库，推荐14.x版本，需提前创建数据库实例并配置远程访问权限（如需分布式部署）
Redis (可选，用于协作功能)：推荐6.x版本，需配置持久化策略（RDB/AOF），确保协作数据不丢失

2 安装依赖

安装前建议先创建并激活Python虚拟环境，避免全局依赖冲突：

# 创建虚拟环境（Linux/Mac）
python -m venv venv
# 激活虚拟环境（Linux/Mac）
source venv/bin/activate
# 激活虚拟环境（Windows）
venv\Scripts\activate
# 安装基础依赖
pip install -r requirements.txt
# 可选：安装生产环境优化依赖
pip install gunicorn uvloop httptools
# 前端依赖安装（进入前端目录）
cd frontend && npm install --registry=https://registry.npmmirror.com

注意事项：

国内用户建议使用清华/阿里云PyPI镜像加速依赖安装：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
若安装过程中出现编译错误（如psycopg2），需提前安装系统依赖：apt install libpq-dev python3-dev（Linux）或下载预编译包（Windows）
前端依赖安装建议使用国内npm镜像，提升安装速度与稳定性

3 运行应用

开发环境运行

# 后端开发模式（自动重载，适合开发调试）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
# 前端开发模式（热更新）
cd frontend && npm run dev

生产环境运行

# 后端生产模式（使用gunicorn，多进程运行）
gunicorn -c start_service.sh app.main:app
# 前端打包部署
cd frontend && npm run build
# 将dist目录部署至Nginx/Apache等Web服务器

start_service.sh 配置说明：

workers：进程数，建议设置为 CPU核心数 * 2 + 1
worker_class：工作模式，推荐使用uvloop（异步）
bind：绑定地址与端口，建议使用127.0.0.1:8000（配合Nginx反向代理）
timeout：请求超时时间，建议设置为60s（适配大文件上传场景）
accesslog/errorlog：日志路径，建议配置为绝对路径，便于日志收集

运行验证：

后端启动成功后，访问 http://localhost:8000/docs 可查看自动生成的Swagger接口文档
前端启动成功后，访问 http://localhost:3000 可进入平台前端界面
生产环境部署后，建议配置Nginx反向代理，实现前后端接口转发、静态资源缓存、HTTPS配置

数据库配置

项目采用SQLAlchemy的ORM模式管理数据库，支持多数据库适配，核心配置通过环境变量文件（.env）管理，避免硬编码敏感信息。

# 核心配置文件：.env（项目根目录）
# 主数据库（PostgreSQL）配置
DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
# 数据库连接池配置（生产环境建议调整）
DATABASE_POOL_SIZE=10
DATABASE_MAX_OVERFLOW=20
DATABASE_POOL_RECYCLE=3600
# Redis配置（协作功能）
REDIS_URL="redis://:password@localhost:6379/0"
# 可选：MySQL备用数据库配置
MYSQL_DATABASE_URL="mysql+pymysql://user:password@localhost:3306/dbname?charset=utf8mb4"

配置项说明：

DATABASE_URL：PostgreSQL连接字符串，格式为 postgresql://用户名:密码@主机:端口/数据库名，需提前创建数据库（建议字符集为UTF8）
DATABASE_POOL_SIZE：数据库连接池大小，默认10，生产环境可根据并发量调整（建议不超过20）
DATABASE_MAX_OVERFLOW：连接池最大溢出数，超出连接池大小的临时连接数，默认20
DATABASE_POOL_RECYCLE：连接回收时间（秒），默认3600，避免长连接占用资源
REDIS_URL：Redis连接字符串，若Redis设置密码，格式为 redis://:密码@主机:端口/数据库编号

数据库初始化：

# 执行数据库迁移（创建表结构）
alembic upgrade head
# 初始化基础数据（如默认管理员、基础分类）
python app/init_data.py

数据库维护建议：

定期备份数据库：PostgreSQL可使用 pg_dump 工具，MySQL可使用 mysqldump 工具
生产环境开启数据库慢查询日志，优化慢SQL
针对大表（如模型文件、日志表）建立合适的索引，提升查询效率
定期清理过期数据（如日志、临时文件），避免数据库膨胀

注意：详细的安装和使用说明请参考完整文档。企业级部署建议结合Docker/K8s实现容器化部署，提升环境一致性与运维效率；生产环境需配置HTTPS、防火墙、数据备份策略，确保系统安全与数据可靠。

在线文档 OpenECP 快速上手指南