urbanLifeline/urbanLifelineWeb/packages/shared/EXPOSES.md

Shared 模块导出规范

导出路径组织

为了保持代码的清晰性和可维护性，shared 包的模块导出已按照功能分类组织。

组件模块 (Components)

// 整体导出
import { FileUpload, DynamicFormItem } from 'shared/components'

// 单独导入（推荐）
import FileUpload from 'shared/components/FileUpload'
import DynamicFormItem from 'shared/components/DynamicFormItem'

可用组件：

• shared/components/FileUpload - 文件上传组件（支持 cover/dialog/content 三种模式）
• shared/components/DynamicFormItem - 动态表单项组件

---

API 模块

// 整体导出
import { api, TokenManager } from 'shared/api'

// 单独导入（推荐）
import { authAPI } from 'shared/api/auth'
import { fileAPI } from 'shared/api/file'

可用 API：

• shared/api - API 基础模块和 TokenManager
• shared/api/auth - 认证相关 API
• shared/api/file - 文件管理 API

---

Utils 工具模块

// 整体导出
import { formatFileSize, isImageFile } from 'shared/utils'

// 单独导入
import { getDeviceType, isMobile } from 'shared/utils/device'
import { 
    generateSimpleRoutes, 
    loadViewsFromStorage,
    buildMenuTree 
} from 'shared/utils/route'
import { formatFileSize, isImageFile } from 'shared/utils/file'

可用工具：

• shared/utils - 通用工具函数集合
• shared/utils/device - 设备检测工具
• shared/utils/route - 路由生成和菜单构建工具
  • generateSimpleRoutes() - 生成简化路由（适合直接添加到 router）
  • loadViewsFromStorage() - 从 localStorage 加载视图数据
  • buildMenuTree() - 构建菜单树结构
  • generateRoutes() - 生成完整路由配置
  • 更多工具函数...
• shared/utils/file - 文件处理工具

---

Types 类型模块

// 整体导出
import type { LoginParam, TbSysViewDTO } from 'shared/types'

// 单独导入
import type { LoginParam, LoginDomain } from 'shared/types/auth'
import type { TbSysFileDTO } from 'shared/types/file'
import type { SysUserVO, SysConfigVO } from 'shared/types/sys'

可用类型：

• shared/types - 所有类型的统一导出
• shared/types/base - 基础类型（BaseVO, BaseDTO 等）
• shared/types/auth - 认证相关类型
• shared/types/file - 文件相关类型
• shared/types/sys - 系统相关类型

---

向后兼容性

为了保持向后兼容，旧的导入路径仍然可用（但不推荐）：

// ❌ 旧路径（不推荐，但仍可用）
import FileUpload from 'shared/FileUpload'
import { authAPI } from 'shared/authAPI'
import { fileAPI } from 'shared/fileAPI'

// ✅ 新路径（推荐）
import FileUpload from 'shared/components/FileUpload'
import { authAPI } from 'shared/api/auth'
import { fileAPI } from 'shared/api/file'

---

最佳实践

1. 使用明确的路径

// ✅ 推荐：路径清晰，便于理解
import FileUpload from 'shared/components/FileUpload'
import { authAPI } from 'shared/api/auth'

// ❌ 不推荐：路径模糊
import FileUpload from 'shared/FileUpload'

2. 按需导入

// ✅ 推荐：只导入需要的模块
import { formatFileSize } from 'shared/utils/file'

// ❌ 不推荐：导入整个模块
import * as utils from 'shared/utils'

3. 使用类型导入

// ✅ 推荐：明确标识类型导入
import type { LoginParam } from 'shared/types/auth'
import { authAPI } from 'shared/api/auth'

// ❌ 不推荐：混合导入
import { LoginParam, authAPI } from 'shared/types'

---

添加新模块

如果需要添加新的导出模块，请按照以下步骤：

1. 在 vite.config.ts 中添加导出

   exposes: {
       './components/YourComponent': './src/components/yourcomponent/YourComponent.vue'
   }
   

2. 在 shared.d.ts 中添加类型声明

   declare module 'shared/components/YourComponent' {
       import { DefineComponent } from 'vue'
       const YourComponent: DefineComponent<{}, {}, any>
       export default YourComponent
   }
   

3. 更新此文档

---

常见问题

Q: TypeScript 报错找不到模块？

A: 尝试以下方法：

1. 重启 TypeScript 语言服务器（VS Code: Ctrl+Shift+P → Restart TS Server）
2. 确认 shared.d.ts 文件已正确更新
3. 检查 shared 包是否已正确构建

Q: 运行时找不到模块？

A: 确保：

1. shared 包已启动（npm run dev 在 shared 目录）
2. vite.config.ts 中的 exposes 配置正确
3. Module Federation 配置正确加载

Q: 如何查看所有可用模块？

A: 查看 packages/shared/vite.config.ts 的 exposes 配置

---

更新日志

2025-12-12

• ✅ 重新组织导出路径，使用清晰的分类前缀
• ✅ 添加向后兼容性支持
• ✅ 更新类型声明文件
• ✅ 添加更多常用模块导出