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

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 3.0 | 2025-10-20 | 基于PRD创建集团AI智能进销存系统全栈架构 | Winston |

## 介绍

本文档定义了集团管理多公司AI智能进销存应用系统的完整技术架构。系统基于D8D Starter技术栈构建，支持多租户架构、AI智能决策和多端访问（Web + 小程序）。

### 文档范围
全面定义集团级进销存系统的技术架构，包括多租户数据隔离、AI服务集成、多端支持等关键设计。

### 变更日志
| 日期 | 版本 | 描述 | 作者 |
|------|------|------|------|
| 2025-10-20 | 3.0 | 基于PRD创建集团AI智能进销存系统全栈架构 | Winston |

## 高层架构

### 平台和基础设施选择
**平台**: Docker + Node.js 多八多云端容器环境
**核心服务**: PostgreSQL 17, Redis 7, MinIO对象存储
**部署主机**: 多八多云端开发容器环境，开放8080端口外网访问
**小程序平台**: Taro多端框架（微信、支付宝、H5等）

### 架构图
```mermaid
graph TD
    subgraph "前端应用层"
        A[React 19 Web管理后台] --> B[React Router v7]
        A --> C[React Query 状态管理]
        A --> D[shadcn/ui 组件库]

        E[Taro 多端小程序] --> F[微信小程序]
        E --> G[支付宝小程序]
        E --> H[H5移动端]
        E --> I[其他小程序平台]
    end

    subgraph "API网关层"
        J[Hono 4.8.5 API路由] --> K[Zod Schema验证]
        J --> L[JWT认证中间件]
        J --> M[多租户权限中间件]
        J --> N[OpenAPI文档生成]
        J --> O[AI服务代理]
    end

    subgraph "业务服务层"
        P[通用CRUD服务] --> Q[TypeORM实体管理]
        R[组织架构服务] --> S[多租户数据隔离]
        T[供应商管理服务] --> U[供应商评价系统]
        V[销售管理服务] --> W[订单处理流程]
        X[库存管理服务] --> Y[实时库存监控]
        Z[采购管理服务] --> AA[采购审批流程]
        AB[客户档案服务] --> AC[客户等级管理]
        AD[AI决策服务] --> AE[智能预测分析]
    end

    subgraph "数据存储层"
        AF[PostgreSQL 17] --> AG[用户和组织数据]
        AF --> AH[业务实体数据]
        AF --> AI[AI决策记录]
        AJ[Redis 7 缓存] --> AK[会话缓存]
        AJ --> AL[业务数据缓存]
        AM[MinIO 对象存储] --> AN[文件存储]
    end

    subgraph "AI服务层"
        AO[第三方AI服务] --> AP[销售预测]
        AO --> AQ[库存优化]
        AO --> AR[供应商匹配]
        AO --> AS[客户分析]
    end

    subgraph "基础设施层"
        AT[Docker Compose] --> AU[本地开发环境]
        AV[Node.js 20.19.2] --> AW[生产运行时]
    end

    A --> J
    E --> J
    J --> P
    J --> R
    J --> T
    J --> V
    J --> X
    J --> Z
    J --> AB
    J --> AD
    P --> AF
    AD --> AO
    N --> AX[Swagger UI /ui]

    style A fill:#e1f5fe
    style E fill:#e8f5e8
    style J fill:#f3e5f5
    style P fill:#fff3e0
    style R fill:#fff0f5
    style AD fill:#e1f5fe
    style AO fill:#f0fff0
```

### 架构模式
- **分层架构**: 清晰的前后端分离，统一的API网关
- **多租户架构**: 基于组织架构的数据隔离和权限管理
- **微服务模块化**: 业务功能模块化，支持独立扩展
- **AI驱动**: 深度集成AI服务，实现智能决策
- **多端统一**: Web端和小程序端共享API和数据模型

## 技术栈

