@yorkjs/hive-biz 0.1.8 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yorkjs/hive-biz",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "util function",
   "main": "dist/hive-biz.esm.js",
   "module": "dist/hive-biz.esm.js",

package/types/coupon/availableRepeat.d.ts

@@ -1,12 +1,28 @@
 export interface IFormatAvailableRepeatOptions {
+    /** 重复类型：0 每天 / 1 每周 / 2 每月 */
     repeatType?: number;
+    /** 周几或每月几号；周：0-6，月：1-28。也可传接口 JSON 字符串 */
     repeatValue?: Array<number | string> | string;
+    /** 日内时段，一维 [start, end, ...]，单位分钟 */
     minuteSegments?: Array<number | string> | string;
 }
+/** 00:00-24:00 或 00:00-23:59 都视为全天 */
 export declare function isFullDayMinuteSegment(start: number, end: number): boolean;
+/**
+ * 接口里的周几 / 日期 / 时段可能是 number[] 或 JSON 字符串。
+ * formatItem 原样搬运即可，这里统一收成 number[]。
+ */
 export declare function parseCouponNumberList(value?: Array<number | string> | string): number[];
+/** 仅日期部分，不含时段。按天且未选具体日时返回空，由调用方补「每天」 */
 export declare function formatAvailableRepeatDateText(options?: IFormatAvailableRepeatOptions): string;
+/**
+ * 日期 + 时段拼成一句，次卡列表等场景用。
+ * 例：工作日08:00-11:00；都空时「全天」
+ */
 export declare function formatAvailableRepeatText(options?: IFormatAvailableRepeatOptions): string;
