844 lines
32 KiB
Markdown
844 lines
32 KiB
Markdown
文档版本：v0.3 评审稿（核心决策更新版）
|
|
文档状态：部分决策已确认
|
|
更新日期：2026-08-08
|
|
适用范围：Web 生产版，兼顾后续微信小程序
|
|
核心目标：把当前演示系统升级为可运营、可扩展、可监控、可稳定发布的线上产品
|
|
|
|
---
|
|
1. 执行摘要
|
|
当前仓库已经验证了 MathBTI、数学人物卡、知识内容、互动剧情、数学工具等产品表达，但工程形态仍属于内部 Demo：
|
|
- 后端路由、数据库和 AI 调用集中在单个 Flask 文件。
|
|
- 前端页面、状态和业务规则集中在单个 JavaScript 文件。
|
|
- SQLite 同时承载结构、种子数据和运行时用户数据。
|
|
- 用户成长、抽卡和剧情状态大量依赖 localStorage。
|
|
- 缺少正式账号、权限、数据库迁移、测试、监控和可靠回滚。
|
|
- 产品入口较多，但缺少明确的每日使用主线。
|
|
生产版不继续在当前单文件结构上堆叠功能，但也不另建一套长期并行的新旧系统。项目采用当前仓库内的分阶段重构：先建立 Django 生产骨架和兼容层，再按垂直业务链路替换 Flask 路由、SQLite 和旧前端模块，完成一个阶段即删除对应旧实现。
|
|
生产版的产品主线定义为：
|
|
数学人生是核心体验。MathBTI 帮助用户发现自己的数学人格，四条旗舰人生线让用户体验不同的数学精神，人物 Skill 包持续扩展真实而多样的人生选择；Contest、LaTeX 和内容探索既可独立使用，也服务于人生节点与长期成长。
|
|
本轮已经确认的产品方向：
|
|
暂时无法在飞书文档外展示此内容
|
|
评审建议：
|
|
- 统一剧情引擎与信仰者数学少年线作为生产版第一阶段核心功能。
|
|
- MathBTI 不是孤立测试，而是进入数学人生宇宙的身份仪式。
|
|
- 人物 Skill 包使用统一结构持续生产，首发至少提供可验证的样板。
|
|
- 首版 Contest 以实时 1v1 为主推体验，每日异步赛与其同期交付或紧随其后。
|
|
- 实时范围严格限制为单一匹配模式，不在首版扩展房间赛、淘汰赛和观战。
|
|
- 全年龄用户必须通过水平分层、兴趣选择和个性化首页解决体验冲突。
|
|
- 后端确定改为 Django 模块化单体，数据库确定改为 PostgreSQL。
|
|
- 在当前仓库中实施分阶段重构；每个新模块通过验收后替换并删除对应旧代码。
|
|
|
|
---
|
|
2. 本次评审目标
|
|
本轮已经确认：
|
|
1. “数学人生宇宙”是生产版核心产品。
|
|
2. MathBTI、四条旗舰线、人物 Skill 包和跨剧本成长属于同一系统。
|
|
3. 信仰者数学少年线是首发旗舰内容。
|
|
4. Contest 以实时多人玩法优先，异步赛同期交付或紧随其后。
|
|
5. 六个一级模块为：首页、数学人生、比赛、工具箱、探索发现、我的。
|
|
6. LaTeX Lab 放入工具箱，并作为工具箱重点能力。
|
|
7. 后端采用 Django 模块化单体。
|
|
8. 数据库采用 PostgreSQL。
|
|
9. 当前仓库进行分阶段重构，不长期并行维护两套产品系统。
|
|
本次后续评审需要形成以下结论：
|
|
1. 实时 1v1 与每日异步赛是否必须在同一次公开发布中交付。
|
|
2. 信仰者主线的章节范围与首轮试玩范围。
|
|
3. 首批人物 Skill、邀请注册方式和试点规模。
|
|
4. 确认详细交付阶段和生产验收标准。
|
|
本次评审不解决具体视觉稿、所有题目内容和每个接口字段。上述内容应在方案通过后进入详细 PRD 与技术设计阶段。
|
|
|
|
---
|
|
3. 产品定位
|
|
3.1 一句话定义
|
|
葫芦数学是一个面向全年龄数学兴趣用户的“数学人生宇宙”：用户发现自己的数学人格，进入不同数学精神对应的人生故事，在选择、关系、挑战和成长中体验数学如何塑造一个人。
|
|
3.2 核心价值
|
|
- 不把数学简化为刷题和知识点，而是呈现为人生选择、精神气质和理解世界的方式。
|
|
- 用 MathBTI 建立身份认同，让用户获得“这是一种属于我的数学人生”的入口。
|
|
- 用四条旗舰人生线提供深度沉浸，用人物 Skill 包持续扩展真实人生样本。
|
|
- 用短时 Contest 形成明确、可重复的每日行为。
|
|
- 用 LaTeX Lab 降低数学表达门槛，并成为剧情中的真实能力。
|
|
- 用个人档案记录跨剧本成长，而不是只展示静态信息。
|
|
3.3 产品核心循环
|
|
完成 MathBTI 或选择感兴趣的数学人生
|
|
↓
|
|
进入旗舰主线或人物 Skill 包
|
|
↓
|
|
在不完整信息下做人生选择
|
|
↓
|
|
管理能力、时间、关系与机会
|
|
↓
|
|
通过 Contest、LaTeX 或推理挑战改变部分结果
|
|
↓
|
|
获得结局、数学人物卡和跨剧本成长
|
|
↓
|
|
继续另一条人生，或通过每日 Contest 回访
|
|
3.4 非目标
|
|
首个生产版本不做：
|
|
- 开放式论坛、陌生人私信和用户发帖。
|
|
- 现金奖励、充值抽卡和博彩式机制。
|
|
- 四条旗舰人生线同时完整上线。
|
|
- 实时比赛的房间赛、多人混战、淘汰赛、观战等复杂形态。
|
|
- 复杂推荐算法。
|
|
- 同时重制全部历史剧情。
|
|
- 微服务拆分和 Kubernetes 集群。
|
|
|
|
---
|
|
4. 用户分层
|
|
“全年龄”不能理解为所有用户看到同一套题和同一个排行榜。系统首次使用时应建立轻量用户画像。
|
|
4.1 首次引导
|
|
首次进入需要完成或跳过以下选择：
|
|
暂时无法在飞书文档外展示此内容
|
|
涉及未成年人时，只收集实现分层所需的最少信息，不要求真实学校、真实年龄和真实姓名。
|
|
4.2 赛道分层
|
|
首发建议设置：
|
|
- 入门赛道：基础运算、直观逻辑和轻量数学常识。
|
|
- 标准赛道：初高中通用数学思维和速度挑战。
|
|
- 进阶赛道：高阶逻辑、概率、估算和大学基础数学。
|
|
- Open 赛道：不限制用户水平，用于主题活动。
|
|
用户可以自主切换练习赛道，但正式排行榜应按赛道分别计算。
|
|
|
|
---
|
|
5. 信息架构
|
|
5.1 一级导航
|
|
首页
|
|
数学人生
|
|
比赛
|
|
工具箱
|
|
探索发现
|
|
我的
|
|
建议保持左侧导航，移动端折叠为底部导航或抽屉导航。
|
|
5.2 导航结构
|
|
首页
|
|
- 继续当前数学人生
|
|
- MathBTI 身份入口
|
|
- 四大主题与人物 Skill 推荐
|
|
- 当前人生属性、关系和关键选择摘要
|
|
- 今日挑战
|
|
- 数学精灵与跨剧本成长概览
|
|
数学人生
|
|
- MathBTI：发现数学人格
|
|
- 四大旗舰主题
|
|
- 信仰者：数学少年线
|
|
- 传播者：待开发
|
|
- 应用者：待开发
|
|
- 直觉者：待开发
|
|
- 人物 Skill 人生包
|
|
- 葫芦侠行等特别篇
|
|
- 我的存档、结局与人生图鉴
|
|
比赛
|
|
- 实时竞技
|
|
- 今日挑战
|
|
- 单人闯关
|
|
- 主题周赛
|
|
- 排行榜
|
|
- 比赛历史
|
|
工具箱
|
|
- LaTeX Lab
|
|
- 手写公式
|
|
- LaTeX 编辑器
|
|
- 模板与符号库
|
|
- 分级课程
|
|
- 表达挑战
|
|
- 我的公式
|
|
- 口算练习
|
|
- 函数绘图
|
|
- 数学符号查询
|
|
- 后续数学实验工具
|
|
探索发现
|
|
- 视频
|
|
- 知识卡片
|
|
- 数学人物
|
|
- 主题筛选
|
|
我的
|
|
- 个人资料
|
|
- MathBTI 身份与数学人格
|
|
- 人生存档、结局和关键选择
|
|
- 五维能力与人物关系
|
|
- 段位和 Rating
|
|
- 比赛记录
|
|
- 错题记录
|
|
- 课程进度
|
|
- 收藏与历史
|
|
- 数学人物卡册
|
|
- 账号与安全
|
|
5.3 管理后台
|
|
管理后台独立使用 /admin，不出现在普通用户导航中。
|
|
|
|
---
|
|
6. 首页体验方案
|
|
6.1 设计原则
|
|
当前首页主要承担功能陈列。生产版首页应优先回答三个问题：
|
|
1. 我正在经历哪一段数学人生？
|
|
2. 我现在面对什么选择，为什么值得继续？
|
|
3. 今天还有什么短时行动可以推动成长？
|
|
6.2 首页优先级
|
|
从上到下建议为：
|
|
1. 继续数学人生主卡片，展示当前章节、人物和未解决事件。
|
|
2. 新用户显示 MathBTI 或“选择第一条人生”入口。
|
|
3. 四大主题和人物 Skill 的个性化推荐。
|
|
4. 今日比赛与工具箱中的 LaTeX 表达挑战。
|
|
5. 数学精灵、五维能力、卡册和结局图鉴。
|
|
6. 个性化内容推荐。
|
|
6.3 新用户任务
|
|
引导新用户一进来先做mathbti，然后再让他尝试我们四条剧本里的一个
|
|
|
|
|
|
---
|
|
6.4 数学人生核心产品方案
|
|
6.4.1 产品结构
|
|
数学人生不是导航中的一个普通内容栏目，而是连接产品其他能力的核心系统。
|
|
身份层：MathBTI 数学人格
|
|
↓
|
|
旗舰体验层：信仰者 / 传播者 / 应用者 / 直觉者
|
|
↓
|
|
扩展体验层：人物 Skill 人生包 / 特别篇
|
|
↓
|
|
互动层：隐藏信息选择 / 资源经营 / 人物羁绊 / 数学挑战
|
|
↓
|
|
成长层：五维能力 / 数学精灵 / 卡牌 / 结局图鉴
|
|
6.4.2 MathBTI 的角色
|
|
MathBTI 应从独立测试升级为数学人生的身份入口：
|
|
- 给出用户的数学人格与代表数学家。
|
|
- 推荐最适合开始的旗舰人生线，但不锁定其他路线。
|
|
- 生成初始五维能力倾向。
|
|
- 赠送第一张人物卡，并建立数学精灵。
|
|
- 测试结果影响部分开场对白、推荐顺序和隐藏选项。
|
|
- 用户可以自由重测，但历史身份和人生记录不应被覆盖。
|
|
6.4.3 四条旗舰人生线
|
|
四条路线彼此独立，每条都是约 2 小时、可分章节完成、可重复体验的完整人生线。
|
|
暂时无法在飞书文档外展示此内容
|
|
首发完整打磨“信仰者数学少年线”。另外三条路线在界面中可以展示世界观与开发状态，但不应使用空白大卡占据核心空间；可通过序章、人物预告或短 Skill 提前建立期待。
|
|
6.4.4 人物 Skill 人生包
|
|
人物 Skill 是围绕一位真实人物、数学家或校友制作的约 20 分钟短篇人生体验。
|
|
每个 Skill 包应包含：
|
|
- 明确的人物身份和真实时代或职业背景。
|
|
- 4 至 6 个关键人生节点。
|
|
- 至少一次信息不完整的高风险选择。
|
|
- 一组有限资源，例如时间、精力、收入、声望或关系。
|
|
- 2 至 4 位关键人物关系。
|
|
- 至少一个与人物经历相关的数学挑战。
|
|
- 2 个以上有意义的结局或人生评价。
|
|
- 事实来源、虚构范围和创作者信息。
|
|
Skill 包既是内容形态，也是未来的内容生产标准。校友访谈、数学家传记和职业故事都可以进入同一生产管线。
|
|
6.4.5 四类核心互动
|
|
隐藏信息选择
|
|
- 选择前只提供角色当时能够知道的信息。
|
|
- 不直接展示所有属性收益和最优答案。
|
|
- 允许通过人物关系、探索和数学能力获得额外情报。
|
|
- 结果可以延迟发生，避免每次选择立即结算成数值题。
|
|
属性与资源经营 @何立煊
|
|
建议区分两层：
|
|
- 跨剧本五维能力：眼光、人文、侦探、建模、联结。
|
|
- 剧本内资源：时间、精力、金钱、学术进度、声望等。
|
|
剧本只是剧本，只是让用户体验，不会增加五维能力，五维能力是通过看视频、签到等其他方式，获得碎片，从而获得自己的数学精灵的对应维度的能力
|
|
人物关系
|
|
- 关系不是单一好感度，应允许信任、竞争、亏欠、合作等不同状态。
|
|
- 关键人物能够提供信息、机会、挑战或阻碍。
|
|
- 关系变化应通过行为和事件表达，而不仅是显示 +5。
|
|
数学挑战
|
|
- Contest 可用于考试、竞赛、面试和限时事件。
|
|
- LaTeX 可用于证明、论文、书信和教学表达。
|
|
- 推理、估算和建模可用于调查或现实决策。
|
|
6.4.6 真实与虚构边界
|
|
采用“真实骨架 + 虚构剧情”：
|
|
- 数学知识、专业路径、时代背景和职业机制应尽量真实。
|
|
- 角色、对话、事件组合和分支可以戏剧化。
|
|
- 涉及真实人物时标记事实来源和艺术加工范围。
|
|
- 不把虚构选择包装成真实历史事实。
|
|
- 每段人生结束后提供“真实世界中的他们”或延伸阅读。
|
|
6.4.7 跨剧本成长
|
|
跨剧本成长用于连接不同人生，但不能把选择体验变成单纯刷数值：
|
|
- 五维能力记录用户体验过的数学方式。
|
|
- 人物卡代表遇见和理解过的人，而不是付费稀有度。
|
|
- 数学精灵反映长期倾向与经历。
|
|
- 结局图鉴记录不同人生选择。
|
|
- 特殊身份、卡牌或经历可解锁其他剧本的额外信息和对话。
|
|
- 核心结局不能要求重复刷取或付费。
|
|
6.4.8 数学人生大厅设计
|
|
当前页面以四张等权主题卡为主体，其中三张显示“敬请期待”。这会让核心产品看起来像尚未完成的功能目录，也没有形成继续游玩的动力。
|
|
生产版应将该页面设计为“人生大厅”，而不是剧本列表。
|
|
新用户状态
|
|
首屏结构建议：
|
|
1. 身份引导 Hero：“你会成为怎样的数学人？”
|
|
2. 主行动：开始 MathBTI。
|
|
3. 次行动：暂不测试，自由选择人生。
|
|
4. 四种数学精神的简短预览。
|
|
5. 一个可直接试玩的信仰者序章。
|
|
6. 人物 Skill 推荐，让用户理解这里不只有一条长剧情。
|
|
回访用户状态
|
|
首屏结构建议：
|
|
1. “继续你的人生”主卡：当前章节、地点、关键人物、最近选择和预计剩余时间。
|
|
2. 当前身份：MathBTI 人格、代表数学家和五维倾向。
|
|
3. 当前悬念：展示尚未解决的问题，不提前暴露结果。
|
|
4. 当前关系：只展示最关键的 2 至 3 位人物。
|
|
5. 主行动：继续旅程。
|
|
6. 次行动：回顾路径、切换存档或进入相关挑战。
|
|
四条旗舰线展示
|
|
四条线不应继续使用完全相同的空白卡片。建议使用一张“数学人生地图”或具有明显叙事差异的路线卡：
|
|
- 展示该路线的核心冲突，而不只是数学家名单。
|
|
- 展示体验时长、章节进度和已发现结局。
|
|
- MathBTI 推荐路线使用“与你最契合”标识。
|
|
- 未完成路线提供序章、人物档案或开发预告，不重复堆叠“敬请期待”。
|
|
- 不使用强制锁定，用户始终可以自由选择其他路线。
|
|
四条路线的入口文案应表达冲突：
|
|
暂时无法在飞书文档外展示此内容
|
|
人物 Skill 区
|
|
人物 Skill 应成为大厅中的持续内容流：
|
|
- 每周或每两周推荐一个人物人生。
|
|
- 卡片展示人物、时代、核心抉择和约 20 分钟时长。
|
|
- 支持按数学家、校友、职业、时代和主题筛选。
|
|
- 完成后展示人生路径，而不是只显示“通关”。
|
|
- 相关 Skill 可以反向解锁旗舰线中的信息、人物对话或卡片。
|
|
特别篇
|
|
《葫芦侠行》不应与四大人格路线混在同一层级，可放入“特别篇”：
|
|
- 保留独立世界观和叙事风格。
|
|
- 共享账号、五维能力、卡牌和结局图鉴。
|
|
- 不强行解释为四条真实人生线之一。
|
|
页面视觉优先级
|
|
继续当前人生 / MathBTI 身份入口
|
|
↓
|
|
当前悬念、关系与成长
|
|
↓
|
|
四条旗舰人生地图
|
|
↓
|
|
本期人物 Skill
|
|
↓
|
|
特别篇与已完成的人生图鉴
|
|
页面首屏不应再出现大面积不可点击的“敬请期待”卡片。
|
|
|
|
---
|
|
7. Contest 产品方案
|
|
7.1 每日异步赛
|
|
每日异步赛是重要留存模块，但不是首个上线的比赛形态。它与实时 1v1 共用题库、判分、Rating 和反作弊基础设施，在实时玩法可用后同期交付或紧随其后上线。
|
|
建议基础规则：
|
|
暂时无法在飞书文档外展示此内容
|
|
比赛计时、出题和判分必须由服务端控制。客户端只负责展示和提交答案。
|
|
7.2 单人闯关
|
|
单人闯关用于非正式练习：
|
|
- 随时开始。
|
|
- 难度逐步提升。
|
|
- 连续答对形成连击。
|
|
- 错误不会影响正式 Rating。
|
|
- 可与数学精灵经验和能力成长关联。
|
|
7.3 主题周赛
|
|
建议主题：
|
|
- 口算速度
|
|
- 估算
|
|
- 概率直觉
|
|
- 几何观察
|
|
- 逻辑推理
|
|
- 数学常识
|
|
- LaTeX 表达
|
|
主题周赛用于内容运营，不要求首发全部完成。
|
|
7.4 排行榜
|
|
排行榜分为：
|
|
- 每日榜
|
|
- 周榜
|
|
- 赛季榜
|
|
- 邀请码小组榜
|
|
- 好友榜，后续开放
|
|
排行榜默认显示昵称和头像，不显示真实姓名、学校和精确年龄。
|
|
排序原则：
|
|
1. 正式得分。
|
|
2. 正确率。
|
|
3. 完成用时。
|
|
4. 达成时间。
|
|
7.5 实时多人赛
|
|
实时多人赛是比赛模块的首发主推玩法。为了控制生产风险，第一版只实现 1v1 口算竞技，并与数学人生核心版本一起进入首发范围；每日异步赛可以同批上线，也可以在实时 1v1 稳定后紧随上线。
|
|
首个实时玩法建议限制为 1v1 口算竞技：
|
|
- Rating 匹配。
|
|
- 双方接收同一题目序列。
|
|
- 60 秒连续作答。
|
|
- 服务端计时和判分。
|
|
- 支持断线重连和超时结算。
|
|
- 结束后展示双方逐题时间线。
|
|
后续再评估多人房间、观战和淘汰赛。
|
|
首发明确不做：
|
|
- 三人及以上同局。
|
|
- 自定义房间和房主规则。
|
|
- 淘汰赛和大型锦标赛。
|
|
- 观战、弹幕和语音。
|
|
- 现金或可交易奖励。
|
|
7.6 公平与反作弊
|
|
首发最低要求：
|
|
- 正式比赛题目由服务端下发。
|
|
- 服务端记录开始、作答和提交时间。
|
|
- 正式答案不能随题目一起返回。
|
|
- 同一用户、设备和邀请码组进行基础频率限制。
|
|
- 对极端用时、重复答案序列和异常高分进行标记。
|
|
- 管理员可以隐藏异常成绩并记录操作原因。
|
|
- 不把客户端本地分数直接写入排行榜。
|
|
|
|
---
|
|
8. 工具箱与 LaTeX Lab 产品方案
|
|
LaTeX Lab 是工具箱中的核心子模块，不单独占用一级导航。工具箱不是零散功能集合，而是用户在数学人生和比赛之外进行数学表达、实验和练习的工作空间。
|
|
8.1 手写公式
|
|
- 支持鼠标、触控笔和触摸屏。
|
|
- 手写轨迹可撤销、重做和清空。
|
|
- 将手写内容识别为 LaTeX。
|
|
- 展示识别置信度和候选结果。
|
|
- 同步展示渲染效果。
|
|
- 支持复制、保存和继续编辑。
|
|
识别服务需要单独选型，可评估自建模型、Mathpix 或其他 API。正式选型前必须确认成本、隐私和可用性。
|
|
8.2 LaTeX 编辑器
|
|
- 左侧源码，右侧实时预览。
|
|
- 错误位置提示。
|
|
- 自动补全括号和常见命令。
|
|
- 支持矩阵、方程组和对齐环境。
|
|
- 支持导出 PNG、SVG 和源码。
|
|
- 自动保存草稿。
|
|
8.3 零基础教学
|
|
课程建议分层：
|
|
1. 上标、下标和基础运算。
|
|
2. 分式、根式和括号。
|
|
3. 求和、积分、极限。
|
|
4. 矩阵和方程组。
|
|
5. 多行公式与对齐。
|
|
6. 完整数学解答和证明排版。
|
|
每课包含：
|
|
- 概念说明。
|
|
- 可运行示例。
|
|
- 模仿输入。
|
|
- 自动判定。
|
|
- 常见错误解释。
|
|
8.4 LaTeX 表达挑战
|
|
- 根据公式图片输入 LaTeX。
|
|
- 根据自然语言要求构造公式。
|
|
- 修复错误公式。
|
|
- 按准确率和完成时间计分。
|
|
- 可作为 Contest 的独立主题赛。
|
|
|
|
---
|
|
9. 账号与“我的”
|
|
9.1 邀请码注册
|
|
首发流程：
|
|
输入邀请码
|
|
↓
|
|
设置邮箱或用户名、密码和昵称
|
|
↓
|
|
完成注册
|
|
↓
|
|
检测并迁移当前游客数据
|
|
需要支持：
|
|
- 单次邀请码。
|
|
- 批量邀请码。
|
|
- 有效期。
|
|
- 最大使用次数。
|
|
- 邀请码分组。
|
|
- 禁用和使用记录。
|
|
密码必须使用成熟密码哈希，不得明文存储。
|
|
9.2 游客数据迁移
|
|
注册前产生的以下数据应允许迁移：
|
|
- MathBTI 结果。
|
|
- 数学精灵。
|
|
- 已有卡牌。
|
|
- 剧情存档。
|
|
- 本地收藏。
|
|
迁移前应展示摘要，由用户确认。迁移完成后以服务端数据为准。
|
|
9.3 我的页面
|
|
首发必须可用：
|
|
- 昵称、头像和个人简介。
|
|
- 当前赛道、段位和 Rating。
|
|
- 连续参赛天数。
|
|
- 比赛历史和错题。
|
|
- LaTeX 学习进度。
|
|
- 我的公式。
|
|
- 收藏和浏览记录。
|
|
- 数学人物卡册。
|
|
- 密码修改。
|
|
- 登录设备和退出登录。
|
|
- 账号注销。
|
|
|
|
---
|
|
10. 管理后台
|
|
10.1 P0 后台能力
|
|
- 管理员登录和权限分级。
|
|
- 邀请码生成、导出、禁用和使用记录。
|
|
- 用户查询、封禁、解封和密码重置。
|
|
- MathBTI 题目、人格结果和推荐关系维护。
|
|
- 旗舰人生、章节、节点、选项、条件和效果维护。
|
|
- 人物、关系类型、剧本资源和结局维护。
|
|
- 人物 Skill 创建、校验、预览、发布和版本回滚。
|
|
- 剧本节点可达性、引用和存档兼容检查。
|
|
- 题目录入、批量导入、标签、难度和答案维护。
|
|
- 比赛组卷、预览、定时发布、撤回和结果查询。
|
|
- 排行榜异常成绩处理。
|
|
- 视频和知识卡片的创建、审核、上下架。
|
|
- LaTeX 课程和挑战题维护。
|
|
- 管理员操作审计。
|
|
10.2 数据看板
|
|
首发关注：
|
|
- 新增注册用户。
|
|
- 邀请码转化率。
|
|
- MathBTI 完成率和各人格分布。
|
|
- 数学人生开始率、章节完成率和主线完成率。
|
|
- 关键节点选项分布和退出节点。
|
|
- 人物 Skill 开始率、完成率和重玩率。
|
|
- 各结局达成率与关系变化。
|
|
- 今日 Contest 参与率和完成率。
|
|
- D1、D7 留存。
|
|
- 各赛道参与人数。
|
|
- 每题正确率和平均耗时。
|
|
- LaTeX Lab 使用率和课程完成率。
|
|
- AI 调用次数、失败率和成本。
|
|
|
|
---
|
|
11. 技术架构建议
|
|
11.1 已确认方案
|
|
Next.js Web
|
|
后续 Taro 小程序
|
|
│
|
|
▼
|
|
Django + Django REST Framework
|
|
├── Accounts
|
|
├── Math Life
|
|
├── Contest
|
|
├── Toolbox / LaTeX Lab
|
|
├── Content
|
|
├── Story
|
|
├── Progression
|
|
├── Engagement
|
|
└── AI Tutor
|
|
│
|
|
PostgreSQL + Redis + 对象存储
|
|
首期采用模块化单体，不拆微服务。
|
|
11.2 采用 Django 的原因
|
|
本项目生产版的核心需求集中在：
|
|
- 用户、权限和会话。
|
|
- 邀请码注册。
|
|
- 数据库模型和迁移。
|
|
- 题库与内容运营后台。
|
|
- 管理员权限与审计。
|
|
- 表单校验和安全默认值。
|
|
Django 可以直接提供这些基础能力。当前 Flask 代码作为重构期间的数据和行为参考，不再作为生产版目标架构继续扩展。
|
|
11.3 Django 模块化单体结构
|
|
目标工程结构建议为：
|
|
backend/
|
|
├── manage.py
|
|
├── config/
|
|
├── accounts/
|
|
├── math_life/
|
|
├── contest/
|
|
├── latex_lab/
|
|
├── content/
|
|
├── story/
|
|
├── progression/
|
|
├── engagement/
|
|
├── ai_tutor/
|
|
├── admin/
|
|
├── common/
|
|
└── tests/
|
|
每个业务模块拥有自己的模型、服务、API、后台配置和测试。跨模块写操作通过显式服务接口完成，不允许在视图层随意跨模块更新数据库。
|
|
11.4 实时比赛
|
|
- Django Channels 提供 WebSocket。
|
|
- Redis 作为 Channel Layer。
|
|
- 实时连接与普通 HTTP 可分别部署进程。
|
|
- ASGI 服务承载实时连接，普通 HTTP API 与 WebSocket 可以分别扩容。
|
|
- 实时比赛上线前必须完成独立压测、断线恢复和异常结算测试。
|
|
|
|
---
|
|
12. 后端模块边界
|
|
暂时无法在飞书文档外展示此内容
|
|
禁止模块绕过服务层随意修改其他模块的数据。
|
|
|
|
---
|
|
13. 核心数据模型
|
|
13.1 账号
|
|
- User
|
|
- UserProfile
|
|
- InviteCode
|
|
- InviteCodeUsage
|
|
- UserSession
|
|
- Role
|
|
- AuditLog
|
|
13.2 Contest
|
|
- Question
|
|
- QuestionVersion
|
|
- QuestionTag
|
|
- Contest
|
|
- ContestQuestion
|
|
- ContestAttempt
|
|
- ContestAnswer
|
|
- ContestScore
|
|
- RatingHistory
|
|
- LeaderboardSnapshot
|
|
- CheatFlag
|
|
题目修改后必须产生版本，历史比赛不能被新内容覆盖。
|
|
13.3 LaTeX Lab
|
|
- FormulaDocument
|
|
- FormulaRevision
|
|
- LatexCourse
|
|
- LatexLesson
|
|
- LatexExercise
|
|
- LatexAttempt
|
|
- HandwritingRecognitionJob
|
|
13.4 剧情与成长
|
|
- MathIdentity
|
|
- Story
|
|
- StoryVersion
|
|
- StoryChapter
|
|
- StoryNode
|
|
- StoryChoice
|
|
- StoryCondition
|
|
- StoryEffect
|
|
- StorySave
|
|
- StoryRun
|
|
- StoryEnding
|
|
- Character
|
|
- UserRelationship
|
|
- SkillPackage
|
|
- UserPet
|
|
- UserAbility
|
|
- Card
|
|
- UserCard
|
|
- RewardTransaction
|
|
存档必须绑定：
|
|
user_id + story_id + story_version
|
|
奖励和卡牌必须通过服务端事务发放。
|
|
旗舰人生和人物 Skill 必须共用同一套基础引擎及内容校验规则，但允许通过节点组件扩展各自的特殊玩法。剧本发布前需要自动检查：
|
|
- 起点和终点是否有效。
|
|
- 节点引用是否完整。
|
|
- 是否存在不可达节点。
|
|
- 条件和效果字段是否合法。
|
|
- 是否存在无法退出的意外循环。
|
|
- 使用的挑战、人物和资源是否存在。
|
|
- 新版本是否能够兼容或明确迁移旧存档。
|
|
|
|
---
|
|
14. API 与状态原则
|
|
- API 使用 /api/v1/ 版本前缀。
|
|
- 输入统一校验，错误返回统一结构。
|
|
- 所有写操作进行权限校验。
|
|
- 正式比赛提交需要幂等键。
|
|
- 列表接口默认分页。
|
|
- 服务端是用户数据的最终事实来源。
|
|
- localStorage 只用于游客临时数据、界面偏好和可失效缓存。
|
|
- 不允许客户端直接决定积分、Rating、奖励和抽卡结果。
|
|
- 前后端共享 OpenAPI 契约和生成类型。
|
|
|
|
---
|
|
15. 安全与合规
|
|
生产上线前最低要求：
|
|
- 所有密钥通过环境变量或密钥管理服务注入。
|
|
- 当前已暴露的 AI Key 立即吊销。
|
|
- 密码使用成熟密码哈希。
|
|
- 登录、注册、AI 和比赛接口具备限流。
|
|
- 管理后台启用强密码和双因素认证，条件允许时实施。
|
|
- 管理操作保留审计日志。
|
|
- 用户上传或输入内容进行长度、格式和安全校验。
|
|
- 禁止 eval 和动态执行用户输入。
|
|
- 为未成年人准备隐私政策和最小数据收集方案。
|
|
- 支持用户数据导出和账号注销。
|
|
- 视频、图片和文本维护版权来源与下架状态。
|
|
|
|
---
|
|
16. 可观测性与稳定性
|
|
16.1 日志
|
|
每个请求至少记录：
|
|
- Request ID
|
|
- 时间
|
|
- 路径和状态码
|
|
- 匿名化用户 ID
|
|
- 响应时间
|
|
- 错误类型
|
|
- 关键业务 ID
|
|
禁止记录密码、Token、完整 AI Key 和敏感个人信息。
|
|
16.2 监控
|
|
- API 请求量、错误率和 P95 延迟。
|
|
- PostgreSQL 连接与慢查询。
|
|
- Redis 状态。
|
|
- WebSocket 在线连接和断线率。
|
|
- Contest 提交成功率。
|
|
- AI 请求成功率、延迟和成本。
|
|
- 任务队列积压。
|
|
16.3 告警
|
|
- 5xx 错误率超过阈值。
|
|
- 登录或比赛提交连续失败。
|
|
- 数据库不可用。
|
|
- AI 成本异常增长。
|
|
- 部署健康检查失败。
|
|
- 实时连接大面积断开。
|
|
|
|
---
|
|
17. 测试要求
|
|
17.1 单元测试
|
|
重点覆盖：
|
|
- 邀请码有效性。
|
|
- 密码和权限。
|
|
- Contest 计分。
|
|
- Rating 变化。
|
|
- 排行榜排序。
|
|
- 题目版本。
|
|
- 奖励发放幂等性。
|
|
- MathBTI 评分。
|
|
- 剧情效果和存档版本。
|
|
- LaTeX 练习判定。
|
|
17.2 集成测试
|
|
- 注册、登录、退出和游客迁移。
|
|
- 后台发布题目和比赛。
|
|
- 实时匹配、统一发题、服务端判分和 Rating 结算。
|
|
- WebSocket 断线重连、超时和重复提交。
|
|
- 完整 Contest 作答流程。
|
|
- 收藏、历史和个人资料。
|
|
- AI 限流与异常降级。
|
|
- 数据库迁移。
|
|
17.3 E2E
|
|
最低覆盖：
|
|
1. 邀请码注册、完成 MathBTI 并进入推荐人生。
|
|
2. 完成一个关键选择，刷新页面后从正确节点继续。
|
|
3. 完成一段人物 Skill 并写入结局和五维成长。
|
|
4. 两个测试用户完成实时匹配、整场 1v1 和 Rating 结算。
|
|
5. 模拟一方断线并恢复，双方得到一致且唯一的比赛结果。
|
|
6. 完成今日异步挑战并查看成绩和排行榜。
|
|
7. 完成一节 LaTeX 课程并保存公式。
|
|
8. 修改个人资料并重新登录，确认身份、存档和记录仍存在。
|
|
9. 管理员创建、校验、预览并发布一个人物 Skill。
|
|
|
|
---
|
|
18. Gitea Action 与部署
|
|
18.1 现有部署的可复用部分
|
|
可以保留：
|
|
- PR 合并触发。
|
|
- SSH 到生产服务器。
|
|
- 服务器环境中的进程管理。
|
|
- 部署密钥和主机 Secrets。
|
|
不建议继续使用生产目录内 git reset --hard 后直接重载的方式作为最终方案。
|
|
18.2 第一阶段改造
|
|
PR 合并
|
|
↓
|
|
安装依赖
|
|
↓
|
|
静态检查与自动化测试
|
|
↓
|
|
SSH 到服务器
|
|
↓
|
|
备份数据库
|
|
↓
|
|
拉取版本
|
|
↓
|
|
执行数据库迁移
|
|
↓
|
|
收集静态资源
|
|
↓
|
|
重启应用
|
|
↓
|
|
检查 HTTP 与 WebSocket 健康状态
|
|
↓
|
|
健康检查
|
|
↓
|
|
失败则回滚
|
|
18.3 推荐最终形态
|
|
- CI 构建带版本号的 Docker 镜像。
|
|
- 镜像推送至私有 Registry。
|
|
- 服务器拉取指定版本。
|
|
- 数据库迁移作为独立步骤执行。
|
|
- HTTP API 和 ASGI WebSocket 服务分别执行健康检查。
|
|
- 应用通过健康检查后切换流量。
|
|
- 保留最近若干版本，可快速回滚。
|
|
18.4 环境
|
|
至少区分：
|
|
- Development
|
|
- Staging
|
|
- Production
|
|
生产数据库不能继续作为 Git 文件提交。
|
|
|
|
---
|
|
20. 首发范围建议
|
|
P0
|
|
- 邀请码注册和登录。
|
|
- 个性化首次引导。
|
|
- 行动导向首页。
|
|
- MathBTI 身份入口。
|
|
- 统一、可版本化的数学人生引擎。
|
|
- 约 2 小时的信仰者数学少年线。
|
|
- 隐藏信息选择、剧本内资源和人物关系。
|
|
- 剧情存档、结局和人生档案。
|
|
- 至少 2 个人物 Skill 样板。
|
|
- 五维能力、第一版数学精灵和人物卡沉淀。
|
|
- 实时 1v1 口算竞技。
|
|
- 服务端匹配、计时、判分、Rating 和比赛记录。
|
|
- WebSocket 断线恢复、异常结算和基础反作弊。
|
|
- 实时比赛排行榜。
|
|
- 可用的“我的”。
|
|
- 剧本、人物、Skill、用户、邀请码、题库和比赛后台。
|
|
- 监控、备份、健康检查和回滚。
|
|
P1
|
|
- 每日异步 Contest。
|
|
- 入门、标准、进阶三个赛道。
|
|
- 每日榜、周榜和邀请码小组榜。
|
|
- 比赛历史和基础错题记录。
|
|
- LaTeX 编辑器、模板库和首批课程。
|
|
- 单人闯关。
|
|
- 主题周赛。
|
|
- LaTeX 表达挑战。
|
|
- 手写识别。
|
|
P2
|
|
- 多人房间、淘汰赛和观战。
|
|
- 葫芦侠行迁移。
|
|
- 第二条旗舰人生线。
|
|
- 人物 Skill 内容生产工具。
|
|
- 好友榜和组队赛。
|
|
- 复杂赛季活动。
|
|
- 小程序客户端。
|
|
- 个性化推荐。
|
|
|
|
---
|
|
21. 生产验收标准
|
|
产品
|
|
- 新用户能在 60 秒内完成注册并进入 MathBTI 或第一条人生。
|
|
- 用户能在 3 次点击内继续上次的人生节点。
|
|
- 用户完成关键选择后，能理解故事变化，但不能提前看穿所有最优结果。
|
|
- 信仰者主线具备完整章节、关系、资源、挑战和多个有意义结局。
|
|
- 人物 Skill 可以在约 20 分钟内完成，并提供可回顾的人生路径。
|
|
- 两名在线用户能够完成匹配、实时作答、结算和 Rating 更新。
|
|
- 一名用户短暂断线后能够回到原比赛，且双方只产生一份一致赛果。
|
|
- 用户重新登录后，身份、存档、关系、结局、比赛和课程数据不丢失。
|
|
- 运营可以不修改业务代码发布剧本新版本和人物 Skill。
|
|
性能
|
|
- 常规网络下首页可交互时间不超过 2.5 秒。
|
|
- 普通 API P95 不超过 500ms，不含 AI 和手写识别。
|
|
- 正常负载下实时答题消息端到端 P95 延迟不超过 300ms。
|
|
- 有可匹配玩家时，实时 1v1 的 P95 匹配时间不超过 10 秒。
|
|
- Contest 提交成功率不低于 99.9%。
|
|
- 排行榜生成不阻塞正式成绩提交。
|
|
- 剧情选择保存成功率不低于 99.9%。
|
|
稳定性
|
|
- 部署失败可以自动终止并恢复上一版本。
|
|
- 数据库每日自动备份。
|
|
- 完成至少一次备份恢复演练。
|
|
- 关键错误能够通过监控告警发现。
|
|
- HTTP 与 WebSocket 服务均有独立健康检查和告警。
|
|
- Staging 环境通过全部核心 E2E 后才能发布。
|
|
安全
|
|
- 仓库中不存在生产密钥。
|
|
- 未登录用户不能读取或修改其他用户数据。
|
|
- 客户端不能直接修改正式分数、Rating 和奖励。
|
|
- 管理员操作可追溯。
|
|
|
|
---
|
|
22. 主要风险
|
|
暂时无法在飞书文档外展示此内容
|
|
|
|
---
|
|
23. 决策记录与剩余问题
|
|
23.1 已确认决策
|
|
1. 数学人生宇宙是生产版核心产品。
|
|
2. MathBTI、四条旗舰线、人物 Skill 包和跨剧本成长构成同一系统。
|
|
3. 信仰者数学少年线是首发旗舰内容。
|
|
4. 比赛模块以实时多人优先；首版限制为 1v1，异步赛同期或紧随上线。
|
|
5. 一级模块为：首页、数学人生、比赛、工具箱、探索发现、我的。
|
|
6. LaTeX Lab 属于工具箱的重点子模块。
|
|
7. 后端采用 Django 模块化单体。
|
|
8. 正式数据库采用 PostgreSQL。
|
|
23.2 首发前必须决策
|
|
1. 实时 1v1 与每日异步赛必须同一次公开发布。
|
|
2. 邀请码注册使用用户名加密码。
|
|
3. 实时比赛冷启动采用邀请码组内约战。
|
|
4. LaTeX 手写识别首版暂缓。
|
|
23.3 后续决策
|
|
1. 人生路线与结局图鉴的展示方式。
|
|
2. 五维能力如何从选择和挑战中增长。
|
|
3. 数学精灵与人生经历、Contest 奖励的具体关系。
|
|
4. 段位名称、赛季周期和 Rating 算法。
|
|
5. 是否提供学校或社团管理视图。
|
|
6. 小程序的启动时间。 |