feat(types): 添加类型检查脚本和迁移指南

添加 check-types.ps1 脚本用于检查项目各模块的类型定义添加 migrate-types.ps1 脚本用于自动迁移类型导入路径添加类型迁移指南文档说明迁移步骤和最佳实践添加共享类型测试用例验证 schema 定义
2026-03-20 18:00:31 +08:00
parent 427becbc8f
commit 888d3844f3
4 changed files with 837 additions and 0 deletions
--- a/docs/05_AI/08_Type_Migration_Guide.md
+++ b/docs/05_AI/08_Type_Migration_Guide.md
@@ -0,0 +1,376 @@
+# 类型导入迁移指南
+
+> **目的**: 帮助开发者将旧的类型导入方式迁移到统一类型中心  
+> **更新日期**: 2026-03-20
+
+---
+
+## 1. 迁移概览
+
+### 1.1 迁移目标
+
+```
+旧方式（分散）                    新方式（统一）
+─────────────────────────────────────────────────────
+各模块独立定义类型       →        从类型中心导入
+手动维护类型一致性       →        Schema 自动推导
+无运行时验证             →        Zod 运行时验证
+```
+
+### 1.2 迁移原则
+
+1. **渐进式迁移**: 不要求一次性全部迁移
+2. **向后兼容**: 保留旧的类型导出路径
+3. **验证优先**: 迁移后必须通过类型检查
+
+---
+
+## 2. 后端迁移
+
+### 2.1 旧导入方式
+
+```typescript
+// ❌ 旧方式：从本地文件导入
+import { User } from '../models/User';
+import { Product } from '../models/Product';
+import { Order } from '../models/Order';
+
+// ❌ 旧方式：在文件中直接定义
+interface CreateUserRequest {
+  username: string;
+  email: string;
+  password: string;
+}
+```
+
+### 2.2 新导入方式
+
+```typescript
+// ✅ 新方式：从统一类型中心导入
+import { User, Product, Order } from '@shared/types';
+import { CreateUserDTO, UpdateUserDTO } from '@shared/types';
+import { CreateUserSchema } from '@shared/schemas';
+
+// ✅ 新方式：使用 Schema 验证
+const validated = CreateUserSchema.parse(requestBody);
+```
+
+### 2.3 迁移步骤
+
+```bash
+# 1. 查找需要迁移的文件
+grep -r "from '../models" server/src --include="*.ts"
+
+# 2. 替换导入语句
+# 将 '../models/User' 替换为 '@shared/types'
+
+# 3. 运行类型检查
+cd server && npx tsc --noEmit
+
+# 4. 修复类型错误
+```
+
+---
+
+## 3. 前端迁移
+
+### 3.1 旧导入方式
+
+```typescript
+// ❌ 旧方式：从本地 types 导入
+import { User } from '../types/user';
+import { Product } from '../types/product';
+
+// ❌ 旧方式：在组件中定义类型
+interface UserCardProps {
+  user: {
+    id: string;
+    name: string;
+  };
+}
+```
+
+### 3.2 新导入方式
+
+```typescript
+// ✅ 新方式：从 server 类型中心导入
+import { User, Product } from '@shared/types';
+import { UserDTO, ProductDTO } from '@shared/types';
+
+// ✅ 新方式：使用类型化的 Props
+import { User } from '@shared/types';
+
+interface UserCardProps {
+  user: User;
+  onEdit?: (user: User) => void;
+}
+```
+
+### 3.3 迁移步骤
+
+```bash
+# 1. 查找需要迁移的文件
+grep -r "from '../types" dashboard/src --include="*.ts" --include="*.tsx"
+
+# 2. 替换导入语句
+# 将 '../types/user' 替换为 '@shared/types'
+
+# 3. 运行类型检查
+cd dashboard && npx tsc --noEmit
+
+# 4. 修复类型错误
+```
+
+---
+
+## 4. 插件端迁移
+
+### 4.1 旧导入方式
+
+```typescript
+// ❌ 旧方式：在插件中重复定义类型
+interface Message {
+  type: string;
+  payload: any;
+}
+```
+
+### 4.2 新导入方式
+
+```typescript
+// ✅ 新方式：从 server 类型中心导入
+import { BaseMessage, MessageResponse } from '../../server/src/shared/types';
+import { BaseMessageSchema } from '../../server/src/shared/schemas';
+
+// ✅ 新方式：使用 Schema 验证
+const validated = BaseMessageSchema.parse(message);
+```
+
+---
+
+## 5. 常见迁移场景
+
+### 5.1 类型扩展
+
+```typescript
+// ❌ 旧方式：扩展本地类型
+interface User {
+  id: string;
+  name: string;
+}
+
+interface UserWithRole extends User {
+  role: string;
+}
+
+// ✅ 新方式：从 Schema 扩展
+import { User } from '@shared/types';
+import { z } from 'zod';
+
+const UserWithRoleSchema = UserSchema.extend({
+  role: z.string()
+});
+
+type UserWithRole = z.infer<typeof UserWithRoleSchema>;
+```
+
+### 5.2 类型组合
+
+```typescript
+// ❌ 旧方式：手动组合类型
+interface CreateUserRequest {
+  username: string;
+  email: string;
+}
+
+interface UpdateUserRequest {
+  username?: string;
+  email?: string;
+}
+
+// ✅ 新方式：使用 Schema 工具
+import { UserSchema } from '@shared/schemas';
+import { z } from 'zod';
+
+const CreateUserSchema = UserSchema.pick({
+  username: true,
+  email: true,
+  password: true
+});
+
+const UpdateUserSchema = UserSchema.partial().pick({
+  username: true,
+  email: true
+});
+```
+
+### 5.3 API 响应类型
+
+```typescript
+// ❌ 旧方式：手动定义响应类型
+interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+
+// ✅ 新方式：使用统一响应类型
+import { ApiResponse, PaginatedResult } from '@shared/types';
+import { SuccessResponseSchema, ErrorResponseSchema } from '@shared/schemas';
+```
+
+---
+
+## 6. 迁移检查清单
+
+### 6.1 后端检查
+
+- [ ] 所有 Service 层使用 `@shared/types` 导入
+- [ ] 所有 Controller 层使用 `@shared/schemas` 验证
+- [ ] 所有 Model 层类型从 Schema 推导
+- [ ] 运行 `npx tsc --noEmit` 无错误
+
+### 6.2 前端检查
+
+- [ ] 所有组件使用 `@shared/types` 导入
+- [ ] 所有 API 调用使用类型化的 DTO
+- [ ] 所有 Props 使用类型中心定义
+- [ ] 运行 `npx tsc --noEmit` 无错误
+
+### 6.3 插件端检查
+
+- [ ] 所有消息类型从 server 导入
+- [ ] 所有消息使用 Schema 验证
+- [ ] 运行 `npx tsc --noEmit` 无错误
+
+---
+
+## 7. 迁移脚本
+
+### 7.1 自动替换脚本
+
+```bash
+#!/bin/bash
+# migrate-types.sh
+
+# 后端迁移
+find server/src -name "*.ts" -type f -exec sed -i \
+  -e "s|from '../models/User'|from '@shared/types'|g" \
+  -e "s|from '../models/Product'|from '@shared/types'|g" \
+  -e "s|from '../models/Order'|from '@shared/types'|g" \
+  {} +
+
+# 前端迁移
+find dashboard/src -name "*.ts" -o -name "*.tsx" -type f -exec sed -i \
+  -e "s|from '../types/user'|from '@shared/types'|g" \
+  -e "s|from '../types/product'|from '@shared/types'|g" \
+  {} +
+
+echo "Migration complete. Please run: npx tsc --noEmit"
+```
+
+### 7.2 类型检查脚本
+
+```bash
+#!/bin/bash
+# check-types.sh
+
+echo "Checking server types..."
+cd server && npx tsc --noEmit --skipLibCheck
+SERVER_EXIT=$?
+
+echo "Checking dashboard types..."
+cd ../dashboard && npx tsc --noEmit --skipLibCheck
+DASHBOARD_EXIT=$?
+
+echo "Checking extension types..."
+cd ../extension && npx tsc --noEmit --skipLibCheck
+EXTENSION_EXIT=$?
+
+if [ $SERVER_EXIT -ne 0 ] || [ $DASHBOARD_EXIT -ne 0 ] || [ $EXTENSION_EXIT -ne 0 ]; then
+  echo "❌ Type check failed"
+  exit 1
+else
+  echo "✅ All type checks passed"
+  exit 0
+fi
+```
+
+---
+
+## 8. 常见问题
+
+### Q1: 导入路径报错怎么办？
+
+**A**: 检查 `tsconfig.json` 中的 `paths` 配置是否正确：
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@shared/types": ["../server/src/shared/types"],
+      "@shared/schemas": ["../server/src/shared/schemas"]
+    }
+  }
+}
+```
+
+### Q2: 类型不匹配怎么办？
+
+**A**: 确保使用 Schema 推导类型，而不是手动定义：
+
+```typescript
+// ❌ 手动定义可能与 Schema 不一致
+interface User {
+  id: string;
+  name: string;
+}
+
+// ✅ 从 Schema 推导，保证一致
+import { User } from '@shared/types';
+// User 类型来自 UserSchema
+```
+
+### Q3: 运行时验证失败怎么办？
+
+**A**: 使用 Schema 的 `parse` 或 `safeParse` 方法：
+
+```typescript
+import { CreateUserSchema } from '@shared/schemas';
+
+// 安全解析
+const result = CreateUserSchema.safeParse(data);
+if (!result.success) {
+  console.error(result.error.issues);
+  return;
+}
+const validated = result.data;
+```
+
+---
+
+## 9. 版本兼容
+
+### 9.1 向后兼容
+
+旧的导入路径仍然可用，但建议迁移：
+
+```typescript
+// 仍然可用（向后兼容）
+import { User } from '../types/domain/User';
+
+// 推荐使用（新方式）
+import { User } from '@shared/types';
+```
+
+### 9.2 废弃计划
+
+| 版本 | 状态 | 说明 |
+|------|------|------|
+| 1.0.0 | 当前 | 新旧方式并存 |
+| 1.1.0 | 计划 | 标记旧方式为 deprecated |
+| 2.0.0 | 计划 | 移除旧的类型定义文件 |
+
+---
+
+*迁移完成后，请更新 `server/src/shared/types/version.ts` 中的版本号*