Imported from wwsun/java-web-starter (
AGENTS.md). Install upstream withnpx skills add wwsun/java-web-starter. Copyright stays with the author.
AGENTS.md — AI Agent 行为指令
项目概述
这是一个前后端分离的 Web 工程脚手架（java-web-starter），用于快速搭建企业内部管理系统。
子栈详细规范：
- 后端：
backend/AGENTS.md - 前端：
frontend/AGENTS.md
项目结构
backend/ → Spring Boot 3.2 + JDK 21 后端
frontend/ → Vite + React 19 + TypeScript 前端
doc/ → 项目文档
nginx/ → Nginx 反向代理配置
禁止事项
- ❌ 不要修改
common/下的基础组件（除非明确需要） - ❌ 不要绕过 Spring Security 直接处理认证
- ❌ 不要在代码中存储密钥或密码
- ❌ 不要在前端硬编码后端 URL
- ❌ 不要使用
System.out.println，使用 SLF4J Logger
基础设施命令
# 启动基础设施（MySQL 必须；Redis 可选）
docker compose up -d mysql
# 若需启用 Redis 缓存支持
docker compose up -d redis
# 启动所有服务（生产部署）
docker compose up -dAPI 验证与回归测试
使用 scripts/api.sh 进行端到端 API 验证，无需每次手动登录：
# 加载工具（每个终端会话执行一次）
source scripts/api.sh
# token 自动缓存（首次调用自动登录，50 分钟内复用）
api_get /api/users/me
api_post /api/users -d '{"username":"x","password":"y","email":"x@y.com"}'
api_put /api/users/1 -d '{"email":"new@x.com"}'
api_delete /api/users/1
# 其他常用命令
api_health # 检查服务是否运行
api_login # 强制刷新 token
api_token # 查看当前 token
api_users # 查询用户列表（支持 api_users 2 20 分页参数）环境变量（覆盖默认值）：
API_BASE_URL=http://localhost:8080 # 默认
API_USERNAME=admin # 默认
API_PASSWORD=admin123 # 默认安全和权限
无需提示可直接执行：
- 读取和搜索代码文件
- 启动 / 停止基础设施容器（
docker compose up/down） - 运行
scripts/api.sh进行 API 验证
先询问确认：
- 安装或删除依赖包（npm / Maven）
git push或创建 PR- 删除文件或清除持久化数据（
docker compose down -v） - 生产环境部署操作
PR 检查清单
- 提交信息格式：
type(scope): 描述（Conventional Commits） - 后端：
mvn test全部通过 - 前端：lint、TypeScript 类型检查、单元测试全部通过
- 无硬编码的密钥或密码
- 无
System.out.println（后端）或残留console.log（前端） - 接口变更已更新 Knife4j 文档注解（
@Tag、@Operation）
关键约定
- 遵循 Conventional Commits 提交规范
- API 前缀：
/api（server.servlet.context-path） - 数据库：
starter_db - 默认管理员：admin / admin123
