01 已有原型提供了什么
两个系统已经证明了功能可实现，也沉淀了真实数据和规则。新 MVP 的任务是把它们变成一条家长愿意长期使用的手机端路径。
| 原型 | 已具备能力 | 可复用资产 | 需要改变 |
|---|---|---|---|
| 成绩追踪系统 | 考试增删改、七科成绩、总分、班级排名、趋势图 | 考试与成绩数据结构、趋势逻辑、真实使用经验 | 手工录入过重；JSON单文件不可扩展；界面不是手机家长场景 |
| 志愿预测系统 | 分数位次换算、学校数据、招生计划、定向名额、距离、志愿组合 | 学校与初中数据、位次表、规则算法、招生计划比较、志愿逻辑 | 一次性填报导向；输入参数较多；数据和逻辑都在前端，不利于迭代和审计 |
整合原则
保留成绩系统的“持续记录”，保留志愿系统的“学校与规则判断”，用家庭档案和预测服务把二者连接起来。前端不再保存核心算法和大体量数据。
02 MVP目标与边界
要验证的四个产品假设
H1
截图自动识别能把一次成绩录入时间压到30秒以内。
H2
家长愿意在初三阶段持续记录至少三次考试，而不是只体验一次。
H3
“当前学校层次 + 目标差距 + 变化解释”比单纯趋势图更有价值。
H4
基于孩子纵向数据的判断能够形成月度查看和分享行为。
MVP范围
| 模块 | 第一版 | 暂不进入第一版 |
|---|---|---|
| 家庭档案 | 孩子、城市、初中、年级、目标学校 | 多孩子、复杂家庭协作权限 |
| 成绩录入 | 截图识别、手工补充、确认后保存 | 批量导入、学校系统直连 |
| 成绩管理 | 考试列表、总分/排名/科目趋势、编辑删除 | 错题本、试卷逐题分析 |
| 升学判断 | 当前学校区间、目标差距、变化解释、可信度 | 确定性录取承诺、复杂志愿自动填报 |
| 学校信息 | 目标学校基础信息、历年门槛、招生计划 | 全面学校百科、家长社区 |
| 报告提醒 | 考试后即时解读、月度简报 | 全渠道消息中心、复杂营销自动化 |
03 核心用户流程
首版必须围绕一个高频动作设计：家长收到学校小程序或 App 的成绩通知后，立即截图并获得本次判断。
1. 上传截图从相册选择或直接拍摄成绩页面
2. 自动识别提取考试、科目、分数、排名和满分
3. 家长确认高亮低置信字段，允许一键修改
4. 保存分析计算趋势、位次区间和目标差距
5. 给出行动说明变化、相关学校和下阶段重点
不可省略确认步骤
成绩截图格式不统一，OCR或多模态模型一定会出错。系统只能辅助提取，不能在未经家长确认的情况下把识别结果写入正式成绩记录或进入预测模型。
04 功能需求与可验证标准
每项需求都以用户结果和验收条件描述，不以“做一个页面”作为完成标准。
FR-01 首次建档
| 需求 | 验收标准 | 优先级 |
|---|---|---|
| 家长通过手机号验证码登录。 | 新用户2分钟内完成登录与孩子建档；重复登录能恢复原数据。 | MVP |
| 填写孩子昵称、城市、所在初中、年级和目标学校。 | 城市和初中采用搜索选择；目标学校可跳过；必填项缺失时不能完成建档。 | MVP |
| 记录适用的考试总分和科目口径。 | 根据城市默认配置自动带出，家长可在录入时修正。 | MVP |
FR-02 截图录入成绩
| 需求 | 验收标准 | 异常处理 |
|---|---|---|
| 支持相册选择或拍照上传1至3张成绩截图。 | 单张不超过10MB；支持JPG、PNG、HEIC转码；上传后2秒内显示本地预览。 | 格式或大小不符时明确提示，不清空已填内容。 |
| 自动提取考试名称、日期、各科成绩、总分、班级/年级排名、参考人数。 | 典型样本字段识别准确率目标≥90%；每个字段返回置信度和来源截图位置。 | 未识别字段留空；冲突字段提示家长选择。 |
| 识别后进入确认页。 | 低置信字段醒目标记；家长可修改；确认前不写入正式成绩表。 | 识别失败时自动切换为简化手工录入。 |
| 支持不同学校、不同考试的科目和满分差异。 | 允许调整科目、分数和满分；总分自动重算；同一考试不能重复保存。 | 发现满分或总分异常时阻止提交并说明原因。 |
FR-03 考试记录与趋势
| 需求 | 验收标准 | 优先级 |
|---|---|---|
| 首页展示最近一次考试核心结果。 | 显示总分、排名、与上次变化、当前学校区间和目标差距；进入首页首屏可见。 | MVP |
| 查看总分、排名和各科趋势。 | 可在“总分/排名/科目”间切换；排名趋势采用名次越高图形越向上；缺失数据不补0。 | MVP |
| 查看、编辑、删除考试。 | 编辑后重新计算所有派生结果；删除需二次确认并保留审计记录。 | MVP |
FR-04 升学判断
| 需求 | 验收标准 | 解释要求 |
|---|---|---|
| 输出当前可达学校区间。 | 至少区分“冲刺、匹配、稳妥”三档；每次结果保存模型版本和数据版本。 | 必须显示依据、更新时间和可信等级。 |
| 输出目标学校差距。 | 用位次区间为主、分数差为辅；显示“当前区间、目标门槛、差距范围”。 | 边界样本必须提示对考试难度和政策变化敏感。 |
| 解释本次变化。 | 区分真实进步、正常波动、考试口径变化和数据不足；不得只根据总分涨跌下结论。 | 解释引用参与判断的考试和排名数据。 |
| 给出一条明确行动建议。 | 建议与数据相关，例如关注排名稳定性、补录年级排名或确认目标学校，不泛泛输出鸡汤。 | 大模型生成内容必须经过规则约束和敏感表述检查。 |
FR-05 学校与月度简报
| 需求 | 验收标准 | 优先级 |
|---|---|---|
| 目标学校信息页。 | 显示学校层次、性质、区域、历年位次、当年计划、与孩子当前差距；字段均带年份。 | MVP |
| 月度升学简报。 | 每自然月有两次以上考试时自动生成；包含本月变化、当前区间、目标差距和下月关注点。 | MVP |
| 政策相关提醒。 | 首版由运营配置规则，仅向命中城市、学校、资格或目标条件的家庭展示。 | 下一阶段 |
05 手机端信息与交互设计
首版采用底部四个入口，首页只回答“现在怎么样”，录入入口始终触手可及。
首页
最近一次考试
总分 515 年级 428
匹配：第二梯队高中
总分 515 年级 428
匹配：第二梯队高中
目标差距
距目标学校约 180–260 位
距目标学校约 180–260 位
本次判断
排名进步，仍需观察下一次考试
排名进步，仍需观察下一次考试
上传新成绩
上传成绩
选择截图 / 拍照
支持学校小程序、App、群通知截图
开始识别
确认识别结果
考试：三模
语文：92
数学：98?
年级排名：428
语文：92
数学：98?
年级排名：428
黄色字段置信度较低，请确认
确认并分析
分析结果
当前学校区间
冲刺 3 所｜匹配 5 所｜稳妥 4 所
冲刺 3 所｜匹配 5 所｜稳妥 4 所
为什么
近三次年级排名中位数改善 7%
近三次年级排名中位数改善 7%
下一步
补充参考人数可提高判断可信度
补充参考人数可提高判断可信度
底部导航
首页
最新状态、目标差距、相关提醒
成绩
考试列表、趋势、上传与编辑
学校
目标学校、学校区间与详情
我的
孩子档案、城市、目标与数据管理
交互指标
常用任务单手完成；核心按钮高度不低于44px；成绩确认不使用横向大表格；所有模型结论先给一句结论，再允许展开查看依据。
06 系统架构设计
采用模块化单体作为 MVP 起点：一个后端应用按领域分模块，共用数据库，但接口和职责提前分开。它比微服务开发快，同时保留后期拆分能力。
客户端
原生微信小程序运营管理后台CDN / 静态资源
接入层
Nginx / 负载均衡鉴权限流请求追踪
业务 API
家庭与用户考试成绩学校数据预测编排报告与提醒运营配置
异步任务
截图识别报告生成批量数据更新离线回测
算法与AI
规则引擎预测服务模型网关提示词与模板库模型评估
数据层
PostgreSQLRedis缓存/队列对象存储OSS日志与指标
建议技术栈
| 层 | MVP建议 | 选择理由 | 扩展方式 |
|---|---|---|---|
| 移动端 | 原生微信小程序 | 原生上传、扫码体验、家长常用入口、稳定的手机体验 | 复用统一 API 和业务模型；网页端后续作为运营后台 |
| 后端 | FastAPI 模块化单体 | 延续Python能力，适合数据与模型服务，接口定义清晰 | 无状态部署，多实例水平扩容；高负载模块可单独拆出 |
| 数据库 | PostgreSQL | 事务、结构化数据、JSON扩展、分析能力兼顾 | 读副本、分区、连接池；按城市与学年归档 |
| 文件 | 阿里云OSS | 截图不进入应用服务器磁盘，容量和并发独立扩展 | CDN、生命周期、自动删除原图 |
| 异步任务 | Redis + Worker | 截图识别和报告生成不阻塞用户请求 | 增加Worker数量；后期可切换托管消息队列 |
| 部署 | 容器化 + Nginx | 环境一致、可回滚、便于Codex维护 | 从单机Docker Compose升级到多实例或容器平台 |
为什么现在不做微服务
- MVP用户量和团队规模不足以抵消微服务的部署、监控和数据一致性成本。
- 通过模块边界、独立接口和异步任务，已经为后期拆分保留空间。
- 优先把复杂度留给数据质量和预测模型，而不是基础设施。
07 核心数据设计
正式数据与识别草稿必须分开；原始输入、确认数据、派生特征和预测结果必须可追溯。
| 实体 | 核心字段 | 设计要点 |
|---|---|---|
users | 手机号、状态、同意版本 | 手机号加密或脱敏存储；记录监护人授权 |
students | 用户、城市、初中、年级、入学年份 | 所有业务数据按学生隔离；预留多孩子 |
exam_records | 考试名称、日期、类型、总分、排名、参考人数 | 保存用户确认值；支持不同考试口径 |
exam_subject_scores | 科目、得分、满分、知识点标签 | 不把固定七科写死；适应城市和学年变化 |
upload_jobs | 文件、识别状态、原始结果、置信度 | 草稿与正式成绩分离；失败可重试；保留供应商信息 |
schools | 城市、名称、性质、层次、地址 | 稳定主数据，不按年份重复建学校 |
school_admission_years | 学校、年份、计划、录取分/位次、批次 | 所有易变化信息均带城市、年份、来源和发布时间 |
student_targets | 目标学校、优先级、建立时间 | 保留目标变化历史，不直接覆盖 |
prediction_runs | 输入快照、特征、模型版本、数据版本、结果 | 任何结论可重放、可解释、可回测 |
reports | 周期、结构化结论、展示文本、版本 | 结构化数据与大模型生成文案分离 |
数据版本规则
- 学校、招生计划、位次表、政策规则均包含
city_id、school_year、source_id和effective_at。 - 修订数据不覆盖历史版本；预测结果始终关联当时使用的数据版本。
- 原始截图默认短期保存，确认后的结构化数据长期保存；用户可申请删除。
08 预测算法与大模型接入设计
把AI拆成四条独立能力线，避免一个模型同时负责识别、计算、预测和解释。任何一条都可以单独升级或更换供应商。
信息抽取截图OCR、多模态识别、政策和学校资料结构化
输出字段、置信度和证据位置
输出字段、置信度和证据位置
确定性规则总分校验、位次映射、招生资格、批次和定向规则
代码化、可单元测试，不交给大模型
代码化、可单元测试，不交给大模型
统计预测孩子位次分布、学校门槛分布、情景模拟
版本化、可回测、输出区间
版本化、可回测、输出区间
解释生成把结构化结果转成家长能理解的结论和行动建议
受模板、规则和禁用表述约束
受模板、规则和禁用表述约束
统一模型网关
| 设计 | 要求 | 带来的能力 |
|---|---|---|
| 统一接口 | extract()、generate()、embed()按内部协议调用 | 业务代码不直接依赖某一家模型API |
| 供应商适配器 | 每家模型只在适配器中处理参数、鉴权和响应差异 | 可以切换OpenAI、通义、DeepSeek或本地模型 |
| 任务路由 | 按任务、成本、延迟、准确率选择模型 | 截图识别和报告解释可使用不同模型 |
| 降级策略 | 超时、限流或低置信时自动换模型或进入手工录入 | 单一供应商故障不阻断核心流程 |
| 提示词版本 | 提示词、结构化Schema、模型参数均有版本号 | 可灰度、回滚和A/B测试 |
| 调用审计 | 记录任务类型、版本、耗时、费用、成功率，不记录不必要隐私 | 持续优化成本和质量 |
预测模型的迭代路径
- M0 规则基线：历史位次、线差、招生计划变化和简单趋势，先建立可解释基线。
- M1 分层统计：按城市、初中、考试类型和分数段估计孩子中考位次区间。
- M2 概率模型：同时估计孩子位次分布与学校门槛分布，计算冲稳保概率区间。
- M3 个性化模型：使用跨届纵向样本、学校校准系数和更细粒度特征持续优化。
持续优化闭环
记录输入考试、排名、目标和当时数据版本
冻结预测中考前保存不可修改的预测快照
回收结果中考位次、志愿顺序和录取结果
离线评估覆盖率、误差、校准、滑档和后悔值
灰度升级新旧模型并行，达到门槛后切换
模型上线原则
新模型先作为 Challenger 在后台并行运行，不直接影响用户；只有在离线回测和小流量灰度均优于当前 Champion 后，才切换默认版本，并保留快速回滚能力。
09 性能、安全与可运维要求
性能与扩展目标
| 指标 | MVP验收值 | 扩展设计 |
|---|---|---|
| 普通API响应 | P95 ≤ 500ms，错误率 < 1% | 无状态API、多实例、数据库连接池和缓存 |
| 首页打开 | 4G网络下首屏可用 ≤ 2.5秒 | 静态资源CDN、接口聚合、按需加载 |
| 截图上传 | 显示上传进度；上传接口不阻塞识别 | 客户端直传OSS，服务端签名；异步Worker识别 |
| 截图识别 | 80%任务30秒内完成，超时可重试或手工录入 | 任务队列、幂等、Worker水平扩容、供应商降级 |
| 初期并发 | 100并发用户下核心API稳定 | 通过增加API与Worker实例扩展到更高并发 |
| 可用性 | 月可用性≥99.5% | 健康检查、自动重启、数据库备份和监控告警 |
安全与隐私
- 监护人明确同意后采集未成年人信息，默认最小化采集。
- 全站HTTPS；鉴权令牌短期有效；敏感字段加密或脱敏；对象存储使用私有桶和临时URL。
- 用户只能访问自己孩子的数据；运营后台采用角色权限和操作审计。
- 向大模型发送截图前进行最小化处理，能裁剪就不发送整屏；供应商调用不用于训练。
- 支持导出和删除家庭数据；原始截图设置自动过期策略。
监控与质量
系统指标
请求量、P95延迟、错误率、队列长度、数据库连接和存储失败。
产品指标
建档完成率、截图成功率、确认耗时、考试留存、报告查看和分享。
模型指标
字段准确率、人工修改率、模型费用、预测覆盖率、误差与概率校准。
10 MVP开发顺序
按可独立验收的纵向切片开发，优先完成一条真实可用路径，不先铺满所有页面。
| 阶段 | 交付内容 | 完成定义 |
|---|---|---|
| 迭代1 基础闭环 | 登录建档、手工录入、考试列表、首页最近结果 | 一个真实家庭能连续录入并在不同设备看到同一数据 |
| 迭代2 降低录入成本 | 截图上传、异步识别、确认页、识别质量记录 | 典型截图可完成“上传—确认—保存”，失败可降级手工 |
| 迭代3 体现产品思想 | 趋势、规则基线预测、当前学校区间、目标差距、解释 | 每次考试保存后自动形成一份有依据的个性化判断 |
| 迭代4 形成陪伴感 | 目标学校页、月度简报、分享、运营数据后台 | 家长可查看本月变化，项目方能观察留存与模型质量 |
| 迭代5 小规模验证 | 种子家庭灰度、数据修正、性能压测、隐私与备份 | 达到验收指标后再决定是否扩大用户和接入完整志愿系统 |
Codex使用方式
Codex承担代码实现、测试、数据迁移脚本、接口文档、部署和重复性数据处理；创始人集中负责产品判断、数据口径、家长访谈、模型验收和市场验证。
11 MVP总体验收清单
满足以下条件，才算第一版真正体现产品思路，而不是两个旧系统的移动版拼接。
- 录入 家长可通过截图完成成绩录入，识别后确认，典型流程中位耗时≤30秒。
- 持续 同一孩子可记录多次不同口径考试，趋势正确处理缺失科目和排名。
- 判断 首页明确展示当前学校区间、目标差距、本次变化和一条行动建议。
- 可信 每个预测结果包含依据、可信等级、模型版本、数据版本和更新时间。
- 移动端 390px宽度无页面溢出，核心操作可单手完成，关键按钮不小于44px。
- 性能 普通API P95≤500ms；100并发用户下核心流程稳定；识别任务不阻塞API。
- 可切换 大模型通过统一网关调用，更换识别或解释模型无需修改业务模块。
- 可迭代 预测运行可重放、回测、灰度和回滚，历史结论不因模型升级而被覆盖。
- 隐私 用户数据隔离，截图私有存储，具备监护人同意、导出和删除机制。
- 验证 首批种子家庭达到连续录入、报告查看和真实结果回收的预设指标。
开发前仍需确认的产品参数
- 第一批种子家庭数量及覆盖的初中、分数段。
- 西安首版考试科目、满分和排名口径配置。
- MVP默认使用的截图识别模型，以及可接受的单次识别成本。
- 首版“学校区间”和“目标差距”的规则基线具体口径。
- 月度简报的固定结构和家长可分享范围。