Claude Opus 4.6 e87e2dde00 refactor: 完成代码重构规范化 - 2026-03-12

后端重构:
- 添加统一响应格式 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>

2026-03-12 17:27:13 +08:00

17 KiB

Raw Permalink Blame History

幼儿阅读教学服务平台 - 项目总览

更新时间：2026-02-27 项目状态：需求重构中 - 课程包与套餐结构重构

⚠️ 重要变更通知（2026-02-27）

本项目正在进行课程包与套餐结构重构，涉及较大幅度的需求变更。请优先阅读以下新文档：

文档	说明
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

17 KiB Raw Permalink Blame History Unescape Escape