# 统一类型管理规范（Unified Type Management Standards）

> **模块**: 01_Architecture - 统一类型管理与语义中心  
> **更新日期**: 2026-03-20  
> **版本**: 1.0.0  
> **适用范围**: 全项目（dashboard、server、node-agent）

---

## 1. 概述（Overview）

### 1.1 什么是统一类型管理

**统一类型管理**是一种集中式类型定义和管理的方法，通过建立统一的类型中心来：

- **消除类型重复**：避免在多个模块中重复定义相同类型
- **确保类型一致性**：前后端使用相同的类型定义
- **提高可维护性**：类型变更只需修改一处
- **增强类型安全**：通过 Schema 驱动确保类型正确性
- **AI 友好**：为 AI 提供清晰、统一的类型定义

### 1.2 核心原则

| 原则 | 说明 | 违反后果 |
|------|------|----------|
| **单一来源** | 所有类型只从类型中心导入 | 类型不一致 |
| **禁止重复定义** | 禁止在各模块中重复定义类型 | 维护困难 |
| **Schema 驱动** | 类型从 Schema 推导而来 | 类型错误 |
| **分层管理** | 按层次组织类型（API、DTO、Domain） | 结构混乱 |
| **版本控制** | 类型变更必须版本化 | 兼容性问题 |

---

## 2. 当前实现架构（Current Implementation）

### 2.1 目录结构

```
server/src/shared/
├── schemas/                     # ✅ Zod Schema 定义中心（唯一真理源）
│   ├── user.schema.ts           # User Schema + 类型推导
│   ├── product.schema.ts        # Product Schema + 类型推导
│   ├── order.schema.ts          # Order Schema + 类型推导
│   ├── message.schema.ts        # 插件消息类型
│   ├── common.schema.ts         # 通用类型（分页、错误等）
│   └── index.ts                 # 统一导出
│
├── types/                       # 类型重新导出（兼容层）
│   ├── domain/                  # 领域模型（从 Schema 推导）
│   │   ├── User.ts
│   │   ├── Product.ts
│   │   ├── Order.ts
│   │   ├── Inventory.ts
│   │   ├── ShopInfo.ts
│   │   ├── Certificate.ts
│   │   └── ProductSelection.ts
│   ├── dto/                     # 数据传输对象（从 Schema 推导）
│   │   ├── UserDTO.ts
│   │   ├── ProductDTO.ts
│   │   ├── OrderDTO.ts
│   │   └── index.ts
│   ├── enums/                   # 枚举定义
│   │   ├── BusinessEnums.ts
│   │   ├── PlatformType.ts
│   │   ├── StoreStatus.ts
│   │   └── index.ts
│   ├── shared/                  # 共享类型
│   │   ├── Message.ts
│   │   ├── DataSource.ts
│   │   ├── Monitoring.ts
│   │   ├── Security.ts
│   │   ├── Service.ts
│   │   ├── Pagination.ts
│   │   ├── Error.ts
│   │   ├── Response.ts
│   │   └── index.ts
│   ├── version.ts               # 类型版本管理
│   └── index.ts                 # 统一导出
│
└── utils/
    └── zodToOpenAPI.ts          # Zod → OpenAPI 转换工具

dashboard/src/types/
├── dataSourceMap.ts             # DataSource 类型映射
└── index.ts                     # 重新导出 server 类型

node-agent/src/types/
└── index.ts                     # 重新导出 server 类型
```

### 2.2 类型层次

```
┌─────────────────────────────────────────┐
│      Zod Schema（唯一真理源）            │
│  - 运行时验证                            │
│  - 类型推导                              │
└──────────────┬──────────────────────────┘
               │ z.infer<typeof Schema>
               ↓
┌─────────────────────────────────────────┐
│         Domain Layer (领域层)            │
│  - Business Entities                    │
│  - Domain Models                        │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│         DTO Layer (传输层)              │
│  - Data Transfer Objects                │
│  - API Input/Output                     │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│         API Layer (接口层)              │
│  - Request Types                        │
│  - Response Types                       │
└─────────────────────────────────────────┘
```

