urbanLifeline/urbanLifelineWeb/packages/shared/EXPOSES.md

# Shared 模块导出规范

## 导出路径组织

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

### 组件模块 (Components)

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

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

**可用组件：**
- `shared/components/file/FileUpload` - 文件上传组件（支持 cover/dialog/content 三种模式）
- `shared/components/DynamicFormItem` - 动态表单项组件

---

### API 模块

```typescript
// 整体导出
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 工具模块

```typescript
// 整体导出
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 类型模块

```typescript
// 整体导出
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` - 系统相关类型

---

## 向后兼容性

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

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

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

---

## 最佳实践

### 1. 使用明确的路径

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

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

### 2. 按需导入

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

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

### 3. 使用类型导入

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

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

---

## 添加新模块

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

1. **在 vite.config.ts 中添加导出**
   ```typescript
   exposes: {
       './components/YourComponent': './src/components/yourcomponent/YourComponent.vue'
   }
   ```

2. **在 shared.d.ts 中添加类型声明**
   ```typescript
   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
- ✅ 重新组织导出路径，使用清晰的分类前缀
- ✅ 添加向后兼容性支持
- ✅ 更新类型声明文件
- ✅ 添加更多常用模块导出