# SKUManager

**Repository Path**: StarsPython/skumanager

## Basic Information

- **Project Name**: SKUManager
- **Description**: SKU生命周期数据分析与管理系统
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-17
- **Last Updated**: 2025-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

SKU 生命周期系统 MVP

概览
- 轻量化数据分析系统，聚焦SKU的描述性统计、特征工程与生命周期建模。
- 代码组织模块化，数据通过标准化CSV在模块间传递。

列名与数值规范
- 适用范围：`data/stats` 与 `data/results` 下由描述性统计与特征工程模块生成的CSV。
- 列名中文化：基础指标列统一使用中文列名（如`销量`、`销售额`、`毛利润`、`毛利率`、`退货率`、`月份`）。
- 英文后缀保留：派生/聚合字段保留英文后缀（如`_mean`、`_std`、`_sum`、`_ratio`、`_yoy_growth`、`_mom_growth`）。例如：`销量_mean`、`销售额_sum`、`毛利率_yoy_growth`。
- 数值格式：所有浮点数默认保留3位小数；计数类整数不做小数处理。
- 百分比字段：以数值形式存储（不附带`%`），展示层负责格式化。

统一写入方式
- 使用统一写入函数：`utils.file_utils.write_csv(df, path)`。
- 该函数会自动：
  - 确保父目录存在；
  - 针对`results`/`stats`路径应用中文列名映射（保留后缀）；
  - 以UTF-8编码写入CSV，并将浮点数格式化为三位小数。

列名映射说明
- 映射字典：`utils/column_mapping.py` 的 `BASE_COLUMN_MAP`。
- 映射规则：
  - 若整列名在映射字典中（如`year_month`），直接替换为中文（如`年月`）。
  - 否则仅映射首段前缀并保留后缀（如`grossProfit_sum` → `毛利润_sum`）。

示例
```
from utils.file_utils import write_csv

# 统计模块保存
write_csv(monthly_df, "data/stats/月度维度数据.csv")

# 特征模块保存
write_csv(sku_df, "data/results/SKU维度数据.csv")
```

开发约定
- 统计（`stats/`）与特征（`features/`）模块中，统一使用`write_csv`，避免直接调用`DataFrame.to_csv`。
- 新增或变更列名时，应同步维护`utils/column_mapping.py`中的映射字典，以保持输出一致性与可读性。

脚本：规则配置生成器（Markdown → YAML）
- 位置：`scripts/generate_rules.py`
- 作用：从业务规范文档（默认 `docs/生命周期业务标准.md`）解析生成规则模型可用的 YAML。
- 输出：默认写入 `config/lifecycle_rules.generated.yaml`；若加 `--overwrite` 则覆盖 `config/lifecycle_rules.yaml`。
- 示例：
  - 使用默认文档与输出路径：
    - `python scripts/generate_rules.py`
  - 指定文档与输出文件：
    - `python scripts/generate_rules.py --spec docs/生命周期业务标准.md --out config/lifecycle_rules.v2.yaml`
  - 覆盖当前配置：
    - `python scripts/generate_rules.py --overwrite`

脚本：时间序列阈值调优器（TS 阈值网格搜索）
- 位置：`scripts/tune_ts.py`
- 作用：针对 `TimeSeriesLifecycleModel` 的阈值（新品窗口、成长/衰退斜率阈值）进行网格搜索，最大化最后一个月阶段的 macro-F1（并回退比较准确率）。
- 输入：
  - `--ts` 时间序列明细 CSV（默认 `data/init/last_sales_month.csv`）。需包含列：`SKU编码/skuCode`、`月份/month`、`销量/salesQty`（其余列可选）。
  - `--labels` 监督标签 CSV（可选）。需包含列：`SKU编码`、`label`（取值如：引入期/成长期/成熟期/衰退期/淘汰期）。
  - `--rules` 规则 YAML（可选，默认 `config/lifecycle_rules.yaml`）。当未提供 `--labels` 时，用规则模型生成伪标签。
  - `--grid` 自定义搜索网格 JSON，例如：`{"npm":[3,4,5],"grow":[0.05,0.1],"decl":[0.05,0.1]}`。
- 输出：将最优阈值与评估指标写入 `config/models.tuned.yaml`，便于手动更新 `config/models.yaml` 中对应字段。
- 示例：
  - 使用规则配置生成伪标签进行调参：
    - `python scripts/tune_ts.py --ts data/init/last_sales_month.csv --rules config/lifecycle_rules.yaml`
  - 使用真实标签进行调参：
    - `python scripts/tune_ts.py --ts data/init/last_sales_month.csv --labels data/init/sku_stages.csv`
  - 自定义搜索网格：
    - `python scripts/tune_ts.py --grid "{\"npm\":[3,6],\"grow\":[0.05,0.15],\"decl\":[0.05,0.15]}"`

