# FF AI Workspace Backend API > FF AI Workspace 平台后端 API 服务 > > 基于 NestJS + Prisma + PostgreSQL --- ## 📋 目录结构 ``` backend/ ├── src/ # 源代码 │ ├── core/ # 🏗️ 核心基础设施 │ │ ├── auth/ # 认证与授权 │ │ ├── database/ # 数据库（Prisma） │ │ ├── messaging/ # 消息通知 │ │ ├── observability/ # 可观测性（日志、审计、监控） │ │ └── workflow/ # 工作流引擎（Temporal） │ │ │ ├── engines/ # ⚙️ 可重用引擎 │ │ ├── approval/ # 审批引擎 │ │ └── form/ # 表单引擎 │ │ │ ├── modules/ # 📦 业务模块 │ │ ├── organization/ # 组织架构 │ │ ├── parts/ # 零件库存 │ │ ├── work-records/ # 工时记录 │ │ ├── feedback/ # 用户反馈 │ │ ├── ai-assistant/ # AI 助手 │ │ └── ... │ │ │ ├── common/ # 🔧 共享代码 │ │ ├── decorators/ # 装饰器 │ │ ├── guards/ # 守卫 │ │ ├── interceptors/ # 拦截器 │ │ ├── filters/ # 异常过滤器 │ │ └── utils/ # 工具函数 │ │ │ ├── app.module.ts # 根模块 │ └── main.ts # 应用入口 │ ├── prisma/ # Prisma ORM │ ├── schema/ # 数据库模型（多文件） │ │ ├── base.prisma # Generator & Datasource │ │ ├── platform_*.prisma # 平台级 schema │ │ ├── corp_*.prisma # 企业级 schema │ │ └── mfg_*.prisma # 制造业 schema │ ├── migrations/ # 数据库迁移 │ └── seeds/ # 种子数据 │ ├── dist/ # 编译输出 └── node_modules/ # 依赖包 ``` **架构说明**： - **core**: 基础设施层，提供通用能力 - **engines**: 可重用的业务引擎 - **modules**: 具体的业务模块 - **common**: 跨模块共享的代码 --- ## 🚀 快速开始 ### 1. 安装依赖 ```bash cd backend npm install ``` ### 2. 配置环境变量 ```bash # 复制环境变量模板 cp .env.dev.example .env # 编辑环境变量 vim .env ``` **必需的环境变量**: - `DATABASE_URL` - PostgreSQL 连接字符串 - `JWT_SECRET` - JWT 密钥 - `REDIS_HOST` / `REDIS_PORT` - Redis 配置 详细说明查看 [环境配置指南](../docs/setup/development-env-setup.md) ### 3. 初始化数据库 ```bash # 生成 Prisma Client npm run prisma:generate # 推送数据库结构（开发环境） npm run db:push # 或运行迁移（生产环境） npm run prisma:migrate # 初始化权限数据 npm run init:permissions # 创建管理员用户 npm run init:itadmin ``` ### 4. 启动服务 ```bash # 开发模式（自动重启） npm run start:dev # 生产模式 npm run start:prod ``` 服务将运行在 `http://localhost:3001` --- ## 📖 npm scripts ### 开发 ```bash npm run start:dev # 开发模式（监听文件变化） npm run build # 构建生产版本 npm run start:prod # 运行生产版本 ``` ### 数据库 ```bash npm run prisma:generate # 生成 Prisma Client npm run prisma:migrate # 运行数据库迁移 npm run prisma:studio # 打开 Prisma Studio npm run db:push # 推送 schema 到数据库（开发） npm run db:push:force # 强制推送（首次初始化） npm run db:seed # 填充种子数据 npm run db:reset # 重置数据库 ``` ### 初始化脚本 ```bash npm run init:permissions # 初始化权限数据 npm run init:itadmin # 创建 IT 管理员用户 npm run init:work-record-roles # 初始化工时记录角色 ``` ### 测试（统一入口） ```bash cd testing npm run test:backend # 运行后端测试 npm run test:backend:e2e # 运行后端 E2E 测试 npm run test:backend:all:cov # 覆盖率 ``` ### 代码质量 ```bash npm run lint # 运行 ESLint npm run format # 格式化代码（Prettier） ``` --- ## 🗄️ 数据库 ### Prisma 多文件架构 本项目使用 Prisma 原生多文件支持（v6.7.0+）： ``` prisma/schema/ ├── base.prisma # Generator & Datasource ├── platform_iam.prisma # 用户、角色、权限 ├── corp_hr.prisma # 组织架构 ├── mfg_inventory.prisma # 零件库存 ├── approval_engine.prisma # 审批引擎 ├── form_engine.prisma # 表单引擎 └── ... # 其他业务域 ``` **重要规则：** - ✅ 每个 model 必须有 `@@schema("schema_name")` - ✅ 无需手动合并，Prisma 自动处理 - ✅ 每个业务域独立文件 详细说明查看 [数据库规范入口](../docs/standards/06-database/README.md) ### 数据库迁移 ```bash # 开发环境（首次） npm run db:push:force npm run prisma:generate # 开发环境（日常） npm run db:push # 生产环境（创建迁移） npm run prisma:migrate:create -- --name migration_name npm run prisma:migrate # 重置数据库 npm run db:reset ``` --- ## 🔐 认证与权限 ### 认证方式 - **JWT Token**: 基于 JWT 的身份认证 - **LDAP/Entra ID**: 企业目录集成 - **邮箱登录**: 邮箱+密码登录 ### 权限系统 - **RBAC**: 基于角色的访问控制 - **PBAC**: 基于权限的访问控制 - **动态权限**: 运行时权限检查 **使用装饰器：** ```typescript @RequirePermissions('users:read') @Get() findAll() { ... } ``` --- ## 📚 相关文档 ### 环境配置 - [开发环境配置](../docs/setup/development-env-setup.md) - 环境变量详细说明 - [数据库规范入口](../docs/standards/06-database/README.md) - 数据库配置指南 ### 业务模块 - [零件库存系统](../docs/modules/parts/) - Parts 模块文档 - [组织架构](../docs/modules/organization/) - Organization 模块文档 - [用户反馈](../docs/modules/feedback/) - Feedback 模块文档 - [AI 助手](../docs/modules/ai-assistant/) - AI Assistant 模块文档 ### 引擎系统 - [审批引擎](../docs/modules/approval-engine/) - Approval Engine 文档 - [表单引擎](../docs/modules/form-engine/) - Form Engine 文档 ### 基础设施 - [审计系统](../docs/modules/audit-system/) - Audit System 文档 - [日志系统](../docs/modules/logging-system/) - Logging System 文档 - [通知引擎](../docs/modules/notification-engine/) - Notification Engine 文档 ### 开发指南 - [前端规范入口](../docs/standards/04-frontend/README.md) - [后端规范入口](../docs/standards/05-backend/README.md) --- ## 🔧 常见问题 ### 1. Prisma Client 未生成 ```bash npm run prisma:generate ``` ### 2. 数据库连接失败 检查 `DATABASE_URL` 环境变量和 Docker 服务状态： ```bash # 查看 Docker 容器 docker ps # 检查 PostgreSQL docker logs ffoa-postgres ``` ### 3. 端口被占用 ```bash # 查找占用 3001 端口的进程 lsof -ti:3001 # 杀死进程 kill -9 $(lsof -ti:3001) ``` ### 4. TypeScript 编译错误 ```bash # 清理编译缓存 rm -rf dist/ rm -f tsconfig.build.tsbuildinfo # 重新编译 npm run build ``` --- ## 🏗️ 技术栈 - **框架**: NestJS 10.x - **语言**: TypeScript 5.x - **数据库**: PostgreSQL 16 - **ORM**: Prisma 6.x - **缓存**: Redis 7.x - **工作流**: Temporal - **认证**: Passport + JWT - **验证**: class-validator - **文档**: Swagger/OpenAPI --- ## 📦 主要依赖 ```json { "@nestjs/core": "^10.0.0", "@nestjs/common": "^10.0.0", "@nestjs/jwt": "^10.0.0", "@prisma/client": "^6.7.0", "passport": "^0.7.0", "class-validator": "^0.14.0" } ``` --- ## 🔗 API 文档 启动服务后访问： - **Swagger UI**: `http://localhost:3001/api/docs` - **API JSON**: `http://localhost:3001/api/docs-json` - **健康检查**: `http://localhost:3001/api/v1/health` --- ## 📝 开发规范 ### 代码风格 - 使用 ESLint + Prettier - 遵循 Airbnb TypeScript 规范 - 提交前运行 lint 和 format ### 提交规范 ```bash # 格式 (): # 示例 feat(auth): add LDAP authentication fix(parts): fix inventory count bug docs(readme): update installation guide ``` ### API 规范 - 统一使用 `/api/v1` 前缀 - 使用 RESTful 风格 - 返回统一的响应格式 - 详见 [后端规范入口](../docs/standards/05-backend/README.md) --- ## 🆘 获取帮助 - **文档中心**: [../docs/README.md](../docs/README.md) - **问题反馈**: 创建 GitHub Issue - **开发指南**: [../scripts/README.md](../scripts/README.md) --- ## 📄 许可证 私有项目 - FF AI Workspace 团队所有 --- **最后更新**: 2025-12-25 **维护者**: FF AI Workspace 开发团队