contraband_manager/README.md

# 违禁品查获排行榜系统 - 开发文档

## 1. 项目概述
“违禁品查获排行榜系统”是一个用于记录、统计和展示安检团队违禁品查获数据的应用。它包含一个Web界面用于实时展示排行榜，以及一个后端脚本用于数据管理和通知。系统设计旨在提供直观的排行榜展示、便捷的数据管理和自动化的通知功能。

## 2. 逻辑实现

### 2.1 架构概览
项目采用前后端分离的轻量级架构：
- **数据管理层**: `/root/.openclaw/workspace/contraband_manager/update_security_ranking_v2.py` 负责数据的增删改查、人员管理、数据备份和企业微信通知。
- **展示层**: `/root/.openclaw/workspace/contraband_manager/app.py` 是一个基于 Flask 的Web应用，负责从数据文件读取数据并渲染到前端页面，提供实时的排行榜展示和查获详情。
- **数据存储**: 使用 `security_data_v2.json` 作为主要数据存储文件。
- **前端界面**: `/root/.openclaw/workspace/contraband_manager/templates/index.html` 使用HTML、CSS和JavaScript实现响应式设计，提供“本月榜”和“总榜”切换、三甲配色、列表渐入动画、数字滚动特效和详情弹窗功能。

### 2.2 数据管理脚本 (`update_security_ranking_v2.py`)
该脚本是系统的核心数据处理器，提供命令行接口进行数据操作。

#### 2.2.1 核心功能
- **数据加载与保存**: `load_data()` 和 `save_data()` 函数负责从 `security_data_v2.json` 加载和保存数据。`save_data()` 会自动更新元数据（如脚本版本、最后更新时间）并触发异步备份到WebDAV。
- **人员管理**:
    - `add_member(name_with_shift)`: 新增活跃人员，支持“姓名(班次)”格式。
    - `remove_member(name)`: 将人员标记为“离职”状态，不再参与排名，但历史记录保留。
- **记录管理**:
    - `record_entry(name, content, biz_date_manual)`: 录入新的查获记录。支持手动指定业务日期，否则根据当前时间（凌晨0-5点算前一日）自动判定。每条记录会被分配一个唯一ID。
    - `delete_entry(log_id)`: 根据记录ID，将记录标记为“已删除”，数据不会真正移除，但不会在排名和查询中显示。
- **查询功能**:
    - `query_logs(mode, value)`: 根据姓名或日期查询查获记录。
- **排行榜统计**:
    - `get_ranking(target_month)`: 统计指定月份或当前月份（根据业务日期逻辑）的违禁品查获排行榜。
- **企业微信通知**: `send_notification(action_text, data)` 函数在每次数据更新后，异步发送包含最新排名和最近动态的企业微信通知。通知内容经过格式化，支持姓名对齐。
- **WebDAV 备份**: `upload_to_webdav(local_path, remote_sub_path)` 函数负责将 `security_data_v2.json` 和脚本自身备份到WebDAV服务器，确保数据和代码版本安全。

#### 2.2.2 业务日期修正逻辑
- 脚本内定义了北京时区 (`BEIJING_TZ`)。
- `record_entry` 函数在自动判定业务日期时，如果当前时间是当日00:00到05:00之间，则记录归属于前一个日历日。这有助于正确处理跨夜班的查获记录。

### 2.3 Web展示应用 (`app.py`)
这是一个轻量级的Flask应用，专注于数据展示。

#### 2.3.1 核心功能
- **Flask 应用初始化**: 创建Flask应用实例。
- **数据加载与处理**: `load_and_process_data()` 函数负责从 `security_data_v2.json` 读取数据。它将原始数据处理成前端所需的“月榜”和“总榜”格式，并对人员按分数降序排序。
    - **“月榜”**: 仅统计当月有查获记录的活跃人员。
    - **“总榜”**: 统计所有活跃人员（包括0记录），显示他们的总查获数。
- **路由**:
    - `/` (根路径): 渲染 `index.html` 模板，并将处理后的排行榜数据以JSON格式嵌入到页面中。
    - `/api/rankings`: 提供一个API接口，返回纯JSON格式的排行榜数据，供前端进行异步刷新。
- **环境变量支持**: `DATA_FILE`、`FLASK_DEBUG`、`FLASK_HOST` 和 `FLASK_PORT` 可以通过环境变量进行配置。

### 2.4 前端界面 (`templates/index.html`)
采用响应式设计，提供良好的移动端体验。

