create-pardx-scaffold 0.1.0

package/template/packages/contracts/ERROR-MIGRATION.md

@@ -0,0 +1,179 @@
+# Error System Migration Guide
+
+## Overview
+
+This guide helps migrate from the old error handling system to the new typed error system in `@repo/contracts`.
+
+## Key Changes
+
+### Before (Old System)
+```typescript
+// Backend: apps/api/libs/common/enums/code.enum.ts
+import { ApiErrorCode, ErrorMessageEnums } from '@/enums/code.enum';
+import { ApiException } from '@/filter/exception/api.exception';
+
+// Throwing errors
+throw new ApiException(ErrorMessageEnums.TeamNotFound);
+```
+
+### After (New System)
+```typescript
+// Backend: Import from @repo/contracts
+import { TeamErrorCode, apiError } from '@repo/contracts/errors';
+import { ApiExceptionV2 } from '@/filter/exception/api-exception-v2';
+
+// Method 1: Using apiError helper
+throw apiError(TeamErrorCode.TeamNotFound);
+
+// Method 2: Using ApiExceptionV2 directly
+throw ApiExceptionV2.fromCode(TeamErrorCode.TeamNotFound, { teamId: '123' });
+```
+
+## Migration Steps
+
+### Step 1: Update Imports
+
+Replace old imports with new ones:
+
+```typescript
+// Old
+import { ApiErrorCode, ErrorMessageEnums } from '@/enums/code.enum';
+
+// New
+import { TeamErrorCode, UserErrorCode, SpaceErrorCode } from '@repo/contracts/errors';
+// Or import specific domain
+import { TeamErrorCode } from '@repo/contracts/errors/domains/team.errors';
+```
+
+### Step 2: Update Exception Throwing
+
+Replace `ApiException` with `ApiExceptionV2`:
+
+```typescript
+// Old
+throw new ApiException(ErrorMessageEnums.TeamNotFound);
+throw new ApiException(ErrorMessageEnums.TeamNotFound, { teamId });
+
+// New
+import { apiError } from '@repo/contracts/errors';
+throw apiError(TeamErrorCode.TeamNotFound);
+throw apiError(TeamErrorCode.TeamNotFound, { teamId });
+```
+
+### Step 3: Update i18n Messages
+
+Move error messages from `test.message.*` to `errors.{domain}.*`:
+
+```json
+// Old: apps/api/libs/i18n/en/test.json
+{
+  "message": {
+    "TeamNotFound": "Team not found"
+  }
+}
+
+// New: apps/api/libs/i18n/en/errors.json
+{
+  "team": {
+    "teamNotFound": "Team not found"
+  }
+}
+```
+
+### Step 4: Update API Contracts (Optional)
+
+Add typed error responses to contracts:
+
+```typescript
+import { TeamErrorCode } from '../errors/domains/team.errors';
+import { createTypedErrorResponse } from '../errors/error-response';
+
+export const teamContract = c.router({
+  getInfo: {
+    method: 'GET',
+    path: '/:teamId',
+    responses: {
+      200: ApiResponseSchema(TeamInfoSchema),
+      400: createTypedErrorResponse([
+        TeamErrorCode.TeamNotFound,
+        TeamErrorCode.TeamMemberViewNoPermission,
+      ] as const),
+    },
+  },
+});
+```
+
+## Error Code Organization
+
+Error codes are now organized by domain:
+
+| Domain | Prefix | File |
+|--------|--------|------|
+| Team | 1xx | `team.errors.ts` |
+| User | 2xx | `user.errors.ts` |
+| Space | 3xx | `space.errors.ts` |
+| Folder | 4xx | `folder.errors.ts` |
+| File | 5xx | `file.errors.ts` |
+| Comment | 56x-57x | `comment.errors.ts` |
+| Payment | 7xx | `payment.errors.ts` |
+| Common | 9xx | `common.errors.ts` |
+
+## Backward Compatibility
+
+The old system is still supported for gradual migration:
+
+- `ErrorMessageEnums` is auto-generated from `@repo/contracts`
+- `ApiException` continues to work alongside `ApiExceptionV2`
+- Both i18n namespaces are checked (new first, then old)
+
+## Frontend Usage
+
+```typescript
+import {
+  TeamErrorCode,
+  handleApiError,
+  createErrorHandler
+} from '@repo/contracts/errors';
+
+// Handle errors with typed handlers
+const errorHandler = createErrorHandler({
+  [TeamErrorCode.TeamNotFound]: {
+    message: 'Team not found',
+    action: () => router.push('/teams'),
+  },
+  [TeamErrorCode.TeamOpNoPermission]: {
+    message: 'No permission',
+  },
+});
+
+// In API call
+try {
+  await api.team.getInfo({ teamId });
+} catch (error) {
+  const result = handleApiError(error.code);
+  toast.error(result.message);
+  result.action?.();
+}
+```
+
+## Best Practices
+
+1. **Use domain-specific error codes** - Import from the specific domain file
+2. **Include error data** - Pass relevant data to `apiError()` for debugging
+3. **Add typed responses** - Document expected errors in API contracts
+4. **Use new i18n namespace** - Use `errors.{domain}.{key}` for new messages
+5. **Gradual migration** - Migrate one module at a time
+
+## Troubleshooting
+
+### Error: "Unknown error code"
+- Ensure the error code is exported from `@repo/contracts/errors`
+- Check that `@repo/contracts` is built: `pnpm --filter @repo/contracts build`
+
+### Error: "i18n key not found"
+- Check that the error message exists in `errors.json`
+- Ensure the domain and key match: `errors.team.teamNotFound`
+
+### TypeScript errors
+- Run `pnpm build` to regenerate types
+- Check that imports use correct paths

