重组前端功能目录并统一代码规范工具链 (#10)

Reviewed-on: #10
2026-09-29 18:09:38 +08:00
parent 720ad29f06
commit 0af0256c97
101 changed files with 14644 additions and 10309 deletions
@@ -0,0 +1,80 @@
+# 目录结构与依赖约定
+
+按业务功能组织文件，使一次功能修改涉及的页面、组件和状态尽量集中。文件迁移只改变源码路径，接口请求、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
+```
@@ -4,14 +4,14 @@

 ## 分层

-| 层级 | 文件 | 职责 |
-| --- | --- | --- |
-| 设计令牌 | `src/styles/tokens.css` | 颜色、字体、渐变、阴影、动效时长等稳定决策 |
-| 基础规则 | `src/styles/base.css` | 页面基线、选中文本、全局圆角策略 |
-| 组件规则 | `src/styles/components.css` | 页面 Hero、容器、表单、面板、按钮等共享语义类 |
-| 第三方主题 | `src/lib/theme.ts` | Naive UI 的全局主题契约；值应与设计令牌保持一致 |
-| 单组件样式 | Vue 文件的 `<style scoped>` | 只属于一个功能的滑杆、动画、地图或媒体细节 |
-| 一次性布局 | Vue 模板中的 Tailwind 类 | flex/grid、间距、响应式排列及确实只出现一次的视觉调整 |
+| 层级       | 文件                        | 职责                                                  |
+| ---------- | --------------------------- | ----------------------------------------------------- |
+| 设计令牌   | `src/styles/tokens.css`     | 颜色、字体、渐变、阴影、动效时长等稳定决策            |
+| 基础规则   | `src/styles/base.css`       | 页面基线、选中文本、全局圆角策略                      |
+| 组件规则   | `src/styles/components.css` | 页面 Hero、容器、表单、面板、按钮等共享语义类         |
+| 第三方主题 | `src/lib/theme.ts`          | Naive UI 的全局主题契约；值应与设计令牌保持一致       |
+| 单组件样式 | Vue 文件的 `<style scoped>` | 只属于一个功能的滑杆、动画、地图或媒体细节            |
+| 一次性布局 | Vue 模板中的 Tailwind 类    | flex/grid、间距、响应式排列及确实只出现一次的视觉调整 |

 `src/style.css` 只负责按以上顺序装配全局样式，不再直接堆放组件规则。

@@ -25,8 +25,8 @@ OpenCloud 的绿色应接近清晨的桉叶与嫩叶，而不是灰暗的苔藓
 - 不直接使用 Tailwind 默认 `green-*`、`lime-*`，也不要在组件里写亮绿色十六进制值或 RGB。
 - 新增绿色前先判断它属于品牌交互还是成功状态，并优先使用已有语义类或设计令牌。

-| 语义 | 主色 | 深色 | 浅色表面 |
-| --- | --- | --- | --- |
+| 语义      | 主色      | 深色      | 浅色表面  |
+| --------- | --------- | --------- | --------- |
 | 品牌/交互 | `#34745d` | `#274c40` | `#f2faf6` |
 | 成功/通过 | `#4d7f3b` | `#35522c` | `#f4faef` |

@@ -44,15 +44,15 @@ OpenCloud 的绿色应接近清晨的桉叶与嫩叶，而不是灰暗的苔藓

 ```html
 <section class="oc-page-hero">
-  <div class="oc-container oc-container--content oc-page-hero__inner">
-    <p class="oc-page-eyebrow">Cloud Upload</p>
-    <h1 class="oc-page-title">上传云图</h1>
-    <p class="oc-page-description">页面描述</p>
-  </div>
+    <div class="oc-container oc-container--content oc-page-hero__inner">
+        <p class="oc-page-eyebrow">Cloud Upload</p>
+        <h1 class="oc-page-title">上传云图</h1>
+        <p class="oc-page-description">页面描述</p>
+    </div>
 </section>

 <main class="oc-container oc-container--content oc-page-content">
-  <!-- 页面内容 -->
+    <!-- 页面内容 -->
 </main>
 ```

@@ -63,9 +63,7 @@ Hero 同时包含左侧介绍和右侧状态卡时，使用 `oc-page-hero__split
 ### 表单

 ```html
-<label class="oc-field-label">
-  拍摄时间 <span class="oc-field-required">*</span>
-</label>
+<label class="oc-field-label"> 拍摄时间 <span class="oc-field-required">*</span> </label>
 <input class="oc-field-control" />
 <p class="oc-field-help">补充说明</p>
 <p class="oc-field-error">错误信息</p>
@@ -88,12 +86,8 @@ Hero 同时包含左侧介绍和右侧状态卡时，使用 `oc-page-hero__split
 Naive UI 按钮继续使用 `type="default"`，视觉语义由共享类控制：

 ```html
-<NButton class="oc-panel-button oc-panel-button--neutral" type="default">
-  取消
-</NButton>
-<NButton class="oc-panel-button oc-panel-button--sky" type="default">
-  保存
-</NButton>
+<NButton class="oc-panel-button oc-panel-button--neutral" type="default"> 取消 </NButton>
+<NButton class="oc-panel-button oc-panel-button--sky" type="default"> 保存 </NButton>
 ```

 页面级主操作使用 `oc-primary-button`；面板内操作使用 `oc-panel-button`。可用变体为 `neutral`、`sky`、`teal`、`amber`、`danger`，不要临时创建新的强调色。其中 `teal` 是兼容命名，视觉上使用的是清新桉叶绿。