e87e2dde00
后端重构:
- 添加统一响应格式 ResultDto<T> 和 PageResultDto<T>
- 添加分页查询 DTO 基类 PageQueryDto
- 添加响应转换拦截器 TransformInterceptor
- 添加公共工具函数（JSON 解析、分页计算）
- 配置 Swagger/OpenAPI 文档（访问路径：/api-docs）
- Tenant 模块 DTO 规范化示例（添加 @ApiProperty 装饰器）
- CourseLesson 控制器重构 - 移除类级路径参数，修复 Orval 验证错误
- 后端 DTO 规范化 - 为 Course、Lesson、TeacherCourse、SchoolCourse 控制器添加完整的 Swagger 装饰器
前端重构:
- 配置 Orval 从后端 OpenAPI 自动生成 API 客户端
- 生成 API 客户端代码（带完整参数定义）
- 创建 API 客户端统一入口 (src/api/client.ts)
- 创建 API 适配层 (src/api/teacher.adapter.ts)
- 配置文件路由 (unplugin-vue-router)
- 课程模块迁移到新 API 客户端
- 修复 PrepareModeView.vue API 调用错误
- 教师模块迁移到新 API 客户端
- 修复 school-course.ts 类型错误
- 清理 teacher.adapter.ts 未使用导入
- 修复 client.ts API 客户端结构
- 创建文件路由目录结构
Bug 修复:
- 修复路由配置问题 - 移除 top-level await，改用手动路由配置
- 修复响应拦截器 - 正确解包 { code, message, data } 格式的响应
- 清理 teacher.adapter.ts 未使用导入
- 修复 client.ts API 客户端结构
- 创建文件路由目录结构
系统测试:
- 后端 API 测试通过 (7/7)
- 前端路由测试通过 (4/4)
- 数据库完整性验证通过
- Orval API 客户端验证通过
- 超管端功能测试通过 (97.8% 通过率)
新增文件:
- reading-platform-backend/src/common/dto/result.dto.ts
- reading-platform-backend/src/common/dto/page-query.dto.ts
- reading-platform-backend/src/common/interceptors/transform.interceptor.ts
- reading-platform-backend/src/common/utils/json.util.ts
- reading-platform-backend/src/common/utils/pagination.util.ts
- reading-platform-frontend/orval.config.ts
- reading-platform-frontend/src/api/generated/mutator.ts
- reading-platform-frontend/src/api/client.ts
- reading-platform-frontend/src/api/teacher.adapter.ts
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
407 lines
17 KiB
Markdown
407 lines
17 KiB
Markdown
# 幼儿阅读教学服务平台 - 项目总览
|
||
|
||
> 更新时间：2026-02-27
|
||
> 项目状态：需求重构中 - 课程包与套餐结构重构
|
||
|
||
---
|
||
|
||
## ⚠️ 重要变更通知（2026-02-27）
|
||
|
||
本项目正在进行**课程包与套餐结构重构**，涉及较大幅度的需求变更。请优先阅读以下新文档：
|
||
|
||
| 文档 | 说明 |
|
||
|-----|------|
|
||
| **[17-课程包套餐重构需求.md](./17-课程包套餐重构需求.md)** | 最新需求文档，包含完整的重构需求 |
|
||
|
||
**核心变更点：**
|
||
- 新增"课程套餐"概念（授权/计费单位）
|
||
- 课程包结构重构（从单次课程变为教学单元）
|
||
- 新增"校本课程包"功能
|
||
- 授权方式变更（从按课程包授权变为按套餐授权）
|
||
|
||
---
|
||
|
||
## 📋 项目简介
|
||
|
||
**幼儿阅读教学服务平台**是一个面向幼儿园的B2B2C阅读教学服务平台，将优质绘本资源包装成教学课程，帮助幼儿园老师更好地完成教学工作。
|
||
|
||
### 核心价值
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ │
|
||
│ 专业教研团队 幼儿园教师 │
|
||
│ │ │ │
|
||
│ │ 课程套餐制作工作台 │ │
|
||
│ │ └──────┬───────────────┘ │
|
||
│ │ │ │
|
||
│ ▼ ▼ │
|
||
│ 教学方案 ────▶ 课程套餐（含课程包） ────▶ "傻瓜式"教学 │
|
||
│ +素材资源 (按年级编排、 (备课简单、 │
|
||
│ 授权分发) 上课轻松) │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 🏗️ 平台架构
|
||
|
||
### 技术形态（MVP）
|
||
|
||
| 端 | 技术形态 | 说明 |
|
||
|---|---------|------|
|
||
| 🔴 超管端 | Web端 | PC浏览器访问，复杂内容管理操作 |
|
||
| 🔴 学校端 | Web端 | PC浏览器访问，数据查看和管理 |
|
||
| 🔴 教师端 | Web端 | PC/平板浏览器访问，支持投屏上课 |
|
||
| ⬜ 家长端 | H5响应式 | 手机/平板访问，支持微信内打开（V2版本） |
|
||
|
||
### 当前技术栈
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|-----|------|------|
|
||
| 前端框架 | Vue 3 + Vite | 已实现 |
|
||
| UI组件库 | Ant Design Vue | 已实现 |
|
||
| 状态管理 | Pinia | 已实现 |
|
||
| 后端框架 | NestJS | 已实现 |
|
||
| ORM | Prisma | 已实现 |
|
||
| 数据库 | SQLite（开发）→ PostgreSQL（生产） | 开发阶段使用SQLite |
|
||
| 认证 | JWT + Passport | 已实现 |
|
||
|
||
### 系统架构图
|
||
|
||
```
|
||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||
│ 超管端Web │ │ 学校端Web │ │ 教师端Web │ ← MVP
|
||
└──────────┘ └──────────┘ └──────────┘
|
||
│ │ │
|
||
└─────────────┼─────────────┘
|
||
│
|
||
┌──────▼──────┐
|
||
│ 后端API服务 │
|
||
└─────────────┘
|
||
│
|
||
┌──────▼──────┐
|
||
│ 数据库 │
|
||
└─────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 👥 角色体系
|
||
|
||
| 角色 | 核心诉求 | 主要功能 |
|
||
|-----|---------|---------|
|
||
| **超管端** | 制作套餐和课程包、管理租户、数据统计 | 套餐管理、课程包制作、租户管理、资源库、数据看板 |
|
||
| **学校端** | 管理教师、查看数据、套餐管理 | 教师管理、学生管理、套餐续费、校本课程包 |
|
||
| **教师端** | 备课上课、记录测评、班级管理 | 课程中心、备课模式、上课模式、校本课程包、成长档案 |
|
||
| **家长端** | 查看孩子情况、亲子共读 | 孩子成长档案、阅读记录、亲子共读指导（V2） |
|
||
|
||
---
|
||
|
||
## 📦 核心功能模块（新结构）
|
||
|
||
### 超管端
|
||
|
||
| 模块 | 功能 | 状态 | 说明 |
|
||
|-----|------|------|------|
|
||
| **套餐管理** | 创建、编辑、发布套餐 | ✅ 已实现 | 新增模块，授权/计费单位 |
|
||
| **课程包管理** | 创建、编辑课程包（6步流程） | ✅ 已实现 | 结构重构（8个富文本+3类课程） |
|
||
| **主题字典** | 全局主题管理 | ✅ 已实现 | 新增模块 |
|
||
| 租户管理 | 开通学校、套餐授权 | ✅ 已实现 | 从按课程包授权改为按套餐授权 |
|
||
| 资源库管理 | 绘本库、多媒体素材 | ⬜ 待开发 | 第二阶段开发 |
|
||
| 数据统计看板 | 平台整体数据 | ⬜ 待开发 | 租户数、套餐数、使用量 |
|
||
| 系统配置 | 标签体系、年级配置 | ✅ 已实现 | 预置《3-6岁指南》标签 |
|
||
|
||
### 学校端
|
||
|
||
| 模块 | 功能 | 状态 | 说明 |
|
||
|-----|------|------|------|
|
||
| 首页看板 | 学校数据概览 | 🔄 框架完成 | 授课趋势、活跃教师、课程排行 |
|
||
| 教师管理 | 教师列表、账号管理 | 🔄 框架完成 | 新增/停用教师、查看教师数据 |
|
||
| **套餐管理** | 查看套餐、续订套餐 | 🆕 待开发 | 新增模块 |
|
||
| **校本课程包** | 查看、预约、排课 | 🆕 待开发 | 新增模块 |
|
||
| 课程包查看 | 查看课程包详情 | 🔄 需调整 | 适配新结构 |
|
||
| 学生管理 | 学生列表、班级管理 | 🔄 框架完成 | 学生信息、成长档案 |
|
||
| 数据报表 | 授课统计、教师活跃度 | ⬜ 待开发 | 数据导出 |
|
||
|
||
### 教师端
|
||
|
||
| 模块 | 功能 | 状态 | 说明 |
|
||
|-----|------|------|------|
|
||
| 课程中心 | 浏览、搜索课程包 | 🔄 需调整 | 适配新结构展示 |
|
||
| 备课模式 | 左侧导航+右侧预览 | 🔄 需调整 | 按课程维度备课 |
|
||
| 上课模式 | 大屏展示+环节导航 | 🔄 需调整 | 支持整体上或选择性上 |
|
||
| **校本课程包** | 创建、编辑校本课程包 | 🆕 待开发 | 新增模块 |
|
||
| 反馈记录 | 快速记录+详细反馈 | 🔄 部分完成 | 课程评分、意见建议 |
|
||
| 班级管理 | 学生列表、班级数据 | 🔄 框架完成 | 管理班级学生 |
|
||
| 成长档案 | 五大领域发展情况 | ⬜ 待开发 | 查看学生阅读和测评数据 |
|
||
|
||
---
|
||
|
||
## 🎓 课程体系（新结构）
|
||
|
||
### 概念层级
|
||
|
||
```
|
||
课程套餐（授权/计费单位）
|
||
│
|
||
├── 按年级分组（小班/中班/大班）
|
||
├── 课程包有前后顺序
|
||
│
|
||
└── 包含多个 ──→ 课程包
|
||
│
|
||
├── 基本信息（主题、年级、绘本、核心内容）
|
||
├── 课程介绍（8个富文本）
|
||
├── 排课计划参考（表格）
|
||
│
|
||
└── 包含课程
|
||
├── 1. 导入课（5-15分钟）
|
||
├── 2. 集体课（约25分钟）
|
||
└── 3. 五大领域课（可选）
|
||
├── 语言领域课
|
||
├── 健康领域课
|
||
├── 科学领域课
|
||
├── 社会领域课
|
||
└── 艺术领域课
|
||
```
|
||
|
||
### 课程包新结构
|
||
|
||
| 模块 | 内容 |
|
||
|-----|------|
|
||
| 基本信息 | 主题（字典单选）、适用年级、关联绘本、核心内容 |
|
||
| 课程介绍 | 课程简介、课程亮点、课程总目标、课程内容安排、教学重难点、教学方法、评价方式、注意事项 |
|
||
| 排课计划参考 | 表格：时间、课程类型、课程名称、区域活动、备注 |
|
||
| 导入课 | 教学目标、教学准备、教学过程（自定义环节）、教学反思、测评工具 |
|
||
| 集体课 | 核心资源（动画+课件）、教学目标、教学准备、教学过程（4环节模板）、教学延伸、教学反思、测评工具 |
|
||
| 五大领域课 | 结构同集体课，但教学过程自定义，可选配置 |
|
||
|
||
### 标签体系（基于《3-6岁指南》）
|
||
|
||
```
|
||
一级：五大领域（5个）
|
||
└─ 二级：子领域（11个）
|
||
└─ 三级：发展目标（32个）
|
||
└─ 四级：年龄段指标（96个）
|
||
```
|
||
|
||
| 领域 | 子领域 | 目标数 |
|
||
|-----|-------|-------|
|
||
| 健康 | 身心状况、动作发展、生活习惯与能力 | 9个 |
|
||
| 语言 | 倾听与表达、阅读与书写准备 | 6个 |
|
||
| 社会 | 人际交往、社会适应 | 7个 |
|
||
| 科学 | 科学探究、数学认知 | 6个 |
|
||
| 艺术 | 感受与欣赏、表现与创造 | 4个 |
|
||
|
||
---
|
||
|
||
## 💰 商业模式（新结构）
|
||
|
||
### 盈利模式
|
||
|
||
| 项目 | 说明 |
|
||
|-----|------|
|
||
| 收费方式 | 按年/学期向幼儿园收费 |
|
||
| **授权单位** | **按课程套餐授权**（非按课程包） |
|
||
| 套餐定价 | 手动填写固定价格或折扣价格 |
|
||
|
||
### 套餐示例
|
||
|
||
| 套餐类型 | 包含内容 | 价格示例 |
|
||
|---------|---------|---------|
|
||
| 小班套餐 | 小班年级所有课程包 | 待定 |
|
||
| 中班套餐 | 中班年级所有课程包 | 待定 |
|
||
| 大班套餐 | 大班年级所有课程包 | 待定 |
|
||
| 全年套餐 | 所有年级课程包 | 待定 |
|
||
| 主题套餐 | 特定主题的课程包合集 | 待定 |
|
||
|
||
### 竞争优势
|
||
|
||
- ✅ 独家版权绘本资源
|
||
- ✅ 专业教研团队
|
||
- ✅ 强大的研发能力
|
||
- ✅ 完整的教学体系（导入→集体→领域延伸）
|
||
|
||
---
|
||
|
||
## 🗄️ 数据模型（重构中）
|
||
|
||
### 新增核心实体
|
||
|
||
```
|
||
课程套餐 (course_packages)
|
||
│
|
||
├──← 套餐-课程包关联 (course_package_courses) →→ 课程包 (courses)
|
||
│ │
|
||
│ ├── 课程 (course_lessons)
|
||
│ │ │
|
||
│ │ └── 教学环节 (lesson_steps)
|
||
│ │
|
||
│ └── 校本课程包 (school_course_packages)
|
||
│
|
||
└── 租户-套餐授权 (tenant_packages)
|
||
```
|
||
|
||
### 主要数据表（重构后）
|
||
|
||
| 表名 | 说明 | 状态 |
|
||
|-----|------|------|
|
||
| course_packages | 课程套餐 | 🆕 新增 |
|
||
| course_package_courses | 套餐-课程包关联 | 🆕 新增 |
|
||
| courses | 课程包 | 🔄 重构 |
|
||
| course_lessons | 课程（导入课/集体课/领域课） | 🆕 新增 |
|
||
| lesson_steps | 教学环节 | 🆕 新增 |
|
||
| school_course_packages | 校本课程包 | 🆕 新增 |
|
||
| themes | 主题字典 | 🆕 新增 |
|
||
| tenants | 租户（幼儿园） | ✅ 保留 |
|
||
| teachers | 教师 | ✅ 保留 |
|
||
| students | 学生 | ✅ 保留 |
|
||
| classes | 班级 | ✅ 保留 |
|
||
| tags | 标签体系 | ✅ 保留 |
|
||
|
||
---
|
||
|
||
## 🔌 API接口设计
|
||
|
||
### 接口规范
|
||
|
||
| 项目 | 说明 |
|
||
|-----|------|
|
||
| 协议 | HTTPS |
|
||
| 数据格式 | JSON |
|
||
| 认证方式 | JWT Token |
|
||
| 基础路径 | `/api/v1` |
|
||
|
||
### 主要API模块
|
||
|
||
| 模块 | 路径前缀 | 说明 |
|
||
|-----|---------|------|
|
||
| 认证 | `/auth` | 登录、登出、刷新Token |
|
||
| 超管端 | `/admin` | 套餐管理、课程包管理、租户管理 |
|
||
| 学校端 | `/school` | 教师、学生、班级、套餐、校本课程包 |
|
||
| 教师端 | `/teacher` | 课程包、备课、上课、校本课程包、反馈 |
|
||
| 文件上传 | `/files` | 文件上传、删除 |
|
||
|
||
---
|
||
|
||
## 📅 开发计划与进度
|
||
|
||
### 重构阶段（当前）
|
||
|
||
```
|
||
Phase R1 (2-3周) → 需求梳理与设计重构 ✅ 已完成
|
||
├── ✅ 需求梳理完成
|
||
├── ✅ 设计重构
|
||
│ ├── ✅ 超管端设计（套餐管理、课程包管理）
|
||
│ ├── ✅ 教师端设计（适配新结构）
|
||
│ └── ✅ 学校端设计（新增套餐、校本课程包）
|
||
└── ✅ 数据模型重构
|
||
|
||
Phase R2 (3-4周) → 功能重构 ✅ 已完成（2026-02-27）
|
||
├── ✅ 超管端：套餐管理、课程包管理重构（6步流程）
|
||
├── ✅ 学校端：套餐查看、校本课程包
|
||
├── ✅ 教师端：适配新结构、校本课程包
|
||
└── ✅ 后端API重构
|
||
|
||
Phase R3 (2周) → 测试与优化 ✅ 已完成（2026-02-27）
|
||
├── ✅ 功能测试
|
||
├── ✅ 数据迁移
|
||
└── ⬜ 上线部署
|
||
```
|
||
|
||
### MVP验证指标
|
||
|
||
| 指标 | 目标 |
|
||
|-----|------|
|
||
| 课程套餐数量 | ≥3个（覆盖小/中/大班） |
|
||
| 课程包数量 | ≥10个（覆盖各年级） |
|
||
| 试点学校 | ≥5所幼儿园 |
|
||
| 活跃教师 | ≥20人 |
|
||
| 使用次数 | ≥100次授课 |
|
||
| 反馈收集 | ≥50条反馈 |
|
||
| 付费意愿 | ≥2所续费意向 |
|
||
|
||
---
|
||
|
||
## 📁 项目文档清单
|
||
|
||
### 核心文档（最新）
|
||
|
||
| 序号 | 文档名称 | 状态 | 内容摘要 |
|
||
|-----|---------|------|---------|
|
||
| **17** | **课程包套餐重构需求** | ✅ 已完成 | 完整的重构需求文档 |
|
||
| **18** | **超管端设计-重构版** | ✅ 已完成 | 套餐管理、课程包管理、主题字典 |
|
||
| **19** | **教师端设计-重构版** | ✅ 已完成 | 课程包查看、备课、上课、校本课程包 |
|
||
| **20** | **学校端设计-重构版** | ✅ 已完成 | 套餐查看、续订、校本课程包管理 |
|
||
| **21** | **数据模型重构设计** | ✅ 已完成 | 新增表设计、重构表设计、迁移方案 |
|
||
| **22** | **教师端重构开发规划** | ✅ 已完成 | 6阶段开发规划，Phase 1-6 全部完成 |
|
||
| **23** | **校本课程包功能完善设计** | ✅ 已完成 | 校本课程包完整设计方案 |
|
||
| **24** | **展播模式优化设计** | ✅ 已完成 | 展播模式儿童友好界面设计 |
|
||
| 00 | 项目概览 | ✅ | 本文档 |
|
||
|
||
### 设计文档
|
||
|
||
| 序号 | 文档名称 | 状态 | 说明 |
|
||
|-----|---------|------|------|
|
||
| 01 | 商业模式 | ⚠️ 需更新 | 套餐定价模式已变更 |
|
||
| 02 | 角色分析 | ✅ 有效 | 四端角色核心诉求 |
|
||
| 03 | 课程体系 | ⚠️ 需更新 | 课程包结构已重构 |
|
||
| 04 | 教学场景 | ✅ 有效 | 一日活动流程、延伸活动形式 |
|
||
| 06 | 指南解读与应用 | ✅ 有效 | 《3-6岁指南》标签体系详解 |
|
||
| 07 | 课程包设计 | ❌ **已过时** | 被17号文档替代 |
|
||
| 08 | 教师端功能设计 | ⚠️ 需更新 | 适配新结构 |
|
||
| 08+ | 教师端功能设计（补充）| ⚠️ 需更新 | 适配新结构 |
|
||
| 09 | 标签体系详解 | ✅ 有效 | 4级标签体系完整表格 |
|
||
| 10 | 超管端功能设计 | ❌ **已过时** | 被17号文档替代 |
|
||
| 11 | 技术形态与MVP范围 | ✅ 有效 | 技术选型、MVP功能清单 |
|
||
| 12 | 学校端功能设计 | ⚠️ 需更新 | 新增套餐、校本课程包 |
|
||
| 13 | 数据模型与API设计 | ❌ **已过时** | 需按新结构重构 |
|
||
| 15 | 课程发布流程完善方案 | ⚠️ 需更新 | 状态流转逻辑保留，但需适配套餐 |
|
||
| 16 | 教学环节资源关联设计 | ⚠️ 需更新 | 适配新的课程/环节结构 |
|
||
| 99 | 决策记录 | ✅ 有效 | 历次讨论结论和待办清单 |
|
||
|
||
### 文档状态说明
|
||
|
||
| 标记 | 说明 |
|
||
|-----|------|
|
||
| 🆕 最新 | 最新文档，优先参考 |
|
||
| ✅ 有效 | 文档内容仍然有效 |
|
||
| ⚠️ 需更新 | 部分内容需要更新 |
|
||
| ❌ 已过时 | 文档已被新文档替代，仅供参考 |
|
||
|
||
---
|
||
|
||
## 🚀 下一步行动
|
||
|
||
### 当前重点
|
||
|
||
| 优先级 | 任务 | 状态 |
|
||
|-------|------|------|
|
||
| 🔴 P0 | 设计重构 - 超管端（套餐管理、课程包管理） | ✅ 完成 |
|
||
| 🔴 P0 | 设计重构 - 教师端（适配新结构） | ✅ 完成 |
|
||
| 🔴 P0 | 设计重构 - 学校端（套餐、校本课程包） | ✅ 完成 |
|
||
| 🟡 P1 | 数据模型重构 | ✅ 完成 |
|
||
| 🟡 P1 | 后端API重构 | ✅ 完成 |
|
||
| 🟡 P1 | 前端界面开发 | ✅ 完成 |
|
||
| 🟢 P2 | 课程包7步流程重构 | ✅ 完成（2026-02-27） |
|
||
| 🟢 P2 | Bug修复（10个） | ✅ 完成（2026-02-27） |
|
||
| 🟢 P2 | 学校端新功能开发 | ✅ 完成（2026-02-27 晚） |
|
||
| 🟢 P3 | 教师端重构 Phase 1-6 | ✅ 完成（2026-03-11） |
|
||
| 🟢 P3 | PDF查看器增强（PDF.js） | ✅ 完成（2026-03-11） |
|
||
| 🟢 P3 | 展播模式优化 | ✅ 完成（2026-03-11） |
|
||
| 🟢 P3 | 自动化测试（60个用例） | ✅ 完成（2026-03-11） |
|
||
| ⬜ P4 | 上线部署 | 待开始 |
|
||
| ⬜ P4 | TypeScript编译警告修复 | 待开始 |
|
||
|
||
---
|
||
|
||
## 📞 联系方式
|
||
|
||
如有问题或需要进一步讨论，请联系项目组。
|
||
|
||
---
|
||
|
||
**文档版本：v2.3**
|
||
**最后更新：2026-03-11**
|