package/template/packages/contracts/README.md

@@ -0,0 +1,203 @@
+# @repo/contracts - API 契约
+
+使用 ts-rest 实现的前后端类型安全 API 契约。
+
+## 安装
+
+```json
+{
+  "dependencies": {
+    "@repo/contracts": "workspace:*"
+  }
+}
+```
+
+## 使用
+
+### 前端使用
+
+```typescript
+import { teamContract } from '@repo/contracts/api';
+import { initClient } from '@ts-rest/core';
+
+const client = initClient(teamContract, {
+  baseUrl: '/api',
+});
+
+const { data } = await client.getInfo({ params: { teamId: '123' } });
+```
+
+### 后端使用
+
+```typescript
+import { teamContract } from '@repo/contracts/api';
+import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
+import { success } from '@/common/ts-rest';
+
+@Controller()
+export class TeamController {
+  @TsRestHandler(teamContract.getInfo)
+  async getInfo() {
+    return tsRestHandler(teamContract.getInfo, async ({ params }) => {
+      const team = await this.teamService.getInfo(params.teamId);
+      return success(team);
+    });
+  }
+}
+```
+
+## 错误码系统
+
+错误码按业务域组织，从 `@repo/contracts/errors` 导出。
+
+### 错误码域
+
+| 域      | 前缀    | 导入               |
+| ------- | ------- | ------------------ |
+| Team    | 1xx     | `TeamErrorCode`    |
+| User    | 2xx     | `UserErrorCode`    |
+| Space   | 3xx     | `SpaceErrorCode`   |
+| Folder  | 4xx     | `FolderErrorCode`  |
+| File    | 5xx     | `FileErrorCode`    |
+| Comment | 56x-57x | `CommentErrorCode` |
+| Payment | 7xx     | `PaymentErrorCode` |
+| Common  | 9xx     | `CommonErrorCode`  |
+
+### 后端错误处理
+
+```typescript
+import { TeamErrorCode, apiError } from '@repo/contracts/errors';
+import { ApiExceptionV2 } from '@/filter/exception/api-exception-v2';
+
+// 简单错误
+throw apiError(TeamErrorCode.TeamNotFound);
+
+// 带数据的错误
+throw apiError(TeamErrorCode.TeamNotFound, { teamId: '123' });
+
+// 直接使用 ApiExceptionV2
+throw ApiExceptionV2.fromCode(TeamErrorCode.TeamNotFound);
+```
+
+### 前端错误处理
+
+```typescript
+import {
+  TeamErrorCode,
+  handleApiError,
+  createErrorHandler,
+} from '@repo/contracts/errors';
+
+// 创建类型安全的错误处理器
+const teamErrorHandler = createErrorHandler({
+  [TeamErrorCode.TeamNotFound]: {
+    message: '团队不存在',
+    action: () => router.push('/teams'),
+  },
+  [TeamErrorCode.TeamOpNoPermission]: {
+    message: '您没有权限执行此操作',
+  },
+});
+
+// 处理 API 响应
+const handleTeamError = (errorCode: number) => {
+  const result = teamErrorHandler(errorCode);
+  if (result) {
+    toast.error(result.message);
+    result.action?.();
+  }
+};
+```
+
+### 契约中的类型化错误响应
+
+```typescript
+import { TeamErrorCode } from '../errors/domains/team.errors';
+import { createTypedErrorResponse } from '../errors/error-response';
+
+export const teamContract = c.router({
+  getInfo: {
+    method: 'GET',
+    path: '/:teamId',
+    responses: {
+      200: createApiResponse(TeamInfoSchema),
+      400: createTypedErrorResponse([
+        TeamErrorCode.TeamNotFound,
+        TeamErrorCode.TeamMemberViewNoPermission,
+      ] as const),
+    },
+  },
+});
+```
+
+### 验证 Schema
+
+```typescript
+import { TeamNameSchema, PaginationQuerySchema } from '@repo/contracts/schemas';
+
+// 在表单中使用
+const teamForm = useForm({
+  resolver: zodResolver(
+    z.object({
+      name: TeamNameSchema,
+    }),
+  ),
+});
+
+// 在 API 查询中使用
+const query = PaginationQuerySchema.parse(searchParams);
+```
+
+## 目录结构
+
+```
+src/
+├── api/                    # API 契约
+│   ├── team.contract.ts
+│   ├── user.contract.ts
+│   ├── space.contract.ts
+│   └── index.ts
+├── errors/                 # 错误码系统
+│   ├── domains/            # 域错误定义
+│   │   ├── team.errors.ts
+│   │   ├── user.errors.ts
+│   │   └── ...
+│   ├── codes.ts            # 统一错误码
+│   ├── error-response.ts   # 类型化错误响应辅助函数
+│   └── index.ts
+├── schemas/                # Zod Schema
+│   ├── team.schema.ts
+│   ├── user.schema.ts
+│   └── ...
+├── base.ts                 # 基础 Schema (createApiResponse 等)
+└── index.ts                # 主导出
+```
+
+## 构建
+
+```bash
+pnpm --filter @repo/contracts build
+```
+
+## 迁移
+
+从旧错误系统迁移请参阅：
+
+- [错误系统迁移指南](./ERROR-MIGRATION.md) - 从旧系统迁移到新系统的指南
+- [错误码管理优化方案](./错误码管理方案.md) - 错误码枚举字符串化优化方案及实施情况
+
+### 错误码系统状态
+
+✅ **已完成**：
+
+- 所有错误码已迁移到 `@packages/contracts/src/errors`
+- 错误码枚举已改为字符串格式（避免打包类型问题）
+- i18n 错误消息已迁移到 `errors.json`
+- 过期文件已清理
+
+✅ **已完成**：
+
+- 所有文件已迁移到新系统或桥接文件
+- `code.enum.ts` 已无任何直接引用（可安全删除）
+
+📊 **实施进度**：**100%** ✅