---

## 3. Schema 驱动开发（Schema-Driven Development）

### 3.1 定义 Schema

```typescript
// server/src/shared/schemas/user.schema.ts
import { z } from 'zod';

export const UserRoleSchema = z.enum([
  'admin',
  'customer',
  'manager',
  'staff',
  'finance',
  'sourcing',
  'logistics',
  'analyst'
]);

export const UserStatusSchema = z.enum([
  'active',
  'inactive',
  'suspended'
]);

export const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
  phone: z.string().optional(),
  role: UserRoleSchema,
  status: UserStatusSchema,
  createdAt: z.coerce.date(),
  updatedAt: z.coerce.date()
});

// 自动推导类型
export type User = z.infer<typeof UserSchema>;
export type UserRole = z.infer<typeof UserRoleSchema>;
export type UserStatus = z.infer<typeof UserStatusSchema>;
```

### 3.2 DTO 层从 Schema 推导

```typescript
// server/src/shared/types/dto/UserDTO.ts
import type {
  User,
  UserRole,
  UserStatus,
  CreateUserInput,
  UpdateUserInput,
  UserQueryInput
} from '../../schemas/user.schema';

export type {
  User,
  UserRole,
  UserStatus,
  CreateUserInput as CreateUserDTO,
  UpdateUserInput as UpdateUserDTO,
  UserQueryInput as UserQueryDTO
};

export interface UserResponseDTO extends User {}
```

### 3.3 Domain 层从 Schema 推导

```typescript
// server/src/shared/types/domain/User.ts
export type {
  User,
  UserRole,
  UserStatus
} from '../../schemas/user.schema';
```

---

## 4. API 验证（API Validation）

### 4.1 使用 Zod 验证中间件

```typescript
// server/src/api/routes/user.ts
import { Router } from 'express';
import { validateSchema } from '../middleware/ZodValidationMiddleware';
import { CreateUserSchema, UpdateUserSchema } from '@shared/schemas';

const router = Router();

router.post(
  '/users',
  validateSchema(CreateUserSchema),
  UserController.create
);

router.put(
  '/users/:id',
  validateSchema(UpdateUserSchema),
  UserController.update
);
```

### 4.2 验证中间件实现

```typescript
// server/src/api/middleware/ZodValidationMiddleware.ts
import { NextFunction, Request, Response } from 'express';
import { ZodObject, ZodError } from 'zod';

export const validateSchema = (schema: ZodObject<any>) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    try {
      await schema.parseAsync({
        body: req.body,
        query: req.query,
        params: req.params,
      });
      next();
    } catch (error) {
      if (error instanceof ZodError) {
        return res.status(400).json({
          success: false,
          error: 'BAD_REQUEST_INVALID_SCHEMA',
          message: '请求参数不符合 API 契约规范',
          details: error.issues
        });
      }
      next(error);
    }
  };
};
```

---

## 5. 三端类型同步（Three-End Type Sync）

### 5.1 后端导入

```typescript
// server/src/services/UserService.ts
import { User, CreateUserDTO, UpdateUserDTO } from '../shared/types';
import { CreateUserSchema } from '../shared/schemas';
```

### 5.2 前端导入

```typescript
// dashboard/src/services/userDataSource.ts
import { User, CreateUserDTO } from '@shared/types';
// 或
import { User } from '@/types';
```

### 5.3 Node Agent导入

```typescript
// node-agent/src/index.ts
import { NodeTask } from '../../server/src/shared/types';
import { NodeTaskSchema } from '../../server/src/shared/schemas';
```

---

## 6. 类型版本管理（Type Version Management）

### 6.1 版本文件