#### 2.4.1 主要组件与功能
- **头部 (Header)**: 显示应用标题和副标题。
- **Tab 切换**: “本月”和“总榜”两个Tab按钮，用于切换排行榜显示。
- **列表容器**: 动态加载和显示排行榜列表。
- **列表项 (Item)**:
    - 显示排名、姓名、班次和查获票数。
    - 前三名有特殊的金/银/铜配色和阴影效果。
    - 列表项支持点击，会弹出详情弹窗。
    - 列表项采用渐入动画 (`fadeInUp`)。
    - 查获票数有数字滚动动画 (`countPop`)。
- **详情弹窗 (Modal)**:
    - 点击列表项后弹出，显示该人员的所有查获记录详情。
    - 详情内容中的特定关键词（如“打火机”、“管制刀具”等）会被高亮显示。
    - 支持点击弹窗外部或关闭按钮来关闭。
    - 详情列表项也有渐入动画 (`fadeInDetail`)。
- **数据嵌入与异步刷新**:
    - 初始数据通过 `data_json` 变量从Flask后端嵌入到HTML中。
    - 页面每15秒通过 `/api/rankings` 接口异步获取最新数据并刷新列表，实现实时更新。
- **空状态**: 当无数据时，显示友好的“暂无数据”提示。

## 3. 使用指南

### 3.1 数据管理 (通过命令行脚本 `update_security_ranking_v2.py`)
你可以通过在终端执行 Python 脚本来管理数据。

#### 3.1.1 新增成员
格式：`python3 update_security_ranking_v2.py 新增 姓名(班次)`
示例：
```bash
python3 update_security_ranking_v2.py 新增 张三(早班)
python3 update_security_ranking_v2.py 新增 李四(晚班)
```

#### 3.1.2 去除成员 (标记为离职)
格式：`python3 update_security_ranking_v2.py 去除 姓名`
示例：
```bash
python3 update_security_ranking_v2.py 去除 张三
```
被去除的成员将不再参与排名，但历史记录仍保留。

#### 3.1.3 录入查获记录
格式：`python3 update_security_ranking_v2.py 姓名 查获内容`
示例：
```bash
python3 update_security_ranking_v2.py 张三 打火机2个
python3 update_security_ranking_v2.py 李四 仿真枪1把
```
**注意**:
- 脚本会自动判断业务日期（凌晨0-5点算前一日）。
- 每次录入都会增加该成员的查获票数。

#### 3.1.4 补录查获记录 (指定日期)
格式：`python3 update_security_ranking_v2.py 姓名 查获内容 YYYY-MM-DD` (日期格式为 `月-日`，年份默认为当前年份)
示例：
```bash
python3 update_security_ranking_v2.py 张三 不明液体1瓶 02-05
```
这会在当前年份的2月5日为张三补录一条记录。

#### 3.1.5 删除查获记录 (标记为删除)
格式：`python3 update_security_ranking_v2.py 删除 #索引号`
示例：
```bash
python3 update_security_ranking_v2.py 删除 #123
```
记录将被标记为删除，不再显示在排行榜和查询结果中。

#### 3.1.6 查询记录
- **按姓名查询**: `python3 update_security_ranking_v2.py 违禁品查询 姓名`
  示例：`python3 update_security_ranking_v2.py 违禁品查询 张三`
- **按日期查询**: `python3 update_security_ranking_v2.py 违禁品查询 月-日` (日期格式为 `月-日`)
  示例：`python3 update_security_ranking_v2.py 违禁品查询 02-06`

#### 3.1.7 查看排行榜
格式：`python3 update_security_ranking_v2.py 排行榜 [月份]`
- 查看当前月份排行榜（根据业务日期逻辑）：`python3 update_security_ranking_v2.py 排行榜`
- 查看指定月份排行榜：`python3 update_security_ranking_v2.py 排行榜 01` (表示1月) 或 `python3 update_security_ranking_v2.py 排行榜 2026-01`

### 3.2 Web展示 (通过Web应用 `app.py`)
Web界面提供了排行榜的实时展示。

- **访问地址**: 默认通过 `http://127.0.0.1:9517` 访问。如果部署到服务器，则访问服务器IP和对应端口。
- **功能**:
    - 切换“本月”和“总榜”查看不同维度的排名。
    - 点击任意列表项可查看该人员的详细查获记录。
    - 页面每15秒自动刷新数据。

## 4. 部署指南

本系统推荐使用 `systemd` 或 `Docker` 进行部署，并可选择性地使用 `Nginx` 进行反向代理和SSL加密。

### 4.1 前置条件
- Python 3.x 及 `pip`。
- `Flask` 库 (`pip install Flask`)。
- `requests` 库 (`pip install requests`)。
- `supervisor` (推荐用于进程守护，或使用 `systemd`)。
- `curl` (用于WebDAV备份)。

### 4.2 部署步骤

#### 4.2.1 准备项目文件
将 `contraband_manager` 目录下的所有文件（包括 `app.py`, `update_security_ranking_v2.py`, `templates/` 等）上传到服务器的指定目录，例如 `/opt/contraband_ranking/`。

