yash-types

璞瑞雅诗（PureRhyme）前后端共享 TypeScript 类型定义包。

🎯 项目概述

此包包含璞瑞雅诗电商平台的所有 API 相关类型定义，确保前后端类型完全一致，提供完整的类型安全保障。

📦 安装

npm install yash-types
# 或
pnpm add yash-types
# 或
yarn add yash-types

🚀 使用方式

前端使用 (React)

import type { 
  IAccountRequest, 
  IAccountResponse, 
  IResponse,
  IProduct,
  ICartProduct 
} from 'yash-types';

// API 调用示例
async function createAccount(params: IAccountRequest): Promise<IResponse<IAccountResponse>> {
  const response = await fetch('/api/user/create', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(params)
  });
  
  return response.json();
}

// Zustand Store 示例
import { create } from 'zustand';

interface CartState {
  items: ICartProduct[];
  addItem: (item: ICartProduct) => void;
  removeItem: (skuId: string) => void;
}

export const useCartStore = create<CartState>((set) => ({
  items: [],
  addItem: (item) => set((state) => ({ 
    items: [...state.items, item] 
  })),
  removeItem: (skuId) => set((state) => ({ 
    items: state.items.filter(item => item.id !== skuId) 
  }))
}));

后端使用 (Midway.js)

import type { 
  IAccountRequest, 
  IAccountResponse, 
  IResponse 
} from 'yash-types';
import {
  Body,
  Controller,
  Inject,
  Post,
  HttpServerResponse,
  Get,
  Del,
  Param,
  Put,
} from '@midwayjs/core';

@Controller('/address')
export class AddressController {
  @Inject()
  ctx: Context;

  @Inject()
  addressService: AddressService;

  /**
   * 获取用户id
   */
  getUserId() {
    const user = this.ctx.state.user;
    return user?.id;
  }

  /**
   * 添加收货地址
   * @param {Partial<Address>} address - 地址信息
   * @returns {Promise<HttpServerResponse>} - 返回添加后的地址信息
   */
  @Post('/add')
  async addAddress(@Body() address: Partial<Address>) {
    const userId = this.getUserId();
    const resp = await this.addressService.addAddress({
      userId,
      address,
    });
    return new HttpServerResponse(this.ctx).json(resp);
  }
}

📚 类型分类

基础类型 (/common)

• CommonInfo<T> - 通用信息结构
• PageRequest - 分页请求参数
• IResponse<T> - 统一 API 响应格式
• Timestamp - 时间戳类型

枚举定义 (/common/enums)

• PaymentMethod - 支付方式
• OrderStatus - 订单状态
• Gender - 性别
• UserCenterTab - 用户中心标签
• ProductEnum - 产品枚举
• Locale - 语言设置

API 类型 (/api)

用户模块 (/api/user)

• IAccountRequest - 账户创建请求
• IAccountResponse - 账户信息响应
• AccountUser - 当前登录用户
• UpdateUserPasswordRequest - 密码更新请求

产品模块 (/api/product)

• IProduct - 产品基础信息
• SKU - 产品规格信息
• IProductSKU - 包含SKU的产品信息
• IProductResponse - 产品列表响应

购物车模块 (/api/cart)

• ICartProduct - 购物车商品
• ICartProductResponse - 购物车列表响应
• AddCartRequest - 添加到购物车请求

订单模块 (/api/order)

• CreateOrder - 创建订单请求
• IOrder - 订单基础信息
• IOrderResponse - 订单列表响应

地址模块 (/api/address)

• IAddress - 地址信息
• AddAddressRequest - 添加地址请求
• UpdateAddressRequest - 更新地址请求

支付模块 (/api/payment)

• PayOrderParamsRequest - 支付订单请求
• PayOrderParamsResponse - 支付订单响应
• PaymentNotification - 支付结果通知

微信模块 (/api/wechat)

• WechatSDKConfig - 微信SDK配置
• WechatQRCodeResponse - 微信二维码响应
• WechatUserInfo - 微信用户信息

验证模块 (/api/email, /api/sms)

• SendEmailCodeRequest - 发送邮件验证码
• VerifyEmailCodeRequest - 验证邮件验证码
• SendSMSCodeRequest - 发送短信验证码
• VerifySMSCodeRequest - 验证短信验证码

工具类型 (/utils)

• PartialBy<T, K> - 使某些属性可选
• RequiredBy<T, K> - 使某些属性必需
• DeepReadonly<T> - 深度只读
• ApiResponseData<T> - API响应数据类型提取

🔧 本地开发

开发环境要求

• Node.js >= 22.0.0
• TypeScript >= 5.0.0

安装依赖

pnpm install

构建项目

pnpm build

监听模式

npm dev

本地链接调试

# 创建全局链接
pnpm link:dev

# 在其他项目中使用
pnpm link --global yash-types

📝 版本管理

更新版本

# 补丁版本 (1.0.0 -> 1.0.1)
npm run version:patch

# 次版本 (1.0.0 -> 1.1.0)
npm run version:minor

# 主版本 (1.0.0 -> 2.0.0)
npm run version:major

发布到 npm

npm run publish:npm

🛠️ 开发工作流

日常开发流程

1. 修改类型定义
2. 构建并测试
3. 在前后端项目中验证
4. 提交变更
5. 发布新版本

最佳实践

1. 向后兼容: 尽量保持向后兼容，避免破坏性更改
2. 语义化版本: 遵循语义化版本规范
3. 文档更新: 重要更改需要更新 README 和 CHANGELOG
4. 类型验证: 使用 TypeScript 严格模式确保类型安全

🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交变更 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

📄 许可证

本项目基于 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 支持

如果您在使用过程中遇到问题，请：

1. 查看 Issues
2. 创建新的 Issue
3. 联系维护团队

璞瑞雅诗技术团队 ❤️