Training Full-Stack Project

前后端分离的培训项目：

• frontend：React 18、TypeScript、Vite、React Router、Zustand、Tailwind CSS、SCSS Modules
• backend：Spring Boot 3.4.5、Java 21、Maven、MyBatis-Plus
• MySQL：外部 MySQL 8 数据库，应用不会自动创建或修改表结构

环境要求

• Node.js 20+
• JDK 21+
• Maven 3.9+
• 可访问目标 MySQL 的网络和账号

配置环境

使用 .env.example 作为本地配置参考，并将真实值写入未提交的根目录 .env：

Copy-Item .env.example .env

生产环境使用 .env，或由部署平台注入同名 Secret。不要将真实密码、令牌或数据库地址写入示例文件、日志或提交内容。

数据库初始化与迁移

SQL 文件只保存在根目录 sql/：

• sql/USERS.sql：新环境的最终建表语句，包含表和字段中文注释。
• sql/migrations/V1__rename_users_to_USERS.sql：保留既有 users 数据的人工迁移脚本。

迁移前只读检查目标库和影响范围：

SHOW TABLES LIKE 'users';
SHOW TABLES LIKE 'USERS';

确认备份、目标数据库和回滚方式后，人工执行迁移脚本。MySQL 的 RENAME TABLE 会隐式提交，回滚使用：

RENAME TABLE USERS TO users;

应用启动不会自动执行 SQL；迁移和建表必须由数据库管理员按环境流程执行。

启动后端

mvn -f backend/pom.xml spring-boot:run

后端默认运行在 http://127.0.0.1:8080，健康检查地址为 GET /api/v1/health。每次请求支持并返回 X-Request-Id。

启动前端

Set-Location frontend
npm ci
npm run dev -- --host 127.0.0.1

前端默认运行在 http://127.0.0.1:5173，开发服务器将 /api 请求代理到后端。API 基础路径为 /api/v1。

API 示例

用户列表使用 1-based 分页：

GET /api/v1/users?page=1&pageSize=50&keyword=&role=&status=
GET /api/v1/users/summary

成功响应统一为：

{
  "code": 200,
  "message": "success",
  "data": {}
}

构建与测试

Set-Location frontend
npm ci
npm run test
npm run build

Set-Location ..
mvn -f backend/pom.xml test
mvn -f backend/pom.xml verify

全栈只读验证

从项目根目录执行：

python skills/fullstack-start-verify/scripts/start_and_verify.py `
  --backend-cmd "mvn -f backend/pom.xml spring-boot:run" `
  --backend-dir . `
  --backend-url http://127.0.0.1:8080/api/v1/health `
  --frontend-cmd "npm run dev -- --host 127.0.0.1" `
  --frontend-dir frontend `
  --frontend-url http://127.0.0.1:5173/ `
  --check-url summary=http://127.0.0.1:8080/api/v1/users/summary `
  --check-url "users=http://127.0.0.1:8080/api/v1/users?page=1&pageSize=50&keyword=&role=&status="

验证期间只执行健康检查和 GET 查询，不执行新增、修改、删除或数据库迁移。脚本默认清理本次启动的进程；排查启动失败时增加 --keep-logs 保留日志，并确认日志中没有敏感信息。