Order Management

Overview

Order management refers to the process of selecting content from the content repository, generating orders, then translating, and finally delivering to customers. An order is associated with the following elements:

• Query builder that can filter content from the content repository
• Associated language assets for quotation (not required)
• Tag rules used to lock source content (not required)
• Service items
• Suppliers
• Quotation
• Quotation negotiation history
• Production process negotiation
• Acceptance negotiation history
• Context strategy

Process

The PM filters content in the Repository using a query builder, clicks to create an order, selects target languages, additional service items, language assets for quotation, and sets lockers in the order preview page, then generates the order. The user enters the order, selects to start quotation, and a popup shows qualified suppliers. After selecting a supplier, the first round of machine quotation begins. Quotation needs to be done asynchronously, and a notification is triggered when the quotation is complete. If the PM has no objection to the machine quotation, they select the approved supplier and enter the localization production phase. If there is no satisfactory machine quotation, they select suppliers that need further communication and enter the negotiation process. Currently, it supports one negotiation with one supplier at a time. If negotiation with multiple suppliers is needed, the current negotiation phase must be exited and another supplier selected (equivalent to process rollback, not implemented in this phase). During negotiation with suppliers, suppliers will generate multiple rounds of quotations based on customer needs until the customer is satisfied with the final quotation. If consensus cannot be reached, the user closes the order. Note that when there is an order in progress, the associated content repository cannot be modified. If negotiation is successful, the production phase begins. In the production phase, the PM's main work is to monitor progress. There will be continuous negotiation during the production process until production is completed and enters the acceptance phase. In the acceptance phase, the PM's main work is to preview the deliverables, which is equivalent to generating a preview version in the Repository. If there is no objection to the preview, acceptance is completed, the preview version becomes the official version, and the order is completed. If there are objections during acceptance, it enters the negotiation process. After the supplier acknowledges, it re-enters the production process. This work is repeated until acceptance is completed, then enters the payment phase. After payment is completed, the order is closed. Additional explanation about context strategy: Users select content for translation, but since the content repository is continuously iterated, if the entire content repository is completely exposed to translators, it may cause confusion for translators or issues such as parameter information leakage. However, if only part of the content is provided, it may not meet translation needs. Therefore, a context strategy needs to be provided to guide translators in translation. Context strategies include:

• Entire repository
• Specify N items before and after the translation
• Selected content only (manual context acquisition not allowed)
• Selected content only (manual context acquisition allowed)

Manual context acquisition means that during the translation process, translators can manually acquire context based on their needs.

Order Status and Actions

Order Status

• Initialization

Order entity has been created, order information can be edited.

• Quotation in Progress

Order information has been confirmed, automatic quotation process is being executed.

• Negotiation in Progress

Quotation information is available, waiting for user to confirm the final quotation.

• Production in Progress

Order has been confirmed, production process is being executed.

• Acceptance in Progress

Production deliverables have been submitted, waiting for user acceptance.

• Payment in Progress

Acceptance has passed, waiting for user payment.

• Completed

Order has been completed.

• Closed

Order can be closed at any time before entering the production phase.

Customer Perspective Actions

• Generate order
• Edit order
• Start quotation
• Confirm quotation
• Initiate negotiation
• Confirm negotiation quotation
• Initiate production
• Confirm acceptance
• Execute payment
• Close order

Supplier Perspective Actions

• Generate negotiation quotation
• Confirm production
• Initiate acceptance
• Initiate payment (upload/generate Invoice)
• Confirm payment (upload/generate Receipt)

Complete Order Lifecycle

Quotation Process

When an order enters the quotation phase, it first determines the unique content data through Repository ID, Repository Version, and filters. It then calls the Allen TM service with the source text from the content data to get the TM match range word count, calls the TMS service to get the supplier's rate configuration and discount configuration, and calculates the total price through range word count × range rate (range rate = range price or base rate × range discount). This generates a detailed quotation. The quotation process is an asynchronous task. When the task is completed, the quotation is written to the database, and the PM is notified that the quotation is complete.

