SietaData 进销存分析系统 — 落地版 PRD

文档信息

一、概述

1. 需求背景

1.1 现状

Sieta 连锁鞋店现有 5 个店铺，使用老 ERP 系统 oupu v6（基于 IE6 内核），无法实现现代 ERP 的分析功能。oupu 可设定每天 24:00 自动生成两组数据并通过邮件发送：

• 库存报表：全量 SKU 库存明细，约 3000 行，每日产出
• 销售报表：当日销售汇总（按 SKU），每日产出

当前问题：这些数据以 Excel 附件形式存在邮件中，没有沉淀到数据库，无法做跨日对比、趋势分析、同比环比。手动导出到 Excel 加工效率低，手机端查看效果差。

1.2 核心痛点

1.3 库存台账设计的解决思路（大头哥设计）

核心方案：周快照 + 每日流水，SQLite 存储。

每天 01:00   → 收前一日（24:00）数据 → 推算变动流水入库（只存有变化的 SKU）
每周一 01:00 → 常规日处理 + 将周日的数据同时存入周快照（作为整周锚点）

查询任意日期库存 = 最近周日快照数量 + 该SKU从周日起到目标日的所有流水累加

设计优势： - 数据库行数不无限增长——快照固定 52 次/年，流水只存有变动的 SKU - 查询高效——SQLite 千万行级别毫秒响应 - 通过对每日库存的反推，自动产生进销存明细

2. 需求目标

2.1 业务目标

1. 数据持久化：从 2026 年 5 月起，每日库存/销售数据自动入库，形成可查询的历史数据库
2. 日报自动化：每天自动生成交互式 H5 报告（含新款销售、售罄下样、经营建议），飞书推送简报
3. 对比分析：支持同比/环比——先做周同比（需 2 周以上数据），再做月同比（需 2 月以上数据）

2.2 成功标准

3. 需求范围

包含（MVP v1.0）

1. 数据库搭建：库存台账（快照 + 流水）+ 商品表/销售表
2. 数据初始化：导入最近 1 个月的每日数据 + 2025/2024 年历史数据
3. 每日自动入库：cron 每日凌晨 1:00 收邮件 → 入库
4. 日报 H5 产出：基于数据分析生成交互式报告
5. 飞书推送：简报（含新款图片 + 售罄提醒）+ H5 链接

不包含（本版本不做）

• 周报/月报的独立报告页面（但数据库为它们预留结构）
• 多用户权限管理
• 自动化进货建议
• 店铺级权限隔离
• Dashboard 首页顶视图的完整开发（MVP 只出 H5 日报，Dashboard 后续迭代）

版本路线图

4. 参考资料

二、数据库设计

2.1 库存快照表（inventory_snapshot）

支持多粒度快照同时存入——日快照、周快照、月快照共用同一张表，通过 snapshot_date 区分。

主键：(snapshot_date, sku_id)

设计要点： - snapshot_date 不限制必须是周日——日快照、周快照、月快照均存入 - 查询时找目标日期之前的最近一个快照，不论粒度 - 2026 年 5 月起：每日一个全量快照（入库后即生成） - 2026 年 5 月起：每周一 01:00 将周日数据存为周快照（作为周分析锚点） - 2025 年历史数据：每周一次快照 - 2024 年历史数据：每月一次快照

为什么日快照和周快照同时存？ 每日快照是入库流水推算后的副产品（已有今日全量库存 xlsx，顺手存入）；周快照是正式分析锚点。二者不冲突。

2.2 库存变动流水表（inventory_ledger）

主键：(change_date, sku_id, change_type) 索引：(change_date) 单独索引，加速按日期范围查询 索引：(sku_id) 单独索引，加速按商品查询

变动类型枚举：

设计要点： - 只记录当天发生变化的 SKU，无变化不产生行 - 从 2026 年 5 月（系统启动月份）开始逐日记录 - 2025 年及以前的历史数据不在流水表中产生行——只存快照

2.3 商品信息表（product）

2.4 日报分析结果表（可选，daily_analysis）

三、历史数据导入策略（重点）

这是大头哥特别强调的部分。核心原则：时间越久远，粒度越粗。

3.1 数据时间线

2024年 ───────── 2025年 ───────── 2026年5月 ────── 现在（持续）
   │                   │                │
 月粒度              周粒度           日粒度
（每月1号快照）    （每周快照）    （每日全量库存+销售）

3.2 各时间段的数据准备要求

3.3 导入顺序

