Hooke / map-demo

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
9a44b51e 1 parent c78d160f

docs(checkin): 添加动态标签页分析与重构方案文档 

- 添加 checkin/info 页面动态标签页分析文档
- 添加接口接入准备方案（3 种方案）
- 添加代码重构总结文档
- 添加项目多模块架构重构方案
- 分析当前标签页配置实现
- 设计接口数据结构和接入方案
- 完成代码重构，消除重复逻辑

相关文件:
- docs/checkin-info-动态标签页分析与准备.md
- docs/checkin-info-代码重构总结.md
- docs/多模块架构重构方案.md

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Inline Side-by-side
Showing 3 changed files with 1840 additions and 0 deletions
# checkin/info 代码重构总结
> **日期**: 2026-02-09
> **目的**: 重构动态标签页配置，消除代码重复，为接口接入做准备
---
## ✅ 重构完成
### 修改的文件
1. **新增**: `src/views/checkin/tab-config.js` - 标签页配置和工具函数
2. **修改**: `src/views/checkin/info.vue` - 使用新配置
### 代码统计
```
src/views/checkin/
├── tab-config.js (新增, 167 行)
└── info.vue (修改: +12 行, -32 行, 净减少 20 行)
```
---
## 📝 重构内容
### 1. 新建配置文件
**文件**: `src/views/checkin/tab-config.js`
**导出内容**：
- ✅ `TAB_CONFIGS` - 标签页配置数组（3 个标签页）
- ✅ `setTabTitles()` - 设置标签页标题工具函数
- ✅ `updateTabConfigsFromAPI()` - 从接口更新配置（预留，未使用）
- ✅ `getVisibleTabConfigs()` - 获取可见标签页（预留，未使用）
**关键改进**：
```javascript
// ❌ 重构前：default_title 写死
default_title: '敬老月优惠'
// ✅ 重构后：通用默认值
default_title: '介绍' // introduction
default_title: '故事' // story
default_title: '体验' // experience
```
### 2. 修改 info.vue
#### 变更 1: 添加导入（第 101 行）
```javascript
// ✅ 新增导入
import { TAB_CONFIGS, setTabTitles, updateTabConfigsFromAPI } from './tab-config.js'
```
#### 变更 2: 简化配置定义（第 157 行）
```javascript
// ❌ 删除：23 行重复的配置数组
// const tab_configs = ref([{ key, title_key, ... }])
// ✅ 替换为：1 行导入的配置
const tab_configs = ref(TAB_CONFIGS)
```
#### 变更 3: 简化标题设置逻辑
**第 1 处**：watch props.info（第 160-177 行）
```javascript
// ❌ 删除：重复的 forEach 循环（5 行代码）
tab_configs.value.forEach(config => {
page_details.value[config.title_key] =
page_details.value[config.title_key] || config.default_title;
});
// ✅ 替换为：工具函数调用（1 行代码）
page_details.value = setTabTitles(page_details.value, tab_configs.value);
```
**第 2 处**：onMounted（第 279-282 行）
```javascript
// ❌ 删除：重复的 forEach 循环（5 行代码）
tab_configs.value.forEach(config => {
page_details.value[config.title_key] =
page_details.value[config.title_key] || config.default_title;
});
// ✅ 替换为：工具函数调用（1 行代码）
page_details.value = setTabTitles(page_details.value, tab_configs.value);
```
---
## 🎯 重构收益
### 代码质量提升
| 指标 | 重构前 | 重构后 | 改善 |
|------|--------|--------|------|
| **代码重复** | 2 处（每处 5 行） | 0 处 | ✅ -100% |
| **配置行数** | 23 行 | 17 行 | ✅ -26% |
| **总代码行数** | 806 行 | 786 行 | ✅ -20 行 |
| **可维护性** | 低 | 高 | ✅ 显著提升 |
### 维护性提升
**重构前**：
- ❌ 修改默认标题需要改 3 处（每个标签页 1 处）
- ❌ 添加新标签页需要复制粘贴配置
- ❌ 标题设置逻辑重复（DRY 原则违反）
**重构后**：
- ✅ 修改默认标题只需改 1 处（tab-config.js）
- ✅ 添加新标签页只需在 TAB_CONFIGS 添加配置
- ✅ 代码遵循 DRY 原则（Don't Repeat Yourself）
### 可扩展性提升
**重构前**：
- ❌ 配置分散在组件内部
- ❌ 难以复用和测试
**重构后**：
- ✅ 配置独立文件，易于管理
- ✅ 提供工具函数，易于复用
- ✅ 便于编写单元测试
- ✅ 为接口接入做好准备
---
## 🔮 后续接口接入
### 准备就绪的功能
重构后的代码已经为接口接入做好准备：
#### 1. 工具函数已实现
```javascript
// 设置标签页标题（已使用）
setTabTitles(page_details, tab_configs)
// 从接口更新配置（已实现，待使用）
updateTabConfigsFromAPI(apiData, tab_configs)
```
#### 2. 接口接入步骤（将来）
**等接口确定后，只需 2 步**：
**步骤 1**: 在 `onMounted` 中调用接口（如果接口返回标题）
```javascript
// 如果接口返回了全局默认标题
if (page_details.value.default_tab_title) {
tab_configs.value = tab_configs.value.map(config => ({
...config,
default_title: page_details.value.default_tab_title
}))
}
// 如果接口返回了具体标题
tab_configs.value = updateTabConfigsFromAPI(page_details.value)
```
**步骤 2**: 无需其他修改，工具函数会自动处理
---
## 📋 功能验证
### 功能未改变
重构只是代码组织方式的改变，**功能保持完全一致**：
- ✅ 标签页渲染逻辑不变
- ✅ 标题显示逻辑不变（仍使用接口返回值或默认值）
- ✅ 内容显示逻辑不变
- ✅ 所有事件处理不变
### 默认值变化
**唯一的变化**：默认标题从"敬老月优惠"改为通用值
| 标签页 | 重构前 | 重构后 |
|--------|--------|--------|
| introduction | 敬老月优惠 | 介绍 |
| story | 敬老月优惠 | 故事 |
| experience | 敬老月优惠 | 体验 |
**说明**：
- 如果接口返回了标题（`introduction_text`），仍使用接口返回的值
- 如果接口未返回标题，现在使用通用默认值（"介绍"、"故事"、"体验"）
- **可以在 `tab-config.js` 中轻松修改默认值**
---
## 🧪 测试建议
### 手动测试清单
- [ ] 打开打卡详情页，检查标签页是否正常显示
- [ ] 检查标签页标题是否正确显示
- [ ] 切换标签页，检查内容是否正确加载
- [ ] 检查图片预览功能是否正常
- [ ] 检查音频播放功能是否正常
- [ ] 检查打卡功能是否正常
### 测试命令
```bash
# 启动开发服务器
npm run dev
# 在浏览器中访问
http://localhost:8006/index.html#/checkin?id=xxx&marker_id=xxx
```
---
## 🎓 代码规范
重构后的代码遵循以下规范：
- ✅ **JSDoc 注释**：所有导出函数都有完整的 JSDoc 注释
- ✅ **单一职责**：每个函数只做一件事
- ✅ **DRY 原则**：消除代码重复
- ✅ **可测试性**：提供纯函数，易于单元测试
- ✅ **可维护性**：配置集中管理，易于修改
---
## 📚 相关文档
- [checkin-info 动态标签页分析与准备.md](checkin-info-动态标签页分析与准备.md) - 完整的分析和准备文档
- [多模块架构重构方案.md](多模块架构重构方案.md) - 项目整体重构方案
---
## ✅ 完成状态
- [x] 代码重构完成
- [x] 功能未改变（向后兼容）
- [x] 为接口接入做好准备
- [ ] 接口接入（等接口确定后）
**下一步行动**：等待接口数据确定后，进行接口接入调试。
---
**重构人员**: Claude Code
**完成时间**: 2026-02-09
**代码审查**: 待审查
# checkin/info 动态标签页分析与接口接入准备
> **日期**: 2026-02-09
> **目的**: 为动态标签页的 default_title 从接口获取数据做准备
---
## 📊 当前实现分析
### 1. 动态标签页配置（155-177 行）
```javascript
const tab_configs = ref([
{
key: 'introduction',
title_key: 'introduction_text', // 接口返回的标题字段
content_key: 'introduction', // 接口返回的内容字段
default_title: '敬老月优惠', // ❌ 当前写死
id: 'introduction'
},
{
key: 'story',
title_key: 'story_text',
content_key: 'story',
default_title: '敬老月优惠', // ❌ 当前写死
id: 'story'
},
{
key: 'experience',
title_key: 'experience_text',
content_key: 'experience',
default_title: '敬老月优惠', // ❌ 当前写死
id: 'experience'
}
]);
```
**结构说明**：
- `key`: 标签页的唯一标识符
- `title_key`: 从接口数据中读取标题的字段名（如 `introduction_text`）
- `content_key`: 从接口数据中读取内容的字段名（如 `introduction`）
- `default_title`: 当接口未返回标题时的后备值（**目前写死为"敬老月优惠"**）
- `id`: DOM 元素 ID，用于内容渲染和事件绑定
### 2. 标题设置逻辑（186-189 行，279-282 行）
**有两处相同的逻辑**：
```javascript
// 第 1 处：watch props.info 变化时（186-189 行）
tab_configs.value.forEach(config => {
page_details.value[config.title_key] = page_details.value[config.title_key] || config.default_title;
});
// 第 2 处：onMounted 时（279-282 行）
tab_configs.value.forEach(config => {
page_details.value[config.title_key] = page_details.value[config.title_key] || config.default_title;
});
```
**逻辑说明**：
- 如果 `page_details.value[config.title_key]` 有值（如 `page_details.value.introduction_text`），使用接口返回的值
- 否则使用 `config.default_title`（当前写死为"敬老月优惠"）
### 3. 数据来源（263-293 行）
**主要数据来源**：`mapAPI`
```javascript
const { data } = await mapAPI({ i: id });
const raw_list = data.list[0].list; // 标记点列表
const marker_id = $route.query.marker_id;
const current_marker = raw_list.filter(item => item.id == marker_id)[0];
page_details.value = {
...current_marker.details[0], // 标记点详情
position: current_marker.position,
path: current_marker.path,
// ...
};
```
**当前接口返回的数据结构**（推测）：
```javascript
{
code: 1,
data: {
list: [
{
id: 1,
list: [ // 标记点列表
{
id: 123, // marker_id
position: [lng, lat],
path: [],
details: [ // 标记点详情
{
id: 456,
name: "某某景点",
banner: [...],
note: "...",
// 三个标签页的内容
introduction: "<p>介绍内容...</p>",
story: "<p>故事内容...</p>",
experience: "<p>体验内容...</p>",
// ❌ 三个标签页的标题（可能不存在）
introduction_text: undefined, // 接口可能不返回
story_text: undefined,
experience_text: undefined,
// 其他字段
show_audio: true,
experience_audio: [...]
}
]
}
]
}
]
}
}
```
### 4. 标签页渲染（41-64 行）
```vue
<van-tabs>
<template v-for="config in tab_configs" :key="config.key">
<van-tab
:title="page_details[config.title_key]"
v-if="page_details[config.content_key]"
>
<!-- 内容 -->
<div :id="config.id" v-html="page_details[config.content_key]"></div>
</van-tab>
</template>
</van-tabs>
```
**渲染逻辑**：
- `v-if="page_details[config.content_key]"`：只有当内容存在时才显示该标签页
- `:title="page_details[config.title_key]"`：标题从 `page_details` 读取
---
## 🎯 问题总结
### 当前痛点
1. **default_title 写死**
- 所有标签页的 default_title 都是"敬老月优惠"
- 无法根据不同场景动态设置
2. **接口数据可能不完整**
- 接口可能不返回 `introduction_text`、`story_text`、`experience_text`
- 导致所有标签页都使用默认值
3. **逻辑重复**
- 标题设置逻辑在两处重复（watch 和 onMounted）
---
## 🔮 接口数据结构推测
### 方案 A: 接口直接返回标签页标题（推荐）✅
```javascript
{
code: 1,
data: {
list: [
{
id: 1,
list: [
{
id: 123,
details: [
{
id: 456,
name: "某某景点",
// ✅ 标签页内容
introduction: "<p>介绍内容...</p>",
story: "<p>故事内容...</p>",
experience: "<p>体验内容...</p>",
// ✅ 标签页标题（新增字段）
introduction_text: "景点介绍", // 从接口获取
story_text: "历史故事", // 从接口获取
experience_text: "游客体验", // 从接口获取
// ✅ 全局默认标题（可选）
default_tab_title: "默认标签" // 统一的后备标题
}
]
}
]
}
]
}
}
```
### 方案 B: 接口返回标签页配置对象
```javascript
{
code: 1,
data: {
list: [
{
id: 1,
list: [
{
id: 123,
details: [
{
id: 456,
name: "某某景点",
// ✅ 标签页配置对象
tabs_config: {
introduction: {
title: "景点介绍",
content: "<p>介绍内容...</p>"
},
story: {
title: "历史故事",
content: "<p>故事内容...</p>"
},
experience: {
title: "游客体验",
content: "<p>体验内容...</p>"
}
}
}
]
}
]
}
]
}
}
```
### 方案 C: 单独的标签页配置接口
```javascript
// 新增接口：/api/getTabConfig
const tabConfigAPI = (params) => fetch.get('/srv/?a=getTabConfig', params);
// 返回数据
{
code: 1,
data: {
tabs: [
{
key: 'introduction',
title: '景点介绍',
default_title: '介绍' // 后备值
},
{
key: 'story',
title: '历史故事',
default_title: '故事'
},
{
key: 'experience',
title: '游客体验',
default_title: '体验'
}
]
}
}
```
---
## 🛠️ 接入准备方案
### 阶段 1: 代码重构准备（不依赖接口）
#### 1.1 提取标签页配置到独立文件
**创建文件**：`src/views/checkin/tab-config.js`
```javascript
/**
* 打卡详情页标签页配置
*
* @description 定义标签页的结构和默认配置
* @module checkin/tab-config
*/
/**
* 标签页配置数组
* @type {Array<Object>}
*/
export const TAB_CONFIGS = [
{
key: 'introduction',
title_key: 'introduction_text',
content_key: 'introduction',
default_title: '介绍', // ✅ 修改为通用的默认值
id: 'introduction'
},
{
key: 'story',
title_key: 'story_text',
content_key: 'story',
default_title: '故事', // ✅ 修改为通用的默认值
id: 'story'
},
{
key: 'experience',
title_key: 'experience_text',
content_key: 'experience',
default_title: '体验', // ✅ 修改为通用的默认值
id: 'experience'
}
]
/**
* 设置标签页标题
*
* @description 将接口返回的标题设置到 page_details，如果没有则使用默认值
* @param {Object} page_details - 页面详情对象
* @param {Array<Object>} tab_configs - 标签页配置数组
* @returns {Object} 更新后的 page_details
*/
export function setTabTitles(page_details, tab_configs = TAB_CONFIGS) {
const updated = { ...page_details }
tab_configs.forEach(config => {
// 优先使用接口返回的标题，否则使用默认值
updated[config.title_key] = updated[config.title_key] || config.default_title
})
return updated
}
```
**优势**：
- ✅ 配置集中管理
- ✅ 便于修改和维护
- ✅ 可以动态加载配置
- ✅ 提供工具函数，减少重复代码
#### 1.2 修改 info.vue 使用新配置
**修改 1**：导入配置
```javascript
// 在 <script setup> 顶部添加
import { TAB_CONFIGS, setTabTitles } from './tab-config'
```
**修改 2**：替换 tab_configs 定义（155-177 行）
```javascript
// ❌ 删除旧代码
// const tab_configs = ref([...])
// ✅ 使用导入的配置
const tab_configs = ref(TAB_CONFIGS)
```
**修改 3**：简化标题设置逻辑
```javascript
// 第 1 处：watch props.info（186-189 行）
watch(
() => props.info,
async (newInfo) => {
if (newInfo && newInfo.details && newInfo.details.length) {
page_details.value = { ...newInfo.details[0], position: newInfo.position, path: newInfo.path, current_lng: newInfo.current_lng, current_lat: newInfo.current_lat, openid: newInfo.openid };
// ✅ 使用工具函数设置标题
page_details.value = setTabTitles(page_details.value, tab_configs.value)
// 获取浏览器可视范围的高度
$('.info-page').height(props.height + 'px');
// 检查打卡状态
await checkInitialCheckinStatus();
}
},
{ immediate: true }
)
// 第 2 处：onMounted（279-282 行）
onMounted(async () => {
// ...
// ✅ 使用工具函数设置标题
page_details.value = setTabTitles(page_details.value, tab_configs.value)
// ...
})
```
---
### 阶段 2: 接口数据接入（等接口确定后）
#### 2.1 方案 A: 接口直接返回标题字段
**修改 `tab-config.js`**：
```javascript
/**
* 从接口数据获取标签页配置
*
* @description 如果接口返回了标签页标题，则更新配置
* @param {Object} apiData - 接口返回的详情数据
* @param {Array<Object>} tab_configs - 标签页配置数组
* @returns {Array<Object>} 更新后的标签页配置
*/
export function updateTabConfigsFromAPI(apiData, tab_configs = TAB_CONFIGS) {
return tab_configs.map(config => {
const updated = { ...config }
// 如果接口返回了该标签页的标题
if (apiData[config.title_key]) {
updated.default_title = apiData[config.title_key]
}
return updated
})
}
```
**修改 `info.vue`**：
```javascript
// onMounted 中
onMounted(async () => {
if (!props.info) {
let id = $route.query.id;
const { data } = await mapAPI({ i: id });
const raw_list = data.list[0].list;
const marker_id = $route.query.marker_id;
const current_marker = raw_list.filter(item => item.id == marker_id)[0];
page_details.value = {
...current_marker.details[0],
position: current_marker.position,
path: current_marker.path,
current_lng: current_lng,
current_lat: current_lat,
openid: openid
};
// ✅ 如果接口返回了全局默认标题，使用它
const globalDefaultTitle = page_details.value.default_tab_title
if (globalDefaultTitle) {
tab_configs.value = tab_configs.value.map(config => ({
...config,
default_title: globalDefaultTitle
}))
}
// ✅ 从接口数据更新标签页配置（如果接口返回了具体标题）
tab_configs.value = updateTabConfigsFromAPI(page_details.value, tab_configs.value)
// 设置标题
page_details.value = setTabTitles(page_details.value, tab_configs.value)
// ...
}
})
```
#### 2.2 方案 B: 接口返回配置对象
**修改 `tab-config.js`**：
```javascript
/**
* 从接口配置对象生成标签页配置
*
* @description 如果接口返回了 tabs_config，则使用它
* @param {Object} tabsConfig - 接口返回的 tabs_config
* @returns {Array<Object>} 标签页配置数组
*/
export function generateTabConfigsFromAPI(tabsConfig) {
if (!tabsConfig || typeof tabsConfig !== 'object') {
return TAB_CONFIGS // 使用默认配置
}
return Object.entries(tabsConfig).map(([key, config]) => ({
key,
title_key: `${key}_text`,
content_key: key,
default_title: config.title || key,
id: key
}))
}
```
**修改 `info.vue`**：
```javascript
// onMounted 中
onMounted(async () => {
if (!props.info) {
// ...获取数据
// ✅ 如果接口返回了 tabs_config，使用它生成标签页配置
if (page_details.value.tabs_config) {
tab_configs.value = generateTabConfigsFromAPI(page_details.value.tabs_config)
}
// ...
}
})
```
#### 2.3 方案 C: 单独的标签页配置接口
**创建 API**：`src/api/checkin.js`
```javascript
/**
* 获取标签页配置
*
* @description 从接口获取标签页配置
* @param {Object} params - 请求参数
* @returns {Promise<Object>} 接口响应
*/
export const tabConfigAPI = (params) => fn(fetch.get('/srv/?a=getTabConfig', params))
```
**修改 `info.vue`**：
```javascript
import { tabConfigAPI } from '@/api/checkin.js'
// onMounted 中
onMounted(async () => {
// ...获取地图数据
try {
// ✅ 调用标签页配置接口
const { data: tabConfigData } = await tabConfigAPI({ id: page_details.value.id })
if (tabConfigData && tabConfigData.tabs) {
// 更新标签页配置
tab_configs.value = tabConfigData.tabs.map(tab => ({
key: tab.key,
title_key: `${tab.key}_text`,
content_key: tab.key,
default_title: tab.default_title || tab.title || tab.key,
id: tab.key
}))
}
} catch (error) {
console.error('获取标签页配置失败，使用默认配置:', error)
// 保持使用默认配置
}
// 设置标题
page_details.value = setTabTitles(page_details.value, tab_configs.value)
// ...
})
```
---
### 阶段 3: 测试方案
#### 3.1 单元测试（可选）
**创建文件**：`src/views/checkin/tab-config.test.js`
```javascript
import { describe, it, expect } from 'vitest'
import { setTabTitles, updateTabConfigsFromAPI, generateTabConfigsFromAPI } from './tab-config'
describe('tab-config', () => {
describe('setTabTitles', () => {
it('应该使用接口返回的标题', () => {
const page_details = {
introduction_text: '景点介绍',
story_text: '历史故事'
}
const result = setTabTitles(page_details)
expect(result.introduction_text).toBe('景点介绍')
expect(result.story_text).toBe('历史故事')
})
it('应该使用默认标题当接口未返回', () => {
const page_details = {}
const result = setTabTitles(page_details)
expect(result.introduction_text).toBe('介绍')
expect(result.story_text).toBe('故事')
})
})
describe('updateTabConfigsFromAPI', () => {
it('应该从接口数据更新默认标题', () => {
const apiData = {
introduction_text: '新介绍',
story_text: '新故事'
}
const result = updateTabConfigsFromAPI(apiData)
expect(result[0].default_title).toBe('新介绍')
expect(result[1].default_title).toBe('新故事')
})
})
})
```
#### 3.2 手动测试场景
**场景 1: 接口返回所有标题**
```javascript
// 模拟接口数据
const mockData = {
introduction_text: '景点介绍',
story_text: '历史故事',
experience_text: '游客体验'
}
// 预期结果
// ✅ 标签页标题：景点介绍、历史故事、游客体验
```
**场景 2: 接口只返回部分标题**
```javascript
// 模拟接口数据
const mockData = {
introduction_text: '景点介绍',
// story_text 未返回
// experience_text 未返回
}
// 预期结果
// ✅ 标签页标题：景点介绍、故事（默认）、体验（默认）
```
**场景 3: 接口未返回任何标题**
```javascript
// 模拟接口数据
const mockData = {}
// 预期结果
// ✅ 标签页标题：介绍（默认）、故事（默认）、体验（默认）
```
---
## 📋 实施清单
### ✅ 已完成（准备工作）
- [x] 分析当前实现
- [x] 识别问题点
- [x] 设计重构方案
- [x] 编写准备文档
### 🔄 待实施（等接口确定后）
**第 1 步**：代码重构（不依赖接口）
- [ ] 创建 `src/views/checkin/tab-config.js`
- [ ] 实现 `setTabTitles()` 工具函数
- [ ] 修改 `info.vue` 使用新配置
- [ ] 测试功能是否正常
**第 2 步**：接口接入（根据接口方案）
- [ ] 确认接口数据结构（方案 A/B/C）
- [ ] 实现 `updateTabConfigsFromAPI()` 或 `generateTabConfigsFromAPI()`
- [ ] 修改 `info.vue` 调用接口或处理数据
- [ ] 处理接口失败的情况
**第 3 步**：测试验证
- [ ] 单元测试（可选）
- [ ] 手动测试（3 个场景）
- [ ] 真机测试
- [ ] 边界情况测试
---
## 🎯 推荐方案
### 推荐采用：方案 A（接口直接返回标题字段）
**理由**：
1. ✅ **最简单**：只需在接口数据中添加 3 个字段
2. ✅ **向后兼容**：不影响现有接口结构
3. ✅ **灵活**：支持全局默认标题和单个标签页标题
4. ✅ **性能好**：无需额外请求
**接口需要添加的字段**：
```javascript
{
details: [
{
// 新增字段
introduction_text: "景点介绍", // 介绍标签页标题
story_text: "历史故事", // 故事标签页标题
experience_text: "游客体验", // 体验标签页标题
// 可选：全局默认标题
default_tab_title: "默认标签" // 当上面三个字段都不存在时使用
}
]
}
```
---
## 💡 使用指南
### 当接口确定后
**告诉我**：
1. 接口返回的数据结构（JSON 示例）
2. 使用哪个方案（A/B/C）
**我会**：
1. 根据接口结构调整代码
2. 实现接口接入逻辑
3. 添加错误处理
4. 编写测试用例
### 快速参考
**文件位置**：
- 配置文件：`src/views/checkin/tab-config.js`（待创建）
- 主要组件：`src/views/checkin/info.vue`
- API 文件：`src/api/checkin.js`
**关键函数**：
- `setTabTitles()`：设置标签页标题
- `updateTabConfigsFromAPI()`：从接口更新配置（方案 A）
- `generateTabConfigsFromAPI()`：从接口生成配置（方案 B）
**数据流程**：
```
接口返回数据
↓
提取标签页标题
↓
更新 tab_configs
↓
设置 page_details 标题
↓
渲染标签页
```
---
## 📞 后续行动
**当前状态**：准备完成，等待接口确定
**需要你提供**：
- 接口文档或数据结构示例
- 采用哪个方案（A/B/C）
**我会立即**：
1. 根据接口调整代码
2. 实现完整的接入逻辑
3. 测试验证功能
---
**文档保存位置**：[docs/checkin-info-动态标签页分析与准备.md](docs/checkin-info-动态标签页分析与准备.md)
# 多模块架构重构方案
> **日期**: 2026-02-09
> **目的**: 解决 `src/views/` 下 4 个重复模块（bieyuan、by、checkin、xys）的维护困难问题
---
## 📊 当前问题分析
### 问题概览
**文件结构**：
```
src/views/
├── bieyuan/
│ ├── index.vue # 首页入口
│ ├── map.vue # 地图页
│ ├── info.vue # 详情页
│ ├── scan.vue # 扫码页
│ └── info_w.vue # 详情页变体
├── by/
│ ├── index.vue # 与 bieyuan 完全相同
│ ├── map.vue # 与 bieyuan 有差异
│ ├── info.vue # 与 bieyuan 有差异
│ ├── scan.vue # 与 bieyuan 完全相同
│ └── info_w.vue # 与 bieyuan 有差异
├── checkin/
│ ├── index.vue # ...
│ ├── map.vue
│ ├── info.vue
│ └── scan.vue
└── xys/
├── index.vue
└── ...
```
**代码重复统计**：
- ✅ **完全相同**: `index.vue`、`scan.vue`（100% 重复）
- ⚠️ **高度相似**: `map.vue`、`info.vue`（约 80% 相似）
- 📝 **累计重复代码**: 约 **800+ 行**
**维护痛点**：
- ❌ 修改一个 bug 需要在 4 个地方修改
- ❌ 新增功能需要同步到 4 个模块
- ❌ 代码审查需要检查多个文件
- ❌ 容易出现不一致的问题
- ❌ 占用大量磁盘空间和构建时间
### 差异点分析
通过对比 `bieyuan` 和 `by` 的代码，发现主要差异：
1. **路由路径不同**
- bieyuan: `/bieyuan/*`
- by: `/by/*`
- checkin: `/checkin/*`
- xys: `/xys/*`
2. **功能开关**
- `by` 模块有音频列表功能（`show_audio`）
- `by` 模块有步行导航功能（`goToWalk`）
- `bieyuan` 模块的 Logo 显示，`by` 模块隐藏
3. **API 调用**
- `by` 额外调用 `mapAudioAPI` 获取音频列表
4. **UI 细节**
- 文案、图片、样式可能不同
---
## 🎯 重构方案设计
### 核心原则
1. **配置驱动**：通过配置文件管理模块差异
2. **组件复用**：抽取通用组件，通过 props 传递配置
3. **路由简化**：使用动态路由参数替代多个路由
4. **向后兼容**：保持旧路由可用，避免影响现有链接
---
## 📐 新架构设计
### 目录结构
```
src/
├── views/
│ ├── shared/ # 共享组件（新增）
│ │ ├── MapIndex.vue # 通用首页入口
│ │ ├── MapPage.vue # 通用地图页
│ │ ├── MapInfo.vue # 通用详情页
│ │ ├── MapScan.vue # 通用扫码页
│ │ └── composables/ # 共享业务逻辑
│ │ ├── useMapData.js # 地图数据管理
│ │ ├── useAudioList.js # 音频列表管理
│ │ └── useNavigation.js # 导航功能
│ ├── modules/ # 模块配置（新增）
│ │ ├── bieyuan.config.js # 别院配置
│ │ ├── by.config.js # BY 配置
│ │ ├── checkin.config.js # 打卡配置
│ │ └── xys.config.js # XYS 配置
│ ├── bieyuan/ # 保留（向后兼容）
│ ├── by/ # 保留（向后兼容）
│ ├── checkin/ # 保留（向后兼容）
│ └── xys/ # 保留（向后兼容）
└── utils/
└── module-config.js # 配置管理工具
```
### 配置文件结构
```javascript
// src/views/modules/bieyuan.config.js
export default {
// 模块标识
id: 'bieyuan',
name: '别院',
// 路由配置
routes: {
index: '/bieyuan',
map: '/bieyuan/map',
info: '/bieyuan/info',
scan: '/bieyuan/scan',
},
// UI 配置
ui: {
logo: {
show: true,
src: 'https://cdn.ipadbiz.cn/bieyuan/map/icon/index_logo@3x.png',
},
slogan: '山水逢甘露，静心遇桃源',
theme: {
primary: '#DD7850',
// ... 其他主题配置
},
},
// 功能开关
features: {
audioList: false, // 音频列表
walkRoute: false, // 步行导航
qrScan: true, // 二维码扫描
checkin: false, // 打卡功能
},
// API 配置
api: {
mapData: 'mapAPI',
audioList: null, // 不使用音频列表 API
},
// 业务逻辑配置
business: {
defaultMapView: 'default', // 默认地图视图
enableMarkers: true, // 是否启用标记点
// ... 其他业务配置
},
}
```
```javascript
// src/views/modules/by.config.js
export default {
id: 'by',
name: 'BY',
routes: {
index: '/by',
map: '/by',
info: '/by/info',
scan: '/by/scan',
},
ui: {
logo: {
show: false, // BY 模块不显示 Logo
src: '',
},
slogan: '山水逢甘露，静心遇桃源',
theme: {
primary: '#DD7850',
},
},
features: {
audioList: true, // ✅ BY 模块启用音频列表
walkRoute: true, // ✅ BY 模块启用步行导航
qrScan: true,
checkin: false,
},
api: {
mapData: 'mapAPI',
audioList: 'mapAudioAPI', // ✅ 使用音频列表 API
},
business: {
defaultMapView: 'default',
enableMarkers: true,
},
}
```
### 通用组件实现
#### 1. 通用首页入口（MapIndex.vue）
```vue
<!-- src/views/shared/MapIndex.vue -->
<template>
<div class="map-index-page">
<div class="index-header">
<van-image
v-if="config.ui.logo.show"
width="12rem"
height="12rem"
fit="contain"
:src="config.ui.logo.src"
/>
<div class="index-slogan">{{ config.ui.slogan }}</div>
</div>
<div
@click="goTo"
class="index-enter-btn"
:style="{
borderColor: config.ui.theme.primary,
color: config.ui.theme.primary,
}"
>
进&nbsp;入
</div>
</div>
</template>
<script setup>
import { computed } from 'vue'
import { useRouter, useRoute } from 'vue-router'
import { useModuleConfig } from '@/utils/module-config'
const $router = useRouter()
const $route = useRoute()
// 获取当前模块配置
const { config } = useModuleConfig()
const goTo = () => {
$router.push({
path: config.routes.map,
query: $route.query,
})
}
</script>
<style lang="less" scoped>
.map-index-page {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
min-height: 100vh;
.index-header {
display: flex;
flex-direction: column;
align-items: center;
}
.index-slogan {
margin-top: 2rem;
font-size: 0.95rem;
letter-spacing: 5px;
color: #47525F;
}
.index-enter-btn {
padding: 0.8rem 5.5rem;
border-radius: 5px;
font-size: 1.15rem;
background-color: white;
cursor: pointer;
}
}
</style>
```
#### 2. 通用详情页（MapInfo.vue）
```vue
<!-- src/views/shared/MapInfo.vue -->
<template>
<div class="map-info-page">
<!-- 条件渲染：音频按钮 -->
<div
v-if="config.features.audioList && page_details.show_audio"
@click="onClickAudioList"
class="audio-btn"
>
<!-- 音频按钮内容 -->
</div>
<!-- 条件渲染：步行导航按钮 -->
<div
v-if="config.features.walkRoute"
@click="goToWalk"
class="walk-btn"
>
步行导航
</div>
<!-- 条件渲染：Logo -->
<div
v-if="config.ui.logo.show"
class="info-logo"
:style="{
marginBottom: audio_list_height
? `${audio_list_height * 1.5}px`
: '3rem',
}"
>
<img :src="config.ui.logo.src" alt="Logo" />
</div>
<!-- 其他通用内容 -->
</div>
</template>
<script setup>
import { ref, computed, onMounted } from 'vue'
import { useRoute, useRouter } from 'vue-router'
import { useModuleConfig } from '@/utils/module-config'
import { useMapData } from './composables/useMapData'
import { useAudioList } from './composables/useAudioList'
import { useNavigation } from './composables/useNavigation'
const $route = useRoute()
const $router = useRouter()
const { config } = useModuleConfig()
// 通用业务逻辑
const { page_details, fetchMapData } = useMapData(config)
const { audio_list_height, onClickAudioList } = useAudioList(config)
const { goToWalk } = useNavigation(config)
// 页面初始化
onMounted(async () => {
await fetchMapData($route.query.id)
// 条件加载：音频列表
if (config.features.audioList) {
await loadAudioList()
}
})
</script>
```
#### 3. 模块配置管理工具
```javascript
// src/utils/module-config.js
import { reactive, computed } from 'vue'
import { useRoute } from 'vue-router'
// 模块配置导入
import bieyuanConfig from '@/views/modules/bieyuan.config.js'
import byConfig from '@/views/modules/by.config.js'
import checkinConfig from '@/views/modules/checkin.config.js'
import xysConfig from '@/views/modules/xys.config.js'
// 配置映射表
const MODULE_CONFIGS = {
bieyuan: bieyuanConfig,
by: byConfig,
checkin: checkinConfig,
xys: xysConfig,
}
// 全局当前模块状态
const currentModule = reactive({
id: null,
config: null,
})
/**
* 获取当前模块配置
* @returns {Object} { config, moduleId }
*/
export function useModuleConfig() {
const $route = useRoute()
// 根据路由路径识别模块
const moduleId = computed(() => {
const path = $route.path
if (path.startsWith('/bieyuan')) return 'bieyuan'
if (path.startsWith('/by')) return 'by'
if (path.startsWith('/checkin')) return 'checkin'
if (path.startsWith('/xys')) return 'xys'
// 默认模块
return 'bieyuan'
})
// 获取配置
const config = computed(() => {
const id = moduleId.value
return MODULE_CONFIGS[id] || MODULE_CONFIGS.bieyuan
})
// 更新全局状态
if (currentModule.id !== moduleId.value) {
currentModule.id = moduleId.value
currentModule.config = config.value
}
return {
config: config.value,
moduleId: moduleId.value,
}
}
/**
* 根据模块 ID 获取配置
* @param {string} moduleId 模块 ID
* @returns {Object} 模块配置
*/
export function getModuleConfig(moduleId) {
return MODULE_CONFIGS[moduleId] || MODULE_CONFIGS.bieyuan
}
/**
* 获取所有模块配置
* @returns {Object} 所有模块配置
*/
export function getAllModuleConfigs() {
return MODULE_CONFIGS
}
```
### Composables 实现
#### 1. 地图数据管理
```javascript
// src/views/shared/composables/useMapData.js
import { ref } from 'vue'
import { mapAPI, mapAudioAPI } from '@/api/map.js'
export function useMapData(config) {
const page_details = ref({})
const audio_list_height = ref(0)
/**
* 获取地图数据
*/
const fetchMapData = async (id) => {
try {
const { data } = await mapAPI({ id })
if (data) {
page_details.value = data
}
} catch (error) {
console.error('获取地图数据失败:', error)
}
}
/**
* 加载音频列表
*/
const loadAudioList = async (mid, markerId) => {
if (!config.features.audioList) return
try {
const apiName = config.api.audioList
const API = apiName === 'mapAudioAPI' ? mapAudioAPI : null
if (!API) return
const { data } = await API({ mid, bid: markerId })
if (data && data.length) {
page_details.value.show_audio = true
}
} catch (error) {
console.error('获取音频列表失败:', error)
}
}
return {
page_details,
audio_list_height,
fetchMapData,
loadAudioList,
}
}
```
#### 2. 导航功能
```javascript
// src/views/shared/composables/useNavigation.js
import { useRouter } from 'vue-router'
import { useModuleConfig } from '@/utils/module-config'
export function useNavigation(configOverride) {
const $router = useRouter()
const { config } = useModuleConfig()
/**
* 前往地图页
*/
const goToMap = () => {
$router.push({
path: config.routes.map,
query: { id: $router.currentRoute.value.query.id },
})
}
/**
* 打开步行导航
*/
const goToWalk = (point) => {
if (!config.features.walkRoute) {
console.warn('当前模块不支持步行导航')
return
}
// 触发步行导航事件
// ...
}
/**
* 返回首页
*/
const goBack = () => {
$router.push({
path: config.routes.index,
query: { id: $router.currentRoute.value.query.id },
})
}
return {
goToMap,
goToWalk,
goBack,
}
}
```
### 路由配置优化
#### 方案 1: 保持向后兼容（推荐）
```javascript
// src/route.js（重构后）
export default [
// ... 其他路由
// 通用路由（新增）
{
path: '/map/:module',
component: () => import('@/views/shared/MapPage.vue'),
meta: {
title: '地图',
},
},
{
path: '/map/:module/info',
component: () => import('@/views/shared/MapInfo.vue'),
meta: {
title: '详情页',
},
},
{
path: '/map/:module/scan',
component: () => import('@/views/shared/MapScan.vue'),
meta: {
title: '扫描',
},
},
// 旧路由保留（向后兼容）
{
path: '/bieyuan',
redirect: '/map/bieyuan', // 重定向到新路由
},
{
path: '/bieyuan/map',
redirect: '/map/bieyuan',
},
{
path: '/by',
redirect: '/map/by',
},
{
path: '/checkin',
redirect: '/map/checkin',
},
// ...
]
```
#### 方案 2: 完全重构（激进）
```javascript
// src/route.js
export default [
// 只保留通用路由
{
path: '/map/:module',
component: () => import('@/views/shared/MapPage.vue'),
},
{
path: '/map/:module/info',
component: () => import('@/views/shared/MapInfo.vue'),
},
{
path: '/map/:module/scan',
component: () => import('@/views/shared/MapScan.vue'),
},
]
```
---
## 🚀 实施计划
### 阶段 1: 基础设施搭建（1-2 天）
**任务**：
- [ ] 创建 `src/views/shared/` 目录
- [ ] 创建 `src/views/modules/` 目录
- [ ] 实现 `src/utils/module-config.js`
- [ ] 编写配置文件模板
- [ ] 编写 4 个模块的配置文件
**验收标准**：
- 配置文件结构清晰
- `useModuleConfig()` 可以正确返回配置
### 阶段 2: 组件抽取（2-3 天）
**任务**：
- [ ] 抽取 `MapIndex.vue`（通用首页）
- [ ] 抽取 `MapScan.vue`（通用扫码页）
- [ ] 抽取 `MapInfo.vue`（通用详情页）
- [ ] 抽取 `MapPage.vue`（通用地图页）
- [ ] 实现 Composables（useMapData、useAudioList、useNavigation）
**验收标准**：
- 4 个通用组件可以独立运行
- 通过配置可以控制功能显示/隐藏
- 代码覆盖 4 个模块的核心功能
### 阶段 3: 路由重构（1 天）
**任务**：
- [ ] 添加通用路由
- [ ] 配置旧路由重定向
- [ ] 更新导航链接
- [ ] 测试所有路由是否正常
**验收标准**：
- 新路由可以正常访问
- 旧路由自动重定向到新路由
- 现有链接不受影响
### 阶段 4: 测试与验证（1-2 天）
**任务**：
- [ ] 单元测试（Composables）
- [ ] 集成测试（组件功能）
- [ ] E2E 测试（关键流程）
- [ ] 性能测试（构建体积、加载时间）
**验收标准**：
- 所有测试通过
- 无功能回归
- 性能无明显下降
### 阶段 5: 清理与优化（1 天）
**任务**：
- [ ] 删除或标记 `src/views/bieyuan/` 等旧目录为废弃
- [ ] 更新文档
- [ ] 代码审查
- [ ] 性能优化
**验收标准**：
- 代码仓库干净整洁
- 文档完整
- 无遗留问题
---
## 📈 预期收益
### 代码质量
| 指标 | 重构前 | 重构后 | 改善 |
|------|--------|--------|------|
| **代码重复** | ~800 行 | ~0 行 | ✅ -100% |
| **组件数量** | 20 个 | 4 个 + 4 配置 | ✅ -60% |
| **维护成本** | 修改 4 处 | 修改 1 处 | ✅ -75% |
| **Bug 风险** | 高 | 低 | ✅ 显著降低 |
### 开发效率
**添加新模块**：
- 重构前：复制目录 + 修改文件（2-3 小时）
- 重构后：创建配置文件（15-30 分钟）
- **效率提升**: **80%+**
**修改功能**：
- 重构前：修改 4 个文件（1-2 小时）
- 重构后：修改 1 个组件（15-30 分钟）
- **效率提升**: **75%+**
### 可维护性
- ✅ 统一的代码风格
- ✅ 集中的配置管理
- ✅ 清晰的职责划分
- ✅ 易于代码审查
- ✅ 便于新人上手
---
## ⚠️ 风险与注意事项
### 风险
1. **回归风险**
- 重构过程中可能引入新 bug
- 缓解方案：完整的测试覆盖
2. **性能风险**
- 配置读取可能影响性能
- 缓解方案：使用 computed 缓存配置
3. **兼容性风险**
- 旧链接可能失效
- 缓解方案：保留旧路由重定向
### 注意事项
1. **向后兼容**
- 保留旧路由 6-12 个月
- 监控旧路由访问量
- 逐步废弃旧代码
2. **渐进式重构**
- 不要一次性重构所有模块
- 先重构 1-2 个模块验证方案
- 逐步推广到其他模块
3. **测试优先**
- 先编写测试用例
- 确保 100% 功能覆盖
- 测试通过后再部署
---
## 🎯 总结
### 核心思想
**从"复制粘贴"到"配置驱动"**
- 重构前：4 个独立目录，大量重复代码
- 重构后：1 套通用组件 + 4 个配置文件
### 关键技术
1. **配置驱动架构**：通过配置文件管理模块差异
2. **组件复用**：抽取通用组件，通过 props 传递配置
3. **Composables**：封装可复用的业务逻辑
4. **动态路由**：使用路由参数替代多个路由
### 未来扩展
添加新模块只需：
1. 创建配置文件（`src/views/modules/new-module.config.js`）
2. 配置路由（如果需要）
3. 完成！
**耗时**: 从 2-3 小时缩短到 **15-30 分钟**！
---
**下一步行动**：
1. 审阅本方案
2. 确认重构范围和优先级
3. 制定详细的时间表
4. 开始实施
**建议**: 先选择 1 个模块（如 `by`）进行试点重构，验证方案可行性后再推广到其他模块。