# Directory Structure Template

本文用于给项目补一份明确的目录结构真相源，减少 AI 在文件放置、目录新建和业务域组织上的随意性。

## 适用场景

- 项目目录较大，单靠 `repo-map.md` 不足以约束文件放置。
- 同一项目中同时存在页面、组件、API、hooks、types、constants、测试等多类资产。
- 团队已经反复遇到“文件放错位置”“随意新建目录”“按技术类型乱堆而不是按业务域组织”的问题。

## 目标

- 说明已有目录各自负责什么。
- 说明新文件应该放到哪里。
- 说明哪些目录名禁止新增。
- 说明是按业务域组织，还是按技术层组织，或两者混合。

## 目录规范模板

```markdown
# Directory Structure

## 1. 组织原则

- 当前项目主要按 `<业务域 / 技术层 / 混合模式>` 组织。
- 业务域优先的模块：`<features/<domain> / packages/<domain> / apps/<domain>>`
- 技术层优先的共享目录：`<components/common / services / hooks / types / constants>`
- 当业务域目录与共享目录冲突时，优先规则：`<写清优先级>`

## 2. 顶层目录说明

| 路径 | 用途 | 应放内容 | 不应放内容 |
| --- | --- | --- | --- |
| `src/pages/` | 页面 / 路由 | 页面组合、路由入口 | 纯公共组件、HTTP 调用细节 |
| `src/components/common/` | 通用组件 | 无业务语义组件 | 业务状态、业务权限 |
| `src/features/` | 业务域模块 | 业务组件、业务 hooks、领域 model | 全局通用 primitive |
| `src/services/` | API / service | HTTP client、service 封装 | 页面 UI 逻辑 |
| `src/hooks/` | 通用 hooks | 跨页面复用 hooks | 页面专用临时逻辑 |
| `src/types/` | 类型 | 通用类型、契约类型 | 页面样式、业务逻辑 |
| `src/constants/` | 常量 | 枚举、配置常量 | 函数实现 |
| `tests/` | 测试 | 同构测试、集成测试、E2E | 生产代码 |

## 3. 新文件放置规则

- 页面级组件：放到对应页面目录或 `features/<domain>/components`
- 可复用业务组件：放到 `features/<domain>/components`
- 全局公共组件：放到 `components/common`
- 接口请求：放到 `services/` 或 `features/<domain>/api/`
- 类型定义：放到 `types/` 或模块内 `model/` / `types/`
- 测试文件：与源码保持同构，或进入明确的测试目录

## 4. 禁止新增的目录名

- `newFeature/`
- `featureNew/`
- `myComponents/`
- `common2/`
- `utils2/`
- `helper/`
- `temp/`
- `test-new/`

## 5. 新增目录前必须回答

- 为什么需要新目录？
- 现有目录为什么不能放？
- 这个目录未来会放什么？
- 是否符合当前项目现有结构？
- 是否需要给该目录补 `AGENTS.md`？

## 6. 业务域组织规则

- 若按业务域组织，推荐域列表：`<domain-a> / <domain-b> / <domain-c>`
- 新业务代码默认先进对应业务域目录。
- 只有跨业务复用已被验证后，才允许上提到共享层。

## 7. 测试与索引同步

- 新增目录后，如影响导航，更新 `docs/ai/repo-map.md`
- 新增目录后，如目录规则明显不同，补该目录 `AGENTS.md`
- 新增目录后，补充相关测试入口或验证命令
```

## 使用建议

- 根 `AGENTS.md` 只索引这份文档，不复制全文。
- `repo-map.md` 负责导航；本文件负责放置规范。
- 如果项目已有强约束的前端目录规则，优先和 `templates/design/frontend-architecture.md` 对齐。