Quotation Process Diagram

Negotiation Process

When the customer sees the quotation, they can select a supplier from multiple quotations to negotiate. After the user clicks the Request New button, the order status changes to "Negotiation in Progress" and a message is pushed to the supplier. The supplier clicks the quotation button on the order and can see the reason for requoting and possibly related attachments. Based on this, the supplier can adjust the TM association of the order, add Tag Rules, and generate a new quotation. After the quotation is generated, the supplier can view the quotation details. If there are still issues, they can continue to adjust and generate. When they think it's correct, they click Push, and the customer will receive the new quotation. If the customer is satisfied with this quotation, they accept it and enter the production phase. If they still have objections, they can continue to click the Request New button, at which point the supplier needs to repeat the previous steps to continue generating quotations. This process can continue until the customer accepts the quotation or closes the order.

Negotiation Process Diagram

API Design

1. Order Creation Related APIs

1.1 Create Order API

• Description: Create a new order based on content repository filter results
• Method: POST
• URL: /api/v1/orders
• Request Example:

{
  "repository_id": "repo_uuid",
  "name": "Project Name-20240301",
  "query_builder_id": "query_uuid",
  "target_languages": ["zh-CN", "ja-JP"],
  "service_items": [
    {
      "type": "translation",
      "unit_type": "word",
      "currency": "EUR"
    },
    {
      "type": "expedited service",
      "currency": "EUR"
    }
  ],
  "guidance": "Need to complete as soon as possible",
  "attachment": [{
    "file_id": "file_uuid",
    "description": "Reference File-01"
  }],
  "language_assets": ["asset_uuid1", "asset_uuid2"],
  "content_locker_ids": ["locker_uuid1", "locker_uuid2"]
}

• Response Example:

{
  "code": 200,
  "message": "Order created successfully",
  "data": {
    "order_id": "order_uuid",
    "status": "draft",
    "created_at": "2024-03-01T00:00:00Z"
  }
}

1.2 Edit Order API

• Description: Edit order information in draft status
• Method: PUT
• URL: /api/v1/orders/{orderId}
• Request Example:

{
  "name": "Project Name-20240301-Modified",
  "target_languages": ["zh-CN", "ja-JP", "ko-KR"],
  "service_items": [
    {
      "type": "translation",
      "unit_type": "word",
      "currency": "EUR"
    },
    {
      "type": "expedited service",
      "currency": "EUR"
    },
    {
      "type": "desktop publishing",
      "currency": "EUR"
    }
  ],
  "guidance": "Need to complete as soon as possible, and pay attention to layout requirements",
  "attachment": [
    {
      "file_id": "file_uuid1",
      "description": "Reference File-01"
    },
    {
      "file_id": "file_uuid2",
      "description": "Layout Standards"
    }
  ],
  "language_assets": ["asset_uuid1", "asset_uuid2", "asset_uuid3"],
  "content_locker_ids": ["locker_uuid1", "locker_uuid2"]
}

• Response Example:

{
  "code": 200,
  "message": "Order updated successfully",
  "data": {
    "order_id": "order_uuid",
    "status": "draft",
    "updated_at": "2024-03-01T00:10:00Z"
  }
}

2. Quotation Related APIs

2.1 Start Automatic Quotation Process

• Method: POST
• URL: /api/v1/orders/{orderId}/quotation/start
• Response Example:

{
  "code": 200,
  "message": "Quotation process started",
  "data": {
    "qualified_vendors": [
      {
        "vendor_id": ["vendor_uuid1", "vendor_uuid2"]
      }
    ]
  }
}

2.2 Query Machine Quotation Result

• Method: GET
• URL: /api/v1/orders/{orderId}/quotation/machine-quote/{taskId}
• Response Example:

{
  "code": 200,
  "message": "Query successful",
  "data": {
    "status": "completed",
    "quote_details": {
      "total_amount": 1000.00,
      "currency": "CNY",
      "word_count": {
        "source": 5000,
        "new": 3000,
        "fuzzy": 1500,
        "exact": 500
      },
      "service_breakdown": [
        {
          "service_type": "translation",
          "unit_price": 0.15,
          "quantity": 5000,
          "amount": 750.00
        },
        {
          "service_type": "review",
          "unit_price": 0.05,
          "quantity": 5000,
          "amount": 250.00
        }
      ]
    }
  }
}

3. Negotiation Related APIs

3.1 Initiate Quotation Negotiation

• Method: POST
• URL: /api/v1/orders/{orderId}/negotiation/start
• Request Example:

{
  "vendor_id": "vendor_uuid",
  "message": "Expected unit price adjustment",
  "expected_price": {
    "translation": 0.12,
    "review": 0.04
  }
}

3.2 Supplier Update Quotation

• Method: POST
• URL: /api/v1/orders/{orderId}/negotiation/update-quote
• Request Example:

{
  "quote_details": {
    "service_breakdown": [
      {
        "service_type": "translation",
        "unit_price": 0.13,
        "quantity": 5000,
        "amount": 650.00
      }
    ]
  },
  "message": "Translation unit price adjusted"
}

4. Production Phase APIs

4.1 Update Production Progress

• Method: POST
• URL: /api/v1/orders/{orderId}/production/progress
• Request Example:

{
  "progress": 45,
  "completed_items": ["content_uuid1", "content_uuid2"],
  "message": "45% of translation work completed"
}

5. Acceptance Phase APIs

5.1 Submit for Acceptance

• Method: POST
• URL: /api/v1/orders/{orderId}/acceptance/submit
• Request Example:

{
  "preview_version": "version_uuid",
  "message": "Translation work completed, please review"
}

5.2 Acceptance Confirmation

• Method: POST
• URL: /api/v1/orders/{orderId}/acceptance/confirm
• Request Example:

{
  "status": "accepted",
  "message": "Acceptance passed"
}

Database Design

1. Order Main Table (orders)

