🥭 Distributor Touch

FMCG B2B Distribution SaaS — Multi-terminal Reach System

Brand — Distributor — Consumer. One chain, fully connected.

15 compliance guardrails · closed-loop mall commerce · automated commissions · distributor training & enablement

---

⭐ If this project saves you time or money, please give it a Star — it keeps the project alive! 🚀

English · 中文文档

---

📖 Table of Contents

• Background
• Why Distributor Touch
• Core Features
• Screenshots
• Architecture
• Quick Start
• Live Demo
• ⬇️ Download
• Editions
• Compliance by Design
• Quality Assurance
• Roadmap
• Tech Stack
• Contributing
• Community & Support
• License

---

🌱 Background

Distributor Touch, built by Tengguan International, is a turnkey B2B distribution SaaS platform purpose-built for the fast-moving consumer goods (FMCG) industry.

FMCG distribution chains are long and crowded — brands manage regional distributors, distributors recruit their own downlines, and retailers need a frictionless way to order. Legacy distribution models suffer from three chronic pain points:

Pain point	The legacy problem
😰 Compliance risk	Multi-level distribution easily crosses into illegal pyramid-selling territory; the bigger the team, the higher the risk
📊 Chaotic management	Distributor tiers tracked in spreadsheets, commissions reconciled by hand — error-prone and opaque
🛍️ Inefficient selling	No unified online mall; distributors post images and prices, deals close over WeChat transfers

We interviewed dozens of FMCG brands and distributors, and worked with our legal team on a dedicated compliance ruling (anchored to CB-LEGAL-2026-DIST-001). The conclusion became our first principle — compliance as code:

Fifteen compliance guardrails are baked directly into the system kernel, so crossing the legal line is architecturally impossible — not just "discouraged".

After multiple rounds of market research, compliance review and engineering hardening, the system passes 504+ automated tests and is production-ready. We are now open-sourcing the Basic Edition to help FMCG brands and entrepreneurs build compliant, efficient and trustworthy distribution networks.

---

❓ Why Distributor Touch

• ✅ Afraid of crossing the pyramid-selling red line? — 15 built-in compliance guardrails: max 2 distributor levels hardcoded, head-count compensation blocked at the engine level
• ✅ Commissions always wrong? — Transaction-driven auto-settlement: commission lands the moment payment succeeds; cancelled orders auto-reverse
• ✅ Distributors lack tools? — Dedicated distributor dashboard + training quizzes + branded posters, enabling growth instead of just managing quotas
• ✅ No e-commerce team? — Multi-SKU products, publish/unpublish, low-stock alerts; order → pay → commission, fully automatic
• ✅ Scared of lock-in? — Node.js with zero third-party dependencies + vanilla frontend + frozen OpenAPI contract: lightweight, auditable, easy to customize

---

✨ Core Features

🛡️ Compliance First	🛒 Closed-loop Mall Commerce	💰 Automated Commissions
15 guardrails (CB-LEGAL-2026-DIST-001) frozen in the kernel, dynamic sensitive-word library, three-tier data permissions, one-click report & ban	Consumer mall → pick SKU → order → simulated payment → commission lands. Orders are born from real transactions; admins read, never hand-enter	Multi-level split rules, order-driven settlement, auto-reconciliation reports. Payment success triggers commission; cancellation restores inventory

📱 Multi-terminal Separation	🎨 One-click Theming	🎓 Distributor Enablement
Three independent terminals: Admin / Distributor / Consumer — brand runs the whole, distributor sees only their own data, consumers transact publicly	Built-in "Durian Trio" theme family, applied consistently across all four surfaces. Source Edition can fully customize colors & branding	Video / image / livestream courses + quizzes in 4 question types; objective questions auto-graded, subjective answers AI-reviewed

Full Feature Map (E1–E8 modules)

Module	Capabilities
E1 Dashboard	Global data overview, real-time KPI insights
E2 Distributor Management	Onboarding / tiering (max 2 levels) / status workflow / freeze & ban
E3 Commission Engine	Multi-level split rules, transaction-driven auto-settlement, monthly reconciliation reports
E4 Assets & Outreach	Poster generator (printable / QR), marketing asset library, share attribution
E5 Analytics	Transaction analysis, commission stats, low-stock alerts, multi-dimensional reports
E6 Compliance Center	Visual config of 15 guardrails, dynamic sensitive-word library, report & ban
E7 Product Management	Multi-SKU (spec / price / stock / alert threshold), publish & unpublish, per-product split rates
E8 Mall & Orders	Consumer mall → order → simulated payment → commission, complete state machine