```bash
# 假设你在项目根目录
sudo mkdir -p /opt/contraband_ranking
sudo cp -r contraband_manager/* /opt/contraband_ranking/
sudo cp security_data_v2.json /opt/contraband_ranking/ # 如果数据文件在上一级目录
cd /opt/contraband_ranking
pip install -r requirements.txt # 如果有requirements.txt
```
**注意**: 确保 `security_data_v2.json` 数据文件与 `app.py` 位于同一目录，或者根据 `app.py` 中的 `DATA_FILE` 路径进行配置。建议将 `security_data_v2.json` 放在 `/opt/contraband_ranking/` 目录下。

#### 4.2.2 配置环境变量
你可以在启动脚本或 `systemd` 配置中设置环境变量来覆盖默认值：
- `CONTRABAND_DATA_FILE`: 数据文件的绝对路径 (默认为 `app.py` 同目录下的 `security_data_v2.json`)。
- `FLASK_DEBUG`: `True` 或 `False`，控制 Flask 调试模式 (默认为 `False`)。
- `FLASK_HOST`: Flask 监听的IP地址 (默认为 `127.0.0.1`)。设置为 `0.0.0.0` 可以从外部访问。
- `FLASK_PORT`: Flask 监听的端口 (默认为 `9517`)。
- `WEBHOOK_URL`: 企业微信Webhook URL (在 `update_security_ranking_v2.py` 中配置)。

#### 4.2.3 方式一：使用 Systemd 部署 (推荐)

##### 4.2.3.1 创建 Flask Web 应用的 Systemd 服务
在 `/etc/systemd/system/` 目录下创建 `contraband_ranking_web.service` 文件：
```ini
[Unit]
Description=Contraband Ranking Web Application
After=network.target

[Service]
User=root
WorkingDirectory=/opt/contraband_ranking
ExecStart=/usr/bin/python3 app.py
Restart=always
Environment="FLASK_HOST=0.0.0.0"
Environment="FLASK_PORT=9517"
Environment="CONTRABAND_DATA_FILE=/opt/contraband_ranking/security_data_v2.json"
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```
**注意**: `User` 可以改为非root用户，但需要确保该用户对 `/opt/contraband_ranking/` 目录和 `security_data_v2.json` 文件有读写权限。

##### 4.2.3.2 创建数据管理脚本的 Systemd Timer (可选，用于定时执行统计或清理任务)
如果你需要定时执行 `update_security_ranking_v2.py` 的某些功能（例如每日/每月统计、数据清理等），可以创建 `systemd` timer。

创建 `contraband_ranking_update.service`：
```ini
[Unit]
Description=Contraband Ranking Data Update
After=network.target

[Service]
User=root
WorkingDirectory=/opt/contraband_ranking
ExecStart=/usr/bin/python3 update_security_ranking_v2.py # 这里可以添加具体参数，例如 排行榜
StandardOutput=journal
StandardError=journal
```

创建 `contraband_ranking_update.timer` (例如，每天凌晨2点执行)：
```ini
[Unit]
Description=Run Contraband Ranking Data Update Daily

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true

[Install]
WantedBy=timers.target
```

##### 4.2.3.3 启用并启动服务
```bash
sudo systemctl daemon-reload
sudo systemctl enable contraband_ranking_web.service
sudo systemctl start contraband_ranking_web.service
# 如果创建了timer
sudo systemctl enable contraband_ranking_update.timer
sudo systemctl start contraband_ranking_update.timer
```

##### 4.2.3.4 查看状态和日志
```bash
sudo systemctl status contraband_ranking_web.service
sudo journalctl -u contraband_ranking_web.service -f
```

#### 4.2.4 方式二：使用 Docker 部署 (推荐，更易于环境隔离和迁移)

##### 4.2.4.1 创建 Dockerfile
在 `/opt/contraband_ranking/` 目录下创建 `Dockerfile`：
```dockerfile
# 使用官方Python运行时作为父镜像
FROM python:3.9-slim-buster

# 设置工作目录
WORKDIR /app

# 复制requirements.txt并安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目文件
COPY . .

# 暴露端口
EXPOSE 9517

# 定义默认命令来运行应用程序
CMD ["python3", "app.py"]
```
如果 `requirements.txt` 不存在，你需要根据 `app.py` 和 `update_security_ranking_v2.py` 的依赖（`Flask`, `requests`）手动创建。

##### 4.2.4.2 构建 Docker 镜像
在 `/opt/contraband_ranking/` 目录下执行：
```bash
sudo docker build -t contraband-ranking-app .
```

