# dev-trace Drop 移除 — Wave 排序确认

> 日期:2026-05-04 / 触发:Neo 在 P1 二轮反馈"接受 Drop,排在任务列表中吧,Wave 排序你来确认"

## 一、Wave 排序决定

**推荐排到 Wave 5(部署 + 文档收尾)**。

## 二、为什么排到 Wave 5

### 不该排到 Wave 1-3 的理由

- Wave 1-3 都是"业务功能 D Bug 修复 + 沙箱接入"主线,移除工具页会**分散注意力**
- dev-trace 不影响功能(零业务依赖,Neo 没在用),没有"必修紧迫性"
- 删除涉及 admin-web 路由 + 后端 router + 前端 .tsx + 中间件,虽然只是 1-2h,但是**结构性变更**(删除 + 后端日志清理),最好与其他文档收尾合并 PR

### 不该排到 Wave 2 的理由

- Wave 2 是 admin-web AI 套件 + P1-1 schema 迁移 + P1-6 触发器合并,P1-1 schema 迁移已经是 9 人时大工作量,不再叠加结构性变更

### 排到 Wave 5 的理由

- Wave 5 是"部署 + 文档收尾",本来就要做大量结构性清理(P0/P1 文档批改 / 文件名修正等)
- 与 Wave 5 其他清理项合并 1 个 PR 即可
- Wave 5 是上线前最后窗口,适合做"减法"

## 三、具体执行清单

### 删除文件(确认无业务依赖后)

```text
apps/admin-web/src/pages/DevTrace.tsx
apps/admin-web/src/api/devTrace.ts (若存在)
apps/admin-web/src/__tests__/DevTrace.test.* (若存在)
apps/backend/app/routers/admin_dev_trace.py
apps/backend/app/middlewares/dev_trace_*.py (若有专门中间件)
apps/backend/app/services/dev_trace_service.py (若存在)
apps/backend/tests/test_dev_trace*.py (若存在)
```

### 修改文件

```text
apps/admin-web/src/App.tsx       # 删除 DevTrace 路由 + import + 菜单项
apps/backend/app/main.py         # 删除 admin_dev_trace include_router 行
apps/backend/app/main.py         # 若有中间件挂载,删除
```

### 数据库清理(可选)

- 如有 `meta.dev_trace` 或类似表,加迁移 `XXX__drop_dev_trace_tables.sql`
- 已有 111 MB 落盘数据可一并清理(执行 DROP TABLE 即可,无业务依赖)

### 配置 / 环境变量清理

```text
.env.example      # 删除 DEV_TRACE_* 配置项
.env / .env.local # Neo 手动删本地配置
```

### 文档清理

```text
docs/_overview/02b-adminweb-page-matrix.md   # §3.16 dev-trace 节移除或标"已 Drop"
docs/_overview/00-index.md                   # 若提到 dev-trace 路由,移除
docs/_overview/04b-feedback/extra-dev-trace-perf.md  # 标"已实施 Drop"
docs/audit/changes/2026-XX-XX__drop_dev_trace.md  # 新建一份审计记录
```

## 四、执行步骤(Wave 5 内)

1. **第 1 步**:`grep -r "dev_trace\|DevTrace" --include="*.py" --include="*.ts" --include="*.tsx"` 全项目确认无遗漏依赖
2. **第 2 步**:删除上述清单文件 + 修改 App.tsx / main.py
3. **第 3 步**:数据库迁移 DROP 表 + 落盘数据清理
4. **第 4 步**:跑 admin-web pnpm build / backend pytest 验证无引用
5. **第 5 步**:Playwright 走查 admin-web 全部 19 路由,确认菜单 + 路由 + 页面正常
6. **第 6 步**:写审计 commit

**总耗时**:1-2 小时(单 PR 完成)。

## 五、风险与回滚

### 风险

- 万一有"未发现的业务依赖"(grep 没匹配到的 dynamic import / 字符串拼路由)
- 数据库 DROP 不可回滚(但 dev-trace 表数据本身没价值)

### 回滚

- 代码层:`git revert` 即可
- 数据库层:重建空表(数据丢失但不影响业务)

## 六、给 Neo 的最终确认

- ✅ Wave 5 排序合理(与文档收尾合并)
- ✅ 1-2h 单 PR 可完成
- ✅ 影响面明确,可回滚
- ⚠️ Wave 5 之前如果 Neo 发现需要 dev-trace 看某个性能/调用栈,通知我提前到 Wave 1-3

---

> Wave 5 实施时按本文步骤进行;Wave 5 之前若有变化,Neo 通知调整。