jsharness 1.0.0

package/.harness/dev-map/backend/database.md

@@ -0,0 +1,106 @@
+# 后端分区 — 数据库设计与迁移
+
+## 当前数据库
+
+| 项目 | 值 |
+|------|-----|
+| 数据库类型 | PostgreSQL 15+ |
+| ORM | Prisma / TypeORM |
+| 连接池 | pg-pool (默认 10 连接) |
+| 迁移工具 | Prisma Migrate / TypeORM Migration |
+| 字符集 | UTF-8 |
+| 时区 | UTC (应用层做时区转换) |
+
+## 数据模型总览
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│    users     │     │    roles     │     │ permissions  │
+├──────────────┤     ├──────────────┤     ├──────────────┤
+│ id (PK)      │◄──┐ │ id (PK)      │     │ id (PK)      │
+│ email (UQ)   │   └─┤ name         │     │ resource     │
+│ password     │     │ description  │     │ action       │
+│ name         │     └──────┬───────┘     └──────┬───────┘
+│ avatar_url   │            │                    │
+│ status       │     ┌──────┴───────┐    ┌──────┴───────┐
+│ created_at   │     │ user_roles   │    │role_permissions│
+│ updated_at   │     ├──────────────┤    ├──────────────┤
+└──────────────┘     │ user_id (FK) │    │ role_id (FK)  │
+                      │ role_id (FK) │    │ perm_id (FK)  │
+                      └──────────────┘    └──────────────┘
+
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│  sessions    │     │ audit_logs   │     │  files       │
+├──────────────┤     ├──────────────┤     ├──────────────┤
+│ id (PK)      │     │ id (PK)      │     │ id (PK)      │
+│ user_id (FK) │     │ user_id (FK) │     │ uploader_id  │
+│ token_hash   │     │ action       │     │ url          │
+│ expires_at   │     │ entity_type  │     │ file_name    │
+│ created_at   │     │ entity_id    │     │ mime_type    │
+└──────────────┘     │ ip_address   │     │ size_bytes   │
+                     │ created_at   │     │ created_at   │
+                     └──────────────┘     └──────────────┘
+```
+
+## 迁移工作流
+
+### 1. 创建迁移
+
+```bash
+# Prisma
+npx prisma migrate dev --name add_user_avatar_field
+
+# TypeORM
+npx typeorm migration:generate src/database/migrations/AddUserAvatarField
+```
+
+### 2. 迁移文件规范
+
+```sql
+-- YYYYMMDDHHMMSS_description.sql
+
+-- =============================================
+-- Migration: Add avatar_url to users table
+-- Author: {developer-name}
+-- Ticket: #{issue-number}
+-- Description: Add avatar storage support for user profiles
+-- =============================================
+
+BEGIN;
+
+-- Up migration
+ALTER TABLE users ADD COLUMN avatar_url VARCHAR(512);
+ALTER TABLE users ADD COLUMN avatar_updated_at TIMESTAMPTZ;
+CREATE INDEX idx_users_avatar ON users(avatar_url) WHERE avatar_url IS NOT NULL;
+
+-- Down migration (必须可逆)
+-- ALTER TABLE users DROP COLUMN IF EXISTS avatar_url;
+-- ALTER TABLE users DROP COLUMN IF EXISTS avatar_updated_at;
+-- DROP INDEX IF EXISTS idx_users_avatar;
+
+COMMIT;
+```
+
+### 3. 迁移注意事项
+
+| 规则 | 说明 |
+|------|------|
+| **必须可逆** | 每个 up 都要有对应的 down |
+| **不加锁大表** | >100 万行表的 DDL 要分段执行 |
+| **默认值** | 新增非空列必须有 DEFAULT |
+| **索引** | 新增索引考虑 CONCURRENTLY 模式 |
+| **备份** | 生产环境变更前先备份 |
+
+## 数据库命名规范
+
+| 对象 | 规范 | 示例 |
+|------|------|------|
+| 表名 | snake_case 复数 | `user_profiles`, `order_items` |
+| 列名 | snake_case | `created_at`, `is_active` |
+| 主键 | `id` (UUID v4) 或 `{table}_id` | `id`, `order_id` |
+| 外键 | `{referenced_table}_id` | `user_id`, `role_id` |
+| 索引 | `idx_{table}_{column}` | `idx_users_email`, `idx_orders_status_created` |
+| 唯一约束 | `uq_{table}_{columns}` | `uq_users_email` |
+| 时间戳 | `created_at`, `updated_at` | 统一命名 |
+| 布尔列 | `is_` / `has_` / `should_` 前缀 | `is_active`, `is_deleted`, `should_notify` |
+| 枚举 | 不用 ENUM 类型，用 CHECK 约束或外键表 | `CHECK (status IN ('active','inactive','banned'))` |

package/.harness/dev-map/backend/structure.md

@@ -0,0 +1,140 @@
+# 后端分区 — 模块划分与分层
+
+## 整体架构分层
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Controller Layer                  │
+│              (路由 / 参数解析 / 响应格式化)            │
+├─────────────────────────────────────────────────────┤
+│                     Service Layer                    │
+│              (业务逻辑 / 事务协调 / 编排)             │
+├─────────────────────────────────────────────────────┤
+│                   Repository Layer                   │
+│            (数据访问 / SQL 构建 / 缓存)              │
+├─────────────────────────────────────────────────────┤
+│                    Entity / Model                    │
+│              (数据结构 / 校验 / 序列化)               │
+└─────────────────────────────────────────────────────┘
+```
+
+## 目录结构
+
+```
+src/
+├── modules/                      # 按业务域分模块
+│   ├── user/                    # 用户模块
+│   │   ├── user.controller.ts   # 路由控制器
+│   │   ├── user.service.ts      # 业务逻辑
+│   │   ├── user.repository.ts   # 数据访问
+│   │   ├── user.entity.ts       # 数据实体
+│   │   ├── dto/                 # 数据传输对象
+│   │   │   ├── create-user.dto.ts
+│   │   │   ├── update-user.dto.ts
+│   │   │   └── query-user.dto.ts
+│   │   └── user.module.ts       # NestJS 模块定义
+│   │
+│   ├── auth/                    # 认证模块
+│   │   ├── auth.controller.ts
+│   │   ├── auth.service.ts
+│   │   ├── auth.strategy.ts
+│   │   └── ...
+│   │
+│   └── [domain]/               # 其他业务域...
+│
+├── common/                      # 公共模块
+│   ├── decorators/             # 自定义装饰器
+│   ├── filters/                # 异常过滤器
+│   ├── guards/                 # 守卫（认证/授权）
+│   ├── interceptors/           # 拦截器（日志/转换）
+│   ├── pipes/                  # 管道（验证/转换）
+│   └── utils/                  # 通用工具
+│
+├── database/                    # 数据库相关
+│   ├── migrations/             # 迁移文件
+│   └── seeds/                  # 种子数据
+│
+└── config/                      # 配置
+    ├── app.config.ts
+    ├── database.config.ts
+    └── redis.config.ts
+```
+
+## 模块职责边界
+
+| 层 | 职责 | 可以做 | 不能做 |
+|----|------|--------|--------|
+| **Controller** | 接收请求、返回响应 | 参数解析、调用 Service、HTTP 状态码 | 业务逻辑、SQL 查询 |
+| **Service** | 业务逻辑编排 | 调用多个 Repository、事务管理、外部服务调用 | HTTP 相关操作 |
+| **Repository** | 数据 CRUD | SQL/ORM 操作、数据库查询优化 | 业务判断 |
+| **Entity** | 数据结构定义 | 字段定义、关联关系、基础校验 | 业务流程逻辑 |
+| **DTO** | 数据传输 | 请求/响应的格式定义 | 数据转换以外的逻辑 |
+
+## 模块间依赖方向
+
+```
+         Controller
+             ↓ 调用
+           Service
+         ↙         ↘ 调用    Repository
+    Repository      外部服务
+         ↓
+       Entity
+         
+⚠️ 禁止：
+- Controller 直接调用 Repository
+- Service 之间循环依赖
+- 下层引用上层（Entity 引用 Service）
+```
+
+## 示例：完整模块实现骨架
+
+```typescript
+// modules/user/user.module.ts
+@Module({
+  controllers: [UserController],
+  providers: [UserService, UserRepository],
+  exports: [UserService],
+})
+export class UserModel {}
+
+// modules/user/user.service.ts
+@Injectable()
+export class UserService {
+  constructor(private readonly userRepo: UserRepository) {}
+
+  async findById(id: string): Promise<User> {
+    return this.userRepo.findById(id);
+  }
+
+  async create(dto: CreateUserDto): Promise<User> {
+    // 业务逻辑：检查唯一性等
+    const exists = await this.userRepo.findByEmail(dto.email);
+    if (exists) throw new ConflictException('Email already registered');
+    
+    // 密码加密
+    const hashedPassword = await hash(dto.password, 12);
+    
+    return this.userRepo.create({ ...dto, password: hashedPassword });
+  }
+}
+
+// modules/user/user.repository.ts
+@Injectable()
+export class UserRepository {
+  constructor(@InjectRepository(User) private repo: Repository<User>) {}
+
+  async findById(id: string): Promise<User | null> {
+    return this.repo.findOne({ where: { id }, select: ['id', 'name', 'email'] });
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.repo.findOne({ where: { email: email.toLowerCase() }});
+  }
+
+  async create(data: Partial<User>): Promise<User> {
+    const user = this.repo.create(data);
+    return this.repo.save(user);
+  }
+}
+```

