# 核心业务模块设计

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 3.0 | 2025-10-20 | 集团AI智能进销存系统核心业务模块 | Winston |

## 1. 组织架构管理模块

### 功能特性
- **母子公司树形结构管理**: 支持无限层级组织架构
- **公司信息维护和状态管理**: 完整的公司档案管理
- **用户分配到具体公司**: 用户与公司绑定关系
- **数据权限配置**: 基于组织架构的权限控制

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

interface ContactInfo {
  phone: string | null;
  address: string | null;
  contactPerson: string | null;
  email: string | null;
}

interface BusinessInfo {
  businessLicense: string | null;
  taxNumber: string | null;
  industry: string | null;
  scale: 'small' | 'medium' | 'large';
}
```

### API端点
- `GET /api/v1/companies` - 获取公司列表
- `POST /api/v1/companies` - 创建公司
- `GET /api/v1/companies/{id}` - 获取公司详情
- `PUT /api/v1/companies/{id}` - 更新公司信息
- `DELETE /api/v1/companies/{id}` - 删除公司
- `GET /api/v1/companies/tree` - 获取组织架构树

## 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[];
  performance: SupplierPerformance;
  createdAt: Date;
  updatedAt: Date;
}

interface SupplierDocument {
  id: number;
  supplierId: number;
  type: 'business_license' | 'tax_certificate' | 'quality_certificate';
  name: string;
  filePath: string;
  expiryDate: Date | null;
  status: 'valid' | 'expired' | 'pending';
}

interface SupplierPerformance {
  deliveryRate: number; // 准时交付率
  qualityRate: number; // 质量合格率
  responseTime: number; // 平均响应时间
  totalOrders: number; // 总订单数
  totalAmount: number; // 总交易金额
  lastOrderDate: Date | null;
}
```

### API端点
- `GET /api/v1/suppliers` - 获取供应商列表
- `POST /api/v1/suppliers` - 创建供应商
- `GET /api/v1/suppliers/{id}` - 获取供应商详情
- `PUT /api/v1/suppliers/{id}` - 更新供应商信息
- `POST /api/v1/suppliers/{id}/documents` - 上传供应商证件
- `GET /api/v1/suppliers/{id}/performance` - 获取供应商绩效

## 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';
  paymentStatus: 'pending' | 'paid' | 'refunded';
  shippingInfo: ShippingInfo;
  createdAt: Date;
  updatedAt: Date;
}

interface OrderItem {
  id: number;
  orderId: number;
  productId: number;
  productName: string;
  quantity: number;
  unitPrice: number;
  totalPrice: number;
  sku: string;
}

interface ShippingInfo {
  recipient: string;
  phone: string;
  address: string;
  shippingMethod: string;
  trackingNumber: string | null;
  estimatedDelivery: Date | null;
  actualDelivery: Date | null;
}
```

### API端点
- `GET /api/v1/sales-orders` - 获取销售订单列表
- `POST /api/v1/sales-orders` - 创建销售订单
- `GET /api/v1/sales-orders/{id}` - 获取订单详情
- `PUT /api/v1/sales-orders/{id}/status` - 更新订单状态
- `POST /api/v1/sales-orders/import` - 导入多彩宝订单
- `GET /api/v1/sales-orders/statistics` - 获取销售统计

## 4. 库存管理模块

### 功能特性
- **多仓库库存管理**: 支持多个物理仓库的库存管理
- **实时库存监控和预警**: 库存水平实时监控和预警
- **库存调拨和盘点**: 仓库间调拨和定期盘点
- **AI库存分配建议**: 基于AI的智能库存分配

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

interface Warehouse {
  id: number;
  name: string;
  code: string;
  companyId: number;
  location: string;
  capacity: number;
  contactInfo: ContactInfo;
  status: 'active' | 'inactive';
}

interface StockMovement {
  id: number;
  productId: number;
  warehouseId: number;
  type: 'in' | 'out' | 'transfer' | 'adjustment';
  quantity: number;
  referenceId: number | null; // 关联订单ID
  referenceType: 'sales_order' | 'purchase_order' | 'transfer' | 'adjustment';
  description: string;
  createdAt: Date;
}
```