package/template/packages/contracts/jest.config.js

@@ -0,0 +1,11 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.ts', '**/*.spec.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts', '!src/**/index.ts'],
+  coverageDirectory: 'coverage',
+  verbose: true,
+};

package/template/packages/contracts/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@repo/contracts",
+  "version": "0.1.0",
+  "private": true,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "clean": "rimraf dist",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./base": {
+      "types": "./dist/base.d.ts",
+      "default": "./dist/base.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "default": "./dist/schemas/index.js"
+    },
+    "./schemas/*": {
+      "types": "./dist/schemas/*.d.ts",
+      "default": "./dist/schemas/*.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "default": "./dist/api/index.js"
+    },
+    "./api/*": {
+      "types": "./dist/api/*.d.ts",
+      "default": "./dist/api/*.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "default": "./dist/errors/index.js"
+    },
+    "./errors/*": {
+      "types": "./dist/errors/*.d.ts",
+      "default": "./dist/errors/*.js"
+    }
+  },
+  "dependencies": {
+    "@repo/config": "workspace:*",
+    "@ts-rest/core": "^3.51.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/minimatch": "^6.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.3",
+    "typescript": "^5"
+  }
+}

package/template/packages/contracts/src/api/analytics.contract.ts

@@ -0,0 +1,45 @@
+import { initContract } from '@ts-rest/core';
+import { createApiResponse } from '../base';
+import {
+  AnalyticsEventSchema,
+  BatchAnalyticsEventsSchema,
+  AnalyticsResponseSchema,
+} from '../schemas/analytics.schema';
+
+const c = initContract();
+
+/**
+ * Analytics API Contract
+ * 用于追踪用户行为和产品指标
+ */
+export const analyticsContract = c.router({
+  /**
+   * Track a single analytics event
+   * 追踪单个事件
+   */
+  track: {
+    method: 'POST',
+    path: '/analytics/track',
+    body: AnalyticsEventSchema,
+    responses: {
+      200: createApiResponse(AnalyticsResponseSchema),
+    },
+    summary: '追踪单个事件',
+    description: '记录单个用户行为事件',
+  },
+
+  /**
+   * Track multiple analytics events in batch
+   * 批量追踪事件
+   */
+  trackBatch: {
+    method: 'POST',
+    path: '/analytics/track/batch',
+    body: BatchAnalyticsEventsSchema,
+    responses: {
+      200: createApiResponse(AnalyticsResponseSchema),
+    },
+    summary: '批量追踪事件',
+    description: '批量记录多个用户行为事件，提高性能',
+  },
+});

