training/README.md

# 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`：

```powershell
Copy-Item .env.example .env
```

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

## 数据库初始化与迁移

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

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

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

```sql
SHOW TABLES LIKE 'users';
SHOW TABLES LIKE 'USERS';
```

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

```sql
RENAME TABLE USERS TO users;
```

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

## 启动后端

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

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

## 启动前端

```powershell
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 分页：

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

成功响应统一为：

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

## 构建与测试

```powershell
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
```

## 全栈只读验证

从项目根目录执行：

```powershell
python .codex/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"
```

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