# 页面内容管理方案

> 版本：v1.0  |  最后更新：2026-04-29
> 配套文档：[Worksheet 发布方案](./Worksheet发布方案.md)  |  [小程序云开发方案](./小程序云开发方案.md)

---

## 一、背景与目标

worksheet 已可通过 Debug 发布进入云数据库，但三个展示页仍使用本地静态数据：


| 页面  | 当前数据来源                            | 问题                     |
| --- | --------------------------------- | ---------------------- |
| 首页  | `pages/home/home.data.ts`         | featured、hot、分区靠代码手动维护 |
| 分类页 | `pages/category/category.data.ts` | 新 worksheet 发布后不会自动出现  |
| 分龄页 | `pages/age/age.ts` 内 Mock         | 推荐内容和周路线无法运营配置         |


**目标：** 通过 Debug 管理页配置三个页面的内容，生成统一 JSON 上传云存储，小程序启动时通过**数据预拉取**获取并渲染。

---

## 二、整体架构

### 2.1 数据流

```
┌──────────────────────────────────────────────────────────────────┐
│  Debug 内容管理页（三个独立 tab）                                    │
│                                                                    │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐                         │
│  │ 首页管理  │   │ 分类页管理 │   │ 分龄页管理 │                      │
│  └────┬────┘   └────┬────┘   └────┬────┘                         │
│       │             │             │                                │
│       └──────┬──────┘──────┬──────┘                               │
│              ▼             ▼                                       │
│     点击「更新」按钮 → 调用云函数 pageContentUpdate                   │
│              │                                                     │
│              ▼                                                     │
│     更新云存储 content/page-config.json 中对应页面的配置              │
└──────────────────────────────────────────────────────────────────┘

                              ▼

┌──────────────────────────────────────────────────────────────────┐
│  小程序启动                                                        │
│                                                                    │
│  app.onLaunch                                                      │
│    └─ 数据预拉取 → 获取 content/page-config.json                    │
│                                                                    │
│  页面 onLoad                                                       │
│    ├─ 1. 使用本地 *.data.ts / age.config.ts 渲染兜底首屏             │
│    ├─ 2. 读取预拉取结果中对应页面的配置                                │
│    └─ 3. 成功则 setData 更新页面                                     │
└──────────────────────────────────────────────────────────────────┘
```

### 2.2 统一 JSON 格式

云存储路径：`content/page-config.json`

```ts
// content/page-config.json 结构
type PageConfig = {
    home: HomePageData;       // 首页配置
    category: CategoryPageData; // 分类页配置
    age: AgePageData;         // 分龄页配置
    version: number;          // 版本号，每次更新递增
    updatedAt: string;        // 最后更新时间
};
```

每个管理页更新时，只修改 JSON 中自己负责的字段，通过云函数读取当前 JSON → 合并更新 → 写回云存储。

### 2.3 页面加载策略

三个页面统一采用**数据预拉取 + 本地兜底**的加载策略：

```
页面 onLoad
  │
  ├─ Step 1: 使用本地静态数据渲染首屏（零延迟）
  │           首页 → home.data.ts
  │           分类页 → category.data.ts
  │           分龄页 → age.config.ts
  │
  ├─ Step 2: 读取数据预拉取结果
  │           wx.getBackgroundFetchData('pre') 获取 page-config.json
  │           取出当前页面对应的配置（home / category / age）
  │
  └─ Step 3: 成功 → setData 更新页面内容
             失败 → 保持本地兜底数据，用户无感知
```

> **数据预拉取**在 `app.json` 中配置 `fetchDataUrl`，小程序冷启动时由微信客户端自动发起，不占用页面加载时间。预拉取的数据指向云存储中的 `content/page-config.json`。

### 2.4 云函数设计

新增一个统一云函数 `pageContentUpdate`：

```ts
// cloudfunctions/pageContentUpdate/index.js
type PageContentUpdatePayload = {
    page: 'home' | 'category' | 'age';  // 要更新的页面
    data: HomePageData | CategoryPageData | AgePageData; // 该页面的完整配置
};
```