### 后端技术栈
| 类别 | 技术 | 版本 | 用途 | 备注 |
|------|------|------|------|------|
| 运行时 | Node.js | 20.19.2 | 服务器运行时环境 | ES模块支持 |
| 框架 | Hono | 4.8.5 | Web框架和API路由 | RPC类型安全 |
| 数据库 | PostgreSQL | 17 | 数据持久化存储 | 多租户支持 |
| ORM | TypeORM | 0.3.25 | 数据库操作抽象 | 实体管理 |
| 缓存 | Redis | 7 | 会话和数据缓存 | 性能优化 |
| 存储 | MinIO | latest | 对象存储服务 | 文件管理 |
| 验证 | Zod | 4.x | Schema验证 | 类型安全 |
| 认证 | JWT | 9.0.2 | 用户认证和安全 | Bearer Token |
| 文档 | @hono/zod-openapi | latest | OpenAPI文档生成 | Swagger UI |

### 前端技术栈（Web）
| 类别 | 技术 | 版本 | 用途 | 备注 |
|------|------|------|------|------|
| 框架 | React | 19.1.0 | 用户界面构建 | 最新版本 |
| 构建工具 | Vite | 7.0.0 | 开发服务器和构建 | 热重载支持 |
| 路由 | React Router | v7 | 前端路由管理 | 声明式路由 |
| 状态管理 | React Query | 5.83.0 | 服务端状态管理 | 数据同步 |
| UI组件 | shadcn/ui | latest | 组件库 | 基于Radix UI |
| 样式 | Tailwind CSS | 4.1.11 | 原子化CSS框架 | 设计一致性 |
| 类型检查 | TypeScript | 5.x | 类型安全 | 严格模式 |

### 小程序技术栈
| 类别 | 技术 | 版本 | 用途 | 备注 |
|------|------|------|------|------|
| 框架 | Taro | 4.1.4 | 多端小程序框架 | 一次开发多端运行 |
| UI框架 | React | 18.0.0 | 小程序UI构建 | 与Web端共享逻辑 |
| 状态管理 | @tanstack/react-query | 5.84.1 | 服务端状态管理 | 与Web端一致 |
| 表单处理 | react-hook-form | 7.62.0 | 表单状态管理 | 类型安全 |
| 验证 | Zod | 4.0.14 | Schema验证 | 与后端一致 |
| 样式 | Tailwind CSS | 4.1.11 | 原子化CSS框架 | 跨端样式 |

### AI服务集成
| 服务 | 用途 | 集成方式 | 数据流 |
|------|------|----------|--------|
| 销售预测 | 基于历史数据预测未来销售 | REST API | 销售数据 → AI服务 → 预测结果 |
| 库存优化 | 智能库存分配和补货建议 | 异步处理 | 库存数据 → AI服务 → 优化建议 |
| 供应商匹配 | 基于采购需求推荐供应商 | 实时调用 | 采购需求 → AI服务 → 供应商推荐 |
| 客户分析 | 客户行为分析和信用评估 | 批量处理 | 客户数据 → AI服务 → 分析报告 |

## 多租户架构设计

### 组织架构实体设计
```typescript
// 公司实体
interface Company {
  id: number;
  name: string;
  code: string; // 公司编码
  parentId: number | null; // 母公司ID
  level: number; // 层级深度
  path: string; // 层级路径
  status: 'active' | 'inactive';
  createdAt: Date;
  updatedAt: Date;
}

// 用户实体扩展
interface User {
  id: number;
  username: string;
  email: string | null;
  password: string;
  companyId: number; // 所属公司
  roles: Role[];
  company: Company;
  createdAt: Date;
  updatedAt: Date;
}
```

### 数据隔离策略

**数据库层面**:
- 所有业务表添加 `company_id` 字段
- 通过数据库视图实现数据隔离
- 使用行级安全策略（RLS）增强安全性

