@yorkjs/hive-biz 0.1.8 → 0.2.0

package/types/selector/customSpecSelector.d.ts

@@ -1,5 +1,16 @@
 import { ICartListItem, IProductSelectedCustomizationItem } from './type';
 import { ICountChangeResult, IAddToCartParamsResult, ICustomSpecSelectorView, ICustomSpecSelectorOptions, IFetchCustomCartCountParams, IFetchCartCountResult, IFetchMemberPriceParams } from './type';
+/**
+ * 做法加料商品规格选择器
+ *
+ * 设计原则：类内部不发起任何接口请求，所有数据处理逻辑封装在此，
+ * 网络请求由 UI 层发起，将结果通过公开方法回填。
+ *
+ * 与 ComboSpecSelector 的差异：
+ * - productData 已包含做法数据，初始化时无需额外接口
+ * - 支持活动 sku（promotionActivityProduct）
+ * - 购物车参数含 product_customization_item_list
+ */
 export declare class CustomSpecSelector {
     private product;
     private promotionActivityProduct;
@@ -29,33 +40,81 @@ export declare class CustomSpecSelector {
     private negativeStockSaleEnabled?;
     private onChange;
     constructor(options: ICustomSpecSelectorOptions);
+    /**
+     * 设置购物车列表，当购物车数据变化时调用
+     * 会根据当前选中的规格和做法重新匹配购物车数据
+     */
     setCartList(cartList: ICartListItem[]): void;
+    /**
+     * 初始化（做法加料商品无需额外接口请求，productData 已包含全部数据）
+     * 调用后触发 onChange，UI 可通过 getView() 拿到渲染数据；
+     * 但购物车数据需 UI 层调用 buildCartCountParams() 拿参数后自行请求。
+     */
     init(): void;
     getView(): ICustomSpecSelectorView;
+    /**
+     * 选择规格（纯数据处理）
+     * @returns needFetchCart 是否需要刷新购物车数（为 true 时同样需要重新请求会员价）；cartParams 购物车查询参数
+     */
     handleSelectSpecs(isOption: boolean, value: string, index: number): {
         needFetchCart: boolean;
         cartParams: IFetchCustomCartCountParams;
     };
+    /**
+     * 用购物车查询结果更新内部状态
+     */
     updateCartCountData(result: IFetchCartCountResult): void;
+    /**
+     * 用会员价查询结果更新内部状态，由 UI 层请求会员价接口后调用
+     * @param price 会员价，请求失败或无会员价时传 undefined
+     */
     updateMemberPrice(price: number | undefined): void;
+    /**
+     * 做法选中变化（纯数据处理）
+     * @returns isValid 校验是否通过；cartParams 若通过则返回购物车查询参数
+     */
     handleCustomizationItemListSelect(customizationItemList: IProductSelectedCustomizationItem[][]): {
         isValid: boolean;
         cartParams?: IFetchCustomCartCountParams;
     };
+    /**
+     * 数量变化（纯逻辑，返回操作结果供 UI 决策）
+     */
     handleProductCountChange(count: number, type: string): ICountChangeResult;
+    /**
+     * 加入购物车前校验，返回提交所需参数
+     * 由 UI 层使用参数调用 addToCart 接口
+     */
     getAddToCartParams(productId: number, promotionActivityProductId?: number): IAddToCartParamsResult;
     getSalePrice(): number;
     getOriginalPrice(): number;
     getMemberPrice(): number | undefined;
     getSelectedSpecAndCustomization(): string;
     buildCartCountParams(): IFetchCustomCartCountParams;
+    /**
+     * 构造会员价查询参数（供 UI 层使用）
+     * sku 未选中时返回 undefined
+     */
     buildMemberPriceParams(): IFetchMemberPriceParams | undefined;
     private _initProductData;
     private _updateSkuData;
     private _checkProductCount;
     private _selectSpec;
     private _notifyChange;
+    /**
+     * 获取当前 sku 类型，活动 sku 返回活动类型，否则返回商城类型
+     */
     private _getSkuType;
+    /**
+     * 从购物车列表中查找匹配的购物车项
+     * 匹配逻辑：
+     * 1. 判断购物车商品是否是当前商品（优先使用活动商品 id 比较）
+     * 2. 判断 sku_id 是否一样（优先使用活动 sku_id）
+     * 3. 比较做法值列表是否相等（数组长度一致，且 id 和 count 一致）
+     */
     private _findSkuCartItem;
+    /**
+     * 更新当前 sku 对应的购物车数据
+     */
     private _updateSkuCartItem;
 }

package/types/selector/specSelector.d.ts

@@ -1,17 +1,26 @@
 import { ISpecList, ISkuCombination, IProductSpecItem } from './type';
 export interface ISpecSelectorOptions {
+    /** 规格组列表，包含每组规格标题和可选值 */
     productSpecGroupList: ISpecList[];
+    /** 格式化后的 sku 组合列表 */
     skuListAfter: ISkuCombination[];
+    /** 活动规格列表，二维数组，与 productSpecGroupList 下标对应 */
     activitySpecList?: IProductSpecItem[][];
 }
 export interface ISpecItemState {
+    /** 规格值 */
     value: string;
+    /** 是否可选（未被禁用） */
     isEnabled: boolean;
+    /** 是否已选中 */
     isActive: boolean;
+    /** 是否是活动规格 */
     isActivitySpec: boolean;
 }
 export interface ISpecGroupState {
+    /** 规格组标题 */
     title: string;
+    /** 该组下所有规格项的状态 */
     items: ISpecItemState[];
 }
 export declare class SpecSelector {
@@ -20,10 +29,38 @@ export declare class SpecSelector {
     private activitySpecList;
     private specAdjoinMatrix;
     constructor(options: ISpecSelectorOptions);
+    /**
+     * 判断某个规格值是否是活动规格
+     * @param listIndex 规格组下标
+     * @param value 规格值
+     */
     isActivitySpec(listIndex: number, value: string): boolean;
+    /**
+     * 根据当前已选规格，获取所有规格组的渲染状态
+     * @param selectedSpecs 当前已选规格值数组
+     */
     getSpecGroupStateList(selectedSpecs: string[]): ISpecGroupState[];
+    /**
+     * 根据当前已选规格，获取可选规格值列表（扁平数组）
+     * @param selectedSpecs 当前已选规格值数组
+     */
     getOptionSpecs(selectedSpecs: string[]): string[];
+    /**
+     * 处理规格选择/取消选择，返回新的已选规格数组
+     * @param isEnabled 当前规格是否可选
+     * @param value 被点击的规格值
+     * @param groupIndex 规格组下标
+     * @param selectedSpecs 当前已选规格值数组
+     */
     toggleSpec(isEnabled: boolean, value: string, groupIndex: number, selectedSpecs: string[]): string[];
+    /**
+     * 根据当前已选规格找到匹配的 sku 组合
+     * @param selectedSpecs 当前已选规格值数组
+     */
     findMatchedSku(selectedSpecs: string[]): ISkuCombination | undefined;
+    /**
+     * 判断规格是否已全部选完
+     * @param selectedSpecs 当前已选规格值数组
+     */
     isAllSpecSelected(selectedSpecs: string[]): boolean;
 }

package/types/selector/type.d.ts

@@ -257,17 +257,26 @@ export interface IProductSpecGroup {
     has_image: number;
     items: IProductSpecItem[];
 }
+/**
+ * 做法值基础接口定义
+ */
 export interface ICustomizationItemBase {
     id: number;
     name: string;
     increase_type: number;
     increase_sale_price: number;
 }
+/**
+ * 做法值接口定义
+ */
 export interface ICustomizationBase {
     id: number;
     name: string;
     count_type: number;
 }
+/**
+ * 做法项接口定义 - 做法设置页面
+ */
 export interface ICustomizationItem {
     id: number;
     customization_item: ICustomizationItemBase;
@@ -278,6 +287,9 @@ export interface ICustomizationItem {
     min_count: number;
     max_count: number;
 }
+/**
+ * 做法组接口定义 - 做法设置页面
+ */
 export interface IProductCustomizationGroupItem {
     id: number;
     customization: ICustomizationBase;
@@ -340,17 +352,21 @@ export interface IAddCartParams {
     productCustomizationItemList?: ISubmitSelectedCustomizationItem[];
     skuComboItemList?: ISelectSkuComboItem[][];
 }
+/** 数量变化操作结果 */
 export interface ICountChangeResult {
     isValid: boolean;
     errMsg?: string;
+    /** 需要修改购物车时，由 UI 层调用 changeCartCount 接口传入 */
     cartItem?: ICartListItem;
     count?: number;
 }
+/** 加入购物车前校验结果 */
 export interface IAddToCartParamsResult {
     isValid: boolean;
     errMsg?: string;
     params?: IAddCartParams;
 }
+/** 套餐商品 Selector 初始化选项 */
 export interface IComboSpecSelectorOptions {
     productData: {
         product: IProduct;
@@ -364,6 +380,7 @@ export interface IComboSpecSelectorOptions {
     onChange: SelectorChangeCallback;
     validateComboGroupList: () => string;
 }
+/** 做法加料商品 Selector 初始化选项 */
 export interface ICustomSpecSelectorOptions {
     productData: {
         product: IProduct;
@@ -378,6 +395,7 @@ export interface ICustomSpecSelectorOptions {
     channel1Type: number;
     onChange: SelectorChangeCallback;
 }
+/** 套餐商品 UI 渲染数据 */
 export interface IComboSpecSelectorView {
     product: IProduct;
     skuId: number;
@@ -393,8 +411,10 @@ export interface IComboSpecSelectorView {
     maxCount: number;
     isComponentLoading: boolean;
     visibleComboInfo: boolean;
+    /** 会员价，sku 变化后重置为 undefined，需 UI 层重新请求回填 */
     memberPrice: number | undefined;
 }
+/** 做法加料商品 UI 渲染数据 */
 export interface ICustomSpecSelectorView {
     product: IProduct;
     promotionActivityProduct: IPromotionActivityProduct | undefined;
@@ -412,9 +432,11 @@ export interface ICustomSpecSelectorView {
     cartCount: number;
     maxCount: number;
     cartItem: ICartListItem | undefined;
+    /** 会员价，sku 变化后重置为 undefined，需 UI 层重新请求回填 */
     memberPrice: number | undefined;
 }
 export type SelectorChangeCallback = () => void;
+/** 套餐商品购物车查询参数 */
 export interface IFetchCartCountParams {
     channel1_type: number;
     checked: number;
@@ -423,6 +445,7 @@ export interface IFetchCartCountParams {
     sku_combo_item_list: string;
     cart: number;
 }
+/** 做法加料商品购物车查询参数 */
 export interface IFetchCustomCartCountParams {
     channel1_type: number;
     checked: number;
@@ -431,6 +454,7 @@ export interface IFetchCustomCartCountParams {
     product_customization_item_list: string;
     cart: number;
 }
+/** 购物车查询返回结果 */
 export interface IFetchCartCountResult {
     cart?: {
         id: number;
@@ -439,6 +463,7 @@ export interface IFetchCartCountResult {
     };
     [key: string]: any;
 }
+/** 会员价查询参数 */
 export interface IFetchMemberPriceParams {
     sku_id: number;
     sku_type: number;

package/types/util/specAdjoinMartix.d.ts

@@ -3,6 +3,9 @@ export default class SpecAdjoinMatrix extends AdjoinMatrix {
     specList: never[];
     specCombinationList: never[];
     constructor(specList: any, specCombinationList: any);
+    /**
+     * 根据可选规格组合填写邻接矩阵的值
+     */
     initSpec(): void;
     initSameLevel(): void;
     getSpecsOptions(params: any): string[];