create-pardx-scaffold 0.1.0

package/template/packages/config/eslint/react-internal.js

@@ -0,0 +1,41 @@
+import js from "@eslint/js"
+import eslintConfigPrettier from "eslint-config-prettier"
+import pluginReact from "eslint-plugin-react"
+import pluginReactHooks from "eslint-plugin-react-hooks"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+import { config as baseConfig } from "./base.js"
+
+/**
+ * A custom ESLint configuration for libraries that use React.
+ *
+ * @type {import("eslint").Linter.Config} */
+export const config = [
+  ...baseConfig,
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  pluginReact.configs.flat.recommended,
+  {
+    languageOptions: {
+      ...pluginReact.configs.flat.recommended.languageOptions,
+      globals: {
+        ...globals.serviceworker,
+        ...globals.browser,
+      },
+    },
+  },
+  {
+    plugins: {
+      "react-hooks": pluginReactHooks,
+    },
+    settings: { react: { version: "detect" } },
+    rules: {
+      ...pluginReactHooks.configs.recommended.rules,
+      // React scope no longer necessary with new JSX transform.
+      "react/react-in-jsx-scope": "off",
+      "react/prop-types": "off",
+    },
+  },
+]

package/template/packages/config/eslint.config.mjs

@@ -0,0 +1,26 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([
+    ".next/**",
+    "out/**",
+    "build/**",
+    "dist/**",
+    "node_modules/**",
+    "*.config.js",
+    "*.config.mjs",
+    "*.config.ts"
+  ]),
+  {
+    rules: {
+      "react/no-children-prop": "off",
+    },
+  },
+]);
+
+export default eslintConfig;
+

package/template/packages/config/eslint.nestjs.config.mjs

@@ -0,0 +1,62 @@
+/**
+ * ESLint configuration for NestJS projects
+ * Usage: import and spread in your eslint config
+ */
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+import eslintPluginPrettier from "eslint-plugin-prettier/recommended";
+
+const nestjsConfig = tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  eslintPluginPrettier,
+  {
+    languageOptions: {
+      ecmaVersion: 2021,
+      sourceType: "module",
+      parserOptions: {
+        project: "./tsconfig.json",
+      },
+      globals: {
+        node: true,
+        jest: true,
+      },
+    },
+    rules: {
+      "@typescript-eslint/interface-name-prefix": "off",
+      "@typescript-eslint/explicit-function-return-type": "off",
+      "@typescript-eslint/explicit-module-boundary-types": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+      "@typescript-eslint/no-require-imports": "off",
+      "prettier/prettier": [
+        "error",
+        {
+          semi: true,
+          trailingComma: "all",
+          singleQuote: true,
+          printWidth: 100,
+          tabWidth: 2,
+        },
+      ],
+    },
+  },
+  {
+    ignores: [
+      "dist/**",
+      "node_modules/**",
+      "*.js",
+      "*.mjs",
+      "coverage/**",
+      ".turbo/**",
+    ],
+  }
+);
+
+export default nestjsConfig;

package/template/packages/config/index.ts

@@ -0,0 +1,2 @@
+// Shared configuration exports
+export { default as eslintConfig } from './eslint.config.mjs';

package/template/packages/config/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@repo/config",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./eslint": "./eslint.config.mjs",
+    "./eslint-nestjs": "./eslint.nestjs.config.mjs",
+    "./eslint/base": "./eslint/base.js",
+    "./eslint/next-js": "./eslint/next.js",
+    "./eslint/react-internal": "./eslint/react-internal.js",
+    "./prettier": "./prettier.config.mjs",
+    "./tailwind": "./tailwind.config.ts",
+    "./tsconfig": "./tsconfig.json",
+    "./typescript/base.json": "./typescript/base.json",
+    "./typescript/nextjs.json": "./typescript/nextjs.json",
+    "./typescript/react-library.json": "./typescript/react-library.json",
+    "./postcss": "./postcss.config.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@next/eslint-plugin-next": "^15.4.5",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@typescript-eslint/eslint-plugin": "^8.39.0",
+    "@typescript-eslint/parser": "^8.39.0",
+    "eslint": "^9",
+    "eslint-config-next": "16.0.7",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-only-warn": "^1.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-turbo": "^2.5.5",
+    "globals": "^15.15.0",
+    "prettier": "^3.3.3",
+    "tailwindcss": "^4",
+    "typescript": "^5",
+    "typescript-eslint": "^8.18.0"
+  }
+}

