🚀 脚手架核心 —— 打造高效开发新体验

📐 代码规范：统一协作，提升质量

✨ 为什么需要代码规范？

多人协作开发时，统一的代码规范是团队高效协作的基石
良好的代码规范让后续维护和迭代事半功倍
自动化工具辅助 + 开发者自身规范意识 = 优质代码

⚡ Vite 8 + Rolldown：性能飙升的秘密武器

🔥 新一代构建引擎，速度起飞！

Vite 8 ：Vite团队最新力作，完全由Rolldown驱动，性能质的飞跃
Rolldown ：Vite团队自研下一代Rust构建引擎，目标取代Rollup + esbuild组合，保持Rollup兼容性的同时速度更快、效率更高

🧹 Eslint：代码质量的守护者

✅ 全方位的代码检查，让错误无所遁形

不仅格式化代码，更能实时检查语法错误，开发过程中就消灭bug
针对React和Vue3用户提供定制化配置，精准适配不同框架
语法规范 + 格式规范双管齐下，打造完美代码
🔗 React Eslint 规范文件：eslint.config.mjs
🔗 Vue3 Eslint 规范文件：eslint.config.mjs

🧩 TypeScript：模板默认类型系统

🔒 React 与 Vue3 的 SPA、SSR 模板均已内置 TypeScript

React 模板源码默认使用 .ts / .tsx，并提供 tsconfig.json、vite-env.d.ts、路由类型声明等基础配置
Vue3 模板源码默认使用 .ts，单文件组件可使用 <script setup lang="ts">，并通过 vue-tsc 进行类型检查
React SSR 模板使用 Next.js App Router 与 TypeScript，Vue 3 SSR 模板使用 Nuxt 类型检查
提交前统一执行 pnpm run typecheck，再运行模板提供的 pnpm run lint

📌 Git：强制规范，守住最后一道防线

🚫 拒绝不合规代码提交！

代码提交前自动校验Eslint规范
有错误？修复后才能提交，确保仓库代码质量始终如一
团队协作的“守护神”，让规范落地生根

🤖 AI 协作：让智能体读得懂项目

🧭 四套模板均已面向 AI 协作整理结构

根目录保留 AGENTS.md，用短规则描述目录边界、依赖用法和验证命令
React 与 Vue3 模板默认提供 docs 模块，登录后直接展示项目结构和核心库职责
src/app、src/features、src/shared 分层明确，减少 AI 误放代码、重复造目录的问题
SSR 模板额外划分 src/server，并在 AGENTS.md 中约束浏览器 API 与服务端代码边界
Vue3 模板额外内置 .agents/skills/shadcn-vue，让 AI Agent 操作 shadcn-vue 组件时有明确规则可循

⚡ 项目优化：从开发到打包，全面加速

💡 Vite已经很快？我们让它更快！

基于Vite默认优化，进一步深度定制开发和打包配置
针对实际项目场景，优化每一个细节

📦 构建开关：默认轻量，按需增强

🔪 复杂能力不默认强开

compression、legacy、web update notice、DevTools、Million.js、React Compiler 等能力通过环境变量开启
默认 start / build 只执行 Vite，模板创建后不再要求先初始化 Git 仓库
需要性能优化时再基于实际分析结果添加分包策略

// 示例：按需开启构建压缩
VITE_ENABLE_COMPRESSION=true pnpm run build

// 示例：按需开启 legacy 兼容构建
VITE_ENABLE_LEGACY=true pnpm run build

🎨 样式与组件：统一现代 UI 栈

🎯 React 与 Vue3 模板统一迁移到 shadcn + Tailwind CSS

React 模板使用 shadcn/ui，Vue3 模板使用 shadcn-vue
基础组件固定在 src/shared/ui，业务组件留在各自 feature
Tailwind CSS 4 作为默认样式方案，不再保留 UnoCSS 配置
React 模板使用 @heroicons/react，Vue3 模板使用 @heroicons/vue，避免继续依赖 Uno/Iconify 图标预设

