flux-web/src/js/README.md

薇钱包 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"> 引入主入口文件：

<!-- 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：

npm install -D vite

2. 创建 vite.config.js：

import { defineConfig } from 'vite';

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

3. 在 package.json 中添加脚本：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

4. 启动开发服务器：

npm run dev

📦 模块说明

配置模块 (config/)

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

使用示例：

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 请求、缓存管理等。

使用示例：

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/)

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

使用示例：

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/)

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

使用示例：

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 组件类。

使用示例：

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/)

页面级别的逻辑封装。

使用示例：

import { IndexPage, BasicInfoPage } from './pages/index.js';

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

🔄 从旧代码迁移

步骤 1: 备份旧文件

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

步骤 2: 修改 HTML 文件

index.html 和 basic-info.html：

删除旧的 script 标签：

<!-- 删除这些行 -->
<script src="config.js"></script>
<script src="script.js"></script>
<script src="basic-info.js"></script>

添加新的 module script：

<!-- 添加这一行 -->
<script type="module" src="./src/js/main.js"></script>

步骤 3: 测试功能

1. 启动开发服务器：

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"：

<script type="module" src="./src/js/main.js"></script>

Q2: CORS 错误

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

解决： 使用 HTTP 服务器：

# 使用 Node.js
npx serve .

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

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

Q3: 找不到模块

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

解决：

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

📚 进一步阅读

• ES6 模块入门
• Vite 官方文档
• JavaScript 模块化最佳实践

🤝 贡献

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

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

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

---

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