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/，按模块分文件后聚合