|
2 | 2 |
|
3 | 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | 4 |
|
5 | | -## Commands |
6 | | - |
7 | | -- Build: `pnpm build` |
8 | | -- Build libraries: `pnpm build:lib` |
9 | | -- Dev: `pnpm dev` |
10 | | -- Lint: `pnpm lint` |
11 | | -- Test: `pnpm test` |
12 | | -- Test with coverage: `pnpm test:coverage` |
13 | | -- Format: `pnpm format` |
14 | | -- Commit: `pnpm commit` |
15 | | - |
16 | | -## Architecture |
17 | | - |
18 | | -Monorepo structure with multiple apps, CLI tools, config packages, and libraries. Main packages include: |
19 | | - |
20 | | -- **Apps**: Playground (Vite) |
21 | | -- **CLIs**: Create app, Product analysis, Workflow cloud |
22 | | -- **Configs**: ESLint, Prettier, TSConfig, Vite, Rollup, Sentry, Tailwind |
23 | | -- **Libraries**: Utils, Shared, Types, HTTP, Hooks, Styles, Polyfill, AI Hub, Vue3 UI components, Vue3 Ant Design UI components |
24 | | - |
25 | | -## Development |
26 | | - |
27 | | -- Uses Turbo for monorepo management |
28 | | -- TypeScript with strict configs |
29 | | -- Vite as main build tool |
30 | | -- Vitest for testing |
31 | | -- Husky for Git hooks |
32 | | -- Conventional Commits |
33 | | - |
34 | | -## Workspaces |
35 | | - |
36 | | -- **apps/**: Applications |
37 | | -- **cli/**: CLI tools |
38 | | -- **configs/**: Shared configurations |
39 | | -- **packages/**: Shared libraries |
40 | | -- **docs/**: Documentation |
| 5 | +## 项目概述 |
| 6 | + |
| 7 | +**quantum-design** 是一个企业级前端开发基础设施项目,提供从 0-1 所需的完整工具链:CLI 脚本、构建配置、文档、组件库、样式库、类型库、工具库等,帮助快速搭建完整的工程。 |
| 8 | + |
| 9 | +当前分支:`feature/3.0.0`(进行中) |
| 10 | + |
| 11 | +**环境要求**: |
| 12 | + |
| 13 | +- Node.js: >= 20.19.0(推荐 22.19.0) |
| 14 | +- pnpm: >= 10.0.0(推荐 10.15.1) |
| 15 | +- 包管理器已在根 `package.json` 中配置 `packageManager: pnpm@10.15.1`,并使用 Volta 管理版本 |
| 16 | + |
| 17 | +## 常用命令 |
| 18 | + |
| 19 | +```bash |
| 20 | +# 安装依赖(首次或依赖变更后) |
| 21 | +pnpm i |
| 22 | + |
| 23 | +# 本地开发(使用 Turbo 启动各工作区应用/包的 dev) |
| 24 | +pnpm dev |
| 25 | + |
| 26 | +# 全量构建(所有包或按依赖拓扑构建) |
| 27 | +pnpm build |
| 28 | + |
| 29 | +# 仅构建库型包(按各包内的 build:lib 脚本) |
| 30 | +pnpm build:lib |
| 31 | + |
| 32 | +# 运行测试 / 覆盖率 |
| 33 | +pnpm test:unit # 单次运行测试 |
| 34 | +pnpm test:coverage # 带覆盖率的测试 |
| 35 | + |
| 36 | +# 代码检查与格式化 |
| 37 | +pnpm lint # 先运行 oxlint 再运行 eslint |
| 38 | +pnpm format # Prettier 批量格式化 ts/tsx/md |
| 39 | + |
| 40 | +# 规范提交(使用 czg 交互式提交) |
| 41 | +pnpm commit |
| 42 | + |
| 43 | +# Tauri 应用开发 |
| 44 | +pnpm tauri # 构建 Tauri |
| 45 | +pnpm tauri:dev # 开发模式 |
| 46 | +pnpm tauri:build # 构建生产版本 |
| 47 | + |
| 48 | +# 其他工具 |
| 49 | +pnpm migrator # Sass 模块化迁移辅助工具 |
| 50 | +``` |
| 51 | + |
| 52 | +**注意**: |
| 53 | + |
| 54 | +- 首次安装后如果看到 `postinstall` 触发 `turbo run stub`,属于生成占位构建的正常行为 |
| 55 | +- 测试命令是 `pnpm test:unit` 而不是 `pnpm test` |
| 56 | + |
| 57 | +## Monorepo 架构 |
| 58 | + |
| 59 | +使用 **Turbo** 进行单仓库多包管理,采用 **pnpm workspaces** 管理依赖。 |
| 60 | + |
| 61 | +### 工作区结构 |
| 62 | + |
| 63 | +- **apps/** - 应用示例和演示 |
| 64 | + - `playground`: 组件与功能演示的 Vite 应用 |
| 65 | + - `yapi-to-typescript`: 浏览器插件(CRX),将 YApi 接口转换为 TypeScript 类型 |
| 66 | + |
| 67 | +- **cli/** - CLI 工具集合 |
| 68 | + - `create-app`: 项目脚手架(支持 monorepo、nuxt3、vue3-antd-vite、vitepress-docs 等模板) |
| 69 | + - `product-analysis`: 需求/产品分析辅助 CLI |
| 70 | + - `workflow-cloud`: 工作流云端工具与客户端封装 |
| 71 | + |
| 72 | +- **configs/** - 统一配置包(作为独立包复用) |
| 73 | + - `eslint`: 统一 ESLint 配置(v9.x,使用 flat config) |
| 74 | + - `prettier`: 统一 Prettier 配置 |
| 75 | + - `tsconfig`: TypeScript 配置 |
| 76 | + - `vite`: Vite 插件与构建封装(当前 peer 依赖为 Vite ^7) |
| 77 | + - `rollup`: Rollup 构建配置 |
| 78 | + - `commitlint`: Commitlint 配置 |
| 79 | + - `sentry`: Sentry 集成配置 |
| 80 | + - `tailwind`: Tailwind CSS 配置 |
| 81 | + |
| 82 | +- **packages/** - 基础库(内部共享包) |
| 83 | + - `utils`: 通用工具方法 |
| 84 | + - `shared`: 共享常量/枚举等 |
| 85 | + - `types`: 公共类型定义 |
| 86 | + - `http`: HTTP 封装(基于 Axios) |
| 87 | + - `hooks`: 通用 Hooks(包含 Vue 相关) |
| 88 | + - `styles`: 样式库(AntD/Element/base) |
| 89 | + - `polyfill`: Polyfill 与工具补丁 |
| 90 | + - `ai-hub`: AI 相关封装 |
| 91 | + - `vue3-antd-pc-ui`: 基于 Ant Design Vue 的 PC 组件库(v3.0.0) |
| 92 | + - `vue3-pc-ui`: 通用 PC 组件库(不强绑 AntD) |
| 93 | + - `vue3-antd-pc-ui-nuxt`、`vue3-pc-ui-nuxt`: 对应 Nuxt 集成包 |
| 94 | + |
| 95 | +- **docs/** - 文档 |
| 96 | + - `project-docs`: 文档工程(VitePress) |
| 97 | + |
| 98 | +### Turbo 配置要点 |
| 99 | + |
| 100 | +- `build`: 依赖 `^build`,输出到 `dist/**` 和 `.next/**` |
| 101 | +- `build:lib`: 依赖 `^build`,输出到 `dist/**`、`dist-components/**`、`.next/**` |
| 102 | +- `dev`: 不缓存,持久化运行,依赖 `^build` |
| 103 | +- `test`: 依赖 `^build` |
| 104 | +- `test:coverage`: 依赖 `^build`,输出到 `coverage/**` |
| 105 | + |
| 106 | +## 技术栈 |
| 107 | + |
| 108 | +- **构建工具**: Vite 7.x、Rollup |
| 109 | +- **包管理**: pnpm 10.x + workspaces |
| 110 | +- **Monorepo**: Turbo 2.x |
| 111 | +- **语言**: TypeScript(严格模式) |
| 112 | +- **测试**: Vitest + @vitest/ui + happy-dom/jsdom |
| 113 | +- **代码质量**: ESLint 9.x(flat config)、oxlint、Prettier 3.x |
| 114 | +- **Git 工作流**: Husky + lint-staged + commitlint + czg |
| 115 | +- **版本管理**: @changesets/cli |
| 116 | +- **样式**: Sass、Tailwind CSS、CSS Variables |
| 117 | +- **UI 框架**: Vue 3.5+、Nuxt 4.x、Ant Design Vue 4.x |
| 118 | +- **桌面应用**: Tauri 2.x |
| 119 | + |
| 120 | +## 开发规范 |
| 121 | + |
| 122 | +### 1. 提交规范 |
| 123 | + |
| 124 | +- 统一使用 `pnpm commit` 调用 `czg` 进行规范化提交 |
| 125 | +- 遵守 Conventional Commits 规范(feat、fix、docs、chore 等) |
| 126 | +- 通过 `@changesets/cli` 管理版本和变更日志 |
| 127 | + |
| 128 | +### 2. 代码质量 |
| 129 | + |
| 130 | +- 统一 Lint:仓库提供 `@quantum-design-configs/eslint`,包内按需继承 |
| 131 | +- 统一构建:库包优先使用 `configs/rollup` 与 `configs/vite` 的封装 |
| 132 | +- ESLint 配置使用 flat config 格式(`eslint.config.mjs`) |
| 133 | +- Lint 流程:先运行 `oxlint` 再运行 `eslint` |
| 134 | + |
| 135 | +### 3. 包发布 |
| 136 | + |
| 137 | +- 使用 `pnpm-workspace.yaml` 中的 `catalog` 统一管理依赖版本 |
| 138 | +- 组件库支持多种导出方式(ESM、CJS、tree-shaking) |
| 139 | +- Nuxt 集成包不在 workspaces 根级别暴露(`- "!**/*-ui-nuxt/**"`) |
| 140 | + |
| 141 | +## 升级指南 |
| 142 | + |
| 143 | +### 3.0.0(进行中) |
| 144 | + |
| 145 | +- ✅ Vite 升级到 v7,更新 `configs/vite` 的 peer 依赖 |
| 146 | +- ✅ 重构 ESLint 配置(`configs/eslint`) |
| 147 | +- ✅ 支持 Tailwind CSS |
| 148 | +- ✅ 重构项目偏好设置,支持 CSS Variables 模式、多主题、系统主题 |
| 149 | +- ✅ 增加主题切换动画,优化视觉体验 |
| 150 | +- ✅ 样式库重构,替换 SCSS 变量为 CSS 变量 |
| 151 | +- 🔄 样式体系切换到 Tailwind(与现有 SCSS 共存/迁移策略) |
| 152 | +- 🔄 Nuxt 升级到 Nuxt 4,验证 `*-nuxt` 集成包兼容性 |
| 153 | + |
| 154 | +### 4.0.0(规划) |
| 155 | + |
| 156 | +- 🔜 升级 Vue 3.6 |
| 157 | +- 🔜 表格组件从 AntD Table 迁移到 `vxe-table` |
| 158 | +- 🔜 AntD 替换为 `shadcn-vue`(或提供可插拔主题方案) |
| 159 | + |
| 160 | +## AI/自动化开发 |
| 161 | + |
| 162 | +项目已集成 CloudBase AI 开发规则(`.github/copilot-instructions.md`),包含: |
| 163 | + |
| 164 | +- 场景化开发指导(Web 项目、小程序、数据库、UI 设计) |
| 165 | +- 标准开发工作流程(需求确认 → 技术方案 → 任务拆分 → 执行) |
| 166 | +- MCP 工具集成(`.cursor/mcp.json` 配置 cloudbase-mcp) |
| 167 | +- 专业规则文件映射(web-development、cloudbase-platform、database 等) |
| 168 | + |
| 169 | +## 外部资源 |
| 170 | + |
| 171 | +- **文档站点**: https://little-littleprogrammer.github.io/quantum-design/docs/ |
| 172 | +- **Playground**: https://little-littleprogrammer.github.io/quantum-design/playground/ |
0 commit comments