```typescript
// server/src/shared/types/version.ts
export const TYPE_VERSION = '1.0.0';

export const TYPE_CHANGELOG: TypeChangeLog[] = [
  {
    version: '1.0.0',
    date: '2026-03-20',
    changes: [
      'Initial unified type center setup',
      'Created Zod schemas for User, Product, Order',
      'Added DTO layer with schema-driven types',
      'Added common types: Pagination, Error, Response',
      'Added plugin message types',
      'Created zodToOpenAPI converter'
    ]
  }
];

export function getTypeVersion(): string {
  return TYPE_VERSION;
}

export function getLatestChanges(): TypeChangeLog {
  return TYPE_CHANGELOG[0];
}
```

### 6.2 使用版本信息

```typescript
import { getTypeVersion, getLatestChanges } from '@shared/types/version';

console.log('Type Version:', getTypeVersion());
console.log('Latest Changes:', getLatestChanges());
```

---

## 7. OpenAPI 文档生成（OpenAPI Documentation）

### 7.1 Zod 转 OpenAPI

```typescript
// server/src/shared/utils/zodToOpenAPI.ts
import { zodToOpenAPI, createAPIDocumentation } from '@shared/utils/zodToOpenAPI';
import { CreateUserSchema, UserSchema } from '@shared/schemas';

const docs = createAPIDocumentation(
  'CreateUser',
  CreateUserSchema,
  UserSchema
);

// docs.request → OpenAPI Schema for request
// docs.response → OpenAPI Schema for response
```

### 7.2 与 Swagger 集成

```typescript
// server/src/api/routes/user.ts
import { zodToOpenAPI } from '@shared/utils/zodToOpenAPI';
import { CreateUserSchema } from '@shared/schemas';

/**
 * @openapi
 * /users:
 *   post:
 *     requestBody:
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/CreateUser'
 */
router.post('/users', UserController.create);
```

---

## 8. 插件消息类型（Plugin Message Types）

### 8.1 消息类型定义

```typescript
// server/src/shared/schemas/message.schema.ts
import { z } from 'zod';

export const MessageTypeSchema = z.enum([
  'COLLECT_ORDERS',
  'SYNC_ALL_ORDERS',
  'SYNC_RETURNS',
  'SYNC_ALL_RETURNS',
  'QUERY_REFUNDS',
  'AUTO_SHIP',
  'GET_SHOP_INFO',
  'UPDATE_SHOP_STATUS',
  'GET_FINGERPRINT',
  'VALIDATE_SESSION',
  'HEALTH_CHECK'
]);

export const BaseMessageSchema = z.object({
  type: MessageTypeSchema,
  payload: z.record(z.string(), z.unknown()),
  traceId: z.string().optional(),
  shopId: z.string().optional(),
  platform: z.string().optional()
});

export const MessageResponseSchema = z.object({
  success: z.boolean(),
  data: z.unknown().optional(),
  error: z.object({
    code: z.string(),
    message: z.string()
  }).optional(),
  traceId: z.string()
});
```

### 8.2 Node Agent使用

```typescript
// node-agent/src/index.ts
import { NodeTask } from '../../server/src/shared/types';

export class NodeAgent {
  async executeTask(task: NodeTask): Promise<void> {
    const traceId = task.traceId || this.generateTraceId();
    
    switch (task.type) {
      case 'COLLECT_ORDERS':
        return this.collectOrders(task.payload, traceId);
      // ...
    }
  }
}
```

---

## 9. 前端 DataSource 类型映射（Frontend DataSource Mapping）

### 9.1 类型映射定义

```typescript
// dashboard/src/types/dataSourceMap.ts
import type { IDataSource } from './datasource';
import type { User, CreateUserDTO, UpdateUserDTO, UserQueryDTO } from '@shared/types';

export interface DataSourceMap {
  certificate: IDataSource<Certificate, CertificateQueryParams>;
  user: IDataSource<User, UserQueryDTO> & {
    create: (data: CreateUserDTO) => Promise<User>;
    update: (id: string, data: UpdateUserDTO) => Promise<User>;
  };
  product: IDataSource<Product, ProductQueryDTO>;
  order: IDataSource<Order, OrderQueryDTO>;
}

export type DataSourceKey = keyof DataSourceMap;
export type DataSourceType<K extends DataSourceKey> = DataSourceMap[K];
```

