Case Study: Tianwo (Jing Mai) — Air Filtration Installation & Maintenance Management System

Project Code: tianwo
Category: B2B Service Operations Platform / ERP for Field Service
Status: Active Production (Port 8000)
Industry: Environmental Technology / Clean Air Solutions

1. Project Name

Tianwo — A full-stack business operations platform for an air filtration installation and maintenance company in Taiwan, managing the complete customer lifecycle from lead to quotation, sales order, materials procurement, on-site installation scheduling, payment collection, and warranty management.

2. Core Technology Stack

Custom Apps Built:
cores · apps.common · apps.frontend (customer portal) · apps.businesses (multi-company entity) · apps.accounts · apps.customers · apps.product (filtration units, consumables) · apps.materials (BOM & requisition) · apps.quotations (measurement records, competitor pricing, state-tracked quotes) · apps.orders (order items, payment installments, material requirements, warranty) · apps.installations (on-site scheduling, technician dispatch) · apps.scheduling (capacity planning) · apps.notifications (LINE OA events) · apps.projects

Key Models:
Quotation (CodeNoMixin + StateTrackingModel) · MeasurementRecord · MaterialRequirement (CodeNoMixin + StateTrackingModel) · PaymentInstallment · Warranty (StateTrackingModel)

3. The Challenge (The Problem)

Field-service businesses in the environmental technology sector face a uniquely complex operational chain that spans pre-sales, technical delivery, and long-term maintenance:

1. Multi-stage quote-to-cash complexity: An air filtration project involves: initial site measurement → custom quotation → order confirmation → materials bill-of-materials generation → procurement → installation scheduling → milestone payment collection → post-installation warranty. Each stage involves different roles (sales, operations, warehouse, technician) and without a unified system, handoffs between stages create information loss and delay.
2. Measurement-dependent custom pricing: Unlike commodity products, filtration systems must be measured on-site before an accurate quote can be generated. Managing the relationship between MeasurementRecord → Quotation → Order without a structured system leads to version mismatch — installations proceed on the wrong specification.
3. Materials procurement timing: Materials for installation must be procured after order confirmation but delivered before the scheduled installation date — a timing dependency that, if managed manually, frequently results in installations delayed due to missing materials.
4. Multi-payment milestone tracking: Payment is typically split across project milestones (deposit → mid-project → final). Without systematic payment state tracking, follow-up on outstanding balances is ad hoc, and cash flow visibility for the business is low.

4. The Solution (The Implementation)

Feature 1: Measurement → Quotation State Machine

The apps.quotations module links MeasurementRecord (on-site measurement data) directly to Quotation objects via a versioned state machine. Quotes cannot advance to confirmed without a locked MeasurementRecord, preventing the order-proceeds-on-wrong-specification failure mode. CompetitorPrice records attached to each quotation give sales staff real-time competitive context when negotiating.

Feature 2: Automated Material Requirements Generation

When an order is confirmed, the system automatically generates a MaterialRequirement record based on the product BOM (Bill of Materials) defined in apps.materials. This feeds directly into the procurement workflow, eliminating the manual "now figure out what we need to order" step that previously occurred after every sale.

Feature 3: Installment Payment State Tracking

The PaymentInstallment model tracks each payment milestone independently — amount due, due date, payment method, and receipt confirmation. Operations staff have a live view of which projects have outstanding payment, enabling systematic follow-up rather than relying on memory or calendar reminders.

Feature 4: Warranty Lifecycle Management

The Warranty model with StateTrackingModel tracks every installed system through its warranty period. Warranty expiry alerts and service follow-up triggers create an automated upsell pipeline for maintenance contracts — converting one-time installation customers into recurring revenue relationships.

Feature 5: Multi-Company Architecture

The apps.businesses module supports multiple distinct business entities operating within the same system, with appropriate data isolation — a common requirement for owner-operators managing related but legally separate companies in Taiwan's SME landscape.

5. Business Impact (The Result)

• End-to-end flow integrity: The enforced measurement-to-quote-to-order dependency chain prevents the most common failure mode in custom installation businesses — proceeding with work based on an incorrect or superseded specification.
• Materials availability: Automated BOM-to-procurement-requirement generation means materials procurement is initiated immediately after order confirmation, not after the installation is already scheduled to fail.
• Cash flow visibility: Milestone payment tracking gives management a real-time view of receivables at every stage of every project — enabling proactive cash flow management rather than reactive invoice chasing.
• E2E tested: The system has been validated with an end-to-end test suite (17/17 test scenarios passing as of 2026-03-14), demonstrating the reliability of the full quotation-to-warranty lifecycle.
• [Needs Manual Input]: Number of active projects, average project value, specific payment collection improvement metrics, warranty conversion rate to maintenance contracts.

6. AI / Innovation Factor

• LINE OA Integration for Customer Notifications: The apps.notifications module delivers automated LINE messages at key project milestones — quote ready, installation confirmed, payment due, warranty expiring — maintaining customer engagement without manual communication overhead.
• State Machine Design Pattern: The consistent use of StateTrackingModel across Quotation, MaterialRequirement, and Warranty ensures that every entity in the system has a defined, auditable state history. This is the foundation for future AI-driven anomaly detection (e.g., "this quote has been in 'pending' for 14 days — flag for sales follow-up").
• Multi-Entity Architecture: The multi-company apps.businesses design anticipates franchise or multi-branch growth, allowing the platform to scale from a single operator to an enterprise without re-architecture.
• [Needs Manual Input]: Any AI components planned for demand forecasting, installation capacity optimisation, or predictive maintenance scheduling.

Document generated: 2026-05-03 | Maintained by Tom Lai / You Er Ta Mu She Ji