# 门店检测工作台 · 换机迁移说明

> 打包时间：2026-10-30
> 数据现状：2026-10 周期，1409 家门店；考核阈值与反馈文案配置均已随包带走

---

## 一、新电脑需要什么

只需 **Python 3.8 或更高版本**（Windows 官方安装包即可），**不需要 pip 安装任何第三方库**——后端是 Python 标准库写的，前端已本地化（断网也能跑）。

安装 Python 时务必勾选 **Add python.exe to PATH**。

检查是否装好：打开 PowerShell 或 CMD，输入

```
python --version
```

能显示 `Python 3.x.x` 即可。

---

## 二、怎么跑起来

### Windows（原方案）

1. 把压缩包解压到任意目录（建议放 D 盘，路径不要有空格更省事，例如 `D:\门店检测工作台\`）
2. 进入 `store-ops` 文件夹
3. 双击 **`启动工作台.bat`**
4. 浏览器会自动打开 `http://127.0.0.1:8787`；窗口别关，关了服务就停

窗口里同时会打印**局域网访问地址**（形如 `http://192.168.x.x:8787`），同事用这个地址访问。

### macOS / Linux（2026-10-31 起支持）

1. 把 `门店检测工作台` 文件夹放到任意目录
2. 进入 `store-ops` 文件夹
3. 双击 **`启动工作台.command`**；若系统提示「无法打开，因为来自身份不明的开发者」，右键点该文件 → 选「打开」→ 再点「打开」，只需一次
4. 浏览器会自动打开 `http://127.0.0.1:8787`；终端窗口别关，关了服务就停

换端口 / 只给本机用：

```bash
./启动工作台.command 9000       # 换端口
./启动工作台.command --local    # 只允许本机访问
```

> macOS 自带 Python 3 即可（`python3 --version` 能显示 3.7+ 就行），无需 pip 安装任何库。
> macOS 的防火墙放行：首次运行时系统会弹「是否允许 Python 接受传入连接」，点「允许」即可，不需要 `开放局域网访问.bat`（那是 Windows 专用）。

### 其他电脑 / 手机访问不了时

双击 `store-ops\开放局域网访问.bat`（会自动申请管理员权限），放行 TCP 8787 端口，一次即可。

仍然不行就按顺序排查：

1. 两台设备是否连同一个 WiFi / 路由器
2. 公司 WiFi 是否开了 AP 隔离（客户端隔离）—— 开了同网段也互访不了，找网管关
3. 本机 8787 是否被其他程序占用（改端口：`python backend/server.py --port 9000`）
4. 新电脑的 IP 和旧电脑不同，地址以启动窗口打印的为准

> ⚠️ 本服务**没有登录密码**，同一内网的人都能看数据和改配置。只在公司办公网用，别在公共 WiFi 上开。想只给本机用：`python backend/server.py --local`。

---

## 三、数据在哪

`store-ops\data\app.db` —— **所有东西都在这一个文件里**：

| 内容 | 说明 |
|---|---|
| 门店数据 | 2026-10 周期 1409 家门店的指标与日/月明细 |
| 考核阈值 | 你改过的核销金额基准等配置 |
| 反馈文案 | 43 个文案模板（含你自定义的「近30天成交…」概览行） |
| 导入历史 | 每次导入的批次记录 |

**迁移时最不能丢的就是这个文件**。想备份就单独复制它。

### 每天怎么导新数据

两种方式，任选：

- 左侧菜单 **【导入数据】** → 选文件 → 开始导入
- 或把文件直接丢进 `store-ops\data\inbox\`，20 秒内自动导入并归档到 `processed\`

支持 `.csv` 和 `.xlsx`。老的 `.xls` 请先用 Excel 另存为 `.xlsx`。
必须包含表头行，列名可以是数据表原始列名（门店ID、门店名称、核销券数…）。

### 想清空重来

关掉服务，删除 `store-ops\data\app.db`，重启即会重建空库。
⚠️ 注意：**连同你调过的阈值和文案配置一起清空**，删之前先复制备份。

---

## 四、包里都有什么

```
门店检测工作台/
├─ 换机迁移说明.md          ← 本文件
├─ store-ops/               ← 正式项目（前后端分离，日常用这个）
│  ├─ 启动工作台.bat        ← 双击启动
│  ├─ 开放局域网访问.bat    ← 放行防火墙（管理员）
│  ├─ README.md             ← 功能说明、规则口径、变量对照表
│  ├─ backend/              ← Python 后端（rules.py 是检测规则唯一源）
│  ├─ frontend/             ← 前端页面（含本地 ECharts，断网可用）
│  └─ data/app.db           ← 全部数据与配置
├─ 对标试点/                ← 早期静态演示版（历史留档）
│  ├─ 02_采集脚本/collect_douyin.py
│  ├─ 03_分析/              检测规则、报告生成脚本、10月原始数据
│  └─ 04_输出/              静态 HTML 报告与工作台（双击可直接看）
└─ 项目记录/
   └─ 开发日志_2026-10-29.md ← 需求变更、bug 修复、口径决策记录
```

`对标试点\04_输出\门店工作台_202610.html` 是早期的单文件版本，**不启动服务双击也能看**，适合临时演示或当作备份视图。

---

## 五、换机后建议做一次自检

启动后打开 `http://127.0.0.1:8787`，确认三件事：

1. 顶部显示 **2026-10**、门店数 **1409**
2. 四个 KPI 数字：超违规线 **469** / 评分不达标 **323** / 核销率不达标 **929** / 零核销 **276**
3. 左侧【文案配置】→ 概览行模板仍是 `近30天成交{门店意向成交券数}；核销券数{门店核销券数}；退单券数{门店意向退款券数}`，预览能正常显示数字而不是占位符

三项都对，说明数据、配置、文案全部完好。

---

## 六、常见问题

**双击 bat 一闪而过**
说明没找到 python。确认 `python --version` 可用；或在该窗口手动执行 `python backend\server.py` 看报错。

**提示端口被占用（Address already in use）**
换端口：`python backend\server.py --port 9000`，然后访问 `http://127.0.0.1:9000`。

**页面能开但数据是空的**
`data\app.db` 没带过来或路径放错。确认 `store-ops\data\app.db` 存在且大小约 500KB。

**改了阈值/文案，重启后还在吗**
在。都存 `app.db` 的 settings 表里。

**能不能不装 Python**
不能。后端是 Python 写的；如果不方便装，可以用 `对标试点\04_输出` 里的静态 HTML 应急，但没有导入、筛选、文案配置这些功能。