# 分龄页内容管理方案

> 版本：v1.0 | 最后更新：2026-05-06
> 配套文档：[页面内容管理方案](./页面内容管理方案.md) | [小程序云开发方案](./小程序云开发方案.md)

---

## 一、背景与目标

分龄页（`pages/age/age`）按年龄段展示学习内容，目前数据写死在 `age.ts` 内部 Mock。页面内容可拆分为**四个部分**，变更频率各不相同：

| 部分     | 名称             | 变更频率                | 数据来源                                                   |
| -------- | ---------------- | ----------------------- | ---------------------------------------------------------- |
| 第一部分 | 年龄段设置       | 几乎不变                | 写死在 `age.config.ts`                                     |
| 第二部分 | 能力目标         | 低频变更                | AI Skill 生成 → 写入 `age.config.ts`                       |
| 第三部分 | 4 周推荐学习路线 | 随 worksheet 增加而更新 | AI Skill 生成 → 写入 `age.config.ts`                       |
| 第四部分 | 为你推荐         | 动态                    | 运行时调用云函数生成：同年龄段 downloads Top3 + likes Top3 |

**目标：**

1. 将分龄页配置抽取到独立的 `age.config.ts` 中，分离静态配置与动态数据
2. 通过 AI Skill（Cursor 本地技能），结合最新 worksheet 数据，以早教专家视角自动生成第二部分（能力目标）和第三部分（学习路线）
3. 第四部分「为你推荐」在运行时通过云函数生成：同年龄段 **downloads Top3 + likes Top3**

---

## 二、页面四部分详解

### 2.1 第一部分：年龄段设置（静态）

年龄段划分几乎不变，直接写死在配置中。

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

export const AGE_TAB_SUB: Record<AgeBandKey, string> = {
    '3-4': '启蒙认知',
    '4-5': '基础练习',
    '5-6': '能力提升',
    '6-7': '幼小衔接',
    '7-8': '知识拓展',
};
```

数据来源：`core/data/difficulty.ts` 中的 `AGE_BANDS` 定义了 5 个年龄段 `3-4 | 4-5 | 5-6 | 6-7 | 7-8`。

### 2.2 第二部分：能力目标（AI 生成，低频更新）

每个年龄段 3 个能力维度（数感、书写、思维），描述该年龄段应达到的核心能力。

```ts
type AbilityItem = {
    icon: string; // emoji 图标
    title: string; // 能力维度名称
    desc: string; // 能力描述
};

// age.config.ts 中的结构
export const AGE_ABILITIES: Record<AgeBandKey, AbilityItem[]> = {
    '3-4': [
        { icon: '🔢', title: '数感', desc: '认读 1-5、点数对应' },
        { icon: '✏️', title: '书写', desc: '涂鸦线条、简单描红' },
        { icon: '🧩', title: '思维', desc: '找相同、简单配对' },
    ],
    // ... 其他年龄段
};
```

**更新方式：** 运行 AI Skill `generate-age-abilities`，基于当前所有 worksheet 内容，以早教专家视角重新生成各年龄段的能力目标，并更新 `age.config.ts`。

### 2.3 第三部分：4 周推荐学习路线（AI 生成，中频更新）

每个年龄段 4 周学习计划，每周一个主题，包含 3 个推荐练习。练习需关联到实际存在的 worksheet。

```ts
type WeekExercise = {
    _id: string; // 云 worksheets._id，与 page-config category.items[].id 一致
    title: string; // worksheet 标题
    subtitle: string; // 副标题（列表展示）
    path: string; // 小程序跳转路径，可含 query；点击后 navigateTo / switchTab
};

type WeekPlan = {
    week: number; // 第几周 1-4
    theme: string; // 周主题
    exercises: WeekExercise[]; // 3 个练习
};