应用调参结果
- 打开 `config/models.tuned.yaml`，将 `time_series_model` 下的三个参数拷贝到 `config/models.yaml` 中 `time_series_model` 的同名字段：
  - `new_product_months`
  - `growth_slope_threshold`
  - `decline_slope_threshold`
- 之后运行 `python scripts/run_lifecycle.py` 时，时间序列模型将使用更新后的阈值。

脚本：时间序列模型调优扩展（ARIMA/Holt-Winters + 全量网格CSV）
- 位置：`scripts/tune_ts.py`
- 扩展能力：
- `--model` 选择 `threshold`（默认）/`arima`/`holtwinters`
  - `--objective` 优化目标：
    - 阈值：`f1` 或 `accuracy`（内部以 macro-F1 为主，平分时比较准确率）
    - ARIMA/HWE：`mase`（默认）或 `aic`/`bic`
  - `--cv-splits`、`--horizon`：时间序列扩展窗口交叉验证参数（ARIMA/HWE）
  - `--trials-out`：导出全量网格结果 CSV（默认 `data/results/时间序列模型调参结果表.csv`）
  - `--apply-default`：在导出的 `config/models.tuned.yaml` 中写入 `apply_by_default: true`（主流程可自动应用覆盖）
- ARIMA 网格 JSON 示例：`{"p":[0,1,2],"d":[0,1],"q":[0,1,2],"seasonal":true,"P":[0,1],"D":[0,1],"Q":[0,1],"s":[12]}`
- HWE 网格 JSON 示例：`{"trend":[null,"add","mul"],"seasonal":[null,"add","mul"],"sp":[12]}`
- 运行示例：
  - `python scripts/tune_ts.py --model arima --ts data/init/last_sales_month.csv --objective mase --cv-splits 3 --horizon 1 --trials-out data/results/时间序列模型调参结果表.csv`
  - `python scripts/tune_ts.py --model holtwinters --grid "{\"trend\":[null,\"add\"],\"seasonal\":[null,\"add\"],\"sp\":[12]}" --objective mase`

运行时阈值临时覆盖（--ts-override）
- 位置：`scripts/run_lifecycle.py`
- 用法：在运行主流程时通过 `--ts-override config/models.tuned.yaml` 临时覆盖时间序列阈值：
  - `python scripts/run_lifecycle.py --input ts=data/init/last_sales_month.csv logit=data/init/stdata.csv rule=data/init/mutidata.csv --ts-override config/models.tuned.yaml`
- 行为：
  - 若 `models.tuned.yaml` 中包含 `time_series_model` 的三个字段（或位于 `params` 子键下），将覆盖 `config/models.yaml` 中对应阈值，仅对本次运行生效。
  - 若包含 `time_series_model_tuning.trials_csv`，会自动将该 CSV 拷贝至 `data/results/时间序列模型调参结果表.csv`，便于复核与归档。

依赖说明
- ARIMA/Holt-Winters 调优依赖 `statsmodels`，已加入 `requirements.txt`（`statsmodels>=0.14.0`）。
默认覆盖开关（无需传参也可生效）
- 当存在 `config/models.tuned.yaml` 且其中任一开关为 `true` 时，主流程会自动应用覆盖，无需显式 `--ts-override`：
  - 根级：`apply_ts_override_default: true`
  - `time_series_model.apply_by_default: true`
  - `time_series_model_tuning.apply_by_default: true`
- 使用 `tune_ts.py --apply-default` 可自动在导出的 tuned YAML 中写入该开关。

指标选择与多指标预测（ARIMA/Holt-Winters）
- 新增脚本 `scripts/metric_selector.py` 提供指标选择 Web 界面：
  - 类别管理、搜索筛选、指标详情展示、直观多选与实时选中数提示。
  - 默认行为：未手动选择时保存将提示并默认选择数据源中的所有可用指标。
  - 启动示例：`python scripts/metric_selector.py --port 8020`，浏览 `http://localhost:8020/`。
  - 发现可用指标：在页面输入数据源 CSV（如 `data/init/stdata.csv`）并点击“读取可用指标”。
  - 保存选择：点击“保存选择”，生成 `config/predict_metrics.yaml`（含 `apply_by_default: true` 与 `metrics` 列表）。
