# 类型定义规范

> 前端请求参数、响应数据类型以及页面数据模型的定义规范。

---

## 命名原则

- 类型名要体现用途，例如 `LoginParams`、`OrderListItem`、`UserDetailResponse`
- 优先使用业务语义命名，不用后端传输层术语硬套前端场景
- 名称要与实际使用场景一致，不要出现“通用类型”却只服务单一页面的情况
- 页面私有类型优先就近定义在页面目录；全局复用类型再抽到公共位置

---

## 字段设计原则

- 只保留当前页面、组件、Hook 真实需要的字段
- 字段语义必须单一明确，不要一个字段承担多种含义
- 嵌套对象只在确实提升可读性时使用，避免过深层级
- 能用稳定基础类型表达的，不要额外包一层无意义对象
- 禁止为了“以后可能会用”提前塞入无消费方字段

---

## 类型边界

- 区分“接口原始返回类型”和“页面消费后的展示类型”
- 不要把后端所有字段原样铺到页面组件 props 中
- 页面展示需要格式化、组合、兜底时，应在 `utils/` 或 `hooks/` 做转换
- 同一个后端实体被多个页面以不同方式使用时，允许定义多个前端视图类型

---

## 默认值与可选值

- 可选字段要明确标注 `?`，不要靠调用方猜测
- 默认值策略必须显式，不要把隐式兜底散落在多个组件里
- 会影响页面分支逻辑的字段，必须明确说明为空时的处理方式
- 列表字段默认值、布尔字段默认值、文本占位值等应在消费层统一处理

---

## 映射规范

- 映射的目标是让页面更好用，不是机械复制后端结构
- 不要保留“临时透传字段”或无人消费的中间字段
- 若多个页面需要不同数据形状，应该拆成不同类型，而不是堆成一个超大类型
- 时间、金额、状态文案等展示型字段，优先通过派生字段生成，避免在组件内部重复处理

## 前端类型安全

- 禁止在新增代码中使用无约束的 `any`
- 对枚举值、状态值、字典值，优先用联合类型或 `enum` 明确约束
- 组件 Props 类型要最小化，只暴露组件真正需要的数据
- 需要缓存、比较、序列化的数据结构，应保持简单、稳定、可预期

## 示例

```ts
export type KnowledgeListParams = {
  keyword?: string;
  pageNo: number;
  pageSize: number;
};

export type KnowledgeListItem = {
  id: string;
  title: string;
  status: "draft" | "published";
  updatedAt: string;
};
```