# 薇钱包 H5 项目 - 模块化重构说明

## 📁 新的目录结构

```
web/
├── src/js/
│   ├── config/              # 配置模块
│   │   ├── index.js        # 配置统一导出
│   │   ├── api.config.js   # API 配置
│   │   └── app.config.js   # 应用配置
│   │
│   ├── core/               # 核心模块
│   │   ├── index.js        # 核心模块统一导出
│   │   ├── api.js          # API 请求封装
│   │   ├── user-cache.js   # 用户缓存管理
│   │   ├── form-id.js      # 表单 ID 生成器
│   │   └── draft-manager.js # 草稿管理器
│   │
│   ├── utils/              # 工具函数库
│   │   ├── index.js        # 工具函数统一导出
│   │   ├── validator.js    # 表单验证器
│   │   ├── formatter.js    # 格式化工具
│   │   └── helper.js       # 通用辅助函数
│   │
│   ├── services/           # 业务服务层
│   │   ├── index.js        # 服务层统一导出
│   │   ├── sms.service.js  # 短信服务
│   │   ├── auth.service.js # 认证服务
│   │   ├── loan.service.js # 借款服务
│   │   └── form.service.js # 表单服务
│   │
│   ├── ui/                 # UI 组件
│   │   ├── index.js        # UI 组件统一导出
│   │   ├── modal.js        # 模态框基类
│   │   ├── picker.js       # 选择器组件
│   │   ├── toast.js        # Toast 提示
│   │   └── city-picker.js  # 城市选择器
│   │
│   ├── pages/              # 页面逻辑
│   │   ├── index.js        # 页面逻辑统一导出
│   │   ├── index.page.js   # 主页面逻辑
│   │   └── basic-info.page.js # 基本信息页面逻辑
│   │
│   └── main.js             # 应用主入口
│
├── index.html              # 主借款申请页面
├── basic-info.html         # 基本信息填写页面
├── config.js               # 旧配置文件（已废弃）
├── script.js               # 旧主页面逻辑（已废弃）
└── basic-info.js           # 旧基本信息页面逻辑（已废弃）
```

## 🚀 使用新模块化结构

### 方法 1: 使用 ES6 模块（推荐）

在 HTML 文件中使用 `<script type="module">` 引入主入口文件：

```html
<!-- index.html 和 basic-info.html -->
<script type="module" src="./src/js/main.js"></script>
```

**注意：**
- 需要删除旧的 `<script>` 标签（如 `config.js`、`script.js`、`basic-info.js`）
- 确保所有模块文件都使用 `.js` 扩展名
- 现代浏览器都支持 ES6 模块

### 方法 2: 使用构建工具（可选）

如果需要更好的兼容性和性能优化，可以使用 Vite 或 Webpack：

#### 使用 Vite

1. 安装 Vite：
```bash
npm install -D vite
```

2. 创建 `vite.config.js`：
```javascript
import { defineConfig } from 'vite';

export default defineConfig({
  root: './',
  build: {
    outDir: 'dist',
    rollupOptions: {
      input: {
        main: './index.html',
        basicInfo: './basic-info.html'
      }
    }
  }
});
```

3. 在 `package.json` 中添加脚本：
```json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}
```

4. 启动开发服务器：
```bash
npm run dev
```

## 📦 模块说明

### 配置模块 (config/)

所有应用配置的集中管理位置。

**使用示例：**
```javascript
import { API_CONFIG, LOAN_CONFIG, DEBUG_CONFIG } from './config/index.js';

// 使用 API 配置
const url = API_CONFIG.BASE_URL + API_CONFIG.ENDPOINTS.SEND_SMS;

// 使用借款配置
const maxAmount = LOAN_CONFIG.AMOUNT.MAX;

// 使用调试配置
if (DEBUG_CONFIG.ENABLED) {
    console.log('Debug mode is on');
}
```

### 核心模块 (core/)

提供核心功能，如 API 请求、缓存管理等。

**使用示例：**
```javascript
import { ApiClient, UserCache, FormIdGenerator } from './core/index.js';

// API 请求
const response = await ApiClient.post('/api/endpoint', { data: 'value' });

// 用户缓存
UserCache.saveUserSession({ customerid: '123', mobile: '13800138000' });
const session = UserCache.getUserSession();

// 表单 ID
const formId = FormIdGenerator.getOrCreate();
```

### 工具函数模块 (utils/)

提供纯函数工具，无副作用。

