# 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` 一个文件汇集该模块所有后端接口调用。