---
# 项目：净流  
# Project: CleanFlow

> **识别.收容.处置**  
> *Identify. Contain. Dispose.*

本系统用于检测并收容电子商务环境中的**异常客户行为个体**（Anomalous Customer Entities, ACE）。  
所有上传的订单数据将被视为潜在污染源，自动进行模式比对与威胁评估。

恶意客户库（`/suspects/*.json`）即为**收容单元列表**，每一条记录代表一个已被确认的异常实体。

⚠️ **警告**：本系统不提供道德判断。它只执行协议。

---

### 🚀 核心协议（Core Protocols）

* 📦 **样本提交**：上传 `.xlsx` 订单文件作为行为样本
* 🧠 **收容单元管理**：对已确认异常个体进行增、删、查、改
* 📊 **三级折叠视图**：按 **地址 → 客户 → 订单号** 展示异常关联网络
* 🔍 **威胁过滤**：支持关键词搜索与条件筛选
* 💾 **数据归档**：纯 JSON 存储，确保可迁移与审计
* 🌌 **前端渲染**：基于 Tailwind 的动态 UI，模拟认知滤网

---

### 📁 基础设施结构（Facility Structure）

```
project_root/
├── app.py                 # 主控程序（Protocol Controller）
├── suspects/              # 收容单元数据库
│   ├── test.json          # 测试收容单元
│   └── ...
├── uploads/               # 临时样本存储区（自动清理）
├── static/
│   └── index.html         # 认知界面（前端）
└── README.md              # 本文件（协议文档）
```

---

### ⚙️ 运行环境要求（System Requirements）

* Python ≥ 3.8
* Flask ≥ 2.3 （协议调度框架）
* pandas ≥ 2.0 （行为数据分析引擎）
* openpyxl ≥ 3.1 （样本解析器）

---

### 🧩 协议部署流程（Deployment）

```bash
sudo apt update
sudo apt install python3 python3-pip -y
pip install flask pandas openpyxl
```

---

### ▶️ 启动主控程序

```bash
python3 app.py
```

启动后接入认知界面：

👉 [http://localhost:5000](http://localhost:5000)  
或  
👉 `http://<你的服务器IP>:5000`

---

### 📤 样本分析流程（Sample Analysis）

1. 接入认知界面，选择 `[📦 订单分析]`
2. 提交 `.xlsx` 行为样本
3. 系统自动执行 **威胁匹配协议**
4. 输出结果以「地址 → 客户 → 订单」三级结构展开  
   （默认展开地址层，以加速威胁溯源）

> ✅ 所有匹配个体将被标记为 **潜在异常**，等待收容确认。

---

### 🧠 收容单元管理（Containment Management）

1. 切换至 `[🧠 恶意客户管理]` 模块
2. 可执行以下操作：

   * **新建收容库**：创建新的 JSON 收容单元文件
   * **威胁检索**：按姓名、手机号、备注进行模糊匹配
   * **新增收容**：录入新确认的异常个体信息
   * **更新档案**：修正或补充个体行为记录
   * **销毁记录**：移除误判或已净化个体（慎用）

3. 所有数据将实时归档至 `/suspects/*.json`

---

### 📡 外部接口规范（API Endpoints）

| 方法       | 路径                          | 功能说明                     |
| -------- | --------------------------- | -------------------------- |
| `GET`    | `/api/suspects`             | 获取所有收容单元文件列表       |
| `GET`    | `/api/suspects/<file>.json` | 读取指定收容单元内容           |
| `POST`   | `/api/suspects/<file>.json` | 创建新收容库（空单元）         |
| `PUT`    | `/api/suspects/<file>.json` | 更新收容单元内容               |
| `DELETE` | `/api/suspects/<file>.json` | 销毁收容单元文件（不可逆操作）  |
| `POST`   | `/api/analyze`              | 提交样本并启动威胁分析协议     |

---

### 💾 收容单元数据结构（ACE Schema）

每个 `.json` 文件代表一个收容库，结构如下：

```json
[
  {
    "name": "刘**",
    "phone": "1*********7",
    "address": "湖南省 株洲市 醴陵市",
    "store": "",
    "registertime": "2025-10-05 14:30:00",
    "order_id": "1184,2943,3020",
    "note": "辱骂客服，多次恶意退货",
    "info_url": "https://example.com"
  }
]
```

> 📌 字段说明：  
> `order_id`：关联的异常行为编号（污染链）  
> `note`：行为日志摘要  
> `info_url`：外部证据链接（可选）

---

### 🧰 故障排查指南（Troubleshooting）

* `Unexpected token '<'` → 系统返回错误页面，检查 Flask 日志
* `404 文件不存在` → 收容库文件缺失，手动创建或使用「新建」功能
* `Tailwind 警告` → CDN 加载问题，可替换为本地构建版本

---

### 🛡️ 安全声明（Security Notice）

本系统仅用于内部风险防控与教学演示。  
禁止用于非法监控、人身攻击或超出授权范围的数据处理。

开发者不承担因协议滥用导致的任何法律与伦理后果。

> **你所收容的，或许只是一个客户。**  
> **但在数据之海中，它可能已是不可名状之物。**

---