**应用层面**:
- 中间件自动注入 `company_id` 过滤条件
- 权限系统支持数据访问控制
- 审计日志记录所有数据访问操作

### 权限穿透机制
```typescript
// 权限检查逻辑
function checkDataAccess(user: User, targetCompanyId: number): boolean {
  // 管理员可以访问所有数据
  if (user.roles.some(role => role.name === 'super_admin')) {
    return true;
  }

  // 母公司管理员可以访问子公司数据
  if (user.roles.some(role => role.name === 'parent_admin')) {
    return isChildCompany(user.companyId, targetCompanyId);
  }

  // 普通用户只能访问本公司数据
  return user.companyId === targetCompanyId;
}
```

## 核心业务模块设计

### 1. 组织架构管理模块
**功能特性**:
- 母子公司树形结构管理
- 公司信息维护和状态管理
- 用户分配到具体公司
- 数据权限配置

**数据模型**:
```typescript
interface Company {
  id: number;
  name: string;
  code: string;
  parentId: number | null;
  level: number;
  path: string;
  status: 'active' | 'inactive';
  contactInfo: ContactInfo;
  businessInfo: BusinessInfo;
}
```

### 2. 供应商管理模块
**功能特性**:
- 供应商全生命周期管理
- 供应商评价和等级系统
- 证件管理和合规检查
- 供应商绩效分析

**数据模型**:
```typescript
interface Supplier {
  id: number;
  name: string;
  code: string;
  companyId: number;
  contactInfo: ContactInfo;
  businessInfo: BusinessInfo;
  rating: number; // 1-5星评价
  status: 'active' | 'inactive' | 'blacklisted';
  documents: SupplierDocument[];
  createdAt: Date;
  updatedAt: Date;
}
```

### 3. 销售管理模块
**功能特性**:
- 销售订单全流程管理
- 多彩宝订单导入和校验
- 订单状态跟踪
- 销售统计分析

**数据模型**:
```typescript
interface SalesOrder {
  id: number;
  orderNumber: string;
  companyId: number;
  customerId: number;
  warehouseId: number;
  items: OrderItem[];
  totalAmount: number;
  status: 'pending' | 'confirmed' | 'shipped' | 'delivered' | 'cancelled';
  source: 'manual' | 'duocaibao' | 'api';
  createdAt: Date;
  updatedAt: Date;
}
```

### 4. 库存管理模块
**功能特性**:
- 多仓库库存管理
- 实时库存监控和预警
- 库存调拨和盘点
- AI库存分配建议

**数据模型**:
```typescript
interface Inventory {
  id: number;
  productId: number;
  warehouseId: number;
  companyId: number;
  quantity: number;
  reservedQuantity: number; // 预留数量
  availableQuantity: number; // 可用数量
  minStock: number; // 最低库存
  maxStock: number; // 最高库存
  lastUpdated: Date;
}
```

### 5. 采购管理模块
**功能特性**:
- 采购计划和需求管理
- 采购订单和合同管理
- 供应商匹配和审批流程
- 进货验收和发票管理

**数据模型**:
```typescript
interface PurchaseOrder {
  id: number;
  orderNumber: string;
  companyId: number;
  supplierId: number;
  items: PurchaseItem[];
  totalAmount: number;
  status: 'draft' | 'submitted' | 'approved' | 'ordered' | 'received' | 'completed';
  aiRecommendation: AIRecommendation; // AI供应商匹配建议
  createdAt: Date;
  updatedAt: Date;
}
```

### 6. 客户档案管理模块
**功能特性**:
- 客户信息全生命周期管理
- 客户等级和信用评估
- 历史订单关联分析
- AI客户行为分析

**数据模型**:
```typescript
interface Customer {
  id: number;
  name: string;
  code: string;
  companyId: number;
  contactInfo: ContactInfo;
  level: 'A' | 'B' | 'C' | 'D'; // 客户等级
  creditRating: number; // 信用评分
  totalOrders: number;
  totalAmount: number;
  lastOrderDate: Date | null;
  aiAnalysis: CustomerAnalysis; // AI分析结果
  createdAt: Date;
  updatedAt: Date;
}
```

