opencloud/docs/project-structure.md

目录结构与依赖约定

按业务功能组织文件，使一次功能修改涉及的页面、组件和状态尽量集中。通信层按下文分工；接口变更与后端配套验证，见通信架构。

目录职责

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、api-adapters.ts、pagination.ts、seo.ts、theme.ts
├── types/                      # 生成的 API 契约、前端模型、路由元数据
├── styles/                     # 全局设计令牌、基线、共享样式
└── style.css                   # 全局样式入口

文件归属

修改内容	归属位置
登录、会话、验证邮件	features/auth/
多个页面复用的云图详情、编辑、点赞	features/clouds/
上传表单、上传弹窗、文件处理与上传状态	features/upload/
用户主页、设置、贡献热力图	features/profile/
图鉴列表、云型详情及其状态	features/encyclopedia/
首页地图时间轴、标记交互	features/map/
通用选点、位置预览、高德加载	shared/map/
应用导航和整体布局	components/layout/
HTTP 请求与响应适配、公共 API 类型	lib/api.ts、lib/api-adapters.ts、types/api-contract.ts

按职责归属文件：快捷上传虽然从地图打开，仍属于上传模块；云图点赞虽然在多个页面使用，仍属于云图业务；选点和小地图仅提供位置能力，放在公共地图模块。

依赖与新增文件

• 功能模块按需创建 views/、components/、stores/、composables/；只有页面的模块保留 views/ 即可。
• 业务组件放在所属功能模块。components/layout/ 仅存放应用布局，lib/ 存放公共基础设施。
• 功能模块可以依赖公共地图能力、基础设施、公共类型和其他模块的具体组件、store 或 composable。shared/map/、lib/ 和 types/ 保持独立于业务模块；新增跨模块依赖时避免循环引用。
• 使用 @/features/...、@/shared/... 等具体文件路径，不增加统一导出所有页面和 store 的入口。路由继续在 router/index.ts 中动态导入各模块页面，保持按页面懒加载。
• 页面与 store 调用所属功能的 api.ts，由该模块通过 lib/api.ts 发送请求。认证 SDK 调用集中在 features/auth/authClient.ts 和认证 store。生成 DTO 在 types/api-contract.ts，前端模型在 types/models.ts 与 types/view-models.ts。
• 现有 clouds 与 encyclopedia store 保留各自的缓存行为；后续如需合并缓存，应作为独立行为变更验证。
• 共享视觉规则遵循样式体系，组件专属样式随组件迁移。

例如，新增上传进度组件放到 features/upload/components/；新增通用地图控件放到 shared/map/components/；新增个人主页统计 composable 放到 features/profile/composables/。

迁移验证

移动文件后更新静态 import、路由动态 import 和文档引用，并运行：

npm run check
npm run build
git diff --check