+/**
+ * 使用次数限制。例：每日2次、每周3次、每月5次；都没有则「不限制」
+ */
 export declare function formatUseLimitText(options?: {
     daily?: number | string;
     weekly?: number | string;

package/types/coupon/constant.d.ts

@@ -1,25 +1,62 @@
+/** 折扣券。对齐 coupon_type = 1，走折扣票面 */
 export declare const COUPON_TYPE_DISCOUNT = 1;
+/** 满减券。对齐 coupon_type = 2，走金额票面 */
 export declare const COUPON_TYPE_AMOUNT = 2;
+/** 配送券。对齐 coupon_type = 3，走金额票面 */
 export declare const COUPON_TYPE_FREIGHT = 3;
+/** 使用门槛：按金额。对齐 threshold_type */
 export declare const COUPON_THRESHOLD_TYPE_AMOUNT = 1;
+/** 使用门槛：按件数。对齐 threshold_type */
 export declare const COUPON_THRESHOLD_TYPE_COUNT = 2;
-export declare const COUPON_EXPIRE_START_TYPE_NOW = 1;
-export declare const COUPON_EXPIRE_START_TYPE_FUTURE = 2;
-export declare const COUPON_EXPIRE_END_TYPE_FOREVER = 1;
-export declare const COUPON_EXPIRE_END_TYPE_FUTURE = 2;
-export declare const COUPON_EXPIRE_END_TYPE_EXTEND = 3;
+/** 生效开始：立即。对齐 effective_start_type */
+export declare const COUPON_EFFECTIVE_START_TYPE_NOW = 1;
+/** 生效开始：指定时间。对齐 effective_start_type */
+export declare const COUPON_EFFECTIVE_START_TYPE_FUTURE = 2;
+/** 生效结束：永久。对齐 effective_end_type */
+export declare const COUPON_EFFECTIVE_END_TYPE_FOREVER = 1;
+/** 生效结束：指定时间。对齐 effective_end_type */
+export declare const COUPON_EFFECTIVE_END_TYPE_FUTURE = 2;
+/** 生效结束：领取后延长 N 天。对齐 effective_end_type */
+export declare const COUPON_EFFECTIVE_END_TYPE_EXTEND = 3;
+/** 可用日期：按天（每天）。对齐 available_repeat_type */
 export declare const COUPON_AVAILABLE_REPEAT_TYPE_DAILY = 0;
+/** 可用日期：按周。对齐 available_repeat_type */
 export declare const COUPON_AVAILABLE_REPEAT_TYPE_WEEKLY = 1;
+/** 可用日期：按月。对齐 available_repeat_type */
 export declare const COUPON_AVAILABLE_REPEAT_TYPE_MONTHLY = 2;
+/** 券实例状态：待生效。对齐 coupon.status */
 export declare const COUPON_STATUS_PENDING = 1;
+/** 券实例状态：已生效。对齐 coupon.status */
 export declare const COUPON_STATUS_ENABLED = 2;
+/** 券实例状态：已使用。对齐 coupon.status */
 export declare const COUPON_STATUS_USED = 3;
+/** 券实例状态：已过期。对齐 coupon.status */
 export declare const COUPON_STATUS_EXPIRED = 4;
+/** 券实例状态：已注销。对齐 coupon.status */
 export declare const COUPON_STATUS_CANCELED = 5;
+/** 券实例状态：已锁定。对齐 coupon.status */
 export declare const COUPON_STATUS_LOCKED = 6;
+/** 券模板状态：草稿。对齐 coupon_template.status */
+export declare const COUPON_TEMPLATE_STATUS_DRAFT = 1;
+/** 券模板状态：已上线。对齐 coupon_template.status */
+export declare const COUPON_TEMPLATE_STATUS_ONLINE = 2;
+/** 券模板状态：已下线。对齐 coupon_template.status */
+export declare const COUPON_TEMPLATE_STATUS_OFFLINE = 3;
+/** 券模板状态：已过期。对齐 coupon_template.status */
+export declare const COUPON_TEMPLATE_STATUS_EXPIRED = 4;
+/** 接口没给 available_error 时，按已知状态补不可用原因 */
+export declare const COUPON_TEMPLATE_STATUS_UNAVAILABLE_ERROR: Record<number, string>;
+/** 券实例独有状态：已注销 / 已锁定。数字不与模板冲突 */
+export declare const COUPON_STATUS_UNAVAILABLE_ERROR: Record<number, string>;
+/** 可用券展开：使用规则等额外信息 */
 export declare const COUPON_EXPAND_TYPE_EXTRA = "extra";
+/** 不可用券展开：本单不可用原因 */
 export declare const COUPON_EXPAND_TYPE_REASON = "reason";
+/** 没有可展开内容 */
 export declare const COUPON_EXPAND_TYPE_NONE = "none";
+/** confirm 未选券时的默认提示 */
 export declare const COUPON_CONFIRM_EMPTY_MSG = "\u8BF7\u9009\u62E9\u4F18\u60E0\u5238";
-export declare const COUPON_EXPIRE_DISPLAY_DEADLINE = "deadline";
-export declare const COUPON_EXPIRE_DISPLAY_VALIDITY = "validity";
+/** 实例票面：过期时间展示具体截止日期 */
+export declare const COUPON_EXPIRE_MODE_DEADLINE = "deadline";
+/** 模板票面：有效期，按次卡同一套开始/结束类型拼文案 */
+export declare const COUPON_EXPIRE_MODE_VALIDITY = "validity";

package/types/coupon/couponSelector.d.ts

@@ -1,21 +1,47 @@
 import { ICouponConfirmResult, ICouponSelectorOptions, ICouponSelectorView } from './type';
+/**
+ * 优惠券选择器（无 UI、不发请求）。
+ *
+ * 列表来源由调用方决定：静态 list 或接口拉完后 setList / appendList。
+ * formatItem 只把后端字段收到 ICoupon（数字 / 枚举即可）；
+ * 门槛、过期、可用日期/时间、使用限制由 couponUtil 格式化，getView 产出 contentLines / expandLines。
+ */
 export declare class CouponSelector {
     private list;
     private selectedId?;
+    /**
+     * 调用方传入的回显 id。
+     * 接口列表异步到达前不要丢掉；分页补齐后继续用它匹配。
+     */
+    private preferredSelectedId?;
     private expandedIds;
     private formatItem?;
-    private expandOne;
-    private expireDisplay?;
+    private exclusiveExpand;
+    private expireMode?;
     private onChange;
     constructor(options: ICouponSelectorOptions);
+    /** 全量替换列表，并清掉已不存在的选中 / 展开 */
     setList(list: any[]): void;
+    /** 分页追加。追加后仍按可用在前重排 */
     appendList(list: any[]): void;
+    /** 当前列表票面快照，给 CouponCard 渲染 */
     getView(): ICouponSelectorView;
+    /**
+     * 点票面。
+     * 可用：选中，再点取消；不可用：不选中，只展开原因。
+     */
     select(id: string | number): void;
+    /** 点箭头，只切换展开，不改变选中 */
     toggleExpand(id: string | number): void;
+    /** 确认选中。未选可用券时 isValid 为 false */
     confirm(): ICouponConfirmResult;
     private _toViewItem;
     private _findCoupon;
+    /** 0 / 空字符串视为未选 */
+    private _normalizeSelectedId;
+    /** 列表尚未包含该券时先留着 preferred，等 setList / appendList 再匹配 */
+    private _syncSelectedId;
+    /** 回显只认当前列表里的可用券 */
     private _pickValidSelectedId;
     private _isExpanded;
     private _setExpanded;

package/types/coupon/couponUtil.d.ts

@@ -1,34 +1,89 @@
-import { CouponExpandType, CouponExpireDisplay, CouponFormatItem, ICoupon, ICouponKvLine, ICouponViewItem } from './type';
+import { CouponExpandType, CouponExpireMode, CouponFormatItem, ICoupon, ICouponKvLine, ICouponViewItem } from './type';
+/** id 统一转字符串再比，避免 number / string 回显对不上 */
 export declare function isSameCouponId(a?: string | number, b?: string | number): boolean;
-export declare function isCouponStatusExpired(status?: number): boolean;
-export declare function resolveCouponAvailable(coupon: Pick<ICoupon, 'status' | 'available'>): boolean;
+/**
+ * 可用态。
+ * 1. availableError 有值：一定不可用
+ * 2. 带了 status 则只有 2（已上线 / 已生效）可用
+ * 3. 没带 status：没有 availableError 则可用（兼容列表只筛 status、项上不回传该字段）
+ */
+export declare function resolveCouponAvailable(coupon: Pick<ICoupon, 'availableError' | 'status'>): boolean;
+/**
+ * 展开用的不可用原因。
+ * 接口 availableError 优先；没有时按已知状态补文案（草稿/下线/过期/注销/锁定），其它灰态不展开。
+ */
+export declare function resolveCouponAvailableError(coupon: Pick<ICoupon, 'availableError' | 'status'>): string;
+/**
+ * 原始列表 → 标准 ICoupon。
+ * 有 formatItem 就逐项转换（返回空则跳过）；没有则把项当作已是 ICoupon。
+ * 未带 original 时自动挂上原始 item。可用券排在不可用前面，组内保持原相对顺序。
+ */
 export declare function formatCouponList(rawList?: any[], formatItem?: CouponFormatItem): ICoupon[];
+/**
+ * 是否走折扣票面（折）。
+ * couponType === 1 为折扣；2/3 为金额。
+ */
 export declare function isCouponDiscountBenefit(coupon: ICoupon): boolean;
+/** 票面数字。满减走 formatAmount；折扣走 formatDiscount，只返回数字部分 */
 export declare function formatCouponAmountValue(coupon: ICoupon): string;
+/** 票面左侧前缀。满减 / 配送为 ¥，折扣为空 */
 export declare function formatCouponAmountPrefix(coupon: ICoupon): string;
+/** 票面右侧单位。折扣为「折」，满减 / 配送为空 */
 export declare function formatCouponAmountSuffix(coupon: ICoupon): string;
+/**
+ * 门槛展示值（不含「使用门槛：」）。
+ * 由 thresholdType + thresholdValue 生成；0 为无门槛。
+ */
 export declare function formatCouponThreshold(coupon: ICoupon): string;
+/**
+ * 过期时间展示值（不含「过期时间：」）。
+ * 给已发出的券实例用，只展示截止日期年月日时分，或永久有效。
+ */
 export declare function formatCouponExpireText(coupon: ICoupon): string;
+/**
+ * 有效期展示值（不含「有效期：」）。
+ * 给发券选模板用，字段和次卡同一套开始/结束类型，不把「领取后 N 天」折成当前时间。
+ */
 export declare function formatCouponValidityText(coupon: ICoupon): string;
+/** 可用日期。按天未选具体日时为「每天」 */
 export declare function formatCouponAvailableDateText(coupon: ICoupon): string;
+/** 可用时段。空或全天时段走 hive formatMinuteSegments，空数组为「全天」 */
 export declare function formatCouponAvailableTimeText(coupon: ICoupon): string;
+/** 使用限制展示值（不含「使用限制：」）。无限制时为「不限制」 */
 export declare function formatCouponUseLimitText(coupon: ICoupon): string;
+/** 把键值行拼成「键：值」；label 为空时只返回 value */
 export declare function formatCouponKvText(line: ICouponKvLine): string;
-export declare function getCouponContentLines(coupon: ICoupon, expireDisplay?: CouponExpireDisplay): ICouponKvLine[];
+/** 票面信息区：使用门槛、过期时间 / 有效期 */
+export declare function getCouponContentLines(coupon: ICoupon, expireMode?: CouponExpireMode): ICouponKvLine[];
+/** 是否带了可用日期 / 时段，用来决定要不要生成展开行 */
 export declare function hasCouponAvailableRepeat(coupon: ICoupon): boolean;
+/** 是否带了使用限制字段（含 0，表示明确「不限制」也要展示） */
 export declare function hasCouponUseLimit(coupon: ICoupon): boolean;
+/** 把「键：值」拆回键值行；没有分隔符则整句当 value */
 export declare function parseCouponKvLine(text: string): ICouponKvLine;
+/** 展开区键值行。extra 走 extraLines 或生成规则，reason 为本单不可用原因 */
 export declare function getCouponExpandKvLines(coupon: ICoupon): ICouponKvLine[];
+/** 当前券应展示的展开类型：extra / reason / none */
 export declare function getCouponExpandType(coupon: ICoupon): CouponExpandType;
+/** 展开区展示文案。reason 只出原因正文，extra 为「键：值」 */
 export declare function getCouponExpandLines(coupon: ICoupon): string[];
+/**
+ * ICoupon → 票面数据。选券弹层和单独挂 CouponCard 共用。
+ * selected / expanded 由调用方控制，available 由 availableError + status 推出。
+ */
 export declare function formatCouponViewItem(coupon: ICoupon, state?: {
     selected?: boolean;
     expanded?: boolean;
-    expireDisplay?: CouponExpireDisplay;
+    expireMode?: CouponExpireMode;
 }): ICouponViewItem;
+/**
+ * 原始项或 ICoupon → 票面。
+ * 有 formatItem 时先映射；没有则把 source 当 ICoupon。
+ * formatItem 跳过该项时返回 undefined。
+ */
 export declare function toCouponViewItem(source: any, state?: {
     selected?: boolean;
     expanded?: boolean;
     formatItem?: CouponFormatItem;
-    expireDisplay?: CouponExpireDisplay;
+    expireMode?: CouponExpireMode;
 }): ICouponViewItem | undefined;

package/types/coupon/type.d.ts

@@ -1,69 +1,182 @@
 import { COUPON_EXPAND_TYPE_EXTRA, COUPON_EXPAND_TYPE_NONE, COUPON_EXPAND_TYPE_REASON } from './constant';
-export type CouponExpireDisplay = 'deadline' | 'validity';
+/**
+ * 票面过期 / 有效期展示模式。
+ * - deadline：已领券实例，展示「过期时间」+ 截止日期
+ * - validity：发券模板，展示「有效期」+ 次卡同一套开始/结束类型文案
+ */
+export type CouponExpireMode = 'deadline' | 'validity';
+/**
+ * 调用方把接口原始项收到标准券结构。
+ * 返回空则跳过该项。H5 桥只能传函数字符串，由 APP createFunction 还原。
+ */
 export type CouponFormatItem = (item: any) => ICoupon | null | undefined;
+/**
+ * 展开区类型。
+ * extra：可用券的使用规则；reason：不可用原因；none：没有可展开内容。
+ */
 export type CouponExpandType = typeof COUPON_EXPAND_TYPE_EXTRA | typeof COUPON_EXPAND_TYPE_REASON | typeof COUPON_EXPAND_TYPE_NONE;
+/**
+ * 选券内部标准结构。后端字段未知时由 formatItem 映射到这里，
+ * UI 只消费 getView() 里的展示字段。
+ *
+ * 文案分两层：
+ * - formatItem 只搬数字 / 枚举（可过 App 桥），不要拼「使用门槛：xxx」
+ * - 标签和格式化在 couponUtil；extraLines 有值时覆盖展开区
+ */
 export interface ICoupon {
+    /** 券 / 模板 id，对齐 coupon.id / coupon_template.id */
     id: string | number;
+    /** 券名称，对齐 title */
     title: string;
-    status?: number;
-    available?: boolean;
-    couponType?: number;
-    amount?: number;
-    discount?: number;
-    thresholdType?: number;
-    thresholdValue?: number;
-    thresholdAmount?: number;
-    thresholdText?: string;
-    expireStartType?: number;
-    expireStartTime?: number;
-    expireEndType?: number;
-    expireEndTime?: number;
-    expireDays?: number;
-    expireText?: string;
+    /**
+     * 券状态，对齐 coupon.status / coupon_template.status。
+     * 模板：1 草稿 / 2 已上线 / 3 已下线 / 4 已过期。
+     * 仅在带了 status 时：为 2 且没有 availableError 才可选；availableError 优先于 status。
+     * 没带 status 且没有 availableError 时视为可用。
+     */
+    status: number;
+    /**
+     * 券业务类型，对齐 coupon_type：1 折扣 / 2 满减 / 3 配送。
+     * 1 走折扣票面，2/3 走金额票面。
+     */
+    couponType: number;
+    /**
+     * 券面值，对齐 coupon_value。
+     * couponType 1 为折扣万分比（9000 → 9折）；2/3 为金额最小单位。
+     */
+    couponValue: number;
+    /**
+     * 门槛类型，必传，对齐 threshold_type：1 金额 / 2 件数。
+     * 与 thresholdValue 一起生成门槛文案。
+     */
+    thresholdType: number;
+    /**
+     * 门槛值，必传，对齐 threshold_value。
+     * thresholdType 1 为金额最小单位，2 为件数；0 视为无门槛。
+     */
+    thresholdValue: number;
+    /**
+     * 生效开始类型，对齐 effective_start_type：
+     * 1 立即 / 2 指定时间。发券模板 expireMode: validity 时使用。
+     */
+    effectiveStartType?: number;
+    /** 生效开始时间戳，对齐 effective_start_time。effectiveStartType 为 2 时有值 */
+    effectiveStartTime?: number;
+    /**
+     * 生效结束类型，对齐 effective_end_type：
+     * 1 永久 / 2 指定时间 / 3 领取后延长 N 天。
+     */
+    effectiveEndType?: number;
+    /** 生效结束时间戳，对齐 effective_end_time。券实例票面截止日期优先用这个 */
+    effectiveEndTime?: number;
+    /** 领取后有效天数，对齐 effective_end_days。effectiveEndType 为 3 时有值 */
+    effectiveEndDays?: number;
+    /**
+     * 可用日期重复类型，对齐 available_repeat_type：
+     * 0 按天 / 1 按周 / 2 按月。
+     */
     availableRepeatType?: number;
+    /**
+     * 可用日期取值，对齐 available_repeat_value。
+     * 按周为周几 0-6，按月为 1-28 号。数组或 JSON 字符串均可。
+     */
     availableRepeatValue?: Array<number | string> | string;
+    /**
+     * 可用时段，对齐 available_minute_segments。
+     * 一维 [start, end, ...]，单位分钟。数组或 JSON 字符串均可。
+     */
     availableMinuteSegments?: Array<number | string> | string;
-    useLimitDaily?: number;
-    useLimitWeekly?: number;
-    useLimitMonthly?: number;
-    extraLines?: string[];
-    unavailableReason?: string;
+    /** 每人每日使用次数上限，对齐 per_user_use_limit_count_daily。0 或不传表示不限制 */
+    useLimitCountDaily?: number;
+    /** 每人每周使用次数上限，对齐 per_user_use_limit_count_weekly。0 或不传表示不限制 */
+    useLimitCountWeekly?: number;
+    /** 每人每月使用次数上限，对齐 per_user_use_limit_count_monthly。0 或不传表示不限制 */
+    useLimitCountMonthly?: number;
+    /**
+     * 本单不可用原因，对齐 available_error。
+     * 有值则一定不可用（优先于 status），并作为展开原因。
+     * 接口没返回时，按 status 补原因（草稿 / 已下线 / 已过期 / 已注销 / 已锁定）。
+     */
+    availableError?: string;
+    /**
+     * 确定时随 ICoupon 回传。
+     * formatItem 未填时自动挂列表原始 item（接口 list 那一行，原样引用）。
+     */
     original?: any;
+    /**
+     * 覆盖整段展开文案。有值时不再用可用日期/时间/使用限制生成。
+     * 建议已是「键：值」；也可只传值。
+     */
+    extraLines?: string[];
 }
+/** 票面 / 展开区的键值行 */
 export interface ICouponKvLine {
+    /** 标签，如「使用门槛」。空则只展示 value */
     label: string;
+    /** 展示值，如「满20元」 */
     value: string;
 }
+/**
+ * 票面展示数据。选券弹层和单独挂 CouponCard 都吃这个结构。
+ * 金额拆成 prefix / value / suffix，方便 ¥、数字、折用不同字号。
+ */
 export interface ICouponViewItem {
+    /** 标准券数据，确认时回传；点选/展开用 coupon.id */
     coupon: ICoupon;
+    /** 当前是否选中 */
     selected: boolean;
+    /** 当前是否展开详情 */
     expanded: boolean;
+    /** 是否可选、非灰态。availableError 优先，否则 status 为 2 才可用 */
     available: boolean;
+    /** 票面左侧前缀，满减为 ¥，折扣为空 */
     amountPrefix: string;
+    /** 票面数字，如 5 或 9 */
     amountValue: string;
+    /** 票面右侧单位，折扣为 折，满减为空 */
     amountSuffix: string;
+    /** 券名称，来自 coupon.title */
     title: string;
+    /** 票面信息区，已拼成「键：值」，含使用门槛、过期时间 / 有效期 */
     contentLines: string[];
-    thresholdText: string;
-    expireText: string;
+    /** 展开区类型：extra 使用规则 / reason 不可用原因 / none 无展开 */
     expandType: CouponExpandType;
+    /** 展开区文案。reason 时为原因正文，extra 时为「键：值」 */
     expandLines: string[];
 }
+/** CouponSelector.getView() 的列表快照 */
 export interface ICouponSelectorView {
+    /** 当前列表票面，可用券在前 */
     items: ICouponViewItem[];
+    /** 当前选中的券 id */
     selectedId?: string | number;
+    /** 当前选中的标准券；未选则为空 */
     selectedCoupon?: ICoupon;
 }
+/** CouponSelector 构造参数 */
 export interface ICouponSelectorOptions {
+    /** 初始列表；静态数据或接口第一页 */
     list?: any[];
+    /** 回显选中的券 id */
     value?: string | number;
+    /** 把接口原始项收到 ICoupon；不传则把 list 项当作已是 ICoupon */
     formatItem?: CouponFormatItem;
-    expandOne?: boolean;
-    expireDisplay?: CouponExpireDisplay;
+    /** true 时展开互斥，同时只展开一张，默认 false */
+    exclusiveExpand?: boolean;
+    /**
+     * deadline：过期时间 + 截止日期（实例，默认）。
+     * validity：有效期 + 次卡开始/结束类型文案（发券模板）。
+     */
+    expireMode?: CouponExpireMode;
+    /** 选中 / 展开 / 列表变化时通知 UI 重绘 */
     onChange: () => void;
 }
+/** confirm() 的结果 */
 export interface ICouponConfirmResult {
+    /** 是否选中了可用券 */
     isValid: boolean;
+    /** 未选中时的提示，如「请选择优惠券」 */
     errMsg?: string;
+    /** 选中的标准券，含 original */
     coupon?: ICoupon;
 }

package/types/selector/comboSpecSelector.d.ts

@@ -1,5 +1,11 @@
 import { ICartListItem, ISelectSkuComboItem } from './type';
 import { ICountChangeResult, IAddToCartParamsResult, IComboSpecSelectorView, IComboSpecSelectorOptions, IFetchCartCountParams, IFetchMemberPriceParams, IMallSkuDetailDataForCombo } from './type';
+/**
+ * 套餐商品规格选择器
+ *
+ * 设计原则：类内部不发起任何接口请求，所有数据处理逻辑封装在此，
+ * 网络请求由 UI 层发起，将结果通过公开方法回填。
+ */
 export declare class ComboSpecSelector {
     private product;
     private specImage;
@@ -33,18 +39,49 @@ export declare class ComboSpecSelector {
     private _initSkuId;
     private _validateComboGroupList;
     constructor(options: IComboSpecSelectorOptions);
+    /** 获取初始 sku 列表（供 UI 在调用 fetchSkuDetail 前获取初始 skuId） */
     getInitialSkuId(): number;
+    /**
+     * 初始化，接收 UI 层拉取的 sku 详情数据
+     * 调用后触发 onChange，UI 可通过 getView() 拿到渲染数据
+     */
     init(skuDetailData: IMallSkuDetailDataForCombo): void;
+    /**
+     * 同步最新的购物车列表
+     * cartList 更新后调用此方法，会重新计算当前 skuId 在购物车中的数量
+     */
     syncCartList(cartList: ICartListItem[]): void;
     getView(): IComboSpecSelectorView;
+    /**
+     * 选择规格（纯数据处理）
+     * @returns needFetchSkuDetail 是否需要重新拉取 sku 详情（为 true 时同样需要重新请求会员价）；skuId 目标 skuId
+     */
     handleSelectSpecs(isOption: boolean, value: string, index: number): {
         needFetchSkuDetail: boolean;
         skuId: number;
     };
+    /**
+     * 用新的 sku 详情数据更新内部状态
+     * （规格切换后，UI 调用 fetchSkuDetail 接口拿到数据后传入此方法）
+     */
     updateSkuDetailData(skuDetailData: IMallSkuDetailDataForCombo): void;
+    /**
+     * 用会员价查询结果更新内部状态，由 UI 层请求会员价接口后调用
+     * @param price 会员价，请求失败或无会员价时传 undefined
+     */
     updateMemberPrice(price: number | undefined): void;
+    /**
+     * 套餐选中变化（纯数据处理）
+     */
     handleSelectComboData(skuComboItemList: ISelectSkuComboItem[][]): void;
+    /**
+     * 数量变化（纯逻辑，返回操作结果供 UI 决策）
+     */
     handleProductCountChange(count: number, type: string): ICountChangeResult;
+    /**
+     * 加入购物车前校验，返回提交所需参数
+     * 由 UI 层使用参数调用 addToCart 接口
+     */
     getAddToCartParams(productId: number, promotionActivityProductId?: number): IAddToCartParamsResult;
     handleShowComboInfo(): void;
     handleCloseComboInfo(): void;
@@ -52,14 +89,31 @@ export declare class ComboSpecSelector {
     getOriginalPrice(): number;
     getMemberPrice(): number | undefined;
     buildCartCountParams(): IFetchCartCountParams;
+    /**
+     * 构造会员价查询参数（供 UI 层使用）
+     * sku 未选中时返回 undefined
+     */
     buildMemberPriceParams(): IFetchMemberPriceParams | undefined;
     private _initProductData;
     private _initSkuDetail;
     private _updateSkuData;
     private _checkProductCount;
+    /**
+     * 内部规格选择逻辑（被 handleSelectSpecs 和 init 时复用）
+     * @returns 是否发生了选中变化
+     */
     private _selectSpec;
+    /**
+     * 刷新当前 skuId 对应的购物车数据
+     */
     private _refreshCartItem;
+    /**
+   * 根据 skuId 和当前 skuComboItemList 从 cartList 中查找匹配的购物车项
+   */
     private _findSkuCartItem;
+    /**
+     * 校验套餐分组是否满足要求，返回错误信息（空字符串表示校验通过）
+     */
     private _validateCombo;
     private _notifyChange;
 }

package/types/selector/comboUtil.d.ts

@@ -21,8 +21,11 @@ export declare function checkGroupCanMinusCount(comboGroupItem: ISkuComboGroupIt
 export declare function checkIsFixedSelectNeedSelectSku(comboItem: ISkuComboItem): boolean;
 export declare function checkIsUseSelectSkuBtn(comboItem: ISkuComboItem): boolean;
 export declare function getSkuComboItemGroup(skuComboItemList: ICartSkuComboItem[]): ISkuComboGroupList[];
+/** 将购物车数据回填到 comboGroupList */
 export declare function reconstructComboGroupList(comboGroupList: ISkuComboGroupItem[], skuComboItemList?: ICartSkuComboItem[]): ISkuComboGroupItem[];
+/** 格式化当前选中的 skuComboItemList（二维数组） */
 export declare function formatSelectSkuComboItemList(comboGroupList: ISkuComboGroupItem[]): ISelectSkuComboItem[][];
+/** 校验 comboGroupList 选中是否合法，合法返回 ''，否则返回错误信息 */
 export declare function validateComboGroupList(comboGroupList: ISkuComboGroupItem[], skuComboItemList?: ISelectSkuComboItem[][]): string;
 export declare function formatComboGroupItemSelectTips(comboGroupItem: ISkuComboGroupItem): string;
 export declare function generateCartSkuComboItemList(skuComboItemList: ISelectSkuComboItem[][] | undefined): ICartSkuComboItem[];