SietaData 项目规则大全

最后更新: 2026-05-24

SietaData 项目规则大全

> 最后更新: 2026-05-24

> 此文档是所有已确认规则的单一源头。每次有新的持久化约定时更新此文件。

---

1. 项目概览

---

2. 数据库：5 表架构

2.1 product（商品属性）

```sql

CREATE TABLE product (

货号 TEXT PRIMARY KEY,

商品名称 TEXT,

品牌 TEXT,

年份 TEXT,

季节 TEXT,

二类 TEXT,

三类 TEXT,

...

);

```

- ⚠️ 仅 ~20% SKU 有分类值（625/3087）

- 品牌通过 `LEFT JOIN product ON sales_ledger.货号 = product.货号` 获取

2.2 sales_ledger（店铺维度销售）

```sql

CREATE TABLE sales_ledger (

日期 TEXT,

货号 TEXT,

店铺编码 TEXT,

店铺 TEXT,

数量 REAL,

单价 REAL,

金额 REAL,

进价 REAL,

销售成本 REAL,

毛利 REAL,

颜色编码 TEXT,

颜色 TEXT,

营业员编码 TEXT,

营业员 TEXT,

created_at TEXT,

UNIQUE(日期, 货号, 颜色编码, 营业员编码, 数量, 单价)

);

```

- **来源**: Mobile BI `自动报表_零售汇总_当日销售_店铺_YYYYMMDD_HHMMSS.xlsx`

- **毛利公式**: `金额 - (进价 × 数量)`

- **营业员字段可能为空**: 部分日期（如 5/20）只有店铺维度数据

2.3 staff_sales（营业员维度销售）

```sql

CREATE TABLE staff_sales (

日期 TEXT NOT NULL,

营业员编码 TEXT,

姓名 TEXT NOT NULL,

货号 TEXT NOT NULL,

颜色编码 TEXT,

颜色 TEXT,

数量 REAL NOT NULL,

金额 REAL,

毛利 REAL,

created_at TEXT DEFAULT (datetime('now','localtime')),

UNIQUE(日期, 营业员编码, 姓名, 货号, 颜色编码)

);

```

- **来源**: Mobile BI `自动报表_零售汇总_当日销售_营业员_YYYYMMDD_HHMMSS.xlsx`

- **拆分规则**: 两人名按 `、` 或 `/` 分隔，数量/金额/毛利各分一半

2.4 inventory_snapshot（库存快照）

```sql

CREATE TABLE inventory_snapshot (

snapshot_date TEXT,

货号 TEXT,

店铺编码 TEXT,

颜色编码 TEXT,

数量 REAL,

... ,

snapshot_type TEXT, -- 'full'（周日） or 'delta'（周一至六）

UNIQUE(snapshot_date, 货号, 店铺编码, 颜色编码)

);

```

- **全量快照**: 每周日，~7K+ 行

- **增量快照**: 周一至六，只记变动行

- **查询**: `get_inventory_on_date(date)` 找最近周日 full + 累加 delta

2.5 inventory_ledger（变动流水）

```sql

CREATE TABLE inventory_ledger (

change_date TEXT,

货号 TEXT,

店铺编码 TEXT,

颜色编码 TEXT,

change_type TEXT, -- 'sale' / 'adjustment_in' / 'adjustment_out'

数量 REAL,

...

);

```

---

3. 🚨 核心数据规则

3.1 sales_ledger 和 staff_sales 是同一批数据

**这是最严重的错误，已犯 3 次。**

ERP 无法同时导出店铺和营业员，必须分两次导出。但数据是同一批销售。

- ✅ 两个表各自独立，**绝不能加总**

- ✅ 报表只用其中一个表（周报用 sales_ledger，营业员业绩用 staff_sales）

- ❌ sales_ledger.金额 + staff_sales.金额 = 金额翻倍

**自检**: 每次做报表时问自己——两个表有没有无意中加在一起？

3.2 数据中台合并模式

数据中台每天发两封邮件（店铺维度 + 营业员维度），按合并键导入：

- **合并键**: `(商品编码, 颜色编码, 数量, 单价, 金额)` 五字段精确匹配

- **期望匹配率**: ≥94%

- ❌ 不能各自独立导入 → 双倍数据

3.3 SQLite UNIQUE + NULL 坑

`INSERT OR IGNORE` 在 UNIQUE 索引列含 NULL 时**不防重**（SQLite 允许多个 NULL 视为不同值）。

- 批量导入前需先 `DELETE WHERE 日期=?` 清理该日期数据

- 去重时用 `SELECT ... GROUP BY HAVING COUNT(*) > 1` 先确认

---

