调整结构

2026-07-28 12:52:36 +08:00
parent f9dcf890b2
commit 94dd560331
61 changed files with 4243 additions and 906 deletions
--- a/README.md
+++ b/README.md
@@ -1,62 +1,114 @@
 # Training Full-Stack Project

-前后端分离的全栈项目基础工程：
+前后端分离的培训项目：

- `frontend`: React 18 + TypeScript + Vite
- `backend`: Spring Boot + Java 21 + Maven + MyBatis-Plus
- `MySQL`: 外部 MySQL 8 数据库，由环境变量提供连接配置
+- `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+（或使用项目中的 Maven Wrapper）
+- Maven 3.9+
 - 可访问目标 MySQL 的网络和账号

-## 配置数据库
+## 配置环境

-项目不会创建或启动 MySQL。请先确保 `.env.example` 中配置的 MySQL 服务已经运行并允许当前机器访问。
-
-Spring Boot 启动时按以下顺序读取配置：根目录 `.env`，然后是根目录 `.env.example`。同名变量以 `.env` 为准；没有 `.env` 时直接使用已配置的 `.env.example`。
-
-建议将 `.env.example` 复制为本地 `.env`，实际 `.env` 不提交到仓库：
+使用 `.env.example` 作为本地配置参考，并将真实值写入未提交的根目录 `.env`：

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

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

-```powershell
-cp .env.production.example .env
+## 数据库初始化与迁移
+
+SQL 文件只保存在根目录 `sql/`：
+
+- `sql/USERS.sql`：新环境的最终建表语句，包含表和字段中文注释。
+- `sql/migrations/V1__rename_users_to_USERS.sql`：保留既有 `users` 数据的人工迁移脚本。
+
+迁移前只读检查目标库和影响范围：
+
+```sql
+SHOW TABLES LIKE 'users';
+SHOW TABLES LIKE 'USERS';
 ```

-需要确认 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_DATABASE`、`MYSQL_USER` 和 `MYSQL_PASSWORD` 均已配置。生产环境建议使用部署平台的 Secret 管理能力。
+确认备份、目标数据库和回滚方式后，人工执行迁移脚本。MySQL 的 `RENAME TABLE` 会隐式提交，回滚使用：
+
+```sql
+RENAME TABLE USERS TO users;
+```
+
+应用启动不会自动执行 SQL；迁移和建表必须由数据库管理员按环境流程执行。

 ## 启动后端

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

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

 ## 启动前端

-```bash
-cd frontend
-npm install
-npm run dev
+```powershell
+Set-Location frontend
+npm ci
+npm run dev -- --host 127.0.0.1
 ```

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

-## 构建检查
+## API 示例

-```bash
-cd frontend
+用户列表使用 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

-cd ../backend
-mvn clean verify
+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` 保留日志，并确认日志中没有敏感信息。