EvoCode 技术债管理方案
定位：系统性的技术债管理策略——识别、分类、量化评估、优先级排序，以及短/中/长期处理计划。
范围：EvoCode 自身工程债（本仓库三端代码）的治理策略；平台对被分析项目的技术债管理能力见《09》§2.8 与《07》§3.11。
配套：《11-技术债监控与质量指标体系》定义指标与门禁；《05-架构审查》《08-测试计划》为既有治理设施。
版本：v1.4 · 2026-08-13 · 基于 P9 v1.1 交付状态（backend 155 / analyzer 158 / frontend 12）；技术债全部闭环（TD-01~12）+ SPI-1（A1 管线插件化）达成，剩余仅架构演进 A2（报告拆表 SPI-6）/ A3（多租户 SPI-8）
1. 技术债识别
1.1 识别通道（四类来源）
| 通道 |
触发点 |
产出 |
状态 |
| 架构审查 |
每阶段结束时（05 §10 评审清单） |
P0/P1/P2 问题清单 |
已执行三轮，P0 全清 |
| 契约测试 |
每次接口变更（T-C-01~03） |
字段/错误码/事件类型偏差 |
门禁化 |
| 代码扫描 |
评审 + 手工 |
TODO/FIXME/死代码/重复 |
持续 |
| devlog 遗留清单 |
每阶段收尾 |
"遗留增强"项 |
待排期 |
1.2 v1.0 已识别技术债清单（实证）
以下条目均来自本次审计（2026-08-11）：扫描三端源码、对比《06 契约》《07 数据字典》与实现。
| # |
条目 |
类型 |
证据 |
来源 |
| TD-01 |
/analyze/v1/explain 已入契约（06 §5.4）但 analyzer 无实现端点 |
已闭环（P9e：analyzer /analyze/v1/explain 规则版模板 + LLM 增强） |
analyzer/app/core/explain.py；test_explain.py 5 例 |
契约审计 |
| TD-02 |
《07》§3.4 已定义 dependency 字段字典并标注 V002 建表，但迁移 V001~V008 均未建该表；backend 亦无任何消费端（无 controller/service/entity） |
已闭环（P9d：V009 dependency 表 + 全链路消费端） |
db/migration/V009__dependency.sql；DependencyService/Controller |
表实现审计 |
| TD-03 |
P7 devlog 明确"依赖清单落库"为遗留增强，P9d 才排入 |
已闭环（P9d：依赖分析全链路交付） |
devlog 2026-08-11-p9d.md |
devlog 审计 |
| TD-04 |
技术债 source 枚举含 AI_DOCTOR/MANUAL 但聚合仅实现四源（ARCH/QUALITY/EVOLUTION/DEPEND） |
已闭环（P9d DEPEND 源收口 + 2026-08-13 补 AI_DOCTOR/MANUAL 登记入口 POST /projects/{id}/tech-debts） |
TechDebtServiceImpl.create；06 §3.12 |
代码审计 |
| TD-05 |
Redis 端口已预留（AD-017）但无任何使用（缓存/队列均空） |
已闭环（2026-08-13：AD-018 选读缓存方向，项目列表 GET /projects 走 Spring Cache + Redis，TTL 60s + 写路径失效 + CacheErrorHandler 降级） |
CacheConfig.java + ProjectServiceImpl 注解；CacheConfigTest 2 例 |
基础设施审计 |
| TD-06 |
frontend 无 vitest 单测（08 §1 标注"可选"），仅 lint+build |
已闭环（P9a：vitest 进门禁，12/12） |
frontend/src/api/*.test.ts；npm run test |
测试审计 |
| TD-07 |
SonarQube 依赖外部服务，演示/离线环境不可用（降级 N/A） |
已闭环（docker-compose --profile full 可选启动；演示环境走代理指标 available=false） |
docker-compose.yml sonarqube profiles: ["full"]；README 快速开始说明 |
架构审计 |
| TD-08 |
LLM 依赖外部 API：无 Key/网络不通时规则版兜底，但文档生成（doc）无规则版 |
已闭环（P9b：docgen 规则版降级 source=RULES，无 Key 也 200） |
analyzer/app/core/docgen.py _rules_doc；test_doc.py 降级用例 |
降级链审计 |
| TD-09 |
analyzer core/arch 仅支持 Python/Java 两语言 parser |
已闭环（2026-08-13：新增 JS/TS/Go tree-sitter parser + archscan 分发，混合语言目录端到端扫描） |
app/core/arch/go_parser.py/js_parser.py；test_arch_langs.py 6 例 |
代码审计 |
| TD-10 |
prompts.py 报告 prompt 与 RAG chunker 的 token 估算为近似（~4 chars/token），非精确 tokenizer |
已闭环（2026-08-13：内置轻量估算器 app/core/tokenizer.py，chunker 改 token 预算驱动 + 单测断言上限） |
tokenizer.py + test_tokenizer.py 6 例；test_rag.py 断言 ≤400 token/片 |
代码审计 |
| TD-11 |
监控缺失：无任何自动化质量指标采集/趋势记录（健康分只对被分析项目，不覆盖 EvoCode 自身） |
已落地（2026-08-13：docs/metrics/ 台账 + 首期快照 v1.1） |
docs/metrics/README.md + 2026-08-13-v1.1.md |
审计 |
| TD-12 |
backend 启动命令分散：README 手工分步两处重复 java -jar 命令（L98-99/L121-122），未收敛到统一脚本入口 |
已闭环（P9e：删除重复分步块，统一 scripts/ 入口单一引用） |
README「快速开始 → 手动分步」仅一处 |
文档审计 |
2. 技术债分类
2.1 分类维度（按性质）
| 类别 |
含义 |
本清单条目 |
| C-契约 |
契约已定义但实现缺失/漂移 |
TD-01 |
| C-数据 |
表结构悬空/未落地、字段未消费 |
TD-02 |
| C-功能 |
规划/枚举预留但未实现 |
TD-03、TD-04 |
| C-基础设施 |
预留未用、依赖外部服务 |
TD-05、TD-07 |
| C-测试 |
覆盖缺口 |
TD-06 |
| C-鲁棒性 |
降级不对称、精度近似 |
TD-08、TD-10 |
| C-扩展性 |
能力受限 |
TD-09 |
| C-工程 |
流程/监控/弃用路径 |
TD-11、TD-12 |
2.2 与产品内技术债的映射
EvoCode 对被分析项目使用四源分类（ARCH/QUALITY/EVOLUTION/DEPEND，见《09》§2.8）；自身工程债采用上述 8 类。两套分类不混用：前者是产品数据模型（落 tech_debt 表），后者是研发治理台账（本文档 + 《11》监控）。
3. 量化评估
3.1 单条债务量化（四维评分）
每条技术债按 4 个维度打分（1–5），加权得 debt_score：
debt_score = impact×0.4 + likelihood×0.2 + cost×0.2 + stability×0.2
| 维度 |
1 分 |
5 分 |
说明 |
| impact（影响） |
仅影响内部实现 |
阻断功能/契约/安全 |
用户可感知程度 |
| likelihood（发生概率） |
几乎不发生 |
必然触发 |
降级路径、错误码、异常分支 |
| cost（修复成本） |
≤0.5 人日 |
>5 人日 |
按估算 |
| stability（稳定性） |
修复即稳 |
修复引出连锁变化 |
依赖面大小 |
3.2 清单量化结果
| # |
impact |
likelihood |
cost |
stability |
debt_score |
等级 |
| TD-01 |
4 |
4 |
2 |
3 |
3.6 |
高 |
| TD-02 |
3 |
3 |
2 |
3 |
2.9 |
中 |
| TD-03 |
4 |
3 |
2 |
3 |
3.3 |
高 |
| TD-04 |
3 |
2 |
1 |
3 |
2.5 |
中 |
| TD-05 |
2 |
1 |
1 |
2 |
1.6 |
低 |
| TD-06 |
3 |
3 |
3 |
3 |
3.0 |
中 |
| TD-07 |
3 |
4 |
3 |
3 |
3.2 |
高 |
| TD-08 |
4 |
4 |
2 |
3 |
3.6 |
高 |
| TD-09 |
2 |
2 |
2 |
3 |
2.2 |
低 |
| TD-10 |
1 |
3 |
1 |
2 |
1.5 |
低 |
| TD-11 |
4 |
4 |
3 |
3 |
3.8 |
高 |
| TD-12 |
2 |
1 |
1 |
2 |
1.6 |
低 |
等级：≥3.5 高 / 2.5–3.4 中 / <2.5 低。
4. 优先级排序
4.1 影响 × 成本矩阵
成本 ↓ / 影响 →
高影响 中影响 低影响
低成本 P0 立即处理 P1 近期 P2 顺手
TD-01 (契约缺失) TD-02 (字典-迁移漂移) TD-05 (Redis)
TD-08 (降级不对称) TD-12 (弃用路径)
中成本 P0 立即处理 P1 近期 P2 可延
TD-11 (监控体系) TD-04 (枚举补齐) TD-09 (语言扩展)
TD-06 (前端测试)
高成本 P1 排期 P2 远期 P3 观察
TD-03 (依赖落库) TD-07 (Sonar 可选) TD-10 (精确 tokenizer)
4.2 处理策略
| 等级 |
策略 |
原则 |
| P0（立即） |
契约一致性 + 降级安全补全 |
契约即承诺，必须收敛；降级链路不对称会在演示/离线场景暴露 |
| P1（近期） |
表结构收口、测试补强、枚举闭环 |
随下一功能阶段（P9）批量消化 |
| P2（可延） |
预留设施启用、能力扩展 |
有明确业务价值时再动，避免过度工程 |
| P3（观察） |
精度/近似类 |
记录在案，触发条件（如 RAG 命中率劣化）满足再修 |
5. 短期 / 中期 / 长期处理计划
5.1 短期（S，0–2 周，随 P9 交付）
| 项 |
动作 |
验收 |
| TD-01 |
analyzer 实现 /analyze/v1/explain（规则版：按 ruleKey/severity 模板生成解释；LLM 可用时增强） |
T-C-01 全过；T-U-09~12 扩展 explain 用例 |
| TD-08 |
doc 生成增加规则版降级（无 Key 时按 docType 模板产出基础文档，source=RULES） |
无 Key 全链路可演示，与 report 降级一致 |
| TD-04 |
四源聚合补 AI_DOCTOR（chat 中确认的技术债落库）与 MANUAL（前端手动登记）入口 |
07 枚举全部可写；T-U-13/14 扩展 |
| TD-12 |
启动命令收敛：把 README 两处重复的 java -jar 分步合并为 scripts 脚本入口（start-dev.bat 等）的单一引用 |
README 无重复命令；一键/分步说明指向同一入口 |
| TD-06 |
引入 vitest，为 api/request.ts、chat.ts（SSE 解析）补单测 |
npm run test 进门禁 |
5.2 中期（M，1–3 个月，P10+）
| 项 |
动作 |
验收 |
| TD-02/TD-03 |
依赖分析落库：analyzer /analyze/v1/dependency（解析 pom.xml/package.json，EOL 判定）→ 落 dependency 表 → backend 查询端点 → 前端依赖区块 |
P9d 交付；表无空悬 |
| TD-11 |
落地《11》监控体系：质量指标采集（每阶段门禁后回填 docs/metrics/），健康分曲线 + 门禁红绿灯 |
指标台账连续 ≥3 期 |
| TD-07 |
SonarQube 改为可选组件（docker-compose profile），文档明确演示环境用代理指标 |
一键启动不依赖 Sonar |
5.3 长期（L，3–12 个月）
| 项 |
动作 |
验收 |
| TD-05 |
Redis 启用：分析任务队列（替换内存 @Async）或读缓存（file_node/列表页）；出 AD-018 |
高并发 3+ 任务不丢；列表接口 P95 <500ms |
| TD-09 |
arch/rag 语言扩展：注册 tree-sitter parser + symbol 映射（JS/TS/Go）；验证新增语言 ≤1 天配置级接入 |
04 §G3 指标达成 |
| TD-10 |
引入精确 token 估算（tiktoken 等价）替换 4 chars/token 近似 |
chunker 单测断言 token 上限 |
| — |
架构演进 A1→A3（《04》§11）：多租户/分布式任务/插件市场 |
按 04 演进规划节点推进 |
6. 治理流程与责任
6.1 技术债生命周期
识别(§1) → 登记(本文档清单) → 量化(§3) → 排序(§4) → 排期(§5) → 修复 → 验收(门禁) → 监控(§11 曲线) → 复发复查(新扫描)
6.2 触发规则
| 事件 |
动作 |
| 新增契约字段/端点 |
触发 T-C-01/02 契约测试 + 本文档增补 |
| 阶段收尾 |
05 架构审查 + devlog 遗留清单 → 更新本文档 §1.2 |
| 门禁红 |
《11》指标下滑 → 回填"新债"条目并排期 |
| 每次发版 |
回归 7 项冒烟（08 §8）+ 指标台账快照 |
6.3 责任
- 每次提交：三端门禁自证（03 DoD）。
- 每阶段：架构审查（05 §10）+ devlog 双轨记录。
- 每版本：本文档清单评审 + 《11》指标回顾；负责人更新台账。
7. 与既有设施的关系
| 设施 |
角色 |
本文档关系 |
| 《05-架构审查》 |
结构性债的发现机制 |
识别通道之一（§1.1） |
| 《08-测试计划》 |
回归与门禁 |
验收标准来源 |
| 《11-技术债监控与质量指标体系》 |
量化与趋势 |
第 3/6 节的量化与监控落地 |
| AD-017 等 |
决策记录 |
TD-05 修复时新增 AD-018 |