目录结构分析.md
14.6 KB
项目目录结构分析
最后更新: 2026-02-09 项目根目录: /Users/huyirui/program/itomix/git/map-demo
完整目录树
map-demo/
├── public/ # 静态资源目录
├── docs/ # 项目文档（新增）
│ ├── 项目架构分析/
│ ├── 功能模块分析/
│ ├── 注意事项与陷阱/
│ └── 开发指南/
├── src/ # 源代码目录
│ ├── api/ # API 接口定义
│ │ ├── B/ # B端（企业端）API
│ │ │ ├── audit.js # 审计相关
│ │ │ ├── kg.js # 卡片相关？
│ │ │ └── localism.js # 本土化相关
│ │ ├── C/ # C端（用户端）API
│ │ │ ├── book.js # 预订相关
│ │ │ ├── donate.js # 捐赠相关
│ │ │ ├── kg.js # 卡片相关？
│ │ │ ├── me.js # 个人中心
│ │ │ ├── perf.js # 性能相关？
│ │ │ └── prod.js # 产品相关
│ │ ├── wx/ # 微信相关 API
│ │ │ ├── config.js # 微信配置
│ │ │ ├── jsApiList.js # JS API 列表
│ │ │ └── pay.js # 微信支付
│ │ ├── checkin.js # 打卡 API
│ │ ├── common.js # 通用 API（短信、上传、Token）
│ │ ├── fn.js # API 包装器（错误处理）
│ │ └── map.js # 地图数据 API
│ ├── assets/ # 资源文件
│ │ ├── css/ # 全局样式
│ │ ├── images/ # 图片资源
│ │ ├── mock/ # Mock 数据
│ │ │ ├── routes.js # 路由 Mock 数据
│ │ │ ├── video_list.js # 视频列表 Mock
│ │ │ └── video_list1.js # 视频列表 Mock 1
│ │ └── styles/ # 样式文件
│ │ └── base.less # 基础样式（全局注入）
│ ├── common/ # 通用代码
│ │ ├── alert.js # 弹窗提示
│ │ ├── inner_router.js # 内部路由
│ │ ├── map_data.js # 地图数据
│ │ ├── max.js # 最大值处理？
│ │ ├── members.js # 成员管理
│ │ ├── mixin.js # Vue 混入
│ │ ├── my_router.js # 自定义路由
│ │ ├── tool.js # 工具函数
│ │ ├── yard.js # 院落相关
│ │ └── vueuse.js # VueUse 封装
│ ├── components/ # 公共组件
│ │ ├── Floor/ # 楼层平面图组件
│ │ │ ├── index.vue # 主组件
│ │ │ ├── pin.js # 标记点
│ │ │ └── svgIcon.vue # SVG 图标
│ │ ├── VRViewer/ # VR 全景查看器
│ │ │ └── index.vue
│ │ ├── audioBackground.vue # 背景音频（单模式）
│ │ ├── audioBackground1.vue # 背景音频（备用）
│ │ ├── audioList.vue # 音频列表（播放列表模式）
│ │ ├── InfoWindowLite.vue # 信息窗口（轻量版）
│ │ ├── InfoWindowWarn.vue # 信息窗口（警告版）
│ │ ├── InfoWindowYard.vue # 信息窗口（院落版）
│ │ ├── InfoPopupLite.vue # 信息弹窗（轻量版）
│ │ └── InfoPopupWarn.vue # 信息弹窗（警告版）
│ ├── hooks/ # Vue Hooks
│ │ ├── injectionSymbols.js # 注入符号
│ │ ├── useContext.js # 上下文 Hook
│ │ ├── useDebounce.js # 防抖 Hook
│ │ ├── useFlowFn.js # 流程函数 Hook
│ │ ├── useGo.js # 跳转 Hook
│ │ └── useKeepAlive.js # Keep-Alive Hook
│ ├── packages/ # 多页面应用包（已废弃）
│ │ ├── mono1/ # 子应用 1
│ │ │ ├── App.vue
│ │ │ ├── index.html
│ │ │ ├── main.js
│ │ │ ├── router.js
│ │ │ └── views/
│ │ │ └── index.vue
│ │ └── mono2/ # 子应用 2
│ │ ├── App.vue
│ │ ├── index.html
│ │ ├── main.js
│ │ ├── router.js
│ │ └── views/
│ │ └── index.vue
│ ├── router/ # 路由配置
│ │ ├── routes/ # 路由模块
│ │ │ └── modules/
│ │ │ └── auth/ # 认证路由
│ │ │ └── index.js
│ │ └── methods/ # 路由方法（可能不存在）
│ ├── settings/ # 设置
│ │ ├── componentSetting.js # 组件设置
│ │ └── designSetting.js # 设计设置
│ ├── store/ # Pinia 状态管理
│ │ ├── index.js # 主 Store
│ │ └── test.js # 测试 Store
│ ├── test/ # 测试
│ │ └── mocha/
│ │ └── test.js # Mocha 测试
│ ├── utils/ # 工具函数
│ │ ├── MonitorKeyboard.js # 键盘监控
│ │ ├── TileCutter.js # 瓦片切割
│ │ ├── axios.js # Axios 实例
│ │ ├── generateIcons.js # 生成图标
│ │ ├── generateModules.js # 生成模块
│ │ ├── generatePackage.js # 生成包
│ │ ├── generateRoute.js # 生成路由
│ │ ├── share.js # 分享工具
│ │ ├── tools.js # 通用工具
│ │ └── vconsole.js # VConsole 调试
│ ├── views/ # 页面组件
│ │ ├── bieyuan/ # 别院模块
│ │ │ ├── index.vue # 别院首页
│ │ │ ├── info_w.vue # 信息页面（带警告）
│ │ │ └── scan.vue # 扫码页面
│ │ ├── by/ # BY 模块
│ │ │ ├── index.vue # BY 首页
│ │ │ ├── info.vue # 信息页面
│ │ │ ├── info_w.vue # 信息页面（带警告）
│ │ │ └── scan.vue # 扫码页面
│ │ ├── checkin/ # 打卡模块
│ │ │ ├── index.vue # 打卡首页
│ │ │ ├── info.vue # 打卡信息
│ │ │ ├── info_w.vue # 打卡信息（带警告）
│ │ │ └── scan.vue # 扫码打卡
│ │ ├── xys/ # XYS 模块
│ │ ├── about.vue # 关于页面
│ │ ├── auth.vue # 认证页面
│ │ ├── info.vue # 信息页面
│ │ ├── noticeList.vue # 通知列表
│ │ └── test.vue # 测试页面
│ ├── App.vue # 根组件
│ ├── constant.js # 常量定义
│ ├── main.js # 入口文件
│ ├── route.js # 路由配置（辅助）
│ ├── router.js # 路由配置（主）
│ ├── theme-vars.js # 主题变量
│ └── auto-imports.d.ts # 自动导入类型定义
├── build/ # 构建配置
│ └── proxy.js # 代理配置
├── .history/ # 文件历史（Git 记录）
├── .env # 环境变量（基础）
├── .env.development # 环境变量（开发）
├── .env.production # 环境变量（生产）
├── .eslintrc.js # ESLint 配置
├── .gitignore # Git 忽略文件
├── index.html # 主入口 HTML
├── package.json # 项目依赖
├── vite.config.js # Vite 配置
├── cypress.json # Cypress 配置
├── CLAUDE.md # Claude Code 项目指南
├── README.md # 项目说明
└── tsconfig.json # TypeScript 配置
核心目录说明
1. src/api/ - API 接口层
职责: 定义所有与后端交互的 API 接口
结构:
-
B/: B端（企业/管理端）接口 -
C/: C端（用户/客户端）接口 -
wx/: 微信相关接口（配置、支付） -
common.js: 通用接口（短信、上传、Token） -
fn.js: API 包装器，统一错误处理
关键文件:
-
fn.js: 核心 API 包装器，处理响应验证和错误 -
map.js: 地图数据接口 -
checkin.js: 打卡功能接口
2. src/components/ - 公共组件
职责: 可复用的 Vue 组件
核心组件:
-
Floor/: 楼层平面图组件（SVG 交互） -
VRViewer/: 360° 全景查看器 -
audioBackground.vue: 背景音频播放（单模式） -
audioList.vue: 音频列表播放（列表模式） -
InfoWindow*.vue: 各种样式的信息窗口
3. src/views/ - 页面组件
职责: 页面级组件
模块划分:
-
bieyuan/: 别院模块 -
by/: BY 模块 -
checkin/: 打卡模块 -
xys/: XYS 模块
共同页面:
-
about.vue: 关于页面 -
auth.vue: 认证页面 -
info.vue: 信息页面 -
noticeList.vue: 通知列表 -
test.vue: 测试页面
4. src/store/ - 状态管理
职责: Pinia 全局状态
核心状态:
-
keepPages: Keep-Alive 缓存页面列表 - 音频播放状态（单模式和播放列表模式）
- 滚动位置状态
- 用户认证状态
5. src/router/ - 路由配置
职责: Vue Router 路由定义
特点:
- 使用 Hash 模式 (
createWebHashHistory('/index.html')) - 动态路由生成（从 Mock 数据加载）
- 模块化路由（
routes/modules/）
6. src/utils/ - 工具函数
职责: 通用工具函数和辅助方法
核心工具:
-
axios.js: Axios 实例（拦截器配置） -
tools.js: 通用工具函数 -
share.js: 微信分享工具 -
generateRoute.js: 动态路由生成
7. src/common/ - 通用代码
职责: 跨层级的通用代码
核心文件:
-
map_data.js: 地图数据处理 -
mixin.js: Vue 混入 -
alert.js: 弹窗提示
8. src/packages/ - 多页面应用（已废弃）
状态: 代码已存在，但未在构建配置中启用
说明:
-
mono1/,mono2/: 两个独立的子应用 -
vite.config.js中相关配置已注释
9. build/ - 构建配置
职责: Vite 构建相关配置
核心文件:
-
proxy.js: 代理配置生成器
文件命名规范
Vue 组件
页面组件: index.vue（放在模块目录下）
公共组件: PascalCase.vue（多单词，大驼峰）
示例:
- ✅
audioList.vue - ✅
VRViewer/index.vue - ✅
InfoWindowLite.vue
JavaScript 文件
工具函数: camelCase.js（小驼峰）
常量文件: constant.js
配置文件: *.config.js
示例:
- ✅
tools.js - ✅
useDebounce.js - ✅
vite.config.js
样式文件
全局样式: base.less
组件样式: 与组件同名的 .less 文件
目录组织原则
1. 按功能划分
-
api/: 按业务端（B/C）和功能（wx/map）划分 -
views/: 按业务模块（bieyuan/by/checkin/xys）划分 -
components/: 按功能组件（Floor/VRViewer）划分
2. 按层级划分
-
src/: 源代码根目录 -
public/: 静态资源（不经过 Vite 处理） -
build/: 构建脚本和配置 -
docs/: 项目文档
3. 特殊目录
-
.history/: Git 文件历史（本地编辑器生成） -
node_modules/: 依赖包（.gitignore） -
dist/: 构建输出（.gitignore）
建议的目录优化
1. 清理废弃代码
# 建议移除或归档
src/packages/ # 多页面应用（已废弃）
.history/ # 本地编辑器历史（不应提交）
2. 统一 API 结构
src/api/
├── modules/ # 按功能模块划分
│ ├── auth.js
│ ├── map.js
│ ├── checkin.js
│ └── wechat/
│ ├── config.js
│ ├── pay.js
│ └── jsapi.js
├── common.js # 通用 API
└── fn.js # API 包装器
3. 组件分类
src/components/
├── ui/ # 基础 UI 组件
├── business/ # 业务组件
│ ├── map/
│ │ ├── Floor/
│ │ ├── VRViewer/
│ │ └── InfoWindow/
│ └── audio/
│ ├── audioBackground.vue
│ └── audioList.vue
└── layouts/ # 布局组件
4. Hooks 分类
src/hooks/
├── router/ # 路由相关
│ ├── useGo.js
│ └── useKeepAlive.js
├── data/ # 数据相关
│ └── useContext.js
└── utils/ # 工具相关
└── useDebounce.js
文件搜索指南
查找页面组件
# 查找所有页面组件
find src/views -name "index.vue"
# 查找特定模块的页面
ls src/views/bieyuan/
ls src/views/by/
ls src/views/checkin/
查找公共组件
# 查找所有公共组件
find src/components -name "*.vue"
# 查找特定组件
find src/components -name "*Window*.vue"
find src/components -name "*audio*.vue"
查找 API 定义
# 查找所有 API 文件
find src/api -name "*.js"
# 查找特定 API
grep -r "mapAPI" src/api/
grep -r "checkinAPI" src/api/
查找工具函数
# 查找所有工具文件
ls src/utils/
# 搜索特定函数
grep -r "function formatTime" src/
Git 相关
.gitignore 关键配置
node_modules/
dist/
.history/
*.log
.DS_Store
建议添加
# IDE
.vscode/
.idea/
# 本地环境
.env.local
.env.*.local
# 测试覆盖率
coverage/
# 临时文件
*.tmp
*.temp