# 09-项目目录结构

## 一、仓库顶层

```
<project-root>/
├── CLAUDE.md                  # CC 项目指令
├── README.md                  # 项目说明
├── .env.local                 # 本地环境变量（不入 git）
├── .gitignore
├── .githooks/
│   └── pre-push               # push 前测试闸门
├── scripts/
│   ├── setup-test-db.sh       # 重置测试数据库
│   └── test.sh                # 全量测试入口
├── sql/
│   └── migrations/            # Flyway V_n__*.sql
├── docs/                      # 规划文档（见 § 四）
├── backend/                   # Spring Boot 后端
└── frontend/                  # React 前端
```

## 二、后端目录

```
backend/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/
    │   │   └── com/example/erp/
    │   │       ├── config/             # Spring 配置类（Security、Swagger、MyBatis 等）
    │   │       ├── common/             # 通用工具（统一响应体、全局异常、枚举、常量）
    │   │       ├── module/
    │   │       │   └── usr/            # USR 用户管理模块
    │   │       │       ├── controller/ # REST 接口层
    │   │       │       ├── service/    # 业务逻辑层
    │   │       │       ├── mapper/     # MyBatis-Plus Mapper
    │   │       │       ├── entity/     # 数据库实体
    │   │       │       ├── dto/        # 请求参数 DTO
    │   │       │       └── vo/         # 响应视图 VO
    │   │       └── Application.java    # 启动类
    │   └── resources/
    │       ├── application.yml         # 主配置
    │       ├── application-dev.yml     # 开发环境配置
    │       ├── application-prod.yml    # 生产环境配置
    │       └── mapper/                 # MyBatis XML（可选）
    └── test/
        └── java/
            └── com/example/erp/
                └── module/
                    └── usr/            # USR 模块单元/集成测试
```

## 三、前端目录

```
frontend/
├── package.json
├── vite.config.ts
├── index.html
└── src/
    ├── main.tsx                # 应用入口
    ├── App.tsx                 # 根组件 + 路由配置
    ├── styles/
    │   └── tokens.css          # Design Token CSS 变量
    ├── api/                    # Axios 封装 + 各模块接口
    │   └── usr.ts              # USR 用户管理接口
    ├── store/                  # Redux Toolkit Store
    │   └── slices/
    │       └── authSlice.ts    # 认证状态
    ├── hooks/                  # 通用 React Hooks
    ├── components/             # 通用业务组件（PermButton 等）
    ├── pages/                  # 页面组件（按模块子目录）
    │   ├── usr/                # USR 用户管理页面
    │   │   ├── UserListPage.tsx
    │   │   ├── UserFormDrawer.tsx
    │   │   └── LoginPage.tsx
    │   └── 403.tsx             # 无权限页
    └── utils/                  # 工具函数
```

## 四、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.example.erp`
- **Controller**：`XxxController.java`，放 `module/<mod>/controller/`，只做入参校验 + 调 Service
- **Service**：`XxxService.java` 接口 + `XxxServiceImpl.java` 实现，放 `module/<mod>/service/`
- **Mapper**：`XxxMapper.java`，放 `module/<mod>/mapper/`，继承 `BaseMapper<T>`
- **DTO**：请求参数用 `XxxReqDTO`，放 `module/<mod>/dto/`
- **VO**：响应视图用 `XxxVO`，放 `module/<mod>/vo/`
- **前端组件**：PascalCase，如 `UserFormDrawer.tsx`，放 `components/` 或页面同级
- **前端页面**：PascalCase + `Page` 后缀，如 `UserListPage.tsx`，放 `pages/<mod>/`
- **前端 API**：camelCase 模块名，如 `usr.ts`，放 `api/`