EvoCode 模块详细设计（实现级）¶
定位：《04-架构设计》的"实现级说明书"——逐模块给出边界、核心算法、数据模型与接口规范。 配套：《06-API契约》为接口唯一契约来源（本文只做模块↔端点映射）；《07-数据字典》为表结构唯一事实源（本文标注各模块涉及表）；《08-测试计划》为用例级验证（本文标注各模块对应测试分组）。 版本：v1.0 · 2026-08-11 · 覆盖三端全部功能模块（P0~P8 已实现）
1. 模块总览与依赖矩阵¶
1.1 三端模块地图¶
┌─ frontend（Vue3 + TS + Vite + ECharts）─────────────────────────────┐
│ views: dashboard / project-list / project-create / project-detail │
│ └─ detail 内: report / quality / architecture / evolution / │
│ doctor / tech-debt / doc 七个区块 │
│ api/* (axios + SSE 客户端) → types/api.ts → stores → components │
└──────────────────────────────┬──────────────────────────────────────┘
│ /api/v1（REST + SSE）
┌─ backend（Spring Boot 3, Java 17）──────────────────────────────────┐
│ controller ──► service ──► mapper ──► PostgreSQL │
│ │ │ └─ entity（16 表映射） │
│ │ └─ AnalyzerClient ──► analyzer（内部 HTTP） │
│ 模块：project / analysis(编排) / scan / quality / architecture / │
│ evolution / chat / debt / doc / common / config │
└──────────────────────────────┬──────────────────────────────────────┘
│ /analyze/v1（仅 127.0.0.1）
┌─ analyzer（Python 3.12, FastAPI）───────────────────────────────────┐
│ core: filescanner / sonar / arch(tree-sitter) / evolution(git) / │
│ reportgen+report_rules / rag / docgen / llm / prompts │
│ schemas.py = 契约唯一事实源 │
└──────────────────────────────┬──────────────────────────────────────┘
│
PostgreSQL(pgvector) · Redis(预留) · 磁盘代码库 data/ · LLM API
1.2 模块依赖矩阵（backend 视角）¶
| 依赖方 | 依赖目标 | 方式 |
|---|---|---|
| AnalysisRunner（编排） | AnalyzerClient / FileNodeService / QualityIssueService / ArchitectureService / EvolutionService / TechDebtService | Spring 注入，串行编排 |
| ProjectService | UploadService / GitCloneService / FileNodeService | 委托 |
| ChatService | AnalyzerClient（SSE 透传） | HTTP 流式 |
| DocService | AnalyzerClient（/doc 同步调用） | HTTP |
| DebtController | TechDebtService | 分页查询 + 状态机 |
| analyzer 各 core | schemas.py（纯数据结构，无反向依赖） | import |
| analyzer core/rag | core/llm + PG(pgvector) | 直连 |
| frontend views | api/*（axios） | HTTP / SSE |
1.3 防腐边界（继承《04》§3.1）¶
- D-4：backend 只经
AnalyzerClient + 契约 DTO访问 analyzer，禁止依赖其实现细节。 - D-5：LLM 出口唯一在 analyzer；backend 永不直连 LLM（含 /chat SSE 透传）。
- D-1：controller 不直接依赖 mapper / entity（统一走 service + DTO）。
- 数据单向流：
frontend → backend → analyzer → PG/磁盘/LLM；backend 是唯一业务状态持有者。
2. backend 模块¶
包根：
com.evocode（backend/src/main/java/com/evocode/），下同节内路径省略前缀。
2.1 项目管理模块（project）¶
文件：controller/ProjectController.java、service/project/{ProjectService,ProjectServiceImpl,UploadService,UploadServiceImpl,GitCloneService,GitCloneServiceImpl,GitExecutor,ProcessGitExecutor}.java
模块边界
- 拥有：项目档案 CRUD、zip 上传解压（含安全校验）、GitHub 克隆、磁盘目录管理（data/projects/{id}/）、删除级联入口。
- 不拥有：代码解析、质量扫描（全在 analyzer）；任务编排（见 2.2）。
核心算法
- zip 安全上传（T-U-05/06/07，对应 AC-8）：白名单路径校验（common/util/PathSafetyUtil.java）→ 拒绝 ../、绝对路径、符号链接；大小上限 200MB / 解压 500MB；单层目录自动上移（zip 内仅一层目录时把该层作为项目根）。
- 克隆（T-U-23~26，对应 AC-2）：GitExecutor 白名单参数透传（cloneDepth 支持 depth=0 全量）→ subprocess 调用系统 git → 超时 5min → 退出码 128 映射 2009「不存在或为私有」。
- 删除级联（T-U-20/21）：任务 CANCELLED 等待退出 → 各表按 FK 清理 → 磁盘目录删除（幂等）。
数据模型（《07》§3.1~3.3）：project、analysis（本模块建 + 删除，运行态属 2.2）。
接口映射（《06》§3.1~3.2）：GET/POST /api/v1/projects、GET/PATCH/DELETE /api/v1/projects/{id}（P9b 将新增 PATCH 重命名与报告导出）。
测试：《08》T-U-05/06/07/20/21/22/23/24/25/26；T-I-01a/04/05/06/13/14。
2.2 分析任务编排模块（analysis）¶
文件：controller/AnalysisController.java、service/analysis/{AnalysisService,AnalysisServiceImpl,AnalysisRunner,AnalyzerClient,QuickScanService}.java、enums/{AnalysisStatus,AnalysisType,Stage}.java
模块边界 - 拥有：任务生命周期状态机、幂等/并发控制、异步执行编排（FULL 与 QUICK_SCAN 两条流水线）、analyzer 内部 HTTP 客户端（含错误码映射与降级）、历史报告查询与 regenerate。 - 不拥有：任何分析算法本身。
核心算法
- 任务状态机（《06》§3.6）：PENDING(QUEUED,0) → RUNNING(SCAN,5→60) → SCAN_DONE(70) → RUNNING(REPORT,75→95) → SUCCEEDED(DONE,100)；失败 → FAILED；删除 → CANCELLED。非法转移拒绝（T-U-03）。
- 并发幂等：同项目已有 RUNNING/SCAN_DONE 任务时拒绝新任务（错误码 2002）；regenerate 期间重复触发 2008（T-U-02/04）。
- FULL 编排顺序（AnalysisRunner.run，实测 12 分钟内）：
scan → replaceSnapshot(file_node) → 更新档案(lang_stats/framework_tags/loc_total)
→ runQuality（Sonar 可用→issues 落库+metrics 返回；不可用→null 降级）
→ runArchitecture（失败降级不阻塞报告）
→ runEvolution（失败降级不阻塞报告）
→ generateAndStoreReport（LLM 优先，analyzer 内部降级 RULES）
→ techDebtService.rebuildForAnalysis（四源聚合，失败仅 warn 不阻塞）
file_node 快照重建 scan 摘要，仅重跑 REPORT 阶段（T-I-08）。
- AnalyzerClient 错误映射（T-U-08/09）：analyzer 不可达 → 3001；LLM_NO_KEY → 触发降级路径而非异常。
数据模型：analysis（《07》§3.2）、file_node（快照，经 FileNodeService）。
接口映射：POST /api/v1/projects/{id}/analyses、GET /api/v1/analyses/{id}（含 status/stage/progress）、GET /api/v1/analyses/{id}/report、POST /api/v1/analyses/{id}/report/regenerate、GET /api/v1/projects/{id}/analyses（历史分页）。
测试：《08》T-U-01~04/08~12、T-I-01b/02/08/11/12、T-C-01。
2.3 扫描快照模块（scan / file_node）¶
文件：service/scan/FileNodeService.java、dto/scan/*
模块边界
- 拥有：file_node 快照的幂等重建、按 project/analysis 查询、供报告与文件地图读取。
- 数据来源：analyzer /analyze/v1/scan 结果（只读消费）。
核心算法
- 快照重建（T-U-16）：同 analysis_id 二次写入先删后插，避免堆积；快扫（QUICK_SCAN）时替换 project 最新快照。
- 文件地图：目录树聚合（供 GET /projects/{id}/files 与前端文件面板）。
数据模型：file_node（《07》§3.3，含 path/language/loc/sizeBytes）。
接口映射：GET /api/v1/projects/{id}/files、GET /api/v1/projects/{id}/files/content（内容读取，越权/超限拦截 2005，T-U-17/18）。
测试：《08》T-U-16/17/18、T-A-01~06（analyzer 侧）、T-I-07/14。
2.4 质量模块（quality）¶
文件：controller/QualityController.java、service/quality/{QualityIssueService,QualityIssueServiceImpl}.java、dto/quality/*、entity/QualityIssue.java
模块边界
- 拥有：quality_issue 查询/筛选/分页、metrics 聚合、AI 解释（explain）触发与落库。
- 不拥有：Sonar 扫描本身（analyzer core/sonar.py）。
核心算法
- severity 过滤：BLOCKER/CRITICAL 等进入技术债聚合（见 2.8）；列表接口支持按 severity/type 筛选。
- AI 解释（P3）：质量 issue 的 ai_suggestion / ai_note 由 analyzer /analyze/v1/explain 生成（异步，不阻塞主流程）。
数据模型：quality_issue（《07》§3.5，含 severity/message/type/ai_suggestion/ai_note）。
接口映射：GET /api/v1/projects/{id}/quality-issues、GET /api/v1/quality-issues/{id}/explain。
测试：《08》T-U-09~12、T-A-09/10/13/15、T-I-03。
2.5 架构模块（architecture）¶
文件：controller/ArchitectureController.java、service/{ArchitectureService,ArchitectureServiceImpl}.java、entity/{ArchitectureNode,ArchitectureEdge,ArchViolation}.java
模块边界
- 拥有：架构节点/边/违规的落库查询；analysisId 缺省取最新；无数据 → 404/2010。
- 不拥有：tree-sitter 解析（analyzer core/arch/*）。
核心算法
- 数据装配：从 architecture_node / architecture_edge / arch_violation 三表按 analysis_id 组装 ArchitectureResp（节点含 nodeType/language、边含调用方向、违规含 severity/description/suggestion）。
- 空态语义：available=false（与演化一致），前端显示空态而非报错。
数据模型：architecture_node、architecture_edge、arch_violation（《07》§3.6~3.8）。
接口映射：GET /api/v1/projects/{id}/architecture。
测试：《08》T-A-11/12/18、T-P-05（3000+ 节点 ≤3s）、T-I-01b。
2.6 演化模块（evolution）¶
文件：controller/EvolutionController.java、service/{EvolutionService,EvolutionServiceImpl}.java、entity/{CommitStat,FileChangeStat,Hotspot}.java
模块边界
- 拥有：commit_stat / file_change_stat / hotspot 查询；range 参数校验（30d/90d/180d/all）；非 Git/无数据 → available=false（非 404）。
- 不拥有：git log 解析（analyzer core/evolution/gitlog.py，subprocess 调系统 git）。
核心算法 - rangeDays 校验：白名单（30/90/180/0），非法 → 1002。 - 热点聚合：从 hotspot 表取 riskLevel=HIGH/MEDIUM 的模块热点，供技术债聚合（2.8）与前端风险卡片。
数据模型：commit_stat、file_change_stat、hotspot（《07》§3.9~3.10、§3.16）。
接口映射：GET /api/v1/projects/{id}/evolution?range=30d。
测试：《08》T-A-14、T-U-15 相关、T-I-12。
2.7 AI 医生模块（chat + RAG）¶
文件：controller/ChatController.java、service/chat/{ChatService,ChatServiceImpl,ChatStreamer}.java、entity/{ChatSession,ChatMessage}.java、mapper/KnowledgeChunkMapper.java
模块边界
- 拥有：会话 CRUD（逻辑删除 @TableLogic）、消息分页、SSE 透传（SseEmitter）、防重发（2007）、标题自动生成。
- 不拥有：RAG 检索、LLM 生成（analyzer core/rag/* + core/llm.py）。
核心算法
- SSE 透传（《06》§4）：backend ChatStreamer 用 JDK HttpClient 流式读 analyzer /analyze/v1/chat，delta/citations/done/error 事件原样转发；断线重发不重复落库（T-I-10）；LLM_NO_KEY → 落库 error 事件 + 前端横幅（T-I-03）。
- 防重发：同 content 2s 内重发 → 2007（T-U-19）。
- 标题生成：首条消息后 AI 生成（截断 ≤200 字符）。
数据模型：chat_session、chat_message（citations jsonb）、knowledge_chunk（《07》§3.13~3.15）。
接口映射：GET/POST /api/v1/projects/{id}/chats、GET/DELETE /api/v1/chats/{id}、GET /api/v1/chats/{id}/messages、POST /api/v1/chats/{id}/messages（SSE 响应）。
测试：《08》T-U-19、T-I-09/10、T-C-03、T-S-04。
2.8 技术债模块（debt）¶
文件：controller/DebtController.java、service/debt/{TechDebtService,TechDebtServiceImpl}.java、entity/TechDebt.java
模块边界 - 拥有：技术债四源聚合（重建）、列表分页筛选、状态机流转、复发复查。 - 不拥有：任何分析算法（纯消费 arch/quality/evolution/hotspot/report 的库内产物）。
核心算法（技术债识别与量化）
- 四源聚合（rebuildForAnalysis，P7a）：分析完成后全量重建（按 project_id 删除后重插，避免残留旧 analysis 引用）：
| 源 | 输入 | 判定 | level 映射 |
|---|---|---|---|
| ARCH | arch_violation | severity ∈ {HIGH, MEDIUM} | 原样 |
| QUALITY | quality_issue | severity ∈ {BLOCKER, CRITICAL} | BLOCKER→HIGH，CRITICAL→MEDIUM |
| EVOLUTION | hotspot | riskLevel = HIGH | HIGH |
| DEPEND | report.risks | title 匹配 EOL\|依赖\|版本\|升级 | normalize(risk.level) |
- 状态机：OPEN → DOING/DONE/WONTFIX、DOING → DONE；DONE 必填 resolve_note、WONTFIX 必填 wonfix_reason（2011/2012）；关闭记 resolved_at。
- 复发复查（T-U-15）：DONE 后新分析仍命中 → 重新 OPEN。
数据模型：tech_debt（《07》§3.11，含 source/level/status/ref_analysis_id）。
接口映射：GET /api/v1/projects/{id}/tech-debts（分页+status 筛选）、POST /api/v1/tech-debts/{id}/status。
测试：《08》T-U-13/14/15、T-C-02、T-I-01b。
技术债的管理策略（识别分类、量化评估、优先级排序、短中长期计划）见《10-技术债管理方案.md》； 监控机制与质量指标体系见《11-技术债监控与质量指标体系.md》。
2.9 文档模块（doc）¶
文件：controller/DocController.java、service/doc/{DocService,DocServiceImpl}.java、entity/GeneratedDoc.java
模块边界
- 拥有：文档列表/生成/编辑（版本递增）/删除；docType 白名单（README/ARCH/API）。
- 不拥有：Markdown 生成（analyzer core/docgen.py，后端同步调用并落库 upsert）。
核心算法
- 版本控制：version 从 1 起，每次生成/编辑 +1；人工编辑置 edited=true（区分 AI 原文）。
- 降级语义：LLM_NO_KEY → 400（带 code）；LLM_FAILED → 502（3004 映射）。
数据模型：generated_doc（《07》§3.12）。
接口映射：GET /api/v1/projects/{id}/docs、POST /api/v1/projects/{id}/docs/{docType}/generate、POST /api/v1/docs/{id}/edit。
测试：《08》T-C-02、T-I-01b；doc 表格 XSS 已转义（P6-P8 审查修复）。
2.10 公共层（common / config / entity / mapper / dto / enums）¶
文件：common/{BusinessException,ErrorCode,GlobalExceptionHandler,PageResultResp,Result}.java、common/util/PathSafetyUtil.java、config/*、entity/*（16 实体）、mapper/*（16 Mapper）、enums/*
核心机制
- 统一返回：Result{code,message,data} + ErrorCode 全表（《06》§2.2，2004 预留除外，T-C-02）。
- 全局异常：GlobalExceptionHandler 把 BusinessException/参数错误/兜底映射为统一错误码，SSE 场景特殊透传。
- MyBatis Plus：@TableLogic 逻辑删除（chat_session/chat_message 等）；PG 类型适配：PgJsonbTypeHandler（jsonb）、PgStringArrayTypeHandler（varchar[]）。
- 线程池：AsyncConfig 定义 quickScanExecutor（异步分析执行）。
- PathSafetyUtil：内容读取/上传的路径白名单核心（T-U-22，含符号链接）。
3. analyzer 模块¶
包根：
analyzer/app/；schemas.py是全部契约字段的唯一事实源（T-C-01 与 backend DTO 反射比对）。
3.1 扫描管线（filescanner / ignore / langdetect / loc / stackdetect）¶
文件：core/{filescanner,ignore,langdetect,loc,stackdetect}.py
模块边界：纯函数式扫描，输出 ScanResult（语言占比/LOC/框架/前后端判定/文件清单）。
核心算法
- ignore 规则（T-A-01/02）：默认忽略 node_modules/.git/dist 等 + .evocodeignore 自定义（支持 ! 取反）。
- 语言识别（T-A-03/04）：20+ 后缀映射 + Dockerfile 文件名匹配；未知 → OTHER。
- LOC 统计（T-A-05）：空行/注释/shebang 不计。
- 大文件保护（T-A-06）：> scan_max_file_bytes（默认 2MB）跳过并计数 skippedBigFiles，不崩溃。
- 技术栈识别（T-A-07/08）：pom.xml / package.json 等 → frameworks + hasBackend/hasFrontend + dbHint。
数据模型：ScanResult / ScanFile（schemas.py）；落库 file_node、project.lang_stats/framework_tags/loc_total/file_count/ignored_count。
接口：POST /analyze/v1/scan（写 {projectId}.status.json 供后端轮询）。
测试：《08》T-A-01~08、T-I-14。
3.2 质量扫描（sonar）¶
文件：core/sonar.py
模块边界：SonarQube 客户端（可用性探测 + sonar-scanner 执行 + CE 轮询 + 指标/issues 归一化）；不可用 → 200 + metrics.available=false（降级 N/A，非错误）。
核心算法（T-A-13）
- 可用性三条件：token / host / scanner 可执行。
- 指标映射：bugs / vulnerabilities / codeSmells / duplicationRate / coverageRate / complexity。
- issues 归一化为 QualityIssue（含 severity/type/message）。
数据模型：quality_issue（落库由 backend 完成）。
接口：POST /analyze/v1/quality。
测试：《08》T-A-13、T-I-03。
3.3 架构解析（arch）¶
文件：core/arch/{base,java_parser,python_parser,archscan}.py
模块边界：tree-sitter 解析 Python/Java → 符号节点、调用边、分层违规；未知语言 → 空结果降级（T-A-12）。
核心算法（T-A-11）
- 节点提取：类/方法/函数等顶层符号 + 文件归属。
- 调用边：解析调用表达式 → source → target 边。
- 分层违规：按预定义分层（如 controller/service/mapper）检测反向调用/跨层依赖 → ArchViolation（severity/description/suggestion）。
- 出入度指标：每节点 fan-in/fan-out（前端 hover 展示）。
数据模型：ArchNode/ArchEdge/ArchViolation（schemas.py）→ 落库三表。
接口：POST /analyze/v1/architecture。
测试：《08》T-A-11/12/18、T-P-05。
3.4 演化统计（evolution）¶
文件：core/evolution/gitlog.py
模块边界：subprocess 调系统 git（不引 Python git 库）；非 git 目录 → available=false。
核心算法（T-A-14）
- git log 解析（增删行/文件/作者/时间），防 git 参数注入（T-S-06 白名单）。
- 周聚合趋势、TOP 变更文件、作者占比。
- 规则热点：按文件变更频次/规模阈值标记 Hotspot(riskLevel=HIGH/MEDIUM, evidence, aiConclusion)。
数据模型：EvolutionResult（schemas.py）→ 落库 commit_stat/file_change_stat/hotspot。
接口：POST /analyze/v1/evolution（rangeDays 透传）。
测试：《08》T-A-14、T-S-06。
3.5 报告生成（reportgen / report_rules / llm / prompts）¶
文件：core/{reportgen,report_rules,llm,prompts}.py
模块边界：健康报告生成，LLM 优先 + 规则版降级（source=RULES，HTTP 仍 200）。
核心算法（健康分模型，即《02》§10 评分模型落地）
healthScore = round(quality×0.4 + structure×0.3 + dependency×0.15 + scale×0.15)
round(score/20) 封顶 5。
- 规则版附加 scoreDetail 记录各子分（可解释、可复现）。
- LLM 版（llm.py）：OpenAI 兼容客户端，JSON 输出清洗（去 ```json 围栏，T-A-16）、重试、LLM_NO_KEY 抛错→调用方降级。
数据模型：ReportResponse{source,promptVersion,report}（report 含 health_score/level/summary/dimensions/risks/recommendations/score_detail）→ backend 存 analysis.report_json/report_source/prompt_version。
接口：POST /analyze/v1/report。
测试：《08》T-A-15/16/17、T-U-10/11/12、T-I-03、T-P-02（≤120s）。
3.6 RAG 服务（rag）¶
文件：core/rag/{chunker,vectorstore,service}.py
模块边界：代码知识索引与检索；PG 未配/宕机 → index stored=false（200）、search 503、chat 兜底话术。
核心算法
- 切片（chunker.py，T-A 相关）：tree-sitter 顶层符号（函数/类/方法）为单元，≤800 token（内置估算器 _MAX_TOKENS=800，见 tokenizer.py，TD-10）；超长符号按 ≤400 token 窗口滑切（overlap 50 token）；不支持语言/无符号文件 → 整文件单块兜底（symbol=None）。
- 索引（service.index）：切片 → embedding（默认 bge-m3，失败降级 NULL）→ 写 knowledge_chunk（项目级全量重建，随 analysis）。
- 检索（service.search）：向量 cosine（pgvector HNSW）+ 关键词 LIKE 合并去重（P6 实测多关键词空结果已修）。
- 对话（service.chat）：检索 → 引用 [path:line] 校验防幻觉（无命中集合则剔除）→ SSE 生成（D.6 prompt，temperature 0.7，history ≤ 最近若干轮）。
数据模型：knowledge_chunk（《07》§3.15，vector(1024)+HNSW）。
接口：POST /analyze/v1/rag/index、POST /analyze/v1/rag/search、POST /analyze/v1/chat（SSE）。
测试：《08》T-I-09/10、T-C-03、T-S-04、T-P-04。
3.7 文档生成（docgen）¶
文件：core/docgen.py（prompt 见 core/prompts.py D.7）
模块边界：三类文档（README/架构/API）Markdown 生成；API 文档从 controller 源码正则提取端点。
核心算法：docType 白名单校验（400）→ LLM 生成（无 key → LLM_NO_KEY 400；失败 → 502）→ backend 落库版本递增。
数据模型：DocRequest/DocResponse（schemas.py）→ 落库 generated_doc。
接口：POST /analyze/v1/doc。
测试：《08》T-C-02、T-I-01b；XSS 已转义（P7 审查）。
3.8 契约层（schemas）¶
文件：schemas.py
职责：全部内/外契约 Pydantic 模型；model_json_schema() 供契约测试导出（T-C-01 与 Java DTO 反射比对，允许后端多字段）。任何字段变更必须先改这里（《04》设计原则 2）。
4. frontend 模块¶
文件：frontend/src/（views / api / types / router / styles）
4.1 页面与区块¶
| 页面/区块 | 文件 | 数据源接口 | 关键行为 |
|---|---|---|---|
| Dashboard | views/dashboard/index.vue |
/projects（聚合复用） |
统计卡 + ECharts（健康分布/语言构成/状态分布）+ 最近分析 |
| 项目列表 | views/project-list/index.vue |
GET /projects |
卡片/列表切换、筛选、状态点、删除确认 |
| 项目创建 | views/project-create/index.vue |
POST /projects（zip/GitHub） |
双入口 + 上传进度 |
| 详情-报告 | views/project-detail/index.vue |
/analyses/{id}/report |
健康分环 + 维度星级 + 风险/建议 + 分析历史 |
| 详情-质量 | project-detail/quality 区块 |
/quality-issues |
severity 色标、metrics 徽章、AI 解释 |
| 详情-架构 | views/project-detail/architecture-view.vue |
/architecture |
ECharts 分层图（nodeType 5 层）+ 违规表 |
| 详情-演化 | views/project-detail/evolution-view.vue |
/evolution?range= |
提交趋势折线 + TOP 文件条 + 作者环形 + 热点卡 |
| 详情-AI 医生 | views/project-detail/doctor-view.vue |
SSE /chats/{id}/messages |
流式渲染 + 引用卡（Monaco 定位行号）+ 会话列表 |
| 详情-技术债 | views/project-detail/tech-debt-view.vue |
/tech-debts |
severity/source/status 徽章 + 筛选 + 处理弹窗 |
| 详情-文档 | views/project-detail/doc-view.vue |
/docs |
三 tab（README/ARCH/API）+ 轻量安全 Markdown 渲染 + 编辑 |
4.2 公共机制¶
- api/request.ts：axios 封装，统一错误码处理、非 2xx 丢失业务 code 修复（P4c）、防重复请求。
- api/chat.ts：fetch + ReadableStream 逐行解析 SSE（断线无 done → CONNECTION_LOST 提示，P6-P8 修复）。
- styles/variables.css：设计 token 双主题（
[data-theme='dark']），35+ 色值收编；前端types/api.ts与后端 DTO 对齐（契约测试辅助）。 - 路由
router/index.ts；导航在App.vue（Dashboard/项目 + 一键主题切换，localStorage 持久化）。
5. 核心算法汇总表¶
| 算法 | 模块 | 公式/规则 | 引用 |
|---|---|---|---|
| 健康分 | analyzer report_rules | quality×0.4 + structure×0.3 + dependency×0.15 + scale×0.15 |
《02》§10、《09》§3.5 |
| 任务状态机 | backend analysis | PENDING→RUNNING(SCAN)→SCAN_DONE→RUNNING(REPORT)→SUCCEEDED | 《06》§3.6 |
| 技术债聚合 | backend debt | 四源（ARCH/QUALITY/EVOLUTION/DEPEND）全量重建 | 《09》§2.8、《10》 |
| 技术债状态机 | backend debt | OPEN→DOING/DONE/WONTFIX、DOING→DONE | 《06》§3.12 |
| RAG 切片 | analyzer rag | tree-sitter 符号 ≤800 token；≤400 token 窗滑切 overlap 50 | 《09》§3.6 |
| RAG 检索 | analyzer rag | 向量 cosine + 关键词 LIKE 合并去重 | 《06》§5.8 |
| 架构解析 | analyzer arch | tree-sitter 节点/调用边/分层违规/出入度 | 《09》§3.3 |
| 演化热点 | analyzer evolution | git log 聚合 + 文件变更频次/规模阈值 | 《09》§3.4 |
| 扫描保护 | analyzer filescanner | >2MB 跳过计数；.evocodeignore；截断保护 | 《09》§3.1 |
| 降级链 | 三端 | LLM_NO_KEY→RULES；Sonar 不可用→N/A；PG 宕机→stored=false/503 | 《04》§7.4 |
6. 各模块质量属性速查（承接《04》§9）¶
| 属性 | 保障位置 | 措施 |
|---|---|---|
| 可替换 | analyzer | LLM/Sonar/队列均 SPI 或配置级（_llm 工厂、sonar 三条件探测） |
| 可扩展 | analyzer arch/rag | 新增语言 = 注册 tree-sitter parser + symbol 映射（配置级） |
| 可解释 | 报告/技术债 | scoreDetail 子分记录；技术债四源均带 description/suggestion/证据 |
| 可维护 | backend | ArchUnit 防 D-1~D-6（《04》§10.1）；契约测试 T-C-01~03 |
| 安全 | 全链路 | PathSafetyUtil、zip 白名单、git 参数白名单、无 eval/exec（T-S-05） |