// age.config.ts 中的结构
export const AGE_WEEK_PLANS: Record<AgeBandKey, WeekPlan[]> = {
    '3-4': [
        {
            week: 1,
            theme: '数感启蒙',
            exercises: [
                {
                    _id: 'ws_001',
                    title: '找数字，涂一涂',
                    subtitle: '在数字方阵中找出目标数字并涂色',
                    path: '/mathPages/mathDraw/mathDraw?id=number-find',
                },
                // ...
            ],
        },
        // ... week 2-4
    ],
    // ... 其他年龄段
};
```

**更新方式：** 运行 AI Skill `generate-age-weekly-plans`，基于当前所有 worksheet 内容，以早教专家视角为每个年龄段编排 4 周学习路线，并更新 `age.config.ts`。

**交互：** 列表展示 `title` + `subtitle`；用户点击「去练习」时，使用 `path` 调用 `wx.navigateTo`（TabBar 页面则 `wx.switchTab` 并不带 query）。

### 2.4 第四部分：为你推荐（动态，云函数）

展示当前年龄段的 6 个推荐 worksheet，规则固定为：

- **前 3 个**：同年龄段 `downloads` 最高的 3 个（downloads Top3）
- **后 3 个**：同年龄段 `likes` 最高的 3 个（likes Top3）

> 若两者出现重复，likes Top3 会自动向后补齐，确保总数为 6（在 worksheet 数量充足的前提下）。

实现方式：

- **云函数**：`cloudfunctions/ageRecommendedQuery`，入参 `ageKey`（如 `5-6`），从 `worksheets` 集合查询 `status=active 且 ageMin/ageMax 匹配` 的数据并返回 6 条
- **分龄页运行时**：在切换年龄段时调用该云函数，拿到 `title + previewImg + worksheetId` 渲染
- **兜底**：云函数失败或无数据时，前端使用本地占位推荐（后续可替换为固定兜底表）

---

## 三、`age.config.ts` 完整结构

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

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

// ─── 类型定义 ─────────────────────────────────
export type AbilityItem = {
    icon: string;
    title: string;
    desc: string;
};

export type WeekExercise = {
    _id: string;
    title: string;
    subtitle: string;
    path: string;
};

export type WeekPlan = {
    week: number;
    theme: string;
    exercises: WeekExercise[];
};

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

// ─── 第一部分：年龄段设置（手动维护，几乎不变）────────
export const AGE_TAB_SUB: Record<AgeBandKey, string> = {
    '3-4': '启蒙认知',
    '4-5': '基础练习',
    '5-6': '能力提升',
    '6-7': '幼小衔接',
    '7-8': '知识拓展',
};

// ─── 第二部分：能力目标（由 AI Skill generate-age-abilities 生成）────────
export const AGE_ABILITIES: Record<AgeBandKey, AbilityItem[]> = {
    '3-4': [
        /* AI 生成内容 */
    ],
    '4-5': [
        /* AI 生成内容 */
    ],
    '5-6': [
        /* AI 生成内容 */
    ],
    '6-7': [
        /* AI 生成内容 */
    ],
    '7-8': [
        /* AI 生成内容 */
    ],
};

// ─── 第三部分：4 周学习路线（由 AI Skill generate-age-weekly-plans 生成）────────
export const AGE_WEEK_PLANS: Record<AgeBandKey, WeekPlan[]> = {
    '3-4': [
        /* AI 生成内容 */
    ],
    '4-5': [
        /* AI 生成内容 */
    ],
    '5-6': [
        /* AI 生成内容 */
    ],
    '6-7': [
        /* AI 生成内容 */
    ],
    '7-8': [
        /* AI 生成内容 */
    ],
};
```

---

## 四、AI Skill 方案

### 4.1 设计思路

通过两个 Cursor AI Skill 分别管理第二部分和第三部分的内容生成：

```
doodle-mini/skills/
  ├── generate-age-abilities/
  │   └── SKILL.md          # Skill 1：生成能力目标
  └── generate-age-weekly-plans/
      └── SKILL.md          # Skill 2：生成 4 周学习路线
```

两个 Skill 的共同点：

1. **数据输入**：`page-config.json` 存储在微信云存储（路径：`/content/page-config.json`），本地不存在。运行 Skill 前需先将其下载到 `.cache/page-config.json`（通过微信开发者工具或 `tcb` CLI），Skill 从本地缓存读取 `category` 下所有 worksheet 的标题、描述和内容
2. **专家视角**：以儿童早教专家（3-8 岁）的专业视角进行内容编排
3. **输出目标**：生成符合 `age.config.ts` 数据结构的 TypeScript 代码，直接更新配置文件

### 4.2 Skill 1：`generate-age-abilities`（生成能力目标）

**触发场景：** 当 worksheet 内容体系发生较大变化（如新增学科分类、调整难度体系）时运行

**生成逻辑：**

1. 读取所有 active worksheet 的分类、年龄段、难度、标题和描述
2. 按年龄段分组，分析该年龄段覆盖的知识领域和技能点
3. 以早教专家视角，为每个年龄段总结 3 个核心能力维度（数感/书写/思维 或根据实际内容调整）
4. 每个能力维度用一句话描述该年龄段应达到的水平
5. 更新 `age.config.ts` 中的 `AGE_ABILITIES`

### 4.3 Skill 2：`generate-age-weekly-plans`（生成 4 周学习路线）

**触发场景：** 每次有新 worksheet 发布上线后运行，确保学习路线推荐最新内容

**生成逻辑：**

1. 读取所有 active worksheet 的完整信息（标题、描述、分类、年龄段、难度）
2. 按年龄段分组，筛选适合该年龄段的 worksheet
3. 以早教专家视角，设计 4 周主题式学习路线：

- 遵循由易到难、由基础到综合的编排原则
- 每周一个主题，覆盖不同能力维度
- 每周 3 个练习，从实际存在的 worksheet 中选取
- 确保 4 周内容覆盖该年龄段的主要学科和技能

4. 生成 `WeekPlan[]` 数据，关联实际 worksheet ID
5. 更新 `age.config.ts` 中的 `AGE_WEEK_PLANS`

