feat: 完成分龄页开发
This commit is contained in:
R524809
@@ -0,0 +1,396 @@
|
||||
# 分龄页内容管理方案
|
||||
|
||||
> 版本：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 |
|
||||
Reference in New Issue
Block a user