EvoCode 需求分析（详细版）
AI Software Evolution Platform · 基于大模型的软件维护与演化平台
版本：v1.3 · 2026-08-10 · 状态：评审中
使用说明（灵活性声明）：本文档是需求纲要与基线，不是死规定。文档未覆盖、或与实际开发冲突时，具体情况具体分析——先记录决策（docs/decisions/AD-xxx.md + devlog），再合理调整，最后回填本文档。唯一硬约束：三端验证命令必须通过（见《开发规范》§10）。优先级 P0/P1/P2 是建议而非命令，可按论文需要微调。
目录
- 项目背景与问题定义
- 项目定位与竞品对比
- 目标用户与使用场景
- 系统边界与外部依赖
- 核心业务流程
- 功能需求（FR，按模块）
- 界面需求（页面级）
- 非功能需求（NFR）
- 数据需求
- 异常与边界场景
- 术语表
- 需求优先级与追溯矩阵
- MVP（v0.1）验收用例
1. 项目背景与问题定义
1.1 问题：软件必然腐化
一个软件项目上线半年后，普遍进入"维护困境"：
代码越来越多 → 设计原因被遗忘 → 新人不敢改 → Bug 增多
→ 技术债累积 → 局部打补丁 → 腐化加速 → 最终被迫重构
根因：对"软件现状"的认知成本随规模增长，而人力认知有限。传统工具只解决"怎么写代码"，不解决"怎么持续理解已经写出来的代码"。
1.2 机会：大模型可以低成本"读"代码
大模型具备：跨文件上下文理解、自然语言解释、结构化总结能力。将其与静态分析（确定性）结合，可以构建一个持续理解软件状态的系统。
1.3 系统目标
| 目标 |
说明 |
| 业务目标 |
让开发者 10 分钟内得到一份可信的"软件体检报告"，并持续跟踪健康变化 |
| 技术目标 |
证明"静态分析 + LLM 解释"的组合能产出比单一工具更有价值的诊断 |
| 研究目标（毕业设计） |
覆盖软件工程（维护/演化/质量/架构）与 AI（RAG/Agent/代码理解）双主线 |
1.4 成功标准
- 对 2 万行真实项目：10 分钟内完成分析，报告可读、风险可定位到文件
- 报告的 AI 建议中，>= 80% 被人工判定为"合理可执行"
- 二次分析能体现变化（技术债闭环、健康分对比）
2. 项目定位与竞品对比
2.1 定位
软件健康管理平台：扫描 → 分析 → AI 诊断 → 技术债闭环 → 演化跟踪。
不做代码生成，不做单次 review，做"持续理解与维护决策支持"。
2.2 竞品对比
| 产品 |
核心能力 |
与 EvoCode 差异 |
结论 |
| Cursor / Copilot |
AI 生成代码 |
关注"写"；EvoCode 关注"维护已有系统" |
互补，不竞争 |
| SonarQube |
静态扫描（规则驱动） |
是 EvoCode 的扫描引擎之一；EvoCode 在其上补 AI 解释与闭环 |
集成而非竞争 |
| CodeScene |
演化分析（变更频率、认知复杂度） |
最接近的竞品；但无中文、无 AI 对话式诊断、面向大企业 |
差异化：教学/中小团队 + AI 解释 + 中文 |
| CodeRabbit |
AI PR review |
单 PR 粒度；EvoCode 是项目级、跨时间维度的健康管理 |
互补 |
| Snyk / Dependabot |
依赖漏洞扫描 |
只覆盖依赖维度；EvoCode 依赖风险只是子模块 |
子集 |
| DeepSource / CodeClimate |
质量门禁 |
规则驱动，无"为什么"的解释与演化叙事 |
差异化在 AI 解释 |
2.3 差异化总结（一句话卖点）
"SonarQube 告诉你哪里脏，EvoCode 告诉你为什么脏、怎么收拾、什么时候会再脏。"
3. 目标用户与使用场景
3.1 角色画像
| 角色 |
画像 |
核心诉求 |
| 团队负责人 王强 |
带 5 人团队维护 3 个老项目 |
健康总览、技术债优先级、重构 ROI |
| 老开发者 李工 |
接手 5 年老系统 |
定位风险模块、获得可执行重构方案 |
| 新人 小陈 |
入职 2 周 |
架构图 + 文档 + 演化历史快速上手 |
| 答辩评审老师 |
评估毕业设计 |
软件工程完整度 + AI 能力真实性 |
3.2 使用场景
- 场景 A（每周体检）：王强每周一跑一次分析，对比健康分变化，决定本周技术债排期
- 场景 B（接手项目）：李工导入新项目，先看架构图，再问 AI 医生"最应该先改什么"
- 场景 C（新人入职）：小陈直接看生成的 README/架构文档，比翻代码快
- 场景 D（答辩演示）：离线也能跑通（规则版报告降级），保证演示不翻车
4. 系统边界与外部依赖
4.1 系统边界
[用户] --Web UI--> | 前端 Vue3 |
| 后端 Spring Boot（业务/任务编排/持久化）|
| Python Analyzer（扫描/质量/架构/演化/AI）|
| PostgreSQL(pgvector) | Redis | 磁盘代码库 |
外部: LLM API(OpenAI 兼容) · GitHub · SonarQube
4.2 外部依赖清单
| 依赖 |
用途 |
失效影响 |
容错 |
| LLM API（DeepSeek/OpenAI/Ollama） |
报告/解释/聊天 |
报告降级为规则版 |
必须容错（核心设计） |
| GitHub |
clone 公开仓库 |
无法创建 git 项目 |
zip 上传兜底 |
| SonarQube（自部署） |
质量扫描 |
质量维度显示不可用 |
其余维度不受影响 |
| Docker（开发环境） |
本地基础设施 |
无法启动 dev 环境 |
提供手动安装文档 |
5. 核心业务流程
5.1 主流程（泳道式）
用户 前端 后端 Analyzer
| 上传zip/GitHub | | |
|--------------->| POST /projects | |
| |--------------->| 解压/clone、校验 |
| | | 建档(项目档案) |
| 发起分析 | POST /analyses | |
|--------------->|--------------->| 建任务(PENDING) |
| | | 异步执行 |
| | 轮询状态 <---| 调 /analyze/scan |
| |<--------------|----------------->| 扫描/语言/技术栈
| | | 调 /analyze/report|
| | |----------------->| LLM 诊断(或降级)
| | SUCCEEDED | 写报告/更新档案 |
| 查看报告 | GET /report <--| |
|--------------->|--------------->| |
5.2 技术债闭环流程
分析器自动生成 issue(OPEN)
→ 人工评审: 处理(DOING) / 忽略(WONTFIX, 必须填原因)
→ 处理完成: DONE(填验证说明)
→ 下次分析: 若问题消失自动关联"已解决"备注，否则提示复发
5.3 AI 医生问答流程
用户提问 → 组装上下文(项目摘要+最近报告+相关知识块+会话历史)
→ 检索(向量相似度+关键词) topK=8 知识块
→ LLM 生成(流式) → 返回带引用 [file:line]
→ 引用可点击 → 跳转文件详情/Monaco 预览
6. 功能需求（FR，按模块）
优先级：P0 = MVP 必须 · P1 = v0.2-v0.3 · P2 = v0.4-v1.0
FR 汇总表（44 条索引）
| ID |
模块 |
功能 |
优先级 |
实现阶段 |
| FR-1.1 ~ 1.7 |
M1 项目管理 |
zip 上传 / GitHub 克隆 / 档案 / 列表 / 详情 / 删除 / 重新分析 |
P0 |
P1 |
| FR-2.1 ~ 2.6 |
M2 代码理解 |
项目地图 / 忽略规则 / 语言识别 / 技术栈识别 / 保护机制 / 快照对比 |
P0 |
P1 |
| FR-3.1 ~ 3.4 |
M3 依赖分析 |
解析 / 版本风险 / 清单页 / AI 升级建议 |
P1 |
P3 |
| FR-4.1 ~ 4.5 |
M4 代码质量 |
Sonar 集成 / 指标页 / issue+AI 解释 / 质量门禁 / 降级 |
P1 |
P3 |
| FR-5.1 ~ 5.5 |
M5 架构分析 |
节点 / 关系 / 分层违规 / 可视化 / 架构报告 |
P2 |
P4 |
| FR-6.1 ~ 6.6 |
M6 AI 医生 |
会话 / 上下文组装 / 引用溯源 / 流式 / 防御规则 / 快捷提问 |
P2 |
P6 |
| FR-7.1 ~ 7.4 |
M7 技术债 |
自动生成 / 字段 / 状态机 / 列表看板 |
P2 |
P7 |
| FR-8.1 ~ 8.4 |
M8 演化分析 |
Git 统计 / 热点判定 / 可视化 / 前置要求 |
P2 |
P5 |
| FR-9.1 ~ 9.4 |
M9 文档生成 |
README / 架构 / API / 管理 |
P2 |
P7 |
M1 项目管理中心（P0）
| ID |
功能点 |
详细规则 |
验收要点 |
| FR-1.1 |
创建项目（zip 上传） |
支持拖拽/选择；校验：扩展名 .zip、大小 ≤200MB、解压后 ≤500MB、文件数 ≤5 万；逐文件校验路径（拒绝 ../、绝对路径、符号链接、隐藏文件外泄）；若 zip 内只有单层目录则自动上移一层作为项目根 |
恶意 zip 被拒且服务不崩溃 |
| FR-1.2 |
创建项目（GitHub 地址） |
支持 https://github.com/owner/repo；校验格式与仓库存在性；git clone --depth 1（默认）与全量 clone（配置项，供演化分析用）；超时 5 分钟；失败返回原因（不存在/私有/网络） |
无效地址返回明确错误 |
| FR-1.3 |
项目档案 |
字段：名称、描述、来源、语言占比、框架标签、LOC、文件数、最近分析时间、创建时间；创建后 3 分钟内完成档案识别（快扫） |
上传即见档案 |
| FR-1.4 |
项目列表 |
分页、按名称搜索、按语言/状态筛选、按最近分析时间排序 |
20 个项目内响应 <1s |
| FR-1.5 |
项目详情 |
档案 + 各分析结果 Tab 入口 |
— |
| FR-1.6 |
删除项目 |
级联：分析记录、报告、文件快照、依赖、issue、聊天、文档 + 磁盘代码目录 + 向量块；删除前二次确认 |
删除后磁盘与库内无残留 |
| FR-1.7 |
发起/重新分析 |
同一项目同一时刻仅允许 1 个运行中任务；可查看历史任务与结果 |
重复点击被拒绝并提示 |
M2 代码理解引擎（P0，全项目基础）
| ID |
功能点 |
详细规则 |
| FR-2.1 |
项目地图 |
文件树（含目录层级）；每文件：路径、语言、LOC、大小；支持按语言/路径过滤；前端虚拟滚动（>5000 节点） |
| FR-2.2 |
忽略规则 |
目录：node_modules .git dist target build __pycache__ venv .venv .idea .vscode .next out coverage；文件：.lock package-lock.json yarn.lock *.min.js *.map；隐藏文件仅保留 .github 等白名单；支持 .evocodeignore 自定义（用户根目录） |
| FR-2.3 |
语言识别 |
后缀 + 首行 shebang + 内容启发式；统计占比；未知语言归为 OTHER；优先级表：Java/Python/TypeScript/JavaScript/Go/Vue/HTML/CSS/SQL/Shell 等 |
| FR-2.4 |
技术栈识别 |
依据清单文件：pom.xml(Maven/Spring Boot 版本)、build.gradle、package.json(Vue/React/Next/Electron)、requirements.txt/pyproject.toml、go.mod、composer.json；依据目录结构：src/main/java(后端分层)、docker-compose.yml(部署)、*.sql(数据库)；输出标签数组：["Vue","Electron","Spring Boot","MySQL"] |
| FR-2.5 |
保护机制 |
单文件 >2MB 跳过（计数并在报告中说明）；扫描总超时 10 分钟；进程内存上限保护 |
| FR-2.6 |
扫描快照 |
每次分析记录文件清单（file_node），支持前后两次对比（新增/删除/变化文件） |
M3 依赖分析（P1）
| ID |
功能点 |
详细规则 |
| FR-3.1 |
依赖解析 |
解析 pom.xml / package.json / requirements.txt / pyproject.toml / go.mod（树状递归，pom 解析 parent/依赖树） |
| FR-3.2 |
版本风险 |
内置常用框架 EOL 规则表（Spring Boot 2.5 EOL、Node 14 EOL 等，约 30 条，后续可扩展 API）；大版本落后检测（当前 vs 最新 major）；直接/间接依赖风险标记 |
| FR-3.3 |
依赖清单页 |
名称、生态、当前版本、最新版本、风险等级（LOW/MEDIUM/HIGH）、原因、升级建议；按风险排序；支持标记"已评估" |
| FR-3.4 |
依赖 AI 建议 |
对 HIGH 风险依赖：LLM 给出升级路径与兼容性风险说明 |
M4 代码质量分析（P1）
| ID |
功能点 |
详细规则 |
| FR-4.1 |
SonarQube 集成 |
docker-compose 起 sonarqube(社区版)；后端调 analyzer 触发 sonar-scanner；获取指标：Bugs、漏洞、代码异味、重复率、覆盖率、复杂度；扫描完成回调 |
| FR-4.2 |
指标页面 |
指标卡片 + 雷达图 + 各维度星级；与上次分析对比（↑↓） |
| FR-4.3 |
Issue 列表与 AI 解释 |
每条 issue：severity、类型(BUG/VULN/SMELL)、规则、文件、行号、消息；AI 解释（异步、可点"重新解释"）：为什么是问题（结合该文件上下文） + 怎么改（具体到拆分/提取/命名） + 参考片段 |
| FR-4.4 |
质量门禁（可选） |
配置阈值（如 Critical 数 > 0 则健康分降级），供报告引用 |
| FR-4.5 |
降级 |
SonarQube 未启动时：质量维度显示"不可用"，其他维度正常 |
M5 架构分析（P2，差异化核心）
| ID |
功能点 |
详细规则 |
| FR-5.1 |
节点提取 |
按语言解析：Java(类/接口)、Python(模块/类)、TS/JS(模块/导出类)、Go(package)；节点类型：CONTROLLER/SERVICE/REPOSITORY/MAPPER/ENTITY/UTIL/MODULE/OTHER |
| FR-5.2 |
关系提取 |
tree-sitter 解析符号引用 → CALL（方法调用）/ IMPORT（导入依赖）；跨文件解析，去重 |
| FR-5.3 |
分层规则 |
内置分层定义（Java: Controller→Service→Repository/Mapper→Entity；Python: view→service→model）；违规检测：跨层调用（Controller 直调 Repository）、实体被 Controller 直接操作、循环依赖（A↔B）、上帝类（>N 依赖） |
| FR-5.4 |
架构可视化 |
ECharts 关系图：节点按类型着色、按耦合度放大；违规边标红并可点击查看详情；支持节点搜索、缩放、布局（力导向/层级） |
| FR-5.5 |
架构报告 |
每个违规：说明 + 影响 + 建议；AI 补充"该违规在业务上可能带来的维护成本" |
M6 AI 软件医生（P2，核心卖点）
| ID |
功能点 |
详细规则 |
| FR-6.1 |
会话管理 |
每项目多个会话；会话标题自动生成；历史保留 |
| FR-6.2 |
上下文组装 |
系统级：项目摘要（语言/框架/LOC/结构）+ 最近报告摘要 + 架构摘要；用户级：问题；检索级：向量检索 topK 知识块（切片按函数/类，≤800 token/块，带路径与符号元数据）；可选注入：指定文件全文（用户主动@文件） |
| FR-6.3 |
引用与溯源 |
回答中涉及代码必须带 [文件路径:行号]；前端引用卡片可点击 → 打开 Monaco 预览该文件该行 |
| FR-6.4 |
流式输出 |
SSE 流式；中断可停止；失败提示重试 |
| FR-6.5 |
防御规则 |
不做的事：不改代码、不执行代码、不泄露其他项目数据（权限隔离）；无法判断时明确说"不知道"，禁止编造文件路径 |
| FR-6.6 |
快捷提问 |
预置问题："为什么这个项目难维护""最应该先重构什么""User 模块的风险是什么" |
M7 技术债管理（P2）
| ID |
功能点 |
详细规则 |
| FR-7.1 |
自动生成 issue |
来源：架构违规(ARCH)、质量规则(QUALITY)、依赖风险(DEPEND)、演化热点(EVOLUTION)、AI 医生建议（用户手动转）；自动去重（同文件同规则同项目） |
| FR-7.2 |
Issue 字段 |
标题、等级(HIGH/MEDIUM/LOW)、来源、详情、建议、状态、关联分析、创建/解决时间 |
| FR-7.3 |
状态机 |
OPEN → DOING → DONE（填验证说明）；OPEN → WONTFIX（必填原因）；下次分析自动复查：已 DONE 的问题若复发自动重新 OPEN |
| FR-7.4 |
列表与看板 |
按等级/状态/来源筛选；看板视图（按状态列） |
M8 版本演化分析（P2）
| ID |
功能点 |
详细规则 |
| FR-8.1 |
Git 统计 |
git log --numstat：增删行、文件数、作者、时间；按周/月聚合趋势；Top 变动文件；作者活跃度 |
| FR-8.2 |
热点判定 |
规则：变动频率高 + 耦合度高 + 缺陷多的文件 → 风险热点；AI 输出"风险中心"判断与说明（必须引用统计数据） |
| FR-8.3 |
可视化 |
增删折线图、Top 文件柱状图、作者贡献饼图；点击文件 → 该文件变更时间线 |
| FR-8.4 |
要求 |
git 项目需要全量 clone（配置项 FR-1.2）；zip 项目该模块显示"不可用" |
M9 自动生成文档（P2）
| ID |
功能点 |
详细规则 |
| FR-9.1 |
README |
项目简介、技术栈、模块结构、快速开始（基于分析结果） |
| FR-9.2 |
架构文档 |
模块关系、分层说明、关键流程、部署方式（基于架构分析结果） |
| FR-9.3 |
API 文档 |
控制器/路由清单：方法、路径、入参出参、说明（基于解析结果） |
| FR-9.4 |
文档管理 |
Markdown 渲染预览、复制、下载；版本记录；可手动编辑后保存（标注"已人工修改"） |
跨模块关键业务规则（口径统一，避免实现打架）
| 规则 |
口径 |
| 健康分 |
0-100 整数；规则基础分 + LLM 修正（±10，须给理由）；分维度：质量/结构/依赖/规模（完整公式见《开发指导》§10） |
| 分析并发 |
同一项目同时仅 1 个运行中任务；全系统并发 ≤3；超出的排队（任务状态为 PENDING） |
| 分析历史 |
默认全量保留；v1 提供"保留最近 N 次"清理配置（默认 50） |
| 技术债去重键 |
(project_id, source, rule_key 或 标题归一化)；同键自动去重并更新时间戳 |
| 技术债自动生成条件 |
架构违规（HIGH 或 MEDIUM 且影响模块数≥2）、依赖 HIGH、质量 CRITICAL+、演化风险分≥阈值；生成的 issue 必须可定位（有文件/有规则） |
| AI 解释重试 |
单条解释超时 30s，失败重试 1 次，再失败标 FAILED 可手动"重新解释"；不阻塞页面 |
| 数据保留 |
项目删除 = 级联全清（表 + 磁盘 + 向量块）；分析结果随项目，不做独立导出归档 |
| 权限 |
v1.0 前单用户，无登录；所有接口不做鉴权（仅本地部署），代码留鉴权扩展点 |
| 报告来源标注 |
每个报告必须携带 source（LLM / RULES / 混合），前端对规则版显示横幅，避免误导 |
| 语言支持判定 |
完整支持（解析+分析）：Java/Python/TS/JS/Go/Vue；基础支持：其余常见文本语言；未识别归 OTHER |
页面清单汇总
| 页面 |
路由 |
优先级 |
| 项目列表 |
/projects |
P0 |
| 创建项目（弹窗/独立页） |
/projects/new |
P0 |
| 项目详情-Overview |
/projects/:id/overview |
P0 |
| 报告页 |
/projects/:id/report/:analysisId |
P0 |
| 架构 |
/projects/:id/architecture |
P2 |
| 质量 |
/projects/:id/quality |
P1 |
| 技术债 |
/projects/:id/tech-debt |
P2 |
| 演化 |
/projects/:id/evolution |
P2 |
| AI 医生 |
/projects/:id/doctor |
P2 |
| 文档 |
/projects/:id/docs |
P2 |
| 全局 Dashboard |
/dashboard |
P2 |
7. 界面需求（页面级）
7.1 项目列表页
- 元素：搜索框、语言筛选、状态标签、创建按钮、项目卡片（名称/语言占比条/框架标签/LOC/最近分析时间/健康分徽章）
- 交互：卡片点击进详情；空态引导创建；分页
- 状态：加载骨架屏；错误重试
7.2 创建项目
- zip：拖拽区 + 文件选择；上传进度；解压校验错误提示（文件过大/路径非法）
- GitHub：URL 输入 + 校验提示 + 克隆进度（阶段文案）
- 成功后跳转详情页并提示"档案识别中"
7.3 项目详情 Overview
- 档案卡：语言占比条（堆叠）、框架标签、LOC/文件数、来源、最近分析时间
- 最近分析卡：健康分环形图、维度星级、风险 Top5、报告入口
- 操作：发起分析按钮（进行中显示进度条 + 当前阶段文案，如"正在扫描…3/7"）
7.4 报告页
- 顶部：健康分大数字 + 等级徽章 + 维度雷达图
- 中部：摘要段落 + 风险清单（等级筛选、点击展开详情与引用文件）
- 底部：分阶段建议（第一阶段/第二阶段/第三阶段卡片）
- 操作：导出 Markdown、重新生成（AI）
7.5 架构页
- 图例（节点类型色块）；工具栏（布局切换、搜索、全屏）；违规列表侧栏（点击高亮对应边）
7.6 质量页
- 指标卡（Bugs/漏洞/异味/重复/覆盖率/复杂度）+ 与上次对比箭头
- Issue 表格（severity 色点、类型、文件）；点击行 → 抽屉：消息 + AI 解释（加载态/失败重试）+ 原文片段
7.7 技术债页
- 看板（Open/Doing/Done/Wontfix 四列）+ 表格视图切换；新建（AI 转）与编辑弹窗
7.8 演化页
- 趋势折线（增/删/提交数）、Top 文件柱状、作者饼图；风险中心卡片（AI 判断）
7.9 AI 医生页
- 左侧会话列表（新建/删除）；右侧消息流（用户/助手气泡，助手带引用卡片）；输入框（快捷问题、@文件）；流式打字机效果；底部"当前上下文"指示（引用了几份报告/多少知识块）
7.10 文档页
- 左侧类型切换（README/架构/API）；右侧 Markdown 渲染；复制/下载/编辑（编辑后标注）
7.11 全局
- 顶部导航：Dashboard / 项目
- 统一空态、加载态、错误态组件；深浅色主题可选（P7）
- 页面骨架 ≤ 1s 可见首屏
8. 非功能需求（NFR）
8.1 性能（量化预算）
| 指标 |
预算 |
说明 |
| 2 万行项目全量扫描 |
≤10 分钟 |
不含 LLM 时间，含 Sonar |
| LLM 报告生成 |
≤120s |
含 2 次重试预算 |
| 单次 AI 解释 |
≤30s |
异步队列，不阻塞页面 |
| 列表页响应 |
≤1s（20 条内） |
后端分页 |
| 前端首屏 |
≤3s |
路由懒加载 |
| 并发分析任务 |
3 个 |
超出的排队（数据库状态） |
| 轮询间隔 |
2s |
后端幂等只返回变化 |
8.2 安全
- 静态分析，绝不执行被分析代码；解析器无
eval/exec/shell 拼接（git log 例外，参数经白名单校验）
- zip 解压：逐文件路径校验（
..、绝对路径、符号链接）；大小与文件数上限
- 上传文件仅存本地磁盘指定目录（
data/projects/{id}），权限最小化
- 服务端口绑定：内部 API 仅
127.0.0.1；数据库不对外
- 密钥（LLM Key 等）仅服务端环境变量；日志脱敏
8.3 可用性
- LLM 不可用 → 规则版报告降级（核心设计，演示保障）
- Sonar 不可用 → 质量维度 N/A
- 分析任务失败 → 明确错误信息 + 可重试；部分阶段成功也保存已得结果
- 服务重启后：运行中任务标记为 FAILED("服务重启中断")，可重新发起
8.4 兼容性
| 维度 |
范围 |
| 语言 |
完整支持：Java、Python、TypeScript、JavaScript、Go、Vue；基础支持：HTML/CSS/SQL/Shell/XML/YAML/JSON/Markdown |
| 操作系统 |
Windows / macOS / Linux（开发以 Windows 为主，部署脚本兼容三端） |
| 浏览器 |
Chrome / Edge 最近 2 个大版本 |
8.5 可维护性与可扩展性
- 三端职责分离，analyzer 契约化（pydantic schema 为唯一事实来源）
- LLM 可插拔（OpenAI 兼容协议）
- 分析任务异步化，可平滑升级为 Redis 队列
- 向量库 pgvector，避免额外中间件
8.6 隐私
- 默认只发送"结构化摘要"（文件清单/LOC/规则命中/受限片段）给 LLM
- "全文发送"为显式开关（设置页，默认关）
- 项目数据不出服务器磁盘；无外部遥测
9. 数据需求
| 类别 |
内容 |
存储位置 |
| 业务数据 |
项目/分析/报告/依赖/质量/架构/技术债/演化/聊天/文档/向量块 |
PostgreSQL |
| 代码文件 |
上传的原始项目（解压后） |
磁盘 data/projects/{id} |
| 配置 |
应用配置、LLM 配置、EOL 规则表、忽略规则 |
配置目录 + DB（可编辑项） |
| 日志 |
三端运行日志（按天滚动，保留 14 天） |
磁盘 logs/ |
| 演示素材 |
截图、报告导出 |
docs/screenshots、下载目录 |
10. 异常与边界场景
| 场景 |
系统行为 |
| zip 损坏/空/非 zip |
明确报错，不创建项目 |
解压含 ../ 等恶意路径 |
拒绝整个 zip，记录安全日志 |
| GitHub 地址不存在/私有/网络超时 |
分别返回明确错误；允许转 zip 上传 |
| 分析中删除项目 |
任务标记 CANCELLED，资源释放 |
| LLM 超时/返回非 JSON |
重试 2 次 → 降级规则版报告并标注"规则版" |
| 大文件（>2MB） |
跳过统计 LOC，报告注明数量 |
| 扫描超时 |
保存已完成部分，报告标注"部分扫描" |
| 项目无任何源代码 |
档案为空，报告提示"疑似无源码" |
| 中文/Unicode 文件名 |
全程 UTF-8；路径处理用绝对路径 API |
| 重复上传同一 zip |
正常创建新项目（不自动去重） |
| 磁盘空间不足 |
上传前检查剩余空间，不足时拒绝并提示 |
11. 术语表
| 术语 |
定义 |
| LOC |
Lines of Code，代码行数（不含空行注释） |
| 技术债 |
为短期收益牺牲长期质量的代码问题的统称 |
| 代码异味 Code Smell |
结构上暗示深层问题的写法（如超长方法） |
| EOL |
End of Life，官方停止支持 |
| 健康分 |
系统综合评分（0-100），见开发指导 §10 |
| 分析任务 |
一次完整分析（可含多阶段） |
| 项目地图 |
项目文件树 + 每文件规模信息 |
| RAG |
检索增强生成：先检索相关代码片段再生成回答 |
| Embedding |
文本向量化表示 |
| 知识块 |
代码切片（函数/类级），RAG 检索单元 |
| 风险中心 |
演化分析中高频变更且耦合高的模块 |
| 规则版报告 |
无 LLM 时的模板化降级报告 |
| Analyzer |
Python 分析服务（系统内部服务） |
12. 需求优先级与追溯矩阵
| 用户故事 |
覆盖模块 |
需求 |
阶段 |
优先级 |
| US-1 |
M1+M2 |
FR-1.x + FR-2.1~2.4 |
P1 |
P0 |
| US-2 |
M2 |
FR-2.1~2.6 |
P1 |
P0 |
| US-3 |
M3+M4+M5+报告 |
FR-3/4/5 + 报告页 |
P2-P4 |
P1 |
| US-4 |
M5 |
FR-5.x |
P4 |
P2 |
| US-5 |
M6 |
FR-6.x |
P6 |
P2 |
| US-6 |
M7 |
FR-7.x |
P7 |
P2 |
| US-7 |
M8 |
FR-8.x |
P5 |
P2 |
| US-8 |
M9 |
FR-9.x |
P7 |
P2 |
| 跨项目总览 |
Dashboard |
— |
P7 |
P2 |
阶段 → 内容映射：P0 脚手架 / P1 项目+扫描 / P2 AI 报告（v0.1 完成） / P3 质量 / P4 架构 / P5 演化 / P6 AI 医生 / P7 技术债+文档+Dashboard（v1.0 完成）
FR-6.3（引用预览）依赖文件内容读取接口 GET /projects/{id}/files/content（契约见《开发指导》§6.1），实现顺序与 P6 同步。
13. MVP（v0.1）验收用例
前置：docker compose 起基础设施；准备 2 万行示例项目（如 Chatez）
| # |
用例 |
步骤 |
预期 |
通过条件 |
| AC-1 |
zip 创建项目 |
上传 Chatez.zip |
档案 3 分钟内生成：语言占比、框架标签、LOC、文件数 |
字段非空且与人工统计误差 <10% |
| AC-2 |
GitHub 创建项目 |
输入公开仓库地址 |
克隆成功并生成档案 |
无报错 |
| AC-3 |
发起并跟踪分析 |
发起 FULL 分析 |
状态 PENDING→RUNNING→SUCCEEDED，进度单调递增 |
轮询正常，无跳变 |
| AC-4 |
报告内容 |
查看报告 |
健康分+等级、技术栈、项目地图、风险清单（≥3 条且指向具体文件）、分阶段建议 |
全部存在且可读 |
| AC-5 |
性能 |
计时全流程 |
扫描 ≤10 分钟；LLM 报告 ≤120s |
达标 |
| AC-6 |
无 Key 降级 |
不配置 LLM Key 重跑 |
仍出"规则版"报告，标注来源 |
流程不断 |
| AC-7 |
重复分析 |
连续发起 2 次 |
数据按 analysis_id 隔离，不堆积、不串数据 |
两次报告可分别查看 |
| AC-8 |
恶意 zip |
构造含 ../evil 的 zip 上传 |
拒绝并提示，服务不崩溃 |
无异常日志 |
| AC-9 |
删除项目 |
删除后检查磁盘与库 |
目录 data/projects/{id} 删除，相关记录清零 |
grep 无残留 |
| AC-10 |
大文件保护 |
放入 5MB 单文件 |
跳过并统计，报告注明（实现阈值 scan_max_file_bytes 默认 2MB，5MB 样本必命中跳过逻辑） |
扫描不卡死 |
| AC-11 |
空项目 |
上传无源码 zip |
提示"疑似无源码"（判定：scan fileCount==0），不报错 |
正常提示 |
| AC-12 |
断网演示 |
断外网重跑分析 |
扫描正常，报告为规则版 |
演示可全程离线（除 Sonar 维度） |
AC 与阶段映射（门禁）
| 阶段 |
必须通过的 AC |
说明 |
| P1（项目+扫描） |
AC-1、AC-2、AC-8、AC-10、AC-11 |
档案与安全基础 |
| P2（v0.1 完成） |
AC-3、AC-4、AC-5、AC-6、AC-7、AC-9、AC-12 |
全量 12 条 |
| 每阶段回归 |
AC-1、AC-3、AC-5、AC-6、AC-7、AC-8、AC-9 |
高频冒烟 7 项（防回归，与 02 §13 / 08 口径一致） |
14. 需求变更与演进管理
14.1 变更流程
新需求/变更 → 判断是否进本期：
是 → 更新 FR 编号内容（标注版本）+ 追溯矩阵 + 验收用例 → 影响评估（阶段/工时）→ 记录 devlog
否 → 进 backlog（docs/backlog.md）→ 下期评审
14.2 变更原则
- v0.1 需求在 P1 启动时冻结（验收 AC-1~12 不变），冻结后只允许文档级修正
- P3+ 允许小范围变更，但必须满足：不改变既有表结构/契约字段的语义（破坏性变更走新版本字段）
- 需求"裁剪"与"增加"同等记录——论文里能体现需求管理能力
- 每个变更在文档右下角版本历史登记：
v1.x 变更：xxx
14.3 版本历史
| 版本 |
日期 |
变更 |
| v1.0 |
2026-08-10 |
初稿：9 大模块 + MVP 方向 |
| v1.2 |
2026-08-10 |
细化到 FR 级（44 条）、界面需求、NFR 量化、12 条验收用例 |
| v1.3 |
2026-08-10 |
增加 FR 汇总表、跨模块业务规则口径、AC-阶段映射、变更管理流程、灵活性声明 |