Hulumath-Web-Demo/docs/产品文档/开发需求.md

数学脑 · 开发需求文档

版本：MVP v6.0 | 更新日期：2023年

---

一、项目概述

项目	内容
产品名	数学脑
代码名	miniapp
类型	移动端 SPA（单页应用）Web App
架构	Flask（Python 后端） + 原生 HTML/CSS/JS（前端）
适应端	iPhone 移动端（390px 宽度，100dvh，safe-area 适配）
数据库	SQLite
AI 引擎	DeepSeek Chat API

---

二、技术栈

层级	技术	用途
后端框架	Flask 3.x（Python）	路由、API、数据库管理
数据库	SQLite（SQLite3）	视频数据、行为日志
前端	原生 HTML5 + CSS3 + Vanilla JS	SPA 页面切换、视觉小说引擎
AI 集成	DeepSeek Chat API	AI 数学助教对话
故事数据	JSON（seed_story.json）	8 章互动剧情节点树
视频数据	JSON（seed_videos.json）→ SQLite	54 条专业分区视频
UI 风格	自制设计系统（CSS 变量 + flex/grid）	iPhone 式移动端适配

---

三、项目文件结构

miniapp/
├── app.py                    # Flask 后端主文件
├── data/
│   ├── seed_story.json       # 8章93节点互动剧情数据
│   ├── seed_videos.json      # 54条专业分区种子视频
│   ├── miniapp_v3.db         # SQLite 数据库
│   ├── build_story.py        # 剧情JSON生成脚本
│   └── novel/                # 原著小说txt（素材参考）
│       ├── 葫芦侠行（第一章）.txt
│       ├── 葫芦侠行（第二章）.txt
│       ├── ...
│       └── 框架.txt
├── static/
│   ├── css/
│   │   └── style.css         # 全局样式（~1400行）
│   └── js/
│       └── app.js            # 前端核心逻辑（~550行）
└── templates/
    └── index.html            # SPA 入口页面（~286行）

---

四、后端 API 接口

路径	方法	参数	返回	说明
/	GET	—	HTML	返回 SPA 首页
/api/videos	GET	module(选填), discipline(选填)	{code, data, disciplines}	视频列表 + 学科分类
/api/chat	POST	{message, student_id}	{code, reply, is_fallback}	AI 对话（DeepSeek）
/api/story	GET	—	{code, data}	获取互动剧情 JSON
/api/log	POST	{user_id, action, target}	{code, msg}	行为日志记录
/api/students	GET	—	{code, data}	学生列表（B端预留）

视频数据模型（videos 表）

字段	类型	说明
id	INTEGER PK	自增
title	TEXT NOT NULL	视频标题
module	TEXT	所属模块（如"数人"）
sub_category	TEXT	子分类
discipline	TEXT	学科（如"人工智能"）
discipline_icon	TEXT	学科 emoji
video_url	TEXT	外部视频链接
description	TEXT	视频简介
duration_min	INTEGER	时长（分钟）
author	TEXT	作者（学院+姓名）

---

五、前端架构

五层设计

┌─────────────────────────────────┐
│         index.html              │  ← 结构层：DOM 容器
├─────────────────────────────────┤
│         style.css               │  ← 表现层：响应式 + 动画
├─────────────────────────────────┤
│          app.js                 │  ← 逻辑层：路由 + 状态 + API
├─────────────────────────────────┤
│     seed_story.json             │  ← 数据层：剧情节点树
├─────────────────────────────────┤
│        Flask API                │  ← 服务层：数据库 + AI
└─────────────────────────────────┘

核心 JavaScript 模块

模块	函数	功能
全局状态	vnState, allVideos, storyData	应用级状态管理
模块切换	switchModule(), hideAllPanels()	四Tab页面切换、DOM显隐
发现页面	loadVideos(), renderVideoList(), renderDisciplineGrid()	视频流渲染、12学科网格
知识页面	renderShushuoFeed(), updateShushuoHero()	知识卡片Feed渲染
数学人生	navigateVN(), buildChoiceButtons(), applyVNStats()	视觉小说引擎核心
AI聊天	openChat(), sendMessage(), quickAsk()	AI对话弹窗
数据持久化	saveVNState(), loadVNSave(), resetVNSave()	localStorage存档

---

六、视觉小说引擎（VN Engine）

剧情数据模型

{
  "title": "葫芦侠行",
  "start_node": "ch1_start",
  "nodes": {
    "节点ID": {
      "scene": "场景描述文本",
      "character": "说话角色",
      "sprite": "角色立绘URL（可选）",
      "choices": [
        {
          "text": "选项文本",
          "next": "下一节点ID",
          "effects": {
            "shuli": 整数,      // 数理根基变化
            "xiayi": 整数,      // 侠义声望变化
            "xinzhi": 整数,     // 心志韧性变化
            "favorability": {   // 角色好感度变化
              "角色名": 整数
            }
          }
        }
      ]
    }
  }
}

四属性系统

属性	键名	初始值	说明
📐 数理根基	shuli	10	解锁高阶功法、影响论道胜负
⚔️ 侠义声望	xiayi	10	影响NPC态度、武林大会成绩
🧘 心志韧性	xinzhi	10	面对挫折的选择余地
💕 好感度	favorability	0（每人）	触发专属剧情、影响结局

当前剧情规模

• 8 章：初入江湖 → 西部教习 → 数理论道 → 脑学初创 → 报国之路 → 暗流涌动 → 陋室修炼 → 真相之门
• 93 个交互节点
• 8+ 种结局（真相守望、数理宗师、逍遥江湖、出海远航、悲情英雄、堕落之路、冤狱、虚无）

---

七、UI 设计系统

色彩系统

用途	CSS 变量	色值
发现页主色	--shuren	#F97316（橙）
知识页主色	--shushuo	#3B82F6（蓝）
数学人生主色	--shusi	#10B981（绿）
我的页主色	--mine	#8B5CF6（紫）
页面背景	--bg	#F2F3F7
卡片背景	--card	#FFFFFF
主文字	--text	#1E1E2E

布局规范

• 容器宽度：min(390px, 100vw)（iPhone 比例）
• 桌面端：居中显示 + border-radius: 34px + 阴影（模拟设备壳）
• 底部 TabBar：白色半透明玻璃感 + backdrop-filter: blur(18px) + safe-area
• 顶部状态栏：白色半透明 + 模糊 + z-index: 50
• 字体：-apple-system, PingFang SC, Microsoft YaHei

---

八、部署与运行

启动命令

cd C:\Users\Asus\Desktop\miniapp
py app.py

访问地址

http://127.0.0.1:5000/

环境要求

• Python 3.12+
• Flask
• requests
• python-docx（素材提取用，非运行时必需）

数据初始化

• 首次启动自动执行 init_db() + load_seed_videos()
• 54 条视频数据从 seed_videos.json 导入 SQLite
• 互动剧情从 seed_story.json 按需读取
• 旧数据库可通过改名绕过锁定问题

---

九、待开发需求

P0（核心）

• 用户登录系统（OAuth/手机号）
• 视频上传与审核后台
• 互动剧情章节选择器（允许跳章/读档）
• 个人中心真实数据绑定（收藏、观看记录、剧情存档）

P1（增强）

• 社交功能（评论、点赞、分享）
• 知识页数学小测验
• 视觉小说立绘 + 背景图系统
• 好感度可视化面板
• 多端适配（小程序版本）

P2（远期）

• 微服务拆分
• 实时协作编辑（多人剧情共创）
• AI 生成剧情分支
• 数据分析看板（学生行为）