# 09-项目目录结构

## 一、仓库顶层

```
.
├── CLAUDE.md                # Claude Code 主指令
├── README.md                # 项目说明（人工补充）
├── .env.local               # 本地凭据（不入 git）
├── .gitignore
├── .githooks/               # 项目级 git hooks
│   └── pre-push             # push 前触发本地全量测试闸门
├── scripts/                 # 工具脚本
│   ├── test.sh              # 全量测试入口
│   └── setup-test-db.sh     # DROP+CREATE 测试库
├── sql/
│   └── migrations/          # Flyway 顺序迁移文件
│       └── V1__initial_schema.sql
├── docs/                    # 见 § 四
├── backend/                 # 后端工程（Spring Boot + Maven）
└── frontend/                # 前端工程（React + Vite）
```

## 二、后端目录

根包名：`com.xly.erp`

```
backend/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/<根包路径>/
    │   │   ├── ErpApplication.java          # Spring Boot 启动类
    │   │   ├── common/                       # 通用组件
    │   │   │   ├── response/                 # 统一响应封装
    │   │   │   ├── exception/                # 全局异常处理
    │   │   │   ├── security/                 # JWT / Security 配置
    │   │   │   └── util/
    │   │   └── module/                       # 业务模块（按 docs/01 模块代码分目录）
    │   │       ├── usr/                      # USR 用户管理
    │   │       │   ├── controller/
    │   │       │   ├── service/
    │   │       │   ├── mapper/
    │   │       │   ├── entity/
    │   │       │   ├── dto/
    │   │       │   └── vo/
    │   │       └── mod/                      # MOD 模块管理
    │   │           ├── controller/
    │   │           ├── service/
    │   │           ├── mapper/
    │   │           ├── entity/
    │   │           ├── dto/
    │   │           └── vo/
    │   └── resources/
    │       ├── application.yml               # 主配置
    │       ├── application-dev.yml           # dev profile
    │       ├── application-test.yml          # test profile
    │       └── mapper/                       # MyBatis-Plus XML（按模块子目录）
    └── test/
        └── java/<根包路径>/
            └── module/                       # 与 main 同结构，测试代码
```

## 三、前端目录

```
frontend/
├── package.json
├── vite.config.ts
├── index.html
└── src/
    ├── main.tsx                # 应用入口
    ├── App.tsx                 # 根组件 + 全局 ConfigProvider
    ├── api/                    # 接口封装（按模块分文件，如 usr.ts / mod.ts）
    ├── components/             # 通用组件
    ├── layouts/                # 布局组件（MainLayout 等）
    ├── pages/                  # 业务页面（按模块分目录）
    │   ├── usr/                # USR 用户管理
    │   │   ├── UserList.tsx
    │   │   ├── UserForm.tsx
    │   │   └── UserDetail.tsx
    │   └── mod/                # MOD 模块管理
    │       └── ModuleTree.tsx
    ├── store/                  # Redux Toolkit slices
    ├── hooks/                  # 自定义 hooks
    ├── router/                 # 路由配置
    ├── utils/                  # 工具函数（日期、金额、权限判断等）
    └── styles/                 # 全局样式 / 主题 token
```

## 四、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 类必须在此包或其子包下
- **前端命名空间**：以 `src/` 为根，按模块代码（小写）建子目录
- **Controller**：放 `module/<mod>/controller/`，类名 `<Entity>Controller`，提供 RESTful 接口
- **Service**：接口 `<Entity>Service` + 实现 `<Entity>ServiceImpl`，放 `module/<mod>/service/[impl/]`
- **Mapper**：接口放 `module/<mod>/mapper/`，XML 放 `resources/mapper/<mod>/`
- **DTO**：入参对象，放 `module/<mod>/dto/`，命名 `<Action><Entity>DTO`（如 `CreateUserDTO`）
- **VO**：响应对象，放 `module/<mod>/vo/`，命名 `<Entity>VO` 或 `<Entity><Scope>VO`（如 `UserListVO`）
- **Entity**：与数据库表 1:1 映射，放 `module/<mod>/entity/`
- **前端组件**：通用组件放 `src/components/`，业务专用组件放 `src/pages/<mod>/components/`
- **前端页面**：每个 REQ 一个页面文件，放 `src/pages/<mod>/`，PascalCase 命名
- **前端路由**：集中在 `src/router/`，按模块分文件后聚合