# 集团管理多公司AI智能进销存应用系统 - 全栈架构文档

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 1.0 | 2025-10-20 | 创建集团级进销存系统全栈架构文档 | Claude |

## 1. 系统概述

### 1.1 项目背景
集团管理多公司AI智能进销存应用系统是一个面向集团化企业的全栈供应链管理平台，支持母子公司多租户架构，集成AI服务实现智能决策，覆盖供应商管理、销售管理、库存管理、采购管理、客户档案管理等核心业务。

### 1.2 系统目标
- 构建集团统一的供应链管理平台
- 通过AI技术实现智能化决策支持
- 支持多端访问（Web端 + 小程序端）
- 实现母子公司数据隔离和权限穿透
- 降低人工操作成本30%以上
- 提升库存周转率15-20%

### 1.3 架构原则
- **多租户架构**: 支持母子公司数据隔离
- **多端统一**: Web端和小程序端共享API和数据模型
- **AI驱动**: 集成AI服务实现智能决策
- **模块化设计**: 业务功能模块化，支持独立扩展
- **性能优先**: API响应时间 < 200ms，支持100+并发用户

## 2. 高层架构设计

### 2.1 整体架构图
```mermaid
graph TB
    subgraph "客户端层"
        A[Web管理后台<br/>React + shadcn/ui] --> E[API网关]
        B[小程序端<br/>Taro多端框架] --> E
        C[H5移动端<br/>响应式设计] --> E
        D[数据大屏<br/>可视化展示] --> E
    end

    subgraph "API网关层"
        E[Hono API网关] --> F[认证中间件]
        E --> G[权限中间件]
        E --> H[多租户路由]
        E --> I[AI服务代理]
    end

    subgraph "业务服务层"
        J[组织架构服务] --> K[数据存储层]
        L[供应商管理服务] --> K
        M[销售管理服务] --> K
        N[库存管理服务] --> K
        O[采购管理服务] --> K
        P[客户管理服务] --> K
        Q[AI决策服务] --> K
        R[文件管理服务] --> K
    end

    subgraph "数据存储层"
        K["PostgreSQL 17<br/>主数据库"] --> S[业务数据]
        K --> T[用户权限数据]
        K --> U[组织架构数据]
        V["Redis 7<br/>缓存层"] --> W[会话缓存]
        V --> X[热点数据]
        Y["MinIO<br/>对象存储"] --> Z[文件存储]
    end

    subgraph "AI服务层"
        AA[第三方AI服务] --> AB[销售预测]
        AA --> AC[库存优化]
        AA --> AD[供应商匹配]
        AA --> AE[客户分析]
    end

    subgraph "基础设施层"
        AF[Docker容器] --> AG[多八多云端环境]
        AH[Node.js运行时] --> AI[生产部署]
        AJ[监控告警] --> AK[运维管理]
    end

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style E fill:#fff3e0
    style J fill:#e8f5e8
    style K fill:#f0fff0
    style AA fill:#fff0f5
```

### 2.2 多端架构

#### 2.2.1 Web端架构
- **技术栈**: React 19.1.0 + TypeScript + shadcn/ui + Tailwind CSS
- **状态管理**: React Query + Context API
- **路由**: React Router v7
- **构建工具**: Vite 7.0.0
- **部署**: 静态资源 + Node.js服务端渲染

#### 2.2.2 小程序端架构
- **技术栈**: Taro 4.1.4 + TypeScript + React 18
- **多端支持**: 微信小程序、支付宝小程序、H5、RN
- **状态管理**: 本地存储 + Context API
- **UI组件**: 自定义组件 + 小程序原生组件
- **构建工具**: Taro CLI + Webpack

#### 2.2.3 API共享架构
- **统一API**: Hono 4.8.5 RPC类型安全API
- **认证统一**: JWT Bearer Token跨端共享
- **数据模型**: 前后端共享TypeScript类型定义
- **错误处理**: 统一错误格式和状态码

## 3. 多租户数据隔离方案

