# 代码复用思考指南

## 什么时候先搜索

在创建 helper、常量、转换函数或新的 UI primitive 前，先搜索这些本地模式：

```bash
rg "requestJson|ApiError" zhixing-web/src
rg "QueryKey|queryKey|useQuery" zhixing-web/src
rg "className|cva\(|cn\(" zhixing-web/src/shared zhixing-web/src/features
rg "create_app|response_model|Depends\(" zhixing-server/src zhixing-server/tests
```

当前仓库已经有明确的复用点：

- 网络 JSON 请求统一经 `zhixing-web/src/shared/api/request-json.ts`，不要在页面重新实现 `fetch` 和错误判断。
- Tailwind class 合并统一经 `zhixing-web/src/shared/ui/utils.ts:cn`；有限变体用 `cva`，参照 `button.tsx` 和 `badge.tsx`。
- 服务端应用组合统一经 `zhixing-server/src/zhixing_server/bootstrap/app.py:create_app`，测试也调用真实工厂。
- React Query key 以 feature 内 `as const` 常量维护，参照 `system.query.ts`。

## 复用与边界

- 只有跨 feature、无业务所有权的能力才进入 `shared/`；一次性页面逻辑留在 feature。
- 看到两处相似代码时，先确认输入、错误语义和生命周期是否真的相同，再抽象；不要为了消除两行重复创建泛化框架。
- API 类型和领域概念不能因为“看起来相同”就自动合并。后端 Pydantic 模型、feature TypeScript 类型和 UI view model 各自承担边界责任。

## 验证问题

- 新 helper 是否能被现有测试直接覆盖？
- 抽象后是否让导入方向更清楚，而不是引入 shared → feature 反向依赖？
- 是否保留了 `AbortSignal`、错误状态、可访问性和类型约束等原有行为？