### 4.4 数据获取方式

`page-config.json` 存储在微信云存储中（路径：`/content/page-config.json`），Skill 运行在本地 Cursor 环境中，无法直接访问云存储。需先将文件下载到本地：

**前置步骤：下载 page-config.json 到本地缓存**

```bash
mkdir -p .cache
```

下载方式（任选其一）：

1. **微信开发者工具**：云开发控制台 → 存储 → 找到 `/content/page-config.json` → 下载 → 保存到 `.cache/page-config.json`
2. **tcb CLI**：`tcb storage:download /content/page-config.json .cache/page-config.json`

**Skill 读取本地缓存**

```
读取 .cache/page-config.json
  → 解析 category.categories[].items[]
  → 提取每个 worksheet 的 id、title、description、category、ageBand、difficulty
```

> `.cache/` 目录应加入 `.gitignore`，仅作为 Skill 运行时的临时数据源。

---

## 五、分龄页管理（Debug 管理页）

### 5.1 管理页入口

`supportPages/ageContentManage/ageContentManage`（待开发）

### 5.2 管理 UI

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

| 模块     | 操作     | 说明                                                       |
| -------- | -------- | ---------------------------------------------------------- |
| 能力目标 | 只读展示 | 来自 `age.config.ts` 的 `AGE_ABILITIES`，由 AI Skill 维护  |
| 四周路线 | 只读展示 | 来自 `age.config.ts` 的 `AGE_WEEK_PLANS`，由 AI Skill 维护 |
| 推荐内容 | 自动计算 | 运行时取收藏/下载最高的 6 个 worksheet                     |

> 注：第二、三部分改为由 AI Skill 在开发时生成并提交代码，管理页仅作预览展示，不再需要手动选择 worksheet。

### 5.3 更新流程

```
AI Skill 生成流程（开发时）：
  0. 从云存储下载 /content/page-config.json → 保存到 .cache/page-config.json
  1. 开发者在 Cursor 中运行 AI Skill
  2. Skill 读取 .cache/page-config.json 中的 worksheet 数据
  3. 以早教专家视角生成能力目标 / 学习路线
  4. 自动更新 age.config.ts
  5. 开发者 review 后提交代码

运行时数据流：
  分龄页 onLoad / 切换年龄段
    → 从 age.config.ts 读取能力目标 + 学习路线（静态）
    → 调用云函数 ageRecommendedQuery(ageKey) 获取推荐（动态）
    → 渲染页面
```

---

## 六、数据结构

### 6.1 分龄页完整数据结构

```ts
type AgePageData = {
    ageTabs: Array<{
        key: AgeBandKey;
        rangeText: string; // '3-4'
        subLabel: string; // '启蒙认知'
    }>;
    bands: Record<
        AgeBandKey,
        {
            abilities: AbilityItem[];
            weeks: WeekPlan[];
            recommended: RecommendedItem[]; // 运行时动态计算
        }
    >;
};

type RecommendedItem = {
    id: string;
    title: string;
    image: string;
    worksheetId: string;
};
```

---

## 七、实施计划

### Phase 1：配置文件重构

1. 创建 `miniprogram/pages/age/age.config.ts`，从 `age.ts` 中抽取类型定义和静态数据
2. 重构 `age.ts`，改为引用 `age.config.ts` 中的配置

### Phase 2：AI Skill 开发

1. 创建 `skills/generate-age-abilities/SKILL.md`
2. 创建 `skills/generate-age-weekly-plans/SKILL.md`
3. 运行 Skill 生成初始内容，验证数据结构正确性

### Phase 3：动态推荐

1. 新增云函数 `ageRecommendedQuery`（downloads Top3 + likes Top3）
2. 分龄页调用云函数并渲染「为你推荐」

---

## 八、关键文件索引

| 文件 / 模块                                 | 职责                                                |
| ------------------------------------------- | --------------------------------------------------- |
| `pages/age/age.config.ts`                   | 分龄页配置（类型定义 + 静态数据 + AI 生成数据）     |
| `pages/age/age.ts`                          | 分龄页逻辑，引用 age.config.ts                      |
| `skills/generate-age-abilities/SKILL.md`    | AI Skill：生成各年龄段能力目标                      |
| `skills/generate-age-weekly-plans/SKILL.md` | AI Skill：生成 4 周学习路线                         |
| `core/data/difficulty.ts`                   | AGE_BANDS 年龄段定义                                |
| `core/data/categories.ts`                   | CATEGORY_LIST 分类定义                              |
| `.cache/page-config.json`                   | worksheet 数据本地缓存（运行 Skill 前从云存储下载） |
| 云存储 `/content/page-config.json`          | worksheet 数据源（Source of Truth）                 |
| `cloudfunctions/worksheetsQuery/`           | 查询 worksheet 的云函数                             |
| `cloudfunctions/ageRecommendedQuery/`       | 分龄页推荐：同年龄段 downloads Top3 + likes Top3    |