### 3.1 组织架构设计
```typescript
// 公司实体
@Entity('companies')
export class Company {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column({ nullable: true })
  parentId: number;

  @ManyToOne(() => Company, company => company.children)
  parent: Company;

  @OneToMany(() => Company, company => company.parent)
  children: Company[];

  @OneToMany(() => User, user => user.company)
  users: User[];

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

// 用户实体扩展
@Entity('users')
export class User {
  // 现有字段...

  @Column()
  companyId: number;

  @ManyToOne(() => Company, company => company.users)
  company: Company;
}
```

### 3.2 数据隔离策略

#### 3.2.1 数据库层面
- **表设计**: 所有业务表添加`company_id`字段
- **索引优化**: 为`company_id`字段创建复合索引
- **查询过滤**: 自动添加`WHERE company_id = ?`条件
- **外键约束**: 确保数据引用完整性

#### 3.2.2 应用层面
- **中间件拦截**: 请求级别自动注入company_id
- **权限检查**: 验证用户对目标公司的访问权限
- **数据范围**: 基于角色和公司层级的数据可见性

### 3.3 权限穿透机制

#### 3.3.1 母公司权限
- **全数据访问**: 可以访问所有子公司的数据
- **数据聚合**: 跨公司数据统计和分析
- **管理权限**: 子公司用户和权限管理

#### 3.3.2 子公司权限
- **数据隔离**: 只能访问本公司数据
- **业务操作**: 独立的业务处理流程
- **数据上报**: 向母公司上报关键数据

## 4. AI服务集成架构

### 4.1 AI服务架构图
```mermaid
graph LR
    A[业务系统] --> B[AI服务网关]
    B --> C[销售预测服务]
    B --> D[库存优化服务]
    B --> E[供应商匹配服务]
    B --> F[客户分析服务]

    C --> G[历史销售数据]
    D --> H[库存数据]
    E --> I[供应商数据]
    F --> J[客户数据]

    K[第三方AI平台] --> L[模型训练]
    L --> M[模型部署]
    M --> B
```

### 4.2 AI功能模块

#### 4.2.1 销售预测
- **输入**: 历史销售数据、季节性因素、市场趋势
- **输出**: 未来销售预测、库存建议
- **算法**: 时间序列分析、机器学习模型

#### 4.2.2 库存优化
- **输入**: 当前库存、销售预测、供应商交付周期
- **输出**: 最优库存水平、补货建议
- **算法**: 库存优化模型、安全库存计算

#### 4.2.3 供应商匹配
- **输入**: 采购需求、供应商能力、历史表现
- **输出**: 最优供应商推荐、合作建议
- **算法**: 多维度评分、智能匹配

#### 4.2.4 客户分析
- **输入**: 客户行为、购买历史、信用记录
- **输出**: 客户价值评估、信用评级
- **算法**: 客户分群、行为分析

### 4.3 AI服务集成

#### 4.3.1 API设计
```typescript
// AI服务接口定义
interface AIService {
  // 销售预测
  predictSales(params: SalesPredictionParams): Promise<SalesPredictionResult>;

  // 库存优化
  optimizeInventory(params: InventoryOptimizationParams): Promise<InventoryOptimizationResult>;

  // 供应商匹配
  matchSuppliers(params: SupplierMatchingParams): Promise<SupplierMatchingResult>;

  // 客户分析
  analyzeCustomers(params: CustomerAnalysisParams): Promise<CustomerAnalysisResult>;
}
```

#### 4.3.2 集成策略
- **异步处理**: 长时间AI计算采用异步任务
- **缓存机制**: 缓存AI计算结果，减少重复计算
- **降级处理**: AI服务不可用时提供基础决策
- **监控告警**: AI服务性能和准确性监控

## 5. 核心业务模块设计

### 5.1 组织架构管理模块

#### 5.1.1 功能特性
- 母子公司树形层级管理
- 用户分配和权限配置
- 跨公司数据权限控制
- 组织架构导入导出

