noorulain3479-del/Track-My-Tax

# Track-My-Tax 为 UET Peshawar 开发的基于 Blockchain 治理的基础设施税务跟踪系统。 使用 **React + Vite + TypeScript**（前端）、**Python Flask**（后端）、**MySQL**（数据库）和 **Ganache**（本地 Ethereum 链）构建。 ## 如何在 VS Code 中运行此项目 — 分步指南 ### 步骤 1 — 安装前置条件 在继续之前，请下载并安装每个工具。 | 工具 | 下载 | 备注 | |------|----------|-------| | Node.js 18+ | https://nodejs.org | 选择 LTS 版本 | | Python 3.10+ | https://python.org/downloads | 安装时勾选“Add to PATH” | | MySQL 8.0 | https://dev.mysql.com/downloads/installer | 使用“Developer Default”安装设置 | | VS Code | https://code.visualstudio.com | 安装 Python 和 ESLint 扩展 | | Ganache CLI | 安装 Node.js 后在终端中运行 `npm install -g ganache` | | ### 步骤 2 — 在 VS Code 中打开项目 1. 将下载的 zip 文件解压到一个文件夹，例如 `C:\Projects\track-my-tax` 2. 打开 VS Code → **File → Open Folder** → 选择该文件夹 3. 打开集成终端：**View → Terminal**（或 `` Ctrl + ` ``） ### 步骤 3 — 设置 MySQL 数据库 打开 MySQL Command Line Client（随 MySQL 一起安装）并运行： ``` mysql -u root -p < backend/setup_db.sql ``` 出现提示时，输入您的 MySQL root 密码。 这将创建： - 数据库：`escrow` - 用户：`escrow_user` / 密码：`1k2a3p` - 所有表 + 4 个种子项目 + 管理员账号 验证是否成功： ``` mysql -u escrow_user -p1k2a3p USE escrow; SHOW TABLES; ``` 您应该会看到：`users`、`projects`、`transactions`、`risk_predictions`、`verifications`、`blockchain_logs` ### 步骤 4 — 启动 Ganache（本地 Blockchain） 在 VS Code 的一个**新终端标签页**中，运行： ``` ganache --port 7545 --accounts 10 --deterministic ``` 保持此终端运行。您将看到打印出的 10 个账号及其私钥。让其保持打开状态。 ### 步骤 5 — 部署 Smart Contract（Hardhat） 在一个**新终端标签页**中，进入 backend 文件夹并安装 Hardhat： ``` cd backend npm install ``` 编译并部署到 Ganache： ``` npm run compile npm run deploy ``` 您将看到类似以下的输出： ``` ✅ CitizenCredits deployed at: 0xAbc123... CONTRACT_ADDRESS=0xAbc123... ``` 复制该地址。打开 `backend/.env` 并设置： ``` CONTRACT_ADDRESS=0xAbc123... ``` ### 步骤 6 — 启动 Flask 后端 在一个**新终端标签页**中： ``` cd backend python -m venv venv ``` **Windows:** ``` venv\Scripts\activate ``` **macOS / Linux:** ``` source venv/bin/activate ``` 安装依赖并启动： ``` pip install -r requirements.txt python app.py ``` Flask 将在 **http://127.0.0.1:5000** 启动 ### 步骤 7 — 启动 React 前端 在一个**新终端标签页**中（回到项目根目录，**不要**在 `backend/` 内）： ``` npm install npm run dev ``` 前端将在 **http://localhost:5173** 启动 打开浏览器并访问：**http://localhost:5173** ### 步骤 8 — 登录 | 邮箱 | 密码 | 角色 | |-------|----------|------| | admin@tax.local | admin123 | Admin | ## QR Code 功能 点击导航栏右上角的 **QR 图标**（网格图标 ⊞）。将会弹出一个浮层，其中包含一个指向您当前 URL 的实时可扫描 QR Code，以及一个一键复制按钮。使用同一 Wi-Fi 下的任何手机扫描即可在移动设备上打开应用。 ## 项目结构 ``` track-my-tax/ ├── backend/ │ ├── app.py # Flask API (all 17 routes) │ ├── setup_db.sql # MySQL schema + seed data — run this first │ ├── requirements.txt # Python packages │ ├── package.json # Hardhat devDependencies │ ├── hardhat.config.js # Hardhat → Ganache network config │ ├── .env # DB + Ganache + contract config │ ├── contracts/ │ │ └── CitizenCredits.sol # Solidity escrow smart contract │ └── scripts/ │ └── deploy.js # Hardhat deployment script ├── src/ │ ├── views/ # All page components │ │ ├── HomeSplash.tsx # Landing page with stats + QR │ │ ├── ProjectsMatrix.tsx # Project list grid │ │ ├── ProjectDetails.tsx # Single project + milestones │ │ ├── AdminControlRoom.tsx # Admin escrow controls │ │ ├── AnalyticsCenter.tsx # Charts + risk analytics │ │ ├── BlockchainMonitor.tsx # Ganache accounts + tx logs │ │ ├── VerificationDesk.tsx # Field image forensic upload │ │ └── AuthView.tsx # Login + Register │ ├── contexts/ │ │ └── AuthContext.tsx # Auth state wired to Flask /api/auth/* │ ├── components/ │ │ ├── layout/ │ │ │ ├── Layout.tsx # App shell │ │ │ ├── TopBar.tsx # Header with QR popover + user menu │ │ │ └── Dock.tsx # Bottom navigation bar │ │ └── ui/ # Reusable UI primitives │ ├── lib/ │ │ ├── blockchain.ts # API client (all Flask calls) │ │ └── utils.ts │ └── types/index.ts # TypeScript interfaces ├── public/ ├── index.html ├── vite.config.ts ├── package.json # Frontend deps (React, Vite, etc.) ├── tsconfig.json └── README.md # This file ``` ## Flask API 端点 | 方法 | 路径 | 描述 | |--------|------|-------------| | POST | /api/auth/login | 登录 | | POST | /api/auth/register | 注册（仅限 Faculty / Student） | | GET | /api/projects | 列出所有项目 | | GET | /api/projects/:id | 项目详情 + milestones | | POST | /api/projects | 创建项目（Admin） | | PUT | /api/projects/:id | 更新项目（Admin） | | DELETE | /api/projects/:id | 删除项目（Admin） | | GET | /api/transactions | 所有 transactions | | POST | /api/escrow/allocate | 分配 credits（Admin） | | POST | /api/escrow/freeze | 冻结 escrow（Admin） | | POST | /api/escrow/release | 释放 escrow（Admin） | | POST | /api/risk-prediction/predict | 运行 RandomForest 风险预测 | | GET | /api/risk-prediction/history | 预测审计日志 | | POST | /api/verification/analyze | MobileNetV2 取证检查 | | GET | /api/verification/results | 验证历史记录 | | GET | /api/blockchain/accounts | Ganache ETH + CitizenCredits 余额 | | GET | /api/blockchain/logs | Contract 调用日志 | | GET | /api/ml/evaluation | ML 评估报告（ASCII 表格） | ## ML 评估指标 在后端启动后访问此 endpoint： ``` GET http://127.0.0.1:5000/api/ml/evaluation ``` 返回以下内容的 ASCII 表格： - **MobileNetV2**（图像验证）：每个类别的 Recall 和 F1-score - **RandomForest**（风险评分）：特征重要性排名 ## 环境变量 `backend/.env`: ``` DB_USER=escrow_user DB_PASS=1k2a3p DB_HOST=127.0.0.1 DB_NAME=escrow GANACHE_URL=http://127.0.0.1:7545 CONTRACT_ADDRESS=0x0000000000000000000000000000000000000000 SECRET_KEY=your-flask-secret-key ``` `.env`（前端根目录）： ``` VITE_API_URL=http://127.0.0.1:5000/api ``` ## 常见问题 | 问题 | 解决方法 | |---------|-----| | `npm install` 失败 | 确保已安装 Node.js 18+。运行 `node -v` 进行检查 | | `npm run deploy` 失败 | 确保 Ganache 首先在端口 7545 上运行 | | `pip install` 安装 TensorFlow 失败 | 使用 Python 3.10–3.11（不要用 3.12）。使用的是 TF CPU 版本 | | MySQL 连接被拒绝 | 启动 MySQL 服务：`net start mysql80`（Windows） | | 找不到 Ganache | 运行 `npm install -g ganache` 然后重启 VS Code 终端 | | 端口 5000 已被占用 | 运行 `npx kill-port 5000` | | 端口 5173 已被占用 | 运行 `npx kill-port 5173` | | 前端显示 mock 数据 | 确保在启动前端之前，Flask 正在端口 5000 上运行 | ## 技术栈 | 层级 | 技术 | |-------|-----------| | Frontend | React 18, Vite 6, TypeScript, Tailwind CSS v4, Framer Motion, Recharts | | Backend | Python 3.10+, Flask 3, Flask-SQLAlchemy, Flask-CORS | | Database | 通过 PyMySQL 连接的 MySQL 8 | | Blockchain | Ganache（本地）, Web3.py, Solidity, Hardhat | | ML | scikit-learn RandomForest, TensorFlow MobileNetV2 (CPU) | ## 贡献者 - @Faiza-Khalid — 项目合作者

标签：Apex, Flask, React, Solidity, Syscalls, 区块链, 图像取证, 政务透明, 智能合约, 机器学习, 自动化攻击, 逆向工具