Technical Highlights

• 🚀 Zero-dependency Node.js — pure built-in ESM modules; clone and run, no npm install, no supply-chain risk
• 🔐 JWT from scratch — HMAC-SHA256, access + refresh dual tokens, zero external libs
• 🧪 504+ automated tests — guardrail penetration, edge cases, end-to-end integration, security injection
• 📦 One-command Docker deploy — nginx + PHP + Node orchestration, works out of the box
• 🌐 Four surfaces, one theme — Admin / Distributor / Consumer / Poster with unified branding

---

📸 Screenshots

Admin Dashboard	Distributor View	Consumer Mall

Product Detail	Poster Page

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     User Layer                           │
│   🖥️ Admin /portal    📱 Distributor /agent    🛒 User /u │
└──────────────────────────┬──────────────────────────────┘
                           │ HTTPS
┌──────────────────────────▼──────────────────────────────┐
│                    Nginx Gateway                         │
│   Reverse proxy · SSL termination · WAF · rate limit     │
│                 · bot blocking                           │
└──────────────────────────┬──────────────────────────────┘
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
┌──────────────────────┐   ┌──────────────────────────────┐
│  PHP Portal Layer     │   │  Node.js Backend (zero-dep)   │
│  Rendering · Session  │──▶│  Business core · in-memory    │
│  Multi-terminal router│   │  storage + persistence        │
│                       │   │  E1–E8 modules · guardrails   │
└──────────────────────┘   └──────────────────────────────┘
                                     │
                              ┌──────▼──────┐
                              │  JSON store │
                              │ (DB-ready)  │
                              └─────────────┘

Design principles:

• Frontend/backend separation — the PHP portal only renders and manages sessions; all business logic lives behind the Node.js API
• Contract-first — openapi.yaml freezes the API contract so frontend and backend evolve without conflicts
• Zero dependencies by default — the core is fully auditable, portable, and deployable offline

---

🚀 Quick Start

Requires Node.js 22+ and Docker (optional)

Option 1: Clone & run (no dependencies to install)

git clone https://github.com/yaoteng/distributor-touch.git
cd distributor-touch/backend

# Start the backend (zero dependency — no npm install)
node src/server.js

Option 2: One-command Docker deploy

cd distributor-touch/services
docker-compose up -d

Once up, visit:

• 🖥️ Admin portal: http://localhost:8080/portal/ (default admin / admin123)
• 📱 Distributor portal: http://localhost:8080/agent/
• 🛒 Consumer mall: http://localhost:8080/u/shop

Run the tests

