81 lines
4.8 KiB
Markdown
81 lines
4.8 KiB
Markdown
# 目录结构与依赖约定
|
|
|
|
按业务功能组织文件，使一次功能修改涉及的页面、组件和状态尽量集中。文件迁移只改变源码路径，接口请求、DTO、store 导出与 ID、组件 props/events、路由 URL 和页面行为保持不变。
|
|
|
|
## 目录职责
|
|
|
|
```text
|
|
src/
|
|
├── main.ts # 初始化 Pinia、认证和路由
|
|
├── App.vue # 全局 provider 与应用布局
|
|
├── router/index.ts # 路由、懒加载、权限守卫与 SEO
|
|
├── features/
|
|
│ ├── auth/
|
|
│ │ ├── authClient.ts # 认证客户端与错误适配
|
|
│ │ ├── stores/auth.ts
|
|
│ │ └── views/ # 登录、注册、邮箱验证、密码重置
|
|
│ ├── clouds/
|
|
│ │ ├── cloudTypes.ts # 云型常量与名称查询
|
|
│ │ ├── components/ # 云图详情、编辑、点赞
|
|
│ │ └── stores/ # clouds.ts、likes.ts
|
|
│ ├── upload/
|
|
│ │ ├── components/QuickUploadModal.vue
|
|
│ │ ├── composables/useUpload.ts
|
|
│ │ └── views/UploadView.vue
|
|
│ ├── profile/
|
|
│ │ ├── components/ContributionHeatmap.vue
|
|
│ │ ├── stores/profile.ts
|
|
│ │ └── views/ # 个人主页与账号设置
|
|
│ ├── encyclopedia/
|
|
│ │ ├── stores/encyclopedia.ts
|
|
│ │ └── views/ # 图鉴列表与云型详情
|
|
│ └── {map,gallery,community,admin,system}/views/
|
|
├── shared/map/
|
|
│ ├── amap.ts # 高德加载器
|
|
│ ├── types/amap.d.ts # 高德类型声明，与同名加载器分开放置
|
|
│ └── components/ # MapPickerModal、MiniLocationMap
|
|
├── components/layout/ # 应用外壳：AppHeader
|
|
├── lib/ # api.ts、seo.ts、theme.ts
|
|
├── types/ # 公共 DTO、领域类型、路由元数据
|
|
├── styles/ # 全局设计令牌、基线、共享样式
|
|
└── style.css # 全局样式入口
|
|
```
|
|
|
|
## 文件归属
|
|
|
|
| 修改内容 | 归属位置 |
|
|
| -------------------------------------- | ---------------------------- |
|
|
| 登录、会话、验证邮件 | `features/auth/` |
|
|
| 多个页面复用的云图详情、编辑、点赞 | `features/clouds/` |
|
|
| 上传表单、上传弹窗、文件处理与上传状态 | `features/upload/` |
|
|
| 用户主页、设置、贡献热力图 | `features/profile/` |
|
|
| 图鉴列表、云型详情及其状态 | `features/encyclopedia/` |
|
|
| 首页地图时间轴、标记交互 | `features/map/` |
|
|
| 通用选点、位置预览、高德加载 | `shared/map/` |
|
|
| 应用导航和整体布局 | `components/layout/` |
|
|
| HTTP 请求与响应适配、公共 API 类型 | `lib/api.ts`、`types/api.ts` |
|
|
|
|
按职责归属文件：快捷上传虽然从地图打开，仍属于上传模块；云图点赞虽然在多个页面使用，仍属于云图业务；选点和小地图仅提供位置能力，放在公共地图模块。
|
|
|
|
## 依赖与新增文件
|
|
|
|
- 功能模块按需创建 `views/`、`components/`、`stores/`、`composables/`；只有页面的模块保留 `views/` 即可。
|
|
- 业务组件放在所属功能模块。`components/layout/` 仅存放应用布局，`lib/` 存放公共基础设施。
|
|
- 功能模块可以依赖公共地图能力、基础设施、公共类型和其他模块的具体组件、store 或 composable。`shared/map/`、`lib/` 和 `types/` 保持独立于业务模块；新增跨模块依赖时避免循环引用。
|
|
- 使用 `@/features/...`、`@/shared/...` 等具体文件路径，不增加统一导出所有页面和 store 的入口。路由继续在 `router/index.ts` 中动态导入各模块页面，保持按页面懒加载。
|
|
- API 请求继续使用 `lib/api.ts`，认证 SDK 调用集中在 `features/auth/authClient.ts` 和认证 store。DTO 与领域类型仍由 `types/` 统一提供。
|
|
- 现有 `clouds` 与 `encyclopedia` store 保留各自的缓存行为；后续如需合并缓存，应作为独立行为变更验证。
|
|
- 共享视觉规则遵循[样式体系](style-system.md)，组件专属样式随组件迁移。
|
|
|
|
例如，新增上传进度组件放到 `features/upload/components/`；新增通用地图控件放到 `shared/map/components/`；新增个人主页统计 composable 放到 `features/profile/composables/`。
|
|
|
|
## 迁移验证
|
|
|
|
移动文件后更新静态 import、路由动态 import 和文档引用，并运行：
|
|
|
|
```bash
|
|
npm run check
|
|
npm run build
|
|
git diff --check
|
|
```
|