@qlover/create-app 0.7.14 → 0.8.0

package/dist/templates/next-app/docs/zh/validator.md

@@ -0,0 +1,476 @@
+# 验证器开发指南
+
+## 目录
+
+1. [验证器架构概述](#验证器架构概述)
+2. [验证器接口和抽象层](#验证器接口和抽象层)
+3. [具体验证器实现](#具体验证器实现)
+4. [验证器使用示例](#验证器使用示例)
+5. [自定义验证器示例](#自定义验证器示例)
+6. [最佳实践和扩展](#最佳实践和扩展)
+
+## 验证器架构概述
+
+### 1. 整体架构
+
+项目采用分层的验证器架构设计：
+
+```
+应用层                      验证层
+┌──────────────┐          ┌──────────────┐
+│   业务服务   │          │  验证器接口  │
+├──────────────┤          ├──────────────┤
+│   参数处理   │    ◄─────┤  验证器实现  │
+├──────────────┤          ├──────────────┤
+│   错误处理   │          │   验证规则   │
+└──────────────┘          └──────────────┘
+```
+
+### 2. 核心组件
+
+- **验证器接口**：`ValidatorInterface`
+- **验证器实现**：`LoginValidator`, `PaginationValidator` 等
+- **验证规则**：使用 `zod` 库定义的验证规则
+- **错误处理**：统一的错误响应格式
+
+### 3. 验证结果类型
+
+```typescript
+// 验证失败结果
+interface ValidationFaildResult {
+  path: PropertyKey[]; // 验证失败的字段路径
+  message: string; // 错误消息
+}
+
+// 验证器接口
+interface ValidatorInterface {
+  // 验证数据并返回结果
+  validate(
+    data: unknown
+  ): Promise<void | ValidationFaildResult> | void | ValidationFaildResult;
+
+  // 验证数据，成功返回数据，失败抛出错误
+  getThrow(data: unknown): unknown;
+}
+```
+
+## 验证器接口和抽象层
+
+### 1. 基础验证器接口
+
+```typescript
+export interface ValidatorInterface {
+  /**
+   * 验证数据并返回结果
+   * @param data - 要验证的数据
+   * @returns 如果验证通过返回 void，否则返回验证错误
+   */
+  validate(
+    data: unknown
+  ): Promise<void | ValidationFaildResult> | void | ValidationFaildResult;
+
+  /**
+   * 验证数据，成功返回数据，失败抛出错误
+   * @param data - 要验证的数据
+   * @returns 验证通过的数据
+   * @throws {ExecutorError} 如果数据无效，包含验证错误详情
+   */
+  getThrow(data: unknown): unknown;
+}
+```
+
+### 2. 验证规则定义
+
+```typescript
+// 使用 zod 定义验证规则
+const emailSchema = z.string().email({ message: V_EMAIL_INVALID });
+
+const passwordSchema = z
+  .string()
+  .min(6, { message: V_PASSWORD_MIN_LENGTH })
+  .max(50, { message: V_PASSWORD_MAX_LENGTH })
+  .regex(/^\S+$/, { message: V_PASSWORD_SPECIAL_CHARS });
+
+const pageSchema = z
+  .number()
+  .or(z.string())
+  .transform((val) => Number(val))
+  .refine((val) => val > 0, {
+    message: API_PAGE_INVALID
+  });
+```
+
+## 具体验证器实现
+
+### 1. 登录验证器
+
+```typescript
+@injectable()
+export class LoginValidator implements ValidatorInterface {
+  // 验证邮箱
+  validateEmail(data: unknown): void | ValidationFaildResult {
+    const emailResult = emailSchema.safeParse(data);
+    if (!emailResult.success) {
+      return emailResult.error.issues[0];
+    }
+  }
+
+  // 验证密码
+  validatePassword(data: unknown): void | ValidationFaildResult {
+    const passwordResult = passwordSchema.safeParse(data);
+    if (!passwordResult.success) {
+      return passwordResult.error.issues[0];
+    }
+  }
+
+  // 实现验证接口
+  validate(data: unknown): void | ValidationFaildResult {
+    if (typeof data !== 'object' || data === null) {
+      return {
+        path: ['form'],
+        message: V_LOGIN_PARAMS_REQUIRED
+      };
+    }
+
+    const { email, password } = data as Record<string, unknown>;
+
+    // 验证邮箱
+    let validateResult = this.validateEmail(email);
+    if (validateResult != null) {
+      return validateResult;
+    }
+
+    // 验证密码
+    validateResult = this.validatePassword(password);
+    if (validateResult != null) {
+      return validateResult;
+    }
+  }
+
+  // 实现 getThrow 接口
+  getThrow(data: unknown): LoginValidatorData {
+    const result = this.validate(data);
+    if (result == null) {
+      return data as LoginValidatorData;
+    }
+
+    const error: ExtendedExecutorError = new ExecutorError(result.message);
+    error.issues = [result];
+    throw error;
+  }
+}
+```
+
+### 2. 分页验证器
+
+```typescript
+@injectable()
+export class PaginationValidator implements ValidatorInterface {
+  protected defaultPageSize = 10;
+
+  validatePageSize(value: unknown): void | ValidationFaildResult {
+    const result = pageSchema.safeParse(value);
+    if (!result.success) {
+      return result.error.issues[0];
+    }
+  }
+
+  validate(data: unknown): void | ValidationFaildResult {
+    if (typeof data !== 'object' || data === null) {
+      return {
+        path: ['form'],
+        message: 'form is required'
+      };
+    }
+
+    return this.validatePageSize((data as Record<string, unknown>).page);
+  }
+
+  getThrow(data: unknown): PaginationInterface {
+    const result = this.validate(data);
+    if (result) {
+      throw new Error(result.message);
+    }
+
+    return { page: 1, pageSize: this.defaultPageSize };
+  }
+}
+```
+
+## 验证器使用示例
+
+### 1. 在 API 路由中使用
+
+```typescript
+export async function POST(req: NextRequest) {
+  const server = new BootstrapServer();
+
+  const result = await server.execNoError(async ({ parameters: { IOC } }) => {
+    // 获取请求数据
+    const data = await req.json();
+
+    // 使用验证器验证数据
+    const loginValidator = IOC(LoginValidator);
+    const validatedData = loginValidator.getThrow(data);
+
+    // 使用验证后的数据
+    const userService = IOC(UserService);
+    return userService.login(validatedData);
+  });
+
+  if (result instanceof ExecutorError) {
+    return NextResponse.json(new AppErrorApi(result.id, result.message));
+  }
+
+  return NextResponse.json(new AppSuccessApi(result));
+}
+```
+
+### 2. 在服务中使用
+
+```typescript
+@injectable()
+export class UserService {
+  constructor(
+    @inject(LoginValidator) private loginValidator: LoginValidator,
+    @inject(UserRepository) private userRepository: UserRepositoryInterface
+  ) {}
+
+  async validateAndCreateUser(data: unknown): Promise<User> {
+    // 验证数据
+    const validatedData = this.loginValidator.getThrow(data);
+
+    // 使用验证后的数据
+    return this.userRepository.add(validatedData);
+  }
+}
+```
+
+## 自定义验证器示例
+
+### 1. 创建自定义验证规则
+
+```typescript
+// 定义自定义验证规则
+const phoneSchema = z
+  .string()
+  .regex(/^1[3-9]\d{9}$/, { message: '手机号格式不正确' });
+
+const addressSchema = z.object({
+  province: z.string().min(1, '省份不能为空'),
+  city: z.string().min(1, '城市不能为空'),
+  detail: z.string().min(1, '详细地址不能为空')
+});
+
+// 创建用户信息验证器
+@injectable()
+export class UserInfoValidator implements ValidatorInterface {
+  validate(data: unknown): void | ValidationFaildResult {
+    if (typeof data !== 'object' || data === null) {
+      return {
+        path: ['form'],
+        message: '表单数据不能为空'
+      };
+    }
+
+    const { phone, address } = data as Record<string, unknown>;
+
+    // 验证手机号
+    const phoneResult = phoneSchema.safeParse(phone);
+    if (!phoneResult.success) {
+      return phoneResult.error.issues[0];
+    }
+
+    // 验证地址
+    const addressResult = addressSchema.safeParse(address);
+    if (!addressResult.success) {
+      return addressResult.error.issues[0];
+    }
+  }
+
+  getThrow(data: unknown): UserInfoData {
+    const result = this.validate(data);
+    if (result) {
+      throw new ExecutorError(result.message);
+    }
+    return data as UserInfoData;
+  }
+}
+```
+
+### 2. 组合多个验证器
+
+```typescript
+@injectable()
+export class UserProfileValidator implements ValidatorInterface {
+  constructor(
+    @inject(UserInfoValidator) private userInfoValidator: UserInfoValidator,
+    @inject(LoginValidator) private loginValidator: LoginValidator
+  ) {}
+
+  async validate(data: unknown): Promise<void | ValidationFaildResult> {
+    // 验证登录信息
+    const loginResult = this.loginValidator.validate(data);
+    if (loginResult) return loginResult;
+
+    // 验证用户信息
+    const userInfoResult = this.userInfoValidator.validate(data);
+    if (userInfoResult) return userInfoResult;
+  }
+
+  async getThrow(data: unknown): Promise<UserProfileData> {
+    const result = await this.validate(data);
+    if (result) {
+      throw new ExecutorError(result.message);
+    }
+    return data as UserProfileData;
+  }
+}
+```
+
+## 最佳实践和扩展
+
+### 1. 验证器组织
+
+```typescript
+// 1. 按功能模块组织验证器
+src / validators / user / LoginValidator.ts;
+ProfileValidator.ts;
+SettingsValidator.ts;
+product / CreateValidator.ts;
+UpdateValidator.ts;
+order / PlaceOrderValidator.ts;
+```
+
+### 2. 验证规则复用
+
+```typescript
+// 1. 创建共享验证规则
+const commonRules = {
+  email: z.string().email({ message: '邮箱格式不正确' }),
+  phone: z.string().regex(/^1[3-9]\d{9}$/, { message: '手机号格式不正确' }),
+  password: z
+    .string()
+    .min(6, '密码至少6位')
+    .max(50, '密码最多50位')
+    .regex(/^\S+$/, '密码不能包含空格')
+};
+
+// 2. 在验证器中复用
+export class UserValidator implements ValidatorInterface {
+  validate(data: unknown): void | ValidationFaildResult {
+    const schema = z.object({
+      email: commonRules.email,
+      password: commonRules.password,
+      phone: commonRules.phone.optional()
+    });
+
+    const result = schema.safeParse(data);
+    if (!result.success) {
+      return result.error.issues[0];
+    }
+  }
+}
+```
+
+### 3. 错误处理增强
+
+```typescript
+// 1. 创建验证错误基类
+export class ValidationError extends Error {
+  constructor(
+    public readonly path: PropertyKey[],
+    message: string
+  ) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+// 2. 创建字段验证错误
+export class FieldValidationError extends ValidationError {
+  constructor(
+    public readonly field: string,
+    message: string
+  ) {
+    super([field], message);
+    this.name = 'FieldValidationError';
+  }
+}
+
+// 3. 在验证器中使用
+export class EnhancedValidator implements ValidatorInterface {
+  getThrow(data: unknown): unknown {
+    const result = this.validate(data);
+    if (result) {
+      throw new FieldValidationError(result.path.join('.'), result.message);
+    }
+    return data;
+  }
+}
+```
+
+### 4. 异步验证支持
+
+```typescript
+@injectable()
+export class AsyncValidator implements ValidatorInterface {
+  constructor(
+    @inject(UserRepository) private userRepository: UserRepositoryInterface
+  ) {}
+
+  async validate(data: unknown): Promise<void | ValidationFaildResult> {
+    // 基本验证
+    const basicResult = this.validateBasicFields(data);
+    if (basicResult) return basicResult;
+
+    // 异步验证（例如检查邮箱是否已存在）
+    const { email } = data as { email: string };
+    const existingUser = await this.userRepository.getUserByEmail(email);
+
+    if (existingUser) {
+      return {
+        path: ['email'],
+        message: '该邮箱已被注册'
+      };
+    }
+  }
+
+  async getThrow(data: unknown): Promise<unknown> {
+    const result = await this.validate(data);
+    if (result) {
+      throw new ValidationError(result.path, result.message);
+    }
+    return data;
+  }
+}
+```
+
+## 总结
+
+项目的验证器设计遵循以下原则：
+
+1. **接口抽象**：
+   - 清晰的验证器接口定义
+   - 统一的验证结果格式
+   - 可扩展的验证器实现
+
+2. **类型安全**：
+   - 使用 zod 提供类型安全的验证规则
+   - TypeScript 类型定义
+   - 运行时类型检查
+
+3. **错误处理**：
+   - 统一的错误响应格式
+   - 详细的错误信息
+   - 错误链路追踪
+
+4. **可扩展性**：
+   - 支持自定义验证规则
+   - 支持验证器组合
+   - 支持异步验证
+
+5. **最佳实践**：
+   - 验证规则复用
+   - 模块化组织
+   - 错误处理增强

package/dist/templates/next-app/make/generateLocales.ts

@@ -5,18 +5,25 @@ import { i18nConfig } from '../config/i18n';
 
 export async function generateLocales() {
   const locales = i18nConfig.supportedLngs as unknown as string[];
-  const options = readdirSync('./config/Identifier')
-    .map((file) => ({
-      file,
-      name: file.replace('.ts', ''),
-      path: join('./config/Identifier', file)
-    }))
-    .map(({ path }) => ({
-      source: path,
-      // You can use namespace
-      // target: `./public/locales/{{lng}}/{{${name}}}.json`
-      target: `./public/locales/{{lng}}.json`
-    }));
+  const getAllTsFiles = (dir: string): string[] => {
+    const files: string[] = [];
+    const items = readdirSync(dir, { withFileTypes: true });
+
+    for (const item of items) {
+      const fullPath = join(dir, item.name);
+      if (item.isDirectory()) {
+        files.push(...getAllTsFiles(fullPath));
+      } else if (item.isFile() && item.name.endsWith('.ts')) {
+        files.push(fullPath);
+      }
+    }
+    return files;
+  };
+
+  const options = getAllTsFiles('./config/Identifier').map((path) => ({
+    source: path,
+    target: `./public/locales/{{lng}}.json`
+  }));
 
   const ts2Locale = new Ts2Locales(locales);
   for (const value of options) {

package/dist/templates/next-app/migrations/schema/LocalesSchema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { i18nKeySchema } from '@config/i18n/i18nKeyScheam';
+
+export const localesSchema = z.object({
+  id: z.number(),
+  value: i18nKeySchema,
+  en: z.string(),
+  zh: z.string(),
+  description: z.string(),
+  namespace: z.string(),
+  created_at: z.union([z.string(), z.number()]), // Support both string (TIMESTAMPTZ) and number (Unix timestamp)
+  updated_at: z.union([z.string(), z.number()]) // Support both string (TIMESTAMPTZ) and number (Unix timestamp)
+});
+
+export type LocalesSchema = z.infer<typeof localesSchema>;

package/dist/templates/next-app/migrations/sql/1694244000000.sql

@@ -8,3 +8,14 @@ CREATE TABLE IF NOT EXISTS fe_users (
   created_at TIMESTAMPTZ DEFAULT NOW(),
   updated_at TIMESTAMPTZ DEFAULT NOW()
 );
+
+CREATE TABLE IF NOT EXISTS next_app_locales (
+  id BIGSERIAL PRIMARY KEY,
+  value TEXT NOT NULL,
+  en TEXT NOT NULL,
+  zh TEXT NOT NULL,
+  description TEXT,
+  namesapce TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);

package/dist/templates/next-app/package.json

@@ -10,8 +10,8 @@
     "build:staging": "cross-env APP_ENV=staging next build --turbopack",
     "build:prod": "cross-env APP_ENV=production next build --turbopack",
     "start": "next start --port 3101",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "lint": "eslint ./src ./config ./make ./migrations",
+    "lint:fix": "eslint ./src ./config ./make ./migrations --ext .ts,.tsx --fix",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,scss,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,css,scss,md}\"",
     "fix": "npm run lint:fix && npm run format"
@@ -20,9 +20,11 @@
     "@ant-design/icons": "^6.0.0",
     "@ant-design/nextjs-registry": "^1.1.0",
     "@ant-design/v5-patch-for-react-19": "^1.0.3",
+    "@brain-toolkit/antd-blocks": "^0.0.1",
     "@brain-toolkit/antd-theme-override": "^0.0.3",
     "@brain-toolkit/bridge": "^0.0.1",
-    "@qlover/corekit-bridge": "^1.6.4",
+    "@brain-toolkit/react-kit": "^0.1.0",
+    "@qlover/corekit-bridge": "^1.6.5",
     "@qlover/fe-corekit": "^2.1.0",
     "@qlover/slice-store-react": "^1.4.1",
     "@supabase/auth-helpers-nextjs": "^0.10.0",
@@ -31,6 +33,7 @@
     "@types/jsonwebtoken": "^9.0.10",
     "antd": "^5.27.1",
     "clsx": "^2.1.1",
+    "dayjs": "^1.11.18",
     "inversify": "^7.8.1",
     "jsonwebtoken": "^9.0.2",
     "lodash": "^4.17.21",
@@ -38,6 +41,7 @@
     "next-intl": "^4.3.5",
     "next-themes": "^0.4.6",
     "openai": "^5.23.0",
+    "p-limit": "^7.2.0",
     "react": "19.1.0",
     "react-dom": "19.1.0",
     "reflect-metadata": "^0.2.2",