# geMoldInsight 技术债与治理计划（TECH_DEBT）

> 文档定位：**当前活跃技术债与治理计划的权威文档**。
> 本文回答“现在还有哪些重要债务、优先级如何、下一步怎么处理”；不负责维护当前实现状态，当前状态见 [STATUS.md](STATUS.md)。架构边界见 [ARCHITECTURE.md](ARCHITECTURE.md)，未来路线见 [ROADMAP.md](ROADMAP.md)。
> 本文由归档文档 [archive/MOLDINSIGHT_TECH_DEBT_PLAN.md](archive/MOLDINSIGHT_TECH_DEBT_PLAN.md) 收敛整理而来，保留活跃债务与治理结论，弱化详细实施流水账。

---

## 1. 当前技术债概览

当前最主要的技术债集中在两个区域：

- **moldinsight API 与处理链路的结构收口**
- **文档 / 部署 / 历史语义与当前代码现状未完全一致**

已经完成的高优先级治理不再作为持续待办反复展开，当前重点聚焦在“还没完成、且值得继续推进”的部分。

---

## 2. 已完成的重要治理（摘要）

以下高价值治理已完成：

### 2.1 安全与权限
- debug/history 路由补鉴权
- 任务访问控制收紧
- 无主数据不再默认放行

### 2.2 静默失败与可用性
- `detect-undercuts` 改为基于真实 shape 分析
- OCC 超时后重建 executor，避免全队列永久堵死
- 后台任务统一分派，补强引用与并发控制

### 2.3 状态存储与缓存
- Redis 任务状态改为 Hash 字段级更新，兼容旧格式
- 完成态任务视图增加缓存
- 导出缓存与持久化链路收口，支持重启后再导出

### 2.4 架构与代码清理
- 删除旧单体入口与死代码
- 设置惰性配置校验，提升可测试性
- Generator 公共接口提取完成，补充契约测试

详细历史过程保留在原始技术债文档中，后续将转入归档。

---

## 3. 当前活跃技术债

### D1. `advanced_router` 过大，职责混杂

现状：
- 导出、估算、设计/分析相关接口仍混在同一个 router 中
- 请求体仍有较多手动解析逻辑

影响：
- 路由边界不清晰
- OpenAPI 可读性差
- 接口参数校验不统一
- 后续继续扩展时维护成本高

建议：
- 拆分为 export / design / cost 等子路由
- 高优先级请求体改为 Pydantic 模型

优先级：**P1**

### D2. 铝价模拟数据未显式标注来源

现状：
- 铝价服务返回的是模拟/参考数据，但接口层未明确表达

影响：
- 容易误导前端与业务使用者，把模拟数据理解为实时行情

建议：
- 响应增加 `source: "simulated"`
- 前端界面同步标注“模拟/参考数据”

优先级：**P2**

### D3. shared/platform 边界仍需继续收敛

现状：
- `shared` 同时承担平台基础能力与部分历史耦合职责
- 共享 ORM 与 app factory 仍是主要耦合点

影响：
- 模块边界认知成本较高
- 新增逻辑容易继续堆入 shared

建议：
- 继续从文档、目录语义、职责边界上推进收敛
- 在后续实际重构中优先避免把业务逻辑继续沉入 shared

优先级：**P2**

### D4. 文档现状 / 规划 / 历史混放

现状：
- 文档存在部署说明重叠、计划/总结/权威文档混放
- README 承担过多职责

影响：
- 新成员难以判断“哪篇才是当前有效说法”
- 状态、部署、规划容易发生漂移

建议：
- 建立 `STATUS / ARCHITECTURE / ROADMAP / DEPLOYMENT` 主骨架
- 历史材料迁入 `docs/archive/`

优先级：**P1**

---

## 4. 当前推荐治理顺序

### 第一优先级
1. `advanced_router` 拆分
2. 高优先级接口补 Pydantic 请求模型
3. 文档主骨架收口并减少重复说明

### 第二优先级
4. 铝价模拟数据来源显式化
5. 部署历史文档归档
6. shared/platform 语义继续收敛

---

## 5. 治理原则

### 5.1 先收口接口与边界，再做更大结构调整

当前最值得继续投入的，不是大规模目录重写，而是：
- 先把接口边界、文档边界、部署边界收清楚
- 再逐步推进 shared/platform 的后续调整

### 5.2 优先做“降低长期维护成本”的改动

优先处理：
- 重复逻辑
- 模糊边界
- 静态契约缺失
- 文档漂移风险

### 5.3 已解决问题不再长期占据主文档中心

已经完成且稳定的问题，只在本文保留摘要结论；详细实施流水账后续归档，不继续作为主文档主体。

---

## 6. 与相关文档的边界

- 当前项目状态：看 [STATUS.md](STATUS.md)
- 当前架构与模块边界：看 [ARCHITECTURE.md](ARCHITECTURE.md)
- 后续演进路线：看 [ROADMAP.md](ROADMAP.md)
- 部署主题入口：看 [DEPLOYMENT.md](DEPLOYMENT.md)
- 原始 moldinsight 细粒度债务记录：看 [archive/MOLDINSIGHT_TECH_DEBT_PLAN.md](archive/MOLDINSIGHT_TECH_DEBT_PLAN.md)