# 09-项目目录结构

## 一、仓库顶层

```
.
├── CLAUDE.md                  # 项目级规范与流程指令
├── README.md                  # 项目说明（可选）
├── .env.local                 # 本地凭据（不入 git）
├── .gitignore
├── .githooks/
│   └── pre-push               # 推送前自动跑 scripts/test.sh
├── scripts/
│   ├── test.sh                # 后端 + 前端测试组合入口
│   └── setup-test-db.sh       # 重置本地测试数据库
├── sql/
│   └── migrations/            # Flyway V*__*.sql 文件
├── docs/                      # 全量项目文档（见 § 四）
├── prototype/                 # 静态 HTML mockup（前端实现权威）
├── backend/                   # 后端工程（Spring Boot + Maven）
└── frontend/                  # 前端工程（Vite + React）
```

## 二、后端目录

```
backend/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/
    │   │   └── com.example.erp/
    │   │       ├── ErpApplication.java
    │   │       ├── common/                # 全局响应 / 异常 / 拦截器 / 工具
    │   │       │   ├── result/
    │   │       │   ├── exception/
    │   │       │   ├── interceptor/
    │   │       │   └── util/
    │   │       ├── config/                # Spring 配置类（Security / Redis / MyBatis-Plus / Swagger / Activiti）
    │   │       ├── module/                # 业务模块（按 docs/01 索引拆分）
    │   │       │   └── usr/               # USR 用户管理
    │   │       │       ├── controller/
    │   │       │       ├── service/
    │   │       │       │   └── impl/
    │   │       │       ├── mapper/
    │   │       │       ├── entity/
    │   │       │       ├── dto/
    │   │       │       └── vo/
    │   │       └── security/              # 认证 / 鉴权 / JWT
    │   └── resources/
    │       ├── application.yml
    │       ├── application-dev.yml
    │       ├── application-prod.yml
    │       ├── mapper/                    # MyBatis XML（按模块再分子目录）
    │       └── logback-spring.xml
    └── test/
        └── java/
            └── com.example.erp/
                └── module/
                    └── usr/               # 与 main/ 镜像
```

## 三、前端目录

```
frontend/
├── package.json
├── vite.config.ts
├── tsconfig.json
├── index.html
└── src/
    ├── main.tsx                   # 入口（挂载 React + Router + Store + ConfigProvider）
    ├── App.tsx                    # 顶层路由 + 全局 Layout
    ├── api/                       # Axios 实例 + 各模块 API（数据访问统一入口）
    │   └── usr.ts                 # USR 用户管理 API
    ├── components/                # 跨页面通用组件（AuthButton / AppTable / PageHeader 等）
    ├── pages/                     # 按业务模块组织页面
    │   └── usr/                   # USR 用户管理
    │       ├── UserList.tsx
    │       ├── UserEdit.tsx
    │       └── Login.tsx
    ├── store/                     # Redux Toolkit slices（全局状态）
    │   └── slices/
    ├── hooks/                     # 自定义 hook（useAuth / usePagination 等）
    ├── utils/                     # 工具函数（formatDate / formatMoney / regex 等）
    ├── styles/
    │   ├── tokens.css             # Design Tokens（docs/06 § 二）
    │   └── global.css             # 全局样式 reset / typography
    ├── router/                    # 路由表（含 meta.code 权限码）
    └── assets/                    # 静态资源（图片 / 字体）
```

> 注：仓库根 `src/styles/tokens.css` 由 skeleton-gen 创建，作为 Design Tokens 的「上游」源；前端工程化前可先保留在根 `src/styles/` 下，前端工程初始化时迁入 `frontend/src/styles/`（同名同内容）。

## 四、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`，下文统称 `<ROOT>`；新增业务模块时落到 `<ROOT>.module.<模块代码小写>`（如 `<ROOT>.module.usr`）。
- **Controller**：`<ROOT>.module.<m>.controller.<Module>Controller`，文件名首字母大写驼峰，URI 前缀 `/api/<模块代码小写>`。
- **Service**：接口 `<Module>Service` + 实现 `<Module>ServiceImpl`，实现类放 `service/impl/`。
- **Mapper**：`<Module>Mapper`（Java 接口）+ `resources/mapper/<m>/<Module>Mapper.xml`（XML 同名）。
- **Entity / DTO / VO**：
  - `entity/` 数据库实体（与表 1:1，字段类型同 docs/03）
  - `dto/` 入参（前端 → 后端的请求体）
  - `vo/` 出参（后端 → 前端的响应体）
- **前端组件**：通用组件放 `frontend/src/components/`，文件名首字母大写驼峰（`AuthButton.tsx`）；样式同名 `.module.css`（启用 CSS Modules）。
- **前端页面**：放 `frontend/src/pages/<模块代码小写>/`，文件名按业务功能命名（`UserList.tsx` / `UserEdit.tsx`），路由 path 前缀 `/<模块代码小写>`。
- **API 客户端**：每个模块一个文件 `frontend/src/api/<模块代码小写>.ts`，导出该模块所有接口函数；禁止在组件里直接 `axios.xxx`。