mini-starter/docs/architecture.md

集团管理多公司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等）

架构图

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服务 → 分析报告

多租户架构设计

组织架构实体设计

// 公司实体
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 过滤条件
• 权限系统支持数据访问控制
• 审计日志记录所有数据访问操作

权限穿透机制

// 权限检查逻辑
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. 组织架构管理模块

功能特性:

• 母子公司树形结构管理
• 公司信息维护和状态管理
• 用户分配到具体公司
• 数据权限配置

数据模型:

interface Company {
  id: number;
  name: string;
  code: string;
  parentId: number | null;
  level: number;
  path: string;
  status: 'active' | 'inactive';
  contactInfo: ContactInfo;
  businessInfo: BusinessInfo;
}

2. 供应商管理模块

功能特性:

• 供应商全生命周期管理
• 供应商评价和等级系统
• 证件管理和合规检查
• 供应商绩效分析

数据模型:

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. 销售管理模块

功能特性:

• 销售订单全流程管理
• 多彩宝订单导入和校验
• 订单状态跟踪
• 销售统计分析

数据模型:

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库存分配建议

数据模型:

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

5. 采购管理模块

功能特性:

• 采购计划和需求管理
• 采购订单和合同管理
• 供应商匹配和审批流程
• 进货验收和发票管理

数据模型:

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客户行为分析

数据模型:

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服务架构图

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设计

// 销售预测请求
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设计

// 通用分页响应
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. 冲突解决: 基于时间戳的冲突解决策略

多级缓存策略

// 缓存层级设计
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. 安全监控: 实时监控异常访问

部署和运维

部署架构

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. 容灾备份: 多可用区部署保障可用性

开发工作流

开发环境

# 安装依赖
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          # 测试覆盖率报告

环境配置

# 后端环境变量
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