order-query/docs/superpowers/specs/2026-04-08-order-query-design.md

Order Query Tool — Design Spec

Overview

A Python CLI tool that queries order data from Azure Table Storage and displays it in an interactive TUI. Installable via uv tool install.

Architecture

• Single-module approach: one main.py file with all logic
• Data source: Direct Azure Table Storage connection (azure-data-tables SDK)
• TUI framework: Textual
• Config: ~/.order-query/config.toml with connection_string

Data Model

Mirrors the C# OrderEntity:

• PartitionKey = userId, RowKey = orderId
• Fields: revenue, platformOrder, prodCount, pfId, prodId, prodPrice, state (0=Payed, 1=Recived), OrderTime, ReceiveTime, ver, customData

Project Structure

order-query/
├── pyproject.toml
└── order_query/
    ├── __init__.py
    └── main.py

TUI Flow

1. Start screen: Input field for userId + submit button
2. Order list: Table with columns: orderId, prodId, prodCount, prodPrice, revenue, state, OrderTime
3. Order detail: Press Enter on a row to see full details including customData, platformOrder, ReceiveTime, ver

Dependencies

• azure-data-tables — Azure Table Storage SDK
• textual — TUI framework
• tomli — TOML parsing (Python < 3.11)

Entry Point

order-query command via [project.scripts] in pyproject.toml

Config File

Location: ~/.order-query/config.toml

connection_string = "DefaultEndpointsProtocol=https;AccountName=..."
table_name = "order"

Auto-created on first run with placeholder if missing.