执行逻辑：

```
接收参数 { page, data }
  → 从云存储读取当前 content/page-config.json
  → 合并：config[page] = data
  → config.version++
  → config.updatedAt = new Date()
  → 写回云存储 content/page-config.json
  → 返回 { success, version }
```

---

## 三、首页内容管理

### 3.1 管理 UI

首页管理 tab 分为四个区块：


| 区块     | 对应字段           | 管理方式                                |
| ------ | -------------- | ----------------------------------- |
| 分类 tab | `categoryTabs` | 跟随 `CATEGORY_LIST_WITH_ALL`，一般不单独管理 |
| 年龄入口   | `ageBands`     | 跟随 `AGE_BANDS`，可管理描述文案              |
| 今日推荐   | `featured`     | 手动选择 3-5 个 active worksheet         |
| 热门推荐   | `hot`          | 手动选择或按 downloads 自动生成               |
| 分类分区   | `sections`     | 每个分类选择若干 active worksheet，支持排序      |


交互流程：

```
首页 tab 展示当前配置
  → 每个位置点击「选择内容」
  → 弹出 worksheet 选择器（筛选 active 内容）
  → 保存配置
  → 点击「更新首页数据」
  → 调用 pageContentUpdate({ page: 'home', data: ... })
```

### 3.2 数据结构

```ts
type HomePageData = {
    searchPlaceholder: string;
    categoryTabs: Array<{ id: string; name: string; path?: string }>;
    ageBands: Array<{ key: string; label: string; desc: string; path: string }>;
    featured: HomeDisplayItem[];
    hot: HomeDisplayItem[];
    sections: HomeDisplaySection[];
};
```

自动生成规则：


| 模块             | 默认规则                                           |
| -------------- | ---------------------------------------------- |
| `categoryTabs` | 由 `CATEGORY_LIST_WITH_ALL` 生成                  |
| `ageBands`     | 由 `AGE_BANDS` 生成                               |
| `featured`     | 优先使用手动选择，不足时补 `isNew == true`                  |
| `hot`          | 优先使用手动选择，不足时补 `isHot == true` 或 downloads 高的内容 |
| `sections`     | 使用配置中的 worksheetIds，不足时从该分类 active 内容补齐        |


---

## 四、分类页内容管理

### 4.1 管理 UI

分类页管理 tab 顶部展示分类选择器（来源 `CATEGORY_LIST`），默认选中 `math`。

分类头部统计：


| 指标  | 查询规则                          |
| --- | ----------------------------- |
| 总数  | `worksheets.category == 当前分类` |
| 草稿  | `status == draft`             |
| 线上  | `status == active`            |
| 已隐藏 | `status == hidden`            |


列表展示当前分类下所有 worksheet（按 `status` → `sortOrder` → `updatedAt` 排序），每项显示预览图、标题、ID、年龄/难度/标签、状态、排序权重。

操作按钮：


| 当前状态     | 可执行操作           |
| -------- | --------------- |
| `draft`  | 激活上线            |
| `active` | 下架为 hidden      |
| `hidden` | 恢复为 draft 或直接激活 |
| 任意       | 调整排序、预览跳转、刷新    |


### 4.2 数据结构

```ts
type CategoryPageData = {
    searchPlaceholder: string;
    categories: Array<{
        id: string;
        name: string;
        icon: string;
        items: CategoryItem[];
    }>;
};
```

生成时从 `worksheets` 集合查询 `status == active` 的内容，按分类分组、按 `sortOrder` 排序，转换为 `CategoryItem`。

### 4.3 更新流程

```
分类页管理 tab → 管理 worksheet 状态和排序
  → 点击「更新分类数据」
  → 查询所有 active worksheets，按 category 分组
  → 调用 pageContentUpdate({ page: 'category', data: ... })
  → 云函数更新 page-config.json 中的 category 字段
```

---

## 五、分龄页内容管理

### 5.1 新增 `age.config.ts`