package/template/packages/config/postcss.config.mjs

@@ -0,0 +1,8 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;
+

package/template/packages/config/prettier.config.mjs

@@ -0,0 +1,14 @@
+/** @type {import("prettier").Config} */
+const config = {
+  semi: true,
+  trailingComma: "all",
+  singleQuote: true,
+  printWidth: 100,
+  tabWidth: 2,
+  useTabs: false,
+  bracketSpacing: true,
+  arrowParens: "always",
+  endOfLine: "lf",
+};
+
+export default config;

package/template/packages/config/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}

package/template/packages/config/typescript/base.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Default",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "incremental": false,
+    "isolatedModules": true,
+    "lib": ["es2022", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleDetection": "force",
+    "moduleResolution": "NodeNext",
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022"
+  }
+}

package/template/packages/config/typescript/nextjs.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Next.js",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "plugins": [{ "name": "next" }],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowJs": true,
+    "jsx": "preserve"
+  }
+}

package/template/packages/config/typescript/react-library.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "React Library",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}

package/template/packages/constants/README.md

@@ -0,0 +1,111 @@
+# @repo/constants - 共享常量
+
+前后端共享的常量定义。
+
+## 安装
+
+```json
+{
+  "dependencies": {
+    "@repo/constants": "workspace:*"
+  }
+}
+```
+
+## 使用
+
+### 前端
+
+```typescript
+import { HTTP_STATUS, ERROR_CODES, LIMITS } from '@repo/constants';
+```
+
+### 后端
+
+```typescript
+import { HTTP_STATUS, ERROR_CODES, LIMITS } from '@repo/constants';
+```
+
+## 常量类型
+
+### HTTP 状态
+
+```typescript
+export const HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  INTERNAL_ERROR: 500,
+} as const;
+```
+
+### 错误码
+
+```typescript
+export const ERROR_CODES = {
+  // 认证错误
+  AUTH_INVALID_TOKEN: 'AUTH_001',
+  AUTH_EXPIRED_TOKEN: 'AUTH_002',
+  AUTH_INSUFFICIENT_PERMISSIONS: 'AUTH_003',
+
+  // 业务错误
+  RESOURCE_NOT_FOUND: 'BIZ_001',
+  RESOURCE_ALREADY_EXISTS: 'BIZ_002',
+  INVALID_OPERATION: 'BIZ_003',
+} as const;
+```
+
+### 限制常量
+
+```typescript
+export const LIMITS = {
+  MAX_FILE_SIZE: 10 * 1024 * 1024, // 10MB
+  MAX_PAGE_SIZE: 100,
+  DEFAULT_PAGE_SIZE: 20,
+  MAX_UPLOAD_FILES: 10,
+} as const;
+```
+
+## 添加新常量
+
+1. 在 `src/index.ts` 中定义常量：
+
+```typescript
+// packages/constants/src/index.ts
+
+// 任务状态
+export const TASK_STATUS = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+} as const;
+
+export type TaskStatus = typeof TASK_STATUS[keyof typeof TASK_STATUS];
+```
+
+## 使用规范
+
+- 使用 `as const` 确保类型推断为字面量类型
+- 常量名使用 UPPER_SNAKE_CASE
+- 导出对应的 TypeScript 类型
+
+```typescript
+// 推荐：导出类型
+export const STATUS = {
+  ACTIVE: 'active',
+  INACTIVE: 'inactive',
+} as const;
+
+export type Status = typeof STATUS[keyof typeof STATUS];
+// => 'active' | 'inactive'
+```
+
+## 构建
+
+```bash
+pnpm --filter @repo/constants build
+```

