lxy/flux-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

.

Browse Source
This commit is contained in:
绝尘
2026-01-22 18:31:30 +08:00
commit d703ac3574
46 changed files with 7751 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

351
src/js/README.md Normal file
View File

@@ -0,0 +1,351 @@
# 薇钱包 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