# zsjz-ai 项目长期记忆

## 本机环境怪癖（每次会话都会遇到）

- bash 工具基本不可用：shim 报 `dirname: command not found`，`ls/grep/wc/cd` 全废。**不要用 Bash 工具**。
- PowerShell 工具的 stdout **不回显**：需要看输出时一律 `> 临时文件`，再用 Read 读，读完删掉。
- `Remove-Item` 被 safe-delete 钩子拦截 → 删文件用 `[System.IO.File]::Delete('绝对路径')`。
- 文件搜索/内容搜索用 Glob / Grep 工具，别用 shell。

## 前端（ai-frontend/）

- 技术栈：Vue 3 + `<script setup lang="ts">` + ant-design-vue + vite + less + pnpm。
- 常用命令（cwd 一律在 `ai-frontend/`）：
  - 构建：`pnpm build`（= `vite build --mode production`，**不做类型检查**，约 2 分钟）
  - 类型：`pnpm type:check`（= `vue-tsc --noEmit --skipLibCheck`，约 25 秒）
- **`pnpm type:check` 本来就过不了**：仓库有约 89 条既有报错，集中在
  `src/call/`、`src/trans/`、`src/graph/`、`src/otg/`、`src/person/` 等无关文件。
  判断自己有没有写坏，看的是「报错文件里有没有自己动的文件」，不是退出码。
- `tsconfig.json`：`isolatedModules: true`，无 `verbatimModuleSyntax`；`noUnusedLocals: false`（所以多余的 import 不报错）。
- 路由 / 别名：`@/*` → `src/*`；路由表在 `src/core/router/routes/index.ts`。
- less 全局变量靠 `build/theme/modifyVars.ts` 里的
  `hack: 'true; @import (reference) "src/core/design/var/index.less";'` 注入，
  所以任意 `.vue` style 块和任意 `.less` 文件都能直接用 `@modal-header-bg-color` 这类变量，
  SFC 的 style 抽成独立 `.less` 再 `@import` 回来是安全的。
- ant-design-vue 的 Modal / Popover / Select 会 teleport 到 body，**样式必须全局（非 scoped）**，
  靠 `wrapClassName` + 全局类名命中。

## cleaning 页拆分工程（`src/case/views/data/cleaning.vue`）

**当前进度（2026-09-18）**：`12029 → 944 行`（−92%），30+ 新文件，type:check 0 报错 + build 通过。
依赖顺序（单向、无环）：`useCaseDataCleaningShared`（底层状态）→ `useCleaningRules / useFieldMapping / useRecognitionRules / useTemplateLibrary`
→ `useCaseDataCleaningActions`（叶子动作域，放在最后所以能直接用上游产物）。
剩余（压到 ≤400）：① 把顶层 `watch([...])` 移进 composable（watcher 在 composable 内注册仍绑定页面实例）→ 21 个退回声明可搬走；
② 清未使用 import（匹配标识符要允许 `...` 展开）；③ `useCaseDataCleaningActions`(1310) 可按域再拆成 useFileTree / usePreviewData / useColumnOps。

- **消环的唯一正确姿势**：底层共享状态收进**唯一一个 shared composable**，其余域全部单向依赖它（+ 已有 handle）；
  叶子域一定要放在所有上游之后。不要用「多个平级 composable 互相注入」——底层状态同时被多方需要，会形成真实的环，
  拓扑排序无解；破环退化成空壳 composable 就是垃圾。
- 生成器可复用件（写这类脚本直接照搬）：
  - 声明解析用「**找下一个顶层起点**」，顶层起点要包含 `watch(` / `provide(` / `onMounted(` 等**非声明的顶层语句**，否则上一个声明的范围会吞掉它们
  - 模板取词：`{{ }}` + `: / v- / @ / ref` 绑定值 + 标签名；表达式剥掉 `'…'`/`"…"` 但**保留 `${...}` 插值**
  - 抽出的 `.ts` 补 `export`；跨文件相对路径按新层级重算；deps 类型**显式写 interface**（否则类型循环 → `Object.entries(any)` → `[string, unknown][]`）
  - 接线模式：**页面在 setup 中实例化 composable + 同名解构**（页面代码/模板零改动），`provide` 放在 setup 末尾；
    wiring 插在「最后一个依赖声明」**之后**（锚点是依赖声明的最后一行）