#### 5.1.2 数据模型
```typescript
interface Organization {
  companies: Company[];
  users: User[];
  roles: Role[];
  permissions: Permission[];
}
```

### 5.2 供应商管理模块

#### 5.2.1 功能特性
- 供应商全生命周期管理
- 证件管理和合作等级
- 供应商评价和备注系统
- AI供应商匹配推荐

#### 5.2.2 数据模型
```typescript
interface Supplier {
  id: number;
  name: string;
  contactInfo: ContactInfo;
  certificates: Certificate[];
  cooperationLevel: CooperationLevel;
  ratings: Rating[];
  companyId: number;
}
```

### 5.3 销售管理模块

#### 5.3.1 功能特性
- 基础销售流程管理
- 多彩宝订单导入和校验
- 多维度订单统计
- AI客户分析和信用评估

#### 5.3.2 数据模型
```typescript
interface SalesOrder {
  id: number;
  customerId: number;
  items: OrderItem[];
  status: OrderStatus;
  totalAmount: number;
  companyId: number;
  aiRecommendations: AIRecommendation[];
}
```

### 5.4 库存管理模块

#### 5.4.1 功能特性
- 总库存和分仓库库存管理
- AI辅助分仓库自动分配
- 实时库存监控和预警
- 库存盘点和库位管理

#### 5.4.2 数据模型
```typescript
interface Inventory {
  id: number;
  productId: number;
  warehouseId: number;
  quantity: number;
  reservedQuantity: number;
  minStockLevel: number;
  maxStockLevel: number;
  companyId: number;
  aiOptimization: AIOptimization;
}
```

### 5.5 采购管理模块

#### 5.5.1 功能特性
- 采购计划和订单管理
- 进货单和合同管理
- AI供应商匹配和采购审批
- 供应商交付跟踪

#### 5.5.2 数据模型
```typescript
interface PurchaseOrder {
  id: number;
  supplierId: number;
  items: PurchaseItem[];
  status: PurchaseStatus;
  totalAmount: number;
  companyId: number;
  aiSupplierMatch: AISupplierMatch;
}
```

### 5.6 客户档案管理模块

#### 5.6.1 功能特性
- 客户等级和关键信息管理
- 客户信息修改及保存
- 历史采购订单关联
- AI客户价值分析

#### 5.6.2 数据模型
```typescript
interface Customer {
  id: number;
  name: string;
  contactInfo: ContactInfo;
  level: CustomerLevel;
  creditRating: CreditRating;
  orderHistory: OrderHistory[];
  companyId: number;
  aiAnalysis: AIAnalysis;
}
```

## 6. 多端数据同步和API共享

### 6.1 统一API设计

#### 6.1.1 API规范
- **版本控制**: `/api/v1/` 前缀
- **认证方式**: JWT Bearer Token
- **数据格式**: JSON统一格式
- **错误处理**: 统一错误码和消息

#### 6.1.2 RPC类型安全
```typescript
// 使用Hono RPC实现类型安全API
const app = new Hono()
  .route('/api/v1/auth', authRoutes)
  .route('/api/v1/users', userRoutes)
  .route('/api/v1/suppliers', supplierRoutes)
  .route('/api/v1/sales', salesRoutes)
  .route('/api/v1/inventory', inventoryRoutes)
  .route('/api/v1/purchases', purchaseRoutes)
  .route('/api/v1/customers', customerRoutes)
  .route('/api/v1/ai', aiRoutes);
```

### 6.2 数据同步策略

#### 6.2.1 实时同步
- **WebSocket**: 关键数据实时推送
- **长轮询**: 兼容性更好的实时更新
- **服务端推送**: 重要事件通知

#### 6.2.2 离线同步
- **本地存储**: 小程序端数据缓存
- **增量同步**: 网络恢复后数据同步
- **冲突解决**: 数据版本控制和冲突检测

### 6.3 缓存策略

#### 6.3.1 Redis缓存
- **会话缓存**: 用户会话和权限信息
- **热点数据**: 频繁访问的业务数据
- **AI结果**: AI计算结果的临时缓存