1. 先导最近 1 个月的日数据——系统启动时第一批数据，让日报从第一天就有内容
2. 再导 2025 年的周数据——逐步充实周对比基础
3. 最后导 2024/2023 年的月数据——充实月对比基础

3.4 数据导入方式

你通过网页上传入口（后续开发）或直接告诉我用终端导入。对于历史数据，处理 xlsx 的脚本自动识别粒度： - 文件名含日期，判断是日/周/月 - 日粒度：同时写入 snapshot 和 ledger - 周/月粒度：只写入 snapshot

3.5 对比分析的可用时间线

没有对比、就没有分析——所以历史数据的导入非常关键。

四、实施步骤（先做什么后做什么）

Phase A：数据库搭建 + 核心脚本（第 1-3 天）

任务 1：建表脚本
  ├─ create_tables.sql → 创建 product / inventory_snapshot / inventory_ledger 三表
  └─ 初始化 SQLite 数据库：~/sietadata/db/sieta.db

任务 2：核心 pipeline 脚本
  ├─ step1_parse_inventory.py  → 读取库存 xlsx，标准化字段
  ├─ step2_parse_sales.py      → 读取销售 xlsx，标准化字段
  └─ step3_process_daily.py    → 核心逻辑：
       ① 获取昨日库存（快照+流水推算）
       ② 获取今日库存 + 今日销售（从 xlsx 解析）
       ③ 写入 sale 流水
       ④ 计算非销售净变动 → 写入 adjustment_in/out
       ⑤ 如果是周一 → 将周日数据存为周快照
       ⑥ 写入今日全量库存到 inventory_snapshot（作为日快照）

Phase B：初始数据导入（第 4-5 天）→ 需要你配合

步骤 1：你把 5月1日 ~ 启动前一日 的每日库存 xlsx + 销售 xlsx 给我
步骤 2：我跑导入脚本（按日期顺序），逐日演练一遍 pipeline
步骤 3：验证——查询任意一天的库存台账，确认数据正确
步骤 4：验证——检查 inventory_ledger 行数是否合理（仅含变动的 SKU）

此阶段完成后，系统已有约 20 天的完整数据，日报可以产出。

Phase C：历史数据入库（第 6-8 天）→ 你逐步准备，分批导入

步骤 1：你把 2025 年每周数据给我（一次给几周也可，分批处理）
步骤 2：我跑导入脚本 → 只写入 inventory_snapshot（周快照）
步骤 3：你把 2024 年每月数据给我
步骤 4：跑导入脚本 → 只写入 inventory_snapshot（月快照）
步骤 5：验证——周同比和月同比的 SQL 查询正确返回结果

此阶段完成后，数据库已有 2024~2026 的完整库存全景。

Phase D：cron 自动化（第 8-9 天）

任务 1：配置 oupu 每日自动发送邮件（如果你还没配好）
任务 2：写 daily_pipeline.sh 编排脚本（按顺序调 step1→2→3）
任务 3：cron 定时任务 — 每日 01:00 执行
任务 4：首次 cron 手动跑一次验证邮件接收 → 解析 → 入库全链路
任务 5：异常处理——入库失败时发飞书通知你

Phase E：日报 H5 产出（第 10-14 天）

任务 1：写日报数据查询脚本（从 SQLite 取今日销售/库存/新款/售罄等指标）
任务 2：分析阶段（先用大模型分析数据 → 产出洞察文本）
任务 3：生成 H5 报告模板（HTML + Chart.js 图表）
任务 4：飞书推送脚本（简报内容 + H5 链接）

Phase F：后续迭代（第 3 周起）

v1.1：
- Dashboard 顶视图（sieta.vip/sietadata/）
- 周报/月报页面
- 历史数据上传入口

v1.2：
- 同比/环比深度分析
- 分析脚本化（减少 token 消耗）
- 新款自动识别 + 售罄预警

五、功能列表

六、页面结构与导航设计

6.1 整体导航结构（MVP）

MVP 没有独立导航页面。数据通过两条渠道触达：
├─ 飞书推送 → 点击 H5 链接 → 看到当日日报（独立页面，不依赖导航）
└─ 后续迭代 → Dashboard 顶视图（sieta.vip/sietadata/）

6.2 日报 H5 页面

页面职责：用户通过飞书链接访问，在手机上看当日经营全貌

页面结构（从上到下）：

本页面不展示：店铺级数据（v1.1 加入）、同比环比图表（v1.2 加入）、全量商品列表

6.3 独立页面 / 弹窗