### API端点
- `GET /api/v1/inventory` - 获取库存列表
- `GET /api/v1/inventory/{productId}` - 获取产品库存
- `POST /api/v1/inventory/transfer` - 库存调拨
- `POST /api/v1/inventory/adjustment` - 库存调整
- `GET /api/v1/inventory/alerts` - 获取库存预警
- `GET /api/v1/warehouses` - 获取仓库列表

## 5. 采购管理模块

### 功能特性
- **采购计划和需求管理**: 基于库存和销售预测的采购计划
- **采购订单和合同管理**: 完整的采购流程管理
- **供应商匹配和审批流程**: AI驱动的供应商推荐和审批
- **进货验收和发票管理**: 采购到货验收和发票处理

### 数据模型
```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供应商匹配建议
  approvalInfo: ApprovalInfo;
  deliveryInfo: DeliveryInfo;
  createdAt: Date;
  updatedAt: Date;
}

interface PurchaseItem {
  id: number;
  orderId: number;
  productId: number;
  productName: string;
  quantity: number;
  unitPrice: number;
  totalPrice: number;
  expectedDelivery: Date;
}

interface AIRecommendation {
  recommendedSuppliers: RecommendedSupplier[];
  confidence: number;
  reasoning: string;
  timestamp: Date;
}

interface RecommendedSupplier {
  supplierId: number;
  supplierName: string;
  score: number;
  reasons: string[];
}

interface ApprovalInfo {
  approverId: number;
  approverName: string;
  approvedAt: Date | null;
  comments: string | null;
}
```

### API端点
- `GET /api/v1/purchase-orders` - 获取采购订单列表
- `POST /api/v1/purchase-orders` - 创建采购订单
- `GET /api/v1/purchase-orders/{id}` - 获取采购订单详情
- `PUT /api/v1/purchase-orders/{id}/status` - 更新采购订单状态
- `POST /api/v1/purchase-orders/{id}/approve` - 审批采购订单
- `GET /api/v1/purchase-orders/{id}/ai-recommendation` - 获取AI推荐

## 6. 产品管理模块

### 功能特性
- **产品分类和属性管理**: 支持多层级产品分类和自定义属性
- **SKU和条码管理**: 完整的SKU编码和条码管理系统
- **价格策略和成本管理**: 多维度价格策略和成本控制
- **产品生命周期管理**: 从新品上市到退市的完整生命周期
- **AI产品推荐**: 基于销售数据的智能产品推荐

### 数据模型
```typescript
interface Product {
  id: number;
  name: string;
  code: string;
  sku: string;
  barcode: string;
  companyId: number;
  categoryId: number;
  brand: string;
  model: string;
  description: string;
  specifications: ProductSpecification[];
  images: ProductImage[];
  pricing: ProductPricing;
  inventoryInfo: ProductInventoryInfo;
  status: 'active' | 'inactive' | 'discontinued';
  aiRecommendation: ProductRecommendation; // AI推荐信息
  createdAt: Date;
  updatedAt: Date;
}

interface ProductCategory {
  id: number;
  name: string;
  code: string;
  parentId: number | null;
  level: number;
  path: string;
  attributes: CategoryAttribute[];
  companyId: number;
  status: 'active' | 'inactive';
}

interface CategoryAttribute {
  id: number;
  categoryId: number;
  name: string;
  type: 'text' | 'number' | 'select' | 'boolean';
  required: boolean;
  options: string[] | null;
  defaultValue: string | number | boolean | null;
}

interface ProductSpecification {
  id: number;
  productId: number;
  attributeId: number;
  attributeName: string;
  value: string | number | boolean;
}

interface ProductImage {
  id: number;
  productId: number;
  url: string;
  alt: string;
  isPrimary: boolean;
  sortOrder: number;
}

interface ProductPricing {
  costPrice: number; // 成本价
  retailPrice: number; // 零售价
  wholesalePrice: number; // 批发价
  vipPrice: number; // VIP价
  discountRate: number; // 折扣率
  currency: string; // 货币
  taxRate: number; // 税率
  validFrom: Date;
  validTo: Date | null;
}

interface ProductInventoryInfo {
  totalStock: number; // 总库存
  reservedStock: number; // 预留库存
  availableStock: number; // 可用库存
  safetyStock: number; // 安全库存
  reorderPoint: number; // 补货点
  leadTime: number; // 采购提前期（天）
  turnoverRate: number; // 周转率
}

interface ProductRecommendation {
  popularityScore: number; // 受欢迎度评分
  salesTrend: 'rising' | 'stable' | 'declining'; // 销售趋势
  crossSellProducts: number[]; // 交叉销售产品ID
  upSellProducts: number[]; // 升级销售产品ID
  seasonalFactor: number; // 季节性因素
  lastAnalysisDate: Date;
}
```