在 `miniprogram/pages/age/` 下新增 `age.config.ts`，将年龄段划分、能力目标、默认 worksheet 写死在配置中，作为兜底数据和管理页的基础结构。

```ts
// miniprogram/pages/age/age.config.ts

import { AGE_BANDS, type AgeBandKey } from '../../core/data/difficulty';

export type AbilityItem = {
    icon: string;
    title: string;
    desc: string;
};

export type WeekPlan = {
    week: number;
    theme: string;
    worksheetIds: string[];   // worksheet 业务 ID
    worksheetTitles: string[]; // 兜底展示标题
};

export type AgeBandConfig = {
    key: AgeBandKey;
    label: string;
    subLabel: string;
    abilities: AbilityItem[];
    weeks: WeekPlan[];
};

export const AGE_CONFIG: AgeBandConfig[] = [
    {
        key: '3-4',
        label: '3-4 岁',
        subLabel: '启蒙认知',
        abilities: [
            { icon: '🔢', title: '数感', desc: '认读 1-5、点数对应' },
            { icon: '✏️', title: '书写', desc: '涂鸦线条、简单描红' },
            { icon: '🧩', title: '思维', desc: '找相同、简单配对' },
        ],
        weeks: [
            { week: 1, theme: '数感启蒙',
              worksheetIds: [], worksheetTitles: ['找数字涂一涂', '5以内加法', '数数连一连'] },
            { week: 2, theme: '形状与连线',
              worksheetIds: [], worksheetTitles: ['识别形状', '线条识别', '数字点连线'] },
            { week: 3, theme: '趣味专注',
              worksheetIds: [], worksheetTitles: ['颜色找规律', '方格推理', '格子仿画'] },
            { week: 4, theme: '综合练习',
              worksheetIds: [], worksheetTitles: ['10以内加减法', '识字卡', '连连看'] },
        ],
    },
    {
        key: '4-5',
        label: '4-5 岁',
        subLabel: '基础练习',
        abilities: [
            { icon: '🔢', title: '数感', desc: '10 以内数数、比大小' },
            { icon: '✏️', title: '书写', desc: '笔画模仿、图形描边' },
            { icon: '🧩', title: '思维', desc: '规律排序、图形分类' },
        ],
        weeks: [
            { week: 1, theme: '数感启蒙',
              worksheetIds: [], worksheetTitles: ['找数字涂一涂', '5以内加法', '数数连一连'] },
            { week: 2, theme: '形状与连线',
              worksheetIds: [], worksheetTitles: ['识别形状', '线条识别', '数字点连线'] },
            { week: 3, theme: '趣味专注',
              worksheetIds: [], worksheetTitles: ['颜色找规律', '方格推理', '格子仿画'] },
            { week: 4, theme: '综合练习',
              worksheetIds: [], worksheetTitles: ['10以内加减法', '识字卡', '连连看'] },
        ],
    },
    // 5-6、6-7、7-8 结构相同，abilities 和 weeks 内容不同
    // ... 完整配置见 age.config.ts 文件
];
```

> `worksheetIds` 初始为空数组，由分龄管理页选择后填入。`worksheetTitles` 作为兜底展示。

### 5.2 管理 UI

分龄管理 tab 按年龄段切换：`3-4 岁 | 4-5 岁 | 5-6 岁 | 6-7 岁 | 7-8 岁`

每个年龄段下的管理内容：


| 模块   | 操作           | 说明                               |
| ---- | ------------ | -------------------------------- |
| 能力目标 | 只读展示         | 来自 `age.config.ts`，不需要在管理页修改     |
| 四周路线 | 选择 worksheet | 每周选择 4 个 worksheet，主题来自 config   |
| 推荐内容 | 选择 worksheet | 动态数据，展示 likes 数量最高的 6 个worksheet |


worksheet 选择器默认筛选条件：

```
status == active
ageMin <= 当前年龄段 maxAge
ageMax >= 当前年龄段 minAge
```

