09-项目目录结构

一、仓库顶层

.
├── CLAUDE.md                # Claude Code 主指令
├── README.md
├── .env.local               # 本地凭据，不入 git
├── .gitignore
├── .githooks/
│   └── pre-push             # 推送前测试闸门
├── scripts/
│   ├── test.sh              # 全量测试
│   └── setup-test-db.sh     # 重置测试数据库
├── sql/
│   └── migrations/          # Flyway V_n__*.sql
├── docs/                    # 项目文档（见 § 四）
├── backend/                 # 后端 Spring Boot 模块
└── frontend/                # 前端 Vite + React 模块

二、后端目录

根包名 com.xly.erp，本节以 <root> 代指。

backend/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/<root>/
│   │   │   ├── ErpApplication.java         # Spring Boot 启动类
│   │   │   ├── common/                     # 统一响应 / 异常 / 工具
│   │   │   │   ├── response/               # ApiResponse / ErrorCode
│   │   │   │   ├── exception/              # 全局异常处理器
│   │   │   │   └── util/                   # Hutool 二次封装等
│   │   │   ├── config/                     # SecurityConfig / RedisConfig / SwaggerConfig
│   │   │   ├── security/                   # JWT 过滤器 / RBAC
│   │   │   └── module/
│   │   │       ├── usr/                    # USR 用户管理
│   │   │       │   ├── controller/
│   │   │       │   ├── service/
│   │   │       │   ├── mapper/
│   │   │       │   ├── entity/
│   │   │       │   ├── dto/
│   │   │       │   └── vo/
│   │   │       └── mod/                    # MOD 模块管理
│   │   │           ├── controller/
│   │   │           ├── service/
│   │   │           ├── mapper/
│   │   │           ├── entity/
│   │   │           ├── dto/
│   │   │           └── vo/
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── application-dev.yml
│   │       ├── logback-spring.xml
│   │       └── mapper/                     # MyBatis-Plus XML
│   └── test/
│       └── java/<root>/                    # 单元 / 集成测试
└── target/                                 # 构建产物，git 忽略

三、前端目录

frontend/
├── package.json
├── vite.config.ts
├── index.html
├── src/
│   ├── main.tsx                # 入口
│   ├── App.tsx                 # 路由总配置
│   ├── api/                    # axios 封装 + 各模块接口
│   │   ├── request.ts
│   │   ├── usr.ts
│   │   └── mod.ts
│   ├── components/             # 通用组件
│   ├── pages/
│   │   ├── usr/                # USR 页面
│   │   └── mod/                # MOD 页面
│   ├── store/                  # Redux Toolkit slices
│   ├── hooks/
│   ├── utils/
│   ├── styles/
│   │   ├── tokens.css          # Design Token CSS 变量
│   │   └── index.css
│   └── router/                 # React Router 配置
└── public/

四、docs/ 结构

docs/
├── 01-需求清单/           # 每模块一子目录（_module.md 模块头 + REQ-*.md 卡片）
├── 02-开发计划.md
├── 03-数据库设计文档.md
├── 04-技术规范.md
├── 05-API接口契约.md
├── 06-UI交互规范.md
├── 07-环境配置.md
├── 08-模块任务管理.md
├── 09-项目目录结构.md
├── 10-验收检查清单.md
└── superpowers/          # CC 运行时产物

五、命名与放置约定

• 根包名：com.xly.erp，所有 Java 类位于此包及其子包下。
• 前端命名空间：以 @/ 别名映射 frontend/src/（在 vite.config.ts 中配置）。
• Controller：<root>.module.<mod>.controller.XxxController，REST 入口；不包含业务逻辑。
• Service：<root>.module.<mod>.service.XxxService + service.impl.XxxServiceImpl，业务编排，事务边界。
• Mapper：<root>.module.<mod>.mapper.XxxMapper（接口）+ resources/mapper/<mod>/XxxMapper.xml（XML）。
• Entity：<root>.module.<mod>.entity.Xxx，1:1 映射数据库表。
• DTO：<root>.module.<mod>.dto.XxxDTO，入参传输对象（Controller ↔ Service）。
• VO：<root>.module.<mod>.vo.XxxVO，出参视图对象（Service → Controller → 前端）。
• 前端组件：frontend/src/components/<域>/XxxComponent.tsx，复用粒度。
• 前端页面：frontend/src/pages/<mod>/<功能>.tsx，与 REQ 卡片功能一一对应。
• API 模块：frontend/src/api/<mod>.ts 一个文件汇集该模块所有后端接口调用。