### API端点
- `GET /api/v1/products` - 获取产品列表
- `POST /api/v1/products` - 创建产品
- `GET /api/v1/products/{id}` - 获取产品详情
- `PUT /api/v1/products/{id}` - 更新产品信息
- `DELETE /api/v1/products/{id}` - 删除产品
- `GET /api/v1/product-categories` - 获取产品分类
- `POST /api/v1/product-categories` - 创建产品分类
- `GET /api/v1/products/{id}/ai-recommendation` - 获取产品AI推荐
- `POST /api/v1/products/batch-import` - 批量导入产品

## 7. 客户档案管理模块

### 功能特性
- **客户信息全生命周期管理**: 客户从注册到流失的完整管理
- **客户等级和信用评估**: 基于交易行为的客户评级
- **历史订单关联分析**: 客户购买行为和偏好分析
- **AI客户行为分析**: 基于AI的客户价值分析

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

interface CustomerAnalysis {
  valueScore: number; // 客户价值评分
  loyaltyScore: number; // 客户忠诚度评分
  potentialScore: number; // 客户潜力评分
  riskScore: number; // 客户风险评分
  purchaseFrequency: number; // 购买频率
  averageOrderValue: number; // 平均订单价值
  preferredProducts: number[]; // 偏好产品ID
  lastAnalysisDate: Date;
}

interface CustomerTransaction {
  id: number;
  customerId: number;
  orderId: number;
  type: 'purchase' | 'return' | 'refund';
  amount: number;
  description: string;
  createdAt: Date;
}
```

### API端点
- `GET /api/v1/customers` - 获取客户列表
- `POST /api/v1/customers` - 创建客户
- `GET /api/v1/customers/{id}` - 获取客户详情
- `PUT /api/v1/customers/{id}` - 更新客户信息
- `GET /api/v1/customers/{id}/transactions` - 获取客户交易记录
- `GET /api/v1/customers/{id}/ai-analysis` - 获取客户AI分析

## 模块间交互

### 数据流图
```mermaid
graph TD
    A[组织架构管理] --> B[权限控制]
    B --> C[供应商管理]
    B --> D[产品管理]
    B --> E[客户管理]
    B --> F[销售管理]
    B --> G[库存管理]
    B --> H[采购管理]

    D --> I[产品信息]
    I --> F[销售订单]
    I --> H[采购订单]
    I --> G[库存管理]

    F --> J[库存扣减]
    H --> K[库存增加]
    G --> L[库存预警]
    L --> H[采购触发]

    C --> M[供应商推荐]
    D --> N[产品推荐]
    E --> O[客户分析]
    F --> P[销售预测]
    G --> Q[库存优化]

    M --> R[AI决策服务]
    N --> R
    O --> R
    P --> R
    Q --> R
```

### 关键业务流程

1. **产品管理流程**:
   - 产品分类定义 → 产品属性配置 → 产品信息录入 → SKU生成 → 价格策略设置

2. **销售订单流程**:
   - 选择产品 → 创建销售订单 → 检查库存 → 扣减库存 → 更新订单状态

3. **采购订单流程**:
   - 基于产品需求 → 创建采购需求 → AI供应商推荐 → 创建采购订单 → 审批 → 到货验收 → 增加库存

4. **库存管理流程**:
   - 产品库存监控 → 库存预警 → 触发采购 → 库存调拨 → 库存盘点

5. **客户管理流程**:
   - 客户注册 → 购买产品 → 交易记录 → AI分析 → 客户评级 → 个性化产品推荐

这7个核心业务模块（组织架构管理、供应商管理、销售管理、库存管理、采购管理、产品管理、客户档案管理）共同构成了集团AI智能进销存系统的完整业务基础。产品管理作为系统的核心，为其他模块提供了标准化的产品信息，确保了数据的一致性和业务流程的顺畅性。通过模块化设计和清晰的接口定义，确保了系统的可扩展性和可维护性。