添加 readme.md

readme.md

@@ -0,0 +1,162 @@
+
+---
+# 项目：净流  
+# 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）
+
+本系统仅用于内部风险防控与教学演示。  
+禁止用于非法监控、人身攻击或超出授权范围的数据处理。
+
+开发者不承担因协议滥用导致的任何法律与伦理后果。
+
+> **你所收容的，或许只是一个客户。**  
+> **但在数据之海中，它可能已是不可名状之物。**
+
+---