09-项目目录结构

一、仓库顶层

<project-root>/
├── CLAUDE.md                  # CC 项目指令
├── README.md                  # 项目说明
├── .env.local                 # 本地环境变量（不入 git）
├── .gitignore
├── .githooks/
│   └── pre-push               # push 前测试闸门
├── scripts/
│   ├── setup-test-db.sh       # 重置测试数据库
│   └── test.sh                # 全量测试入口
├── sql/
│   └── migrations/            # Flyway V_n__*.sql
├── docs/                      # 规划文档（见 § 四）
├── backend/                   # Spring Boot 后端
└── frontend/                  # React 前端

二、后端目录

backend/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/
    │   │   └── com/example/erp/
    │   │       ├── config/             # Spring 配置类（Security、Swagger、MyBatis 等）
    │   │       ├── common/             # 通用工具（统一响应体、全局异常、枚举、常量）
    │   │       ├── module/
    │   │       │   └── usr/            # USR 用户管理模块
    │   │       │       ├── controller/ # REST 接口层
    │   │       │       ├── service/    # 业务逻辑层
    │   │       │       ├── mapper/     # MyBatis-Plus Mapper
    │   │       │       ├── entity/     # 数据库实体
    │   │       │       ├── dto/        # 请求参数 DTO
    │   │       │       └── vo/         # 响应视图 VO
    │   │       └── Application.java    # 启动类
    │   └── resources/
    │       ├── application.yml         # 主配置
    │       ├── application-dev.yml     # 开发环境配置
    │       ├── application-prod.yml    # 生产环境配置
    │       └── mapper/                 # MyBatis XML（可选）
    └── test/
        └── java/
            └── com/example/erp/
                └── module/
                    └── usr/            # USR 模块单元/集成测试

三、前端目录

frontend/
├── package.json
├── vite.config.ts
├── index.html
└── src/
    ├── main.tsx                # 应用入口
    ├── App.tsx                 # 根组件 + 路由配置
    ├── styles/
    │   └── tokens.css          # Design Token CSS 变量
    ├── api/                    # Axios 封装 + 各模块接口
    │   └── usr.ts              # USR 用户管理接口
    ├── store/                  # Redux Toolkit Store
    │   └── slices/
    │       └── authSlice.ts    # 认证状态
    ├── hooks/                  # 通用 React Hooks
    ├── components/             # 通用业务组件（PermButton 等）
    ├── pages/                  # 页面组件（按模块子目录）
    │   ├── usr/                # USR 用户管理页面
    │   │   ├── UserListPage.tsx
    │   │   ├── UserFormDrawer.tsx
    │   │   └── LoginPage.tsx
    │   └── 403.tsx             # 无权限页
    └── utils/                  # 工具函数

四、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
• Controller：XxxController.java，放 module/<mod>/controller/，只做入参校验 + 调 Service
• Service：XxxService.java 接口 + XxxServiceImpl.java 实现，放 module/<mod>/service/
• Mapper：XxxMapper.java，放 module/<mod>/mapper/，继承 BaseMapper<T>
• DTO：请求参数用 XxxReqDTO，放 module/<mod>/dto/
• VO：响应视图用 XxxVO，放 module/<mod>/vo/
• 前端组件：PascalCase，如 UserFormDrawer.tsx，放 components/ 或页面同级
• 前端页面：PascalCase + Page 后缀，如 UserListPage.tsx，放 pages/<mod>/
• 前端 API：camelCase 模块名，如 usr.ts，放 api/