CREATE TABLE orders (
    id VARCHAR(36) PRIMARY KEY,
    number VARCHAR(100) NOT NULL COMMENT 'Order number',
    repository_id VARCHAR(36) NOT NULL COMMENT 'Associated content repository ID',
    repository_version VARCHAR(36) NOT NULL COMMENT 'Associated content repository version number',
    source_language VARCHAR(10) NOT NULL COMMENT 'Source language code',
    query_builder_id VARCHAR(36) NOT NULL COMMENT 'Query builder ID used',
    content_locker_id VARCHAR(255) COMMENT 'Content locker ID',
    status VARCHAR(20) NOT NULL COMMENT 'Order status: draft,quoting,negotiating,producing,reviewing,completed,closed',
    workspace_id VARCHAR(36) COMMENT 'Selected supplier Workspace ID',
    total_amount DECIMAL(10,2) COMMENT 'Final order total amount payable',
    currency VARCHAR(10) DEFAULT 'CNY' COMMENT 'Currency',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    created_by VARCHAR(36) NOT NULL COMMENT 'Creator ID',
    updated_by VARCHAR(36) NOT NULL COMMENT 'Updater ID',
    INDEX idx_status (status),
    INDEX idx_repository (repository_id),
    INDEX idx_vendor (workspace_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Order main table';

2. Order Target Language Table (order_target_languages)

CREATE TABLE order_target_languages (
    id VARCHAR(36) PRIMARY KEY,
    order_id VARCHAR(36) NOT NULL,
    language VARCHAR(10) NOT NULL COMMENT 'Target language code',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_order_lang (order_id, language),
    FOREIGN KEY (order_id) REFERENCES orders(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Order target language table';

3. Order Service Items Table (order_service_items)

CREATE TABLE order_service_items (
    id VARCHAR(36) PRIMARY KEY,
    order_id VARCHAR(36) NOT NULL,
    service_id VARCHAR(20) NOT NULL COMMENT 'Service type ID',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (order_id) REFERENCES orders(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Order service items table';

4. Order Language Assets Association Table (order_language_assets)

CREATE TABLE order_language_assets (
    id VARCHAR(36) PRIMARY KEY,
    order_id VARCHAR(36) NOT NULL,
    asset_id VARCHAR(36) NOT NULL COMMENT 'Language asset ID',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_order_asset (order_id, asset_id),
    FOREIGN KEY (order_id) REFERENCES orders(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Order language assets association table';

5. Order Quotation History Table (order_quotation_history)

CREATE TABLE order_quotation_history (
    id VARCHAR(36) PRIMARY KEY,
    order_id VARCHAR(36) NOT NULL,
    workspace_id VARCHAR(36) NOT NULL COMMENT 'Supplier Workspace ID',
    quote_type VARCHAR(20) NOT NULL COMMENT 'Quotation type: machine,negotiation',
    total_amount DECIMAL(10,2) NOT NULL COMMENT 'Quotation total amount',
    quote_details JSON COMMENT 'Quotation details',
    message TEXT COMMENT 'Quotation description',
    status VARCHAR(20) NOT NULL COMMENT 'Quotation status: pending,accepted,rejected',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    created_by VARCHAR(36) NOT NULL COMMENT 'Quotation initiator ID',
    FOREIGN KEY (order_id) REFERENCES orders(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Order quotation history table';

6. Order Production Progress Table (order_production_progress)

CREATE TABLE order_production_progress (
    id VARCHAR(36) PRIMARY KEY,
    order_id VARCHAR(36) NOT NULL,
    progress INT NOT NULL COMMENT 'Progress percentage',
    completed_items JSON COMMENT 'List of completed content IDs',
    message TEXT COMMENT 'Progress description',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    created_by VARCHAR(36) NOT NULL COMMENT 'Updater ID',
    FOREIGN KEY (order_id) REFERENCES orders(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Order production progress table';

7. Order Acceptance Records Table (order_acceptance_records)

CREATE TABLE order_acceptance_records (
    id VARCHAR(36) PRIMARY KEY,
    order_id VARCHAR(36) NOT NULL,
    preview_version VARCHAR(36) COMMENT 'Preview version ID',
    status VARCHAR(20) NOT NULL COMMENT 'Acceptance status: submitted,accepted,rejected',
    message TEXT COMMENT 'Acceptance description',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    created_by VARCHAR(36) NOT NULL COMMENT 'Operator ID',
    FOREIGN KEY (order_id) REFERENCES orders(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Order acceptance records table';

8. Order Additional Information Table (order_additional_info)

CREATE TABLE order_additional_info (
    id VARCHAR(36) PRIMARY KEY,
    order_id VARCHAR(36) NOT NULL,
    info_key VARCHAR(255) NOT NULL COMMENT 'Information key',
    info_value TEXT COMMENT 'Information value',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    created_by VARCHAR(36) NOT NULL COMMENT 'Creator ID',
    FOREIGN KEY (order_id) REFERENCES orders(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Order additional information table';

9. Exchange Rate Dictionary Table (exchange_rates)

Used to store exchange rate information.

CREATE TABLE exchange_rates (
  exchange_rate_id UUID PRIMARY KEY,
  currency_from VARCHAR(10) NOT NULL,
  currency_to VARCHAR(10) NOT NULL,
  rate DECIMAL(10, 4) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  CONSTRAINT fk_currency_from FOREIGN KEY (currency_from) REFERENCES currencies(code),
  CONSTRAINT fk_currency_to FOREIGN KEY (currency_to) REFERENCES currencies(code)
);