## AI服务集成架构

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

    C --> G[历史销售数据]
    C --> H[市场趋势数据]

    D --> I[当前库存数据]
    D --> J[需求预测数据]

    E --> K[供应商数据库]
    E --> L[采购需求数据]

    F --> M[客户行为数据]
    F --> N[交易历史数据]

    O[第三方AI服务] --> P[机器学习模型]
    O --> Q[自然语言处理]
    O --> R[推荐算法]

    C --> O
    D --> O
    E --> O
    F --> O

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style O fill:#fff0f5
```

### AI服务API设计
```typescript
// 销售预测请求
interface SalesForecastRequest {
  companyId: number;
  productIds: number[];
  period: '7d' | '30d' | '90d';
  historicalData: SalesHistory[];
}

// 库存优化请求
interface InventoryOptimizationRequest {
  companyId: number;
  warehouseId: number;
  products: ProductStockInfo[];
  demandForecast: DemandForecast[];
}

// AI服务响应
interface AIResponse<T> {
  success: boolean;
  data: T;
  confidence: number; // 置信度 0-1
  reasoning: string; // 决策理由
  timestamp: Date;
}
```

### AI集成策略
1. **异步处理**: 耗时AI任务异步执行，结果缓存
2. **缓存机制**: AI计算结果缓存，减少重复计算
3. **降级处理**: AI服务不可用时使用规则引擎
4. **人工确认**: 重要AI决策需要人工确认
5. **持续学习**: 基于用户反馈优化AI模型

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

### 统一API设计
```typescript
// 通用分页响应
interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    total: number;
    current: number;
    pageSize: number;
    totalPages: number;
  };
}

// 统一错误格式
interface ApiError {
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
    timestamp: string;
    requestId: string;
  };
}
```

### 数据同步策略
1. **实时同步**: 关键业务数据实时同步
2. **离线同步**: 小程序支持离线数据缓存
3. **增量同步**: 只同步变更数据，减少网络流量
4. **冲突解决**: 基于时间戳的冲突解决策略

### 多级缓存策略
```typescript
// 缓存层级设计
interface CacheStrategy {
  level1: 'memory'; // 内存缓存，快速访问
  level2: 'redis';  // Redis缓存，应用共享
  level3: 'database'; // 数据库，持久化存储
  ttl: {
    memory: 60,     // 60秒
    redis: 300,     // 5分钟
    database: 3600  // 1小时
  };
}
```

## 性能优化策略

### 数据库优化
1. **索引策略**: 为查询字段创建复合索引
2. **分区表**: 按公司分区大表数据
3. **查询优化**: 使用EXPLAIN分析慢查询
4. **连接池**: 配置合理的数据库连接池

### 应用层优化
1. **缓存策略**: 多级缓存减少数据库访问
2. **异步处理**: 非实时任务异步执行
3. **批量操作**: 减少数据库事务次数
4. **连接复用**: HTTP连接池和数据库连接复用

### 前端优化
1. **代码分割**: 按路由懒加载组件
2. **图片优化**: 使用WebP格式和懒加载
3. **缓存策略**: 静态资源长期缓存
4. **压缩传输**: Gzip压缩减少传输大小

## 安全架构

### 认证授权
1. **JWT认证**: Bearer Token，30分钟过期
2. **RBAC权限**: 基于角色的访问控制
3. **多租户隔离**: 数据访问权限控制
4. **会话管理**: Redis存储会话状态

### 数据安全
1. **传输加密**: TLS 1.3加密所有通信
2. **数据加密**: 敏感字段数据库层加密
3. **备份加密**: 数据库备份文件AES-256加密
4. **访问审计**: 所有操作记录审计日志

### 应用安全
1. **输入验证**: Zod Schema验证所有输入
2. **SQL注入防护**: TypeORM参数化查询
3. **XSS防护**: 输出转义和CSP头
4. **CSRF防护**: 同源策略和Token验证

### 基础设施安全
1. **网络隔离**: 数据库仅允许应用服务器访问
2. **防火墙规则**: 仅开放必要端口
3. **最小权限**: 所有服务以非root用户运行
4. **安全监控**: 实时监控异常访问

## 部署和运维

### 部署架构
```mermaid
graph TD
    A[用户访问] --> B[负载均衡器]
    B --> C[Web应用服务器]
    B --> D[API服务器]
    C --> E[静态资源CDN]
    D --> F[数据库集群]
    D --> G[Redis集群]
    D --> H[MinIO集群]
    D --> I[AI服务]

    J[小程序] --> K[微信/支付宝平台]
    K --> D

    style C fill:#e1f5fe
    style D fill:#f3e5f5
    style F fill:#e8f5e8
