从 Demo 到正式项目的改造工作

文档目的

这份文档说明：如果后续要把当前 demo 逐步转成真实项目，需要做哪些主要工作。

当前 Demo 的本质

当前项目的前端结构已经比较稳定，但业务数据仍然是 demo 驱动。

当前特点：

• 页面结构真实
• 流程体验基本可演示
• 数据和状态主要来自本地 mock 与 storage
• 没有真实后端服务接入

因此，后续工作以逐步把“假数据驱动”替换为“真实业务驱动”为主。

改造工作总览

第一阶段：稳定产品定义

目标：

• 明确真实业务范围
• 明确 MVP 范围
• 明确用户角色

需要产出：

• 产品功能清单
• 页面流程图
• 数据实体清单
• 接口清单

第二阶段：补后端基础能力

目标：

• 让 demo 中的关键页面有真实数据来源

优先能力：

• 用户与身份
• 课程体系
• lesson 与 assessment
• 作业记录
• 消息通知
• 活动报名
• 订单与支付

第三阶段：前端适配真实接口

目标：

• 逐步替换 mock/ 和本地 demo 状态

需要做的事：

• 在 services/ 中增加真实接口调用
• 建立接口错误处理
• 建立加载状态
• 建立空状态和异常状态
• 保留一部分 mock 仅用于开发环境

第四阶段：后台管理系统建设

目标：

• 让课程、活动、消息、订单等数据可运营

后台模块范围包括：

• 学员管理
• 课程管理
• 排课管理
• lesson 内容管理
• 测评管理
• 作业与点评管理
• 活动管理
• 消息推送管理
• 订单管理
• 会员管理

当前代码层的主要替换点

1. mock/ 层

当前职责：

• 存演示数据

后续变化：

• 逐步缩小为开发环境 fixture
• 正式环境不再作为主数据来源

2. store/ 中的 demo 状态

当前职责：

• 用于模拟购买、已读、报名、提交等状态

后续变化：

• 部分状态改由后端返回
• 前端只保留 UI 临时状态和缓存

3. services/

当前职责：

• 作为 demo 数据查询入口

后续变化：

• 成为真实 API 的适配层
• 负责把后端数据映射成页面需要的 view model

4. packages/types

当前职责：

• 沉淀稳定字段约定

后续变化：

• 对齐真实接口 payload
• 逐步成为前后端共享契约

真实化改造顺序

可按下面顺序推进：

1. 登录/学员信息
2. 课程与课表
3. lesson / assessment 内容
4. 作业记录与提交
5. 消息中心
6. 活动报名
7. 订单与支付
8. 会员体系
9. 后台管理系统

原因：

• 前几项最直接决定主业务可用性
• 支付和会员虽然重要，但依赖前面的课程和订单模型
• 后台应围绕真实业务模型建设，而不是围绕 demo 页面建设

改造过程中应保持的原则

• 不推翻当前目录结构
• 页面仍通过 services/ 取数
• 平台专属逻辑继续留在 apps/miniapp
• 稳定契约继续沉淀在 packages/types
• 纯函数继续沉淀在 packages/shared

当前优先补充内容

如果要真正从 demo 进入正式开发，最先要补的是：

• 产品范围说明
• 业务流程说明
• 数据实体定义
• 接口清单

这些不清楚，后端和后台很容易做偏。