2026-09-21

更新概览

• cwa-stack（v1.1.1 → v1.2.0，已发布 npm）：新增全栈组合创建——四个预设（react-spring / vue-spring / next-spring / nuxt-spring）一次生成前端 + Spring Boot 的单 Git 仓库全栈工程；不复制模板源码，动态装配。
• 组合工程内置根级编排五命令：pnpm run setup / dev / verify / doctor / api:generate，覆盖环境门禁、依赖安装、本地密码生成、契约生成、一键启动、全栈验证与只读诊断。
• 五套模板真实登录闭环：SPA 登录页接真实后端（Bearer），SSR 的 BFF 会话 API 调用真实 /api/v1/login 并写 HttpOnly Cookie，删除全部演示 token 逻辑。
• 契约驱动：四套前端接入 Orval（OpenAPI 3.1），以 apps/api/openapi.yaml（独立模式下为仓库内契约快照）生成类型与 Axios Client，CI 漂移检查（git diff --exit-code）。
• 显式 Mock 模式：浏览器端 MSW（VITE_ENABLE_MOCK=true）与 BFF 会话 Mock（ENABLE_AUTH_MOCK / NUXT_ENABLE_AUTH_MOCK）默认关闭；生产构建绝不静默回退 Mock。
• 阶段 1 补齐 CLI 测试基线：77 个用例（node:test，零新依赖）覆盖模板映射、参数/管道解析、组合器编排与失败清理。

全栈组合创建（cwa-stack）

组合方式

• 交互式：npx cwa-stack create 首问「独立项目 / 全栈组合项目」，组合路径仅需选择前端技术栈（React/Vue）与渲染模式（SPA/SSR），预设随之唯一确定。
• 非交互：--preset react-spring --package com.example.myapp；--template 与 --preset 互斥。
• 管道：新增 preset:react-spring\n项目名称\nJava包名\n项目描述 格式，旧管道格式保持不变。

组合流程

1. 目标目录存在即拒绝覆盖；在目标同级创建安全临时目录。
2. 下载前端模板与 springboot-template 并分别渲染变量（Java 包目录重命名）。
3. 移除嵌套 .git，写入根级编排文件（cwa.config.json、AGENTS.md、README、docs、scripts）。
4. 根目录执行 git init（单根 Git 仓库），全部成功后原子重命名为目标目录；任一步失败清理临时目录，不留半成品。

根级编排命令

命令	说明
pnpm run setup	运行时门禁（Node 24/pnpm/Java 25/Git/Docker/Compose）、冻结安装、生成随机密码 .env、生成 API Client
pnpm run dev	compose 启动 MySQL/Redis → 等待健康检查 → 启动 Spring Boot → 等待 readiness → 启动前端；SIGINT 优雅清理
pnpm run verify	静态检查 → 契约漂移 → 前端六项门禁 → 后端 mvnw clean verify → 真实登录 E2E
pnpm run doctor	只读诊断，PASS/WARN/FAIL + 修复建议（端口占用、服务不可达、契约漂移等）
pnpm run api:generate	以 apps/api/openapi.yaml 为唯一契约来源重新生成前端 Client

AI Agent 友好

• cwa.config.json 机器可读工程清单：前后端目录、端口基线、契约路径、统一命令。
• 组合工程 AGENTS.md 约束：改接口先改后端与 openapi.yaml，再 pnpm run api:generate 同步生成目录。

模板侧配套改造

• 登录响应类型统一为契约形状：顶层 token / tokenType / expiresAt / user；错误统一 Problem Details 顶层 code / msg / requestId。
• 登录接口的 401 不再触发「会话过期」流程，由登录页展示后端 msg。
• E2E 凭据与 Mock 开关环境变量化：E2E_AUTH_MOCK=false + E2E_AUTH_USERNAME/E2E_AUTH_PASSWORD 可切真实后端；模板级 E2E 默认离线 Mock。
• 开发代理与生产网关对齐：API 前缀固定 /api/v1，代理不做路径改写。

质量门禁（验证结果）

验证项	结果
cwa-stack 单元/集成测试（node:test）	77 个全部通过
四组合矩阵（react/vue/next/nuxt × spring）	setup + verify（含后端 98 测试与真实登录 E2E）全部通过
独立创建冒烟	五模板标识全部可用，渲染产物正确
后端生成项目 ./mvnw clean verify	98 个测试全部通过（Testcontainers 真实 MySQL/Redis）
cwa-docs 构建	通过

品牌升级

• npm 包由 create-wl-app 更名为 cwa-stack（CWA = Create Whole-stack App），内容与 1.2.0 一致，从 npx cwa-stack create ... 开始使用。
• 旧包 create-wl-app 已标记弃用并指向新包名；本站与各仓库文档已同步品牌。