#### 6.3.2 客户端缓存
- **React Query**: 服务端状态管理
- **LocalStorage**: 用户偏好设置
- **IndexedDB**: 离线数据存储

## 7. 性能和安全考虑

### 7.1 性能优化策略

#### 7.1.1 数据库优化
- **索引策略**: 复合索引优化查询性能
- **分库分表**: 大数据量时的水平扩展
- **读写分离**: 主从复制提升读性能
- **连接池**: 数据库连接复用

#### 7.1.2 应用层优化
- **CDN加速**: 静态资源分发
- **缓存策略**: 多级缓存减少数据库压力
- **异步处理**: 耗时操作异步执行
- **压缩传输**: Gzip压缩减少网络传输

#### 7.1.3 前端优化
- **代码分割**: 按需加载减少初始包大小
- **图片优化**: WebP格式和懒加载
- **Bundle分析**: 构建产物分析和优化
- **预加载**: 关键资源预加载

### 7.2 安全架构

#### 7.2.1 认证授权
- **JWT认证**: 无状态token认证
- **RBAC权限**: 基于角色的访问控制
- **多租户隔离**: 公司级别数据权限
- **会话管理**: 安全的会话生命周期

#### 7.2.2 数据安全
- **传输加密**: TLS 1.3加密传输
- **数据加密**: 敏感数据加密存储
- **输入验证**: Zod schema严格验证
- **SQL防护**: TypeORM参数化查询

#### 7.2.3 应用安全
- **CSP头**: 内容安全策略
- **XSS防护**: 输入输出转义
- **CSRF防护**: 跨站请求伪造防护
- **速率限制**: API访问频率控制

#### 7.2.4 基础设施安全
- **网络隔离**: 最小化网络暴露
- **防火墙**: 严格的端口控制
- **安全监控**: 实时安全事件监控
- **备份恢复**: 定期数据备份和恢复测试

## 8. 部署和运维策略

### 8.1 部署架构

#### 8.1.1 开发环境
- **本地开发**: Docker Compose全栈环境
- **热重载**: 前后端开发时热更新
- **测试环境**: 独立的测试数据库

#### 8.1.2 生产环境
- **容器化部署**: Docker容器统一部署
- **负载均衡**: Nginx反向代理和负载均衡
- **高可用**: 多实例部署保证可用性
- **监控告警**: 全面的系统监控

### 8.2 运维策略

#### 8.2.1 监控体系
- **应用监控**: 性能指标、错误率、响应时间
- **业务监控**: 关键业务指标监控
- **基础设施**: 服务器资源使用情况
- **日志管理**: 集中式日志收集和分析

#### 8.2.2 备份恢复
- **数据库备份**: 定时全量和增量备份
- **文件备份**: MinIO对象存储备份
- **配置备份**: 应用配置版本管理
- **恢复测试**: 定期恢复演练

#### 8.2.3 伸缩策略
- **水平伸缩**: 无状态服务水平扩展
- **垂直伸缩**: 数据库和缓存资源升级
- **自动伸缩**: 基于负载的自动扩缩容
- **容量规划**: 基于业务增长的容量预测

### 8.3 CI/CD流程

#### 8.3.1 持续集成
- **代码检查**: ESLint + TypeScript检查
- **单元测试**: Vitest单元测试覆盖
- **集成测试**: API和组件集成测试
- **E2E测试**: Playwright端到端测试

#### 8.3.2 持续部署
- **自动化构建**: Docker镜像自动构建
- **环境部署**: 多环境自动化部署
- **蓝绿部署**: 零停机部署策略
- **回滚机制**: 快速回滚到稳定版本

## 9. 技术栈详细说明

### 9.1 后端技术栈
- **运行时**: Node.js 20.19.2
- **框架**: Hono 4.8.5
- **数据库**: PostgreSQL 17
- **ORM**: TypeORM 0.3.25
- **缓存**: Redis 7
- **对象存储**: MinIO
- **认证**: JWT + bcrypt
- **验证**: Zod schema验证
- **测试**: Vitest + hono/testing

