# 09-项目目录结构

## 一、仓库顶层

```
.
├── CLAUDE.md                 # Claude Code 主指令
├── README.md                 # 项目说明
├── .env.local                # 本地凭据（不入 git）
├── .gitignore
├── .githooks/                # 仓库级 git hooks（core.hooksPath 指向）
│   └── pre-push
├── scripts/                  # 项目脚本（test.sh / setup-test-db.sh 等）
├── docs/                     # 全部规划与设计文档
├── prototype/                # 前端 HTML mockup（前端阶段的布局权威）
├── sql/
│   └── migrations/           # Flyway V_n__*.sql
├── backend/                  # Spring Boot 服务
│   ├── pom.xml
│   └── src/
└── frontend/                 # Vite + React 应用
    ├── package.json
    ├── vite.config.ts
    └── src/
```

## 二、后端目录

后端按 Spring Boot 3 + MyBatis-Plus 的惯例组织；业务代码按 docs/01 模块索引落到 `module/<module_code_lower>/`。

```
backend/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/xly/erp/
│   │   │       ├── Application.java          # Spring Boot 启动类
│   │   │       ├── common/                   # 跨模块基础组件
│   │   │       │   ├── response/             # 统一响应包装（Result / PageResult）
│   │   │       │   ├── exception/            # 全局异常处理 + 业务异常
│   │   │       │   ├── security/             # Spring Security / JWT 配置
│   │   │       │   ├── config/               # 通用配置（CORS / Swagger / MyBatis-Plus 等）
│   │   │       │   └── util/                 # 工具类
│   │   │       └── module/
│   │   │           └── usr/                  # 用户管理（REQ-USR-*）
│   │   │               ├── controller/
│   │   │               ├── service/
│   │   │               ├── service/impl/
│   │   │               ├── mapper/
│   │   │               ├── entity/
│   │   │               ├── dto/              # Request DTO
│   │   │               ├── vo/               # Response VO
│   │   │               └── converter/        # MapStruct DTO/VO/Entity 转换
│   │   └── resources/
│   │       ├── application.yml               # 主配置
│   │       ├── application-dev.yml           # 开发环境
│   │       ├── application-test.yml          # 测试环境
│   │       ├── mapper/                       # MyBatis XML（与 module 子目录对应）
│   │       │   └── usr/
│   │       └── logback-spring.xml
│   └── test/
│       └── java/
│           └── com/xly/erp/
│               └── module/
│                   └── usr/                  # 单元测试 + 集成测试
└── target/                                   # Maven 构建产物（gitignore）
```

> Flyway migration 不在 backend/ 下，统一在仓库根 `sql/migrations/`，由 Spring Boot 启动时自动 apply（见 docs/04 § Schema 演化规约）。

## 三、前端目录

前端按 Vite + React 18 + Ant Design 5 + Redux Toolkit + React Router v6 的惯例组织；业务页面按模块分组放在 `pages/<module>/`。

```
frontend/
├── package.json
├── vite.config.ts
├── tsconfig.json
├── index.html
├── src/
│   ├── main.tsx                              # 入口
│   ├── App.tsx                               # 根组件 + 路由
│   ├── api/                                  # Axios 实例 + 接口调用层
│   │   ├── client.ts                         # axios 实例 + 拦截器（401 / 错误统一处理）
│   │   └── usr.ts                            # 用户管理接口（按模块拆分）
│   ├── store/                                # Redux Toolkit
│   │   ├── index.ts                          # configureStore
│   │   └── slices/
│   │       └── auth.ts                       # 登录态 slice
│   ├── router/                               # React Router 配置
│   │   └── index.tsx
│   ├── pages/                                # 页面（按模块分组）
│   │   ├── login/                            # FE-NN 登录页
│   │   └── usr/                              # 用户管理页面
│   ├── components/                           # 跨页面通用组件
│   ├── layouts/                              # 框架布局（侧栏 / 顶栏 / 内容区）
│   ├── hooks/                                # 自定义 hook
│   ├── utils/                                # 工具方法
│   ├── styles/
│   │   └── tokens.css                        # Design Tokens（docs/06 § 二）
│   └── types/                                # 全局 TypeScript 类型
├── tests/                                    # Playwright E2E
└── dist/                                     # Vite 构建产物（gitignore）
```

> Vitest 组件测试与对应源码同级（`*.test.tsx`）。

## 四、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 运行时产物
```

## 五、命名与放置约定

### 5.1 根包 / 命名空间

- **Java 根包**: `com.xly.erp`
- **前端 npm 包名**: `xly-erp-frontend`

### 5.2 后端文件放置

| 类型 | 路径 | 命名 |
|---|---|---|
| Controller | `module/<m>/controller/<Entity>Controller.java` | 大驼峰 + `Controller` 后缀 |
| Service 接口 | `module/<m>/service/<Entity>Service.java` | 大驼峰 + `Service` 后缀 |
| Service 实现 | `module/<m>/service/impl/<Entity>ServiceImpl.java` | 大驼峰 + `ServiceImpl` 后缀 |
| Mapper 接口 | `module/<m>/mapper/<Entity>Mapper.java` | 大驼峰 + `Mapper` 后缀 |
| Mapper XML | `resources/mapper/<m>/<Entity>Mapper.xml` | 与接口同名 |
| Entity | `module/<m>/entity/<Entity>.java` | 大驼峰，业务实体名 |
| DTO（请求） | `module/<m>/dto/<Action><Entity>Req.java` | 动词 + 实体 + `Req`，如 `CreateUserReq` |
| VO（响应） | `module/<m>/vo/<Entity>Vo.java` 或 `<Entity>DetailVo.java` | 大驼峰 + `Vo` 后缀 |
| Converter | `module/<m>/converter/<Entity>Converter.java` | MapStruct 接口 |

### 5.3 前端文件放置

| 类型 | 路径 | 命名 |
|---|---|---|
| 页面 | `pages/<module>/<PageName>.tsx` | 大驼峰，与路由对齐 |
| 通用组件 | `components/<ComponentName>/index.tsx` | 大驼峰 |
| 接口调用 | `api/<module>.ts` | 小写模块名 |
| Redux slice | `store/slices/<feature>.ts` | 小驼峰 |
| 测试 | 与源文件同级 `<X>.test.tsx`（组件） / `tests/<X>.spec.ts`（E2E） | 与被测对象对齐 |

### 5.4 通用规则

- 所有 Java 包名小写；类名大驼峰；方法 / 字段小驼峰；常量全大写下划线。
- TypeScript / TSX 文件用大驼峰命名组件，其他用小驼峰。
- 业务模块代码与 docs/01 模块代码（USR / PUR / ...）保持一致，小写下划线作为目录名（`module/usr/`）。