##### 4.2.4.3 运行 Docker 容器
```bash
sudo docker run -d \
  --name contraband-ranking \
  -p 9517:9517 \
  -v /opt/contraband_ranking/security_data_v2.json:/app/security_data_v2.json \
  -e FLASK_HOST=0.0.0.0 \
  -e FLASK_PORT=9517 \
  contraband-ranking-app
```
**说明**:
- `-d`: 后台运行容器。
- `--name contraband-ranking`: 为容器指定名称。
- `-p 9517:9517`: 将主机的 9517 端口映射到容器的 9517 端口。
- `-v /opt/contraband_ranking/security_data_v2.json:/app/security_data_v2.json`: 将主机上的数据文件挂载到容器内部，以便数据持久化和外部管理。
- `-e`: 设置环境变量。

##### 4.2.4.4 查看 Docker 容器状态和日志
```bash
sudo docker ps
sudo docker logs -f contraband-ranking
```

#### 4.2.5 使用 Nginx 进行反向代理和 HTTPS (可选，生产环境推荐)

如果你希望通过域名访问并启用 HTTPS，可以使用 Nginx 作为反向代理。

##### 4.2.5.1 安装 Nginx
```bash
sudo apt update
sudo apt install nginx
```

##### 4.2.5.2 配置 Nginx
在 `/etc/nginx/sites-available/` 目录下创建或编辑配置文件 (例如 `contraband_ranking.conf`)：
```nginx
server {
    listen 80;
    server_name your_domain.com; # 替换为你的域名

    location / {
        proxy_pass http://127.0.0.1:9517; # 指向你的Flask应用监听地址和端口
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 如果需要 HTTPS，使用 Certbot 配置
    # listen 443 ssl;
    # ssl_certificate /etc/letsencrypt/live/your_domain.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/your_domain.com/privkey.pem;
    # include /etc/letsencrypt/options-ssl-nginx.conf;
    # ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}
```

##### 4.2.5.3 启用 Nginx 配置并重启
```bash
sudo ln -s /etc/nginx/sites-available/contraband_ranking.conf /etc/nginx/sites-enabled/
sudo nginx -t # 测试配置
sudo systemctl restart nginx
```

##### 4.2.5.4 配置 HTTPS (推荐使用 Certbot)
如果你有域名，强烈建议使用 Let's Encrypt 和 Certbot 来获取免费的 SSL 证书并配置 HTTPS。
```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your_domain.com
```
按照提示操作即可。Certbot 会自动修改 Nginx 配置并设置证书自动续期。

## 5. 数据文件结构 (`security_data_v2.json`)
```json
{
  "meta": {
    "script_version": "v2.3.8",
    "last_update": "2026-02-06T20:30:00+08:00"
  },
  "members": {
    "张三": {
      "shift": "早班",
      "status": "active"
    },
    "李四": {
      "shift": "晚班",
      "status": "offboarded"
    }
  },
  "logs": [
    {
      "id": 0,
      "name": "张三",
      "content": "打火机2个",
      "actual_time": "2026-02-06T10:00:00+08:00",
      "biz_date": "2026-02-06",
      "biz_month": "2026-02",
      "is_deleted": false
    },
    {
      "id": 1,
      "name": "李四",
      "content": "仿真枪1把",
      "actual_time": "2026-02-06T03:00:00+08:00",
      "biz_date": "2026-02-05",
      "biz_month": "2026-02",
      "is_deleted": false
    }
  ],
  "last_id": 1
}
```
- `meta`: 包含脚本版本和最后更新时间等元数据。
- `members`: 存储所有人员信息。
    - `name`: 成员姓名。
    - `shift`: 班次。
    - `status`: `active` (活跃) 或 `offboarded` (离职)。
- `logs`: 存储所有查获记录。
    - `id`: 唯一记录ID。
    - `name`: 查获人员姓名。
    - `content`: 查获内容。
    - `actual_time`: 记录的实际时间（ISO格式）。
    - `biz_date`: 业务日期 (yyyy-mm-dd格式，考虑了跨夜班逻辑)。
    - `biz_month`: 业务月份 (yyyy-mm格式)。
    - `is_deleted`: 布尔值，标记记录是否被删除。
- `last_id`: 最后一个记录的ID，用于生成新的唯一ID。

## 6. 维护与扩展
- **数据备份**: `update_security_ranking_v2.py` 已集成WebDAV备份功能，请确保WebDAV配置正确。
- **日志**: Web应用和脚本的输出都建议通过 `systemd journal` 或 Docker 日志进行监控。
- **扩展功能**:
    - 如果需要新的数据管理功能，可以直接修改 `update_security_ranking_v2.py`。
    - 如果需要新的Web展示页面或功能，可以修改 `app.py` 和 `templates/index.html`。
    - 新增关键词高亮：修改 `index.html` 中的JavaScript `replace` 正则表达式。