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。