- 主流程脚本 `scripts/run_lifecycle.py` 增加指标选择相关参数：
  - `--predict-metrics`: 逗号分隔的规范键（如 `salesQty,salesAmt,grossMargin,returnRate`），或 `all`。
  - `--predict-metrics-file`: 指标选择配置文件（YAML/JSON），默认读取 `config/predict_metrics.yaml`。
  - 选择优先级：命令行参数 > 配置文件（需 `apply_by_default: true`）> 自动发现（默认选择全部可用指标）。
- 预测输出：当加载到 ARIMA/HWE 调参结果（含 `best_params`）时，生成独立报表：
  - 长表：`data/results/时间序列预测报表.csv`
    - 列：`SKU编码`,`预测月份`,`模型`,`指标`,`预测值`
  - 宽表：`data/results/时间序列预测报表_宽表.csv`
    - 列：`SKU编码`,`最近销售月份`,`模型`,`预测月份`,`预测_salesQty`,`预测_salesAmt` 等（每个指标一列）
  - 比例型指标（如 `grossMargin`,`returnRate`）自动约束到 `[0,1]`，规模型指标非负约束。
  - 预测步长：使用调参时的 `horizon`（默认 3，最大 12）。

脚本：聚类代表性SKU选择
- 位置：`scripts/select_representatives.py`
- 作用：基于 `*_聚类特征表.csv` 按聚类中心距离选择代表性SKU；支持数量或比例阈值。
- 输入：
  - `--source-csv` 聚类特征表（默认 `data/cluster/SKU聚类特征表.csv`）
  - `--select-by` `ratio`（默认）或 `count`
  - `--ratio` 比例阈值（默认 0.2）或 `--count` 数量阈值
  - `--metric` 距离度量 `euclidean|cosine`（默认 euclidean）
  - `--standardize` 标准化特征
  - `--output-csv` 输出（默认 `data/cluster/代表性SKU表.csv`）
- 示例：
  - `python scripts/select_representatives.py --select-by ratio --ratio 0.2`
  - `python scripts/select_representatives.py --select-by count --count 5`

脚本：新品SKU筛选
- 位置：`scripts/filter_new_products.py`
- 作用：按上架时间或引入期定义筛选新品SKU。
- 输入：
  - `--mode` `intro_period`（默认）或 `listing_date`
  - `--months-since-create-max` 引入期最大月龄（默认 3）
  - `--listing-date-start`/`--listing-date-end` 上架时间区间（`listing_date` 模式）
  - `--source-csv` 数据源（默认 `data/init/mutidata.csv`，回退 `data/init/stdata.csv`）
  - `--output-csv` 输出（默认 `data/init/新品SKU表.csv`）
- 示例：
  - `python scripts/filter_new_products.py --mode intro_period --months-since-create-max 3`
  - `python scripts/filter_new_products.py --mode listing_date --listing-date-start 2024-01-01 --listing-date-end 2024-06-30`

脚本：SKU曲线拟合与对比
- 拟合：`scripts/curve_fit.py`
  - 作用：对每个SKU按月序列拟合 `logistic/gompertz/bass` 曲线，输出评估与预测；可选只对代表性SKU执行。
  - 输入：
    - `--models` 模型列表（默认 `logistic`）
    - `--forecast-horizon` 预测步长（月，默认 0）
    - `--representative-csv` 仅拟合代表性SKU（可选，默认读取 `selected` 标记）
    - `--source-csv` 数据源（默认 `data/init/mutidata.csv`）
    - `--output-dir` 输出目录（默认 `data/results/curve_fit`）
  - 输出：
    - 汇总：`data/results/curve_fit/SKU曲线拟合汇总.csv`
    - 预测：`data/results/curve_fit/SKU曲线拟合预测明细.csv`
    - 图像：`data/results/curve_fit/plots/<model>/<SKU>.png`
  - 示例：`python scripts/curve_fit.py --models logistic gompertz --forecast-horizon 3 --representative-csv data/cluster/代表性SKU表.csv`
- 对比：`scripts/curve_compare.py`
  - 作用：按指标/分组列（如聚类类目）绘制多条SKU的拟合曲线对比图。
  - 输入：
    - `--predictions-csv` 预测明细（默认 `data/results/curve_fit/SKU曲线拟合预测明细.csv`）
    - `--meta-csv` 元数据表（如 `data/cluster/代表性SKU表.csv` 或 `SKU聚类特征表.csv`）
    - `--group-col` 分组列名（如 `聚类类目`/`clusterId`）
    - `--model` 仅绘制指定模型（可选）
    - `--max-skus-per-plot` 每张图最多SKU数（默认 6）
    - `--output-dir` 输出目录（默认 `data/results/curve_fit/compare_charts`）
  - 输出：`data/results/curve_fit/compare_charts/group_<分组值>.png`