```

### 监控体系
1. **应用性能监控**: 请求率、错误率、响应时间
2. **业务指标监控**: 用户活跃度、订单量、库存周转率
3. **基础设施监控**: CPU、内存、磁盘、网络
4. **安全监控**: 异常访问、攻击尝试、数据泄露

### 备份恢复
1. **数据库备份**: 定时全量备份 + 实时增量备份
2. **文件备份**: MinIO对象存储多副本
3. **配置备份**: 应用配置版本管理
4. **恢复测试**: 定期演练恢复流程

### 伸缩策略
1. **水平扩展**: 无状态服务水平扩展
2. **垂直扩展**: 数据库和缓存垂直升级
3. **自动伸缩**: 基于负载自动调整资源
4. **容灾备份**: 多可用区部署保障可用性

## 开发工作流

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

# 启动开发环境
pnpm dev                    # 启动Web端开发服务器
pnpm dev:mini [platform]    # 启动小程序开发服务器

# 运行测试
pnpm test                   # 运行所有测试
pnpm test:api               # 运行API测试
pnpm test:components        # 运行组件测试
pnpm test:e2e               # 运行E2E测试
pnpm test:mini              # 运行小程序测试

# 代码质量
pnpm lint                   # ESLint检查
pnpm typecheck              # TypeScript类型检查
pnpm test:coverage          # 测试覆盖率报告
```

### 环境配置
```bash
# 后端环境变量
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
REDIS_URL=redis://localhost:6379
MINIO_ENDPOINT=localhost
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
JWT_SECRET=your-jwt-secret-key
AI_SERVICE_URL=https://api.ai-service.com
NODE_ENV=development

# 前端环境变量
VITE_API_BASE_URL=http://localhost:3000/api
VITE_AI_SERVICE_URL=https://api.ai-service.com
```

### CI/CD流程
1. **代码提交**: Git工作流，PR代码审查
2. **自动化测试**: 单元测试、集成测试、E2E测试
3. **代码质量**: ESLint、TypeScript检查、安全扫描
4. **构建部署**: 自动构建Docker镜像，蓝绿部署
5. **监控反馈**: 部署后监控，快速回滚机制

## 附录

### 技术决策依据
1. **选择D8D Starter**: 成熟的全栈技术基础，快速开发能力
2. **多租户架构**: 满足集团化企业的数据隔离需求
3. **AI服务集成**: 提升业务决策的智能化水平
4. **多端支持**: 覆盖Web和移动端不同使用场景

### 相关文档
- 产品需求文档: `docs/prd.md`
- 项目简介: `docs/brief.md`
- API文档: 通过 `/ui` 端点访问
- 测试策略: `docs/architecture/testing-strategy.md`

### 联系方式
- 架构师: Winston 🏗️
- 最后更新: 2025-10-20

---

**文档状态**: 正式版
**下次评审**: 2025-11-20