**使用示例：**
```javascript
import { Validator, Formatter, debounce } from './utils/index.js';

// 验证
const phoneValidation = Validator.validatePhone('13800138000');

// 格式化
const maskedPhone = Formatter.maskPhone('13800138000'); // "138****8000"

// 防抖
const debouncedFn = debounce(() => console.log('Called'), 300);
```

### 业务服务层 (services/)

封装业务逻辑，与核心模块和工具函数协作。

**使用示例：**
```javascript
import { SMSService, AuthService, LoanService } from './services/index.js';

// 发送短信
const result = await SMSService.send('13800138000');

// 用户登录
const loginResult = await AuthService.registerOrLogin('13800138000', loanData);

// 计算还款计划
const plan = LoanService.calculateRepaymentPlan(50000, 12);
```

### UI 组件 (ui/)

可复用的 UI 组件类。

**使用示例：**
```javascript
import { Picker, Modal, CityPicker, showToast } from './ui/index.js';

// 选择器
const picker = new Picker({
    triggerId: 'trigger',
    modalId: 'modal',
    // ... 其他配置
});

// 模态框
const modal = new Modal({
    modalId: 'modal',
    onConfirm: () => console.log('Confirmed')
});

// Toast 提示
showToast('操作成功', 2000);
```

### 页面逻辑 (pages/)

页面级别的逻辑封装。

**使用示例：**
```javascript
import { IndexPage, BasicInfoPage } from './pages/index.js';

// 主页面会自动初始化，无需手动调用
```

## 🔄 从旧代码迁移

### 步骤 1: 备份旧文件

```bash
mkdir old
mv config.js script.js basic-info.js old/
```

### 步骤 2: 修改 HTML 文件

**index.html 和 basic-info.html：**

删除旧的 script 标签：
```html
<!-- 删除这些行 -->
<script src="config.js"></script>
<script src="script.js"></script>
<script src="basic-info.js"></script>
```

添加新的 module script：
```html
<!-- 添加这一行 -->
<script type="module" src="./src/js/main.js"></script>
```

### 步骤 3: 测试功能

1. 启动开发服务器：
```bash
node server.js
```

2. 在浏览器中访问 `http://localhost:3000`

3. 测试所有功能：
   - 借款申请流程
   - 短信验证
   - 资产信息填写
   - 基本信息填写
   - 表单提交

## ✨ 新架构的优势

### 1. 更好的代码组织
- **职责分离**：每个模块只负责一个功能
- **易于定位**：问题查找更快
- **代码复用**：组件和服务可在多个页面使用

### 2. 更强的可维护性
- **单一职责**：文件小，易于理解
- **依赖清晰**：通过 import 明确依赖关系
- **易于扩展**：新增功能只需添加新模块

### 3. 更好的开发体验
- **IDE 支持**：完整的代码提示和跳转
- **调试友好**：源码映射支持
- **版本控制**：小的改动更清晰

### 4. 性能优化潜力
- **按需加载**：ES6 模块支持按需加载
- **Tree Shaking**：未使用的代码可被删除
- **缓存优化**：模块级别的缓存

## 🐛 常见问题

### Q1: 浏览器报错 "Cannot use import statement outside a module"

**原因：** 浏览器不支持 ES6 模块或 script 标签没有 `type="module"`。

**解决：** 确保 script 标签包含 `type="module"`：
```html
<script type="module" src="./src/js/main.js"></script>
```

### Q2: CORS 错误

**原因：** 直接使用 file:// 协议打开 HTML 文件。

**解决：** 使用 HTTP 服务器：
```bash
# 使用 Node.js
npx serve .

# 或使用 Python
python -m http.server 8000

# 或使用项目中的 server.js
node server.js
```

### Q3: 找不到模块

**原因：** 路径错误或文件名错误。

**解决：**
- 确保所有 import 路径以 `./` 或 `../` 开头
- 检查文件名和扩展名是否正确
- 确保导出语句（export）正确

## 📚 进一步阅读

- [ES6 模块入门](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Modules)
- [Vite 官方文档](https://cn.vitejs.dev/)
- [JavaScript 模块化最佳实践](https://www.patterns.dev/posts/modules/)

## 🤝 贡献

在添加新功能时，请遵循现有的模块化结构：

1. **配置** → 添加到 `config/` 目录
2. **工具函数** → 添加到 `utils/` 目录
3. **业务逻辑** → 添加到 `services/` 目录
4. **UI 组件** → 添加到 `ui/` 目录
5. **页面逻辑** → 添加到 `pages/` 目录

记得在相应的 `index.js` 文件中导出新模块！

---

**重构完成日期：** 2025-01-21
**重构人员：** Claude Code
**版本：** 2.0.0