Initial commit: ERP system with advance verification fixes

系统架构设计.md

@@ -0,0 +1,414 @@
+# 跨平台ERP系统架构设计
+
+## 1. 技术栈选择
+
+### 1.1 前端技术栈
+- **框架**: React + TypeScript
+- **PWA实现**: Workbox + Service Worker
+- **状态管理**: Redux Toolkit
+- **UI组件库**: Ant Design
+- **路由**: React Router
+- **HTTP客户端**: Axios
+- **表单处理**: Formik + Yup
+- **图表库**: ECharts
+- **国际化**: i18next
+
+### 1.2 后端技术栈
+- **语言**: Node.js (TypeScript)
+- **框架**: NestJS
+- **ORM**: TypeORM
+- **认证**: JWT + Passport
+- **缓存**: Redis
+- **日志**: Winston
+- **API文档**: Swagger
+
+### 1.3 数据库
+- **主数据库**: PostgreSQL
+- **缓存数据库**: Redis
+
+### 1.4 部署与DevOps
+- **容器化**: Docker + Docker Compose
+- **CI/CD**: GitHub Actions
+- **监控**: Prometheus + Grafana
+
+## 2. 系统架构设计
+
+### 2.1 前端架构
+
+#### 2.1.1 PWA架构
+- **核心特性**:
+  - 离线访问能力
+  - 可安装到主屏幕
+  - 推送通知
+  - 响应式设计
+
+#### 2.1.2 前端目录结构
+```
+/src
+  /assets            # 静态资源
+  /components        # 通用组件
+  /pages             # 页面组件
+  /services          # API服务
+  /store             # Redux状态管理
+  /utils             # 工具函数
+  /hooks             # 自定义Hooks
+  /types             # TypeScript类型定义
+  /workers           # Web Workers
+  /config            # 配置文件
+  App.tsx            # 应用入口
+  main.tsx           # 主渲染文件
+  service-worker.js  # Service Worker
+  manifest.json      # PWA配置
+```
+
+### 2.2 后端架构
+
+#### 2.2.1 分层架构
+- **API层**: 处理HTTP请求和响应
+- **业务逻辑层**: 实现核心业务逻辑
+- **数据访问层**: 与数据库交互
+- **基础设施层**: 提供通用功能
+
+#### 2.2.2 后端目录结构
+```
+/src
+  /modules
+    /auth            # 认证模块
+    /users           # 用户模块
+    /customers       # 客户模块
+    /suppliers       # 供应商模块
+    /subcontractors  # 分包商模块
+    /projects        # 项目模块
+    /finance         # 财务模块
+    /construction    # 施工模块
+    /exchange        # 汇率模块
+    /products        # 商品模块
+    /quotations      # 预算报价模块
+  /common
+    /filters         # 数据过滤器
+    /guards          # 守卫
+    /interceptors    # 拦截器
+    /pipes           # 管道
+    /decorators      # 装饰器
+  /config            # 配置文件
+  /utils             # 工具函数
+  /database          # 数据库配置
+  main.ts            # 应用入口
+  app.module.ts      # 根模块
+```
+
+### 2.3 数据库设计
+
+#### 2.3.1 核心数据模型
+
+**用户表 (users)**
+- id: UUID (主键)
+- username: string (用户名)
+- password: string (密码哈希)
+- name: string (姓名)
+- email: string (邮箱)
+- role: string (角色)
+- created_at: timestamp
+- updated_at: timestamp
+
+**角色表 (roles)**
+- id: UUID (主键)
+- name: string (角色名称)
+- description: string (角色描述)
+- created_at: timestamp
+- updated_at: timestamp
+
+**权限表 (permissions)**
+- id: UUID (主键)
+- name: string (权限名称)
+- description: string (权限描述)
+- created_at: timestamp
+- updated_at: timestamp
+
+**角色权限关联表 (role_permissions)**
+- role_id: UUID (外键)
+- permission_id: UUID (外键)
+
+**客户表 (customers)**
+- id: UUID (主键)
+- name: string (客户名称)
+- contact_person: string (联系人)
+- phone: string (电话)
+- email: string (邮箱)
+- address: string (地址)
+- created_at: timestamp
+- updated_at: timestamp
+
+**供应商表 (suppliers)**
+- id: UUID (主键)
+- name: string (供应商名称)
+- contact_person: string (联系人)
+- phone: string (电话)
+- email: string (邮箱)
+- address: string (地址)
+- type: string (类型: 本地/中国)
+- created_at: timestamp
+- updated_at: timestamp
+
+**分包商表 (subcontractors)**
+- id: UUID (主键)
+- name: string (分包商名称)
+- contact_person: string (联系人)
+- phone: string (电话)
+- email: string (邮箱)
+- address: string (地址)
+- created_at: timestamp
+- updated_at: timestamp
+
+**项目表 (projects)**
+- id: UUID (主键)
+- name: string (项目名称)
+- customer_id: UUID (外键)
+- contract_number: string (合同编号)
+- contract_amount: decimal (合同金额)
+- currency: string (币种)
+- start_date: date (开始日期)
+- end_date: date (结束日期)
+- status: string (状态)
+- payment_terms: jsonb (付款节点)
+- created_at: timestamp
+- updated_at: timestamp
+
+**分包表 (subcontracts)**
+- id: UUID (主键)
+- project_id: UUID (外键)
+- subcontractor_id: UUID (外键)
+- contract_number: string (合同编号)
+- contract_amount: decimal (合同金额)
+- currency: string (币种)
+- payment_terms: jsonb (付款节点)
+- status: string (状态)
+- created_at: timestamp
+- updated_at: timestamp
+
+**采购表 (purchases)**
+- id: UUID (主键)
+- project_id: UUID (外键)
+- supplier_id: UUID (外键)
+- contract_number: string (合同编号)
+- total_amount: decimal (总金额)
+- currency: string (币种)
+- expected_delivery_date: date (预计发货日期)
+- payment_terms: jsonb (付款节点)
+- status: string (状态)
+- created_at: timestamp
+- updated_at: timestamp
+
+**采购商品表 (purchase_items)**
+- id: UUID (主键)
+- purchase_id: UUID (外键)
+- product_id: UUID (外键)
+- quantity: decimal (数量)
+- unit_price: decimal (单价)
+- total_price: decimal (总价)
+
+**财务记录表 (financial_records)**
+- id: UUID (主键)
+- type: string (类型: 收入/支出)
+- amount: decimal (金额)
+- currency: string (币种)
+- rmb_equivalent: decimal (人民币等价金额)
+- project_id: UUID (外键, 可为空)
+- related_id: UUID (外键, 关联具体业务)
+- related_type: string (关联类型)
+- status: string (状态)
+- created_at: timestamp
+- updated_at: timestamp
+
+**汇率表 (exchange_rates)**
+- id: UUID (主键)
+- currency: string (币种)
+- rate: decimal (汇率)
+- reverse_rate: decimal (反向汇率)
+- effective_date: date (生效日期)
+- created_at: timestamp
+- updated_at: timestamp
+
+**商品表 (products)**
+- id: UUID (主键)
+- name: string (商品名称)
+- category_id: UUID (外键)
+- unit: string (单位)
+- cost_price: decimal (成本价)
+- created_at: timestamp
+- updated_at: timestamp
+
+**商品分类表 (product_categories)**
+- id: UUID (主键)
+- name: string (分类名称)
+- parent_id: UUID (外键, 可为空)
+- created_at: timestamp
+- updated_at: timestamp
+
+**预算报价表 (quotations)**
+- id: UUID (主键)
+- customer_id: UUID (外键)
+- project_name: string (项目名称)
+- total_amount: decimal (总金额)
+- currency: string (币种)
+- status: string (状态)
+- created_at: timestamp
+- updated_at: timestamp
+
+**预算报价项目表 (quotation_items)**
+- id: UUID (主键)
+- quotation_id: UUID (外键)
+- product_id: UUID (外键)
+- quantity: decimal (数量)
+- unit_price: decimal (单价)
+- total_price: decimal (总价)
+
+### 2.4 安全架构
+
+#### 2.4.1 认证系统
+- **JWT认证**: 使用JSON Web Token进行身份验证
+- **密码加密**: 使用bcrypt进行密码哈希
+- **会话管理**: 基于Token的无状态会话
+
+#### 2.4.2 授权系统
+- **基于角色的访问控制 (RBAC)**: 角色分配权限，用户分配角色
+- **权限粒度**: 模块级和操作级权限控制
+- **动态权限管理**: 支持后台配置权限和流程节点
+
+## 3. API接口规范
+
+### 3.1 RESTful API设计
+- **基础URL**: `/api/v1`
+- **HTTP方法**: GET, POST, PUT, PATCH, DELETE
+- **资源命名**: 复数形式，使用小写字母和连字符
+- **版本控制**: 通过URL路径进行版本控制
+
+### 3.2 响应格式
+```json
+{
+  "success": true,
+  "data": {},
+  "message": "操作成功",
+  "errors": []
+}
+```
+
+### 3.3 错误处理
+- **400 Bad Request**: 请求参数错误
+- **401 Unauthorized**: 未授权
+- **403 Forbidden**: 禁止访问
+- **404 Not Found**: 资源不存在
+- **500 Internal Server Error**: 服务器内部错误
+
+### 3.4 分页规范
+```json
+{
+  "success": true,
+  "data": {
+    "items": [],
+    "pagination": {
+      "total": 100,
+      "page": 1,
+      "pageSize": 10,
+      "totalPages": 10
+    }
+  }
+}
+```
+
+## 4. 财务串通管理设计
+
+### 4.1 核心功能
+- **统一财务视图**: 所有收入支出既能从单个项目查看，又能从公司总账目中查看
+- **数据一致性**: 确保财务数据在不同视图中的一致性
+- **多币种支持**: 支持人民币、老挝基普、泰铢、美元的汇率换算
+- **财务流程**: 预支、报销、核销流程的完整实现
+
+### 4.2 实现方案
+- **财务记录中心化**: 所有财务交易通过统一的财务记录表进行管理
+- **关联关系**: 通过related_id和related_type字段关联具体业务
+- **项目维度**: 通过project_id字段实现项目级财务视图
+- **公司维度**: 不设置project_id的记录为公司级财务
+- **汇率换算**: 实时根据汇率表进行币种换算
+
+## 5. 权限管理功能设计
+
+### 5.1 角色设计
+- **超级管理员**: 拥有所有权限
+- **管理员**: 拥有大部分管理权限
+- **财务人员**: 拥有财务管理权限
+- **项目经理**: 拥有项目管理权限
+- **采购人员**: 拥有采购管理权限
+- **施工人员**: 拥有施工管理权限
+
+### 5.2 权限设计
+- **用户管理**: 创建、编辑、删除用户
+- **角色管理**: 创建、编辑、删除角色
+- **权限管理**: 分配和管理权限
+- **客户管理**: 创建、编辑、删除客户
+- **供应商管理**: 创建、编辑、删除供应商
+- **分包商管理**: 创建、编辑、删除分包商
+- **项目管理**: 创建、编辑、删除项目
+- **财务管理**: 处理财务流程
+- **施工管理**: 管理施工过程
+- **汇率管理**: 设置和管理汇率
+- **商品管理**: 创建、编辑、删除商品
+- **预算报价管理**: 创建、编辑、删除预算报价
+
+### 5.3 流程节点管理
+- **可配置流程**: 支持在后台配置审批流程节点
+- **流程状态**: 待审批、审批中、已批准、已拒绝
+- **通知机制**: 流程状态变更时发送通知
+
+## 6. 系统集成与扩展性
+
+### 6.1 预留接口
+- **小工具接口**: 支持集成电工计算器等小工具
+- **进销存系统接口**: 预留与后续进销存系统的集成接口
+- **第三方服务接口**: 支持集成支付、物流等第三方服务
+
+### 6.2 扩展性设计
+- **模块化架构**: 各功能模块独立设计，便于扩展
+- **插件机制**: 支持插件式功能扩展
+- **API版本控制**: 确保接口变更的向后兼容性
+
+## 7. 性能优化策略
+
+### 7.1 前端优化
+- **代码分割**: 按需加载模块
+- **缓存策略**: 合理使用浏览器缓存
+- **图片优化**: 压缩和懒加载图片
+- **PWA缓存**: 使用Service Worker缓存静态资源
+
+### 7.2 后端优化
+- **数据库索引**: 合理创建数据库索引
+- **查询优化**: 优化SQL查询
+- **缓存机制**: 使用Redis缓存热点数据
+- **异步处理**: 非关键操作使用异步处理
+
+### 7.3 系统监控
+- **性能监控**: 监控系统响应时间和资源使用
+- **错误监控**: 实时捕获和分析错误
+- **日志管理**: 集中管理系统日志
+
+## 8. 部署方案
+
+### 8.1 本地开发环境
+- **Docker Compose**: 快速搭建开发环境
+- **热重载**: 支持代码修改实时预览
+
+### 8.2 生产环境
+- **容器化部署**: 使用Docker容器部署
+- **负载均衡**: 支持多实例部署
+- **HTTPS**: 启用HTTPS加密
+- **自动备份**: 定期备份数据库
+
+## 9. 总结
+
+本架构设计采用了现代化的技术栈和设计理念，实现了一个跨平台的ERP系统，支持财务串通管理和权限管理功能。系统具有良好的扩展性和可维护性，能够满足企业的业务需求，并为后续功能扩展预留了接口。
+
+通过PWA技术，系统可以在Web端和移动端提供一致的用户体验，支持离线访问和安装到主屏幕。后端采用NestJS框架，提供了强大的API服务和业务逻辑处理能力。数据库使用PostgreSQL，确保数据的可靠性和一致性。
+
+系统的财务串通管理功能确保了所有收入支出既能从单个项目查看，又能从公司总账目中查看，实现了财务数据的完整性和一致性。权限管理功能支持基于角色的访问控制和动态权限配置，满足不同用户的权限需求。
+
+本架构设计为跨平台ERP系统的开发提供了清晰的指导，确保系统能够按时、按质完成，并满足用户的需求。