package/template/packages/contracts/src/api/download.contract.ts

@@ -0,0 +1,66 @@
+import { initContract } from '@ts-rest/core';
+import { z } from 'zod';
+import { ApiResponseSchema } from '../base';
+import { CommonErrorCode } from '../errors/domains/common.errors';
+import { createTypedErrorResponse } from '../errors/error-response';
+import {
+  DownloadFileParamsSchema,
+  DownloadFileQuerySchema,
+  DownloadFileResponseSchema,
+  BatchDownloadRequestSchema,
+  BatchDownloadResponseSchema,
+} from '../schemas/download.schema';
+
+const c = initContract();
+
+/**
+ * Download API Contract
+ *
+ * RESTful Changes from V1:
+ * - GET /files/:fileId (was POST /space/:spaceId/file/:fileId/:operationType)
+ * - POST /batch (unchanged path, cleaner body)
+ */
+export const downloadContract = c.router(
+  {
+    // GET /space/spaces/:spaceId/files/:fileId - Download single file
+    // V1: POST /download/space/:spaceId/file/:fileId/:operationType
+    // V2: GET /space/:spaceId/files/:fileId?operationType=...
+    getFile: {
+      method: 'GET',
+      path: '/spaces/:spaceId/files/:fileId/op',
+      pathParams: z.object({
+        spaceId: z.string().uuid(),
+        fileId: z.string().uuid(),
+      }),
+      query: z.object({
+        operationType: z
+          .enum(['fileViewOp', 'fileDownloadOp'])
+          .optional()
+          .default('fileDownloadOp'),
+      }),
+      responses: {
+        200: ApiResponseSchema(DownloadFileResponseSchema),
+        401: createTypedErrorResponse([CommonErrorCode.UnAuthorized] as const),
+      },
+      summary: 'Get download URL for a single file',
+    },
+    // POST /download/batch - Batch download files
+    // V1: POST /download/batch
+    // V2: POST /download/batch (same path, cleaner schema)
+    batchDownload: {
+      method: 'POST',
+      path: '/batch',
+      body: BatchDownloadRequestSchema,
+      responses: {
+        200: ApiResponseSchema(BatchDownloadResponseSchema),
+        401: createTypedErrorResponse([CommonErrorCode.UnAuthorized] as const),
+      },
+      summary: 'Get download URL for multiple files',
+    },
+  },
+  {
+    pathPrefix: '/download',
+  },
+);
+
+export type DownloadContract = typeof downloadContract;

