# 前端架构技术债清单(2026-06-19 审查)

> 来源:fe-arch-review 子代理多角度审查(目录/组件粒度/状态/类型/依赖/路由/命名/测试/AI coding 友好度)。
> 整体:**B+(AI coding 友好 7.5/10)**。类型基础扎实(strict + vue-tsc 0)、命名一致(A 95/100)、依赖无环、死代码 1.7%。债集中在 AI 模块体量 + status 类型化。
> 已修复:i18n `as any` 样板收口(i18n-helpers.ts,as any 22→10,i18n 13→0,commit f4cc2e5)。
>
> **核对更新(2026-06-20·本次清理)**:P1-1 AiChat.vue **4075→750 已拆 God**(REFACTOR-07/SMELL-P0-3,子组件 ConversationSidebar/MessageList/ChatInput/TopBar/DirAuthDialog/MaxRoundsCard 进 `ai/`)/ ToolCard.vue **1066→374**(拆出 ToolCardList 422 + ToolResultBody)/ MessageList 已进 `ai/`(P1-2 部分兑现)。**P0 未动**:useAiSend/useAiEvents/useToolCard 三大件拆 + status union 仍待。另:`utils/time.ts formatRelativeZh→formatRelative` 重命名落地(SW-260618-21,消除 Zh 误导)。

## P0(阻碍 AI coding)

| # | 项 | 影响 | ROI | 风险 |
|---|---|---|---|---|
| P0-1 | `useAiSend.ts`(532 行)混合发送+队列+审批三条链 | 改一处需通读全文 | 高(拆 3 文件) | 中 |
| P0-2 | `useAiEvents.ts`(427 行)巨型 switch 12 case 216 行 | 新增事件改 200+ 行函数 | 高(按域拆 handler) | 中 |
| P0-3 | `useToolCard.ts` formatToolResult switch 15+ case | 新增工具改多处 | 高(策略表) | 中 |
| P0-4 | **status 字段无 union**(types.ts 4 处 Record + 34 处比较) | 拼写错误编译期不报错 | 高 | 中(逐字段核对字面量集) |

## P1(降效率)

| # | 项 | 影响 |
|---|---|---|
| P1-1 | AiChat.vue(**1474→750 已拆 God**)/MessageList.vue(1445)/ToolCard.vue(**1066→374 拆出 ToolCardList+ToolResultBody**) — AiChat/ToolCard 已收敛,**MessageList 仍重** | AI 改 AI 模块上下文巨大 |
| P1-2 | `components/` 一级散落 AiChat(薄壳容器)/ToolCard/ToolCardList/ToolResultBody — **MessageList 已进 ai/**,余仍一级 | 找文件靠记忆 |
| P1-3 | `catch (e: any)` 30+ 处 | 应改 unknown + Error 收窄 |
| P1-4 | `App.vue` 8 职责(布局已拆 layout/ → AppLayout/AppSidebar,App.vue 546→179,余初始化职责) | layout 已抽取,App.vue 收敛 |
| P1-5 | JSON.parse 后 cast 无守卫 4 处(IdeaDetail/TaskOutputCard/useToolCard/useAiConversations) | 后端格式漂移运行时崩 |
| P1-6 | `useAiConversations.switchConversation` 116 行单函数 | 难维护 |
| P1-7 | `constants/project.ts` 含 task 常量(命名狭窄) | 找 task 常量去错文件 |

## P2(优化)

- 测试覆盖 0%(无 vitest)。高 ROI 目标:utils/time.ts(parseTs 边界)/ utils/markdown.ts(stripMd)/ utils/project.ts(parseStack)纯函数易测
- router 无 404 catch-all
- `meta.icon` 11 处死字段(删或接入 AppSidebar)
- ErrorBoundary.vue 已实现(76 行)+ i18n key 就绪,从未接入(main.ts:12 注释承诺未落地)
- `useAiEvents.ts:95` 模块级导出 `pendingMaxRounds` ref(破坏 composable 可复用性)
- store 三段式 try/catch/finally 样板可抽高阶函数

## 留待用户决策(高风险/需拍板)

1. **P0-4 status union 类型化**:试点 IdeaRecord.status(语义最单一),跑通后推其余(TaskRecord/AiToolCallInfo/WorkflowRecord 字段名同语义不同,易误伤)
2. **P0-1/2/3 AI 三大件拆分**(useAiSend/useAiEvents/useToolCard):行为变更面大,独立任务逐个 + vue-tsc + 手测
3. **ErrorBoundary 接入**:App.vue router-view 外层包裹,或删组件+删注释
4. **P1-2 components 一级归位**(AiChat/ToolCard/ToolCardList → ai/)+ **P1-7 constants/project 拆 task**:改 import 路径面广,集中"目录整理"任务
5. **router meta.icon 死字段**:删或接入 AppSidebar

## AI coding 友好强项(保持)

- 类型基础好(strict + vue-tsc 0 + 0 处 @ts-ignore)
- 命名一致(PascalCase/动词前缀/kebab-case)
- 依赖无环(stores→composables→components→views 单向)
- 死代码少(1.7%)
- 注释详尽(每个 composable 头部职责+耦合说明,极利 AI 理解)