七、功能说明

功能 1：每日自动入库

功能描述

用户无需操作，系统在每天凌晨 1:00 自动执行：接收 oupu 邮件 → 下载库存 xlsx 和销售 xlsx → 解析 → 更新 inventory_ledger 和 inventory_snapshot。

用户流程

cron 01:00 触发
  ↓
himlaya 收最新邮件
  ├─ 有附件 → 下载到 ~/sietadata/inbox/
  ├─ 无附件 → 跳过本次，记日志
  └─ 异常（邮件服务不可用）→ 发飞书告警
  ↓
step1_parse_inventory.py → 解析库存 xlsx
step2_parse_sales.py → 解析销售 xlsx
  ↓
step3_process_daily.py
  ① 推算昨日库存（最近快照 + 流水累加）
  ② 对比今日库存 → 计算净变化
  ③ 写入 sale 流水（销售出库）
  ④ 计算非销售净变动 → 写入 adjustment_in/out
  ⑤ 写入今日全量库存到 inventory_snapshot（日快照）
  ⑥ 如果是周一 → 将周日数据存为周快照
  ├─ 成功 → 日志记录完成
  ├─ 失败（数据不匹配）→ 发飞书告警，数据保留 mbox 不丢
  └─ 失败（xlsx 格式异常）→ 发飞书告警

异常场景

功能 2：日报 H5 报告生成

功能描述

每日入库完成后，从 SQLite 查询当日数据，生成 H5 报告文件部署到 sieta.vip/sietadata/reports/YYYY-MM-DD-daily.html。

用户流程

每日入库成功
  ↓
查询当日指标脚本
  ├─ 总销售额、总销售双数
  ├─ 在售 SKU 数、库存总量
  ├─ 新款销售 top 10（含图片 URL）
  ├─ 售罄 SKU 列表（库存=0）
  └─ 同比/环比：上周同日、上月同日（如有历史数据）
  ↓
分析阶段（大模型 v4-flash）
  ├─ 输入：以上指标 + 库存变动流水
  ├─ 输出：经营建议文字（约 200-400 字）
  └─ 注：稳定后转 Python 脚本分析，零 token
  ↓
渲染 H5 模板
  ├─ HTML + Chart.js + 内联 CSS（手机端适配）
  ├─ 嵌入 COS 图片（新款/售罄 SKU 图片）
  └─ 输出到 ~/sietadata/output/reports/
  ↓
部署
  ├─ cp 到 nginx 路径 /var/www/sieta/sietadata/reports/
  └─ 记录 report_url = https://sieta.vip/sietadata/reports/YYYY-MM-DD-daily.html

异常场景

空状态文案：

功能 3：飞书推送

功能描述

日报 H5 生成后，向飞书群推送一条消息，包含： 1. 新款图片区（核心内容）——当日新款销售中销量最高的 3-5 款，每款含 COS 图片 2. 售罄提醒——已售罄商品列表 3. 关键数字简报——今日销售金额/双数、环比上周同日 4. 报告链接——点开看完整 H5 日报

消息格式

📊 5月16日 Sieta 销售日报

━━━━━━ 今日新款 TOP 3 ━━━━━━
[图片] 新款A | ¥299 | 售出 12 双
[图片] 新款B | ¥359 | 售出 8 双
[图片] 新款C | ¥199 | 售出 6 双

━━━━━━ 售罄提醒 ━━━━━━
· 款式X（¥259）已售罄 - 全部店铺下样
· 款式Y（¥189）仅剩 2 双

━━━━━━ 关键指标 ━━━━━━
今日销售：¥ 28,350（+12% vs 上周同日）
在售 SKU：3,152 款
库存总量：42,380 双

👉 查看完整日报
https://sieta.vip/sietadata/reports/2026-05-16-daily.html

异常场景

八、实施进度一览（总表）

九、六大盲区自检清单

• [x] 数据库设计：完整输出了 4 张表的结构、主键、索引、字段规范
• [x] 数据流设计：ERP 邮件 → pipeline 解析 → 入库的完整链路，含异常处理
• [x] 历史数据策略：多粒度（日/周/月）导入方案，含时间线
• [x] 用户流程：每个功能的正常路径 + 异常路径均已覆盖
• [x] 实施步骤：A-F 六阶段，先后次序明确，里程碑清晰
• [x] 异常处理：邮件收不到、xlsx 格式变、数据不匹配、API 失败、连续失败熔断均覆盖

PRD 落地版已完成，六大盲区均已覆盖。