package/template/packages/contracts/src/api/index.ts

@@ -0,0 +1,12 @@
+export * from './analytics.contract';
+export * from './download.contract';
+export * from './message.contract';
+export * from './risk-words.contract';
+export * from './setting.contract';
+export * from './sign.contract';
+export * from './sms.contract';
+export * from './system.contract';
+export * from './task.contract';
+export * from './uploader.contract';
+export * from './user.contract';
+export * from './webhook.contract';

package/template/packages/contracts/src/api/message.contract.ts

@@ -0,0 +1,70 @@
+/**
+ * Message API Contract
+ * 消息 API 契约定义
+ *
+ * RESTful 变更说明：
+ * - POST /message/set/read → PATCH /messages/read (设置消息已读)
+ */
+
+import { initContract } from '@ts-rest/core';
+import { z } from 'zod';
+import { createApiResponse } from '../base';
+import {
+    MessageListResponseSchema,
+    MessageListQuerySchema,
+    SetMessageReadRequestSchema,
+    UnreadCountResponseSchema,
+} from '../schemas/message.schema';
+
+const c = initContract();
+
+export const messageContract = c.router(
+    {
+        /**
+         * 获取消息列表
+         * GET /messages
+         */
+        list: {
+            method: 'GET',
+            path: '/messages',
+            query: MessageListQuerySchema,
+            responses: {
+                200: createApiResponse(MessageListResponseSchema),
+            },
+            summary: '获取消息列表',
+        },
+
+        /**
+         * 设置消息已读
+         * PATCH /messages/read
+         * V1: POST /message/set/read
+         */
+        setRead: {
+            method: 'PATCH',
+            path: '/messages/read',
+            body: SetMessageReadRequestSchema,
+            responses: {
+                200: createApiResponse(z.void().nullable()),
+            },
+            summary: '设置消息已读',
+        },
+
+        /**
+         * 获取未读消息数量
+         * GET /messages/unread/count
+         */
+        getUnreadCount: {
+            method: 'GET',
+            path: '/messages/unread/count',
+            responses: {
+                200: createApiResponse(UnreadCountResponseSchema),
+            },
+            summary: '获取未读消息数量',
+        },
+    },
+    {
+        pathPrefix: '/message',
+    },
+);
+
+export type MessageContract = typeof messageContract;

package/template/packages/contracts/src/api/risk-words.contract.ts

@@ -0,0 +1,44 @@
+import { initContract } from '@ts-rest/core';
+import { ApiResponseSchema } from '../base';
+import {
+  CheckRiskWordRequestSchema,
+  CheckRiskWordResponseSchema,
+  VolcengineRiskWordDetectionRequestSchema,
+  VolcengineRiskWordDetectionResponseSchema,
+} from '../schemas/risk-words.schema';
+
+const c = initContract();
+
+/**
+ * Risk Words API Contract
+ */
+export const riskWordsContract = c.router(
+  {
+    // POST /risk-words/check - Check risk word
+    checkRiskWord: {
+      method: 'POST',
+      path: '/check',
+      body: CheckRiskWordRequestSchema,
+      responses: {
+        200: ApiResponseSchema(CheckRiskWordResponseSchema),
+      },
+      summary: 'Check risk word in text',
+    },
+
+    // POST /risk-words/volcengine/detection - Volcengine risk word detection
+    volcengineDetection: {
+      method: 'POST',
+      path: '/volcengine/detection',
+      body: VolcengineRiskWordDetectionRequestSchema,
+      responses: {
+        200: ApiResponseSchema(VolcengineRiskWordDetectionResponseSchema),
+      },
+      summary: 'Volcengine text risk detection',
+    },
+  },
+  {
+    pathPrefix: '/risk-words',
+  },
+);
+
+export type RiskWordsContract = typeof riskWordsContract;