4. 数据来源与 Pipeline

4.1 每日 Pipeline（22:30）

**Cron ID**: `b7a874fb42d0` | **时间**: 30 22 * * *

**文件（Mobile BI 邮件，主题 `【Mobile BI】自动订阅报表 (1份)`）**:

**硬性规则**:

- 日期从 xlsx 文件名提取，不用系统时钟

- 只查当天 22:00 之后的邮件

- 4 个附件日期必须一致

- 邮件正文"数据范围"必须与文件名日期一致

**投递**（飞书私聊 `oc_569a01e75d67f5f0422a994aa7132365`）:

1. 文字总结（双数/金额/毛利/各店）

2. 📈 销售分析: https://sieta.vip/sietadata/sales_analysis_mobile.html

3. 📸 销售图片: https://sieta.vip/sietadata/sales_pics.html

4.2 每周周报（周一 09:00）

**Cron ID**: `314b745063bd` | **时间**: 0 9 * * 1

- 脚本: `~/sietadata/scripts/generate_weekly_report.py`

- 生成上周（周一~周日）周报 HTML

- 投递飞书群: `oc_9eeddda2511e3e8c62ed671017134814`（同每晚 22:30 群）

4.3 数据库备份

**Cron ID**: `1e93398d4126` | **时间**: 59 22 * * 6（每周六 22:59）

- 快照到 `~/sietadata/db/snapshots/sieta_YYYY-MM-DD.db`

- 保留最新 5 份滚动

- 脚本: `~/sietadata/scripts/db_snapshot.sh`

---

5. 报表页面设计规范

5.1 参考模板

5.2 设计系统（Neo-brutalism）

- **背景色**: `#FFFDF5`

- **卡片**: 白色背景 + `3px solid #000` 边框 + `4px 4px 0 #000` 阴影

- **字体**: `-apple-system, BlinkMacSystemFont, "Noto Sans SC", sans-serif`

- **KPI 数值**: `1.6em`, `font-weight:900`

- **按钮**: `#FFD93D` 背景, `3px solid #000` 边框

5.3 店铺排序

固定顺序: STA102（二店）→ STA104（四店）→ STA105（五店）→ STA106（六店）→ STA108（八店）

5.4 品牌颜色映射

5.5 图表配置（Chart.js v4）

**柱状图（各店销售额）**:

- `indexAxis: 'y'` 横向

- 双坐标轴：上=销售额(¥)、下=双数

- `barPercentage: 1.0, categoryPercentage: 0.78`

- 销售额数据集: `#FF6B6B`, yAxisID='y', xAxisID='x1'

- 双数数据集: `#C4B5FD`, yAxisID='y', xAxisID='x'

**环形图（品牌排名）**:

- 3 层嵌套: 内层双数(weight=2, CC透明度) + 透明间隔(weight=1) + 外层销售额(weight=7)

- `cutout: '2%'`

- 仅标注前 3 名: `display: function(ctx){return ctx.dataIndex<3}`

- datalabels 插件本地托管: `/sietadata/chartjs-plugin-datalabels.min.js`

5.6 周报结构

1. 标题: `Sieta 销售分析` + `YYYYWNN · YYYY/MM/DD — YYYY/MM/DD`（18px, bold）

2. KPI 五栏（销售额/双数/毛利/店铺均价/商场均价，含日均）

3. 各店销售额柱状图

4. 品牌排名环形图

5. 营业员业绩表

6. 每日明细表（黄色背景）

---

6. 飞书通知规则

---

7. 🚨 硬性禁令

1. **绝不**把 `sales_ledger` 和 `staff_sales` 的金额/双数相加

2. **绝不**只给本地文件路径（必须给 HTTP 链接）

3. **绝不**跳过 gbrain/记忆召回直接动手

4. **绝不**在 `.xls` 文件上用默认 `header=0`（oupu 老格式表头在第 5 行）

5. **绝不**在数据库为空时跑 `INSERT OR IGNORE` 不先 `DELETE`（UNIQUE+NULL 不防重）

6. **绝不**修改 Gallery/Finance 页面时破坏现有 `Sieta@2006` token 登录

7. **绝不**顺手加功能——修 Bug 只修目标，不改造工作流

8. **决不**用 guesswork——不知道就说不知道

---

8. Cron 任务清单

---

9. API 层

所有 API 在 `~/admin-auth-server.py` (port 7891)，nginx `/api/` 代理:

⚠️ sietadata 接口**不加** `get_current_user` 检查。

---

10. 环境与依赖

依赖: `pip install openpyxl pandas xlrd -q`

himalaya: `~/.cargo/bin/himalaya`, 配置 `foxmail` 账户