💪 使用cwa-stack，让前端开发更简单、更高效！

📚 想了解更多？继续探索我们的文档，发现更多实用功能！

🧬 全栈组合：一套脚手架，前后端一次成型

🧩 动态组合，拒绝模板膨胀

🧱 五套模板是唯一源码来源

四个预设 react-spring / vue-spring / next-spring / nuxt-spring 在生成时动态装配，不为组合复制任何模板仓库
前端装配在 apps/web，Spring Boot 装配在 apps/api，工程是单一 Git 仓库（子项目不携带嵌套 .git）
目标目录已存在即拒绝覆盖；生成过程在安全临时目录完成，成功后原子重命名，失败自动清理

🎛️ 根级编排：五个命令覆盖全栈生命周期

🎛️ 组合工程的根 package.json 只暴露五个命令（脚本零第三方依赖，纯 Node 内置模块）

命令	职责
`pnpm run setup`	运行时门禁、冻结安装、生成随机密码 `.env`、生成 API Client
`pnpm run dev`	compose 启动 MySQL/Redis → Spring Boot readiness → 前端开发服务器，SIGINT 优雅清理
`pnpm run verify`	契约漂移 + 前端六项门禁 + 后端 `mvnw clean verify` + 真实登录 E2E
`pnpm run doctor`	只读诊断：版本、端口占用、依赖服务可达性、契约漂移，输出修复建议
`pnpm run api:generate`	以 `apps/api/openapi.yaml` 为唯一契约来源重新生成前端 Client

📜 契约驱动：后端 OpenAPI 是唯一事实来源

🔗 改接口不再靠人肉同步

前端类型与 Axios Client 由 OpenAPI 3.1 契约生成到 src/shared/api/generated，生成目录带“禁止手工编辑”约束，业务代码统一经由 feature API 门面引用
独立模板内置契约快照生成；组合工程直接读取 apps/api/openapi.yaml 并回写快照
CI 运行生成命令后执行 git diff --exit-code，契约漂移 100% 检出
登录契约：POST /api/v1/login 顶层 token/tokenType/expiresAt/user；错误为 Problem Details 顶层 code/msg/requestId；SPA 走 Bearer，SSR 只经 BFF HttpOnly Cookie

🤖 AI Agent 友好：机器可读工程清单

🧭 组合工程根目录的 cwa.config.json 声明一切

前后端目录、端口基线（Web/API/Management）、契约路径、统一命令一览无余
组合工程 AGENTS.md 明确：改接口先改后端与 openapi.yaml，再执行 pnpm run api:generate 同步前端
显式 Mock 模式（VITE_ENABLE_MOCK / ENABLE_AUTH_MOCK / NUXT_ENABLE_AUTH_MOCK）默认关闭，生产构建绝不静默回退 Mock

📦 项目入口

npm：cwa-stack（原 create-wl-app，npx cwa-stack create 即刻开始）
GitHub：whyfail/cwa-stack — 源码、Issue 与 Release
升级记录：2026-09-21 日志 — 全栈组合与根级编排的完整说明

🚀 脚手架核心 —— 打造高效开发新体验 ​

📐 代码规范：统一协作，提升质量 ​

⚡ Vite 8 + Rolldown：性能飙升的秘密武器 ​

🧹 Eslint：代码质量的守护者 ​

🧩 TypeScript：模板默认类型系统 ​

📌 Git：强制规范，守住最后一道防线 ​

🤖 AI 协作：让智能体读得懂项目 ​

⚡ 项目优化：从开发到打包，全面加速 ​

📦 构建开关：默认轻量，按需增强 ​

🎨 样式与组件：统一现代 UI 栈 ​

🧬 全栈组合：一套脚手架，前后端一次成型 ​

🧩 动态组合，拒绝模板膨胀 ​

🎛️ 根级编排：五个命令覆盖全栈生命周期 ​

📜 契约驱动：后端 OpenAPI 是唯一事实来源 ​

🤖 AI Agent 友好：机器可读工程清单 ​

📦 项目入口 ​