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/）。