v0.2.1 add unified inquiry receive api

Author: coowinit

.gitignore

@@ -1,7 +1,9 @@
 /vendor/
 /storage/logs/*.log
-/storage/uploads/*
-!/storage/uploads/.gitkeep
-.env
+/storage/cache/
+/node_modules/
+/dist/
+/.idea/
+/.vscode/
 .DS_Store
 Thumbs.db

CHANGELOG.md

@@ -1,24 +1,25 @@
 # Changelog
 
-## v0.1.0 - Initial scaffold
+## v0.2.0
 
-### Added
-- Full pure PHP project scaffold
-- Front controller routing
-- Login and logout flow
-- CSRF protection helper
-- Session helper
-- PDO database wrapper
-- Dashboard page
-- Inquiry list page
-- Inquiry detail page
-- Site list page
-- Blacklist IP page
-- Personal settings page
-- SQL schema and seed files
-- Basic responsive admin UI
+- Added unified receive API endpoint
+- Added API health check endpoint
+- Added `site_key + api_token` validation
+- Added required field validation for `name`, `email`, `content`
+- Added blocked IP check before insert
+- Added basic spam checks for honeypot, duplicate content, link count, IP/email rate limit
+- Added storage for `extra_data` and `raw_payload`
+- Added inquiry filters in the backend
+- Added quick status update actions
+- Added blocked IP add form in the backend
+- Added API quick start info in dashboard and sites page
+- Added GitHub Actions build-release workflow
+- Added PHP and JavaScript integration examples
 
-### Notes
-- This version is the foundation version.
-- External website inquiry submission API is not included yet.
-- Site token authentication and cross-site receiving flow will be implemented in the next version.
+## v0.1.0
+
+- Initial scaffold version
+- Added login/logout
+- Added dashboard, inquiries, detail, sites, blocked IPs, profile pages
+- Added schema and seed files
+- Added basic project structure and UI

README.md

@@ -1,66 +1,120 @@
 # Inquiry Management System
 
-Version: v0.1.0
+Version: **v0.2.0**
 
-A lightweight inquiry management system built with pure PHP + MySQL.
+A pure PHP + MySQL inquiry management system for collecting inquiry forms from multiple websites into one centralized backend.
 
-## Current scope in v0.1.0
+## v0.2.0 Highlights
 
-- Project scaffold and directory structure
-- PDO database connection layer
-- Login / logout
-- Session + CSRF helper
-- Basic dashboard
-- Inquiry list page
-- Inquiry detail page
-- Site list page
-- Blacklist IP page
-- Personal settings page
-- SQL schema and seed files
-- Changelog and versioned delivery structure for GitHub Desktop workflow
+- Unified receive API is ready: `/api/v1/inquiries/submit`
+- `site_key + api_token` validation
+- Required field validation for `name`, `email`, `content`
+- Stores both `extra_data` and `raw_payload`
+- Basic anti-spam checks
+- Blocked IP validation
+- Inquiry filters and quick status actions in the backend
+- GitHub Actions ZIP packaging workflow included
 
-## Recommended environment
+## Environment
 
 - PHP 8.1+
-- MySQL 5.7+ or MariaDB 10.4+
-- Apache / Nginx
+- MySQL 5.7+ or MySQL 8+
+- Apache or Nginx
 
-## Quick start
+## Installation
 
-1. Create a new MySQL database, for example: `inquiry_system`
-2. Import the SQL files in order:
+1. Create a database, for example: `inquiry_system`
+2. Import:
    - `database/schema.sql`
    - `database/seed.sql`
-3. Update database config in:
-   - `config/database.php`
-4. Put the project in your web root and point the document root to:
-   - `public/`
-5. Open the system in your browser.
+3. Update database settings in `config/database.php`
+4. Point your web root to `public/`
+5. Open the project in your browser
 
-## Default admin account
+## Default Admin Account
 
 - Username: `admin`
 - Password: `Admin@123456`
 
-Please change the password immediately after first login.
+## Main Backend Routes
 
-## Suggested GitHub Desktop workflow
+- `/login`
+- `/dashboard`
+- `/inquiries`
+- `/sites`
+- `/tools/blacklist-ips`
+- `/profile`
 
-For each delivery version:
+## API Routes
 
-1. Replace the local project files with the new full package
-2. Review `CHANGELOG.md`
-3. Commit with a versioned message, such as:
-   - `v0.1.0 initial scaffold`
-   - `v0.2.0 add inquiry receiving API`
-4. Push to GitHub
-5. Optionally create a Git tag
+### Health Check
 
-## Planned next step
+`GET /api/v1/health`
 
-v0.2.0 will focus on:
+### Submit Inquiry
 
-- Inquiry receiving API
-- Site token validation
-- Basic anti-spam checks
-- Insert inquiry records from external websites
+`POST /api/v1/inquiries/submit`
+
+Supported payload types:
+
+- `application/json`
+- standard form POST
+
+### Minimum payload
+
+```json
+{
+  "site_key": "a_main",
+  "api_token": "token_a_main_2026",
+  "name": "John Smith",
+  "email": "john@example.com",
+  "content": "I want more information about your products."
+}
+```
+
+### Optional fields
+
+- `form_key`
+- `title`
+- `country`
+- `phone`
+- `address`
+- `from_company`
+- `source_url`
+- `referer_url`
+- `language`
+- `browser`
+- `device_type`
+- `submitted_at`
+- `client_ip`
+- `extra_data` (array)
+
+Unknown fields will also be merged into `extra_data` automatically.
+
+## Example Files
+
+- `examples/php-forwarder.php`
+- `examples/javascript-fetch-example.js`
+
+## GitHub Actions
+
+Workflow file:
+
+- `.github/workflows/build-release.yml`
+
+It creates a ZIP package automatically when you push a tag like:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+## Notes
+
+Recommended production flow:
+
+1. Website form submits to the current website backend
+2. The current website backend forwards the payload to this central system
+3. This system validates, filters, stores, and manages the inquiry
+
+This is safer than exposing tokens directly in front-end JavaScript.

VERSION.txt

@@ -1 +1 @@
-v0.1.0
+v0.2.0

app/Controllers/Api/InquiryApiController.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Controllers\Api;
+
+use App\Core\Controller;
+use App\Services\InquiryReceiveService;
+
+final class InquiryApiController extends Controller
+{
+    public function options(): void
+    {
+        $this->sendCorsHeaders();
+        http_response_code(204);
+        exit;
+    }
+
+    public function submit(): void
+    {
+        $this->sendCorsHeaders();
+
+        $payload = request_data();
+
+        $authorization = request_header('Authorization');
+        if (!isset($payload['api_token']) && is_string($authorization) && starts_with_ignore_case($authorization, 'Bearer ')) {
+            $payload['api_token'] = trim(substr($authorization, 7));
+        }
+
+        if (!isset($payload['api_token'])) {
+            $siteToken = request_header('X-Site-Token');
+            if (is_string($siteToken) && $siteToken !== '') {
+                $payload['api_token'] = $siteToken;
+            }
+        }
+
+        $service = new InquiryReceiveService();
+        $result = $service->handle($payload, [
+            'request_ip' => request_ip(),
+            'origin_host' => request_origin_host(),
+            'referer_host' => request_referer_host(),
+            'referer_url' => $_SERVER['HTTP_REFERER'] ?? null,
+            'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
+            'user_agent_summary' => substr((string) ($_SERVER['HTTP_USER_AGENT'] ?? ''), 0, 255),
+            'accept_language' => $_SERVER['HTTP_ACCEPT_LANGUAGE'] ?? '',
+            'api_token' => $payload['api_token'] ?? '',
+        ]);
+
+        json_response($result['body'], $result['status_code']);
+    }
+
+    public function health(): void
+    {
+        $this->sendCorsHeaders();
+        json_response([
+            'success' => true,
+            'message' => 'Inquiry receive API is ready.',
+            'version' => (string) config('app.api.version', 'v1'),
+            'timestamp' => date('c'),
+        ]);
+    }
+
+    private function sendCorsHeaders(): void
+    {
+        if (!(bool) config('app.api.enable_cors', true)) {
+            return;
+        }
+
+        $origin = request_header('Origin');
+        if ($origin) {
+            header('Access-Control-Allow-Origin: ' . $origin);
+            header('Vary: Origin');
+        }
+
+        header('Access-Control-Allow-Methods: POST, OPTIONS, GET');
+        header('Access-Control-Allow-Headers: Content-Type, Authorization, X-Site-Token');
+        header('Access-Control-Max-Age: 86400');
+    }
+}

app/Controllers/DashboardController.php

@@ -7,19 +7,22 @@
 use App\Core\Auth;
 use App\Core\Controller;
 use App\Models\Inquiry;
-
+use App\Models\Site;
 
 final class DashboardController extends Controller
 {
     public function index(): void
     {
         $inquiryModel = new Inquiry();
+        $siteModel = new Site();
 
         $this->view('dashboard/index', [
             'pageTitle' => 'Dashboard',
             'user' => Auth::user(),
             'stats' => $inquiryModel->stats(),
             'latestInquiries' => $inquiryModel->latest(6),
+            'sites' => $siteModel->all(),
+            'apiEndpoint' => base_url('api/v1/inquiries/submit'),
         ]);
     }
 }