### 9.2 前端技术栈
- **框架**: React 19.1.0 + TypeScript
- **路由**: React Router v7
- **状态管理**: React Query + Context API
- **UI组件**: shadcn/ui + Radix UI
- **样式**: Tailwind CSS 4.1.11
- **构建工具**: Vite 7.0.0
- **测试**: Vitest + Testing Library

### 9.3 小程序技术栈
- **框架**: Taro 4.1.4 + React 18
- **多端支持**: 微信、支付宝、H5、RN等
- **状态管理**: 本地存储 + Context API
- **UI组件**: 自定义组件库
- **构建工具**: Taro CLI + Webpack
- **HTTP客户端**: Taro.request + RPC客户端

### 9.4 基础设施
- **容器化**: Docker + Docker Compose
- **部署平台**: 多八多云端开发容器环境
- **数据库**: PostgreSQL 17 (默认: postgres)
- **缓存**: Redis 7
- **存储**: MinIO (默认存储桶: d8dai)
- **网络**: 默认开放8080端口外网访问

## 10. 开发工作流

### 10.1 开发环境搭建
```bash
# 安装依赖
pnpm install

# 启动完整开发环境
pnpm dev

# 单独启动Web端
pnpm dev:web

# 单独启动小程序H5
pnpm dev:mini

# 单独启动微信小程序
pnpm dev:weapp
```

### 10.2 测试策略
```bash
# 运行所有测试
pnpm test

# API测试
pnpm test:api

# 组件测试
pnpm test:components

# E2E测试
pnpm test:e2e
pnpm test:e2e:chromium

# 测试覆盖率
pnpm test:coverage
```

### 10.3 数据库操作
```bash
# 数据库迁移
pnpm db:migrate

# 种子数据
pnpm db:seed

# 数据库备份
pnpm db:backup

# 数据库恢复
pnpm db:restore
```

## 11. 风险评估和缓解策略

### 11.1 技术风险
- **多租户性能**: 数据库查询性能优化和索引策略
- **AI服务稳定性**: 降级处理和备用方案
- **多端兼容性**: 充分的跨端测试和兼容性处理

### 11.2 业务风险
- **数据隔离复杂性**: 严格的权限验证和数据范围控制
- **AI决策准确性**: 人工审核和决策修正机制
- **系统集成风险**: 充分的集成测试和回滚计划

### 11.3 安全风险
- **数据泄露风险**: 严格的数据权限控制和加密
- **API安全风险**: 全面的输入验证和速率限制
- **基础设施安全**: 定期的安全扫描和漏洞修复

## 12. 后续演进规划

### 12.1 短期目标（3-6个月）
- 完成基础多租户架构搭建
- 实现核心业务模块MVP
- 集成基础AI决策功能
- 完成Web端和小程序端开发

### 12.2 中期目标（6-12个月）
- 优化AI算法准确性和性能
- 扩展更多业务场景支持
- 提升系统性能和稳定性
- 完善监控和运维体系

### 12.3 长期目标（12个月以上）
- 支持更多小程序平台
- 扩展国际化支持
- 构建开放API生态
- 探索更多AI应用场景

## 13. 附录

### 13.1 相关文档
- [产品需求文档](./prd.md)
- [现有架构文档](./architecture.md)
- [测试策略文档](./architecture/testing-strategy.md)
- [API设计文档](./architecture/api-design-integration.md)

### 13.2 技术决策依据
- **选择Hono框架**: 轻量级、高性能、优秀的TypeScript支持
- **使用Taro小程序**: 多端统一开发、React技术栈一致性
- **PostgreSQL数据库**: 关系型数据、ACID事务、成熟稳定
- **MinIO对象存储**: S3兼容、部署简单、性能优秀

### 13.3 联系方式
- **架构师**: Claude
- **最后更新**: 2025-10-20
- **下次评审**: 2025-11-20

---

**文档状态**: 正式版
**适用范围**: 集团管理多公司AI智能进销存应用系统全栈架构设计