DEV_SPEC.md

开发规格说明（DEV_SPEC）

版本：1.0.0

1. 项目概述

面试复盘助手采用规范驱动（Spec-Driven）开发方式，在同一 profile_id 下关联简历与录屏资产，输出可执行、可追溯的复盘结果，而不是通用对话。

核心产出：

• 面经摘要与结构化问答
• 不足与改进方向
• 简历修改建议
• 模拟面试问题与追问链

2. 功能范围

2.1 v1 范围

• 本地候选人 profile 创建与读取
• 简历上传与解析（PDF）
• 录屏上传（MP4）
• 异步分析任务与阶段状态追踪
• 报告查询
• 简历建议查询
• 模拟面试题生成
• 基于回答生成追问

2.2 v1 不包含

• 实时 Copilot
• 连续视觉理解
• 表情/摄像头分析
• MCP 深度接入
• 题库图谱视图

3. 技术栈

3.1 后端

• FastAPI
• SQLAlchemy + SQLite
• Pydantic v2
• 本地文件存储
• 本地 worker 轮询 analysis_jobs

3.2 前端

• React + Vite
• React Router
• 与共享类型保持一致

3.3 共享

• packages/shared/src/types.ts 维护 DTO 对齐

4. 测试策略

4.1 单元测试

• 插件注册与选择
• 文件哈希幂等
• 说话轮次与 Q&A 结构化
• 证据链接生成
• 模拟题过滤

4.2 集成测试

• 上传 -> 任务 -> 报告闭环
• 简历与录屏基于 profile_id 关联
• Provider 回退行为

4.3 端到端

• 上传简历
• 上传录屏
• 轮询任务至完成
• 查询报告与简历建议
• 生成模拟题与追问

5. 架构与模块

5.1 核心实体

• CandidateProfile
• ResumeAsset
• RecordingAsset
• AnalysisJob
• TranscriptSegment
• InterviewTurn
• RetroReport
• ResumeSuggestion
• MockInterviewSession

适用实体均需带 profile_id。

5.2 插件协议

• LLMProvider
• ASRProvider
• OCRProvider
• ResumeParser
• FrameSampler
• QAStructurer
• ReportSynthesizer

5.3 流水线阶段

1. upload
2. transcribe
3. keyframes
4. ocr
5. structure
6. synthesize
7. link
8. mock_seed

状态：

• queued
• processing
• needs_retry
• completed
• failed

6. API 合约

• POST /api/v1/profiles
• GET /api/v1/profiles/current
• POST /api/v1/assets/resume
• POST /api/v1/assets/recordings
• GET /api/v1/jobs/{job_id}
• GET /api/v1/reports/{recording_id}
• GET /api/v1/reports/{recording_id}/notes
• POST /api/v1/mock-sessions/generate
• POST /api/v1/mock-sessions/{id}/followups

7. 里程碑

阶段 1：工程启动

• Monorepo 目录
• DEV_SPEC 与基础文档
• 后端骨架
• 前端骨架
• 共享类型

阶段 2：复盘 MVP

• 上传 API
• 异步 worker 与阶段更新
• 结构化报告模型
• 报告 API

阶段 3：资源关联闭环

• 简历解析与主题提取
• 简历建议关联
• 模拟面试生成
• 追问生成

阶段 4：开源发布

• Skills 骨架
• QA 基线
• setup/package 脚本
• 文档与架构图

8. 后续规划

• MCP 桥接
• 团队协作与多租户
• 长期面试成长记忆
• 主题图谱与间隔复习