package/template/packages/constants/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@repo/constants",
+  "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"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@repo/config": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/minimatch": "^6.0.0",
+    "typescript": "^5"
+  }
+}

package/template/packages/constants/src/index.ts

@@ -0,0 +1,243 @@
+/**
+ * Shared constants between frontend and backend
+ */
+
+// HTTP Status codes
+export const HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  INTERNAL_SERVER_ERROR: 500,
+} as const;
+
+// API Response codes
+export const API_CODE = {
+  SUCCESS: 0,
+  ERROR: -1,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  VALIDATION_ERROR: 422,
+} as const;
+
+// Pagination defaults
+export const PAGINATION = {
+  DEFAULT_PAGE: 1,
+  DEFAULT_PAGE_SIZE: 20,
+  MAX_PAGE_SIZE: 100,
+} as const;
+
+// File upload limits
+export const FILE_LIMITS = {
+  MAX_FILE_SIZE: 50 * 1024 * 1024, // 50MB
+  MAX_IMAGE_SIZE: 10 * 1024 * 1024, // 10MB
+  MAX_VIDEO_SIZE: 500 * 1024 * 1024, // 500MB
+  ALLOWED_IMAGE_TYPES: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+  ALLOWED_VIDEO_TYPES: ['video/mp4', 'video/webm', 'video/quicktime'],
+} as const;
+
+// Auth token keys
+export const AUTH_KEYS = {
+  ACCESS_TOKEN: 'access_token',
+  REFRESH_TOKEN: 'refresh_token',
+  TOKEN_TYPE: 'Bearer',
+} as const;
+
+// Date formats
+export const DATE_FORMAT = {
+  DATE: 'YYYY-MM-DD',
+  DATETIME: 'YYYY-MM-DD HH:mm:ss',
+  TIME: 'HH:mm:ss',
+  ISO: 'YYYY-MM-DDTHH:mm:ss.SSSZ',
+} as const;
+
+// ============================================================================
+// API Versioning Constants
+// ============================================================================
+
+/**
+ * API 版本号常量
+ * 禁止使用 magic string，所有版本号必须从此处引用
+ */
+export const API_VERSION = {
+  /** Version 1 - 初始版本 */
+  V1: '1',
+  /** Version 2 - 未来版本 */
+  V2: '2',
+} as const;
+
+export type ApiVersion = (typeof API_VERSION)[keyof typeof API_VERSION];
+
+/**
+ * 当前默认 API 版本
+ * 新 contract 默认使用此版本
+ */
+export const API_VERSION_DEFAULT = API_VERSION.V1;
+
+/**
+ * 所有支持的 API 版本列表
+ * 用于验证和 CI 校验
+ */
+export const API_VERSIONS_SUPPORTED = [API_VERSION.V1] as const;
+
+// ============================================================================
+// Version Header Constants (端到端版本控制)
+// ============================================================================
+
+/**
+ * API 版本 Header (请求 + 响应)
+ * 前端发送，后端响应
+ */
+export const API_VERSION_HEADER = 'x-api-version' as const;
+
+/**
+ * 前端构建版本 Header (请求)
+ * 格式: YYYY.MM.DD-<hash>-g<generation>
+ * 示例: 2025.03.18-abcdef-g42
+ */
+export const APP_BUILD_HEADER = 'x-app-build' as const;
+
+/**
+ * 后端构建版本 Header (响应)
+ * 格式: YYYY.MM.DD-<hash>-g<generation>
+ */
+export const SERVER_BUILD_HEADER = 'x-server-build' as const;
+
+/**
+ * 最低兼容前端版本 Header (响应，仅不兼容时返回)
+ */
+export const MIN_APP_BUILD_HEADER = 'x-min-app-build' as const;
+
+// ============================================================================
+// Generation Constants (缓存代际号)
+// ============================================================================
+
+/**
+ * 缓存代际号
+ *
+ * 升级规则:
+ * - API 结构变化 → bump generation
+ * - 数据语义变化 → bump generation
+ * - 不确定是否兼容 → bump generation
+ *
+ * 变更记录:
+ * - g1: 2025.03.18 初始版本
+ */
+export const API_GENERATION = 1;
+
+/**
+ * 最低兼容的前端代际号
+ * 低于此版本的前端必须强制刷新
+ */
+export const MIN_CLIENT_GENERATION = 1;
+
+// ============================================================================
+// Platform Constants (平台标识)
+// ============================================================================
+
+/**
+ * 平台标识 Header
+ */
+export const PLATFORM_HEADER = 'x-platform' as const;
+
+/**
+ * 操作系统 Header
+ */
+export const OS_HEADER = 'x-os' as const;
+
+/**
+ * 设备 ID Header
+ */
+export const DEVICE_ID_HEADER = 'x-device-id' as const;
+
+/**
+ * 埋点追踪 Header
+ */
+export const MPTRAIL_HEADER = 'x-mptrail' as const;
+
+/**
+ * API Contract Header (APP 专用)
+ */
+export const API_CONTRACT_HEADER = 'x-api-contract' as const;
+
+/**
+ * 支持的平台类型
+ */
+export const PLATFORMS = {
+  WEB: 'web',
+  IOS: 'ios',
+  ANDROID: 'android',
+} as const;
+
+export type Platform = (typeof PLATFORMS)[keyof typeof PLATFORMS];
+
+// ============================================================================
+// Contract Constants (合约版本 - APP 专用)
+// ============================================================================
+
+/**
+ * API 合约版本类型
+ * 格式: YYYY-MM (年月)
+ */
+export type ApiContract = '2024-12' | '2025-01';
+
+/**
+ * 合约配置
+ * 每个 Contract 是一套稳定的 API 协议
+ */
+export const CONTRACTS: Record<
+  ApiContract,
+  {
+    /** 最低 APP 构建号 */
+    minBuild: { ios: number; android: number };
+    /** 是否已废弃 (提示升级) */
+    deprecated: boolean;
+    /** 下线日期 (到期后拒绝请求) */
+    sunset: string | null;
+    /** 支持的能力列表 */
+    features: readonly string[];
+  }
+> = {
+  '2024-12': {
+    minBuild: { ios: 1000000, android: 1000000 },
+    deprecated: false,
+    sunset: null,
+    features: ['user-v1'],
+  },
+  '2025-01': {
+    minBuild: { ios: 1000000, android: 1000000 },
+    deprecated: false,
+    sunset: null,
+    features: ['user-v1'],
+  },
+} as const;
+
+/**
+ * 当前 Contract 版本
+ * 新 APP 应使用此版本
+ */
+export const CURRENT_CONTRACT: ApiContract = '2025-01';
+
+/**
+ * 最低支持的 Contract 版本
+ * 低于此版本的 Contract 将被拒绝
+ */
+export const MIN_SUPPORTED_CONTRACT: ApiContract = '2024-12';
+
+// ============================================================================
+// Feature Flags (能力声明)
+// ============================================================================
+
+/**
+ * 能力标识定义
+ * 用于替代版本号判断
+ */
+export const FEATURES = {
+  'user-v1': 'User API V1',
+  'user-v2': 'User API V2 with displayName',
+} as const;
+
+export type Feature = keyof typeof FEATURES;

package/template/packages/constants/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "types": []
+  }
+}

package/template/packages/constants/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "@repo/config/tsconfig",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "paths": {
+    "@repo/config": ["../config"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}