**核心简化：** 分龄管理页不需要配置能力目标和周主题（这些写死在 `age.config.ts` 中），只需要为不同年龄段、不同周选择对应的 worksheet。

### 5.3 数据结构

```ts
type AgePageData = {
    ageTabs: Array<{
        key: AgeBandKey;
        rangeText: string;
        subLabel: string;
    }>;
    bands: Record<AgeBandKey, {
        goalTitle: string;
        abilityItems: AbilityItem[];
        weekPlans: Array<{
            week: number;
            theme: string;
            exercises: Array<{
                id: string;
                title: string;
                path: string;
                previewImg?: string;
            }>;
        }>;
        recommendedItems: Array<{
            id: string;
            title: string;
            image?: string;
            path: string;
        }>;
    }>;
};
```

### 5.4 更新流程

```
分龄管理 tab → 选择年龄段
  → 为每周选择 worksheet
  → 选择推荐内容
  → 点击「更新分龄数据」
  → 合并 age.config.ts 的能力目标 + 管理页选择的 worksheet 详情
  → 调用 pageContentUpdate({ page: 'age', data: ... })
  → 云函数更新 page-config.json 中的 age 字段
```

---

## 六、Debug 页入口结构

```
supportPages/debug/debug
  ├─ 分类基础数据管理      （已有：同步 CATEGORY_LIST → categories）
  ├─ Worksheet 内容池      （已有：状态、分类、上下架、预览）
  └─ 页面内容管理           （新增）
       ├─ Tab: 首页管理     → 编排 featured / hot / sections
       ├─ Tab: 分类页管理   → 管理 worksheet 状态和排序
       └─ Tab: 分龄页管理   → 按年龄段选择周 worksheet
```

---

## 七、实施计划

### Phase 1：基础设施

1. 配置 `app.json` 数据预拉取，指向 `content/page-config.json`
2. 实现 `pageContentUpdate` 云函数
3. 上传初始 `page-config.json`（从现有 `*.data.ts` 转换）
4. 三个页面统一接入预拉取加载逻辑

### Phase 2：分类页管理

1. 实现分类页管理 tab（worksheet 列表、状态管理、排序）
2. 实现「更新分类数据」→ 生成 category 配置 → 调用云函数更新

### Phase 3：首页管理

1. 实现首页管理 tab（featured / hot / sections 编排）
2. 实现 worksheet 选择器弹窗
3. 实现「更新首页数据」→ 生成 home 配置 → 调用云函数更新

### Phase 4：分龄页管理

1. 新增 `age.config.ts` 配置文件
2. 实现分龄管理 tab（年龄段切换、周 worksheet 选择）
3. 实现「更新分龄数据」→ 合并 config + worksheet 详情 → 调用云函数更新

---

## 八、风险与约束


| 风险                | 处理方式                                      |
| ----------------- | ----------------------------------------- |
| 预拉取失败             | 本地 `*.data.ts` / `age.config.ts` 兜底，用户无感知 |
| JSON 生成失败         | 云函数返回错误，管理页提示重试，线上数据不受影响                  |
| 首页配置引用了 hidden 内容 | 生成时只允许 active 内容，不足时返回警告                  |
| 分龄内容不适龄           | 选择器按年龄段默认过滤                               |
| 并发更新冲突            | 云函数使用 version 乐观锁，冲突时提示重新加载后重试            |


---

## 九、关键文件索引


| 文件 / 模块                             | 职责                             |
| ----------------------------------- | ------------------------------ |
| `supportPages/contentManage/`       | 三 tab 内容管理页                    |
| `cloudfunctions/pageContentUpdate/` | 更新 `page-config.json` 中指定页面的配置 |
| `pages/age/age.config.ts`           | 分龄页兜底配置（年龄段、能力目标、默认 worksheet） |
| `pages/home/home.data.ts`           | 首页兜底数据                         |
| `pages/category/category.data.ts`   | 分类页兜底数据                        |
| `content/page-config.json`（云存储）     | 三个页面的统一配置 JSON                 |