cd backend
node --test src/tests/*.test.js
# 504+ test cases, all passing

Project layout

distributor-touch/
├── backend/                 # Node.js backend (zero-dependency ESM)
│   └── src/
│       ├── domain/          # Domain layer: guardrails / tiers / split engine
│       ├── handlers/        # API handlers (E1–E8 modules)
│       └── tests/           # 504+ automated tests
├── frontend/                # Frontend modules (7 pages)
├── services/                # Docker deployment (nginx + PHP + Node)
├── openapi.yaml             # Frozen API contract
└── docs/                    # Deployment docs / security hardening reports

---

🧪 Live Demo

Don't want to set up locally? Try the live demo:

👉 show.chaoyi.club

Full-featured demo covering Admin / Distributor / Consumer terminals. Demo account: admin / admin123

---

⬇️ Download

The Basic Edition is fully open source and free forever; Advanced / Lifetime editions are delivered via business channels with licensed packages.

📦 Basic Edition (Free · Perpetual License)

Complete open-source package: backend (zero-dependency Node.js) + portal frontend + Docker deployment + OpenAPI contract + test suite

Item	Detail
Current version	v0.1.0-alpha
Price	Free forever
License	Apache License 2.0
What's inside	All modules (E1–E8) · full source + deployment docs · OpenAPI contract

👉 Download from the official website

👉 Direct download: distributor-touch-basic.tar.gz

💎 Advanced / Lifetime Editions

Deployment packages and the Source Edition are delivered one-on-one by our business team, with a private download link and license credential after purchase.

Edition	Price	Best for
Advanced	¥15k / 1 year · ¥30k / 3 years	Brands that want plug-and-play + commercial license
Lifetime	¥100k one-time	Enterprises that need source-level customization

👉 Contact sales

---

📋 Editions

Capability	Basic (open source)	Advanced	Lifetime
Price	Free	¥15k–30k	¥100k one-time
Delivery	Open-source code	Deployment package	Source Edition
Modules (E1–E8)	✔ All	✔ All	✔ All
OpenAPI contract / dev docs	✔	✘	✔
Theme customization	✔	✘ locked	✔
Secondary development	✔ allowed	✘ not allowed	✔ allowed
License term	Perpetual	1 / 3 years	Perpetual
Support	Community	Commercial	Dedicated + custom

---

🛡️ Compliance by Design

The core differentiator of this system: compliance is not a bolt-on — it is the kernel.

15 compliance guardrails (anchored to CB-LEGAL-2026-DIST-001):

Tier	Guardrails	Notes
P0 (mandatory for launch)	G01 Max 2 levels hardcoded	Distributor tier depth frozen at code level — cannot be bypassed
	G02 Head-count compensation blocked	Split engine only rewards real transactions
	G06 Informed consent	Distributor onboarding consent recorded
	G09 Audit logs	Every critical operation leaves a trace
	G10 Sensitive-word filtering	Dynamic word library, real-time content interception
	G13 Income commitment letters	Revenue promises normalized & compliant
	G14 Data localization	Cross-border data movement constrained
P1	G03 Single-level rebate alert / G04 Tax withholding / G07 Algorithm toggles / G08 Three-tier permissions / G11 Category restrictions / G12 Report & ban / G15 Recruitment copy validation	Configurable alerts and controls
P2	G05 Registration notice at 1.2M scale	Automatic compliance reminder when scale is reached

⚠️ Note: P0 items are code-frozen and cannot be bypassed through runtime configuration — that is the legal bottom line, and the product bottom line.

---

✅ Quality Assurance

• 504+ automated tests, all green (guardrail G01–G15 penetration, edge cases, end-to-end integration, security injection, full order lifecycle)
• Security hardening: 12-layer nginx defense-in-depth (WAF / rate limiting / bot blocking / sensitive-file protection / HTTP method control / security headers)
• Order-chain security: admin-only write operations, role-based mandatory data isolation, consumer-side data masking
• Continuous integration: full regression on every change; releases only ship when everything is green

---

🗺️ Roadmap

• E1–E8 modules complete (2026-08)
• Configurable compliance guardrails (P1/P2 editable, P0 frozen)
• Three-terminal separation + theming system
• Mall transaction loop + automated commission settlement
• 504+ automated tests all green
• Database adapters (MySQL / PostgreSQL persistence)
• WeChat Mini Program (based on UniApp scaffold)
• HarmonyOS app (based on ArkTS scaffold)
• Real payment gateway (WeChat Pay / Alipay)
• Internationalization (7-locale engine already built in)

---

🧰 Tech Stack

Layer	Technology
Backend	Node.js 22+ (ESM, zero third-party dependencies)
Portal	PHP 8.2 + Nginx
Frontend	Vanilla HTML / JS / CSS
Deployment	Docker + Docker Compose
Contract	OpenAPI 3.0 (frozen)
Auth	JWT (HMAC-SHA256, zero-dependency implementation)
Testing	Node.js built-in test runner
Multi-platform	UniApp (Vue 3) / HarmonyOS (ArkTS) scaffolds

---

🤝 Contributing

Contributions of any kind are welcome — issues, PRs, docs, or sharing your usage experience!

1. Fork this repository
2. Create your feature branch: git checkout -b feat/your-feature
3. Commit your changes: git commit -m 'feat: add xxx'
4. Push to the branch: git push origin feat/your-feature
5. Open a Pull Request

Guidelines:

• Follow the existing code style (the zero-dependency principle is non-negotiable)
• New features must ship with automated tests
• Use feat: / fix: / docs: / test: prefixes in commit messages

---

🌟 Community & Support

⭐ Like it? Give us a Star! ⭐

Channel	How to reach
📖 Product website	www.chaoyi.club
🧪 Live demo	show.chaoyi.club
📧 Business email	yaoteng@chaoyiyt.cn
💬 WeChat	pangzi264118 (add with note "buy source code" 😊)
🐛 Bug reports	Issues in this repository

About Tengguan International: focused on digital distribution for the FMCG industry, with compliance as the first principle — building trusted distribution networks for brands, distributors and consumers.

---

📄 License

The Basic Edition of this project is open-sourced under the Apache License 2.0.

Copyright (c) 2026 Tengguan International

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

⚠️ Note: The Advanced / Lifetime editions are commercially licensed products and are NOT covered by the Apache 2.0 open-source license. Contact our sales team for licensing.

---

Distributor Touch · Making FMCG distribution more compliant, more efficient, more trustworthy

Made with ❤️ by Tengguan International · Shenzhen