09-项目目录结构

根包名 / 命名空间占位由人工补填一次，其他文档复用：

• 后端根包名：com.xly.test4

一、仓库顶层

<repo-root>/
├── CLAUDE.md                  # Claude Code 主指令
├── README.md                  # 项目说明（可选）
├── .env.local                 # 本地凭据（不入 git）
├── .env.example               # 凭据模板（可选）
├── .gitignore
├── .githooks/
│   └── pre-push               # MR 前测试闸门兜底
├── scripts/
│   ├── test.sh                # 一键测试
│   └── setup-test-db.sh       # 重置测试库
├── docs/                      # 项目文档（结构见 § 四）
├── sql/
│   └── migrations/            # Flyway V_n__*.sql
├── prototype/                 # 前端原型 HTML mockup（前端阶段权威布局）
├── backend/                   # Spring Boot 后端工程（结构见 § 二）
└── frontend/                  # Vite + React 前端工程（结构见 § 三）

二、后端目录

backend/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/xly/test4/
│   │   │       ├── Application.java           # @SpringBootApplication 入口
│   │   │       ├── common/                    # 跨模块基础设施
│   │   │       │   ├── config/                # Spring 配置类
│   │   │       │   ├── exception/             # 全局异常处理器 + 业务异常类
│   │   │       │   ├── response/              # 统一响应包装 Result<T>
│   │   │       │   ├── security/              # Spring Security + JWT
│   │   │       │   └── util/                  # 工具类
│   │   │       └── module/                    # 业务模块（按 docs/01 index）
│   │   │           └── usr/                   # USR 用户管理
│   │   │               ├── controller/
│   │   │               ├── service/
│   │   │               ├── mapper/
│   │   │               ├── entity/
│   │   │               ├── dto/
│   │   │               └── vo/
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── application-dev.yml
│   │       └── mapper/                        # MyBatis-Plus XML
│   │           └── usr/
│   └── test/
│       └── java/
│           └── com/xly/test4/
│               └── module/usr/                # 与 main 同包结构

业务模块按 docs/01-需求清单/index.md 的模块代码（小写）落到 module/<code>/ 下；本项目当前模块：

模块代码	后端目录
USR	backend/src/main/java/com/xly/test4/module/usr/

三、前端目录

frontend/
├── package.json
├── vite.config.ts
├── tsconfig.json
├── index.html
└── src/
    ├── main.tsx                              # 入口
    ├── App.tsx                               # 顶层路由
    ├── api/                                  # 后端 API 客户端（按模块分文件）
    │   └── usr.ts
    ├── components/                           # 跨页面通用组件
    ├── pages/                                # 业务页面（按模块分子目录）
    │   └── usr/
    │       ├── LoginPage.tsx
    │       └── UserListPage.tsx
    ├── store/                                # Redux Toolkit slice
    │   └── usrSlice.ts
    ├── hooks/                                # 自定义 hooks
    ├── utils/                                # 纯工具函数
    ├── styles/
    │   └── tokens.css                        # Design Tokens（docs/06 § 二）
    └── types/                                # 全局 TS 类型

业务模块按 docs/01-需求清单/index.md 的模块代码（小写）落到 pages/<code>/、api/<code>.ts、store/<code>Slice.ts。

四、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 后端

• 根包名：com.xly.test4（顶部已声明，本节作引用）。
• 包路径：全小写、点分隔；模块代码作为子包名转小写（USR → usr）。
• Controller：<根包>.module.<code>.controller.<Entity>Controller，仅处理 HTTP 参数解析与响应包装，禁止写业务逻辑。
• Service：<根包>.module.<code>.service.<Entity>Service + 实现 impl/<Entity>ServiceImpl，业务逻辑与事务边界落在此层。
• Mapper：<根包>.module.<code>.mapper.<Entity>Mapper + resources/mapper/<code>/<Entity>Mapper.xml，仅数据访问，禁止跨模块查询。
• Entity：<根包>.module.<code>.entity.<Entity>，与数据库表一一对应。
• DTO / VO：dto/<Entity>CreateDTO 等用于入参，vo/<Entity>VO 用于出参；DTO → Entity → VO 转换走 MapStruct。
• 类名：大驼峰；方法名 / 变量：小驼峰；常量：全大写下划线分隔；布尔变量/方法：is / has / can 前缀。

5.2 前端

• 页面组件：大驼峰 + Page 后缀，如 UserListPage.tsx。
• 通用组件：大驼峰，如 AuthButton.tsx。
• api 文件：模块代码小写 + .ts，如 usr.ts；导出函数名小驼峰，如 loginUser、createUser。
• store slice：模块代码小写 + Slice.ts。
• hooks：use 前缀小驼峰，如 useCurrentUser.ts。
• 样式 token：变量名 --color-<scope>-<role>-<state>（见 docs/04 § 2.5）。

5.3 跨层禁止事项

• 前端 禁止 直接写 SQL / 访问数据库；所有数据访问走 api/ 层封装。
• Controller 禁止 注入 Mapper；必须通过 Service 中转。
• 跨模块调用 禁止 直接 import 另一模块的 Mapper / Entity；必须通过对方模块暴露的 Service 公共方法。