### 9.2 动态获取 DataSource

```typescript
export function getDataSource<K extends DataSourceKey>(key: K): DataSourceType<K> {
  const dataSources = {
    certificate: () => import('../services/certificateDataSource').then(m => m.certificateDataSource),
    user: () => import('../services/userDataSource').then(m => m.userDataSource),
    product: () => import('../services/productDataSource').then(m => m.productDataSource),
    order: () => import('../services/orderDataSource').then(m => m.orderDataSource),
  };
  
  return dataSources[key]() as DataSourceType<K>;
}
```

---

## 10. 导入规范（Import Standards）

### 10.1 后端导入

```typescript
// ✅ 推荐：从统一类型中心导入
import { User, Product, Order } from '../shared/types';
import { CreateUserSchema } from '../shared/schemas';

// ✅ 也可以：从子模块导入
import { User } from '../shared/types/domain';
import { CreateUserDTO } from '../shared/types/dto';
```

### 10.2 前端导入

```typescript
// ✅ 推荐：使用路径别名
import { User, Product } from '@shared/types';

// ✅ 兼容：从本地 types 导入
import { User } from '@/types';
```

### 10.3 插件端导入

```typescript
// ✅ 推荐：使用相对路径
import { BaseMessage, MessageResponse } from '../../server/src/shared/types';
import { BaseMessageSchema } from '../../server/src/shared/schemas';
```

---

## 11. 开发流程（Development Workflow）

### 11.1 新增类型流程

```
1. 定义 Zod Schema → server/src/shared/schemas/*.schema.ts
2. 导出推导类型 → export type X = z.infer<typeof Schema>
3. DTO 层重新导出 → server/src/shared/types/dto/*.ts
4. Domain 层重新导出 → server/src/shared/types/domain/*.ts
5. 更新版本号 → server/src/shared/types/version.ts
```

### 11.2 修改类型流程

```
1. 修改 Zod Schema
2. 运行类型检查 → npx tsc --noEmit
3. 修复所有类型错误
4. 更新版本号和 CHANGELOG
5. 提交代码
```

---

## 12. CI/CD 集成（CI/CD Integration）

### 12.1 类型检查

```yaml
# .github/workflows/ci-cd.yml
jobs:
  type-check:
    steps:
      - name: Run TypeScript check
        run: |
          cd server && npx tsc --noEmit --skipLibCheck
          cd ../dashboard && npx tsc --noEmit --skipLibCheck
          cd ../node-agent && npx tsc --noEmit --skipLibCheck
```

### 12.2 Schema 验证

```yaml
- name: Validate schemas
  run: |
    cd server && npm run test:schemas
```

---

## 13. 最佳实践（Best Practices）

### 13.1 DO ✅

- 使用 `z.infer` 从 Schema 推导类型
- 从统一类型中心导入类型
- 使用 Zod 进行运行时验证
- 保持 Schema 和类型同步
- 版本化类型变更

### 13.2 DON'T ❌

- 在各模块中重复定义类型
- 使用 `any` 类型
- 跳过 Zod 验证
- 直接修改 DTO 而不更新 Schema
- 忽略类型错误

---

## 14. 版本历史（Version History）

| 版本 | 描述 | 日期 |
|------|------|------|
| 1.0.0 | 初始版本，建立统一类型中心 | 2026-03-20 |

---

## 15. 参考资源

- [TypeScript 类型系统](https://www.typescriptlang.org/docs/handbook/2/types-from-types.html)
- [zod 类型推导](https://zod.dev/?id=inferring-the-inferred-type)
- [Schema 驱动开发](https://www.patterns.dev/posts/schema-driven-development/)
- [OpenAPI 规范](https://swagger.io/specification/)