package/.harness/dev-map/decisions.md

@@ -0,0 +1,275 @@
+# 技术决策记录 (ADR — Architecture Decision Records)
+
+> 每个重要技术决策都应该记录在这里。
+> 格式参考 Michael Nygard 的 ADR 模板。
+
+---
+
+## ADR-001: 采用 Pinia 作为 Vue3 前端状态管理
+
+- **状态**: 已采纳
+- **日期**: 2026-05-20
+- **决策者**: 技术团队
+
+### 背景
+Vue3 项目需要选择合适的状态管理方案。候选包括 Vuex 4（Vue3 兼容版）、Pinia（Vue 官方推荐新一代）、以及轻量级组合式 API 方案。
+
+### 决策
+采用 **Pinia** 作为主要状态管理方案，配合 Composition API (`ref`/`reactive`/`computed`) 处理组件局部状态。
+
+### 备选方案对比
+
+| 维度 | Vuex 4 | Pinia | Composition API (无库) |
+|------|--------|-------|----------------------|
+| 样板代码 | 多 (mutations/actions) | 极少 | 无 |
+| TypeScript 支持 | 需要额外装饰器 | 原生推断优秀 | 原生支持 |
+| DevTools | Vue DevTools 原生集成 | Vue DevTools 原生集成 | 有限 |
+| 模块化 | namespaced modules | 每个 Store 独立文件 | N/A |
+| 学习成本 | 中 | 低 | 低 (但大型状态难管理) |
+| 包体积 | ~5KB gzip | ~1KB gzip | 0 |
+| Vue3 组合式友好度 | ★★ | ★★★★★ | ★★★★★ |
+
+### 理由
+- **Vue 官方推荐**：Pinia 是 Vuely 团队打造的 Vuex 继任者，已进入官方生态
+- **Composition API 原生设计**：Store 定义用 `defineStore()` + setup 函数，与组件 `<script setup>` 风格一致
+- **更好的 TS 推断**：无需手动声明接口，store state/action/getter 类型自动推导
+- **更简洁 API**：去掉了 mutation，直接 dispatch action 修改 state
+- **Code Splitting 友好**：Store 可按需懒加载
+
+### 后果
+- **正面**：减少样板代码、更快的开发体验、优秀的 DX、与 Vue3 生态完美融合
+- **负面**：相比 Vuex 4 社区迁移案例较少（但新项目无此问题）
+- **风险**：低 — Pinia 已非常成熟，大量 Vue3 生产项目在使用
+
+### 使用约定
+```
+stores/
+├── useUserStore.ts      # 用户状态
+├── useAuthStore.ts      # 认证状态  
+└── index.ts             # Store 实例导出 (pinia 实例)
+```
+
+---
+
+## ADR-002: JWT 双 Token 认证方案
+
+- **状态**: 已采纳
+- **日期**: 2026-05-20
+- **决策者**: 安全架构师
+
+### 背景
+需要选择合适的认证方案来保护 API 和用户会话。
+
+### 决策
+采用 **JWT Access Token (短期) + Opaque Refresh Token (长期)** 的双 Token 方案。
+
+### 备选方案对比
+
+| 方案 | 安全性 | 性能 | 复杂度 | 可撤销性 |
+|------|--------|------|--------|----------|
+| Session Cookie | ★★★★★ | ★★★ | ★★ | ★★★★★ |
+| 单 JWT | ★★★ | ★★★★★ | ★★★★★ | ★ |
+| 双 JWT (Access+Refresh) | ★★★★ | ★★★★ | ★★★ | ★★★ |
+| **双 Token (JWT+Opaque)** | **★★★★★** | **★★★★** | **★★★** | **★★★★★** ← 选中 |
+
+### 理由
+- Access Token 短有效期（15min），即使泄露影响有限
+- Refresh Token 存储在 DB + HttpOnly Cookie，可随时吊销
+- 每次轮换 Refresh Token，发现异常可立即撤销
+- 无需服务端 Session 存储（相比纯 Session 方案节省内存）
+
+### 后果
+- 需要维护 sessions 表
+- 需要处理 Token 并发刷新问题
+- 需要在移动端和 Web 端分别适配 Cookie / LocalStorage 策略
+
+---
+
+## ADR-003: API 版本化采用 URL 路径策略
+
+- **状态**: 已采纳
+- **日期**: 2026-05-20
+
+### 决策
+API 版本号放在 URL 路径中：`/api/v1/...`, `/api/v2/...`
+
+### 理由
+- 直观明确，易于调试
+- CDN 和代理可以按路径做不同缓存策略
+- 前端可以同时对接多版本（渐进迁移）
+- 业界主流做法（GitHub, Stripe, Slack 等）
+
+### 后果
+- URL 变长
+- 需要在反向代理层面做好路由转发
+- OpenAPI 文档需要按版本分开维护
+
+---
+
+## ADR-004: 双技术栈架构 — 前端 Vue3 + 后端 Spring Boot(JDK21)
+
+- **状态**: 已采纳
+- **日期**: 2026-05-21
+- **决策者**: 技术团队
+
+### 背景
+项目从纯前端扩展为全栈应用，后端技术选型需要确定。团队具备 Java 生态经验，企业基础设施也以 JVM 为主。
+
+### 决策
+采用 **Vue3 + Vite(前端)** + **Spring Boot 3.x + JDK21 + Maven(后端)** 的双技术栈并行架构。
+
+### 备选方案对比
+
+| 方案 | 团队熟悉度 | 企业基建匹配 | 性能 | 生态成熟度 |
+|------|-----------|-------------|------|-----------|
+| Node.js (NestJS/Express) | ★★★★ | ★★★ | ★★★★ | ★★★★ |
+| Go (Gin/Echo) | ★★★ | ★★★ | ★★★★★ | ★★★ |
+| Python (FastAPI/Django) | ★★★ | ★★ | ★★★ | ★★★★ |
+| **Spring Boot 3 + JDK21** | **★★★★★** | **★★★★★** | **★★★★** | **★★★★★** ← 选中 |
+
+### 理由
+- JDK21 Virtual Threads 提升并发吞吐，适合 IO 密集型业务
+- Spring Boot 3 原生 GraalVM 支持，未来可迁移 Native Image
+- 企业 CI/CD 已有 Maven/SonarQube/Jenkins 完整工具链
+- 与前端独立部署，解耦迭代节奏
+
+### 后果
+- **正面**: 团队上手快、企业基建零成本接入、生态完善
+- **负面**: 构建产物较大(JRE ~50MB+)、启动时间比 Go/Node 慢
+- **风险**: 需要维护两套 CI 流水线
+- **依赖**: JDK21+、Maven 3.8+、MySQL 8.0+、Redis 7+
+
+---
+
+## ADR-005: Gate 门禁分流检测 — 按项目类型自动路由
+
+- **状态**: 已采纳
+- **日期**: 2026-05-21
+- **决策者**: 架构师
+
+### 背景
+原 `build-gates.js` 仅支持前端检测(tsc/npm/eslint)。Java 后端加入后需要编译检查(mvn)、单元测试(JUnit)、代码风格(Checkstyle/PMD)、静态分析(SpotBugs)等不同维度的门禁。如果混在同一个文件中会变得臃肿难维护。
+
+### 决策
+将 Gate 拆分为 **路由器 + 两个专用模块**：
+```
+gate/checks/
+├── build-gates.js          ← 路由器: detectProjectType() 自动检测
+├── build-gates-frontend.js ← 前端门禁: tsc / npm ls / build / eslint / audit
+└── build-gates-java.js     ← Java门禁: mvn compile / test / checkstyle / dependency / spotbugs / jacoco
+```
+
+### 路由检测策略
+
+| 检测文件 | 判定类型 | 分发目标 |
+|---------|---------|---------|
+| `pom.xml` 存在 | `java` | `build-gates-java.js` |
+| `package.json` 存在 | `frontend (node)` | `build-gates-frontend.js` |
+| `build.gradle` / `build.gradle.kts` 存在 | `gradle` | (预留) |
+
+### 理由
+- 单一职责：每个门禁文件只关注一种技术栈的检查逻辑
+- 可扩展：未来加 Gradle/.NET 只需新增文件 + 路由规则
+- 自动化：无需手动指定参数，脚本自动识别当前目录的项目类型
+
+### 后果
+- **正面**: 代码清晰易维护、新技术栈接入成本低
+- **负面**: 多了一层路由间接调用
+- **风险**: 低 — detectProjectType() 逻辑简单可靠
+
+---
+
+## ADR-006: Workflow 直接按技术栈引用 Skill（去中间路由）
+
+- **状态**: 已采纳
+- **日期**: 2026-05-21
+- **决策者**: 架构师
+
+### 背景
+原 workflow 的 Step4(Build) 引用通用的 `build.md` skill，而 `build.md` 内部再按技术栈分发到具体文档。这增加了一层间接跳转，且 `build.md` 本身内容单薄（仅一行 `mvn compile`），实际价值低。
+
+### 决策
+Workflow definition.yaml 中 **直接条件引用技术栈专属 skill**：
+```yaml
+# Before
+skill: build
+
+# After (条件引用)
+skill: "java-build | vue-frontend-build"   # 由 Agent 根据项目类型选择
+```
+
+同时将原 `skills/build.md` 标记为 **DEPRECATED**（废弃），重定向到 `java-build.md` 和 `vue-frontend-build.md`。
+
+### 理由
+- 减少 indirection：Agent 不需要先读 `build.md` 再跳转
+- 输出格式对齐：workflow output_formats 新增 `.java`，与实际产出一致
+- 规则引用补齐：development/testing 阶段 rules_referenced 增加 `rules/project/java-backend.md`
+
+### 后果
+- **原有 `build.md` 废弃但保留**，避免外部引用断裂
+- workflow 更新后需同步更新 agents/developer/contract.yaml 的输出格式定义
+
+---
+
+## ADR-007: Java 后端质量保障工具链选型
+
+- **状态**: 已采纳
+- **日期**: 2026-05-21
+- **决策者**: QA Tech Lead
+
+### 背景
+Java 后端需要覆盖「编译 → 测试 → 风格 → 静态分析 → 覆盖率」完整质量链。每个环节有多个候选工具需要统一选型。
+
+### 决策
+
+| 质量维度 | 选型工具 | 版本要求 | 理由 |
+|---------|---------|---------|------|
+| 单元测试 | **JUnit 5** + Mockito 5 | JUnit 5.10+, Mockito 5.x | 业界标准，Spring Boot 原生集成 |
+| BDD 验证 | **BDDMockito** | — | then()/should() 语法更可读 |
+| 集成测试 | **Spring Boot Test** (@Testcontainers) | 3.2+ | 真实 MySQL/Redis 容器隔离 |
+| 代码覆盖率 | **JaCoCo** | 0.8.11+ | Maven 插件原生集成，0% 文件告警 |
+| 代码风格 | **Checkstyle** | 10.x | Google/Sun 规则集可定制 |
+| 缺陷扫描 | **PMD** + **SpotBugs** | PMD 7.x / SpotBugs 4.8+ | PMD 管复杂度，SpotBugs 管 NPE/空指针等 Bug 模式 |
+| 持续质检 | **SonarQube** | 9.9+ LTS | Quality Gate 阻断 + 技术债追踪 |
+| API 测试 | **REST Assured** | 5.x | DSL 风格，与 MockMvc 无缝对接 |
+| 服务端 Mock | **WireMock** | 3.x | 下游依赖 Stub，契约测试基础 |
+| DB 迁移 | **Flyway** | 10.x | 版本化 SQL 脚本，CI 可回滚 |
+
+### 后果
+- **pom.xml** 会变长：需配置 maven-checkstyle/pmd/spotbugs/jacoco/sonar 等约 10 个插件
+- **首次配置成本高**，但后续零维护——所有开发者 `mvn verify` 一条命令跑完所有检查
+- MCP 层需注册 sonarqube/maven 工具定义供 AI Agent 调用查询
+
+---
+
+## ADR 模板（供后续使用）
+
+```markdown
+## ADR-NNN: {决策标题}
+
+- **状态**: [提议中 / 已采纳 / 已废弃 / 已替代]
+- **日期**: {YYYY-MM-DD}
+- **决策者**: {角色/姓名}
+
+### 背景
+{描述驱动这个决策的背景和上下文}
+
+### 决策
+{简短描述做出的决定}
+
+### 备选方案
+{列出考虑过的替代方案及其优劣}
+
+### 理由
+{解释为什么选择这个方案而非其他}
+
+### 后果
+- **正面**:
+- **负面**:
+- **风险**:
+- **依赖**:
+
+### 相关链接
+- Issue/PR: #{number}
+- 讨论: [link]
+```