- 方案文档：仓库根 `cleaning-refactor-plan.md`。已拍板：**路由不动**（cleaning.vue 留作入口）、
  通信走 **provide/inject + 领域 composable**、样式保持**全局 less 非 scoped**、**业务逻辑一律不许动**、
  **每阶段停下来 review**。
- 目录：`cleaning/{types,constants,context}.ts` + `cleaning/{utils,composables,components,styles}/`
- 沟通模式（Phase 3 起确定的**主力模式**，后续阶段照这个来）：
  - 领域逻辑放 `composables/useXxx.ts`，**由页面在 setup 里实例化**
  - 页面用**同名解构**接住返回值（`const { a, b } = useXxx(...)`）→ 页面原有代码与模板**零改动**
  - 页面把 `useXxx` 实例放进 `provide(CleaningContextKey, { ..., xxx })`，子组件从 context 取
  - `provide()` 放在 **setup 末尾**（避开 const 声明顺序的 TDZ）；composable 的调用位置 = 「最后一个依赖声明之后」
  - **composable 的 deps 必须显式声明类型**（写 interface），不要让 TS 从实参反推 —— 页面里有 decl 的签名依赖返回值时
    会形成类型循环，导致 deps 退化成 `Record<string, any>`，而 `Object.entries(<any>)` 会产出 `[string, unknown][]` 引发一片 unknown 报错
- **验证必须 type:check + build 双跑**：`vue-tsc` **抓不到 Vue 模板标签不平衡**，
  抽块边界写错（多删一个 `</div>`）时 type:check 是 0 报错、`pnpm build` 才报 `Element is missing end tag`。
  抽模板块时边界要取「配对的 `</div>` 行」，不要凭缩进猜（这个文件缩进本身不严格）。
- 已踩实的坑：
  - 抽出的 `.ts` 必须补 `export`（无 import/export 的 .ts 会被 TS 当全局脚本 → `TS2306`）
  - 抽出文件引用原页面的相对路径 import 时，要按新层级重算（`@/` 别名例外）
  - **页面级 `let`/`var` 标量不能注入**：跨文件是按值快照，两边各改一份（请求序号守卫之类会失效）
  - **声明解析要用「找下一个顶层起点」**，不要用括号深度（多行泛型 `ref<\n Record<...>` 会让深度中途归零、把声明切一半）
  - **模板取词要保留 `${...}` 插值**，只剥 `'…'` / `"…"`（整段 strip 会把 `` `is-${x}` `` 里的 x 抹掉）
  - 判定「setup 顶层立即求值」时**只扫 wiring 位置之前的行**（末尾的 `provide(...)` 也是顶层语句，会假阳性）；
    `watch([...refs])` 整条都算立即求值；「可搬集合 ↔ wiring 位置」要迭代到收敛
  - 算「页面还要解构哪些名字」时，扫描范围 = **整份模板 minus 被抽走的块**（别漏掉保留在页面里的部分，比如面板里的匹配条/外层 wrapper）
  - 依赖若是页面里 `const { x } = someComposable;` 解构出来的，类型要写成 `ReturnType<typeof someComposable>['x']`（否则退化成 any → `Object.entries(any)` → unknown）；
    依赖类型文本里出现的类型名（`Ref<TemplateTab>` 里的 `TemplateTab`）也要补 import

- **验证「重构没改业务逻辑」的可靠做法**：拿 `git show HEAD:<原文件>` 当基准，和「当前入口 + 抽出目录整棵树」做
  **逐行多集合比对**（归一化：去 `export ` 前缀 / 折叠空白 / 去行尾 `,;`，跳过注释与 import），
  判定条件 = 原始每行在当前树里的出现次数 ≥ 原始次数。本项目已验证 **script 丢失/被改动 = 0**。
  注意：扫描范围只圈自己那一棵（别把同目录其它页面算进来）、SFC 的 template 结束点是 `<script` 不是 `<style`、
  取原始文件用 node `execSync(...,{encoding:'buffer'})`（PowerShell `>` 会写成 UTF-16，且 `cmd /c` 被拦）。

## 用户偏好

- **直接干活，不要反复审计**。
- **业务逻辑不许动**：重构只做搬家/抽取，逐行原样搬运。
- **每个阶段停下来给 review**，确认后才进下一阶段。
- 大文件重构：先给方案文档（会被认真审），方案里要列清决策点。
- **别生成一堆垃圾文档**，编译/构建通过就是完成标准。
- 不要留临时脚本、临时日志在仓库里，做完自己清理。