# 09-项目目录结构

> 根包名 / 命名空间占位由人工补填一次，其他文档复用：
> - **后端根包名**：`com.xly.test4`

## 一、仓库顶层

```
<repo-root>/
├── CLAUDE.md                  # Claude Code 主指令
├── README.md                  # 项目说明（可选）
├── .env.local                 # 本地凭据（不入 git）
├── .env.example               # 凭据模板（可选）
├── .gitignore
├── .githooks/
│   └── pre-push               # MR 前测试闸门兜底
├── scripts/
│   ├── test.sh                # 一键测试
│   └── setup-test-db.sh       # 重置测试库
├── docs/                      # 项目文档（结构见 § 四）
├── sql/
│   └── migrations/            # Flyway V_n__*.sql
├── prototype/                 # 前端原型 HTML mockup（前端阶段权威布局）
├── backend/                   # Spring Boot 后端工程（结构见 § 二）
└── frontend/                  # Vite + React 前端工程（结构见 § 三）
```

## 二、后端目录

```
backend/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/xly/test4/
│   │   │       ├── Application.java           # @SpringBootApplication 入口
│   │   │       ├── common/                    # 跨模块基础设施
│   │   │       │   ├── config/                # Spring 配置类
│   │   │       │   ├── exception/             # 全局异常处理器 + 业务异常类
│   │   │       │   ├── response/              # 统一响应包装 Result<T>
│   │   │       │   ├── security/              # Spring Security + JWT
│   │   │       │   └── util/                  # 工具类
│   │   │       └── module/                    # 业务模块（按 docs/01 index）
│   │   │           └── usr/                   # USR 用户管理
│   │   │               ├── controller/
│   │   │               ├── service/
│   │   │               ├── mapper/
│   │   │               ├── entity/
│   │   │               ├── dto/
│   │   │               └── vo/
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── application-dev.yml
│   │       └── mapper/                        # MyBatis-Plus XML
│   │           └── usr/
│   └── test/
│       └── java/
│           └── com/xly/test4/
│               └── module/usr/                # 与 main 同包结构
```

业务模块按 `docs/01-需求清单/index.md` 的模块代码（小写）落到 `module/<code>/` 下；本项目当前模块：

| 模块代码 | 后端目录 |
|---|---|
| USR | `backend/src/main/java/com/xly/test4/module/usr/` |

## 三、前端目录

```
frontend/
├── package.json
├── vite.config.ts
├── tsconfig.json
├── index.html
└── src/
    ├── main.tsx                              # 入口
    ├── App.tsx                               # 顶层路由
    ├── api/                                  # 后端 API 客户端（按模块分文件）
    │   └── usr.ts
    ├── components/                           # 跨页面通用组件
    ├── pages/                                # 业务页面（按模块分子目录）
    │   └── usr/
    │       ├── LoginPage.tsx
    │       └── UserListPage.tsx
    ├── store/                                # Redux Toolkit slice
    │   └── usrSlice.ts
    ├── hooks/                                # 自定义 hooks
    ├── utils/                                # 纯工具函数
    ├── styles/
    │   └── tokens.css                        # Design Tokens（docs/06 § 二）
    └── types/                                # 全局 TS 类型
```

业务模块按 `docs/01-需求清单/index.md` 的模块代码（小写）落到 `pages/<code>/`、`api/<code>.ts`、`store/<code>Slice.ts`。

## 四、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 后端

- **根包名**：`com.xly.test4`（顶部已声明，本节作引用）。
- **包路径**：全小写、点分隔；模块代码作为子包名转小写（`USR` → `usr`）。
- **Controller**：`<根包>.module.<code>.controller.<Entity>Controller`，仅处理 HTTP 参数解析与响应包装，禁止写业务逻辑。
- **Service**：`<根包>.module.<code>.service.<Entity>Service` + 实现 `impl/<Entity>ServiceImpl`，业务逻辑与事务边界落在此层。
- **Mapper**：`<根包>.module.<code>.mapper.<Entity>Mapper` + `resources/mapper/<code>/<Entity>Mapper.xml`，仅数据访问，禁止跨模块查询。
- **Entity**：`<根包>.module.<code>.entity.<Entity>`，与数据库表一一对应。
- **DTO** / **VO**：`dto/<Entity>CreateDTO` 等用于入参，`vo/<Entity>VO` 用于出参；DTO → Entity → VO 转换走 MapStruct。
- **类名**：大驼峰；**方法名 / 变量**：小驼峰；**常量**：全大写下划线分隔；**布尔变量/方法**：`is` / `has` / `can` 前缀。

### 5.2 前端

- **页面组件**：大驼峰 + `Page` 后缀，如 `UserListPage.tsx`。
- **通用组件**：大驼峰，如 `AuthButton.tsx`。
- **api 文件**：模块代码小写 + `.ts`，如 `usr.ts`；导出函数名小驼峰，如 `loginUser`、`createUser`。
- **store slice**：模块代码小写 + `Slice.ts`。
- **hooks**：`use` 前缀小驼峰，如 `useCurrentUser.ts`。
- **样式 token**：变量名 `--color-<scope>-<role>-<state>`（见 docs/04 § 2.5）。

### 5.3 跨层禁止事项

- 前端 **禁止** 直接写 SQL / 访问数据库；所有数据访问走 `api/` 层封装。
- Controller **禁止** 注入 Mapper；必须通过 Service 中转。
- 跨模块调用 **禁止** 直接 import 另一模块的 Mapper / Entity；必须通过对方模块暴露的 Service 公共方法。