package/.harness/dev-map/frontend/api-integration.md

@@ -0,0 +1,139 @@
+# 前端分区 — API 调用规范
+
+## 统一 API 客户端
+
+所有 API 调用必须经过封装后的客户端实例：
+
+```typescript
+// lib/api-client.ts
+import axios from 'axios';
+import { getAuthToken } from './auth';
+
+const apiClient = axios.create({
+  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || '/api/v1',
+  timeout: 15000,
+  headers: {
+    'Content-Type': 'application/json',
+  },
+});
+
+// 请求拦截器 — 自动附加认证 token
+apiClient.interceptors.request.use((config) => {
+  const token = getAuthToken();
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+
+// 响应拦截器 — 统一错误处理
+apiClient.interceptors.response.use(
+  (response) => response.data, // 直接返回 data 部分
+  (error) => {
+    // Token 过期自动跳转登录
+    if (error.response?.status === 401) {
+      window.location.href = '/login?redirect=' + encodeURIComponent(window.location.pathname);
+    }
+    
+    // 统一错误格式
+    const message = error.response?.data?.message || error.message || '请求失败';
+    return Promise.reject(new Error(message));
+  }
+);
+
+export default apiClient;
+```
+
+## API 调用约定
+
+### GET 请求
+
+```typescript
+import apiClient from '@/lib/api-client';
+
+interface UserListParams {
+  page?: number;
+  pageSize?: number;
+  role?: string;
+  keyword?: string;
+}
+
+interface UserListResponse {
+  code: number;
+  data: {
+    items: User[];
+    total: number;
+    page: number;
+    pageSize: number;
+  };
+}
+
+async function getUserList(params?: UserListParams): Promise<UserListResponse['data']> {
+  return apiClient.get('/users', { params });
+}
+```
+
+### POST/PUT/DELETE 请求
+
+```typescript
+async function createUser(data: CreateUserDTO): Promise<User> {
+  return apiClient.post('/users', data);
+}
+
+async function updateUser(id: string, data: UpdateUserDTO): Promise<User> {
+  return apiClient.put(`/users/${id}`, data);
+}
+
+async function deleteUser(id: string): Promise<void> {
+  return apiClient.delete(`/users/${id}`);
+}
+```
+
+### 文件上传
+
+```typescript
+async function uploadAvatar(file: File): Promise<{ url: string }> {
+  const formData = new FormData();
+  formData.append('file', file);
+  
+  return apiClient.post('/upload/avatar', formData, {
+    headers: { 'Content-Type': 'multipart/form-data' },
+    timeout: 60000, // 文件上传超时更长
+  });
+}
+```
+
+## 错误处理策略
+
+| HTTP 状态码 | 处理方式 | 用户提示 |
+|-------------|----------|----------|
+| 400 | 表单字段级错误展示 | 字段下方显示具体错误信息 |
+| 401 | 跳转登录页 | "登录已过期，请重新登录" |
+| 403 | 显示权限不足页 | "您没有权限执行此操作" |
+| 404 | 显示 404 页面 | "请求的资源不存在" |
+| 422 | 表单验证错误 | 字段级错误展示 |
+| 429 | 显示限流提示 | "操作太频繁，请稍后再试" |
+| 500 | 显示通用错误页 | "服务器出了点问题，请稍后重试" |
+| 网络异常 | 显示离线提示 | "网络连接失败，请检查网络" |
+
+## 取消重复请求
+
+```typescript
+// 使用 AbortController 取消未完成的请求
+function useSearchUsers() {
+  const abortRef = useRef<AbortController | null>(null);
+
+  return useCallback(async (keyword: string) => {
+    // 取消上一次请求
+    abortRef.current?.abort();
+    
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    return apiClient.get('/users/search', {
+      params: { q: keyword },
+      signal: controller.signal,
+    });
+  }, []);
+}
+```