feat:架构代码优化

2025-12-11 13:02:44 +08:00
parent 2c32235568
commit 3c0e2af10d
89 changed files with 2774 additions and 2816 deletions
@@ -0,0 +1,201 @@
+# 页面 Mixin 重构说明
+
+## 重构目标
+
+将 `mathPageMixin.ts` 改造为通用的页面基类，支持数学学习、专注力等多个模块共用。
+
+## 改造内容
+
+### 1. 创建通用基类
+
+**文件：** `base/pageMixin.ts`
+
+- 提供了通用的页面公共方法
+- 抽象了 `initPageInfo` 方法，支持两种调用方式：
+    1. `initPageInfo(functionId, defaultTitle)` - 可以配合 `pageInfoLookup` 函数使用
+    2. `initPageInfo({ title, desc, functionId })` - 直接提供页面信息
+- 支持通过配置传入模块特定的信息查找函数和分享配置
+
+### 2. 重构数学模块 Mixin
+
+**文件：** `mathPages/common/mathPageMixin.ts`
+
+- 基于通用 `pageMixin` 创建数学模块的包装器
+- 自动配置 `MATH_FUNCTION_TYPES` 查找函数
+- 配置数学模块的分享信息
+- **保持完全向后兼容**，所有现有的数学页面无需修改
+
+### 3. 创建专注力模块示例
+
+**文件：** `focusPages/common/focusPageMixin.ts`
+
+- 展示如何为专注力模块创建专用的 mixin
+- 可以配置 `FOCUS_FUNCTION_TYPES` 查找函数
+- 配置专注力模块的分享信息
+
+## 关键改进
+
+### initPageInfo 方法优化
+
+**之前：**
+
+```typescript
+initPageInfo(functionId: string, defaultTitle?: string) {
+    const functionItem = MATH_FUNCTION_TYPES.find(...); // 硬编码
+    // ...
+}
+```
+
+**现在：**
+
+```typescript
+// 方式1：配合 pageInfoLookup 使用（数学模块自动配置）
+initPageInfo(functionId: string, defaultTitle?: string)
+
+// 方式2：直接提供信息（专注力等模块可以使用）
+initPageInfo({ title: string, desc?: string, functionId: string })
+```
+
+### 配置化的页面信息查找
+
+通过 `PageCommonMethodsConfig` 可以传入：
+
+- `shareConfig`: 模块特定的分享配置
+- `pageInfoLookup`: 页面信息查找函数（可选）
+
+这样不同模块可以使用不同的查找逻辑，而不需要硬编码。
+
+## 使用方式
+
+### 数学模块（无需修改）
+
+所有现有的数学页面继续使用原有方式：
+
+```typescript
+import { createMathPage, CanvasDataState } from '../common/mathPageMixin';
+
+createMathPage({
+    // ...
+    onLoad(options: { id?: string }) {
+        const functionId = options.id || 'addition-5';
+        // 自动从 MATH_FUNCTION_TYPES 中查找
+        this.initPageInfo(functionId, '默认标题');
+    },
+});
+```
+
+### 专注力模块（新）
+
+```typescript
+import { createFocusPage } from '../common/focusPageMixin';
+
+createFocusPage({
+    // ...
+    onLoad(options: { id?: string }) {
+        const functionId = options.id || 'grid-drawing';
+        // 自动从 FOCUS_FUNCTION_TYPES 中查找
+        this.initPageInfo(functionId, '格子仿画');
+    },
+});
+```
+
+### 其他模块（通用方式）
+
+```typescript
+import { createPage, PageCommonMethodsConfig } from '../../base/pageMixin';
+
+const myConfig: PageCommonMethodsConfig = {
+    shareConfig: {
+        title: '我的模块',
+        imageUrl: 'https://example.com/share.png',
+    },
+    pageInfoLookup: (functionId) => {
+        // 自定义查找逻辑
+        return { title: '...', desc: '...' };
+    },
+};
+
+createPage(
+    {
+        // ...
+        onLoad(options: { id?: string }) {
+            // 方式1：使用 lookup 函数
+            this.initPageInfo(options.id || 'default', '默认标题');
+
+            // 方式2：直接提供信息
+            this.initPageInfo({
+                functionId: options.id || 'default',
+                title: '页面标题',
+                desc: '页面描述',
+            });
+        },
+    },
+    myConfig,
+);
+```
+
+## 文件结构
+
+```
+miniprogram/
+├── base/
+│   ├── pageMixin.ts              # 通用页面基类（新增）
+│   └── pageMixin.README.md       # 使用文档（新增）
+│
+├── mathPages/
+│   └── common/
+│       └── mathPageMixin.ts      # 数学模块包装器（重构）
+│
+└── focusPages/
+    └── common/
+        └── focusPageMixin.ts     # 专注力模块示例（新增）
+```
+
+## 向后兼容性
+
+✅ **所有现有的数学页面无需修改**
+
+因为：
+
+- `mathPageMixin.ts` 保持了相同的导出接口
+- `createMathPage` 函数签名不变
+- `initPageInfo` 方法调用方式不变
+- 所有类型定义都重新导出
+
+## 受影响的文件
+
+### 无需修改的文件
+
+以下数学页面文件无需修改，因为它们使用相同的接口：
+
+- `mathPages/addition/addition.ts`
+- `mathPages/compare/compare.ts`
+- `mathPages/countMatch/countMatch.ts`
+- `mathPages/countingSelect/countingSelect.ts`
+- `mathPages/missingNumber/missingNumber.ts`
+- `mathPages/numberDecompose/numberDecompose.ts`
+- `mathPages/numberFind/numberFind.ts`
+
+### 修改的文件
+
+- ✅ `base/pageMixin.ts` - 新增
+- ✅ `mathPages/common/mathPageMixin.ts` - 重构（保持向后兼容）
+
+## 测试建议
+
+1. 验证所有数学页面功能正常
+2. 验证页面信息（title, desc）正确显示
+3. 验证分享功能正常
+4. 验证 Canvas 初始化正常
+5. 验证图片导出功能正常
+
+## 后续扩展
+
+其他模块（如专注力模块）可以：
+
+1. 创建自己的 `XXXPageMixin.ts` 文件
+2. 定义自己的函数类型和列表
+3. 配置自己的分享信息
+4. 使用 `createXXXPage` 创建页面
+
+这样可以保持代码的模块化和可维护性。