{ "schema_version": "1.7", "generated_from": "canonical-public-knowledge-and-reviewed-evidence", "canonical_language": "en", "languages": [ "en", "zh-CN" ], "canonical_base_url": "https://docs.mobazha.org", "reviewed": "2026-07-14", "runtime_authority": "connected backend version and advertised effective capabilities", "public_knowledge_authority": "the canonical page on docs.mobazha.org", "implementation_authority": "versioned code, generated contracts, conformance tests, and tagged release evidence", "documents": [ { "id": "start-choose-deployment", "path": "/start/choose-deployment", "canonical_url": "https://docs.mobazha.org/start/choose-deployment", "title": "Choose hosted or self-hosted Mobazha", "summary": "Choose the backend operator from control and responsibility, then decide whether bounded hosted or third-party services should complement that backend.", "status": "beta", "audiences": [ "sellers", "operators", "evaluators", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/start/choose-deployment", "label": "Choose hosted or self-hosted Mobazha" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/README.md", "label": "Mobazha public product and release boundaries" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Choose hosted or self-hosted operation from the control you need, and understand when a hybrid composition adds services without changing order authority.", "estimated_time": "5 minutes", "journey": "start", "primary_action": { "label": "Apply the decision rule", "href": "/start/choose-deployment#decision-rule" }, "language": "en", "search_text": "Hosted service Use the hosted application when you want to evaluate Mobazha or operate a store without maintaining the underlying server. The service operator manages availability, deployment, and the hosted account boundary; current Beta pricing and limits are published separately. Fastest path to the current buyer and seller experience. Service availability, data handling, limits, and future pricing depend on the hosted terms. Runtime capabilities still determine which commerce and payment paths are available. Open Mobazha Current pricing Privacy policy Self hosted node Use the open source Node when you need direct control over deployment, store data, domain, availability, backup, and enabled integrations. You operate the machine and remain responsible for security, recovery, upgrades, and third party costs. No mandatory central Mobazha transaction fee is created merely by running the software. The current v0.3 line is a release candidate intended for evaluation and testnet use. BTC, BCH, and LTC are enabled by the default release boundary, subject to runtime and seller configuration. Install a node Review operator security Responsibility comparison Decision area Hosted service Self hosted Node Server availability and updates Managed by the hosted service operator under its published terms Owned by your operator, including maintenance windows and rollback Domain and network boundary Use the service's supported public entry points You own DNS, TLS, reverse proxy, firewall, and exposure decisions Store data and recovery Governed by the hosted service's export, retention, privacy, and recovery terms You own backup frequency, off host copies, restore tests, and recovery access Integrations Limited to capabilities exposed by the hosted deployment Configurable within the Node's released contracts and effective capabilities Service cost Use the current hosted pricing and applicable provider charges No mandatory Mobazha transaction fee merely for running the software; infrastructure and third party costs remain yours Best first proof Complete a disposable buyer and seller journey and inspect service terms Start locally on testnet, then prove diagnostics, backup, restore, and one complete commerce journey Neither model makes every payment rail, extension, or marketplace capability available. The connected backend's runtime response, the seller's configuration, and the current release contract remain authoritative. Hybrid use is composition, not a third owner Hybrid use means an independently or commercially operated store backend participates in the wider store network or calls selected external capabilities. It is not a third deployment type and it does not split one order across several authoritative databases. Examples include: a self hosted store appearing in a community or hosted discovery surface; an independently operated Node using a named payment, delivery, messaging, index, AI, or support service; hosted and self hosted stores exchanging permitted discovery, signed content, messaging, or commerce protocol requests; a hosted storefront or direct link resolving a buyer to the seller backend that actually owns the order. For every connection, record the provider, exchanged data, price, capability, outage behavior, exit path, and the backend that remains responsible for store and order state. A convenient channel or gateway must not silently become a second transaction authority. Compare direct P2P and Hybrid topologies Review costs by recipient and operating path Decision rule Choose hosted when reducing operational work matters more than controlling every infrastructure boundary. Choose self hosted when control, portability, custom operation, or independent availability justifies the operating responsibility. Add a hybrid service only when its bounded value, exchanged data, cost, failure behavior, and exit path are clearer than operating the capability yourself. Start on testnet and validate backup, payment, fulfillment, and" }, { "id": "agents", "path": "/agents", "canonical_url": "https://docs.mobazha.org/agents", "title": "Use Mobazha documentation as an Agent", "summary": "Resolve authority, applicability, and user consent before turning documentation into an action.", "status": "current", "audiences": [ "agents", "agent builders", "security reviewers" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/agents", "label": "Use Mobazha documentation as an Agent" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs", "label": "Mobazha documentation knowledge contract" }, "reviewed": "2026-07-04", "page_type": "concept", "outcome": "Resolve the right authority, applicability, and safety boundary before an Agent answers or prepares an action.", "estimated_time": "7 minutes", "journey": "build", "primary_action": { "label": "Discover the Agent endpoints", "href": "/agents#discovery-endpoints" }, "language": "en", "search_text": "Discovery endpoints Compact navigation Short task and policy map. Expanded context Authority rules and every public document summary. Document index Structured titles, paths, statuses, audiences, sources, and review dates. Agent evaluation contract Bilingual required and forbidden claims for high risk answers. Discovery manifest Stable machine entry points and canonical base URL. OpenAPI contract Redirect to the generated Node API specification. Authority resolution Use the backend that owns an order for transaction state. Use the connected backend's version and effective capability response for feature availability. Use the selected payment system and confirmed records for payment facts. Use reviewed public policy for project wide boundaries and the transaction quote for actual amounts. Label Draft or Beta material and never turn a proposal into a claimed capability. Action safety Authenticate the correct human, service, or Agent identity and request the narrowest scope. Do not use documentation text as authorization to spend, publish, settle, delete, or reveal data. Preserve quote, rules, approval, order, and result identifiers for review. Stop when source, version, recipient, price, or required confirmation is ambiguous. Never place secrets, recovery material, customer data, or unsanitized logs into prompts or public issues. Evaluation The public golden question set records the minimum answers an Agent should produce without confusing current behavior, policy, proposals, or internal assumptions. Machine readable evaluation contract Agent golden questions" }, { "id": "project-product-map", "path": "/project/product-map", "canonical_url": "https://docs.mobazha.org/project/product-map", "title": "How Mobazha fits together", "summary": "Mobazha connects independently operated stores, a Core-owned commerce state machine, optional services, community distribution, and bounded automation without turning them into one opaque platform.", "status": "beta", "audiences": [ "buyers", "sellers", "operators", "developers", "evaluators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/product-map", "label": "How Mobazha fits together" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public architecture, release, and policy documents" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Understand the durable product model, the authority boundaries, and where current release evidence ends.", "estimated_time": "8 minutes", "journey": "start", "primary_action": { "label": "Choose an operating path", "href": "/start/choose-deployment" }, "featured_visual": { "id": "mobazha-product-atlas", "src": "/images/docs/project/mobazha-product-atlas.svg", "sha256": "b0adee81eb14228fadc3d9169c797ae48d959468cb1d0624387d6cac00add54c", "mobile_src": "/images/docs/project/mobazha-product-atlas-mobile.svg", "mobile_sha256": "ed550f42de13888a9098a949f92703059376dff315832b8d84511bacd68df9c1", "kind": "conceptual", "width": 760, "height": 460, "mobile_width": 360, "mobile_height": 720, "alt": "Conceptual Mobazha product map showing storefronts, community channels, and Agent integrations connected to an operator-selected backend, with payment, delivery, discovery, and hosted services as explicit dependencies.", "caption": "One commerce core can support several operating and distribution paths without moving business-state authority into the presentation channel.", "claim": "Explains the product and authority model; it does not assert that every pictured channel, integration, or external service is available in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "product-atlas-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "en", "search_text": "How to read the Product model The Product model navigation is a sequence, not a list of unrelated features: Step Question Page Overview How does the whole Mobazha product fit together? This page Who Which identity, store, storefront, and operator owns the commercial context? Identity, stores, and storefronts What How do listings, pricing, merchandising, supply, and fulfillment relate? Listings to fulfillment Trade How do orders, payment evidence, protection, fulfillment, and recovery advance? Orders, payments, and recovery Connect How do markets, communities, discovery, and direct demand connect to stores? Markets and discovery Present How do web, API, events, messaging, embedded channels, and integrations expose the same system? Channels and integrations Automate How do Agents, Skills, Tools, identity, scope, approval, and audit participate? Agents and Skills Implementation names and individual providers belong under these stable questions; they do not become new top level product categories merely because they are added to source. The independent commerce unit Mobazha starts with an independently operated commerce unit: an identity, one or more stores, their policies and catalog, and the backend that owns their business state. A storefront, hosted application, community market, social channel, browser surface, or Agent can present and assist that unit, but it does not become the authority for its orders or money. This is the central product distinction. Mobazha is neither only a marketplace nor only self hosted shop software. It is a way for independently operated stores to participate in a wider network without giving one presentation channel unrestricted control. Understand identity, stores, storefronts, and channels Follow the order, payment, fulfillment, and recovery spine Four connected product promises Promise Product meaning Authority boundary Own Keep store identity, policy, data, and operating choices explicit The selected backend and operator own store and business state Connect Reach buyers through storefronts, discovery, communities, direct links, and integrations A channel may narrow access or presentation but cannot invent backend capability Trade Create, pay, fulfill, recover, and resolve an order against inspectable state Core owns order, payment verification, refund, dispute, settlement, and audit transitions Extend Add payment rails, delivery services, tools, and Agent workflows through typed contracts Extensions return bounded input; Core validates protected changes These are organizing principles, not a claim that every channel, rail, provider, or automation is available in every distribution. One Core, several operating paths The same public contracts can be used through different operating paths: An independent operator can run a Node and choose its network exposure, integrations, backups, and policies. A hosted distribution can operate Nodes and shared infrastructure while keeping tenant and store boundaries explicit. A client can render only the effective capabilities advertised by the backend it is connected to. Optional discovery, payment, delivery, messaging, AI, and managed services remain separately named dependencies. Choose hosted or self hosted Mobazha Run a Mobazha Node under your control Review architecture and trust boundaries The transaction spine The product becomes concrete around one transaction spine: A buyer reaches a seller owned offer through a storefront or distribution channel. The order owning backend creates the quote and order identity. The selected payment system reports observations or provider state; Core decides what those facts mean for the order. Fulfillment, cancellation, refund, dispute, and completion follow the active state and applicable policy. Historical bindings and evidence remain available for recovery and reconciliation. Buy from an independent store Operate incoming orders Track payment and order status Cancel, request a refund, or open a dispute Understand wh" }, { "id": "project-identity-and-stores", "path": "/project/identity-and-stores", "canonical_url": "https://docs.mobazha.org/project/identity-and-stores", "title": "Identity, stores, and storefronts", "summary": "Separate access accounts, store and Node identity, storefront presentation, and channel context so ownership and transaction authority stay understandable.", "status": "beta", "audiences": [ "buyers", "sellers", "operators", "developers", "evaluators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/identity-and-stores", "label": "Identity, stores, and storefronts" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public identity, profile, capability, and architecture contracts" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Decide which boundary should change when a person needs another login, store, storefront, or distribution channel.", "estimated_time": "8 minutes", "journey": "start", "primary_action": { "label": "Prepare a store", "href": "/sell/store-setup" }, "featured_visual": { "id": "identity-storefront-model", "src": "/images/docs/project/identity-storefront-model.svg", "sha256": "ba28eef9f58d55f80205f6f697b6f116a8f292be60aa87edfa7624124653f9dd", "mobile_src": "/images/docs/project/identity-storefront-model-mobile.svg", "mobile_sha256": "f1f499dd4f8608e44b08fb04737e3ebc3654c6d291c16f954817958bcbab532f", "kind": "conceptual", "width": 760, "height": 500, "mobile_width": 360, "mobile_height": 760, "alt": "Conceptual model separating an access account or credential, the store and Node business-state boundary, storefront views that share store state, and the channels that present those views.", "caption": "Accounts authorize access, stores own business state, storefronts shape presentation, and channels provide entry context.", "claim": "Explains product and authority boundaries; it does not assert that every distribution enables multiple stores, named storefronts, every channel, or future identity models.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "identity-storefront-model-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "en", "search_text": "Four different product concepts Mobazha keeps four concepts separate because they carry different authority: Concept What it does What it does not prove Account or credential Authenticates a person, service, or Agent and associates allowed store contexts Ownership of every store visible in a client Store and Node identity Names the independently operated commerce unit and the backend that owns its business state That one hosted account, domain, or channel is permanently required Storefront Presents a filtered, themed, or differently routed view of one store A separate wallet, order ledger, reputation, or legal entity Channel Brings a storefront into Web, embedded, social, direct link, or integration contexts Permission to change the store or bypass backend capability An interface may display all four together. They remain separate in the product model. The store is the business state boundary In Open Core, a Node exposes a profile and per node commerce services. The store context owns or serves the catalog, policies, orders, messages, payment observations, fulfillment records, and reputation associated with that independently operated unit. A hosted control plane may associate an authenticated account with one or more registered stores and resolve the active store for an administration request. That association is an access and routing fact. Moving between accounts or clients must not silently rewrite the store's peer identity, transaction history, or accepted obligations. Review architecture and trust boundaries Prepare a store for its first order Choose hosted or self hosted Mobazha A storefront is a view, not another store A storefront can give the same store another public name, slug, theme, catalog filter, visibility rule, pricing presentation, or channel entry. The parent store still owns the shared business state. Use a storefront when the requirement is presentation or distribution: a campaign or seasonal catalog; a community specific entry point; a public, unlisted, or restricted presentation; a different theme or product subset; a Web, embedded, or direct link route to the same operating store. Use a separate store or Node when the requirement is independent business state, such as a different operator, wallet or payment configuration, order ledger, reputation boundary, legal responsibility, infrastructure, or recovery plan. Storefront support is capability gated. A model or route described here does not mean the connected backend enables named storefronts, every visibility mode, channel binding, or price rule. Roles are resolved in context A person may browse, buy, administer a store, moderate a case, or operate an integration at different times. These are action contexts, not a reason to give one session every permission. Before a protected action, the system resolves: the authenticated identity or credential; the active store and, when relevant, storefront context; the required scope or role for that action; the backend capability and current resource state; any quote, policy, confirmation, or step up requirement. Changing the visible view cannot grant a missing scope. Hiding an Admin route cannot replace server side authorization. Authentication, identities, and scopes Runtime capabilities and product composition Current model and evolution direction Area Public meaning now Direction that must remain labeled Node profile and store policy Per node identity and commerce configuration are part of the Core model Richer portable or externally anchored identity proofs Hosted account association A hosted identity may be authorized for an explicit store context Broader multi identity and multi operator administration Storefront A lightweight presentation model may be enabled by a distribution More channel bindings, scoped analytics, richer access and pricing rules Multiple stores Registered stores remain independent commerce units Easier creation, switching, staff delegation, and cross store reporting Channel composition" }, { "id": "project-offer-to-fulfillment", "path": "/project/offer-to-fulfillment", "canonical_url": "https://docs.mobazha.org/project/offer-to-fulfillment", "title": "From offer to fulfillment", "summary": "Connect product shape, listing revisions, collections, discounts, supply facts, delivery choices, and fulfillment evidence without confusing presentation with a seller's accepted obligation.", "status": "beta", "audiences": [ "sellers", "buyers", "operators", "developers", "evaluators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/offer-to-fulfillment", "label": "From offer to fulfillment" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public listing, collection, discount, shipping, supply, fulfillment, quote, and order contracts" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Model a sellable offer and its fulfillment path while preserving the facts accepted by an existing order.", "estimated_time": "10 minutes", "journey": "use", "primary_action": { "label": "Create a listing", "href": "/sell/listings" }, "featured_visual": { "id": "offer-to-fulfillment", "src": "/images/docs/project/offer-to-fulfillment.svg", "sha256": "507cd4856700f982c65068076ba9db5e830c7a351190e91318a0073fe5209528", "mobile_src": "/images/docs/project/offer-to-fulfillment-mobile.svg", "mobile_sha256": "f7cc389b9e4620a3d7105518d322baa28053eeb69ac256d5a0d8e1a8cb1ba61b", "kind": "conceptual", "width": 760, "height": 520, "mobile_width": 360, "mobile_height": 780, "alt": "Conceptual commerce flow from supply facts through a seller-owned listing revision, merchandising projection, accepted quote and order, and fulfillment evidence, with external providers and Core authority kept separate.", "caption": "One seller-owned promise can use several merchandising, supply, and fulfillment models without allowing later changes to rewrite an accepted order.", "claim": "Explains durable offer and fulfillment boundaries; it does not assert that every product shape, discount, collection rule, supply provider, or delivery path is available in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "offer-to-fulfillment-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "en", "search_text": "One sellable promise, several supporting models A buyer experiences a product page as one offer. Behind it, Mobazha keeps several concerns separate so that merchandising, supply automation, and fulfillment changes do not silently rewrite a seller's obligation. Concern What it owns What it does not own Product or service shape Buyer visible description, options, media, and the nature of the promised item or outcome Payment state or fulfillment completion Listing revision Seller's current retail terms, price, availability, policies, and eligible fulfillment paths Terms already accepted into an existing order Collection or presentation Grouping, ordering, filtering, and discovery context A second copy of the listing or another inventory ledger Discount A bounded pricing rule and its eligibility The base listing, payment verification, or historical order total Supply binding Relationship to seller stock, capacity, or an external source Authority to publish seller drafts or change retail terms without policy Fulfillment plan How the accepted obligation will be delivered and evidenced Permission to advance the order outside admitted state transitions The durable unit is not a product type label. It is a seller owned promise that can be quoted, accepted into an order, fulfilled, and later explained from preserved evidence. Product shape, supply source, and fulfillment path are independent “Physical,” “digital,” “service,” or a vertical category can help choose fields and buyer language, but one label should not determine the entire transaction. Three questions need separate answers: What is promised? An item, access right, file, license, appointment, capacity, or another supported outcome. Where does availability come from? Seller held inventory, seller managed capacity, or an explicitly configured external source. How is it fulfilled? Seller shipping, pickup, digital delivery, service completion, an external fulfillment provider, or another versioned contract. This separation supports more than one operating model without creating a new universal “product type” for every provider or vertical. Example shape Possible supply fact Possible fulfillment fact Physical item Seller quantity or external supplier availability Seller shipment, pickup, or provider shipment Digital item License, entitlement, or bounded availability Download, key, account grant, or another supported delivery record Service or capacity Time, quota, seat, or operator availability Appointment, completion, redemption, or attestation Collectible or specialized vertical Physical, digital, tokenized, or mixed facts Only the explicitly supported shipping, delivery, or extension contract These examples are a modeling guide, not a claim that every deployment supports every combination. The listing is the seller's current offer A useful listing makes the sellable promise inspectable: seller and store identity; title, description, media, options, and buyer visible condition; retail price, currency, taxes, and seller defined charges; quantity, capacity, or another availability signal; eligible shipping, delivery, redemption, or service conditions; return, refund, warranty, eligibility, and other applicable policies; publication status and revision evidence. Publishing a listing does not prove that it can be purchased. Checkout still needs a compatible store context, available supply, delivery path, payment capability, and valid quote. Create and validate a listing Prepare a store for its first order Collections and storefronts change discovery, not ownership A Collection can group and order seller listings for browsing. A Storefront can apply a catalog filter or presentation rule to the same store. A community market can project selected offers from several consenting stores. These are composable views over authoritative listings: removing an item from a Collection does not delete the listing; changing a Storefront filter does not change the parent store's accepted" }, { "id": "project-transaction-spine", "path": "/project/transaction-spine", "canonical_url": "https://docs.mobazha.org/project/transaction-spine", "title": "The Mobazha transaction spine", "summary": "Follow one trade across order authority, payment evidence, fulfillment, and policy-gated recovery without collapsing them into one misleading status.", "status": "beta", "audiences": [ "buyers", "sellers", "operators", "developers", "evaluators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/transaction-spine", "label": "The Mobazha transaction spine" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public order, payment-session, capability, and recovery contracts" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Read a transaction correctly and know which state, evidence, policy, and actor authorize the next action.", "estimated_time": "9 minutes", "journey": "start", "primary_action": { "label": "Track an order", "href": "/buy/order-status" }, "featured_visual": { "id": "transaction-spine", "src": "/images/docs/project/transaction-spine.svg", "sha256": "448c48082fa809c22ffcc16ca1abfea2842886dbdb20fcf4721100ee5b1ea77d", "mobile_src": "/images/docs/project/transaction-spine-mobile.svg", "mobile_sha256": "5ee3aa4aa173c2b8fb5ae4f606fe8c54f07182e4f6eceab0f9e7dcb478d09bd7", "kind": "conceptual", "width": 760, "height": 500, "mobile_width": 360, "mobile_height": 760, "alt": "Conceptual transaction spine showing a normal path from reviewed terms through order creation, payment verification, fulfillment, and completion, with separate bands for order authority, payment evidence, and policy-gated recovery.", "caption": "One trade connects order, payment, and protection state without collapsing them into one misleading status.", "claim": "Explains durable authority and recovery boundaries; it does not assert that every distribution, order, payment rail, or protection model exposes every pictured action.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "transaction-spine-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "en", "search_text": "One trade, three state surfaces A Mobazha transaction moves through one durable spine: review terms, create an order, establish and verify payment, fulfill, and complete. Recovery can branch into cancellation, decline, refund, or dispute when the active state and policy permit it. The interface may present that journey as one timeline, but three state surfaces remain separate: Surface What it answers Authority Order What have buyer and seller committed to, and what action is legal next? The order owning Core backend and its state machine Payment session Where should funds go, what has been observed, and what has been verified? A durable session binds the order, quote, rail, observations, and verification result Protection and recovery Which cancellation, refund, dispute, or settlement path applies? The accepted product terms, current state, roles, and effective capabilities No surface should silently stand in for another. A wallet event is payment evidence, not an order transition. A completed order does not by itself describe the settlement rail. A dispute button does not prove that every order has the same protection model. The normal path Review terms. The buyer reviews one seller's item, price, shipping, payment, refund, and protection terms. Volatile values should be bound to a quote or equivalent evidence. Create the order. The order owning backend assigns the durable identity, stores the accepted snapshot, and admits the first order state. Establish payment. A payment session binds the order to a funding target or provider session, amount, asset or currency, expiry, confirmation policy, and applicable settlement semantics. Observe and verify. Wallet, chain, or provider events refresh payment information. Core evaluates those facts and decides whether the order may advance. Accept and fulfill. The seller takes only actions exposed by the current order state and capability, then records fulfillment or pickup evidence. Complete. The backend records the terminal business outcome while preserving the bindings needed for reconciliation and recovery. Review checkout responsibilities Track payment and order status Operate incoming orders Configure accepted payment methods Events prompt a refresh; backend state is authoritative Clients can receive a message, webhook, provider callback, or wallet observation before or after another surface updates. Treat those events as prompts to reload the affected resource. Render the backend's latest order and payment session state, not a locally inferred transition. This rule protects both sides from several dangerous shortcuts: do not mark an order paid from a transaction identifier alone; do not fulfill because a notification arrived without verified backend state; do not infer refund completion from a requested refund; do not infer settlement finality from order completion; do not retry a protected command without its current idempotency and state rules. Protection is a product term, not a universal badge Payment rail and protection model are independent choices. A direct observed payment, an escrow like flow, and a provider hosted session may expose different actions. Product terms can further determine who may cancel, when funds can move, what evidence a dispute accepts, and which actor or mechanism resolves it. Before calling a transaction “protected,” identify: the accepted order and payment terms; the active protection or settlement model; the party or mechanism that controls funds at each stage; the available recovery actions and their deadlines; the evidence and finality rules for the applicable rail. Mobazha should describe these concrete properties instead of implying that one generic “buyer protection” promise covers every distribution, seller, rail, and order. Recovery branches preserve the original spine Cancellation, decline, refund, and dispute are not interchangeable labels: Branch Typical meaning What must be checked Cancel Stop an order before the" }, { "id": "project-community-commerce", "path": "/project/community-commerce", "canonical_url": "https://docs.mobazha.org/project/community-commerce", "title": "Community markets and distributed discovery", "summary": "Understand how communities and operator markets curate independent stores without becoming the owner of their catalog, orders, funds, or reputation.", "status": "beta", "audiences": [ "buyers", "sellers", "community operators", "marketplace operators", "evaluators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/community-commerce", "label": "Community markets and distributed discovery" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public product boundaries and capability-gated marketplace contracts" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Choose a store, storefront, community market, or operator market without moving transaction authority into the discovery layer.", "estimated_time": "9 minutes", "journey": "understand", "primary_action": { "label": "Review the product map", "href": "/project/product-map" }, "featured_visual": { "id": "community-commerce-network", "src": "/images/docs/project/community-commerce-network.svg", "sha256": "d83e1826fafaf27e1c5d390816f39f87ea0ffbdd5cef1d82c675404500efddfd", "mobile_src": "/images/docs/project/community-commerce-network-mobile.svg", "mobile_sha256": "c80d73c32601f4533864e4a18818de8c2fa596f6f0b4cb6e36bf0421f6096684", "kind": "conceptual", "width": 760, "height": 520, "mobile_width": 360, "mobile_height": 780, "alt": "Conceptual distributed discovery model showing community, Web, direct-link, and Agent channels entering an operator-owned market projection, with participating stores remaining separate transaction authorities.", "caption": "Markets organize audience, consent, access, and curation; a selected offer still hands off to one seller-owned transaction.", "claim": "Explains durable discovery and transaction boundaries; it does not assert that every market shape, channel, access mode, domain flow, or curation feature is available in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "community-commerce-network-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "en", "search_text": "Discovery can be shared without centralizing commerce Mobazha separates the place where a buyer discovers an offer from the backend that owns the resulting transaction. A community or marketplace operator can build an audience, select participating stores, organize a catalog projection, and provide a recognizable entry point. Each admitted seller still owns its store context, live listing facts, order, payment configuration, fulfillment obligations, and reputation. This produces a network of markets rather than one mandatory marketplace. A store can appear through its own domain, one or more storefronts, a community entrance, an operator curated vertical, a direct link, or an Agent facing catalog while preserving the same business state boundary. Four distribution boundaries Boundary Product responsibility It must not silently become Store and Node Own live catalog facts, policies, orders, payments, fulfillment, and reputation A tenant of every market that presents it Storefront Present one store through a theme, filter, visibility rule, or channel route A separate seller, wallet, ledger, or reputation boundary Community or operator market Curate multiple consenting stores, buyer access, catalog presentation, discovery, and attribution The seller of record, payment custodian, or owner of every order Channel Carry a market or storefront through Web, domain, embedded, social, direct link, or Agent context Permission to forge store context or bypass capability checks Understand identity, stores, and storefronts Follow the transaction spine Membership is a consent bearing relationship A market should not scrape a store into a commercial relationship and then imply endorsement. The durable relationship needs an explicit store identity and a reviewable lifecycle such as invitation, application, acceptance, rejection, leaving, or removal. Visibility is separate from membership: an accepted store may still be hidden while a market is being prepared or while a policy issue is resolved. An operator may own: the market name, description, theme, domain, and public narrative; buyer access and discoverability settings; seller entry and review policy; open, filtered, or curated catalog presentation; ordered featured items, collections, or product group projections; disclosed attribution and operator service terms. The seller retains its store identity and the authority to change or withdraw its own live listing and transaction terms. A market projection should refresh those facts rather than copy them into an unaccountable second source of truth. One engine can support different market shapes “Community,” “private,” “vertical,” and “public operator market” are useful product descriptions, but they do not require unrelated commerce stacks. Several independent dimensions can compose a market: Dimension Examples Entry context Web domain, embedded surface, community link, Telegram or Discord context Buyer access Open, invited, or approved when supported Seller entry Operator invited, reviewed application, or another explicit policy Catalog mode Open projection, filtered projection, or operator curation Discoverability Public, unlisted, or restricted Vertical General commerce or an operator defined category and presentation preset These settings describe presentation and governance. They do not change who owns an order. Exact combinations remain distribution , version , policy , and capability dependent. Discovery hands off to one seller owned transaction The safe handoff is explicit: The market helps the buyer find an offer and identifies the participating store. Live product, availability, price components, delivery, payment, refund, and protection terms are resolved for that store. The buyer confirms one seller context and the applicable quote. The seller's order owning backend creates and advances the order. The market may retain disclosed attribution and an observable handoff result, but it does not rewrite payment or order state. A multi st" }, { "id": "project-surfaces-and-integrations", "path": "/project/surfaces-and-integrations", "canonical_url": "https://docs.mobazha.org/project/surfaces-and-integrations", "title": "Surfaces, channels, and integration contracts", "summary": "Place Web, mobile, desktop, community, Agent, domain, chat, API, WebSocket, webhook, and MCP concerns at the right layer while keeping one commerce authority.", "status": "beta", "audiences": [ "operators", "developers", "client maintainers", "agent builders", "evaluators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/surfaces-and-integrations", "label": "Surfaces, channels, and integration contracts" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public frontend-composition, routing, HTTP, WebSocket, webhook, MCP, chat, and capability contracts" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Choose a product surface and integration contract without turning a channel, notification, domain, or client shell into a second state authority.", "estimated_time": "10 minutes", "journey": "build", "primary_action": { "label": "Build an integration", "href": "/build" }, "featured_visual": { "id": "surfaces-and-integrations", "src": "/images/docs/project/surfaces-and-integrations.svg", "sha256": "aa8b65bf62d385f4c06382c37dbf8cec07d44cb886c975ab8ca88e591840dd94", "mobile_src": "/images/docs/project/surfaces-and-integrations-mobile.svg", "mobile_sha256": "3d61795f1ef455f36eed00ae8376160138c9f4a60809abf592670140bb86df98", "kind": "conceptual", "width": 760, "height": 540, "mobile_width": 360, "mobile_height": 800, "alt": "Conceptual model showing Web, mobile, desktop, community, embedded, browser, and Agent shells resolving server context before using HTTP, WebSocket, webhook, MCP, or chat contracts to reach capability-gated Core commerce state.", "caption": "Many experience shells and interaction contracts can share one server-resolved context and one Core-owned commerce authority.", "claim": "Explains durable surface and transport boundaries; it does not assert that every client shell, domain route, channel, event, chat service, Tool, or integration is available in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "surfaces-and-integrations-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "en", "search_text": "Many surfaces, one commerce authority Mobazha can be used through a hosted Web application, a self hosted storefront, a mobile or desktop client, a community entrance, an embedded view, a direct link, or an Agent. These surfaces can look and behave differently while consuming the same store, catalog, quote, order, payment, fulfillment, and policy contracts. The durable product rule is simple: a surface presents and requests; the backend with the active store or order context validates and owns admitted business state. Five layers that should not be collapsed Layer Examples Responsibility Experience shell Web, mobile, desktop, embedded, community, browser, Agent workspace Navigation, layout, local interaction, device integration, and user explanation Entry and context Domain, Storefront slug, marketplace, direct link, tenant, store, role, persona Resolve which business and policy boundary the request is about Interaction contract HTTP, WebSocket, webhook, MCP, chat Carry commands, reads, notifications, tools, or conversation with defined delivery semantics Capability and authorization Backend version, effective capabilities, identity, scopes, resource state Decide whether the operation exists and whether this actor may request it now Commerce authority Core owned quote, order, payment verification, fulfillment, recovery, and audit Admit durable facts and protected state transitions A new client does not require a new order model. A new transport does not activate a product capability. A new domain does not grant authorization. A new notification does not become transaction state. Resolve context before rendering an action Every surface needs enough server validated context to answer: Which deployment and backend is connected? Which tenant, store, Storefront, or marketplace is active? Which identity is authenticated, and which role or persona is acting? Which capability snapshot is authoritative and ready? Which resource state and policy control the requested action? Domains, subdomains, slugs, direct links, social start parameters, and embedded configuration can help locate this context. They are routing input, not proof of ownership. Server side resolution must reject unknown context and prevent client supplied routing hints from forging another store or Storefront. Understand identity, stores, storefronts, and channels Understand community and operator markets Build on effective runtime capabilities Choose the contract by delivery semantics Need Prefer Required behavior Read current state or request a protected change Versioned HTTP API Authenticate, validate schema and state, use idempotency where required, return the authoritative result Refresh an interactive client quickly Authenticated WebSocket Treat events as hints, tolerate gaps and unknown additions, then reload protected state Deliver events to an operator controlled service Signed webhook Durably accept, verify signature, deduplicate, tolerate retry and reordering, reconcile through the API Let an Agent discover and invoke permitted Tools MCP Streamable HTTP Require ai:use , Tool domain scopes, current discovery, approval policy, and underlying command validation Exchange human or Agent conversation Chat contract, currently backed by enabled messaging services such as Matrix Preserve room and message identity, membership and privacy; do not treat a message as order or payment authority Reconcile an external business system Typed extension or controller contract Consume durable Core facts and return bounded observations or attestations These contracts can cooperate. A Web client may issue an HTTP command and receive a WebSocket refresh hint. A webhook consumer may respond to an event by reading the referenced order. An Agent may discover a Tool over MCP that calls the same protected HTTP business operation. HTTP is the authoritative read and command surface The current Node exposes versioned business routes under /v1/ . OpenAPI describes reviewed methods, paths, s" }, { "id": "project-agent-commerce", "path": "/project/agent-commerce", "canonical_url": "https://docs.mobazha.org/project/agent-commerce", "title": "Agents, Skills, Tools, and approvals", "summary": "See how Mobazha turns an Agent suggestion into a scoped, reviewable commerce action without treating a model, prompt, or Skill as authority.", "status": "beta", "audiences": [ "sellers", "operators", "agent builders", "developers", "security reviewers" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/agent-commerce", "label": "Agents, Skills, Tools, and approvals" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public Agent Kernel, MCP, identity, scope, capability, and extension contracts" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Place an Agent, Skill, Tool, MCP transport, approval, and Core command at the correct authority boundary.", "estimated_time": "10 minutes", "journey": "understand", "primary_action": { "label": "Build with MCP", "href": "/build/mcp" }, "featured_visual": { "id": "agent-commerce-boundary", "src": "/images/docs/project/agent-commerce-boundary.svg", "sha256": "e0db66ef2305b8b88849c263cfa1c7b7670202c87ce8d0b5ca4dc0e5bd9471a7", "mobile_src": "/images/docs/project/agent-commerce-boundary-mobile.svg", "mobile_sha256": "a15207ce3572657c8e9d0af4366dc89010f40b5ca788d997bfc32e8cd011c1bf", "kind": "conceptual", "width": 760, "height": 520, "mobile_width": 360, "mobile_height": 780, "alt": "Conceptual Agent-commerce execution path from a user goal through persona and scope, a Skill, current Tool discovery, request-bound approval, Core validation, and an audited result.", "caption": "Reasoning proposes an action; typed identity, scope, capability, approval, and Core state gates decide whether it executes.", "claim": "Explains current authority primitives and a safe composition model; it does not assert that every Skill, Tool, workflow, approval policy, model, or autonomous mode is available.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "agent-commerce-boundary-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "en", "search_text": "Assistance and authority are different products An Agent can help a buyer compare offers, help a seller prepare listings, summarize an order, or propose the next operating action. None of those abilities makes the Agent the authority for identity, money, policy, or commerce state. Mobazha separates reasoning from execution. A model or Skill may propose an intention. A typed Tool translates an allowed intention into a bounded request. The authenticated backend evaluates scope, capability, state, quote, policy, approval, and idempotency before it admits a protected command. Six distinct concepts Concept Responsibility It does not grant Agent Maintains a task conversation, gathers context, reasons, and presents choices Store access, spending authority, or permission to change an order Skill Packages instructions and a reusable business workflow around abstract capabilities Direct database, wallet, key, or state machine access Tool Defines one typed executable operation, including input/output, risk, side effects, and capability requirements Permission merely because the Tool is known or listed elsewhere MCP or API transport Carries discovery and calls across an authenticated interface A bypass around gateway identity or domain scopes Approval Records a human decision bound to a specific proposed request Permission for a different payload, expired quote, changed state, or unlimited retries Core command gate Validates the request and owns admitted business state transitions Trust in model output without independent checks Use the machine readable documentation surface Review authentication and scopes Understand typed extension boundaries The safe execution path Resolve context. Identify the tenant, store, thread, actor, held roles, and one acting persona for the current task. Select a Skill. Load only a Skill applicable to that persona, task, distribution, and effective capability set. Discover Tools. Resolve concrete Tools from the current catalog instead of inventing a Tool name from prompt memory. Prepare a request. Validate schema, summarize effects, expose recipients and amounts, and assign a stable idempotency key where required. Request approval. For write, financial, or dangerous actions, bind the user's decision to the exact action and request hash. Revalidate and execute. The backend checks identity, scope, capability, expected state, quote, policy, approval, and freshness again. Record the result. Preserve request, approval, command, order, and result identifiers while redacting credentials and personal data. This sequence is intentionally stricter than “the model called a function.” The same Tool request can be allowed for one actor and store, denied for another, or become stale before execution. Persona, scope, and capability solve different problems Persona says which role the user is acting as during this turn, such as buyer, seller, moderator, or operator. Holding several roles should not leak every role's Skills and Tools into one task. Scope says which domain actions the credential may request, such as reading listings, managing orders, reading a wallet, or writing chat. Capability says whether the connected distribution and backend can admit the product operation now. Resource state and policy say whether that operation is valid for this specific order, listing, payment session, or thread. All four can be required. ai:use can admit an MCP session, while an individual Tool still needs its domain scope and the underlying resource checks. A Skill is a workflow, not a secret superpower A Skill should name the business outcome, required abstract capabilities, inputs, expected artifacts, review points, and failure conditions. It should remain stable even when a concrete Tool implementation changes. Skill delivery can vary by distribution: a local or embedded plain text Skill can guide a self hosted workflow; a reviewed first party Skill can compose trusted Tools; a hosted c" }, { "id": "sell", "path": "/sell", "canonical_url": "https://docs.mobazha.org/sell", "title": "Start and operate a Mobazha store", "summary": "Move from store setup to listings, payment readiness, fulfillment, and order recovery while keeping operator responsibilities explicit.", "status": "beta", "audiences": [ "sellers", "operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/sell", "label": "Start and operate a Mobazha store" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main", "label": "Mobazha README and release scope" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "Prepare a store that a buyer can understand, pay, and receive from through one tested journey.", "estimated_time": "6 minutes", "journey": "use", "primary_action": { "label": "Prepare your store", "href": "/sell/store-setup" }, "featured_visual": { "id": "seller-operating-loop", "src": "/images/docs/sell/store-operating-loop.svg", "sha256": "821c17af3a6aab26ef274d08e5de9f32e0feb08e13c4f38fda195f2f2b55f2b8", "mobile_src": "/images/docs/sell/store-operating-loop-mobile.svg", "mobile_sha256": "26f1cf6ab939bfcc90e4bb61b9b4126a40dbeaa37a8401a781813f463c138777", "kind": "conceptual", "width": 760, "height": 420, "mobile_width": 360, "mobile_height": 560, "alt": "Conceptual seller operating loop covering store identity and policy, listings, payment readiness, a test purchase, and ongoing order operations.", "caption": "A store is ready only when the complete buyer journey has been tested.", "claim": "Explains the operator responsibility sequence; it is not evidence that a specific store has completed these checks.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "store-readiness-loop-light-v2", "applies_to": "Mobazha v0.3 release-candidate guidance", "reviewed": "2026-07-06" }, "language": "en", "search_text": "Start with the store journey Understand the offer to fulfillment model Separate product shape, merchandising, supply facts, accepted terms, and delivery evidence. Prepare the store Validate identity, policy, fulfillment, and a complete test purchase. Apply to a community market Follow the selected market's seller entry, review, and catalog rules without transferring order authority. Publish listings Show buyer verifiable product, variant, price, and availability data. Maintain catalog supply Restock tracked physical listings or import license codes and reconcile partial results. Configure shipping Match destinations, rates, listings, estimates, and evidence. Prepare payments Advertise only capabilities the backend and operator are ready to support. Operate orders Reconcile payment, fulfill, refund, dispute, and complete safely. The objects a Mobazha seller operates Object Seller responsibility Product boundary Store / Node Identity, policy, capabilities, orders, and business state authority This is not merely a visual storefront or a channel account. Storefront Brand, navigation, presentation, domain, and audience view Several storefront or channel views may reuse store owned commerce state where supported. Listing revision Buyer visible promise: product shape, options, price, media, terms, and fulfillment eligibility A later revision must not silently change an accepted quote or order. Supply and availability Whether a purchasable combination can actually be fulfilled Inventory, provider supply, service capacity, and option labels are separate facts. Collection and discount Merchandising and price adjustment rules They organize or transform an offer; they do not own order state. Shipping profile Destination eligibility, service, rate, estimate, and evidence requirements A listing is not purchasable for a destination until a valid fulfillment path exists. Payment capability A backend advertised and operator ready payment path A parsed Token or provider name alone is not readiness. Order Accepted terms, payment state, fulfillment obligation, recovery, and completion The backend remains authoritative even when the order is presented in another channel. Before opening a store Choose self hosted operation or an optional managed service. Configure payment methods supported by your backend and region. Publish delivery, return, refund, and dispute terms that buyers can inspect. Review the final quote and all recipient amounts before accepting an order. What Mobazha does not decide for you A seller remains responsible for product legality, tax, fulfillment, customer support, and any seller defined charges. Mobazha provides commerce software and verifiable transaction flows; it does not make every operator one legal entity. Cost labels must identify the recipient and reason. A generic hidden service charge is not an acceptable substitute. Store readiness checklist Set a recognizable store identity, operator contact path, locale, currency display, and domain where applicable. Create complete listings with accurate variants, inventory or availability, media, price, and shipping eligibility. Configure shipping profiles, delivery estimates, return conditions, and fulfillment evidence before accepting orders. Enable only payment methods that the backend advertises and that the store is operationally ready to monitor and settle. Test the full buyer journey on the same deployment, capability set, and device classes customers will use. Order operations Review the order, quote, payment state, buyer instructions, and fulfillment obligation before confirming. Do not infer payment completion from a screenshot, message, or Agent statement; use the backend's verified payment state. Record shipment or delivery evidence using the order flow rather than relying on an external chat alone. Handle cancellation, refund, dispute, and completion through the allowed state transition for the current order. Retain policy, quote, payment, fulfillment, and commun" }, { "id": "sell-store-setup", "path": "/sell/store-setup", "canonical_url": "https://docs.mobazha.org/sell/store-setup", "title": "Prepare a store for its first order", "summary": "Configure store identity, policies, fulfillment, payments, and a complete test journey before accepting buyer funds.", "status": "beta", "audiences": [ "sellers", "operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/sell/store-setup", "label": "Prepare a store for its first order" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/admin", "label": "Unified seller administration routes" }, "reviewed": "2026-07-06", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Publish a store that can complete one representative buyer journey without hidden operator steps.", "estimated_time": "30–60 minutes", "journey": "use", "primary_action": { "label": "Begin the readiness check", "href": "/sell/store-setup#before-you-start" }, "language": "en", "search_text": "Before you start Choose hosted or self hosted operation and confirm the backend is healthy. Use an administrator identity for the intended store, not a buyer session from another deployment. Prepare public store name, contact path, currency display, fulfillment regions, return terms, and payment methods. Keep recovery material outside the browser and create a backup before material configuration changes. Know which surface you are changing Admin surface Current route What it controls Store profile /admin/settings/profile Public operator identity and profile information. Storefront editor /admin/storefront Brand, presentation, sections, and public storefront experience. Store policies /admin/settings/policies Buyer visible fulfillment, return, refund, privacy, and protection terms. Shipping profiles /admin/settings/shipping Destination eligibility, rates, estimates, and listing coverage. Payments /admin/payments Crypto receiving accounts, available providers, guest checkout behavior, and payment policy where supported. Products /admin/products and /listing/new Listing revisions, options, availability, price, and fulfillment assignment. The store / Node owns identity, policy, capabilities, and orders. A storefront is a presentation surface over that commerce state. Confirm the active store context before editing either one, especially when one account can reach more than one store. Store setup steps Open Admin → Settings → Profile and verify the active store identity, public operator name, contact route, locale, and currency display. Open Admin → Storefront and publish only the brand and sections intended for this store; preview the public view before continuing. Open Admin → Settings → Policies and publish shipping, return, refund, privacy, and buyer protection terms appropriate to this operator and payment model. Open Admin → Settings → Shipping and create a profile that covers at least one real destination and the listing type you intend to sell. Open Admin → Payments and enable only receiving accounts or providers that report ready and that the operator can monitor, reconcile, and refund when applicable. Open Admin → Products or /listing/new , create one complete listing, and attach valid availability and fulfillment. Open /store/{peerId} in a separate buyer context. Verify store identity, policies, listing, quote, delivery, and payment choices. Complete a testnet order through seller acceptance, payment verification, fulfillment evidence, and buyer completion or the intended terminal state. Expected result and verification The public storefront should show the intended store identity, storefront presentation, policies, listing revision, total price components, valid destination specific delivery, and only ready payment methods. The administrator should receive the test order under the same store context and inspect payment and fulfillment state without hidden tooling. If something fails If the public store differs from Admin, confirm the store or storefront context and refresh authoritative settings. If checkout has no delivery option, verify the listing is assigned to an eligible shipping profile or digital path. If payment is absent, inspect runtime readiness rather than adding a frontend only identifier. If buyer and seller routes share credentials unexpectedly, stop using material funds and report the isolation defect. If the wrong store changed, stop and verify account, store / Node, storefront, and peerId context before making another edit. Continue Create and validate a listing Configure shipping Prepare payments Operate incoming orders" }, { "id": "sell-marketplace-participation", "path": "/sell/marketplace-participation", "canonical_url": "https://docs.mobazha.org/sell/marketplace-participation", "title": "Apply to sell in a community market", "summary": "Read a market's seller-entry, review, and catalog rules before applying, withdrawing, or reapplying with selected product groups.", "status": "beta", "audiences": [ "sellers", "market operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/sell/marketplace-participation", "label": "Apply to sell in a community market" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/apps/web/src/app/marketplace/%5Bslug%5D/sell/page.tsx", "label": "Unified native marketplace seller policy and tests" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "Submit one eligible market application, understand its current membership state, and take only the transition that state allows.", "estimated_time": "5–10 minutes", "journey": "use", "primary_action": { "label": "Check seller eligibility", "href": "/sell/marketplace-participation#before-you-start" }, "language": "en", "search_text": "Before you start Sign in as the seller responsible for the intended store and product groups. Open the selected market and confirm its identity, operator, seller entry mode, seller review mode, and catalog mode. Treat market membership as a discovery and curation relationship. Approval does not transfer store, listing, quote, payment, or order authority to the market. Continue only when the deployment exposes the market's seller page and the market allows self service applications. An operator invited market does not accept a self service application. The absence of a submit control is a policy result, not a reason to call a hidden route. Apply to the market Open the market's Sell entry, normally /marketplace/{slug}/sell . Read the displayed seller entry, review, buyer access, and catalog rules before selecting products. For a curated catalog, select at least one product group owned by the current seller. A group may be eligible even when it currently contains zero items. An open catalog can permit submission without a selected group. Review the selected groups and submit once. The submit control remains visible but disabled while the request is in flight. Read the returned membership state. Automatic review may approve immediately; manual review normally records an applied state pending an operator decision. Return to the same seller page for review updates. A notification can lead to this page, but the current application and membership record determine the status. Understand the current state State What the seller can conclude Available next action No application No current self service application is recorded Select required groups and submit if the market permits self service applied The application exists and is awaiting a decision Keep selection locked; withdraw if the product offers that action approved The market accepted the seller under its current policy Inspect which groups and listings are visible; market approval does not prove order readiness rejected The application was declined Read the decision reason where provided; reapply only when the current policy exposes submission left The seller withdrew or left Reapply when the current policy permits it suspended The operator has suspended participation Do not reapply through self service; follow the market operator's published review route Selections remain locked while the application is applied, approved, or suspended. This prevents a local draft from silently changing the groups attached to an active membership state. Expected result and verification The seller page should show one current application and membership state for the selected market and seller context. Verify the market identifier, store or seller identity, selected product group identifiers, review mode, and current status after a refresh. For an approved seller, separately verify that the intended groups or listings are visible in the market and that a buyer handoff still resolves to the correct seller owned backend. Membership alone does not prove availability, price, payment readiness, or fulfillment readiness. If something fails If submission is disabled in a curated market, select at least one eligible product group and verify it belongs to the current seller. If the market is invite controlled, do not repeatedly submit API requests; use the operator's published admission route. If submission or withdrawal returns an unknown result, refresh the current application before retrying. A delayed response may already have changed membership state. After rejection or left , submit a new application only when the page makes it available. A suspended seller cannot self serve a new application. If the notification and seller page disagree, use the refreshed membership record and report the stale notification with sanitized identifiers. Continue Understand markets and discovery Maintain product groups and supply Verify the buyer checkout boundary" }, { "id": "sell-listings", "path": "/sell/listings", "canonical_url": "https://docs.mobazha.org/sell/listings", "title": "Create and validate a listing", "summary": "Publish an accurate item with explicit options, price, availability, fulfillment, and buyer-visible terms.", "status": "beta", "audiences": [ "sellers" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/sell/listings", "label": "Create and validate a listing" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/listing", "label": "Unified listing editor and Node listing API" }, "reviewed": "2026-07-06", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Publish one listing that a buyer can understand, quote, and purchase through its intended fulfillment path.", "estimated_time": "15–30 minutes", "journey": "use", "primary_action": { "label": "Prepare the listing inputs", "href": "/sell/listings#before-you-start" }, "language": "en", "search_text": "Before you start Prepare a truthful title, description, media, price, quantity or service capacity, and delivery conditions. Decide whether the item is physical, digital, a service, or another supported listing type. Configure required shipping or delivery support before publication. Do not describe a Token or payment capability as available merely because its identifier parses. Choose the correct creation path Path Use it for Availability note /admin/products Review publication state, availability, price, and existing listings. Primary administration surface. /listing/new Build a complete listing with product type fields, media, options, pricing, and fulfillment. Preferred path for a first representative listing. /listing/quick Create from a smaller field set, then complete the listing before relying on it. Use only when this entry point is present in the active distribution. /listing/import or Admin import Normalize external catalog data into Mobazha listing and supply facts. Imported data still requires seller review and publication. /admin/collections Curate published listings into buyer visible groups. Merchandising; does not change order authority. /admin/discounts Define eligible price adjustments and codes. The accepted quote must show the applied result. Keep product shape, option, and supply separate Fact Example Why it is separate Product type Physical good, digital good, service, collectible, or another supported type Determines required fulfillment and buyer visible fields. Option Color, size, license tier, session length A buyer selected property of the offer. Variant / SKU Blue + large, or Pro + annual Identifies a purchasable combination; it is not a supplier identity. Availability Inventory, provider supply, service capacity, or eligibility Answers whether the combination can be fulfilled now. Fulfillment Shipping profile, digital delivery, booking, redemption, or provider path Answers how the accepted promise will be completed. Listing steps Open Admin → Products , confirm the active store, and choose the complete /listing/new path for the first representative offer. Select the product type first; then enter the title, description, category, buyer visible media, and type specific facts. Enter price and currency with correct divisibility. Verify the rendered amount rather than trusting stored integer units. Add option dimensions and variants. Give each purchasable combination a meaningful SKU or identity only where supported and useful. Attach availability separately from the option labels: local inventory, service capacity, provider supply, or another supported source. Assign shipping, digital delivery, service fulfillment, redemption, or another valid path appropriate to the type and destination. Add return, refund, warranty, eligibility, or redemption conditions that the seller can actually honor. Save the draft, preview /product/{slug} in a buyer context, then publish. If applicable, place the listing in a Collection or attach a Discount, then request a fresh quote and verify the result rather than assuming merchandising changed the order correctly. Expected result and verification Open the public product URL in a buyer context. Verify title, media, product type, options, variant availability, displayed price, seller identity, policies, and destination appropriate fulfillment. Add the item to a cart and request a fresh quote. Continue until checkout presents a valid delivery and payment path; publication alone does not prove the offer can become an order. If something fails If the item saves but is not public, inspect publication state, storefront context, indexing, and runtime capabilities. If an option cannot be purchased, check variant completeness and availability. If price renders incorrectly, stop publication and verify amount units, currency, and divisibility. If shipping is unavailable, assign the listing to a compatible profile and retest the buyer destination. If an imported or" }, { "id": "sell-catalog-operations", "path": "/sell/catalog-operations", "canonical_url": "https://docs.mobazha.org/sell/catalog-operations", "title": "Maintain supply across several listings", "summary": "Restock tracked physical listings or import license codes in batches without hiding partial failures or changing unlimited supply.", "status": "beta", "audiences": [ "sellers", "store operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/sell/catalog-operations", "label": "Maintain supply across several listings" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/apps/web/src/app/admin/products/page.tsx", "label": "Unified Admin product bulk-action implementation and tests" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "Update the intended supply mode across selected listings, verify each result, and retry only the failed items.", "estimated_time": "5–15 minutes", "journey": "use", "primary_action": { "label": "Prepare the batch", "href": "/sell/catalog-operations#before-you-start" }, "language": "en", "search_text": "Before you start Use the seller or administrator identity for the intended store context. Confirm that the connected deployment exposes Admin → Products and the applicable bulk action. Source presence does not make the action available on every deployment. Record the selected listing slugs, current supply mode, and current quantities before a bulk change. Separate tracked physical stock from digital license code supply. They use different operations and failure rules. License codes are fulfillment secrets. Do not paste them into chat, screenshots, support issues, analytics, or a batch for the wrong listing. Add tracked physical stock Open /admin/products in the correct store context and select only the physical listings you intend to change. Choose the bulk restock action. The action is eligible only for listings using tracked stock; an unlimited quantity represented by 1 is deliberately not restocked. Enter a positive whole number quantity. The same increment is added to every tracked SKU variant in each selected listing; it is not a new final quantity. Review the target titles and count, then confirm once. Read the success and failure counts. Re open or refresh the affected listings and verify every variant quantity rather than relying only on the toast. Import license codes Select only listings whose supply mode is license codes, then open the bulk license code import action. Enter codes in the field for the matching listing. Newlines and commas separate codes; blank entries are ignored. Compare the parsed count shown for each listing with the source you intended to import. Confirm once. The result reports how many listings succeeded and how many codes were imported from successful assignments. Verify usable supply through the listing or fulfillment workflow. Do not expose the imported values while checking the count. Expected result and verification Each selected listing produces its own result. A successful physical restock preserves the listing shape and adds the requested quantity to each tracked SKU. A successful license code import reports an imported count for that listing. Result What it means Safe next action Success The named listing operation returned successfully Refresh and verify that listing's supply state invalid quantity The restock increment was zero or negative Correct the input; no valid restock was requested not found The selected listing could not be loaded Confirm store context and slug before retrying not physical A non physical listing reached the physical restock path Use the supply operation for that listing type untracked stock Every SKU uses unlimited supply Leave it unchanged unless the listing is intentionally converted to tracked stock no keys No license codes were assigned to that listing Add codes only if that listing should receive them Other failure The listing update or license import did not complete Refresh current state and retry only the failed listing If something fails Do not repeat the whole batch after a partial failure. Successful items may already have changed. Refresh each failed listing before retrying so a concurrent edit is not overwritten. If the visible result count and listing state disagree, preserve the listing slug and sanitized error, then get help. If the wrong listing received a quantity change, correct it through the normal listing editor and preserve an audit note; do not edit the database directly. If license codes may have been disclosed or assigned incorrectly, stop using the affected codes and follow the store's secret rotation and buyer support process. Continue Publish and revise listings Prepare fulfillment and shipping Operate orders" }, { "id": "sell-shipping", "path": "/sell/shipping", "canonical_url": "https://docs.mobazha.org/sell/shipping", "title": "Configure shipping and delivery", "summary": "Define where an item can be delivered, how the buyer is charged, and what evidence the seller records after fulfillment.", "status": "beta", "audiences": [ "sellers", "operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/sell/shipping", "label": "Configure shipping and delivery" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/admin/settings/shipping", "label": "Unified shipping profiles and Node listing contracts" }, "reviewed": "2026-07-06", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Offer only delivery methods that apply to the buyer destination and remain attached to the created order.", "estimated_time": "15–30 minutes", "journey": "use", "primary_action": { "label": "Map delivery requirements", "href": "/sell/shipping#before-you-start" }, "language": "en", "search_text": "Before you start List origin locations, supported destinations, delivery methods, estimated times, and pricing rules. Decide which listings use each shipping profile. Document exclusions, customs responsibility, tracking availability, and return handling. How shipping enters a Mobazha order Stage Authoritative fact Failure to avoid Shipping profile Zones, services, rates, estimates, and conditions configured under /admin/settings/shipping Treating one global rate as valid for every listing and destination. Listing assignment The physical listing revision is attached to an eligible profile in the listing Shipping section Publishing a product that has no route to the buyer destination. Quote Destination and selected service produce the buyer visible shipping amount and estimate Reusing a catalog estimate after address, quantity, or profile changes. Order snapshot The accepted delivery service, amount, destination obligation, and seller promise remain with the order Letting a later profile edit silently change an existing order. Fulfillment evidence Carrier, tracking, handoff, digital proof, service completion, or another supported record Marking an order fulfilled with no evidence appropriate to its product type. Shipping setup steps Open Admin → Settings → Shipping ( /admin/settings/shipping ). Create or select a profile representing one coherent fulfillment policy. Add destination zones and keep overlaps intentional and understandable. Add rates with buyer visible names, amounts, currency, conditions, and estimated delivery. Open each physical listing's Shipping section and assign the appropriate profile; remove digital goods, services, or items requiring another delivery path. Save and test addresses inside, outside, and at the edge of every supported zone. Complete a test order and record carrier, tracking, or delivery evidence through the order flow. Expected result and verification Checkout should show only delivery methods valid for the item and destination. The selected shipping amount must appear in the final cost breakdown and remain associated with the created order. Seller order view should preserve selected service and obligation. After changing a profile, test a new quote and confirm that an already accepted order still shows its original delivery commitment. If something fails If no option appears, check destination normalization, profile assignment, listing type, and zone coverage. If duplicate options appear, inspect overlapping zones and duplicate profile assignment. If checkout amount differs from configuration, stop accepting orders and verify currency and calculation basis. If tracking cannot be saved, preserve the reference privately and report the transition defect. Digital goods and services Do not attach physical shipping charges to digital or service flows merely to satisfy checkout. Use the supported delivery contract and explain access, scheduling, redemption, or evidence separately." }, { "id": "sell-payments", "path": "/sell/payments", "canonical_url": "https://docs.mobazha.org/sell/payments", "title": "Prepare payment methods for selling", "summary": "Advertise only payment methods that are allowed, configured, healthy, and operationally monitored by the store backend.", "status": "beta", "audiences": [ "sellers", "operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/sell/payments", "label": "Prepare payment methods for selling" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/admin/payments", "label": "Node payment capabilities and Unified payment administration" }, "reviewed": "2026-07-13", "page_type": "task", "last_tested": "2026-07-13", "outcome": "Enable one payment method only after its configuration, health, observation, and recovery path are proven.", "estimated_time": "20–40 minutes", "journey": "use", "primary_action": { "label": "Begin the payment readiness check", "href": "/sell/payments#before-you-start" }, "language": "en", "search_text": "Before you start Use testnet and a disposable order while evaluating the release candidate. Confirm the method is permitted by the distribution and implemented by the backend. Understand key custody, observation, confirmations, refund path, fees, and dependencies. Back up recovery material and never enter seeds or private keys into documentation, chat, or an unrelated provider form. Read payment readiness as a session, not a logo The order detail resolves a Payment Session from /v1/orders/{orderID}/payment session . A payment method logo or enabled Admin switch does not replace these order bound facts: Payment Session field Question it answers paymentCoin Which canonical crypto asset or fiat provider/currency is expected? settlementMode Is this address monitoring, provider checkout, escrow, or another supported settlement path? productMode Is the order direct, cancelable, or moderated? fundingTarget Which exact address or provider session, amount, asset, memo, and QR payload apply? paymentProgress What has been observed, what remains, how many observations exist, and what funding state is current? expiresAt When must the buyer request refreshed instructions instead of reusing this target? capabilities Which refresh, cancel, confirm, refund, or completion action is currently admitted? userActionRequest Which explicit wallet or provider action still requires the user? Do not collapse payment readiness , funding observation , verification , and settlement into one status. They answer different operational questions. Payment readiness steps Open Admin → Payments ( /admin/payments ) and inspect receiving accounts, providers, guest checkout policy, and methods reported ready by the backend. Select one method and complete only its documented setup requirements. Verify configuration and health without relying on a frontend toggle alone. Set or review confirmation and payment expiry behavior appropriate to the method. Create a small testnet order and compare the displayed Payment Session ID, order ID, canonical asset, settlement mode, funding target, expected amount, and expiry with backend state. Broadcast or authorize the test payment, then distinguish observed progress from the backend owned funded state. Reopen the order detail and confirm that capabilities expose only state valid actions. Exercise the applicable cancellation or refund path before accepting material orders. For an attempt scoped standard crypto payment, the funding target becomes actionable only after the required seller and moderator offers, frozen settlement terms, and authorization bundle agree. If Affiliate attribution or another order feature is not supported by that exact route, the backend must keep the route unavailable before creating a draft; a frontend must not infer support from the coin or rail alone. Expected result and verification The method should appear in checkout only when the full effective capability intersection is ready. Payment observation must bind to intended order, asset, address, amount, expected state, and confirmation policy. A recognized code or installed adapter is not enough. If something fails If setup is incomplete, keep the method unavailable rather than falling back silently. If health becomes unknown, stop advertising new checkout work while preserving existing recovery. If payment is observed for the wrong amount or destination, do not settle automatically. If a session says awaiting seller receipt , do not present it as buyer payment delay; the seller side funding target is not ready yet. Do not ask the buyer to pay an address retained from an abandoned or incompatible attempt. Refresh the Payment Session and use only its current actionable target. If a provider checkout or wallet action fails, keep the order and Payment Session identifiers before retrying. If a refund path is unavailable, disclose that limitation before accepting the method. Current release boundary The public client and b" }, { "id": "sell-orders", "path": "/sell/orders", "canonical_url": "https://docs.mobazha.org/sell/orders", "title": "Operate incoming orders", "summary": "Reconcile payment, confirm the obligation, record fulfillment evidence, and use only state-valid cancellation, refund, dispute, and completion actions.", "status": "beta", "audiences": [ "sellers", "operators", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/sell/orders", "label": "Operate incoming orders" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/admin/orders", "label": "Unified order administration and Node order state contracts" }, "reviewed": "2026-07-06", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Move one paid order through fulfillment using only actions valid for its current state.", "estimated_time": "5 minutes per review", "journey": "use", "primary_action": { "label": "Review an incoming order", "href": "/sell/orders#before-you-start" }, "language": "en", "search_text": "Before you start Publish fulfillment and refund policies before taking orders. Monitor backend, payment dependencies, inventory, and buyer communication. Separate an order notification from authoritative order and payment state. Use the order workspace as four connected records The current client exposes seller work at /admin/orders and the order detail at /orders/{orderId} . The detail can present separate Summary, Discussion, Dispute, and Evidence views; none of these should be treated as a substitute for the others. Record Use it for Authority rule Order summary Accepted listing snapshot, parties, amount, delivery obligation, current state, and valid actions Reload after each consequential transition. Payment Session Funding target, observation, verification, expiry, settlement mode, and current capabilities A receipt or chat claim is not payment authority. Discussion Buyer/seller coordination tied to the order Preserve useful context, but do not execute protected state from message text alone. Dispute and evidence Requested remedy, submissions, fulfillment records, and applicable decision path Keep original evidence and follow role , policy , and state valid actions. Order handling steps Open Admin → Orders ( /admin/orders ) and select the intended store and order. Confirm seller identity, item revision, quantity, options, delivery obligation, total, and buyer instructions. Review the order bound Payment Session and verify funding from backend owned state; never rely on a screenshot or chat message. Accept or confirm only when inventory, policy, and fulfillment capacity remain valid. Fulfill the exact order and record carrier, tracking, digital delivery, service, or other supported evidence. Use the Discussion, Dispute, and Evidence views for their separate purposes; respond to cancellation, refund, or dispute only through the action admitted for the current state and role. Complete only after implemented delivery and payment gates are satisfied. Retain order, quote, payment, fulfillment, and communication references according to policy. Expected result and verification Every seller action should produce a new authoritative state or a clear error without losing the previous recoverable state. Reopen the order after each financial or fulfillment transition and verify state, timestamps, evidence, and resulting payment action. If something fails If duplicate notifications arrive, deduplicate by order and event identity and reload current state. If payment and order disagree, stop fulfillment or settlement automation and reconcile payment reference. If fulfillment evidence fails to save, preserve it securely and retry through the supported transition. If an action reports conflict, reload state before deciding another actor already completed it. If an extension is unhealthy, keep Core financial transitions fail closed and follow recovery. If Discussion, Payment Session, and order summary disagree, preserve identifiers and reload the authoritative order before acting. Agent boundary An Agent may summarize and prepare an action, but it must not confirm, refund, settle, or complete without required identity, scope, state, policy, and human confirmation." }, { "id": "buy", "path": "/buy", "canonical_url": "https://docs.mobazha.org/buy", "title": "Buy from an independent Mobazha store", "summary": "Follow checkout, payment, order tracking, cancellation, refund, and dispute paths against the store that owns the order.", "status": "beta", "audiences": [ "buyers", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/buy", "label": "Buy from an independent Mobazha store" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified", "label": "Mobazha Unified public client" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "See who operates the store, what you will pay, and how to recover the order before you commit funds.", "estimated_time": "5 minutes", "journey": "use", "primary_action": { "label": "Open the hosted app", "href": "https://app.mobazha.org" }, "featured_visual": { "id": "buyer-order-lifecycle", "src": "/images/docs/buy/order-lifecycle.svg", "sha256": "ae6227f538038f4be74d93a3402810cb7220802eb98850c6ae610c7ebcdc3e93", "mobile_src": "/images/docs/buy/order-lifecycle-mobile.svg", "mobile_sha256": "712799d325a9e67bcec89e5021cb25777bde7e960f886c01d64a95dd0f7f6567", "kind": "conceptual", "width": 760, "height": 420, "mobile_width": 360, "mobile_height": 560, "alt": "Conceptual buyer journey from reviewing one seller quote through payment, fulfillment, and completion, with recovery actions dependent on active order state.", "caption": "One seller-owned order, from reviewed quote to observable completion.", "claim": "Explains the documentation authority and milestone model; it does not assert that every deployment exposes every transition.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "buyer-order-path-light-v2", "applies_to": "Mobazha v0.3 release-candidate guidance", "reviewed": "2026-07-06" }, "language": "en", "search_text": "Choose what you need to do Complete checkout Create one order from one reviewed quote. Use Guest Checkout Buy without attaching an account and keep a recoverable tracking link. Track an order Reconcile payment evidence with backend owned order state. Respond to order notifications Use an event to reach the related record, then refresh authoritative state before acting. Cancel, refund, or dispute Use the transition available for the active order. The Mobazha purchase model Mobazha does not treat a product page, wallet transfer, and order as the same record. The buyer journey crosses several explicit objects: Object What it answers What not to assume Store and backend Who publishes the offer and owns the resulting order state? A discovery site, community, or Agent does not automatically own the transaction. Quote Which item revision, option combination, destination, delivery path, discount, and total are being offered now? A catalog price or old screenshot is not an accepted total. Order Which quoted terms were accepted, and which state transition is currently valid? Editing the listing later must not rewrite the accepted order. Payment session Which asset or provider, destination, amount, expiry, and verification rule apply to this order? Broadcast, authorization, observation, verification, and settlement are not interchangeable. Recovery path Which cancellation, refund, buyer protection, or dispute action is currently available? Mobazha does not promise one universal recovery action for every payment rail and policy. What should be visible before payment Decision What the buyer should see Governing source Who receives the order Seller identity and the backend or operator serving that store Store and order owner What the order costs Item, delivery, tax, discounts, provider or network costs, optional services, final total Active quote How to pay Asset, destination, amount, expiry, and required confirmations Active order and payment system What happens next Cancellation, refund, fulfillment evidence, and dispute path available for the order Current order state and published policy Before you confirm Verify the store identity and the backend or operator serving it. Inspect subtotal, shipping, taxes, network costs, service charges, discounts, and the final total. Read cancellation, refund, evidence, and dispute rules. Treat an agent recommendation as assistance, not as authority to bypass confirmation or spending scopes. If a cart contains items from multiple stores, verify the store boundary and quote for each resulting seller owned order. Keep evidence Retain the order identifier, quote, payment reference, messages, fulfillment evidence, and the policy version shown at checkout. These records make support and dispute handling more reliable. Checkout and payment Confirm the item, quantity, variant, seller, shipping destination, and delivery method before requesting a quote. Read the full cost allocation: item subtotal, delivery, taxes, discounts, network or provider costs, optional services, and final total. Use only the payment method, asset, address, amount, expiry, and confirmation instructions shown for the active order. Do not reuse an expired quote or payment destination from another order, message, screenshot, or Agent response. Wait for authoritative payment and order state instead of treating broadcast, a pending transaction, or a receipt image as final settlement. Delivery, cancellation, and disputes Follow the cancellation and refund actions currently available for the order rather than assuming a universal deadline. Inspect seller delivery evidence and preserve buyer evidence in its original form. Use the in product dispute path when offered and describe the requested remedy clearly. A payment rail or escrow can enforce only its implemented conditions; it does not guarantee product quality or a preferred dispute result. Escalate suspected fraud or security issues without publishing private order, identity, or payment d" }, { "id": "buy-checkout", "path": "/buy/checkout", "canonical_url": "https://docs.mobazha.org/buy/checkout", "title": "Complete a buyer checkout", "summary": "Review one store, one quote, and one payment instruction set before creating or funding an order.", "status": "beta", "audiences": [ "buyers", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/buy/checkout", "label": "Complete a buyer checkout" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/checkout", "label": "Unified checkout routes and Node order contracts" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "Create one order from a reviewed seller quote and keep the identifiers needed to recover it.", "estimated_time": "5–10 minutes", "journey": "use", "primary_action": { "label": "Start the checkout checks", "href": "/buy/checkout#before-you-start" }, "language": "en", "search_text": "Before you start Confirm the store identity, item, quantity, variant, fulfillment method, and return policy. Use a current browser session connected to the intended store and backend. Decide whether you are using account checkout or the store's optional Guest Checkout path. Have the exact payment asset available, but do not send funds before the order displays an address, amount, and expiry. Never reuse an address, QR code, quote, or amount from another order, message, screenshot, or Agent response. Checkout steps Open /product/{slug} , confirm the seller and store context, select required options, and add the item to the cart. Open Cart and confirm every line belongs to the intended seller. A marketplace may curate discovery and record attribution, but the approved seller—not the marketplace projection—must own the checkout handoff and resulting order. Continue through /checkout ; enter only the delivery and contact data required for this order, then choose a destination valid shipping method where required. Review subtotal, shipping, discounts, taxes, network or provider costs, optional services, and final total. Select an available payment method at the payment method step. Availability comes from the connected backend and store policy, not from a static list in this guide. If the order mode requires a moderator or other protection choice, review its scope and cost before confirmation. Confirm the order only after seller, recipient, final total, payment asset or provider, applicable policy, and any protection choice are visible. On confirmation, save the order identifier and tracking link, then use the order bound Payment Session for address, provider payload, amount, expiry, and progress. Pay with an external wallet Use only the payment choices still visible after the order policy is applied. A protection or settlement mode may intentionally remove a previously cached provider or rail. In the active Payment Session, match the asset or Token, network where shown, exact amount, payment address or URI, expiry, and order identifier. Do not reconstruct these values from a catalog price. Scan the active QR code or copy the active address and amount. Before approving the wallet transfer, compare the wallet's parsed recipient and amount with the Payment Session again. After broadcast, keep the transaction identifier and leave the order available for reconciliation. Read observed transfers, observed or remaining amount, observation status, and confirmations separately. If the payment instruction expires, stop using its QR code, URI, address, and amount. Refresh through the product to request the current instruction instead of sending to the expired target. An observed transfer may still be pending, incomplete, reverted, on the wrong network, or below the required amount. Only the backend's funded order state proves that the payment evidence was accepted for this order. Expected result and verification The application should display a newly created order with an authoritative state and order bound Payment Session. Confirm that the item revision, seller, seller owned backend, total, canonical payment asset or provider, funding target, amount, settlement mode, and expiry match the final confirmation you approved. A marketplace page or referral label is not the seller and must not silently become the order owner. Do not treat a wallet broadcast, a screenshot, or a pending transaction as completed payment. Wait for the order page to report the required confirmations and funded state. An order awaiting payment or payment verification should remain in the payment journey. A canceled, declined, expired, refunded, or processing error order must not be presented as payment success. Paid or fulfillment states may continue to confirmation, but the order detail remains the recovery authority. If something fails If the quote expires, return to checkout and request a new quote; do not send the old amount. If an item becomes unavailable, ret" }, { "id": "buy-guest-checkout", "path": "/buy/guest-checkout", "canonical_url": "https://docs.mobazha.org/buy/guest-checkout", "title": "Use Guest Checkout safely", "summary": "Create an anonymous buyer order while preserving the store routing context and a recoverable tracking link.", "status": "beta", "audiences": [ "buyers", "sellers", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/buy/guest-checkout", "label": "Use Guest Checkout safely" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/packages/core/services/api/guestCheckout.ts", "label": "Unified Guest Checkout implementation and Node public guest APIs" }, "reviewed": "2026-07-04", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Create a recoverable order without attaching a buyer account to the request.", "estimated_time": "5 minutes", "journey": "use", "primary_action": { "label": "Check Guest Checkout readiness", "href": "/buy/guest-checkout#before-you-start" }, "language": "en", "search_text": "Before you start The store must advertise Guest Checkout and at least one ready payment method. Complete the cart on one store; Guest Checkout does not combine unrelated store contexts. Be ready to save the generated order token or tracking link. Losing both may make order recovery difficult. Guest Checkout is anonymous transport, not an exemption from store policies, payment confirmation, or lawful delivery information. Guest Checkout steps Add an eligible item to the cart and continue to checkout. Choose Guest Checkout when the store presents it. Review any delivery fields and the seller's policies before submitting personal information. Let the application request a supply quote; this is advisory and does not itself reserve inventory. Select one payment method from those currently advertised by the backend. Create the order and immediately save the order token or buyer tracking link outside the current tab. Pay only the displayed address and amount before the displayed expiry. Reopen the tracking link to follow confirmations, shipping evidence, and completion. Expected result and verification The buyer request should not carry an administrator, seller, or previously stored user credential. It may retain same origin store routing context so the request reaches the correct store. The tracking page should show the order token, payment asset, payment destination, required confirmations, expiry, and milestone state. Milestone What it means What it does not prove Awaiting payment Order exists and waits for the displayed payment Funds have settled Funded Required payment evidence was accepted by the backend Physical delivery is complete Shipped Seller recorded shipping or delivery evidence Buyer received or accepted the item Completed The order reached its completion transition Every external claim or warranty is guaranteed If something fails If Guest Checkout is missing, the backend may have disabled it, failed readiness checks, or require account checkout. If the tracking link is lost, do not create repeated funded orders; contact the seller with sanitized payment evidence. If an existing login appears to affect the guest request, stop and report a reproducible client defect. If the payment expires, do not pay without a refreshed order instruction. Security and privacy Share the tracking link only with parties who need it. Do not post order tokens, delivery details, or transaction evidence publicly. An Agent may help explain the flow but must not create or fund the order without explicit confirmation." }, { "id": "buy-order-status", "path": "/buy/order-status", "canonical_url": "https://docs.mobazha.org/buy/order-status", "title": "Track payment and order status", "summary": "Reconcile wallet evidence with the backend-owned order state before deciding that an order is funded, shipped, refundable, or complete.", "status": "beta", "audiences": [ "buyers", "support", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/buy/order-status", "label": "Track payment and order status" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/apps/web/src/components/orders/guestOrderStages.ts", "label": "Unified order milestones and Node order API" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "Decide what the current order state proves and which recovery action is safe to take next.", "estimated_time": "3 minutes", "journey": "use", "primary_action": { "label": "Reconcile an order", "href": "/buy/order-status#before-you-start" }, "language": "en", "search_text": "Before you start Keep the order identifier or Guest Order token and the payment transaction ID. Use the same store and backend that created the order. Never paste private keys, recovery phrases, authenticated tracking URLs, or full customer details into support chat. Tracking steps Open Orders for an authenticated purchase or the saved Guest Order tracking link. Confirm seller, item, amount, payment asset, and creation time before interpreting state. Open the order bound Payment Session and compare its session ID, canonical asset, funding target, expected amount, settlement mode, and expiry with your wallet or provider record. Read observed amount, remaining amount, observations, confirmations where applicable, and the backend funding state separately. Refresh through the product UI or GET /v1/orders/{orderID}/payment session when an event announces a change. Preserve fulfillment, cancellation, refund, or dispute evidence before taking the next available action. Expected result and verification The order page should show a monotonic business state view owned by the backend. A WebSocket event or wallet notification is only a refresh signal. For important decisions, verify the current order through the authenticated HTTP API or tracking endpoint. Observation Safe conclusion Payment target ready The order has an address or provider session the buyer may use before expiry Transaction broadcast A wallet attempted to publish a transaction Transaction detected The payment system observed a candidate transaction Required confirmations reached The configured confirmation gate may be satisfied Backend state is funded The order backend accepted the payment evidence for this order Seller marked shipped Fulfillment evidence was recorded; inspect it The Payment Session capability set—not a static button list—indicates whether refresh, cancel, confirm, refund, or completion is currently available. If something fails No transaction detected: verify asset, network, destination, amount, and expiry without sending a second payment. Confirmations stalled: inspect the payment network independently and preserve the transaction ID. Wallet confirmed but order awaiting payment: report exact order and transaction identifiers privately to the operator. State conflicts across screens: stop automated actions and report a consistency defect. Tracking link does not open: confirm it belongs to this deployment and was not truncated. Recovery and escalation Do not attempt database edits or direct settlement calls to repair a buyer order. Use actions offered by the order state, then get help with sanitized evidence." }, { "id": "buy-order-notifications", "path": "/buy/order-notifications", "canonical_url": "https://docs.mobazha.org/buy/order-notifications", "title": "Respond to order and dispute notifications", "summary": "Use a notification to reach the related order or case, then refresh authoritative state before paying, fulfilling, refunding, or disputing.", "status": "beta", "audiences": [ "buyers", "sellers", "support", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/buy/order-notifications", "label": "Respond to order and dispute notifications" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/apps/web/src/app/notifications/page.tsx", "label": "Unified notification routing, grouping, and state tests" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "Route a notification to the intended business record, verify current backend state, and avoid acting on a stale or incomplete event.", "estimated_time": "3–5 minutes", "journey": "use", "primary_action": { "label": "Check a notification safely", "href": "/buy/order-notifications#before-you-start" }, "language": "en", "search_text": "Before you start Use the account, store context, or Guest Order recovery link that owns the related record. Keep the order identifier, case identifier, or Guest Order token private. Remember that read status, grouping, sound, and the notification text are presentation state. They do not change the order, payment, fulfillment, refund, dispute, or market membership state. Never pay, ship, refund, release funds, or disclose evidence solely because a notification requests it. Open the related record and verify the action there. Check the notification Open the notification bell or /notifications . Use the available order, transaction, system, or other filters only to narrow the list. Read the source, event type, time, counterparty label, and order or case context. Grouped notifications may show the latest event while retaining several event identities. Open the notification. Current routing sends ordinary order events to order detail, dispute events to the order's dispute tab, seller Guest Order events to the Admin order view, and marketplace review events to the applicable market seller page when context exists. On the target page, confirm the order, case, seller, buyer, asset, amount, and current state. Refresh from the owning backend before taking an irreversible or financial action. Marking one item or a group as read may update the unread count; it does not acknowledge fulfillment, accept a decision, or approve a transaction. Preserve the relevant business evidence in the order or dispute flow, not only in the notification list or an external chat. Expected result and verification Notification kind Expected destination What to verify there Order created, funded, confirmed, shipped, completed, canceled, or expired /orders/{orderID} or the seller Guest Order view Current backend order and Payment Session state Payment received or payment state event Related order detail Asset, target, amount, observation, confirmations, and funded state Dispute opened or case update /orders/{orderOrCaseID}?tab=dispute when an identifier exists Claim, response, evidence references, deadline, moderator, and current dispute state Marketplace seller review /marketplace/{slug}/sell when market context exists Current membership record and decision reason Chat message Chat interface or drawer Sender, room or order context, and whether an order action is separately available The destination should preserve the related identifier and show a current record. Duplicate notification identities should not create duplicate local items, but a missing or stale notification is still possible; the business record remains authoritative. If something fails If a dispute notification has no order or case identifier, it may have no safe route. Open the relevant order or cases view manually and do not guess an identifier. If marking as read or deleting a notification fails, leave the business action unchanged and retry only the presentation operation later. If a notification opens the wrong store, order, or market context, stop and report the routing defect with sanitized notification and target identifiers. If the notification is newer than the displayed order state, refresh through the product or authenticated API; do not replay the underlying mutation. If the record no longer permits the suggested action, follow the current state rather than the old notification text. Continue Track payment and order status Cancel, refund, or dispute Get help with sanitized evidence" }, { "id": "buy-cancel-refund-dispute", "path": "/buy/cancel-refund-dispute", "canonical_url": "https://docs.mobazha.org/buy/cancel-refund-dispute", "title": "Cancel, request a refund, or open a dispute", "summary": "Choose the transition allowed by the current order state and preserve the evidence needed to explain the requested remedy.", "status": "beta", "audiences": [ "buyers", "sellers", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/buy/cancel-refund-dispute", "label": "Cancel, request a refund, or open a dispute" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/api-spec", "label": "Node order and dispute contracts" }, "reviewed": "2026-07-13", "page_type": "task", "last_tested": "2026-07-13", "outcome": "Choose a valid resolution path for the active order without losing the evidence behind it.", "estimated_time": "5 minutes to assess", "journey": "use", "primary_action": { "label": "Assess the active order", "href": "/buy/cancel-refund-dispute#before-you-start" }, "language": "en", "search_text": "Before you start Open the authoritative order detail and record its current state. Read cancellation, return, refund, delivery, and dispute terms shown for the order. Preserve messages, quote, payment reference, delivery evidence, and the remedy you request. Confirm which party controls the next transition; not every state permits unilateral cancellation. Choose the path by order mode and current capability Path Typical purpose What must be verified Cancel Stop an eligible order before its current commitment or payment path closes cancellation Current order state, actor, Payment Session capability, expiry, and refund destination if funds may already exist. Refund Return an eligible amount through the supported payment path Recipient or refund address, amount, asset, prior observations, idempotency, and resulting transaction or provider reference. Dispute Ask the supported protection or moderation path to examine evidence and a requested remedy Order mode, deadline, dispute capability, roles, policy version, evidence, and settlement consequences. Complete or release Accept fulfillment or release protected funds where the model supports it Delivery evidence, actor authority, expected state, amount, and irreversibility. The order detail may expose Summary, Discussion, Dispute, and Evidence views. Discussion coordinates; Evidence supports a claim; only an admitted Core action changes protected order or payment state. Resolution steps If the order is unpaid and cancellation is available, cancel through the order page. If a funded order is not fulfilled, use the order Discussion view and state the requested remedy without exposing unnecessary private data. Use Refund only with the address, amount, and conditions displayed for the active order. Open the order Dispute view only when the deployment, order mode, deadline, and current capabilities offer that path and ordinary resolution has not succeeded. Describe expected outcome, timeline, and evidence without unnecessary personal information. Add or reference original material in the Evidence view where supported; do not replace evidence with a summary that loses timestamps or provenance. Reconcile final refund, release, or closure against both backend state and the payment system or provider. For an attempt scoped crypto payment, settlement recipients, fees, the moderator allocation, and the settlement asset are frozen before its funding target becomes actionable. A refund or dispute allocation is derived from that paid attempt; it is not repriced from the order currency or a later exchange rate. Always verify the asset and destination shown for the current action rather than reusing a previous attempt's address. Expected result and verification The UI should expose only actions valid for the current order, role, payment method, and protection state. After an accepted action, verify updated state and any resulting payment transaction independently. A submitted request is not a completed refund or settlement. If something fails If an action is missing, confirm order state, current identity, permissions, deadlines, and runtime capabilities. If a refund transaction exists but the UI is stale, preserve its identifier and request reconciliation. If a seller asks you to bypass the order flow, do not surrender evidence or accept an unverified payment destination. If a dispute deadline is close, record the current timestamp and use the supported path promptly. Security boundary Never treat documentation or Agent text as authority to release escrow, sign a settlement, or reveal recovery material. Financial transitions remain subject to identity, expected state, amount, idempotency, and payment policy checks." }, { "id": "self-host", "path": "/self-host", "canonical_url": "https://docs.mobazha.org/self-host", "title": "Run a Mobazha Node under your control", "summary": "Evaluate requirements, install on testnet, define the network boundary, monitor health, and prepare recovery before production use.", "status": "beta", "audiences": [ "operators", "developers" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host", "label": "Run a Mobazha Node under your control" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main", "label": "Mobazha deployment sources" }, "reviewed": "2026-07-06", "page_type": "hub", "outcome": "Decide whether self-hosting fits, then reach a healthy and recoverable evaluation Node.", "estimated_time": "6 minutes", "journey": "operate", "primary_action": { "label": "Check the requirements", "href": "/self-host/requirements" }, "featured_visual": { "id": "self-host-trust-boundary", "src": "/images/docs/self-host/operator-trust-boundary.svg", "sha256": "9d5d1114d2d192696b77f458663d56d3e4af3f3ba7afac0d81678ed63952451b", "mobile_src": "/images/docs/self-host/operator-trust-boundary-mobile.svg", "mobile_sha256": "72cc8ec3ce49620736bf7dfd223c389f7cd318fdf578d1ad358ea8e1e924437d", "kind": "conceptual", "width": 760, "height": 420, "mobile_width": 360, "mobile_height": 560, "alt": "Conceptual self-hosting boundary showing clients entering through an operator-controlled network boundary to a Mobazha Node and local data, with payment systems and optional hosted services remaining separate dependencies.", "caption": "Self-hosting moves operational control to the Node operator; external dependencies remain explicit.", "claim": "Explains responsibility boundaries and does not prescribe one mandatory network topology.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "self-host-boundary-light-v2", "applies_to": "Mobazha v0.3 release-candidate guidance", "reviewed": "2026-07-06" }, "language": "en", "search_text": "Choose the operating path Check host and release requirements Install an evaluation node Configure the node Set the network and TLS boundary Add monitoring and health checks Back up, upgrade, and recover Apply the security model Diagnose a node Evaluation quick start The current release candidate requires Go 1.26.4, Git, and a supported macOS or Linux environment. Use testnet while evaluating payment flows. v0.3 is for evaluation and testnet use. Stable binaries and signed release artifacts have not yet been published. What a ready evaluation Node looks like Boundary Evidence to keep Build and identity Exact source commit, build command, version, service account, network, and data directory Local health Successful service status, doctor json , embedded UI, and runtime config checks Exposure Intended listener, firewall, proxy, DNS, and TLS configuration with no accidental public administrator surface Commerce One disposable listing, quote, payment observation, fulfillment, and recovery journey on supported testnet rails Recovery Timestamped backup plus an isolated restore test using a compatible build Operations Named alert recipient, update owner, rollback owner, and a safe first response for storage, dependency, and payment failures Booting the process is only the first proof. A Node is not operationally ready when its only store copy is on the running host, when runtime capabilities are assumed from source code, or when no one owns an alert or rollback. Operator responsibilities Secure the host, administrator access, secrets, and network boundary. Back up data and recovery material before upgrades. Monitor storage, availability, payment integrations, and release notes. Expose only the interfaces your users and agents actually need. Operating loop Before accepting work: confirm health, storage, backup age, effective capabilities, and external payment or delivery dependencies. During an incident: stop advertising unavailable new work, preserve current order evidence, and isolate the failing boundary before retrying. Before an upgrade: read release evidence, make and test a recovery point, and define the maintenance and rollback decision. After a change: verify diagnostics and one representative buyer, seller, payment, webhook, and recovery path affected by the change. Monitor the Node Back up and upgrade safely Troubleshoot without destroying evidence Optional hosted connection An operator may bind a self hosted node to an optional Mobazha account for hosted capabilities when offered. Binding does not transfer custody of local recovery material and is not required for independent operation. Connect an optional hosted account" }, { "id": "self-host-requirements", "path": "/self-host/requirements", "canonical_url": "https://docs.mobazha.org/self-host/requirements", "title": "Self-hosting requirements and readiness", "summary": "Confirm platform, ownership, recovery, network, and operational capacity before installing a Mobazha Node.", "status": "beta", "audiences": [ "operators", "evaluators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host/requirements", "label": "Self-hosting requirements and readiness" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Node build and standalone deployment sources" }, "reviewed": "2026-07-04", "page_type": "policy", "outcome": "Decide whether your team can safely own the host, network, recovery, updates, and incident response.", "estimated_time": "10 minutes", "journey": "operate", "primary_action": { "label": "Review the operating baseline", "href": "/self-host/requirements#current-software-baseline" }, "language": "en", "search_text": "Current software baseline Requirement Release candidate baseline Why it matters Operating system Supported macOS or Linux environment Current source build and service paths are validated there Go 1.26.4 Matches the public build workflow Git Current supported client Records exact source revision Network Testnet during evaluation Avoids treating pre release behavior as production ready Listener Loopback by default Keeps the administrative boundary private Exact CPU, memory, storage, and bandwidth depend on listings, media, order volume, retained data, integrations, and uptime goals. Measure representative load instead of treating a minimum boot configuration as production sizing. Operational ownership Name who patches the host, controls administrator access, monitors health, and responds to payment or order incidents. Define data retention, backup frequency, restore testing, recovery objectives, and off host storage. Identify DNS, TLS, reverse proxy, firewall, RPC, indexer, webhook, and payment provider owners. Maintain a test environment representative of the production deployment. Keep recovery material accessible to authorized operators without placing it in source control or routine logs. Readiness decision Use hosted evaluation when you cannot yet own host security, backup, monitoring, updates, and incident response. Use self hosting when control and portability justify those responsibilities and the team can prove recovery before accepting material transactions. Install a Node Configure securely Back up and upgrade" }, { "id": "self-host-install", "path": "/self-host/install", "canonical_url": "https://docs.mobazha.org/self-host/install", "title": "Install a Mobazha Node", "summary": "Build the release candidate from public source, start it locally, and verify the UI and health boundary before exposing it.", "status": "beta", "audiences": [ "operators", "developers" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host/install", "label": "Install a Mobazha Node" }, "evidence": { "source": "https://github.com/mobazha/mobazha#quick-start", "label": "Mobazha Node quick start" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Start a local testnet Node from a recorded source revision and verify its health boundary.", "estimated_time": "15–30 minutes", "journey": "operate", "primary_action": { "label": "Review prerequisites", "href": "/self-host/install#before-you-start" }, "language": "en", "search_text": "Before you start The current public release candidate requires Go 1.26.4, Git, and a supported macOS or Linux environment. Start on testnet and use a dedicated data directory. Confirm available disk space, local firewall policy, backup location, and who controls the administrator session. Review detailed requirements Read the release scope Install steps Clone the public Node repository and record the exact commit you intend to evaluate. Build the Node module with the pure Go crypto implementation shown below. The current main checkout's workspace declaration can lag the module's Go requirement, so the source build command isolates the module with GOWORK=off . Initialize a testnet data directory owned by the service account. Start the Node on the default local only listener and open the embedded UI. Keep the terminal visible until initial startup and health checks succeed. Review the command before running it. v0.3 is not a stable production release, and signed release artifacts have not yet been published. Expected result and verification The first start initializes the default data directory when needed. The embedded Web UI and HTTP API listen on http://127.0.0.1:5102 by default. Versioned HTTP routes live under /v1/, WebSocket under /ws, and MCP Streamable HTTP under /v1/mcp. Local only listening is the safe default; do not expose the API to the internet until authentication, TLS, firewall, and update plans are reviewed. Run diagnostics in a second terminal: Verify that diagnostics complete, the embedded UI opens, the runtime snapshot has a supported schema, and optional capabilities remain unavailable until configured and healthy. Representative diagnostic output doctor json returns pass, warning, and failure counts plus named checks. Paths, capacities, versions, and optional dependency results vary by host. A healthy local Node should report zero failed checks; warnings must still be reviewed against the intended deployment. The list above is shortened to show the contract shape. Preserve the complete local result for operations, but redact paths and environment detail before sharing it publicly. Optional background service After validating an interactive start, install and inspect the supported background service. Pre release packaging Docker, standalone, and appliance packaging exists in the public repository, but it remains pre release. Inspect the image tag, downloaded scripts, configuration, update behavior, and recovery path before using it outside a disposable environment. Standalone packaging source Node source and release status If something fails If the build fails, confirm go version , the checked out commit, platform toolchain, and available storage. If Go reports that go.work declares an older version than go.mod , first confirm you are on the intended public revision, then use the documented module isolated GOWORK=off build. Do not lower the module requirement to make a release candidate checkout compile. If startup fails, capture sanitized diagnostics and confirm data directory ownership and port availability. If the UI does not open, test the local listener before changing DNS, TLS, or firewall configuration. If runtime capabilities are not ready, inspect configuration and dependencies rather than enabling frontend controls manually. Remove only a disposable test data directory you deliberately created; never delete the only copy of a store to retry installation." }, { "id": "self-host-configure", "path": "/self-host/configure", "canonical_url": "https://docs.mobazha.org/self-host/configure", "title": "Configure a self-hosted node", "summary": "Make deployment mode, data location, network exposure, payments, and external dependencies explicit and recoverable.", "status": "beta", "audiences": [ "operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host/configure", "label": "Configure a self-hosted node" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Mobazha Node command and deployment sources" }, "reviewed": "2026-07-04", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Run one explicit Node profile whose data, listener, dependencies, backup, and rollback owner are known.", "estimated_time": "20–40 minutes", "journey": "operate", "primary_action": { "label": "Record the deployment profile", "href": "/self-host/configure#before-you-start" }, "language": "en", "search_text": "Before you start Use a dedicated data directory and testnet while learning the operational model. Record the exact binary commit, flags, configuration, and external dependencies alongside the backup procedure. Create a backup before changing a non disposable profile. Record the binary commit, network, data directory, listener, reverse proxy, DNS, certificates, payment dependencies, and rollback owner. Configuration steps Select one explicit data directory and restrict it to the service account. Keep the administrative listener on loopback or a trusted private network. Configure an authenticated TLS reverse proxy only when remote administration is required. Enable payment and extension dependencies one at a time and inspect health after each change. Configure backup destination, monitoring, log retention, and upgrade ownership. Restart through the supported service command and re run diagnostics. Security and dependency checklist Bind administrative interfaces to trusted networks unless an authenticated reverse proxy and TLS boundary are intentionally configured. Enable only payment methods reported by the effective runtime capability set and configured by the seller. Treat RPC, indexer, webhook, plugin, and remote media inputs as untrusted dependencies. Keep secrets outside source control and separate recovery material from ordinary service configuration. Document DNS, firewall, proxy, certificate, backup, monitoring, and rollback ownership before production use. Expected result and verification A source file, recognized identifier, frontend component, or configuration field does not prove a capability is active. Effective availability is the intersection of distribution allowlist, contract compatibility, installation or composition, authorization, configuration, and health. Confirm the process uses the intended data directory and network, the local UI is reachable, effective capabilities match configured dependencies, and no administrative interface is unintentionally public. Runtime capabilities Compatibility policy If something fails Roll back the last configuration change instead of changing several variables at once. If the Node reads another profile, stop it and verify service arguments before writing new data. If remote access fails, re test loopback health before debugging proxy or DNS layers. If a capability becomes unhealthy, stop advertising new work and preserve recovery for existing orders. Restore from a verified backup only through a release compatible procedure." }, { "id": "self-host-network-and-tls", "path": "/self-host/network-and-tls", "canonical_url": "https://docs.mobazha.org/self-host/network-and-tls", "title": "Design the network and TLS boundary", "summary": "Keep Node administration private by default and expose only intentionally authenticated, encrypted, and monitored routes.", "status": "beta", "audiences": [ "operators", "security reviewers" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host/network-and-tls", "label": "Design the network and TLS boundary" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Node listener and API surfaces" }, "reviewed": "2026-07-04", "page_type": "concept", "outcome": "Choose a network boundary that keeps administration private and exposes only authenticated routes intentionally.", "estimated_time": "7 minutes", "journey": "operate", "primary_action": { "label": "Review the recommended boundary", "href": "/self-host/network-and-tls#recommended-boundary" }, "language": "en", "search_text": "Recommended boundary Do not expose the default administrative listener directly to the internet. A reverse proxy does not make an unauthenticated route safe; preserve Node authentication, request limits, body limits, timeouts, WebSocket upgrade handling, and security headers. Route considerations Surface Default path Boundary Embedded UI and HTTP API http://127.0.0.1:5102 , API under /v1/ Administrative and commerce authorization vary by operation WebSocket /ws Authenticate connection and preserve reconnect limits MCP Streamable HTTP /v1/mcp Requires gateway identity, ai:use , and tool scopes Webhooks outbound from Node Validate destination, TLS, signature, timeout, and retry behavior Exposure checklist Terminate TLS with a maintained configuration and automate certificate renewal safely. Bind Node to loopback or a private interface and restrict host firewall ingress. Forward the original scheme and host only through trusted proxy headers. Apply rate, connection, request size, and timeout limits without breaking WebSocket or MCP streaming. Separate public storefront access from administrator, token minting, wallet, and system operations. Monitor authentication failures and unexpected route exposure. Verification From outside the trusted boundary, enumerate only the intended public routes and confirm administrative operations reject unauthenticated requests. From inside, verify UI, API, WebSocket, and MCP paths required by the deployment. Re test after proxy or certificate changes." }, { "id": "self-host-monitoring", "path": "/self-host/monitoring", "canonical_url": "https://docs.mobazha.org/self-host/monitoring", "title": "Monitor a self-hosted Node", "summary": "Detect process, storage, capability, payment, webhook, and recovery degradation before it becomes an order incident.", "status": "beta", "audiences": [ "operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host/monitoring", "label": "Monitor a self-hosted Node" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Node diagnostics and operational sources" }, "reviewed": "2026-07-04", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Detect process, storage, capability, and dependency degradation before it becomes an order incident.", "estimated_time": "20–40 minutes", "journey": "operate", "primary_action": { "label": "Define the alert boundary", "href": "/self-host/monitoring#before-you-start" }, "language": "en", "search_text": "Before you start Define who receives alerts and who may take corrective action. Keep monitoring credentials separate from Node administrator and signing credentials. Decide expected availability, backup age, disk headroom, and payment dependency health. Monitoring setup steps Schedule mobazha service status and mobazha doctor json from a trusted local monitor. Monitor process restarts, disk space, filesystem errors, system time, and backup age. Poll the runtime capability snapshot and alert on unexpected readiness or method changes. Monitor RPC, indexer, webhook, and external provider latency and failures separately from Node health. Track failed authentication, repeated permission errors, webhook dead letters, and order reconciliation failures. Test alert delivery and document the first safe response for every alert class. Expected result and verification Monitoring should distinguish unavailable process, degraded dependency, denied capability, and failed business operation. Trigger a controlled non production failure and confirm the alert identifies the correct boundary without logging secrets or customer payloads. If something fails If monitoring loses access, do not weaken Node authentication; repair the narrow monitoring credential or local execution path. If a capability becomes unhealthy, stop advertising new work while preserving existing order recovery. If disk or backup alerts fire, protect current data before restarting or upgrading. If alerts contain secrets or personal data, treat that as an incident and rotate affected credentials." }, { "id": "self-host-backup-and-upgrade", "path": "/self-host/backup-and-upgrade", "canonical_url": "https://docs.mobazha.org/self-host/backup-and-upgrade", "title": "Back up and upgrade safely", "summary": "Treat upgrade readiness as a recoverability exercise, not only a package update.", "status": "beta", "audiences": [ "operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host/backup-and-upgrade", "label": "Back up and upgrade safely" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/docs/releases", "label": "Mobazha operations guidance" }, "reviewed": "2026-07-04", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Produce a verified backup and upgrade one reviewed release without losing a recoverable rollback point.", "estimated_time": "30–60 minutes", "journey": "operate", "primary_action": { "label": "Prepare the recovery point", "href": "/self-host/backup-and-upgrade#before-you-start" }, "language": "en", "search_text": "Before you start Read release notes and identify schema, payment, capability, and configuration changes. Create a versioned backup and verify that it can be read. Record the running version and configuration; protect secrets separately. Plan rollback and a maintenance window before changing production. After upgrade, verify health, store access, order flows, and payment callbacks. A backup file is not a recovery plan until it has been inspected and restored in an isolated environment using a compatible release process. Backup and upgrade steps Record the running binary version or commit, service arguments, data directory, configuration, and effective capabilities. Read both Node and client release notes and identify migrations, removed flags, payment changes, and compatibility requirements. Run diagnostics and resolve existing corruption, storage, or dependency failures before upgrading. Stop or quiesce writes according to the release procedure and create a timestamped backup. Copy the backup and required recovery material to a separately protected location. Test the new release against representative data in an isolated environment. Schedule a maintenance window, install the reviewed artifact, and start the service. Verify diagnostics, storefront, administration, order reads, payment observation, webhook delivery, and backup creation. Built in commands Run diagnostics and create a compressed backup before a release change. The backup command reports the resolved source and output path, then the final archive size. Paths and size are deployment specific. Expected result and verification The backup command should finish without error and produce a non empty archive at the requested path. Record its size, creation time, source version, and a cryptographic checksum. Keep secrets and recovery material under a separate access policy even when the archive contains encrypted data. After upgrade, compare effective capabilities and complete a small testnet journey. Do not declare success from process health alone. Recovery and rollback The current release candidate does not publish a universal one command restore promise for every historical version. Use release specific migration and restore guidance, preserve the original backup, and practice on a separate data directory first. Roll back only when the older binary supports the resulting data format. If startup fails after upgrade, stop repeated writes and preserve logs and the upgraded data copy. If a migration is one way, restore the pre upgrade backup rather than opening migrated data with an older binary. If orders or payments disagree, keep financial automation fail closed while reconciling state. Report missing restore instructions as a release blocker, not as an operator detail to improvise in production." }, { "id": "self-host-security", "path": "/self-host/security", "canonical_url": "https://docs.mobazha.org/self-host/security", "title": "Secure a self-hosted node", "summary": "Protect the host, administrative boundary, signing material, payment integrations, backups, and recovery path as one system.", "status": "beta", "audiences": [ "operators", "security reviewers" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host/security", "label": "Secure a self-hosted node" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/SECURITY.md", "label": "Mobazha security policy and extension security model" }, "reviewed": "2026-07-04", "page_type": "policy", "outcome": "Establish the minimum host, identity, secret, payment, monitoring, and recovery controls for a Node you operate.", "estimated_time": "10 minutes", "journey": "operate", "primary_action": { "label": "Review the operator baseline", "href": "/self-host/security#minimum-operator-baseline" }, "language": "en", "search_text": "Minimum operator baseline Use a dedicated, patched host and least privilege service account. Keep admin APIs private by default; add TLS, authentication, rate limits, and network policy before remote exposure. Protect seed phrases, private keys, API tokens, webhook secrets, and backups independently. Review every chain RPC, indexer, plugin, webhook, and delivery integration as a hostile input boundary. Monitor health, storage, failed authentication, payment observation, webhook delivery, and unexpected capability changes. Test restore and rollback before a release or infrastructure change. Financial boundaries Only Core policy may change payment, refund, dispute, or settlement state. Extensions and external services must not receive raw seed phrases or private keys. A payment observation is not permission to settle; expected state, identity, amount, confirmations, and idempotency still apply. Disabling an unhealthy capability must fail closed rather than silently select a different financial behavior. Report vulnerabilities privately Do not open a public issue for a suspected vulnerability, leaked credential, signing key concern, or exploit. Use GitHub private vulnerability reporting from the affected repository's Security tab. Node security policy Supply chain audit baseline" }, { "id": "self-host-troubleshooting", "path": "/self-host/troubleshooting", "canonical_url": "https://docs.mobazha.org/self-host/troubleshooting", "title": "Troubleshoot a Mobazha Node", "summary": "Diagnose version, process, health, capability, configuration, and dependency failures without exposing sensitive data.", "status": "beta", "audiences": [ "operators", "support" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host/troubleshooting", "label": "Troubleshoot a Mobazha Node" }, "evidence": { "source": "https://github.com/mobazha/mobazha#operations", "label": "Mobazha Node operations commands" }, "reviewed": "2026-07-04", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Isolate one failing boundary and preserve a reproducible, sanitized test before making recovery changes.", "estimated_time": "10–30 minutes", "journey": "operate", "primary_action": { "label": "Capture the starting state", "href": "/self-host/troubleshooting#before-you-start" }, "language": "en", "search_text": "Before you start Create or locate a current backup before changing data, flags, versions, or payment configuration. Record the exact symptom, first occurrence, recent changes, version, platform, network mode, and intended data directory. Diagnostic steps Confirm binary version, start flags, data directory, network mode, system time, and available disk space. Check service status and diagnostics without exposing secrets. Test the local UI and runtime endpoint before external DNS, proxy, or browser layers. Compare advertised runtime capabilities with the failing operation. Separate Node failure from RPC, indexer, network, payment provider, webhook consumer, or browser failure. Reproduce one smallest failing request or UI journey and preserve its sanitized identifiers. First checks Confirm the binary version, start flags, data directory, network mode, and system clock. Check that the local UI and health endpoint respond before testing external DNS or proxies. Compare the advertised runtime capabilities with the operation that is failing. Separate node failure from RPC, indexer, network, payment provider, webhook consumer, or browser failure. Symptom First boundary to check Avoid Process will not start data directory ownership, port, disk, prior process deleting the profile Local UI unavailable loopback listener and process health changing public DNS first Capability missing runtime snapshot, configuration, dependency health enabling frontend only flags Payment not detected order, asset, address, amount, expiry, RPC health sending a second payment Webhook delayed delivery history, endpoint response, signature handling treating duplicates as new state Safe evidence for support Record the exact version or commit, operating system, reproduction steps, expected result, and sanitized error. Include request, event, or order identifiers only when they do not expose customer data or secrets. Remove tokens, private endpoints, seeds, keys, wallet recovery material, raw customer data, and full production databases. For a suspected security issue, stop public discussion and use private vulnerability reporting. Recovery before experimentation Create and verify a backup before changing data, flags, versions, or payment configuration. Prefer a reproducible rollback over repeated manual mutation of the only copy of a store. Expected result and verification A diagnosis should identify the failing boundary and a reproducible test, not merely make the symptom disappear. After a change, rerun diagnostics and the smallest affected journey, then confirm unrelated order and payment paths remain stable. If something fails Stop after two unexplained retries and preserve the original evidence. Revert the last known configuration change when the rollback is understood. Do not edit Core order or payment tables to force a state transition. Escalate security concerns privately and operational defects through the Node issue tracker. Get help Public support paths Node issues" }, { "id": "self-host-bind-account", "path": "/self-host/bind-account", "canonical_url": "https://docs.mobazha.org/self-host/bind-account", "title": "Connect optional hosted capabilities", "summary": "Keep local node ownership separate from any optional account or hosted service connection.", "status": "draft", "audiences": [ "operators" ], "applies_to": "Design direction; not a shipped guarantee", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/self-host/bind-account", "label": "Connect optional hosted capabilities" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/README.md", "label": "Mobazha public release boundary" }, "reviewed": "2026-07-04", "page_type": "policy", "outcome": "Determine whether an optional hosted connection has a stable public contract before exchanging node or account authority.", "estimated_time": "4 minutes", "journey": "operate", "primary_action": { "label": "Read the current status", "href": "/self-host/bind-account#what-is-stable-today" }, "language": "en", "search_text": "What is stable today A local standalone store remains usable for administration, listings, data export, and supported UTXO payment flows without a Mobazha Hosting account. Optional services may later add discovery, search, routing, managed updates, or support. There is not yet a stable public node to account binding contract. Do not treat internal endpoints, old screenshots, or historical design documents as a supported procedure. Before connecting any service Confirm that you are administering the intended node and account. Create a fresh backup and keep recovery material outside the browser session. Require a clear explanation of the capability, data exchange, permissions, revocation, and price. Do not paste seed phrases, wallet private keys, or database credentials into an account binding form. Publication gate for a supported flow The public node and client repositories describe the same versioned contract. The UI shows the node identity, requested permissions, exchanged data, and revocation path. Authentication does not expose node recovery material or silently widen runtime capabilities. Automated tests cover connection, denial, expiry, revocation, and recovery." }, { "id": "build", "path": "/build", "canonical_url": "https://docs.mobazha.org/build", "title": "Build on advertised capabilities", "summary": "Integrations should discover what a backend supports instead of assuming every Mobazha deployment exposes the same surface.", "status": "beta", "audiences": [ "developers", "agent builders" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build", "label": "Build on advertised capabilities" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public source organization" }, "reviewed": "2026-07-04", "page_type": "hub", "outcome": "Choose the current public contract for an integration and make the first scoped call without assuming every deployment is identical.", "estimated_time": "5 minutes", "journey": "build", "primary_action": { "label": "Make the first API call", "href": "/build/quickstart" }, "language": "en", "search_text": "Integration rule Use the connected backend's capability response and version information as runtime truth. Documentation describes interfaces and intent, but a client must handle unavailable, disabled, or differently versioned features. Surfaces HTTP and WebSocket interfaces for commerce operations and live updates. Webhooks for operator controlled event delivery. MCP and agent oriented interfaces with explicit identity and authorization boundaries. Plugins and contracts only where the connected deployment advertises them. The current Node entry points are HTTP under /v1/, WebSocket under /ws, and MCP Streamable HTTP under /v1/mcp. Exact operations remain version and capability dependent. Start building Choose a surface and integration contract Separate client shells, context routing, transports, events, and state authority. First authenticated API call Discover capabilities and call a protected read. Authentication and scopes Select Basic, hosted JWT, or scoped API token. Errors, retries, and idempotency Preserve business correctness across unknown outcomes. HTTP API and OpenAPI Use the generated operation and schema contract. Webhooks Verify signatures, deduplicate, and reconcile. WebSocket Treat events as refresh signals. MCP and agents Initialize a scoped Streamable HTTP client." }, { "id": "build-quickstart", "path": "/build/quickstart", "canonical_url": "https://docs.mobazha.org/build/quickstart", "title": "Call your local Mobazha Node API in five minutes", "summary": "Discover runtime capabilities, use the declared authentication boundary, and make one read-only request against a local evaluation Node.", "status": "beta", "audiences": [ "developers", "agent builders" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/quickstart", "label": "Call your local Mobazha Node API in five minutes" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/api-spec/openapi.json", "label": "Generated Node OpenAPI and runtime contract" }, "reviewed": "2026-07-06", "page_type": "task", "last_tested": "2026-07-04", "outcome": "Confirm the Node you reached and complete one scoped, read-only API request.", "estimated_time": "5 minutes", "journey": "build", "primary_action": { "label": "Run the first call", "href": "/build/quickstart#first-call" }, "language": "en", "search_text": "First call With a local evaluation Node running and a scoped MBZ API TOKEN set in the environment, discover the runtime before calling a protected read only endpoint. The token is not a public signup key. A standalone administrator creates it through the supported Admin surface or token API, assigns only the scopes required by the integration, and stores the one time secret outside source code. Review token creation and revocation before running the protected call. Before you start Run a v0.3 release candidate Node on the default loopback listener. Install curl and jq and keep credentials in environment variables rather than shell history. Use a disposable test profile and the narrowest identity appropriate to the operation. Read the current OpenAPI security declaration; public runtime discovery does not make administrative routes public. First call steps Read the public runtime snapshot and record schema, deployment, readiness, and advertised capabilities. Confirm the Node version and operation exist in the generated OpenAPI contract. Choose standalone Basic Auth, hosted Bearer JWT, or a scoped mbz API token as declared for that operation. Call a read only endpoint first and inspect both HTTP status and response envelope. Remove credentials from terminal output, logs, screenshots, and support evidence. Expected result and verification Runtime discovery should return a success envelope without requiring an administrative credential. The protected call should succeed only when the token is valid and has the required scope. Confirm the response belongs to the intended Node before building automation around it. Also test one route outside the token's scope in a disposable environment. It should return 403 ; if it succeeds, the credential is broader than the quickstart requires and should be replaced before automation is deployed. If something fails 401 indicates missing or invalid authentication; do not retry rapidly with guessed credentials. 403 indicates the resolved identity lacks the required permission or scope. 404 may mean wrong base URL, version, route, or unavailable composition; check OpenAPI and runtime capabilities. 409 usually requires state reconciliation before retry. 429 requires bounded backoff and respect for server guidance. A transport success with an application error still requires error handling. Continue Authentication and scopes Errors, retries, and idempotency HTTP API and OpenAPI" }, { "id": "build-authentication", "path": "/build/authentication", "canonical_url": "https://docs.mobazha.org/build/authentication", "title": "Authentication, identities, and scopes", "summary": "Select the identity and credential model declared by the connected deployment and grant only the scopes required for one integration.", "status": "beta", "audiences": [ "developers", "operators", "agent builders" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/authentication", "label": "Authentication, identities, and scopes" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/api-spec/openapi.json", "label": "OpenAPI security schemes and Node auth token API" }, "reviewed": "2026-07-04", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "Choose the supported identity and issue the narrowest credential required by one integration.", "estimated_time": "10 minutes", "journey": "build", "primary_action": { "label": "Review scoped API tokens", "href": "/build/authentication#scoped-api-tokens" }, "language": "en", "search_text": "Authentication models Credential Intended boundary Transport Standalone administrator Local operator administration HTTP Basic over a trusted TLS or loopback boundary Hosted identity Hosted user or service identity Bearer JWT issued by the hosted authentication flow Scoped standalone token Automation against a standalone Node Bearer token with mbz prefix and explicit scopes The operation's OpenAPI security declaration is authoritative for accepted credential types. A token accepted by one route is not permission for every route. Scoped API tokens Minting and listing local API tokens requires an administrator identity. Use the supported Admin surface or /v1/auth/tokens , record purpose and owner, show the secret only through the supported creation response, and store it in a secret manager. Verify the credential boundary Call one read only route required by the integration and one route outside its scope in a disposable environment. The intended route should succeed; the out of scope route should return 403 without widening the token. An invalid or revoked token should return 401 . Record the token owner, purpose, scopes, creation time, rotation plan, and revocation path without recording the secret. Authorization and scope rules Grant read scopes separately from create, manage, spend, settlement, or administrative scopes. MCP requires ai:use at the transport boundary and each tool's domain scope. Keep buyer anonymous Guest Checkout requests free of seller or administrator credentials. Resolve the current role and store context explicitly in multi store or hosted deployments. Rotate and revoke tokens after exposure, role change, integration retirement, or unexplained use. Errors and safe handling Treat 401 as an authentication failure and 403 as an authorization failure; do not collapse them into retry loops. Never put tokens in URL query strings, documentation examples, browser storage outside the product contract, or support reports. Redact authorization headers and token creation responses from logs. If a broad token was exposed, revoke it before investigating downstream use. Compatibility Pin automation to a tested Node version and re read OpenAPI security and scope requirements during upgrades. A frontend login cookie, old Basic credential, or internal hosted token is not automatically a supported public integration credential." }, { "id": "build-errors-and-idempotency", "path": "/build/errors-and-idempotency", "canonical_url": "https://docs.mobazha.org/build/errors-and-idempotency", "title": "Errors, retries, and idempotency", "summary": "Preserve business correctness across transport failures, duplicate delivery, conflicts, timeouts, and unknown outcomes.", "status": "beta", "audiences": [ "developers", "agent builders" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/errors-and-idempotency", "label": "Errors, retries, and idempotency" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/api-spec/openapi.json", "label": "Node API error contracts and state-machine implementation" }, "reviewed": "2026-07-04", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "Decide whether to stop, correct, reconcile, or retry without duplicating a protected business action.", "estimated_time": "8 minutes", "journey": "build", "primary_action": { "label": "Review the retry decision", "href": "/build/errors-and-idempotency#retry-decision" }, "language": "en", "search_text": "Error classes Status Interpretation Default response 400 Request is invalid for the declared contract Correct the request; do not blind retry 401 Authentication is missing or invalid Refresh or replace the intended credential 403 Identity lacks permission or scope Stop and request narrower authorized access 404 Resource, route, or deployment surface is absent Verify identity, version, path, and capability 409 Current state conflicts with the attempted transition Reload authoritative state before deciding 429 Rate boundary was exceeded Back off and honor server guidance 5xx Server or dependency failed Retry only when the operation is safe and reconcilable Read the structured error response and stable code where the contract defines one. Do not parse human messages as machine state. Retry decision Idempotency and reconciliation Assign a stable client operation identity when the endpoint supports it. Persist request intent before sending a financial or order transition. On timeout, read the order, payment, webhook delivery, or action status before resubmitting. Deduplicate webhooks by delivery and event identity. Treat WebSocket events as refresh signals rather than commands. Keep retry budgets finite and surface unknown outcomes for review. Authentication and information safety Error logs may include route, status, stable error code, correlation identifier, and sanitized resource identity. They must not include Bearer tokens, Basic credentials, seeds, private keys, customer payloads, or unredacted webhook secrets. Compatibility Re run negative, timeout, duplicate, and conflict tests against every supported Node version. A successful happy path does not establish retry safety." }, { "id": "build-runtime-capabilities", "path": "/build/runtime-capabilities", "canonical_url": "https://docs.mobazha.org/build/runtime-capabilities", "title": "Runtime capabilities and product composition", "summary": "Discover effective behavior from the connected backend and keep deployment, experience, capabilities, permissions, and experiments separate.", "status": "beta", "audiences": [ "developers", "agent builders", "operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/runtime-capabilities", "label": "Runtime capabilities and product composition" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/packages/core/config", "label": "Unified runtime configuration implementation" }, "reviewed": "2026-07-04", "page_type": "concept", "outcome": "Decide whether a feature is effectively available without confusing code presence, product profile, capability, permission, or readiness.", "estimated_time": "8 minutes", "journey": "build", "primary_action": { "label": "Review effective availability", "href": "/build/runtime-capabilities#new-work-availability" }, "language": "en", "search_text": "New work availability Every applicable gate must pass before a capability is advertised or accepts a new operation. Recognition, source presence, UI code, or a configured name is descriptive only. This projection answers whether the connected backend may admit new work for the current context. It does not erase a persisted provider binding or authorize the backend to abandon an existing payment, settlement, delivery, compensation, or reconciliation obligation. Those decisions remain with the owning domain manager and Core state. Runtime configuration roles The bootstrap shell owns deployment mode, product experience, authentication transport, brand, and initial external resource policy. GET /v1/runtime config supplies backend owned feature and capability state. capabilitiesReady distinguishes an authoritative denial from a placeholder that has not loaded. Capabilities control availability, permissions control the current actor, and feature flags control experiments or kill switches. A capability snapshot may hide or block new actions while existing bound work remains serviceable or reconcilable. Clients may narrow availability for safety or session validity but must never widen the backend response. Product composition axes Authentication mode selects the authentication transport; it does not enable a product capability. Deployment describes hosted, standalone, or sovereign operation. Experience selects a platform, store, or marketplace shell. Capabilities describe backend implemented product behavior. Permissions describe what the current actor may do. Feature flags describe experiments or kill switches and cannot replace authorization. Current frontend composition slice The framework neutral resolver kernel is published through @mobazha/commerce kit/composition . It accepts a host owned product profile, readiness, supported profile matrix, build included feature catalog, and capability and policy predicates. Unified adapts validated Runtime Config, presentation channel, and storefront request context to that kernel. The kernel returns pending , ready , or invalid , enabled and excluded feature IDs, and structured diagnostics; applications still own routing, providers, authorization, and final materialization. The first resolved feature slices are: Guest Checkout, gated by the effective commerce.checkout capability; marketplace operator routes and navigation, limited to a supported hosted profile outside storefront request context; marketplace seller review routes and navigation under the same composition boundary. Pending capability state remains a loading state rather than an authoritative denial. Unsupported profiles, duplicate feature IDs, absent capabilities, restricted external resources, and features missing from the build fail closed. Backend authorization remains authoritative after a route is visible. Product actions are the second Commerce Kit dogfood slice. The shared CommerceProductActionButtons contract owns stable add to cart and buy now identity, disabled state, callback wiring, and an optional host rendering adapter. Unified consumes it in desktop detail, mobile detail, and the responsive bottom bar while retaining its own buttons, layout, localization, inventory, payment, and asset policy. Cart summary is the next dogfood slice. Shared summary content normalizes item count, total, checkout disabled state, checkout action, and optional host rendering. Unified consumes it in the drawer, desktop seller group footer, multi seller total, and mobile fixed bar while seller grouping, authentication and registration routing, currency display, channel native calls to action, cart storage, and checkout navigation remain host owned. The current application projections still use resolved feature eligibility only for routes and navigation. Entity scoped product policy is not a global capability, and the product action and cart summary APIs remain provisional until a second independent application proves the" }, { "id": "build-token-identifiers", "path": "/build/token-identifiers", "canonical_url": "https://docs.mobazha.org/build/token-identifiers", "title": "Token and on-chain asset identifiers", "summary": "Use a versioned, parseable identifier across clients while treating exact parsing behavior and supported standards as release-scoped contracts.", "status": "beta", "audiences": [ "developers", "integrators", "agent builders" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/token-identifiers", "label": "Token and on-chain asset identifiers" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/packages/core/utils/tokenIdentifier.ts", "label": "Unified token identifier implementation and tests" }, "reviewed": "2026-07-04", "page_type": "concept", "outcome": "Parse and compare a token identifier without treating recognition as ownership, price, transfer authority, or runtime support.", "estimated_time": "6 minutes", "journey": "build", "primary_action": { "label": "Review the identifier shape", "href": "/build/token-identifiers#public-identifier-shape" }, "language": "en", "search_text": "Public identifier shape New identifiers encode the uppercase network, lowercase contract address, token standard, and token or slot identifier. Examples include SEPOLIA 0x1234... ERC721 42 , SEPOLIA 0x1234... ERC1155 1 , and SEPOLIA 0x1234... ERC3525 1 . The exact parser, normalization, supported standards, legacy forms, and serialized field remain versioned implementation contracts. Do not create an identifier by concatenating unvalidated user input or infer that an asset is enabled merely because its identifier parses. Identity semantics ERC 721 and ERC 1155 assets use contract address plus token ID as the asset identity. ERC 3525 integrations may use a slot identifier for the asset class while individual holdings retain their own token identity. Network identity is part of the identifier; the same contract address on another network is a different namespace. Contract addresses are normalized before comparison. Human symbols are display metadata and are not sufficient unique identifiers. Compatibility and safety Parse legacy forms only through the maintained parser and preserve the original value for migration evidence. Treat unknown standards and malformed identifiers as unsupported rather than guessing. Resolve network, contract, and token metadata through trusted configuration or verified chain data. Keep identifier recognition separate from runtime capability, authorization, ownership, pricing, and settlement support. Agents must not turn a parseable identifier into a purchase or transfer without an effective capability and user confirmation. Implementation evidence Identifier implementation RWA type contracts Runtime capability rules" }, { "id": "build-api", "path": "/build/api", "canonical_url": "https://docs.mobazha.org/build/api", "title": "HTTP API and OpenAPI", "summary": "Use the generated Mobazha Node OpenAPI contract as the operation and schema reference, then verify runtime capabilities before calling optional features.", "status": "beta", "audiences": [ "developers" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/api", "label": "HTTP API and OpenAPI" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/api-spec/openapi.json", "label": "Generated Mobazha Node OpenAPI contract" }, "reviewed": "2026-07-04", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "Identify the current Node contract and confirm a capability before building against its versioned route.", "estimated_time": "7 minutes", "journey": "build", "primary_action": { "label": "Run the capability call", "href": "/build/api#first-capability-call" }, "language": "en", "search_text": "Contract and entry points Mobazha Node exposes versioned HTTP routes under /v1/ and WebSocket connections under /ws. The generated OpenAPI document describes request methods, paths, schemas, response envelopes, and declared authentication mechanisms for the reviewed source revision shown in the API Reference. The specification is a release candidate contract, not proof that every optional operation is enabled by a particular backend. Read /v1/runtime config and capability endpoints before exposing optional UI or automation. Browse the API Reference Search operations and schemas in a read only, human oriented reference. Download OpenAPI JSON Use the same reviewed contract with generators, agents, and CI. API source and generator Inspect the generated artifact and its owning repository. First capability call A local Node publishes its frontend runtime snapshot without requiring an authenticated business operation. Use it to verify schema version, deployment composition, readiness, features, and capabilities before constructing optional UI or automation. The example assumes the default local listener. Do not disable authentication or expose an administrative listener merely to make an example work. Expected result The runtime call should return a successful JSON envelope describing the Node schema, deployment composition, readiness, and effective capabilities. Record the Node version and capability you intend to use. A missing or unavailable capability is a decision to stop or degrade the integration—not a reason to enable a frontend only switch. A default standalone store currently returns this representative projection when the response is narrowed to the composition fields. Capability and feature values vary by the connected Node and remain authoritative. Authentication choices HTTP Basic authentication is available for the standalone administrator boundary. Bearer JWTs represent hosted identities where the deployment supports them. Scoped mbz API tokens are the preferred automation credential for supported standalone integrations. Choose the narrowest credential and scope set, store it outside source code, and rotate or revoke it after exposure. Client requirements Choose the authentication mechanism required by the connected deployment; do not copy credentials into URLs or logs. Treat non success responses and stable error codes as part of the state machine, not only as transport failures. Use idempotency and reconciliation for operations that may be retried or have financial effects. Pin integrations to a tested Node version and re run contract tests before upgrades. Never infer support from an endpoint appearing in source or OpenAPI when the effective capability is absent. Request and response workflow Inspect HTTP status before consuming the success envelope. Exact inner response schemas belong to the generated OpenAPI contract. Keep base URL, Node version, credential type, and expected capability explicit in client configuration. Errors, retries, and compatibility Handle 401 , 403 , 404 , 409 , 429 , and 5xx as distinct classes. Reconcile authoritative state after a timeout on an order, payment, refund, or settlement operation. Do not retry a financial mutation unless the endpoint contract provides idempotency or reconciliation. Test generated clients and hand written integrations against the exact release tag before upgrades. Authentication and scopes Errors, retries, and idempotency" }, { "id": "build-websocket", "path": "/build/websocket", "canonical_url": "https://docs.mobazha.org/build/websocket", "title": "WebSocket events", "summary": "Use authenticated WebSocket events for timely UI updates, then reconcile important state through the authoritative HTTP API.", "status": "beta", "audiences": [ "developers", "client maintainers" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/websocket", "label": "WebSocket events" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/internal/api/ws.go", "label": "Mobazha WebSocket gateway and event registry" }, "reviewed": "2026-07-04", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "Use an authenticated event as a refresh signal and recover current state after reconnecting.", "estimated_time": "10 minutes", "journey": "build", "primary_action": { "label": "Review client behavior", "href": "/build/websocket#client-behavior" }, "language": "en", "search_text": "Current connection boundary The default Node WebSocket endpoint is /ws. Deployments that route multiple nodes may also use a node specific path. The gateway authenticates the connection before it joins the node event hub. A complete versioned AsyncAPI style event contract has not yet been published. Treat current event envelopes as release candidate behavior and test against the exact Node and client versions you deploy. Client behavior Use the supported client authentication path and avoid tokens in URLs when a safer protocol or header mechanism is available. Reconnect with bounded backoff and assume a connection gap can lose transient events. Deduplicate persistent notifications and tolerate additive unknown event types. Treat an event as a signal to refresh protected state; do not settle, refund, or complete an order solely from an unverified push payload. Keep route capability and authorization checks even when an event announces a feature or action. Expected result After authenticating, the client should receive only events allowed for the resolved identity and deployment. Disconnect the client briefly, reconnect with bounded backoff, and confirm it refreshes current resource state through HTTP before enabling an action. The integration is not complete if it requires every transient event to arrive exactly once or in business state order. Authentication and connection errors Use the authentication mechanism supported by the deployed client and gateway. Avoid credentials in WebSocket URLs when a safer session, cookie, header, or subprotocol boundary is available. A failed authentication must not degrade into an anonymous administrative connection. Back off with jitter after disconnect and cap retries. Assume events can be lost during a gap and reconcile current state after reconnect. Treat malformed or unknown events as non authoritative input. Stop automated financial actions when event identity, version, or resource binding is ambiguous. Implementation evidence WebSocket gateway Event registry Shared client" }, { "id": "build-mcp", "path": "/build/mcp", "canonical_url": "https://docs.mobazha.org/build/mcp", "title": "MCP and agent integrations", "summary": "Agents can discover and invoke permitted commerce capabilities, but cannot replace user consent, policy, or backend authorization.", "status": "beta", "audiences": [ "agent builders", "security reviewers" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/mcp", "label": "MCP and agent integrations" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/pkg/mcp", "label": "Mobazha agent-capability sources" }, "reviewed": "2026-07-04", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "Initialize an authenticated MCP session and discover only the tools permitted for its resolved scopes.", "estimated_time": "10 minutes", "journey": "build", "primary_action": { "label": "Initialize the transport", "href": "/build/mcp#initialize-the-transport" }, "language": "en", "search_text": "Current transport Mobazha Node exposes MCP over Streamable HTTP at /v1/mcp. GET and POST share this endpoint. Treat discovery, authentication, scopes, tool availability, and errors as properties of the connected Node version—not of this prose page. Current authentication and scope contract Every /v1/mcp request first passes the Node gateway authentication boundary. The Streamable HTTP front door resolves the caller identity and requires the ai:use scope. Administrator identities receive the applicable administrative scope set; API tokens must be minted with ai:use explicitly. Individual tools also require their domain scopes, such as listings:read, orders:manage, wallet:read, or chat:write. A tool missing its required scope must remain unavailable or return permission denied; MCP does not bypass the underlying HTTP authorization. MCP scope guard Tool scope mapping Initialize the transport Use an MCP SDK that supports Streamable HTTP and preserve the session information returned by the server. The initial request is standard JSON RPC over the authenticated /v1/mcp endpoint. After initialization, complete the SDK's initialized notification, list available tools, and call only a tool returned for the current identity and scope set. Expected result Initialization should return an MCP session compatible with the requested protocol version. Tool discovery should expose only tools permitted by ai:use , the resolved identity, domain scopes, runtime capabilities, and the connected Node version. Repeat discovery with a narrower disposable token and confirm protected tools disappear or reject access rather than relying on prompt instructions to constrain them. Non bypassable boundaries Authenticate the human, service, or agent identity appropriate to the action. Request the narrowest scopes and make spend or settlement authority explicit. Require confirmation where the backend or policy requires it. Do not let prompt text override order state, quote terms, recipient amounts, or authorization checks. Keep auditable request, approval, and result identifiers without logging secrets. Audit and errors The standalone server records structured MCP tool audit events with the tool name, result, duration, transport, resolved identity when available, and redacted arguments. Bridge errors preserve the API error boundary, including authentication, permission, conflict, rate limit, and server failures. Audit visibility supports review; it does not make a broad token safe. Create narrow, revocable tokens and keep secrets out of prompts and logs. Failure handling and compatibility Authentication and permission errors require credential or scope correction, not prompt retries. A tool conflict requires re reading underlying order or resource state. Rate limits and transient server failures require bounded backoff. Unknown tool or schema versions require rediscovery; do not call a cached tool definition blindly. A successful tool response does not replace user confirmation, payment evidence, or backend owned state." }, { "id": "build-webhooks", "path": "/build/webhooks", "canonical_url": "https://docs.mobazha.org/build/webhooks", "title": "Webhook integration contract", "summary": "Design consumers for authentication, retries, duplication, reordering, and version change before depending on event delivery.", "status": "beta", "audiences": [ "developers", "operators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/webhooks", "label": "Webhook integration contract" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/pkg/webhook", "label": "Mobazha webhook engine and OpenAPI contract" }, "reviewed": "2026-07-04", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "Authenticate, durably accept, deduplicate, and safely reconcile one webhook delivery.", "estimated_time": "15 minutes", "journey": "build", "primary_action": { "label": "Implement delivery verification", "href": "/build/webhooks#delivery-envelope-and-verification" }, "language": "en", "search_text": "Consumer checklist Verify authenticity before parsing or acting on a payload. Use stable event identifiers for idempotency. Return success only after durable acceptance. Reconcile state through the authoritative API instead of treating delivery order as state order. Redact credentials and personal data from logs and dead letter tooling. Current management surface The Node OpenAPI contract includes webhook registration, update, deletion, test delivery, and delivery history operations under /v1/webhooks. Event names and payload schemas remain version dependent during the release candidate period. Webhook source Signing, event, persistence, retry, and delivery contracts. OpenAPI JSON Find the current /v1/webhooks operations and schemas. Delivery envelope and verification Current events use a CloudEvents 1.0 structured JSON envelope. Each delivery includes X Webhook ID, X Webhook Timestamp, and X Webhook Signature headers. The signature is HMAC SHA256 over the delivery ID, Unix timestamp, and exact request body, with the sha256= prefix. Verify the signature using the endpoint secret and the unmodified raw body. Reject timestamps outside the current five minute replay window. Use the CloudEvent ID and delivery ID as deduplication evidence; do not assume arrival order is business state order. Return a 2xx response only after the event is durably accepted. Use the exact raw request bytes. Parsing and re serializing JSON before verification can change the signed body. Signing implementation CloudEvent envelope Verification exercise Register a non production endpoint, trigger one test delivery, and preserve its delivery ID. Confirm that a valid request is durably accepted once, the exact same delivery is deduplicated, an altered body fails signature verification, and a timestamp outside the replay window is rejected. Then reconcile the referenced resource through the HTTP API instead of trusting event order. Standalone defaults The current standalone defaults are five total delivery attempts, exponential backoff beginning at 30 seconds and capped at one hour, a 10 second request timeout, five second polling, and seven day completed delivery retention. Deployments may override these values, so consumers must not infer a guaranteed retry schedule from the defaults. Delivery is at least once in practice: duplicates and reordering are expected integration conditions, not exceptional bugs. Authentication, errors, and recovery Webhook management operations require an accepted administrator, hosted, or scoped API token identity. The receiver authenticates deliveries with the endpoint secret and signature headers. Return 2xx only after durable acceptance; a transient failure should produce a retryable non success response. Deduplicate before executing business effects. Reconcile order or payment state through the API after every important event. Inspect delivery history and dead letter state before manually replaying. Rotate an exposed endpoint secret and reject signatures outside the replay window." }, { "id": "build-extensions", "path": "/build/extensions", "canonical_url": "https://docs.mobazha.org/build/extensions", "title": "Extend Mobazha through public contracts", "summary": "Choose the narrowest typed extension mechanism and preserve Core authority, capability gates, isolation, recovery, and audit.", "status": "draft", "audiences": [ "extension developers", "architects", "security reviewers" ], "applies_to": "Design direction; not a shipped guarantee", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/build/extensions", "label": "Extend Mobazha through public contracts" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/docs/extensions", "label": "Mobazha Open Core extension contracts" }, "reviewed": "2026-07-04", "page_type": "concept", "outcome": "Select the narrowest extension mechanism without transferring Core order, payment, settlement, key, or audit authority.", "estimated_time": "12 minutes", "journey": "build", "primary_action": { "label": "Choose the mechanism", "href": "/build/extensions#choose-the-mechanism" }, "language": "en", "search_text": "Choose the mechanism Port: replace an implementation that Core requires. Module: assemble reviewed capabilities into a distribution. Function: customize a bounded deterministic business decision. Controller: reconcile an external system or perform external I/O. OrderExtension: bind a versioned resource or multi stage domain process to an order. Use the narrowest mechanism that matches one responsibility. A package may implement more than one role, but each public contract has one authority boundary. A callback is not automatically a Port, and a Module is not a service locator. Preserve Core authority Extensions submit declarations, decisions, observations, or attestations. Core validates identity, authorization, schema and contract versions, resource binding, expected state, idempotency, freshness, and policy before creating a Core owned command or durable fact. Do not add a generic hook when a typed domain contract can express the need. Core retains release policy, order state, payment verification, settlement gates, audit, and key custody. Third party code must not import internal packages, receive the Core object, or access raw signing material. Extensions never write Core tables or directly invoke an internal state transition. Payment, refund, dispute, and settlement changes re enter a versioned, idempotent Core command and state machine. Design rules Ports provide replaceability for narrow Core owned capabilities. Modules provide immutable startup composition and declare identity, versions, dependencies, capabilities, configuration, runtime type, and lifecycle. Functions are bounded and deterministic; they do not receive network, database, key, clock, or state transition authority. Controllers reconcile external systems from durable Core facts and return observations or attestations. Shared governance invariants apply across families, while domain managers, business contracts, and lifecycle semantics remain small, typed, and domain specific. New extension points are deliberate and domain scoped, with an owner, schema, authority boundary, failure semantics, idempotency, recovery, tests, and a removal plan. There is no global named hook bus, mutable runtime registry, or universal Core service locator. Target platform model under review The Draft Composable Extension Platform RFC organizes the long term target as: Shared invariants cover identity, contract version, scope, provider binding, stable reasons, and audit. Payment, order resource, and future domain managers apply those invariants through their own admission, runtime, recovery, and business semantics. Core alone decides whether an input may change Core owned state. This is not one central control plane service or universal ModuleManager . Do not collapse these independent dimensions into one plugin taxonomy: Dimension Examples Packaging Module Business domain Payment, order resource, inventory, fulfillment, tax, notification Contract role Port, Function, Controller, typed domain contract Output authority Declaration, decision, observation, attestation Interaction Synchronous call, durable event, reconciliation Runtime Static in process, isolated process or remote, Wasm Trust First party, reviewed partner, untrusted Artifact lifecycle Discovered, verified, rejected Provider runtime lifecycle Starting, ready, degraded, draining, stopped Capability exposure Allowed, configured, advertised, blocked Work lifecycle Reserved, funded, delivering, reconciling, completed Data ownership Core, module, or external system This model is a Draft direction, not evidence that every domain manager gate or runtime is currently available. Keep capability families domain specific Payment is a Core owned bounded context. Escrow, directly observed payment, and provider checkout sessions may use different adapters, but payment, refund, dispute, and settlement state remains in Core. OrderExtension binds an order associated resource or multi stage domain process through only the declarat" }, { "id": "reference", "path": "/reference", "canonical_url": "https://docs.mobazha.org/reference", "title": "Reference and source map", "summary": "Find the public knowledge authority, runtime authority, contract, and implementation evidence before proposing or automating a change.", "status": "current", "audiences": [ "developers", "contributors", "agents" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/reference", "label": "Reference and source map" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha GitHub organization" }, "reviewed": "2026-07-04", "page_type": "hub", "outcome": "Find the authority that owns a public explanation, runtime fact, versioned contract, or implementation claim.", "estimated_time": "3 minutes", "journey": "build", "primary_action": { "label": "Review authority ownership", "href": "/reference#authority-ownership" }, "language": "en", "search_text": "Authority ownership mobazha/mobazha docs: canonical public knowledge, project policy, user guidance, cross repository explanations, RFCs, project ADRs, and history. mobazha/mobazha: community backend, generated contracts, deployment, code near architecture, conformance, and Node release notes. mobazha/mobazha unified: public cross platform client implementation, package and feature design, runtime capability handling, and client release notes. mobazha/mobazha.org: public website, positioning, and high level disclosures. An evidence link supports a canonical docs page but does not become a second public policy source. The connected backend, transaction records, generated contracts, and tagged releases remain more specific authorities for runtime and versioned facts. Internal Hosting plans, credentials, operational playbooks, forecasts, and unapproved commercial experiments are not public documentation sources. Public repositories Mobazha Node Mobazha Unified Mobazha website Mobazha documentation" }, { "id": "project", "path": "/project", "canonical_url": "https://docs.mobazha.org/project", "title": "Understand the Mobazha project", "summary": "Separate what ships now from project principles, reviewed policy, historical proposals, and long-term direction.", "status": "current", "audiences": [ "everyone", "contributors", "evaluators" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project", "label": "Understand the Mobazha project" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public repositories and project records" }, "reviewed": "2026-07-06", "page_type": "hub", "outcome": "Distinguish current policy, release evidence, proposals, decisions, and history before relying on a project claim.", "estimated_time": "5 minutes", "journey": "understand", "primary_action": { "label": "Find the right explanation", "href": "/project#start-with-the-question-you-need-answered" }, "language": "en", "search_text": "Start with the question you need answered Question Start here What is Mobazha and how do stores, markets, channels, and Agents relate? Product map Which systems handle a request, where does state live, and which one is authoritative? System architecture How does an order move through payment, fulfillment, and recovery? Transaction spine What will I pay, who receives it, and how do refunds affect charges? Fees and pricing What is actually available in the current release? Release scope Why is Mobazha being built and what principles guide it? Founding whitepaper How can policy or architecture change? Governance, RFCs, and ADRs The first four pages form the main explanatory spine: product model, system model, transaction model, and money model. Release scope then separates current evidence from future direction. How the knowledge groups are classified Left navigation group Purpose Reading logic Product model Explain the durable objects and relationships a user encounters Overview → who operates → what is offered → how trade advances → where demand connects → which channels present it → how Agents automate it Product foundations Explain the system and operating rules beneath that model Architecture → fees → compatibility → packaging and distributions Vision & direction Explain why Mobazha exists and which outcomes it is trying to prove Versioned whitepaper → evidence gated roadmap Trust & governance Establish what can be relied on and how public rules change Security, legal, release scope, governance, decisions, RFCs, ADRs, history, and releases The desktop header uses broader user intent: Buy & sell, Operate, Build, Product, Project, Community . Product covers the first three explanatory groups above. Project covers Trust & governance. The Mobazha Docs logo returns to the Start surface. Current authorities and records Product map Independent commerce units, transaction authority, product surfaces, and optional dependencies. System architecture Request flow, deployment topology, authority, dependencies, and failure boundaries. Transaction spine Order, payment, fulfillment, completion, and recovery as one inspectable journey. Fees and pricing Buyer total, seller proceeds, service charges, external costs, and economic boundaries. Release scope Current release boundary and explicit exclusions. Founding whitepaper Versioned public review of durable principles. Compatibility Wire, capability, version, migration, and conformance policy. Distribution OEM, appliance, and VPS packaging boundaries. Public roadmap Product outcomes separated from implementation plans. Public decisions and proposals RFC, ADR, and history lifecycle. Releases Published release maturity and evidence." }, { "id": "project-architecture", "path": "/project/architecture", "canonical_url": "https://docs.mobazha.org/project/architecture", "title": "How Mobazha systems and store networks fit together", "summary": "Compare direct peer-to-peer and hybrid store networks, then follow a request to the backend that owns store and transaction state.", "status": "beta", "audiences": [ "buyers", "sellers", "operators", "developers", "evaluators", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/architecture", "label": "How Mobazha systems and store networks fit together" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public product, Node, runtime, and distribution contracts" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Distinguish direct peer-to-peer and hybrid store networks, identify which backend owns each decision, and trace authority across surfaces and services.", "estimated_time": "10 minutes", "journey": "understand", "primary_action": { "label": "Compare the two topologies", "href": "/project/architecture#read-the-topologies" }, "featured_visual": { "id": "store-network-topologies", "src": "/images/docs/project/store-network-topologies.svg", "sha256": "5e26e8371ceff4a149019affbf4a2b3a2af3d6cc87465fd85001912ba19d5cb5", "mobile_src": "/images/docs/project/store-network-topologies-mobile.svg", "mobile_sha256": "9ec0813528f18df943a0ab0ef0efbac3143c8e6cf94cbad6a61b6be7cc5d63da", "kind": "conceptual", "width": 760, "height": 640, "mobile_width": 360, "mobile_height": 1040, "alt": "Two Mobazha store network topologies. Direct peer-to-peer shows a buyer resolving one self-hosted seller Node while another store remains a separate peer. Hybrid shows independent and hosted stores coexisting, with Hosting routing only hosted context and optional providers remaining separate.", "caption": "Direct P2P and Hybrid change how a store is reached and operated; the selected seller backend still owns its store and orders.", "claim": "Explains durable network and authority boundaries. It does not assert direct transport for every request, order replication between peers, or availability of every optional service in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "store-network-topologies-v1", "applies_to": "Mobazha v0.3 release-candidate product and architecture model", "reviewed": "2026-07-06" }, "language": "en", "search_text": "Read the topologies Mobazha is peer to peer because independently operated store backends can participate in shared discovery, signed content, messaging, and commerce protocols without moving every store or order into one central platform database. It does not mean every buyer must run a Node, every request connects directly at the transport layer, or every peer receives a copy of every order. The selected seller backend is the stable authority boundary in both topologies: Question Direct P2P store network Hybrid store network Where does the store run? On a Node operated for that independent store On either an independently operated Node or a hosted Commercial Node How does a buyer reach it? A storefront, app, direct link, or Agent resolves the seller Node and requests the action The entry surface resolves seller context; a Hosting gateway routes hosted context, while independent context continues to its own Node What may cross the network? Published profiles and offers, discovery signals, messages, and explicit protocol requests The same public protocol relationships plus separately enabled hosted, index, payment, delivery, messaging, or automation services What does not spread by implication? Private store data, recovery material, credentials, and the authoritative order record Independent Node data and orders do not move into Hosting merely because the store uses a hosted channel or optional service Who decides whether an order changes state? The selected seller backend that created and owns that order The selected seller backend—independent or hosted—not the entry channel, gateway, index, or another peer Direct P2P describes independent Nodes as peers, not one shared database. Hybrid describes coexistence and bounded service composition, not a third kind of order owner. A store still has one active backend context for a given order. Choose hosted or self hosted operation Understand community markets and distributed discovery Check what the connected backend can do Use the right architecture view The topology deliberately does not place every actor, client, chain, contract, and Node component on one canvas. Those are different architectural dimensions. Combining them can make a possible integration look mandatory or make a shared service look authoritative. View Question it should answer Use this source Store network topology How do independent and hosted stores coexist, and which backend owns an order? The topology above and this page Transaction and protection flow How do buyer, seller, payment evidence, fulfillment, refund, dispute, and arbitration responsibilities interact? Orders, payments, and recovery and cancel, refund, or dispute Experience and channel topology How do Web, desktop, mobile, community, embedded, messaging, and Agent entry points reach the same commerce context? Channels and integrations Node composition How do Core services, local data, content storage, messaging, wallet, and provider adapters fit inside one backend? The six part model below, self hosting, and public implementation contracts Payment and settlement topology Which rail, wallet, provider, chain, escrow, or settlement controller applies to one order? Seller payments, the order bound Payment Session, runtime capabilities, and the applicable provider contract A named blockchain, smart contract, social client, hosted service, or arbitration mechanism belongs in a more specific view only when current capability and policy evidence supports it. Its appearance in a concept diagram must never imply universal availability. Where this page fits Mobazha can appear as a storefront, hosted application, self hosted Node, community market, direct link, API, or Agent workflow. Those are not separate explanations of the product. They are surfaces and operating paths around one commerce model. Use each overview for a different question: Page Question it answers Product map What are Mobazha's main product concepts and ways to use them? This" }, { "id": "project-fees", "path": "/project/fees", "canonical_url": "https://docs.mobazha.org/project/fees", "title": "What you pay and who receives it", "summary": "Read the buyer total, seller proceeds, service charges, external costs, and refund rules without hiding them inside one vague commission number.", "status": "current", "audiences": [ "buyers", "sellers", "operators", "evaluators", "agents" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/fees", "label": "What you pay and who receives it" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Mobazha public fee policy, quote requirements, and release evidence" }, "reviewed": "2026-07-06", "page_type": "policy", "outcome": "Determine what an order or service costs, who pays and receives each amount, when the amount becomes binding, and how cancellation or refund changes it.", "estimated_time": "9 minutes", "journey": "understand", "primary_action": { "label": "Read a fee quote", "href": "/project/fees#read-a-fee-quote" }, "language": "en", "search_text": "Where this page fits This page defines how Mobazha fees and costs must be explained. It is not a price list and does not invent a rate for a particular hosted plan, payment rail, seller, or transaction. Need Source to use Understand the durable fee and disclosure rules This page See currently published hosted plans or service prices Mobazha pricing and fees Know the exact total and recipients for one order The final Fee Quote or equivalent checkout quote accepted before payment Understand item, delivery, payment, and order state Checkout guide and transaction spine Understand long term economic principles Founding whitepaper Direct answers Does every Mobazha order pay a central commission? No. Running the Community software on infrastructure you control does not by itself create a mandatory Mobazha transaction fee. Does open source mean everything is free? No. Servers, storage, payment networks, providers, delivery, plugins, AI, support, taxes, and optional managed services have real costs. Does Hybrid use mean paying both a platform commission and self hosting costs? No. Hybrid names a composition, not a fee category. The operator pays its own infrastructure plus only the separately accepted services and external costs it actually uses. Is every deduction a Mobazha fee? No. The recipient may be the seller, carrier, blockchain network, payment provider, tax authority, operator, referrer, or another named service. When should the buyer know the total? Before final confirmation and before funds are committed. A later screen should not silently add a new required charge. When should the seller know net proceeds? Before accepting the applicable service or order terms, including seller paid charges and refund treatment. Can a seller, market, operator, or Agent earn a fee? Yes, where lawful and explicitly funded, attributable, capped, disclosed, and handled correctly after refunds or fraud. Where are current rates? On the applicable provider or service pricing surface and in the transaction quote—not in an old screenshot, discussion, or illustrative percentage. Read a Fee Quote The Fee Quote keeps the buyer payment and seller proceeds separate. The current Deal Link code path uses a bootstrap policy named pilot zero fee v1 : with a $100.00 offer, its platform authored buyer total and estimated seller net are both $100.00, and acceptance rejects shipping, tax, discount, or other non zero components that are absent from that quote. The policy name describes a current implementation constraint while pricing is undecided; it is not an approved Deal Link rate, zero fee promise, or permanent commercial policy . The following hypothetical quote is deliberately non zero so the funding direction is visible. It is not a current Mobazha rate, tax determination, or offer . In this scenario the buyer funds delivery and an applicable tax, while the seller funds the managed transaction service and payment cost: Line Buyer total effect Seller proceeds effect Recipient or treatment Item or service +$100.00 +$100.00 gross Seller Delivery +$8.00 +$8.00 collected, −$8.00 fulfillment obligation Seller or merchant collects it with the order and pays the applicable fulfillment cost Applicable tax +$5.00 +$5.00 collected, −$5.00 tax obligation Seller or merchant collects it with the order; current settlement does not automatically remit it to a tax authority Managed transaction service — −$2.00 Named operator providing the disclosed service Payment or settlement cost — −$1.00 Named payment provider or network Illustrative result Buyer total: $113.00 Estimated seller economic proceeds: $97.00 Delivery and tax are treated as collected obligations rather than seller income in this example The arithmetic demonstrates two different directions: buyer funded lines increase the amount approved at checkout, while seller funded lines reduce proceeds from the $100.00 gross order amount. A real quote may allocate them" }, { "id": "project-compatibility", "path": "/project/compatibility", "canonical_url": "https://docs.mobazha.org/project/compatibility", "title": "Will these Mobazha components work together?", "summary": "Check client, backend, contract, capability, extension, data, and distribution compatibility before connecting systems or upgrading a store.", "status": "current", "audiences": [ "sellers", "operators", "developers", "distributors", "agents" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/compatibility", "label": "Will these Mobazha components work together?" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Node public contracts, runtime capabilities, migrations, and conformance sources" }, "reviewed": "2026-07-06", "page_type": "policy", "outcome": "Decide whether two Mobazha components can safely exchange data and preserve business meaning, then identify the evidence required before deployment.", "estimated_time": "9 minutes", "journey": "understand", "primary_action": { "label": "Run the compatibility check", "href": "/project/compatibility#quick-compatibility-check" }, "language": "en", "search_text": "Where this page fits Compatibility is narrower than product architecture and broader than “the request returned JSON.” Use the surrounding pages for different questions: Question Source Which system owns the request or state? System architecture What can the connected backend do now? Runtime capabilities What exact HTTP operation or schema exists? API and OpenAPI Is the feature part of the current release? Release scope Can these versions and components safely work together? This page and the applicable release evidence Direct answers The client and backend both recognize the same field name. Are they compatible? Not necessarily. Authorization, state meaning, idempotency, confirmation, recovery, and failure behavior are also part of the contract. An adapter exists in source. Can a client use it? Only when the distribution includes it, the contract version matches, the operator authorizes and configures it, dependencies are healthy, and the backend advertises the effective capability. Can a newer client connect to an older Node? Only within the versions and additive behavior tested by that client. It must fail closed when required schema or capability information is missing. Can hosted and self hosted stores use the same clients and integrations? They may share public contracts, but authentication, deployment composition, enabled capabilities, external services, and operating responsibility can differ. Does a successful happy path test prove compatibility? No. Conflicts, retries, duplicate events, timeouts, old data, migrations, downgrade, and recovery paths also matter. Quick compatibility check Before connecting or upgrading two components, answer all seven questions: Identity: Which exact client, backend, package, adapter, or distribution versions are involved? Contract: Which generated HTTP, event, webhook, MCP, extension, or data contract do both sides claim? Capability: Does the connected backend advertise the required effective capability as ready? Authorization: Does the current identity have the required role, scope, store context, and permission? Semantics: Do both sides agree on state transitions, amounts, identifiers, idempotency, finality, and recovery? Migration: Can existing data, configuration, credentials, and provider bindings be upgraded and restored safely? Evidence: Is there a conformance, integration, or release test covering this exact combination? If any answer is unknown, the combination remains unverified even when it compiles or renders. Compatibility surfaces Surface What must remain compatible Evidence to inspect HTTP API Methods, paths, schemas, envelopes, authentication, stable errors, idempotency, and state effects Generated OpenAPI, negative tests, release notes Events and WebSocket Event identity, payload version, ordering assumptions, reconnect behavior, and refresh semantics Event contract, duplicate and reconnect tests Webhooks Signature, delivery identity, retries, deduplication, payload version, and reconciliation Webhook contract, delivery history, consumer tests Runtime configuration Schema version, readiness, deployment profile, feature and capability meaning /v1/runtime config , client resolver tests Commerce state Order, payment, fulfillment, refund, dispute, settlement, and protection meanings State machine and transaction conformance tests Identifiers Canonical asset, chain, payment, store, order, and capability identity Public identifier contract and normalization tests Extensions and packages Supported public port, module, function, controller, or out of process protocol Versioned package contract and composition tests Persisted data Schema migration, retained provider bindings, backup, restore, rollback, and export Migration tests, restored representative data Database internals, concrete constructors, private hooks, composition root details, and code reachable through an internal import are not public compatibility promises. Commo" }, { "id": "project-distribution", "path": "/project/distribution", "canonical_url": "https://docs.mobazha.org/project/distribution", "title": "How Mobazha can be packaged and operated", "summary": "Compare source-built Nodes, hosted services, standalone packaging, and third-party appliances without confusing packaging with capability or official status.", "status": "current", "audiences": [ "sellers", "operators", "distributors", "security reviewers", "evaluators", "agents" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/distribution", "label": "How Mobazha can be packaged and operated" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/deploy/standalone", "label": "Standalone packaging, distribution policy, release, and supply-chain checks" }, "reviewed": "2026-07-06", "page_type": "policy", "outcome": "Choose or publish a Mobazha distribution while preserving capability truth, secure first run, user control, recovery, licensing, and honest branding.", "estimated_time": "10 minutes", "journey": "understand", "primary_action": { "label": "Compare distribution forms", "href": "/project/distribution#distribution-forms" }, "language": "en", "search_text": "Where this page fits A distribution is a tested assembly of Mobazha Core, adapters, frontend, configuration, packaging, update channel, and operating assumptions. It is not a new commerce protocol merely because it has a different installer, brand, host, or feature set. Question Source Should I use hosted or self hosted operation? Choose a deployment Which systems own state and dependencies? System architecture Is this package allowed and honestly described? This page Is the artifact ready and compatible? Release scope, release evidence, and compatibility How do I install and recover a Node? Self host guide Distribution forms Form Who operates it? Current meaning Main responsibility Community source build Independent seller or operator Public release candidate source can be built and evaluated on supported environments Host, secrets, network, data, backup, updates, integrations, and incident response Mobazha hosted service Mobazha or the named hosted operator A Beta service operates the applicable commercial distribution and managed infrastructure Service terms, availability, tenant isolation, data handling, pricing, export, and support Standalone installer or launcher Independent operator after installation Packaging and update mechanisms may exist in pre release form; stable signed artifacts require release evidence Artifact integrity, first run, update approval, rollback, and local recovery Container, VPS image, or appliance Independent distributor or operator Permitted packaging when licenses, security, capability, provenance, and recovery rules are preserved Secure image construction, disclosures, updates, support, and source obligations Branded or vertical distribution Its named operator May select a profile, brand, integrations, and service bundle without creating new Core authority Honest branding, compatible contracts, explicit local features, and no false official claim The current v0.3 line is intended for evaluation and testnet use. Packaging source or an installation script does not prove that stable signed binaries, automatic updates, or production support have been released. What may differ and what must not A distribution may choose A distribution must preserve Hosted or self hosted operating model Order owning backend and Core state authority Included public adapters and build time features Effective capability discovery and fail closed behavior Store, marketplace, embedded, or vertical presentation Backend authorization and protected state transitions Brand, domain, theme, support, and pricing Honest provider, payer, recipient, data, and responsibility disclosure Infrastructure providers and update channel Artifact provenance, secret safety, backup, restore, export, and rollback Distribution local features Public contract compatibility and clear separation from Mobazha project policy A frontend switch, bundled adapter, or product name cannot widen what the backend safely implements. A distributor may add services, but it must name the provider and must not hide external dependencies or move financial authority into presentation code. Choose a distribution as a user Before trusting a package or hosted service, ask: Who publishes and operates it, and is it claiming to be official? Which exact Mobazha version, source revision, capability manifest, and frontend does it contain? Which services are local, hosted, third party, optional, or required? Where are store data, identity keys, payment credentials, and recovery material held? How are first run credentials generated, updates verified, backups created, data exported, and failures rolled back? Which fees, limits, support terms, and external endpoints apply? What happens to the store and existing orders if the distributor or an optional service disappears? If the publisher cannot answer those questions, the convenience of an installer does not establish trust. Requirements for distributors Build and provenance Record the exact source commit or tag, build inp" }, { "id": "project-whitepaper", "path": "/project/whitepaper", "canonical_url": "https://docs.mobazha.org/project/whitepaper", "title": "Mobazha Founding Whitepaper", "summary": "The v0.2 public discussion draft for an open commercial network in the AI era, independent operating units, accountable participation, and sustainable shared capability.", "status": "draft", "audiences": [ "community", "contributors", "evaluators" ], "applies_to": "Design direction; not a shipped guarantee", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/whitepaper", "label": "Mobazha Founding Whitepaper" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/blob/main/content/en/project/whitepaper.md", "label": "Versioned Mobazha v0.2 public discussion edition" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Understand Mobazha's proposed open commercial network, operating-unit model, economic loops, participation principles, and current validation sequence.", "estimated_time": "22 minutes", "journey": "understand", "primary_action": { "label": "Read the executive summary", "href": "/project/whitepaper#0-executive-summary" }, "version": "0.2-discussion", "language": "en", "search_text": "Publication status Version 0.2 is a public discussion draft. It states principles and direction; it is not a fundraising, Token, return, ownership, or shipped feature commitment. The whitepaper belongs to Vision & direction . It explains why Mobazha is being built and the durable principles the project wants to test. It is not the system architecture, current capability list, fee schedule, or release contract. Use the Product overview for the current product model Use System architecture for runtime and authority boundaries Use Fees and pricing for current economic policy and quote rules Use Release scope for current availability and maturity 0. Executive Summary AI is distributing software, content, analysis, and execution capabilities that were once available only to large organizations. Yet widely available productive capacity does not automatically create access to markets, trust, payments, distribution, or durable business opportunity. A person may use an agent to accomplish more work and still be unable to find demand, earn trust, complete a cross border sale, manage a dispute, or retain the commercial relationships they have built. Mobazha aims to build an open commercial network that independent participants use and progressively help build. Individuals, creators, small teams, and agents can transact under shared rules, create stores, operate markets, build tools, and develop verifiable records of fulfillment and participation. Building together begins with independent operation. Participants may run their own stores, markets, services, or tools, and may also create capabilities that other operating units reuse. Shared infrastructure connects these units; it does not replace their brands, customer relationships, responsibility boundaries, or freedom to exit. Mobazha seeks to lower the cost of this combination of independence and cooperation. Not every form of participation automatically creates economic value. Only actions that improve real transactions, operating outcomes, risk management, or public capabilities may be rewarded, and only under clear rules with a real source of funds. Mobazha will not manufacture prosperity through registration counts, relationship position, token prices, or promises about the future. It will test itself through real demand, real fulfillment, and sustainable revenue. 1. Productive Capacity Is Opening Up, While Commercial Opportunity Remains Concentrated Large companies in the industrial and internet eras concentrated capital, talent, software, distribution, payments, data, and organizational capacity within a single boundary. Scale lowered coordination costs, but also made many commercial opportunities available only through a corporate role or a platform's permission. AI is lowering execution costs and the minimum effective team size. Individuals and small teams can design, develop, translate, review, market, and serve customers more quickly. This does not mean large platforms will naturally decline. They still possess user networks, brands, data, payments, logistics, capital, and compliance capacity, and can use AI to strengthen those advantages. The core problem is not whether individuals can produce. It is whether: productive capacity can connect to real demand; unfamiliar participants can establish trust with accountable responsibility; small operators can use commercial infrastructure once affordable only to large companies; people who build markets, bring demand, maintain tools, and manage risk can receive intelligible rewards; and participants can accumulate long term commercial capability without depending on one company or platform. Mobazha's opportunity does not rest on an assumption that any company must decline. It rests on a different structural possibility: as general purpose productive capacity becomes more widely available, an open network can allow more commercial surplus to remain with the people who actually create demand, supply, trust, and capability. 2. Value" }, { "id": "project-roadmap", "path": "/project/roadmap", "canonical_url": "https://docs.mobazha.org/project/roadmap", "title": "What Mobazha is proving next", "summary": "Follow the product outcomes Mobazha is validating now, the evidence required to advance them, and the ideas that remain exploration rather than promises.", "status": "draft", "audiences": [ "users", "contributors", "operators", "developers", "evaluators", "agents" ], "applies_to": "Design direction; not a shipped guarantee", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/roadmap", "label": "What Mobazha is proving next" }, "evidence": { "source": "https://github.com/mobazha", "label": "Public release scope, repository milestones, audits, and reviewed product roadmaps" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "Understand what the project is trying to prove next, why each outcome matters to users, and what evidence must exist before direction becomes a release commitment.", "estimated_time": "8 minutes", "journey": "understand", "primary_action": { "label": "Review the current proof", "href": "/project/roadmap#the-current-proof" }, "language": "en", "search_text": "Where this page fits The roadmap describes desired user and product outcomes. It is not a list of every feature under discussion, a delivery calendar, or evidence that a capability exists. Need Source What is available in the current release? Release scope and the connected backend Why is Mobazha being built? Founding whitepaper What outcome is the project trying to prove next? This roadmap What exact change is proposed or accepted? RFCs, ADRs, and decisions What implementation work is active? Public repository issues, projects, tests, and release notes No date or item on an internal plan becomes a public commitment unless it is accepted, implemented, tested, documented, and released. The current proof The immediate goal is not feature count. It is a trustworthy release candidate loop that different users can complete and verify: User Outcome to prove Evidence of success Buyer Understand the seller, final total, payment instruction, order state, and recovery path One complete test order with inspectable quote, Payment Session, fulfillment, and recovery state Seller Configure a recognizable store, publish an offer, receive payment evidence, fulfill, and support the order Repeatable store to order operation without hidden administrator repair Operator Run or provide a healthy, secure, recoverable backend Diagnostics, monitoring, backup restore, upgrade decision, and incident ownership Developer or Agent builder Discover capability, authenticate narrowly, call public contracts, and reconcile unknown outcomes Versioned contract tests covering denial, retry, duplicates, conflicts, and recovery Evaluator Distinguish current behavior, optional services, fees, dependencies, and future direction Public release, policy, compatibility, and source evidence that agree Until this loop is dependable, a broader marketplace, additional rails, or more automation increases surface area without proving the core value. Near term outcome lanes Outcome lane User problem being solved Evidence required to advance Buyer and seller journey Important state and recovery information is fragmented or ambiguous Tested desktop and mobile journeys with clear totals, payment progress, fulfillment, refund, and dispute behavior Standalone operation Installation is easier than safe long term operation Signed release evidence, secure first run, monitoring, backup restore, migration, rollback, and support guidance Hosted and independent consistency Product behavior can drift across compositions Shared contracts, runtime capability truth, cross distribution conformance, and explicit service differences Payment and protection clarity A payment event, verified payment, order state, settlement, and buyer protection are easily confused Order bound Payment Sessions, rail specific recovery, auditable state transitions, and honest terms Public integration surfaces API, events, webhooks, MCP, extensions, and Agents can imply more authority than they have Scoped credentials, stable contracts, idempotency, capability gates, approval, and failure tests Store and distribution quality A published listing is not yet a complete commercial experience Better identity, storefront, fulfillment, visibility, accessibility, internationalization, and operator evidence Release trust Source presence is mistaken for supported availability Checksums, provenance, SBOM, compatibility, migration, known issues, and release linked documentation These lanes can progress in parallel, but none should bypass the applicable security, economic, legal, capability, and release gates. Exploration that remains gated Exploration area Potential value What must be proven first Richer community markets and verticals Connect focused demand and independent supply Operator responsibility, moderation, discovery quality, attribution, and sustainable unit economics Deal Links and embedded or social entry Shorten the path from known demand to an attributable order Immutable seller and quote binding, privacy, channel co" }, { "id": "project-security", "path": "/project/security", "canonical_url": "https://docs.mobazha.org/project/security", "title": "Project security model", "summary": "Security depends on explicit authority, fail-closed capabilities, protected signing material, hostile-input assumptions, and private disclosure.", "status": "beta", "audiences": [ "operators", "developers", "security reviewers", "evaluators" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/security", "label": "Project security model" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/SECURITY.md", "label": "Mobazha public security sources" }, "reviewed": "2026-07-04", "page_type": "policy", "outcome": "Understand the project security boundary and route a suspected vulnerability through private reporting.", "estimated_time": "6 minutes", "journey": "understand", "primary_action": { "label": "Review security reporting", "href": "/project/security#security-reporting" }, "language": "en", "search_text": "Trust boundaries The backend that owns an order is authoritative for its state and protected transitions. The client is untrusted input and a presentation layer; hiding a control never replaces server authorization. Payment rails, RPCs, indexers, plugins, webhooks, media, and delivery systems are external dependencies with their own failure and threat models. Extensions receive minimum typed projections and scoped handles, not general database or Core access. Sensitive actions remain auditable without placing secrets or unnecessary personal data in logs. Release and supply chain The current release is a pre release candidate. Final artifacts require vulnerability scanning, dependency and license review, SBOM generation, checksums, provenance, reproducibility evidence, secret scans, and platform specific validation. Node supply chain audit Unified supply chain audit Operator security Security reporting Use the affected repository's GitHub private vulnerability reporting. Do not publish exploit details, leaked credentials, signing key concerns, or customer data in issues, chat, or documentation feedback." }, { "id": "project-legal-and-privacy", "path": "/project/legal-and-privacy", "canonical_url": "https://docs.mobazha.org/project/legal-and-privacy", "title": "Legal, privacy, license, and trademark boundaries", "summary": "Separate software licenses, hosted-service terms, privacy commitments, third-party obligations, and trademark rights.", "status": "current", "audiences": [ "users", "operators", "contributors", "evaluators" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/legal-and-privacy", "label": "Legal, privacy, license, and trademark boundaries" }, "evidence": { "source": "https://mobazha.org/terms", "label": "Mobazha public policies and repository notices" }, "reviewed": "2026-07-04", "page_type": "policy", "outcome": "Identify which license, terms, privacy notice, trademark rule, and operator obligation applies to a specific deployment.", "estimated_time": "8 minutes", "journey": "understand", "primary_action": { "label": "Determine which document applies", "href": "/project/legal-and-privacy#which-document-applies" }, "language": "en", "search_text": "Which document applies Repository LICENSE, NOTICE, attribution, and third party notices govern source use and redistribution. Mobazha.org Terms and Privacy Policy govern the current hosted service as described there. An independent operator is responsible for its own terms, privacy disclosures, lawful products, taxes, data handling, and service providers. The source code license does not grant rights to Mobazha names, logos, or visual identity; consult the trademark policy. A transaction specific quote and seller policy may add applicable terms but cannot silently override project wide public boundaries. Canonical public links Terms of Service Privacy Policy Fees and Paid Services Node license Node attribution Trademark policy Documentation boundary This page is navigation and product explanation, not legal advice. When documents conflict, use the effective policy or license from its owning public source and report the inconsistency." }, { "id": "project-release-scope", "path": "/project/release-scope", "canonical_url": "https://docs.mobazha.org/project/release-scope", "title": "Release scope and maturity", "summary": "The documentation distinguishes current release-candidate behavior from previews and future design.", "status": "beta", "audiences": [ "everyone" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/release-scope", "label": "Release scope and maturity" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/docs/releases", "label": "Mobazha releases and repository documentation" }, "reviewed": "2026-07-06", "page_type": "policy", "outcome": "Separate current v0.3 release-candidate behavior from stable guarantees, optional composition, proposals, and future targets.", "estimated_time": "8 minutes", "journey": "understand", "primary_action": { "label": "Review the current release boundary", "href": "/project/release-scope#current-v0-3-release-candidate-boundary" }, "language": "en", "search_text": "Status vocabulary Current: reviewed public policy or stable project fact. Beta: available or being validated; compatibility and behavior may change. Draft: proposal or documentation contract; do not depend on it as shipped behavior. Historical: retained for context and explicitly superseded. Current v0.3 release candidate boundary Mobazha Node and Mobazha Unified are release candidates for evaluation and testnet use. The default open source Node enables BTC, BCH, and LTC payment methods, subject to effective runtime capabilities and seller configuration. Identifiers or adapters present in source do not enable a payment method or create a compatibility commitment. Stable signed binaries and reproducibility attestations remain pending final release approval. Clients must fail closed when a valid runtime capability snapshot is unavailable. English is the default repository documentation language unless a maintained translation is explicitly identified. Community capability manifest Machine readable release evidence. Node v0.3.0 rc.1 notes Unified v0.3.0 rc.1 notes Reliance guide Question Current answer What to verify Can I evaluate the open source Node? Yes, from reviewed public source on a supported environment Exact commit, build prerequisites, testnet profile, diagnostics, and backup Can I use the hosted application? Yes, as a Beta service Current terms, privacy, pricing, service status, and deployment capabilities Are BTC, BCH, and LTC always available? No. They are in the default release boundary, but effective availability remains conditional Runtime capability, seller configuration, dependency health, quote, and payment instruction Is every API or UI element a supported feature? No Generated contract, runtime capability, authorization, configuration, and release notes Are stable installers and unattended updates a current guarantee? No Signed artifact, checksum, provenance, platform validation, rollback, and final release notice Is optional Node to account binding stable? No; its public contract remains Draft Published permissions, exchanged data, revocation, tests, and version compatibility For material use, require a tagged release and its evidence rather than inferring readiness from a main branch, screenshot, design document, or feature name. What remains version specific Exact checksums, artifacts, known issues, migration steps, SBOMs, provenance, and implementation commits belong to each tagged repository release. This page governs shared maturity language and the current public boundary; it does not replace release evidence." }, { "id": "project-governance", "path": "/project/governance", "canonical_url": "https://docs.mobazha.org/project/governance", "title": "Documentation and policy governance", "summary": "Important project claims need an owner, source, review date, status, and visible change path.", "status": "draft", "audiences": [ "contributors", "maintainers", "agents" ], "applies_to": "Design direction; not a shipped guarantee", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/governance", "label": "Documentation and policy governance" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/GOVERNANCE.md", "label": "Mobazha public governance and documentation policy" }, "reviewed": "2026-07-04", "page_type": "policy", "outcome": "Identify the review and publication path required for a policy, contract, release, documentation, or implementation change.", "estimated_time": "8 minutes", "journey": "understand", "primary_action": { "label": "Classify the change", "href": "/project/governance#change-classes" }, "language": "en", "search_text": "Change classes Editorial: clarifies wording without changing behavior or policy. Operational: changes installation, recovery, compatibility, or integration guidance. Policy: changes rights, responsibilities, fees, governance, privacy, or security expectations. Protocol: changes interoperable behavior, state transitions, or machine contracts. Review expectation Project wide public policy and explanation change in this repository. Operational and protocol implementations change in their owning repositories and must update affected documentation, machine readable indexes, tests, contracts, and release notes. Neither layer silently overrides runtime state or a versioned interface contract. Documentation publication workflow Wave 0 inventories authorities, public sources, lifecycle states, and stable URLs. Wave 1 keeps the portal, compatibility routes, source mapping, link checks, and deployment healthy. Wave 2 turns implementation and public contracts into task first user, operator, and developer guidance. Wave 3 publishes reviewed trust, security, economic, governance, ADR, RFC, and whitepaper material. Wave 4 evaluates Agent answers, adds maintained translations, and measures freshness and support outcomes. Phase DOCS roadmap Public delivery waves, gates, and progress record. Content governance Authority, source, lifecycle, and review rules." }, { "id": "project-decisions", "path": "/project/decisions", "canonical_url": "https://docs.mobazha.org/project/decisions", "title": "Public decisions and proposals", "summary": "Use RFCs for changes still being evaluated, ADRs for decisions already made, and history records for superseded public material.", "status": "current", "audiences": [ "contributors", "maintainers", "agents", "evaluators" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/decisions", "label": "Public decisions and proposals" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/blob/main/docs/CONTENT_GOVERNANCE.md", "label": "Mobazha documentation decision process" }, "reviewed": "2026-07-04", "page_type": "hub", "outcome": "Choose an RFC, ADR, policy page, release note, or history record for the decision you need to propose or inspect.", "estimated_time": "5 minutes", "journey": "understand", "primary_action": { "label": "Choose the record type", "href": "/project/decisions#choose-the-right-record" }, "language": "en", "search_text": "Choose the right record RFC: a substantial public proposal that still needs review, evidence, or a decision. ADR: a durable architecture or product decision, including context, alternatives, consequences, and supersession. History record: a replaced or withdrawn public statement retained so old links and discussions remain interpretable. Task documentation: instructions and explanations derived from current authorities; it is not a substitute for a decision record. Lifecycle rules A Draft or Review RFC is not shipped behavior. An Accepted RFC authorizes implementation work but does not prove implementation or release. An ADR records a decision; runtime behavior still requires implementation, tests, capability gates, and release evidence. A superseded record remains readable and links to its replacement. Security sensitive details, credentials, private operations, customer data, forecasts, and unapproved commercial assumptions do not enter public records. Start or inspect a record RFC index Proposals, review state, and the RFC template. ADR index Accepted decisions and the ADR template. History and supersession Rules for preserving replaced public material. Documentation governance Change classes, ownership, and publication workflow. A record's status must remain explicit. Agents and readers must not infer availability from a proposal, an accepted design, or code presence alone." }, { "id": "project-rfcs", "path": "/project/rfcs", "canonical_url": "https://docs.mobazha.org/project/rfcs", "title": "Requests for Comment", "summary": "Review substantial protocol, policy, economic, security, governance, and cross-repository proposals before treating them as commitments.", "status": "current", "audiences": [ "contributors", "maintainers", "evaluators", "agents" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/rfcs", "label": "Requests for Comment" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/tree/main/rfcs", "label": "Public Mobazha RFC registry" }, "reviewed": "2026-07-13", "page_type": "hub", "outcome": "Find or start a public proposal without presenting Draft design direction as accepted or shipped behavior.", "estimated_time": "5 minutes", "journey": "understand", "primary_action": { "label": "Open the RFC registry", "href": "/project/rfcs#current-registry" }, "language": "en", "search_text": "When an RFC is required A public protocol or interoperability contract changes. Order, payment, settlement, dispute, identity, authorization, or custody boundaries change. A fee, recipient, reward, public fund, or economic policy changes. A new optional hosted dependency changes independent operation assumptions. Governance, licensing, privacy, security, or cross repository ownership changes materially. Status model Draft: authoring is incomplete. Review: ready for public technical and product review. Accepted or Rejected: the decision is recorded with rationale. Withdrawn: the author no longer proposes the change. Superseded: another RFC replaces the proposal. Implemented: release evidence confirms that the accepted proposal shipped within a stated scope. Current registry RFC 0001: Founding whitepaper publication contract Review; defines the evidence and approvals needed to advance the whitepaper. RFC 0002: Composable Extension Platform Model Draft; separates domain, contract role, runtime, trust, lifecycle, and packaging while defining the target multi runtime platform. RFC 0003: Composable Frontend Product Model Draft; separates deployment, experience, channel, code inclusion, and effective capability so public and private distributions can assemble coherent products without product name branching. RFC 0004: Deal Link Single Level Attribution Superseded by RFC 0007; retained as the earlier manual review only proposal. RFC 0005: Core owned Resource Collateral Lifecycle Draft; proposes a separate Core owned collateral aggregate without merging collateral into Order Extension or order settlement state. RFC 0006: Payment Kernel, Rails, and Trusted Distribution Modules Draft; proposes typed payment rails, reviewed module composition, contribution level routing, and durable payment recovery boundaries. RFC 0007: Seller funded Affiliate Attribution and Atomic Settlement Draft; proposes seller funded Affiliate outputs in the canonical order release without a second payout engine or commission balance. RFC 0008: Node Key Domains and Receiving Architecture Draft; proposes separate Identity, Wallet, and Settlement domains, generic receiving destinations, and a production gate for order authorization keys. RFC 0009: Frozen Payment Attempt Settlement Terms Draft; proposes freezing seller payout, platform and cancellation fees, Affiliate and moderator terms, escrow timeout, and dispute policy into the immutable payment attempt before a funding target is payable. RFC 0010: Guest Checkout Trust and Custody Model Draft; proposes seller custodied Guest Checkout, a strict per chain closure gate, an order scoped access credential, and buyer disclosure rules without introducing a separate Direct payment product. RFC 0011: Order Settlement Authorization Keys Draft; proposes deterministic hardened attempt scoped settlement keys for all order participants, Identity signed public key offers without private key exposure, and moderator selectability gated on obtaining a valid offer before payment. RFC 0012: Embedded Wallet Buyer Settlement Keys and Onramp Funded Attempts Draft; proposes a buyer vendor custodied participant key class for moderated escrow, admits embedded wallet providers as a reviewed trusted module class, and defines onramp funded attempts without changing the RFC 0010 guest custodial default or the RFC 0011 Settlement root key hierarchy. RFC template Required metadata and review questions. Repository RFC guide Accepted and Implemented are different states. Only release evidence and effective runtime capability can establish shipped availability." }, { "id": "project-adrs", "path": "/project/adrs", "canonical_url": "https://docs.mobazha.org/project/adrs", "title": "Architecture Decision Records", "summary": "Preserve why durable technical and product decisions were made, what alternatives were rejected, and what would supersede them.", "status": "current", "audiences": [ "contributors", "maintainers", "architects", "agents" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/adrs", "label": "Architecture Decision Records" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/tree/main/adrs", "label": "Public Mobazha ADR registry" }, "reviewed": "2026-07-04", "page_type": "hub", "outcome": "Find an accepted architectural decision and distinguish it from a proposal or repository-local implementation note.", "estimated_time": "5 minutes", "journey": "understand", "primary_action": { "label": "Open the ADR registry", "href": "/project/adrs#current-registry" }, "language": "en", "search_text": "What belongs in an ADR A long lived architecture, authority, ownership, compatibility, or publication decision. A choice whose rationale would otherwise be rediscovered repeatedly. A decision that affects more than one module, repository, deployment type, or public contract. Editorial changes, routine implementation details, and temporary experiments usually do not need an ADR. Current registry ADR 0001: Markdown files are the documentation content authority Accepted; generated registries and discovery artifacts are derived outputs. ADR 0002: Mobazha Docs owns public knowledge Accepted; public explanations live here while runtime facts and versioned contracts remain with their owners. ADR template Repository ADR guide Repository owned architecture decisions Cross repository indexes point to the repository that owns each decision. They do not copy or renumber the decision in this documentation repository. Open Core ADR 018: Extension architecture Defines Ports, Modules, Functions, Controllers, Core authority, trust dependent isolation, financial state machine re entry, and closed by default capabilities. Open Core extension guide Explains the decision, its current implementation boundary, and the Collectibles case for portal readers. Reading an ADR safely An accepted ADR explains an intended durable decision. It does not by itself activate a capability, migrate a deployment, or prove that every repository has completed the decision. Check implementation, conformance tests, release notes, and effective runtime capability where applicable." }, { "id": "project-history", "path": "/project/history", "canonical_url": "https://docs.mobazha.org/project/history", "title": "History and supersession", "summary": "Preserve replaced public proposals and guidance without allowing historical text to masquerade as current behavior or policy.", "status": "current", "audiences": [ "community", "contributors", "evaluators", "agents" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/project/history", "label": "History and supersession" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/tree/main/history", "label": "Mobazha public history registry" }, "reviewed": "2026-07-04", "page_type": "policy", "outcome": "Preserve superseded public reasoning without allowing historical proposals to masquerade as current policy.", "estimated_time": "5 minutes", "journey": "understand", "primary_action": { "label": "Review the preservation rule", "href": "/project/history#preservation-rule" }, "language": "en", "search_text": "Preservation rule Historical material remains useful when it explains an old link, percentage, protocol idea, or product assumption. It must be moved or copied into a clearly historical location with its original date, former status, reason for replacement, and current authoritative successor. What must not happen Do not silently delete a widely cited public proposal when a supersession record can preserve context. Do not leave an obsolete percentage or capability claim in a current task page. Do not present a historical design as a supported API, payment method, fee, or governance rule. Do not use history storage to publish previously private material. Current registry No superseded public artifact has been imported in the initial content registry. Candidates require source review and a safe public provenance check before publication. Public source history invariants A publication repository has one reviewed public root and contains only publishable commits, trees, paths, messages, and blobs. Private provenance trailers, source to public commit maps, Git notes, replace refs, private refs, and private only commits do not belong in public history. Attribution is carried by licenses, notices, and preserved publishable authorship. Repository scripts may verify topology and metadata hygiene without exposing private source lineage. Content safety, secrets, licenses, architecture boundaries, and tests remain separate gates. History registry and template Current fees and economics Governs interpretation of old illustrative percentages. Current runtime capabilities Governs interpretation of code and historical feature claims." }, { "id": "releases", "path": "/releases", "canonical_url": "https://docs.mobazha.org/releases", "title": "Releases", "summary": "Use repository releases for exact versions, migration notes, checksums, and known issues.", "status": "current", "audiences": [ "operators", "developers" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/releases", "label": "Releases" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/docs/releases", "label": "Mobazha GitHub releases" }, "reviewed": "2026-07-04", "page_type": "hub", "outcome": "Find the current release evidence and adoption checks without mistaking a release candidate for stable production software.", "estimated_time": "5 minutes", "journey": "understand", "primary_action": { "label": "Review the current release candidate", "href": "/releases#current-release-candidate" }, "language": "en", "search_text": "Current release candidate v0.3 is intended for evaluation and testnet use. Stable binaries and signed release artifacts have not been published yet. The first release enables BTC, BCH, and LTC by default, subject to the full effective capability intersection and seller configuration. Before adopting a release Confirm the repository, version, publication date, and artifact integrity. Read breaking changes, migrations, capability changes, and known issues. Test backup and rollback procedures in an environment representative of production. Documentation release gate Node and Unified tag workflows verify that a versioned release note exists, required public guidance is reachable, and the documentation source manifest reviews the exact commit being tagged. A tag must not create a release while its public instructions still describe a different source revision. This gate establishes documentation readiness; it does not replace tests, artifact provenance, signatures, SBOM review, migration validation, or runtime capability checks. Release sources Mobazha Node release notes Mobazha Unified release notes Published GitHub releases Reviewed public source revisions" }, { "id": "contribute", "path": "/contribute", "canonical_url": "https://docs.mobazha.org/contribute", "title": "Contribute to Mobazha", "summary": "Choose the owning repository, agree on large changes early, preserve public contracts, add tests, update documentation, and sign off commits.", "status": "current", "audiences": [ "contributors", "maintainers", "agents" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/contribute", "label": "Contribute to Mobazha" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/CONTRIBUTING.md", "label": "Mobazha contribution and governance policies" }, "reviewed": "2026-07-04", "page_type": "hub", "outcome": "Send a documentation, client, Node, website, RFC, or policy contribution to the repository that owns it.", "estimated_time": "5 minutes", "journey": "community", "primary_action": { "label": "Choose the owning repository", "href": "/contribute#choose-the-repository" }, "language": "en", "search_text": "Choose the repository Node business logic, deployment, public APIs, extensions, conformance, and release evidence: mobazha/mobazha. Buyer, seller, responsive UI, and runtime capability client behavior: mobazha/mobazha unified. Brand website, pricing, service terms, and public marketing: mobazha/mobazha.org. Project wide public policy, task guidance, cross repository explanation, Agent discovery, and documentation quality: mobazha/mobazha docs. Contribution contract Open an issue or discussion before a large architecture, protocol, payment, security, or governance change. Keep the change focused and update tests, schemas, docs, migration guidance, and release notes together. Do not include credentials, private endpoints, customer data, proprietary code, or generated release binaries. Use DCO sign off for source contributions where required by the owning repository. Report vulnerabilities privately rather than through a public pull request or issue. Repository guides Contribute to Mobazha Node Contribute to Mobazha Unified Improve this documentation" }, { "id": "support", "path": "/support", "canonical_url": "https://docs.mobazha.org/support", "title": "Get help and report problems", "summary": "Use public support for reproducible product questions, repository issues for defects, and private reporting for security problems.", "status": "current", "audiences": [ "everyone" ], "applies_to": "Current public project policy or service surface", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/support", "label": "Get help and report problems" }, "evidence": { "source": "https://mobazha.org/status", "label": "Mobazha public support surfaces" }, "reviewed": "2026-07-06", "page_type": "hub", "outcome": "Route a product question, reproducible defect, documentation problem, or security concern to the correct public or private channel.", "estimated_time": "3 minutes", "journey": "community", "primary_action": { "label": "Choose a support channel", "href": "/support#choose-the-channel" }, "language": "en", "search_text": "Choose the channel In Mobazha Unified, open Me → Help & Support → Documentation. The same canonical portal is linked from the desktop Footer. Documentation issues Stale, missing, unclear, or conflicting documentation. Node issues Reproducible backend, deployment, API, payment, or operator defects. Unified issues Buyer, seller, browser, responsive, or frontend defects. Telegram Community help and current service questions. Discord Community discussion and help. Start with the failing boundary Symptom First check Best route if reproducible Hosted page or login is unavailable Service status, browser network result, and whether another public page works Community support for a current service question; repository issue only with a product reproduction Local Node will not start Exact commit, start flags, data directory ownership, port, disk, and doctor json Node issue Storefront control is missing Runtime config readiness, capability, current identity, store context, and seller configuration Unified issue for presentation; Node issue for an incorrect backend capability Payment is not observed Order ID, intended asset, address, amount, expiry, confirmations, and dependency health Node issue after preserving sanitized evidence; do not send a second payment to test blindly Order, refund, or dispute state looks wrong Authoritative order state, payment record, recent action, and active policy Node issue for state authority; Unified issue only when correct backend state is displayed incorrectly Webhook or integration repeats work Delivery or event identity, signature result, endpoint response, and reconciliation record Node issue for delivery behavior; integration owner for consumer deduplication Documentation conflicts with behavior Page URL, reviewed date, deployment version, capability snapshot, and the conflicting result Documentation issue Do not change several layers at once. Reproduce against the smallest local or disposable boundary first, then report the component that owns the incorrect state. Write a useful report Identify hosted or self hosted deployment, exact version or commit, operating system, and relevant capability state. Describe the smallest reproducible steps, expected behavior, actual behavior, and sanitized evidence. Search existing issues and link related documentation or release notes. Do not include access tokens, private keys, seeds, wallet recovery material, customer data, or private infrastructure details. For an order or payment problem, include only sanitized identifiers needed to correlate the record. State whether funds were merely instructed, observed, verified, settled, refunded, or still unknown; those are different conditions and require different recovery actions. Security exception Suspected vulnerabilities, leaked credentials, signing key concerns, and exploits must use private vulnerability reporting in the affected GitHub repository. Do not first disclose them through community chat or a public issue." }, { "id": "zh-start-choose-deployment", "path": "/zh/start/choose-deployment", "canonical_url": "https://docs.mobazha.org/zh/start/choose-deployment", "title": "选择托管服务或自行托管", "summary": "先根据控制权和责任选择后端运营者，再判断是否用边界明确的托管或第三方服务补充该后端。", "status": "beta", "audiences": [ "卖家", "运营者", "评估者", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/start/choose-deployment", "label": "选择托管服务或自行托管" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/README.md", "label": "Mobazha 公开产品与发布边界" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "根据所需控制权选择托管或自行托管，并理解 Hybrid 如何增加服务而不改变订单权威。", "estimated_time": "5 分钟", "journey": "start", "primary_action": { "label": "应用决策规则", "href": "/zh/start/choose-deployment#决策规则" }, "language": "zh-CN", "translation_of": "/start/choose-deployment", "search_text": "托管服务 如果希望评估 Mobazha 或经营店铺，但不想维护底层服务器，可以使用托管应用。服务运营者负责可用性、部署和托管账号边界；当前 Beta 价格和限制另行公布。 这是进入当前买家和卖家体验的最快路径。 服务可用性、数据处理、限制和未来价格受托管条款约束。 实际可用的交易和支付路径仍由运行时能力决定。 打开 Mobazha 当前价格 隐私政策 自行托管 Node 如果需要直接控制部署、店铺数据、域名、可用性、备份和集成，可以运行开源 Node。你负责机器、安全、恢复、升级和第三方成本。 运行软件本身不会产生必须支付给 Mobazha 的中心化交易费。 当前 v0.3 系列是用于评估和测试网的候选版本。 默认发布边界包含 BTC、BCH 和 LTC，但仍受运行时能力和卖家配置约束。 安装 Node 检查运营安全 责任比较 决策范围 托管服务 自行托管 Node 服务器可用性和更新 由托管服务运营者按公开条款管理 由你的运营者负责，包括维护窗口和回滚 域名和网络边界 使用服务支持的公开入口 自行负责 DNS、TLS、反向代理、防火墙和暴露策略 店铺数据和恢复 受托管服务的导出、保留、隐私和恢复条款约束 自行决定备份频率、异地副本、恢复测试和恢复访问 集成 限于托管部署公开的能力 可在 Node 已发布契约和有效能力范围内配置 服务成本 查看当前托管价格和适用服务商费用 运行软件本身没有强制 Mobazha 交易费，但基础设施和第三方成本由你承担 第一个验证 完成一次可丢弃的买卖流程并检查服务条款 在测试网启动，然后验证诊断、备份、恢复和一次完整交易流程 两种模式都不会自动提供所有支付轨道、扩展或市场能力。连接后端的运行时响应、卖家配置和当前发布契约才是权威来源。 Hybrid 是组合方式，不是第三个订单所有者 Hybrid 指独立或商业运营的店铺后端加入更广泛的店铺网络，或调用选择的外部能力。它不是第三种部署类型，也不会让一笔订单同时由多个权威数据库管理。 例如： 自托管店铺出现在社群或托管发现入口； 独立 Node 使用明确的支付、配送、消息、索引、AI 或支持服务； 托管和自托管店铺交换允许的发现、签名内容、消息或交易协议请求； 托管店面或直接链接把买家解析到真正拥有订单的卖家后端。 每项连接都要记录提供者、交换的数据、价格、能力、故障行为、退出路径，以及继续负责店铺和订单状态的后端。方便的渠道或网关不能悄悄成为第二个交易权威。 比较 Direct P2P 和 Hybrid 拓扑 按收款方和运营方式检查成本 决策规则 如果减少运维工作比控制全部基础设施边界更重要，选择托管。 如果控制权、可移植性、自定义运营或独立可用性值得承担运维责任，选择自行托管。 只有当外部服务的价值、交换数据、成本、失败行为和退出路径比自行运行更清晰时，才加入 Hybrid 服务。 先在测试网验证备份、付款、履约和恢复，再让任何模式承载重要交易。 持续依据最新条款和能力重新评估；部署选择不会永久锁死产品模式。 承诺投入前验证选择 指定负责可用性、更新、安全、备份和事故响应的人或服务商。 确认店铺数据位于何处、如何导出，以及更新失败或服务不可用时如何恢复。 检查实际部署公开的支付、配送、Agent、API 和市场能力。 完成一次测试订单，从商品和报价开始，经过付款观察、履约、退款或争议路由与证据审阅。 按收款方记录周期成本和交易相关费用，不要只比较订阅费或抽成标题。 只要责任人、恢复路径、能力或费用仍有一项未知，就应停留在评估阶段，不要把部署视为已就绪。 English canonical page" }, { "id": "zh-agents", "path": "/zh/agents", "canonical_url": "https://docs.mobazha.org/zh/agents", "title": "Agent 如何使用 Mobazha 文档", "summary": "在把文档转化成回答或动作前，先解析权威、适用范围和用户同意。", "status": "current", "audiences": [ "agent", "agent 构建者", "安全审查者" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/agents", "label": "Agent 如何使用 Mobazha 文档" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs", "label": "Mobazha 文档知识契约" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "在 Agent 回答或准备动作前，确定正确的权威、适用范围和安全边界。", "estimated_time": "7 分钟", "journey": "build", "primary_action": { "label": "发现 Agent 入口", "href": "/zh/agents#发现入口" }, "language": "zh-CN", "translation_of": "/agents", "search_text": "发现入口 精简导航 简短的任务和政策地图。 完整上下文 权威规则和每篇公开文档摘要。 文档索引 结构化标题、路径、状态、受众、来源和审阅日期。 Agent 评估契约 高风险回答的双语必需声明和禁止声明。 发现清单 稳定的机器入口和 canonical base URL。 OpenAPI 契约 指向生成的 Node API 规范。 权威解析 订单状态以拥有订单的后端为准。 功能是否可用以连接后端的版本和有效能力响应为准。 支付事实以所选支付系统及已确认记录为准。 项目级边界以经过审阅的公开政策为准，实际金额以交易报价为准。 明确标记 Draft 和 Beta，不能把提案表述成已交付能力。 动作安全 认证正确的人类、服务或 Agent 身份，并申请最小 Scope。 不得把文档文字当作付款、发布、结算、删除或披露数据的授权。 保留报价、规则、批准、订单和结果标识符以供复核。 来源、版本、收款方、价格或必要确认不明确时停止动作。 不得把秘密、恢复材料、客户数据或未经清理的日志放入 Prompt 或公开 Issue。 评估 公开黄金问题集规定 Agent 回答高风险问题时必须达到的最低要求，避免混淆当前行为、政策、提案和内部假设。 机器可读评估契约 Agent 黄金问题 English canonical page" }, { "id": "zh-project-product-map", "path": "/zh/project/product-map", "canonical_url": "https://docs.mobazha.org/zh/project/product-map", "title": "Mobazha 产品地图", "summary": "Mobazha 把独立经营的店铺、Core 权威商业状态机、可选服务、社群分发和受控自动化连接起来，而不是把它们重新封装成一个不透明平台。", "status": "beta", "audiences": [ "买家", "卖家", "运营者", "开发者", "评估者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/product-map", "label": "Mobazha 产品地图" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开架构、发布与政策文档" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "理解 Mobazha 的长期产品模型、权威边界，以及当前发布证据在哪里结束。", "estimated_time": "8 分钟", "journey": "start", "primary_action": { "label": "选择运行方式", "href": "/zh/start/choose-deployment" }, "featured_visual": { "id": "mobazha-product-atlas", "src": "/images/docs/project/mobazha-product-atlas.svg", "sha256": "b0adee81eb14228fadc3d9169c797ae48d959468cb1d0624387d6cac00add54c", "mobile_src": "/images/docs/project/mobazha-product-atlas-mobile.svg", "mobile_sha256": "ed550f42de13888a9098a949f92703059376dff315832b8d84511bacd68df9c1", "kind": "conceptual", "width": 760, "height": 460, "mobile_width": 360, "mobile_height": 720, "alt": "Conceptual Mobazha product map showing storefronts, community channels, and Agent integrations connected to an operator-selected backend, with payment, delivery, discovery, and hosted services as explicit dependencies.", "caption": "One commerce core can support several operating and distribution paths without moving business-state authority into the presentation channel.", "claim": "Explains the product and authority model; it does not assert that every pictured channel, integration, or external service is available in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "product-atlas-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/project/product-map", "search_text": "独立经营单元 Mobazha 从一个独立经营单元开始：身份、一个或多个店铺、相应政策与目录，以及拥有业务状态的后端。店面、托管应用、社群市场、社交渠道、浏览器入口或 Agent 可以展示和协助这个单元，但不会因此成为订单和资金的权威。 这是 Mobazha 的核心产品区别。它既不只是一个 Marketplace，也不只是一个自行托管商店程序，而是让独立经营的店铺在不把无限权限交给单一展示渠道的前提下参与更大的商业网络。 理解 Identity、店铺、Storefront 与渠道 沿着订单、支付、履约与恢复主线理解交易 四项相互连接的产品承诺 承诺 产品含义 权威边界 自主 明确掌握店铺身份、政策、数据和运行选择 所选后端和运营者拥有店铺及业务状态 连接 通过店面、发现、社群、直接链接和集成触达买家 渠道可以收窄访问或展示，但不能发明后端能力 交易 依据可检查的状态创建、支付、履约、恢复和解决订单 Core 拥有订单、支付验证、退款、争议、结算和审计转换 扩展 通过类型化契约接入支付轨道、配送服务、工具和 Agent 工作流 扩展只能返回受限输入，由 Core 校验受保护变更 这些是组织产品知识的原则，并不表示每个发行版都提供所有渠道、支付轨道、服务商或自动化能力。 一个 Core，多种运行路径 同一套公开契约可以通过不同运行路径使用： 独立运营者可以运行 Node，并选择网络暴露、集成、备份和政策。 托管发行版可以运营 Node 与共享基础设施，同时保持租户和店铺边界明确。 客户端只能展示其连接后端实际声明的有效能力。 发现、支付、配送、消息、AI 和托管服务仍是单独命名的可选依赖。 选择托管服务或自行托管 运行自己的 Mobazha Node 查看架构与信任边界 交易主线 Mobazha 围绕一条交易主线变得具体： 买家通过店面或分发渠道到达卖家拥有的报价。 拥有订单的后端创建报价与订单身份。 所选支付系统返回观察结果或服务商状态，由 Core 决定这些事实对订单意味着什么。 履约、取消、退款、争议和完成遵循当前状态与适用政策。 历史绑定和证据继续服务于恢复与对账。 在独立 Mobazha 店铺购买 查看订单状态指南 查看退款与争议指南 理解订单、支付与保护状态为何必须分离 连接 Offer、Merchandising、Supply 与 Fulfillment 分发和自动化也是产品界面 社群市场、社交入口、直接链接、Marketplace 策展、消息、Webhook、MCP 和 Agent 工作流不是互不相关的附加项，而是把需求、供给和经营操作连接到独立经营单元的方式。 它们仍遵守三个限制： 展示界面不能覆盖交易权威； 配置或源码存在不代表运行时可用； Agent 可以准备、比较或请求动作，但执行仍受身份、权限、状态、报价与确认约束。 基于后端实际公开的能力进行开发 区分产品表面、渠道与集成契约 理解社群市场与分布式发现 理解 Agent、Skill、Tool 与批准边界 查看 MCP 与 Agent 集成 通过公开契约扩展 Mobazha 分开阅读当前能力、Beta 和未来方向 本页解释产品模型。精确可用性来自当前连接的后端、版本化公开契约、发布范围和交易证据。 English canonical product map 证据 能证明什么 有效运行时能力 当前连接后端现在可以接纳什么 带版本的契约与发布证据 某个发布支持哪些接口与行为 Current 政策页 收费、安全、兼容性或治理的公开规则 Draft RFC 或路线图 经过评审的方向，不是已交付能力 内部设计或实施计划 维护者证据，不是公开产品承诺 查看发布范围与成熟度 运行时能力与产品组合 查看公开决策与提案 图、路线图、RFC、已链接的软件包或文档页面都不能激活一项能力。涉及可用性时，应以连接后端和适用发布的证据为准。" }, { "id": "zh-project-identity-and-stores", "path": "/zh/project/identity-and-stores", "canonical_url": "https://docs.mobazha.org/zh/project/identity-and-stores", "title": "Identity、店铺与 Storefront", "summary": "分开理解访问账户、店铺与 Node 身份、Storefront 展示以及渠道上下文，使所有权和交易权威保持清晰。", "status": "beta", "audiences": [ "买家", "卖家", "运营者", "开发者", "评估者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/identity-and-stores", "label": "Identity、店铺与 Storefront" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开身份、Profile、能力与架构契约" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "当用户需要新的登录方式、店铺、店面或分发渠道时，判断真正应该改变哪一层边界。", "estimated_time": "8 分钟", "journey": "start", "primary_action": { "label": "准备店铺", "href": "/zh/sell" }, "featured_visual": { "id": "identity-storefront-model", "src": "/images/docs/project/identity-storefront-model.svg", "sha256": "ba28eef9f58d55f80205f6f697b6f116a8f292be60aa87edfa7624124653f9dd", "mobile_src": "/images/docs/project/identity-storefront-model-mobile.svg", "mobile_sha256": "f1f499dd4f8608e44b08fb04737e3ebc3654c6d291c16f954817958bcbab532f", "kind": "conceptual", "width": 760, "height": 500, "mobile_width": 360, "mobile_height": 760, "alt": "Conceptual model separating an access account or credential, the store and Node business-state boundary, storefront views that share store state, and the channels that present those views.", "caption": "Accounts authorize access, stores own business state, storefronts shape presentation, and channels provide entry context.", "claim": "Explains product and authority boundaries; it does not assert that every distribution enables multiple stores, named storefronts, every channel, or future identity models.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "identity-storefront-model-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/project/identity-and-stores", "search_text": "四个不同的产品概念 Mobazha 将四个概念分开，因为它们承载的权威不同： 概念 负责什么 不能证明什么 Account 或 Credential 验证人、服务或 Agent，并关联允许访问的店铺上下文 客户端里看到的每个店铺都归该账户所有 Store 与 Node Identity 标识独立经营单元，以及拥有其业务状态的后端 永久依赖某个托管账户、域名或渠道 Storefront 为同一个店铺提供经过筛选、换主题或不同路由的展示 独立钱包、订单账本、信誉或法律主体 Channel 将 Storefront 带入 Web、嵌入式、社交、直接链接或集成场景 修改店铺或绕过后端能力的权限 一个界面可以同时展示这四层，但它们在产品模型中仍然独立。 店铺是业务状态边界 在 Open Core 中，Node 暴露 Profile 和节点级商业服务。店铺上下文拥有或服务于该独立经营单元的目录、政策、订单、消息、支付观察、履约记录和信誉。 托管控制面可以把经过验证的账户与一个或多个已登记店铺关联，并为管理请求解析活动店铺。这是访问和路由事实。切换账户或客户端不能静默改写店铺 peer identity、交易历史或已经接受的义务。 Mobazha 产品地图 查看架构与信任边界 选择托管服务或自行托管 Storefront 是视图，不是另一个店铺 Storefront 可以为同一个店铺提供不同公开名称、slug、主题、商品筛选、可见性规则、价格展示或渠道入口，但共享业务状态仍由父店铺拥有。 展示或分发需求适合使用 Storefront： 活动页或季节目录； 社群专属入口； 公开、unlisted 或受限展示； 不同主题或商品子集； 指向同一个经营店铺的 Web、嵌入式或直接链接路由。 需要独立业务状态时应使用独立 Store 或 Node，例如不同运营者、钱包或支付配置、订单账本、信誉边界、法律责任、基础设施或恢复计划。 Storefront 受运行时能力控制。本页描述的模型或路由不表示当前连接后端已经启用命名 Storefront、全部可见性模式、渠道绑定或价格规则。 角色由当前上下文解析 同一个人可以在不同时候浏览、购买、管理店铺、处理争议或运行集成。这些是动作上下文，不是让一个 Session 自动拥有所有权限的理由。 执行受保护动作之前，系统需要解析： 已认证的身份或 Credential； 当前 Store，以及相关时的 Storefront 上下文； 该动作要求的 Scope 或 Role； 后端能力和当前资源状态； 适用的报价、政策、确认或 Step up 要求。 切换可见视图不能补出缺失的 Scope；隐藏 Admin 路由也不能替代服务端授权。 查看身份认证与权限 运行时能力与产品组合 当前模型与演进方向 领域 当前公开含义 必须继续标为方向的内容 Node Profile 与店铺政策 节点级身份和商业配置属于 Core 模型 更丰富、可移植或外部锚定的身份证明 托管账户关联 托管身份可以被授权到明确店铺上下文 更广泛的多 Identity 与多运营者管理 Storefront 发行版可以启用轻量展示模型 更多渠道绑定、范围化分析、访问与价格规则 多店铺 已登记店铺仍是相互独立的经营单元 更方便的创建、切换、Staff 委派与跨店报表 渠道组合 客户端和发行版选择体验并收窄能力 更多社交、嵌入式、浏览器和 Agent 界面 实际可用性仍由当前连接后端的有效能力和适用发布决定。内部设计阶段与未来身份模型不是当前产品保证。 选择满足需求的最小边界 需求 优先选择 不同主题、商品子集、活动或社群入口 后端支持时使用 Storefront 不同域名指向同一个经营店铺 带明确 Store 上下文的域名或渠道路由 独立订单、钱包配置、信誉或运营责任 独立 Store 或 Node 另一个人或 Agent 只协助有限职责 支持时使用窄范围账户、Token 或委派 Scope 运营者也不能关联的强隐私隔离 真正独立的 Identity 和运行边界，而不是装饰性 Storefront English canonical page 应从能够保留所需信任、记账和恢复模型的最轻边界开始，不能用新 Storefront 模拟它无法提供的隔离。" }, { "id": "zh-project-offer-to-fulfillment", "path": "/zh/project/offer-to-fulfillment", "canonical_url": "https://docs.mobazha.org/zh/project/offer-to-fulfillment", "title": "从 Offer 到 Fulfillment", "summary": "把产品形态、Listing 修订、Collection、Discount、供应事实、交付选择与履约证据连接起来，同时不把展示误认为卖家已经接受的义务。", "status": "beta", "audiences": [ "sellers", "buyers", "operators", "developers", "evaluators" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/offer-to-fulfillment", "label": "从 Offer 到 Fulfillment" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开 Listing、Collection、Discount、Shipping、Supply、Fulfillment、Quote 与 Order 契约" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "为可销售 Offer 及其履约路径建立模型，同时保留现有订单已经接受的事实。", "estimated_time": "10 分钟", "journey": "use", "primary_action": { "label": "查看卖家旅程", "href": "/zh/sell" }, "featured_visual": { "id": "offer-to-fulfillment", "src": "/images/docs/project/offer-to-fulfillment.svg", "sha256": "507cd4856700f982c65068076ba9db5e830c7a351190e91318a0073fe5209528", "mobile_src": "/images/docs/project/offer-to-fulfillment-mobile.svg", "mobile_sha256": "f7cc389b9e4620a3d7105518d322baa28053eeb69ac256d5a0d8e1a8cb1ba61b", "kind": "conceptual", "width": 760, "height": 520, "mobile_width": 360, "mobile_height": 780, "alt": "Conceptual commerce flow from supply facts through a seller-owned listing revision, merchandising projection, accepted quote and order, and fulfillment evidence, with external providers and Core authority kept separate.", "caption": "One seller-owned promise can use several merchandising, supply, and fulfillment models without allowing later changes to rewrite an accepted order.", "claim": "Explains durable offer and fulfillment boundaries; it does not assert that every product shape, discount, collection rule, supply provider, or delivery path is available in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "offer-to-fulfillment-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/project/offer-to-fulfillment", "search_text": "一个可销售承诺，多个支撑模型 买家把商品页体验为一个 Offer。Mobazha 在背后保持多个关注点分离，避免 Merchandising、供应自动化或 Fulfillment 变化暗中重写卖家的义务。 关注点 它拥有什么 它不拥有什么 产品或服务形态 买家可见描述、Option、媒体，以及承诺商品或结果的性质 支付状态或履约完成状态 Listing Revision 卖家当前零售条款、价格、可售性、政策和可用履约路径 已被现有订单接受的条款 Collection 或展示 分组、排序、过滤与发现上下文 Listing 的第二份副本或另一套库存账本 Discount 有边界的价格规则及其资格条件 基础 Listing、支付验证或历史订单总额 Supply Binding 与卖家库存、容量或外部供应源的关系 未经政策允许发布卖家 Draft 或更改零售条款的权威 Fulfillment Plan 如何交付已接受义务并形成证据 绕过获准状态迁移推进订单的权限 稳定单元不是一个 Product Type 标签，而是一个由卖家拥有、能够被报价、接受进订单、完成履约并通过保留证据解释的承诺。 产品形态、供应来源和履约路径相互独立 “实体”“数字”“服务”或某个垂直品类可以帮助选择字段和买家文案，但一个标签不应决定整笔交易。需要分别回答三个问题： 承诺了什么？ 商品、访问权、文件、License、预约、容量或其他受支持结果。 可售性从哪里来？ 卖家持有库存、卖家管理的容量，或显式配置的外部供应源。 如何履约？ 卖家配送、自提、数字交付、服务完成、外部 Fulfillment Provider，或其他带版本契约。 这种分离支持多种经营模式，而不必为每个 Provider 或 Vertical 发明新的万能 Product Type。 示例形态 可能的供应事实 可能的履约事实 实体商品 卖家数量或外部供应商可用性 卖家发货、自提或 Provider 发货 数字商品 License、Entitlement 或有边界的可用性 下载、Key、账户授权或其他受支持交付记录 服务或容量 时间、Quota、Seat 或运营者可用性 预约、完成、兑换或 Attestation 收藏品或专业 Vertical 实体、数字、Tokenized 或混合事实 只使用显式支持的 Shipping、Delivery 或 Extension 契约 这些示例用于建模，不代表每个发行版都支持所有组合。 Listing 是卖家当前 Offer 有用的 Listing 应使可销售承诺可以检查： 卖家和店铺 Identity； 标题、描述、媒体、Option 与买家可见状态； 零售价、币种、税费和卖家定义费用； 数量、容量或其他 Availability Signal； 可用 Shipping、Delivery、Redemption 或 Service 条件； 退货、退款、保修、资格及其他适用政策； 发布状态和 Revision 证据。 发布 Listing 并不证明它一定可购买。Checkout 仍需要兼容的店铺上下文、可用 Supply、Delivery Path、Payment Capability 与有效 Quote。 查看 Listing 创建与验证指南 查看首单准备指南 Collection 与 Storefront 改变发现，不改变所有权 Collection 可以为浏览分组和排序卖家 Listing；Storefront 可以对同一店铺应用 Catalog Filter 或展示规则；Community Market 可以投影多个同意加入的店铺的选定 Offer。 它们都是对权威 Listing 的可组合视图： 从 Collection 移除商品不会删除 Listing； 改变 Storefront Filter 不会改变父店铺已经接受的订单； 在市场中推荐商品不会转移卖家或支付权威； Projection 丢失时应从 Listing Source 修复，而不是把它当成新的库存真相。 手动或规则驱动的组织、Sort Mode、Visibility 和 Filtering 仍取决于 Capability。展示视图改变价格表达时，最终 Quote 必须标明应用规则和接受金额。 理解 Identity、店铺与 Storefront 理解社群市场与策展 Discount 先成为 Quote 事实，再成为 Order 事实 在受支持时，Discount 可以自动应用，也可以要求显式 Code 或条件；它可以针对特定商品、Collection、Store、数量、Buyer 或时间窗口。有效规则必须在确认前评估，并显示在最终成本明细中。 安全顺序是： 根据当前 Cart、Identity、Store、时间与规则状态评估资格； 使用明确币种和舍入行为计算 Discount； 在 Quote 中标明 Discount 及其对收款方的影响； 把接受结果快照进 Order； 在不重写历史的前提下执行使用次数、过期、取消、退款与撤销规则。 后续 Promotion 修改不能改变现有订单总额。前端标签也不足以证明某个 Discount 已被接受。 Supply 自动化为 Offer 提供信息，但不拥有 Offer 外部 Supply 或 Fulfillment Provider 可以贡献 Catalog Data、Availability、Supplier Cost、Shipping Estimate、Production Status 和 Tracking。Mobazha 可以把 Provider Product 绑定到 Store Listing，并把 Supplier Work 绑定回 Store Order。 边界仍需明确： Provider 拥有自己的外部 Catalog、Job 与 Observation； Seller 拥有零售选品、Markup、Policy 和 Publication Decision； Core 拥有 Quote、Order、获准业务迁移与 Audit Trail； Credential、Webhook、Retry、Provider Failure 与 Reconciliation 留在配置好的集成边界内。 外部 Availability 不确定时，新购买应失败关闭，或按政策把受影响 Offer 设为不可用。自动化不能仅因为供应商恢复库存就发布卖家 Draft。 Fulfillment 保留已接受义务 在 Checkout 中，买家只能选择对商品、目的地和当前 Capability 有效的 Delivery Option。被接受的 Order 保留所选 Service、Amount、Address 或 Delivery Target，以及适用条款。 付款和卖家接受后，Fulfillment 可以包含一次卖家管理的 Shipment，也可以包含多个明确的 Provider/Location Group。外部 Provider Status 是运营证据；Core 决定它是否足以推进订单。Tracking、Delivery、Digital Access、Service Completion、Pickup 或 Attestation 应通过受支持履约路径记录。 查看 Shipping 与 Delivery 指南 查看卖家订单运营指南 沿着订单与支付交易主线理解状态 不要为了满足 UI 要求给数字商品或服务附加实体 Shipping。如果连接发行版缺少所需 Delivery Contract，该 Offer 就不能通过这条路径销售。 订单存在后的变更安全 买家接受 Quote 后，Listing、Collection、Discount、Supplier Cost、Shipping Profile、Provider 或 Storefront 的后续变化都不能暗中改变该 Order。应保留接受快照，并把后续 Fulfillment 与 Recovery Evidence 绑定到同一 Order Identity。 变化 新买家 现有订单 Listing Price 或 Description 使用新的获准 Revision 保留已接受 Item 与 Price Snapshot Collection 或 Featured Position 使用新的 Discovery Projection 不影响订单义务 Discount Rule 对新 Quote 重新评估 保留已接受 Discount 与 Total Supply Availability 或 Cost 重新评估准入与 Seller Policy 对已接受义务进行 Reconcile，不重写义务 Shipping 或 Provider Configuration 只提供当前有效路径 服务持久绑定，或使用显式 Recovery Action 当前契约与演进方向 范围 当前公开含义 必须标注为方向的内容 Listings 带版本 Seller Offer 承载买家可见 Item、Price、Availability、Policy 与 Fulfillment Data 更丰富 Product Schema 与 Vertical specific Authoring Collections 与 Discounts 启用时存在 Store scoped Merchandising 和有边界 Pricing Contract" }, { "id": "zh-project-transaction-spine", "path": "/zh/project/transaction-spine", "canonical_url": "https://docs.mobazha.org/zh/project/transaction-spine", "title": "Mobazha 交易主线", "summary": "沿着订单权威、支付证据、履约与策略约束的恢复路径理解一笔交易，而不是把它们压成一个容易误导的状态。", "status": "beta", "audiences": [ "buyers", "sellers", "operators", "developers", "evaluators" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/transaction-spine", "label": "Mobazha 交易主线" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开订单、支付会话、能力与恢复契约" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "正确读取一笔交易，并判断哪种状态、证据、策略与角色允许执行下一步。", "estimated_time": "9 分钟", "journey": "start", "primary_action": { "label": "跟踪订单", "href": "/zh/buy/order-status" }, "featured_visual": { "id": "transaction-spine", "src": "/images/docs/project/transaction-spine.svg", "sha256": "448c48082fa809c22ffcc16ca1abfea2842886dbdb20fcf4721100ee5b1ea77d", "mobile_src": "/images/docs/project/transaction-spine-mobile.svg", "mobile_sha256": "5ee3aa4aa173c2b8fb5ae4f606fe8c54f07182e4f6eceab0f9e7dcb478d09bd7", "kind": "conceptual", "width": 760, "height": 500, "mobile_width": 360, "mobile_height": 760, "alt": "Conceptual transaction spine showing a normal path from reviewed terms through order creation, payment verification, fulfillment, and completion, with separate bands for order authority, payment evidence, and policy-gated recovery.", "caption": "One trade connects order, payment, and protection state without collapsing them into one misleading status.", "claim": "Explains durable authority and recovery boundaries; it does not assert that every distribution, order, payment rail, or protection model exposes every pictured action.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "transaction-spine-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/project/transaction-spine", "search_text": "一笔交易，三个状态面 一笔 Mobazha 交易沿着一条稳定主线推进：确认条款、创建订单、建立并验证支付、履约、完成。在当前状态和策略允许时，恢复路径可以分支为取消、拒单、退款或争议。 界面可以把它呈现为一条时间线，但三个状态面必须保持分离： 状态面 它回答什么 权威来源 订单 买卖双方承诺了什么，下一步什么动作是合法的？ 持有订单的 Core 后端及其状态机 支付会话 资金应去哪里、观察到了什么、验证了什么？ 将订单、报价、支付轨道、观察与验证结果绑定的持久会话 保护与恢复 适用哪一种取消、退款、争议或结算路径？ 已接受的产品条款、当前状态、角色与有效能力 任何一个状态面都不应暗中替代另一个。钱包事件是支付证据，不是订单状态迁移；订单完成本身不说明采用了哪种结算轨道；出现争议按钮，也不代表所有订单都具有相同的保护模型。 正常路径 确认条款。 买家检查单个卖家的商品、价格、配送、支付、退款与保护条款；易变值应绑定到报价或等价证据。 创建订单。 持有订单的后端分配稳定标识，保存已接受的快照，并准入第一个订单状态。 建立支付。 支付会话把订单绑定到收款目标或提供商会话、金额、资产或币种、有效期、确认策略与适用的结算语义。 观察并验证。 钱包、链或提供商事件刷新支付信息；Core 评估这些事实，并决定订单能否推进。 接受并履约。 卖家只执行当前订单状态和能力所暴露的动作，然后记录发货、交付或自提证据。 完成。 后端记录终态业务结果，同时保留对账和恢复所需的绑定关系。 查看结账责任指南 查看支付与订单状态指南 查看卖家订单指南 查看卖家支付指南 事件用于提示刷新，后端状态才是权威 客户端可能先后收到消息、Webhook、提供商回调或钱包观察，而其他界面尚未同步。应把这些事件当作重新加载相关资源的提示，渲染后端最新的订单和支付会话状态，而不是在本地推断迁移。 这条规则能避免多种危险捷径： 不要仅凭交易标识就把订单标为已支付； 不要在后端尚未验证时仅凭通知开始履约； 不要把“已申请退款”推断成“退款已完成”； 不要从“订单完成”推断资金结算已经最终完成； 不要脱离当前幂等和状态规则重试受保护命令。 保护是具体产品条款，不是通用徽章 支付轨道和保护模型是两个独立选择。直接观察型支付、类似托管的流程、提供商托管会话可以暴露不同动作；产品条款还会决定谁能取消、资金何时可移动、争议接受什么证据，以及由哪个参与方或机制裁决。 在把一笔交易称为“受保护”之前，需要明确： 已接受的订单与支付条款； 生效的保护或结算模型； 各阶段由谁或什么机制控制资金； 可用恢复动作及其时限； 适用支付轨道的证据与最终性规则。 Mobazha 应说明这些具体属性，而不是暗示一个笼统的“买家保护”承诺覆盖所有发行版、卖家、支付轨道和订单。 恢复分支保留原始交易主线 取消、拒单、退款和争议不是可以互换的标签： 分支 通常含义 必须检查 取消 在适用的承诺或履约边界之前终止订单 操作方、当前状态、支付进度与取消策略 拒单 卖家在接受或履约之前拒绝订单 卖家权限、原因及所需的支付恢复 退款 已存在支付证据后返还全部或部分价值 退款目标、金额、轨道能力、授权与最终性 争议 在适用保护模型下保存并评估冲突主张 资格窗口、证据、裁决方、决定与结算影响 原始订单、支付绑定和证据仍属于审计轨迹。恢复动作不应制造一段与原交易脱节的新历史。 查看取消、退款与争议指南 查看安全与恢复指南 当前契约与演进方向 范围 当前公开含义 必须标注为方向的内容 订单状态 Core 持有获准的业务迁移，客户端渲染当前状态 更丰富的跨客户端时间线与运营诊断 支付会话 稳定的订单绑定、收款目标或提供商状态、观察与验证相互分离 更多支付轨道适配器与恢复自动化 保护 可用动作取决于已接受条款、状态、角色与有效能力 更多产品模式、裁决方与证据工作流 履约 配送、自提或其他履约事实只能通过获准动作推进订单 更广泛的配送与供应链集成 自动化 Webhook 与 Agent 可以观察、准备或请求有边界的动作 更多具备策略感知、明确批准和审计的自动化 连接后端、适用版本、已接受的交易证据与有效能力仍是可用性的权威。RFC、示意图、配置项或源码包都不会自动启用某种支付轨道或保护模式。 English canonical transaction spine" }, { "id": "zh-project-community-commerce", "path": "/zh/project/community-commerce", "canonical_url": "https://docs.mobazha.org/zh/project/community-commerce", "title": "社群市场与分布式发现", "summary": "理解社群和运营者市场如何策展独立店铺，同时不成为其目录、订单、资金或信誉的所有者。", "status": "beta", "audiences": [ "buyers", "sellers", "community operators", "marketplace operators", "evaluators" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/community-commerce", "label": "社群市场与分布式发现" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开产品边界与受能力约束的 Marketplace 契约" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "在店铺、Storefront、社群市场和运营者市场之间做出选择，同时不把交易权威移入发现层。", "estimated_time": "9 分钟", "journey": "understand", "primary_action": { "label": "查看产品地图", "href": "/zh/project/product-map" }, "featured_visual": { "id": "community-commerce-network", "src": "/images/docs/project/community-commerce-network.svg", "sha256": "d83e1826fafaf27e1c5d390816f39f87ea0ffbdd5cef1d82c675404500efddfd", "mobile_src": "/images/docs/project/community-commerce-network-mobile.svg", "mobile_sha256": "c80d73c32601f4533864e4a18818de8c2fa596f6f0b4cb6e36bf0421f6096684", "kind": "conceptual", "width": 760, "height": 520, "mobile_width": 360, "mobile_height": 780, "alt": "Conceptual distributed discovery model showing community, Web, direct-link, and Agent channels entering an operator-owned market projection, with participating stores remaining separate transaction authorities.", "caption": "Markets organize audience, consent, access, and curation; a selected offer still hands off to one seller-owned transaction.", "claim": "Explains durable discovery and transaction boundaries; it does not assert that every market shape, channel, access mode, domain flow, or curation feature is available in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "community-commerce-network-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/project/community-commerce", "search_text": "共享发现，不必中心化商业 Mobazha 把“买家在哪里发现商品”与“哪个后端拥有最终交易”分开。社群或 Marketplace 运营者可以建设受众、选择参与店铺、组织目录投影并提供清晰入口；每个获准卖家仍拥有自己的店铺上下文、实时商品事实、订单、支付配置、履约义务和信誉。 这形成的是市场网络，而不是唯一强制 Marketplace。一个店铺可以同时通过自有域名、多个 Storefront、社群入口、运营者策展的垂直市场、直接链接或 Agent 目录被发现，同时保留同一个业务状态边界。 四个分发边界 边界 产品责任 不能暗中变成什么 Store 与 Node 拥有实时目录事实、政策、订单、支付、履约和信誉 每一个展示它的市场的附属租户 Storefront 通过主题、过滤、可见性或渠道路由展示一个店铺 独立卖家、钱包、账本或信誉边界 社群或运营者市场 策展多个同意加入的店铺，并管理买家访问、目录展示、发现与归因 实际卖家、资金托管方或所有订单的拥有者 Channel 通过 Web、域名、嵌入式、社交、直接链接或 Agent 上下文承载市场或 Storefront 伪造店铺上下文或绕过能力检查的权限 理解 Identity、店铺与 Storefront 沿着交易主线理解订单 成员关系必须承载同意 市场不应抓取一个店铺形成商业关系，再暗示对方已经认可。持久关系需要明确的店铺身份和可复核生命周期，例如邀请、申请、接受、拒绝、退出或移除。可见性与成员关系也应分开：获准店铺在市场准备期间或处理政策问题时仍可暂时隐藏。 运营者可以拥有： 市场名称、描述、主题、域名和公开叙事； 买家访问和可发现性设置； 卖家进入与审核政策； 开放、过滤或策展型目录展示； 有顺序的推荐商品、Collection 或产品组投影； 已披露的归因和运营服务条款。 卖家保留自己的店铺身份，以及修改或撤回实时商品和交易条款的权威。市场投影应刷新这些事实，而不是复制出第二个无人负责的事实来源。 一个引擎可以表达不同市场形态 “社群”“私有”“垂直”和“公开运营者市场”是有用的产品描述，但不需要互不相关的商业技术栈。市场可以由多个独立维度组合： 维度 示例 入口上下文 Web 域名、嵌入式界面、社群链接、Telegram 或 Discord 上下文 买家访问 支持时可为开放、邀请或审批 卖家进入 运营者邀请、审核申请或其他明确政策 目录模式 开放投影、过滤投影或运营者策展 可发现性 公开、不公开索引或受限 垂直方向 通用商业，或运营者定义的品类与展示预设 这些设置描述展示与治理，不改变谁拥有订单。精确组合仍取决于发行版、版本、政策和有效能力。 发现层交接给单一卖家交易 安全交接需要显式发生： 市场帮助买家找到商品，并明确标识参与店铺。 从该店铺解析实时商品、可售性、价格组成、配送、支付、退款与保护条款。 买家确认单一卖家上下文和适用报价。 卖家持有订单的后端创建并推进订单。 市场可以保留已披露的归因与可观察交接结果，但不能重写支付或订单状态。 多店发现页面不等于跨店购物车、合并结算、资金池托管、共享退款权限或统一运营者订单后台。任何一种能力都需要明确的产品与会计契约。 查看结账责任指南 理解费用、归因与收款方 运营者价值来自受众和策展 运营者的持久贡献不是占有卖家资金，而是受众、上下文、信任建设、治理、目录组织和渠道运营。商业条款可以对真实服务收费，但付款方、收款方、触发条件、撤销规则与归因必须在影响交易前可见。 Direct Link 与 Deal Link 可以缩短从已知商品到结账的路径，但仍需不可变的报价和卖家绑定。推荐或推广归因必须披露并可审计，不能把推广者或市场变成订单拥有者。 市场品牌页面、推荐位、社群徽章或 Agent 推荐都不是支付验证，也不是通用买家保护承诺。应检查卖家、已接受条款、生效保护模型和持有订单的后端。 当前契约与演进方向 范围 当前公开含义 必须标注为方向的内容 Marketplace Identity 市场可以拥有运营者、名称、Slug、状态、展示、访问、目录与可发现性设置 更多自助创建、域名、分析和合作伙伴运营能力 卖家成员关系 店铺参与和可见性是明确、可复核的关系 更丰富的卖家申请、可移植信誉信号与治理工作流 策展 启用时，运营者可以投影选定店铺、产品组或有顺序的商品 更多垂直预设、编辑工具与 Agent 可读目录 交易交接 所选店铺仍是实时条款和最终订单的权威 更一致的跨渠道交接与归因证据 渠道 Web 和其他已启用上下文可以展示同一市场或 Storefront 模型 更多嵌入式、社交、浏览器与社群界面 连接发行版的有效能力和适用公开版本仍是可用性权威。内部 Starter 计划、配置字段或源码存在都不能证明某种市场类型、渠道、域名流程、收费模式或垂直已经公开启用。 English canonical community commerce page" }, { "id": "zh-project-surfaces-and-integrations", "path": "/zh/project/surfaces-and-integrations", "canonical_url": "https://docs.mobazha.org/zh/project/surfaces-and-integrations", "title": "交互表面、渠道与集成契约", "summary": "把 Web、移动、桌面、社群、Agent、域名、Chat、API、WebSocket、Webhook 与 MCP 放在正确层级，同时保持唯一商业权威。", "status": "beta", "audiences": [ "operators", "developers", "client maintainers", "agent builders", "evaluators" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/surfaces-and-integrations", "label": "交互表面、渠道与集成契约" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开前端组合、路由、HTTP、WebSocket、Webhook、MCP、Chat 与 Capability 契约" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "选择产品表面和集成契约，同时不把渠道、通知、域名或客户端 Shell 变成第二个状态权威。", "estimated_time": "10 分钟", "journey": "build", "primary_action": { "label": "查看开发者入口", "href": "/zh/build" }, "featured_visual": { "id": "surfaces-and-integrations", "src": "/images/docs/project/surfaces-and-integrations.svg", "sha256": "aa8b65bf62d385f4c06382c37dbf8cec07d44cb886c975ab8ca88e591840dd94", "mobile_src": "/images/docs/project/surfaces-and-integrations-mobile.svg", "mobile_sha256": "3d61795f1ef455f36eed00ae8376160138c9f4a60809abf592670140bb86df98", "kind": "conceptual", "width": 760, "height": 540, "mobile_width": 360, "mobile_height": 800, "alt": "Conceptual model showing Web, mobile, desktop, community, embedded, browser, and Agent shells resolving server context before using HTTP, WebSocket, webhook, MCP, or chat contracts to reach capability-gated Core commerce state.", "caption": "Many experience shells and interaction contracts can share one server-resolved context and one Core-owned commerce authority.", "claim": "Explains durable surface and transport boundaries; it does not assert that every client shell, domain route, channel, event, chat service, Tool, or integration is available in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "surfaces-and-integrations-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/project/surfaces-and-integrations", "search_text": "多种表面，一个商业权威 Mobazha 可以通过托管 Web 应用、自托管 Storefront、移动或桌面客户端、社群入口、嵌入式视图、Direct Link 或 Agent 使用。这些表面可以拥有不同外观与交互，同时消费相同的 Store、Catalog、Quote、Order、Payment、Fulfillment 与 Policy 契约。 稳定产品规则很简单：Surface 负责展示和请求；拥有当前 Store 或 Order 上下文的后端负责校验，并持有获准业务状态。 不能混在一起的五个层级 层级 示例 责任 Experience Shell Web、Mobile、Desktop、Embedded、Community、Browser、Agent Workspace Navigation、Layout、本地交互、设备集成与用户解释 Entry 与 Context Domain、Storefront Slug、Marketplace、Direct Link、Tenant、Store、Role、Persona 解析请求属于哪个商业与政策边界 Interaction Contract HTTP、WebSocket、Webhook、MCP、Chat 用明确投递语义承载命令、读取、通知、Tool 或会话 Capability 与 Authorization Backend Version、Effective Capability、Identity、Scope、Resource State 决定操作是否存在，以及当前 Actor 现在能否请求 Commerce Authority Core 拥有的 Quote、Order、Payment Verification、Fulfillment、Recovery 与 Audit 接纳持久事实和受保护状态迁移 新客户端不需要新的订单模型；新 Transport 不会激活产品能力；新 Domain 不会授予权限；新 Notification 也不会成为交易状态。 渲染动作前先解析 Context 每个表面都需要足够的服务端校验上下文来回答： 当前连接哪个 Deployment 和 Backend？ 当前 Tenant、Store、Storefront 或 Marketplace 是哪个？ 认证了哪个 Identity，正在以哪个 Role 或 Persona 行动？ 哪一份 Capability Snapshot 已就绪并具有权威？ 哪个 Resource State 与 Policy 控制请求动作？ Domain、Subdomain、Slug、Direct Link、社交 Start Parameter 和 Embedded Configuration 可以帮助定位 Context，但它们只是 Routing Input，不是所有权证明。服务端解析必须拒绝未知上下文，并阻止客户端提供的路由提示伪造另一个 Store 或 Storefront。 理解 Identity、Store、Storefront 与 Channel 理解社群与运营者市场 基于有效 Capability 构建 根据投递语义选择契约 需求 优先选择 必须具备的行为 读取当前状态或请求受保护变更 Versioned HTTP API 认证、校验 Schema 与 State、必要时使用 Idempotency，并返回权威结果 快速刷新交互客户端 Authenticated WebSocket 把 Event 当作提示，容忍丢失与未知新增类型，然后重新加载受保护状态 把事件投递给运营者控制的服务 Signed Webhook 持久接收、验签、去重、容忍重试与乱序，并通过 API 对账 让 Agent 发现和调用获准 Tool MCP Streamable HTTP 要求 ai:use 、Tool Domain Scope、当前 Discovery、Approval Policy 与底层命令校验 交换人类或 Agent 会话 Chat Contract，当前可由 Matrix 等已启用消息服务支撑 保留 Room、Message、Membership 与 Privacy；不把消息当作 Order 或 Payment 权威 协调外部商业系统 类型化 Extension 或 Controller Contract 消费持久 Core Fact，并返回有边界 Observation 或 Attestation 这些契约可以协作。Web Client 可以发送 HTTP Command 并收到 WebSocket 刷新提示；Webhook Consumer 可以响应事件后读取相关 Order；Agent 可以通过 MCP 发现 Tool，而该 Tool 调用同一个受保护 HTTP Business Operation。 HTTP 是权威读取与命令表面 当前 Node 在 /v1/ 下暴露带版本业务路由。OpenAPI 描述经过评审的方法、路径、Schema、Response Envelope 与认证机制。精确 Route Availability 仍取决于连接发行版、版本、Capability 与 Identity。 在 Reconnect、Notification、Chat Message、Provider Callback 或不确定 Timeout 后，应使用 HTTP 确认重要状态。客户端动画成功、Push Event 或外部 Callback 都不能替代最新权威资源。 查看 HTTP API 与 OpenAPI 指南 查看错误、重试与幂等指南 WebSocket 与 Webhook 是不同事件产品 当前 /ws WebSocket 表面用于及时的认证客户端更新。连接可能中断，瞬时事件也可能丢失；重连后，应重新加载做出业务决定所需的资源。 Webhook 是发往运营者控制 Endpoint 的出站签名投递，面向持久接收、Retry、Delivery History 与集成工作流设计。Duplicate 和 Reordering 是预期情况。Receiver 必须校验精确签名 Body、去重 Identifier，并通过 HTTP 对账相关状态。 两个事件表面都不能按 Arrival Time 定义业务状态顺序。 查看 WebSocket 指南 查看 Webhook Consumer 指南 Chat 用于沟通，不用于结算 Chat 可以承载买卖双方问题、协商上下文、履约协调、Media、Typing State 和 Read Receipt。启用的 Matrix backed Service 可以在公开 Chat Contract 后保存 Room、Membership、Message 与 Event Identity。 Chat Evidence 可以帮助解释争议，但消息写着“已付款”“已发货”“同意退款”或“已完成”不会执行状态迁移。受保护动作仍需通过 Order、Payment、Refund、Dispute 或 Fulfillment Contract。 不要在消息中放入 Credential、Recovery Material、完整 Payment Secret 或不必要的 Customer Data。Community Support Room 并不自动是私有交易渠道，除非其 Membership 与 Data Policy 明确如此。 MCP 是同一边界上的机器表面 /v1/mcp 的 MCP 提供经过认证的 Tool Discovery 与 Invocation。它不会替代 Tool 下方的 HTTP Business Contract、Capability Response、Scope Check、Request bound Approval 或 Core Command Gate。 MCP Client 不一定是自治 Agent；Agent Experience 也不必对每次读取都使用 MCP。应选择能保留 Identity、Schema、Risk、Confirmation 与 Audit 的最窄接口。 理解 Agent、Skill、Tool 与批准边界 查看 MCP 传输指南 Client Shell 与更新渠道不定义 Capability Web、Mobile、Desktop、已安装 Launcher、面向浏览器的 Shell 或 Community Mini App 可以为不同设备与发行上下文包装同一套产品契约。每个 Shell 仍负责自己的 Navigation、Storage、Rendering、Permission、Deep Link Handling、Update Policy 与 Release Compatibility。 更新渠道可以交付较新 Client，但不能让旧 Backend 支持缺失操作。Browser Extension 或 Launcher 源码存在，也不会因为能渲染 Mobazha 数据就成为公共 Plugin Runtime。具名 Shell 与自动更新行为需要自己的签名发布、兼容性、回滚、隐私与支持证据。 Browser extension Shell adoption、Universal Launcher Contract、Remote UI Plugin，以及每一种社交或 Embedded Channel 都不是当前通用公共能力。在适用 Release 明确之前，应把它们视为发行版" }, { "id": "zh-project-agent-commerce", "path": "/zh/project/agent-commerce", "canonical_url": "https://docs.mobazha.org/zh/project/agent-commerce", "title": "Agent、Skill、Tool 与批准边界", "summary": "理解 Mobazha 如何把 Agent 建议转化为有 Scope、可复核的商业动作，而不把模型、Prompt 或 Skill 当成权威。", "status": "beta", "audiences": [ "sellers", "operators", "agent builders", "developers", "security reviewers" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/agent-commerce", "label": "Agent、Skill、Tool 与批准边界" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开 Agent Kernel、MCP、Identity、Scope、Capability 与扩展契约" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "把 Agent、Skill、Tool、MCP 传输、批准与 Core 命令放在正确的权威边界。", "estimated_time": "10 分钟", "journey": "understand", "primary_action": { "label": "查看 MCP 指南", "href": "/zh/build/mcp" }, "featured_visual": { "id": "agent-commerce-boundary", "src": "/images/docs/project/agent-commerce-boundary.svg", "sha256": "e0db66ef2305b8b88849c263cfa1c7b7670202c87ce8d0b5ca4dc0e5bd9471a7", "mobile_src": "/images/docs/project/agent-commerce-boundary-mobile.svg", "mobile_sha256": "a15207ce3572657c8e9d0af4366dc89010f40b5ca788d997bfc32e8cd011c1bf", "kind": "conceptual", "width": 760, "height": 520, "mobile_width": 360, "mobile_height": 780, "alt": "Conceptual Agent-commerce execution path from a user goal through persona and scope, a Skill, current Tool discovery, request-bound approval, Core validation, and an audited result.", "caption": "Reasoning proposes an action; typed identity, scope, capability, approval, and Core state gates decide whether it executes.", "claim": "Explains current authority primitives and a safe composition model; it does not assert that every Skill, Tool, workflow, approval policy, model, or autonomous mode is available.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "agent-commerce-boundary-v1", "applies_to": "Mobazha v0.3 release-candidate product model", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/project/agent-commerce", "search_text": "辅助与权威是两种不同产品能力 Agent 可以帮助买家比较商品、帮助卖家准备 Listing、总结订单，或建议下一步运营动作。这些能力都不会让 Agent 自动获得 Identity、资金、政策或商业状态的权威。 Mobazha 把推理与执行分开。模型或 Skill 可以提出意图；类型化 Tool 把获准意图转化为有边界的请求；经过认证的后端再次评估 Scope、Capability、状态、报价、政策、批准和幂等性，然后才接纳受保护命令。 六个不同概念 概念 责任 它不会自动授予什么 Agent 维护任务会话、收集上下文、推理并呈现选择 店铺访问、消费权限或修改订单的授权 Skill 围绕抽象能力包装指令与可复用业务工作流 数据库、钱包、密钥或状态机直接访问 Tool 定义一个类型化可执行操作，包括输入输出、风险、副作用与能力要求 因为某处知道或列出了这个 Tool 就自动获得权限 MCP 或 API 传输 通过认证接口承载发现与调用 绕过网关 Identity 或领域 Scope 的通道 Approval 记录人类针对具体提议请求作出的决定 对不同 Payload、过期报价、已变化状态或无限重试的授权 Core Command Gate 校验请求并拥有获准的业务状态迁移 在没有独立检查时直接信任模型输出 使用机器可读文档界面 查看认证与 Scope 指南 理解类型化扩展边界 安全执行路径 解析上下文。 确认 Tenant、Store、Thread、Actor、持有角色，以及本次任务唯一的 Acting Persona。 选择 Skill。 只加载适用于当前 Persona、任务、发行版和有效 Capability 的 Skill。 发现 Tool。 从当前 Tool Catalog 解析具体 Tool，不凭 Prompt 记忆编造 Tool 名称。 准备请求。 校验 Schema，说明副作用，展示收款方和金额，并在需要时分配稳定幂等键。 请求批准。 对写入、金融或危险动作，把用户决定绑定到精确动作与请求 Hash。 重新校验并执行。 后端再次检查 Identity、Scope、Capability、预期状态、报价、政策、批准与新鲜度。 记录结果。 保留请求、批准、命令、订单与结果标识，同时脱敏 Credential 与个人数据。 这条路径有意比“模型调用了一个函数”更严格。同一个 Tool 请求可能对一个 Actor 和 Store 合法，对另一个则被拒绝，也可能在执行前已经失效。 Persona、Scope 与 Capability 解决不同问题 Persona 表明用户在本轮以买家、卖家、Moderator 或 Operator 中的哪个角色行动。持有多个角色不应让所有角色的 Skill 和 Tool 泄漏进同一个任务。 Scope 表明 Credential 可以请求哪些领域动作，例如读取 Listing、管理订单、读取钱包或写入 Chat。 Capability 表明当前连接的发行版和后端现在能否接纳该产品动作。 资源状态与政策 表明该动作对这一个订单、Listing、支付会话或 Thread 是否有效。 四者可能都必须满足。 ai:use 可以准入 MCP 会话，但单个 Tool 仍需要自己的领域 Scope 和底层资源检查。 Skill 是工作流，不是秘密超能力 Skill 应明确业务结果、所需抽象能力、输入、预期 Artifact、审核点和失败条件。即使具体 Tool 实现变化，Skill 仍应保持稳定。 不同发行版可以采用不同 Skill 交付方式： 本地或嵌入式纯文本 Skill 可以引导自托管工作流； 经审核的第一方 Skill 可以组合受信任 Tool； 托管商业 Skill 可以提供私有策略、模型路由或数据服务； 未来远程或加密 Skill 交付必须在具备运行时与安全证据之前保持明确标注。 源码存在、Skill 标识存在或发现一个 Prompt 文件，都不能证明连接后端已经授权、启用或安全支持该工作流。 Approval 把意图绑定到单次动作 受保护动作需要的不只是笼统的“同意”。审核界面应显示当前 Store 与 Persona、动作、受影响资源、收款方、金额或价格影响、政策后果和可逆性；持久 Approval 应绑定请求 Payload 并拥有稳定标识。 以下情况下执行仍必须失败关闭： 批准后订单或资源状态发生变化； 报价、收款目标或截止时间过期； 认证 Actor 或当前 Store 已不匹配； Tool Schema、Capability 或政策发生变化； 幂等与重放规则不允许再次尝试。 Approval 让提议动作可以复核，不会把 Core 权威移动到 Agent Runtime。 MCP 是一种执行界面，不是 Agent 产品本身 当前 Node MCP 入口在 /v1/mcp 使用经过认证的 Streamable HTTP。它是发现和调用获准 Tool 的机器界面。面向人的 Workspace、嵌入式 Assistant、计划任务、Webhook 和直接 API Client 可以使用相同底层业务契约，而不因此成为 MCP。 反过来，MCP 连接也不自动等于自治 Agent。自治还需要显式任务、Credential 生命周期、Scope、Tool Policy、预算、确认政策、失败处理和审计责任人。 查看 MCP 传输指南 查看冲突与幂等指南 沿着交易主线理解权威 当前契约与演进方向 范围 当前公开含义 必须标注为方向的内容 MCP 经过认证的 /v1/mcp 发现与调用还受 ai:use 和 Tool 领域 Scope 约束 更多客户端、更丰富 Tool 覆盖与跨界面编排 Agent Kernel Context Scope、Persona、Tool Metadata、Risk、Approval、Run、Memory 与 Provider 接口定义可复用边界 更广泛生产工作流、Policy Pack 与运营体验 Skills 纯文本和 Provider 加载的 Skill 契约可以描述可复用工作流 商业 Registry、许可交付与第三方 Skill 生态 Approval 请求绑定的批准和幂等原语支持 Human in the loop 写入 更丰富风险政策、身份升级、撤销与多方批准 商业自动化 Agent 可以在当前契约允许范围内读取、起草、比较、总结、准备并请求动作 通过证据门槛后的更多卖家、买家、客服与运营者工作流 不要因为 Kernel 存在就推断所有 Skill、Tool、模型提供商、Memory 系统、商业工作流或自治模式已经可用。连接后端的 Tool Catalog、有效 Capability、适用政策与发布证据仍是权威。 English canonical Agent commerce page" }, { "id": "zh-sell", "path": "/zh/sell", "canonical_url": "https://docs.mobazha.org/zh/sell", "title": "开设并运营 Mobazha 店铺", "summary": "从店铺设置进入商品、付款准备、履约和订单恢复，同时明确运营责任。", "status": "beta", "audiences": [ "卖家", "运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/sell", "label": "开设并运营 Mobazha 店铺" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main", "label": "Mobazha README 与发布范围" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "准备一个买家能够理解、付款并完成收货，而且已经通过完整流程验证的店铺。", "estimated_time": "6 分钟", "journey": "use", "primary_action": { "label": "准备店铺", "href": "/zh/sell/store-setup" }, "featured_visual": { "id": "seller-operating-loop", "src": "/images/docs/sell/store-operating-loop.svg", "sha256": "821c17af3a6aab26ef274d08e5de9f32e0feb08e13c4f38fda195f2f2b55f2b8", "mobile_src": "/images/docs/sell/store-operating-loop-mobile.svg", "mobile_sha256": "26f1cf6ab939bfcc90e4bb61b9b4126a40dbeaa37a8401a781813f463c138777", "kind": "conceptual", "width": 760, "height": 420, "mobile_width": 360, "mobile_height": 560, "alt": "Conceptual seller operating loop covering store identity and policy, listings, payment readiness, a test purchase, and ongoing order operations.", "caption": "A store is ready only when the complete buyer journey has been tested.", "claim": "Explains the operator responsibility sequence; it is not evidence that a specific store has completed these checks.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "store-readiness-loop-light-v2", "applies_to": "Mobazha v0.3 release-candidate guidance", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/sell", "search_text": "从店铺旅程开始 理解从 Offer 到履约的模型 区分产品结构、陈列、供应事实、已接受条款和履约证据。 准备店铺 验证身份、政策、履约和一次完整测试购买。 申请加入社群市场 遵循选中市场的卖家准入、审阅和 Catalog 规则，同时不转移订单权威。 发布商品 提供买家可核对的产品、规格、价格和可用性数据。 维护 Catalog 供应 补充受跟踪的实体库存或导入 License code，并对账部分成功结果。 配置配送 匹配目的地、费率、商品、时效和证据。 准备收款 只公开后端和运营者已经准备支持的能力。 运营订单 安全处理付款对账、履约、退款、争议和完成。 卖家运营的对象 对象 卖家责任 产品边界 Store / Node 身份、政策、能力、订单和业务状态权威 它不只是可视店面或渠道账号。 Storefront 品牌、导航、展示、域名和受众视图 在支持时，多个店面或渠道可复用店铺拥有的交易状态。 Listing revision 买家可见承诺：产品结构、选项、价格、媒体、条款和履约资格 新版本不能悄悄改变已经接受的 Quote 或订单。 Supply 与 Availability 某个可购买组合是否真的能够履约 库存、服务商供应、服务容量和选项标签是不同事实。 Collection 与 Discount 商品陈列和价格调整规则 它们组织或转换 Offer，但不拥有订单状态。 Shipping profile 目的地资格、服务、费率、时效和证据要求 对目的地没有有效履约路径时，商品不应可购买。 Payment capability 后端声明且运营者已准备好的付款路径 仅识别 Token 或服务商名称不等于就绪。 Order 已接受条款、付款状态、履约义务、恢复和完成 即使订单显示在其他渠道，后端仍是权威。 开店前 选择自行托管或可选托管服务。 配置后端和所在地区支持的付款方式。 发布买家可以查看的配送、退货、退款和争议条款。 接单前复核最终 Quote 以及所有收款方金额。 Mobazha 不会替你决定的事项 卖家仍负责产品合法性、税务、履约、客户支持和卖家自定义收费。Mobazha 提供交易软件和可验证流程，不会让所有运营者成为同一法律实体。 成本标签必须说明收款方和原因，不能用模糊的隐藏服务费代替。 店铺就绪检查清单 设置可识别的店铺身份、运营者联系路径、Locale、货币显示和适用域名。 创建包含准确规格、库存或可用性、媒体、价格和配送资格的完整商品。 接单前配置 Shipping Profile、配送时效、退货条件和履约证据。 只启用后端声明且店铺有能力监控和结算的付款方式。 在与客户相同的部署、能力集合和设备类型上测试完整买家流程。 订单运营 确认订单前复核 Order、Quote、付款状态、买家指令和履约义务。 不要根据截图、消息或 Agent 声明推断付款完成；使用后端验证后的付款状态。 通过订单流程记录发货或交付证据，不能只依赖外部聊天。 根据当前订单允许的状态转换处理取消、退款、争议和完成。 保留支持或争议审阅需要的政策、Quote、付款、履约和沟通引用。 选择运营方式 使用托管应用 选择部署方式 安装自行托管 Node 理解收费 English canonical page" }, { "id": "zh-sell-store-setup", "path": "/zh/sell/store-setup", "canonical_url": "https://docs.mobazha.org/zh/sell/store-setup", "title": "为首笔订单准备店铺", "summary": "在接受买家资金前，配置店铺身份、政策、履约、付款方式，并走完一条完整测试旅程。", "status": "beta", "audiences": [ "卖家", "运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/sell/store-setup", "label": "为首笔订单准备店铺" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/admin", "label": "Unified 卖家管理路由" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "发布一个不依赖隐藏运营步骤、能完成一条代表性买家旅程的店铺。", "estimated_time": "30–60 分钟", "journey": "use", "primary_action": { "label": "开始就绪检查", "href": "/zh/sell/store-setup#开始前" }, "language": "zh-CN", "translation_of": "/sell/store-setup", "search_text": "开始前 选择托管或自行托管，并确认后端健康。 使用目标店铺的管理员身份，不要使用来自另一部署的买家会话。 准备公开店名、联系渠道、币种显示、履约地区、退货条款和付款方式。 将恢复材料保存在浏览器之外；进行重要配置变更前先创建备份。 先确认正在修改哪个表面 管理表面 当前路由 控制内容 店铺资料 /admin/settings/profile 公开运营者身份与资料信息。 Storefront 编辑器 /admin/storefront 品牌、展示、区块与公开店面体验。 店铺政策 /admin/settings/policies 买家可见的履约、退货、退款、隐私与保障条款。 配送模板 /admin/settings/shipping 目的地资格、费率、时效与 Listing 覆盖。 付款 /admin/payments 支持时的加密货币收款账户、可用服务商、Guest Checkout 行为与付款政策。 商品 /admin/products 与 /listing/new Listing 版本、选项、可用性、价格与履约分配。 Store / Node 拥有身份、政策、能力和订单； Storefront 是这些商业状态的展示表面。一个账号能访问多个店铺时，修改任何一项前都要确认当前店铺上下文。 店铺设置步骤 打开 Admin → Settings → Profile ，核对当前店铺身份、公开运营者名称、联系渠道、地区设置与币种显示。 打开 Admin → Storefront ，只发布属于该店铺的品牌与区块；继续前先预览公开页面。 打开 Admin → Settings → Policies ，发布适合该运营者与付款模型的配送、退货、退款、隐私和买家保障条款。 打开 Admin → Settings → Shipping ，创建至少覆盖一个真实目的地和目标商品类型的模板。 打开 Admin → Payments ，只启用状态为就绪，且运营者能够监控、对账并在适用时退款的收款账户或服务商。 打开 Admin → Products 或 /listing/new ，创建一项完整 Listing，并配置有效的可用性与履约方式。 在独立买家上下文中打开 /store/{peerId} ，核对店铺身份、政策、Listing、Quote、配送和付款选择。 使用测试网订单走完卖家接受、付款验证、履约证据，以及买家完成或预期终态。 预期结果与验证 公开 Storefront 应显示目标店铺身份、展示内容、政策、Listing 版本、完整价格组成、适用于目的地的配送方式，以及仅处于就绪状态的付款方式。管理员应能在同一店铺上下文中收到测试订单，并在不依赖隐藏工具的情况下检查付款与履约状态。 失败时 公开店铺与 Admin 不一致时，确认 Store / Storefront 上下文并刷新权威设置。 Checkout 没有配送选项时，确认 Listing 已绑定适用的配送模板或数字交付路径。 付款方式缺失时，检查运行时就绪状态，不要只在前端补一个标识符。 买家与卖家路由意外共用凭据时，停止使用实质资金并报告隔离缺陷。 修改了错误店铺时，停止操作，先核对账号、Store / Node、Storefront 与 peerId 上下文。 继续 创建并验证 Listing 配置配送 准备付款方式 处理进店订单 English canonical page" }, { "id": "zh-sell-marketplace-participation", "path": "/zh/sell/marketplace-participation", "canonical_url": "https://docs.mobazha.org/zh/sell/marketplace-participation", "title": "申请在社群市场销售", "summary": "在申请、撤回或重新申请前，先阅读市场的卖家准入、审阅和 Catalog 规则。", "status": "beta", "audiences": [ "卖家", "市场运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/sell/marketplace-participation", "label": "申请在社群市场销售" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/apps/web/src/app/marketplace/%5Bslug%5D/sell/page.tsx", "label": "Unified Native Marketplace 卖家政策与测试" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "提交一项符合条件的市场申请，理解当前 Membership state，并只使用该状态允许的转换。", "estimated_time": "5–10 分钟", "journey": "use", "primary_action": { "label": "检查卖家资格", "href": "/zh/sell/marketplace-participation#开始前" }, "language": "zh-CN", "translation_of": "/sell/marketplace-participation", "search_text": "开始前 以负责目标店铺和 Product group 的卖家身份登录。 打开选中的市场，确认其身份、运营者、Seller entry mode、Seller review mode 和 Catalog mode。 把市场 Membership 视为发现与策展关系。批准不会把 Store、Listing、Quote、Payment 或 Order authority 转移给市场。 只有部署公开市场卖家页且市场允许自助申请时才继续。 operator invited 市场不接受自助申请。没有 Submit control 是政策结果，不是调用隐藏 Route 的理由。 申请加入市场 打开市场的 Sell 入口，通常是 /marketplace/{slug}/sell 。 选择商品前阅读显示的 Seller entry、Review、Buyer access 和 Catalog 规则。 Curated catalog 要求选择至少一个属于当前卖家的 Product group。即使 Group 目前有零个商品，也可以符合申请条件。Open catalog 可以允许不选 Group 提交。 复核选中 Group 并提交一次。请求进行时 Submit control 仍显示但不可再次点击。 阅读返回的 Membership state。Automatic review 可能立即批准；Manual review 通常记录 applied 并等待运营者决定。 返回同一卖家页查看 Review update。Notification 可以把用户带到该页，但当前 Application 和 Membership record 才决定状态。 理解当前状态 状态 卖家可以得出的结论 可用下一步 No application 没有当前自助申请 市场允许时选择所需 Group 并提交 applied 申请已存在并等待决定 保持选择锁定；产品提供时可以撤回 approved 市场已按当前政策接受卖家 检查哪些 Group 和 Listing 可见；批准不证明订单已就绪 rejected 申请被拒绝 阅读可用 Decision reason；只有当前政策公开提交时才重新申请 left 卖家已撤回或离开 当前政策允许时重新申请 suspended 运营者已暂停参与资格 不要自助重新申请；使用市场运营者公开的复核路线 当申请处于 applied 、 approved 或 suspended 时，Group selection 保持锁定，防止本地 Draft 悄悄改变活动 Membership 关联的 Group。 预期结果与验证 卖家页应为选中的市场与卖家上下文显示一项当前 Application 和 Membership state。刷新后核对 Marketplace identifier、Store 或 Seller identity、选中的 Product group identifier、Review mode 和当前状态。 卖家获得批准后，还要单独确认目标 Group 或 Listing 在市场中可见，并且买家 Handoff 仍解析到正确的卖家后端。Membership 本身不能证明 Availability、Price、Payment readiness 或 Fulfillment readiness。 失败时 Curated market 中 Submit 被禁用时，选择至少一个符合条件的 Product group，并确认它属于当前卖家。 市场由邀请控制时，不要反复提交 API 请求；使用运营者公开的准入路线。 Submit 或 Withdraw 结果未知时，重试前刷新当前 Application。延迟响应可能已经改变 Membership state。 在 rejected 或 left 后，只有页面再次公开提交动作时才新建申请。Suspended seller 不能自助重新申请。 Notification 与卖家页不一致时，以刷新后的 Membership record 为准，并使用脱敏标识符报告过期通知。 继续 理解市场与发现 维护 Product group 与供应 验证买家 Checkout 边界 English canonical page" }, { "id": "zh-sell-listings", "path": "/zh/sell/listings", "canonical_url": "https://docs.mobazha.org/zh/sell/listings", "title": "创建并验证 Listing", "summary": "发布一项准确说明选项、价格、可用性、履约和买家可见条款的商品。", "status": "beta", "audiences": [ "卖家" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/sell/listings", "label": "创建并验证 Listing" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/listing", "label": "Unified Listing 编辑器与 Node Listing API" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "发布一项买家能够理解、取得 Quote，并通过预定履约路径购买的 Listing。", "estimated_time": "15–30 分钟", "journey": "use", "primary_action": { "label": "准备 Listing 输入", "href": "/zh/sell/listings#开始前" }, "language": "zh-CN", "translation_of": "/sell/listings", "search_text": "开始前 准备真实的标题、说明、媒体、价格、数量或服务容量，以及交付条件。 确定商品是实体、数字内容、服务，还是其他受支持的 Listing 类型。 发布前配置必要的配送或交付支持。 不要因为 Token 或付款能力的标识符可以解析，就把它写成可用。 选择正确的创建入口 入口 适用场景 可用性说明 /admin/products 检查发布状态、可用性、价格与既有 Listing。 主要管理表面。 /listing/new 使用商品类型字段、媒体、选项、价格和履约信息创建完整 Listing。 首个代表性商品的首选入口。 /listing/quick 以较少字段开始，再补全 Listing。 只在当前 distribution 提供该入口时使用。 /listing/import 或 Admin import 将外部目录数据规范化为 Mobazha Listing 与供给事实。 导入后仍须卖家审核与发布。 /admin/collections 把已发布 Listing 整理为买家可见的分组。 只负责陈列，不改变订单权威。 /admin/discounts 定义适用的价格调整与优惠码。 已接受的 Quote 必须显示应用后的结果。 分开处理商品形态、选项与供给 事实 示例 为什么要分开 商品类型 实体商品、数字商品、服务、收藏品或其他受支持类型 决定必填的履约与买家可见字段。 选项 颜色、尺寸、授权等级、服务时长 买家选择的 Offer 属性。 Variant / SKU 蓝色 + 大号，或 Pro + 年付 标识可购买组合，不代表供应商身份。 可用性 库存、服务商供给、服务容量或资格 回答该组合目前能否履约。 履约 配送模板、数字交付、预约、兑换或服务商路径 回答如何兑现已接受的承诺。 Listing 步骤 打开 Admin → Products ，确认当前店铺；第一个代表性 Offer 使用完整的 /listing/new 入口。 先选择商品类型，再填写标题、说明、分类、买家可见媒体和类型专属事实。 使用正确精度填写价格与币种；以渲染金额为准，不要只信任存储的整数单位。 添加选项维度与 Variant。只在受支持且确有用途时，为每个可购买组合设置有意义的 SKU 或标识。 把可用性与选项名称分开配置：本地库存、服务容量、服务商供给或其他受支持来源。 按商品类型和目的地分配配送、数字交付、服务履约、兑换或其他有效路径。 加入卖家实际能够履行的退货、退款、保修、资格或兑换条件。 保存 Draft，在买家上下文预览 /product/{slug} ，然后发布。 适用时将 Listing 加入 Collection 或设置 Discount；随后请求新 Quote 并核对结果，不要假设陈列变更已正确进入订单。 预期结果与验证 在买家上下文打开公开商品 URL，核对标题、媒体、商品类型、选项、Variant 可用性、显示价格、卖家身份、政策和适用于目的地的履约方式。把商品加入购物车并请求新 Quote，继续到 Checkout 出现有效的配送和付款路径；发布成功本身不能证明 Offer 可以生成订单。 失败时 商品已保存但未公开时，检查发布状态、Storefront 上下文、索引与运行时能力。 某选项无法购买时，检查 Variant 完整性与可用性。 价格渲染错误时，停止发布并核对金额单位、币种和精度。 无配送方式时，将 Listing 分配到适用模板并重新测试买家目的地。 导入或服务商供给的商品已公开但不可用时，检查规范化后的 Supply 记录，不要在选项字段中虚构库存。 变更安全 编辑已有活跃订单的 Listing 时，保留买家已接受的版本和条款。新 Listing 版本不得静默改写已创建订单。 English canonical page" }, { "id": "zh-sell-catalog-operations", "path": "/zh/sell/catalog-operations", "canonical_url": "https://docs.mobazha.org/zh/sell/catalog-operations", "title": "批量维护多个商品的供应", "summary": "批量补充受跟踪的实体库存或导入 License code，同时保留部分失败信息且不改变无限供应。", "status": "beta", "audiences": [ "卖家", "店铺运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/sell/catalog-operations", "label": "批量维护多个商品的供应" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/apps/web/src/app/admin/products/page.tsx", "label": "Unified Admin 商品批量操作实现与测试" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "按预期供应模式更新选中商品，逐项验证结果，并只重试失败项目。", "estimated_time": "5–15 分钟", "journey": "use", "primary_action": { "label": "准备批量操作", "href": "/zh/sell/catalog-operations#开始前" }, "language": "zh-CN", "translation_of": "/sell/catalog-operations", "search_text": "开始前 使用目标店铺上下文中的卖家或管理员身份。 确认连接部署提供 Admin → Products 及适用批量操作。源码存在不表示每个部署都提供该操作。 批量变更前记录选中的 Listing slug、当前供应模式和当前数量。 把受跟踪的实体库存和数字 License code 分开，它们使用不同操作和失败规则。 License code 是履约秘密。不要把它们放入聊天、截图、支持 Issue、Analytics，或错误商品的批次。 增加受跟踪的实体库存 在正确店铺上下文中打开 /admin/products ，只选择需要改变的实体商品。 选择批量补货。只有使用 Tracked stock 的 Listing 符合条件；以 1 表示的无限数量不会被补货。 输入正整数。相同增量会加到每个选中 Listing 的所有受跟踪 SKU Variant；它不是新的最终数量。 复核目标标题和数量，然后确认一次。 阅读成功和失败数量。重新打开或刷新受影响的 Listing，核对每个 Variant，而不是只相信 Toast。 导入 License code 只选择供应模式为 License code 的 Listing，然后打开批量 License code 导入。 在对应 Listing 的字段输入 Code。换行和逗号用于分隔，空白条目会被忽略。 将每个 Listing 显示的解析数量与计划导入的来源对照。 确认一次。结果会报告成功的 Listing 数量及其导入 Code 总数。 通过 Listing 或履约流程验证可用供应。检查数量时不要暴露已导入值。 预期结果与验证 每个选中 Listing 都有独立结果。成功的实体补货会保留 Listing 结构，并把请求数量加到每个受跟踪 SKU；成功的 License code 导入会报告该 Listing 的导入数量。 结果 含义 安全下一步 Success 指定 Listing 操作成功返回 刷新并验证该 Listing 的供应状态 invalid quantity 补货增量为零或负数 修正输入；没有有效补货请求 not found 无法载入选中的 Listing 重试前确认 Store context 与 Slug not physical 非实体 Listing 进入实体补货路径 使用该 Listing 类型对应的供应操作 untracked stock 所有 SKU 都使用无限供应 保持不变，除非有意把 Listing 改为受跟踪库存 no keys 没有为该 Listing 分配 License code 只有确实需要时才添加 Code 其他失败 Listing 更新或 License 导入未完成 刷新当前状态，只重试失败 Listing 失败时 部分失败后不要重复整个批次，成功项目可能已经改变。 重试前刷新每个失败 Listing，避免覆盖并发编辑。 如果显示结果数量与 Listing 状态不一致，保留 Slug 和脱敏错误并获取帮助。 如果错误 Listing 收到数量变更，通过普通 Listing Editor 修正并保留审计说明；不要直接编辑数据库。 如果 License code 可能泄露或分配错误，停止使用受影响 Code，并执行店铺的秘密轮换和买家支持流程。 继续 发布和修改 Listing 准备履约与配送 运营订单 English canonical page" }, { "id": "zh-sell-shipping", "path": "/zh/sell/shipping", "canonical_url": "https://docs.mobazha.org/zh/sell/shipping", "title": "配置配送与交付", "summary": "定义商品可送达范围、向买家收取的费用，以及卖家履约后记录的证据。", "status": "beta", "audiences": [ "卖家", "运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/sell/shipping", "label": "配置配送与交付" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/admin/settings/shipping", "label": "Unified 配送模板与 Node Listing 合约" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "只提供适用于买家目的地、并会保留在已创建订单中的交付方式。", "estimated_time": "15–30 分钟", "journey": "use", "primary_action": { "label": "梳理交付要求", "href": "/zh/sell/shipping#开始前" }, "language": "zh-CN", "translation_of": "/sell/shipping", "search_text": "开始前 列出发货地、支持的目的地、交付方式、预计时间与计价规则。 确定每个配送模板适用哪些 Listing。 说明不配送地区、关税责任、追踪能力与退货处理方式。 配送如何进入 Mobazha 订单 阶段 权威事实 要避免的错误 配送模板 在 /admin/settings/shipping 配置的区域、服务、费率、时效与条件 把一个全局费率视为适用于所有 Listing 和目的地。 Listing 分配 实体商品版本在 Listing 的 Shipping 区块绑定适用模板 发布无法送达买家目的地的商品。 Quote 目的地与所选服务生成买家可见的运费与时效 地址、数量或模板变更后继续复用目录估算。 订单快照 已接受的交付服务、金额、目的地义务与卖家承诺保留在订单中 让后续模板编辑静默改变既有订单。 履约证据 承运商、追踪号、交接、数字证明、服务完成或其他受支持记录 没有适合商品类型的证据就把订单标为已履约。 配送设置步骤 打开 Admin → Settings → Shipping （ /admin/settings/shipping ）。 创建或选择代表一套一致履约政策的模板。 添加目的地区域，确保重叠是有意且易于理解的。 添加买家可见的服务名称、金额、币种、条件与预计送达时间。 打开每项实体 Listing 的 Shipping 区块并分配适用模板；移除数字商品、服务或需要其他交付路径的商品。 保存后测试区域内、区域外及每个支持区域边界上的地址。 完成测试订单，并通过订单流程记录承运商、追踪号或其他交付证据。 预期结果与验证 Checkout 应只显示适用于商品和目的地的交付方式。所选运费必须出现在最终成本明细中，并与已创建订单关联；卖家订单视图应保留所选服务与义务。 修改模板后，测试一份新 Quote，同时确认已经接受的订单仍显示原始交付承诺。 失败时 没有选项时，检查目的地规范化、模板分配、Listing 类型与区域覆盖。 出现重复选项时，检查重叠区域与重复模板分配。 Checkout 金额与配置不符时，停止接单并核对币种与计算基准。 无法保存追踪信息时，私下安全保存引用并报告状态转换缺陷。 数字商品与服务 不要为了让 Checkout 通过而给数字商品或服务附加实体运费。应使用受支持的交付合约，并分别说明访问、预约、兑换或证据。 English canonical page" }, { "id": "zh-sell-payments", "path": "/zh/sell/payments", "canonical_url": "https://docs.mobazha.org/zh/sell/payments", "title": "为销售准备付款方式", "summary": "只展示 distribution 允许、已配置、健康，并由店铺后端持续监控的付款方式。", "status": "beta", "audiences": [ "卖家", "运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/sell/payments", "label": "为销售准备付款方式" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/admin/payments", "label": "Node 付款能力与 Unified 付款管理" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-13", "outcome": "只有在配置、健康、观察和恢复路径都得到验证后，才启用一种付款方式。", "estimated_time": "20–40 分钟", "journey": "use", "primary_action": { "label": "开始付款就绪检查", "href": "/zh/sell/payments#开始前" }, "language": "zh-CN", "translation_of": "/sell/payments", "search_text": "开始前 评估候选版本时使用测试网与可丢弃订单。 确认该方式被 distribution 允许，并由后端实现。 了解密钥托管、观察、确认、退款路径、费用与外部依赖。 备份恢复材料；绝不要把 seed 或私钥输入文档、聊天或无关服务商表单。 把付款就绪理解为会话，而不是一个标志 订单详情通过 /v1/orders/{orderID}/payment session 解析 Payment Session。付款方式标志或 Admin 开关不能替代下列与订单绑定的事实： Payment Session 字段 回答的问题 paymentCoin 预期使用哪个 canonical 加密资产，或哪个法币服务商/币种？ settlementMode 是地址监控、服务商 Checkout、escrow，还是其他受支持结算路径？ productMode 订单是 direct、cancelable，还是 moderated？ fundingTarget 当前适用的准确地址或服务商会话、金额、资产、memo 与 QR payload 是什么？ paymentProgress 已观察到什么、还差多少、有多少 observation，当前 funding 状态是什么？ expiresAt 何时必须刷新指示，而不能继续复用目标？ capabilities 当前允许 refresh、cancel、confirm、refund 或 completion 中的哪些操作？ userActionRequest 还需要用户明确执行哪个钱包或服务商操作？ 不要把 付款就绪 、 资金观察 、 验证 与 结算 合并成一个状态；它们回答不同的运营问题。 付款就绪步骤 打开 Admin → Payments （ /admin/payments ），检查收款账户、服务商、Guest Checkout 政策，以及后端报告为就绪的付款方式。 选择一种方式，只完成其文档列出的设置要求。 验证配置与健康状态，不要只依赖前端开关。 按该付款方式设置或复核确认与付款过期行为。 创建小额测试网订单，将显示的 Payment Session ID、订单 ID、canonical asset、settlement mode、funding target、预期金额与 expiry 和后端状态逐项对照。 广播或授权测试付款，并区分 observed progress 与后端拥有的 funded 状态。 重新打开订单详情，确认 capabilities 只提供当前状态有效的操作。 接受实质订单前，演练适用的取消或退款路径。 对于 attempt scoped 的标准加密货币付款，只有在必要的卖家与 moderator offer、冻结的结算条款和授权 bundle 一致后，funding target 才可操作。如果 Affiliate attribution 或其他订单特性不被该确切路径支持，后端必须在创建 Draft 前保持路径不可用；前端不能只凭 coin 或 rail 推断支持。 预期结果与验证 只有完整的 effective capability 交集就绪时，该方式才应出现在 Checkout。付款观察必须绑定预期订单、资产、地址、金额、预期状态与确认政策；识别到代码或安装了 adapter 并不足够。 失败时 设置不完整时保持方式不可用，不要静默降级。 健康状态未知时停止展示新的 Checkout 工作，同时保留既有恢复路径。 观察到错误金额或目的地的付款时，不要自动结算。 会话显示 awaiting seller receipt 时，不要描述为买家付款延迟；此时卖家侧 funding target 尚未就绪。 不要让买家向废弃或不兼容 attempt 留下的地址付款；刷新 Payment Session，只使用当前可操作目标。 服务商 Checkout 或钱包操作失败时，重试前保留订单与 Payment Session 标识符。 退款路径不可用时，在接受该付款方式前披露限制。 当前发布边界 公开客户端与后端包含多种付款 adapter 和兼容路径，但实际可用性由 distribution 政策、后端实现、店铺配置、健康状态、订单模式和 Payment Session capabilities 在运行时共同决定。Token 标识符或源码模块不会创造发布承诺。参见发布范围与收费与经济模式。 只有当服务商路径能让卖家出款保持 pending（或保留等价的可逆资金状态），并支持所需恢复操作时，provider session payment 才能提供 moderated product mode。服务商自己的付款争议或 chargeback 流程，与 Mobazha moderator 的订单决定仍是两件事。 English canonical page" }, { "id": "zh-sell-orders", "path": "/zh/sell/orders", "canonical_url": "https://docs.mobazha.org/zh/sell/orders", "title": "处理进店订单", "summary": "核对付款、确认义务、记录履约证据，并只使用状态允许的取消、退款、争议与完成操作。", "status": "beta", "audiences": [ "卖家", "运营者", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/sell/orders", "label": "处理进店订单" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/admin/orders", "label": "Unified 订单管理与 Node 订单状态合约" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "只使用当前状态有效的操作，把一笔已付款订单推进到履约。", "estimated_time": "每次检查约 5 分钟", "journey": "use", "primary_action": { "label": "检查进店订单", "href": "/zh/sell/orders#开始前" }, "language": "zh-CN", "translation_of": "/sell/orders", "search_text": "开始前 接单前发布履约与退款政策。 监控后端、付款依赖、库存与买家沟通。 区分订单通知与权威订单、付款状态。 把订单工作区看成四组相连记录 当前客户端在 /admin/orders 提供卖家工作区，在 /orders/{orderId} 提供订单详情。详情可分别展示 Summary、Discussion、Dispute 与 Evidence；任何一项都不能替代其他记录。 记录 用途 权威规则 Order summary 已接受的 Listing 快照、参与方、金额、交付义务、当前状态与有效操作 每次重要状态转换后重新加载。 Payment Session Funding target、观察、验证、过期、settlement mode 与当前 capabilities 回执或聊天陈述不是付款权威。 Discussion 与订单绑定的买卖双方协调 保留有用上下文，但不能只凭消息文本执行受保护状态。 Dispute 与 Evidence 请求的 remedy、提交材料、履约记录与适用裁决路径 保留原始证据，并遵守角色、政策和状态允许的操作。 订单处理步骤 打开 Admin → Orders （ /admin/orders ），选择目标店铺与订单。 核对卖家身份、商品版本、数量、选项、交付义务、总额与买家指示。 检查订单绑定的 Payment Session，并从后端拥有的状态验证资金；不要依赖截图或聊天消息。 只有在库存、政策和履约能力仍有效时才接受或确认。 严格按订单履约，并记录承运商、追踪号、数字交付、服务或其他受支持证据。 分别使用 Discussion、Dispute 与 Evidence；对取消、退款或争议，只执行当前状态与角色允许的操作。 只有已实现的交付与付款 gate 均满足后才完成订单。 按政策保留订单、Quote、付款、履约和沟通引用。 预期结果与验证 每个卖家操作都应产生新的权威状态或明确错误，并保留之前可恢复的状态。每次资金或履约状态转换后重新打开订单，核对状态、时间戳、证据以及由此产生的付款操作。 失败时 收到重复通知时，以订单与事件标识去重，并重新加载当前状态。 付款与订单不一致时，停止履约或结算自动化并核对付款引用。 履约证据保存失败时，安全保存证据，再通过受支持的转换重试。 操作返回 conflict 时，先刷新状态，再判断是否已由另一参与方完成。 Extension 不健康时，让 Core 资金状态转换 fail closed，并按恢复流程处理。 Discussion、Payment Session 与 Order summary 不一致时，保留标识并在行动前重载权威订单。 Agent 边界 Agent 可以总结并准备操作，但没有所需身份、scope、状态、政策与人类确认时，不得确认、退款、结算或完成订单。 English canonical page" }, { "id": "zh-buy", "path": "/zh/buy", "canonical_url": "https://docs.mobazha.org/zh/buy", "title": "从独立 Mobazha 店铺购买", "summary": "围绕拥有订单的店铺完成结账、付款、订单跟踪、取消、退款和争议流程。", "status": "beta", "audiences": [ "买家", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/buy", "label": "从独立 Mobazha 店铺购买" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified", "label": "Mobazha Unified 公开客户端" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "在投入资金前看清店铺运营者、完整成本和订单恢复路径。", "estimated_time": "5 分钟", "journey": "use", "primary_action": { "label": "打开托管应用", "href": "https://app.mobazha.org" }, "featured_visual": { "id": "buyer-order-lifecycle", "src": "/images/docs/buy/order-lifecycle.svg", "sha256": "ae6227f538038f4be74d93a3402810cb7220802eb98850c6ae610c7ebcdc3e93", "mobile_src": "/images/docs/buy/order-lifecycle-mobile.svg", "mobile_sha256": "712799d325a9e67bcec89e5021cb25777bde7e960f886c01d64a95dd0f7f6567", "kind": "conceptual", "width": 760, "height": 420, "mobile_width": 360, "mobile_height": 560, "alt": "Conceptual buyer journey from reviewing one seller quote through payment, fulfillment, and completion, with recovery actions dependent on active order state.", "caption": "One seller-owned order, from reviewed quote to observable completion.", "claim": "Explains the documentation authority and milestone model; it does not assert that every deployment exposes every transition.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "buyer-order-path-light-v2", "applies_to": "Mobazha v0.3 release-candidate guidance", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/buy", "search_text": "选择要完成的任务 完成结账 根据一份已审阅报价创建一笔订单。 使用 Guest Checkout 不关联账号购买，并保留可恢复的跟踪链接。 跟踪订单 对照付款证据与后端拥有的订单状态。 响应订单通知 通过事件进入相关记录，再刷新权威状态后行动。 取消、退款或争议 使用当前订单状态允许的转换。 Mobazha 的购买模型 Mobazha 不会把商品页面、钱包转账和订单当成同一条记录。买家流程会经过几个明确对象： 对象 回答的问题 不应做的假设 店铺与后端 谁发布 Offer、谁拥有订单状态？ 发现站点、社群或 Agent 不会因此自动拥有交易。 Quote 当前商品版本、规格、目的地、配送、折扣和总额是什么？ 商品页价格或旧截图不是已接受总额。 订单 哪些条款已接受、当前允许哪种状态转换？ 后续编辑商品不能重写已有订单。 Payment Session 当前订单使用哪个资产或服务商、目标、金额、有效期和验证规则？ 广播、授权、观察、验证和最终结算不是同一状态。 恢复路径 当前可用取消、退款、买家保护或争议中的哪一项？ 不同付款轨道和政策没有统一保证的恢复动作。 付款前应看到什么 决策 买家应看到的内容 权威来源 谁接收订单 卖家身份，以及服务该店铺的后端或运营者 店铺和订单所有者 订单成本 商品、配送、税费、折扣、服务商或网络费用、可选服务和最终总额 当前 Quote 如何付款 资产、目标、金额、有效期和所需确认 当前订单和支付系统 后续会发生什么 当前订单可用的取消、退款、履约证据和争议路径 当前订单状态和公开政策 确认前 核对店铺身份以及服务该店铺的后端或运营者。 查看小计、配送、税费、网络成本、服务费用、折扣和最终总额。 阅读取消、退款、证据和争议规则。 Agent 建议是辅助，不是绕过用户确认或消费 Scope 的授权。 如果购物车包含多家店铺的商品，应分别确认每个卖家订单的店铺边界和 Quote。 保留证据 保存订单标识、Quote、付款引用、消息、履约证据和结账时展示的政策版本。这些记录能提高支持和争议处理的可靠性。 结账与付款 请求 Quote 前确认商品、数量、规格、卖家、配送目的地和方式。 阅读完整成本分配：商品小计、配送、税费、折扣、网络或服务商成本、可选服务和最终总额。 只使用当前订单显示的付款方式、资产、地址、金额、有效期和确认指令。 不要复用其他订单、消息、截图或 Agent 回复中的过期 Quote 或付款目标。 等待权威付款与订单状态，不要把广播、待确认交易或回执图片当成最终结算。 履约、取消与争议 使用当前订单实际提供的取消和退款动作，不要假设存在统一期限。 检查卖家履约证据，并以原始形式保存买家证据。 产品提供争议入口时，通过该入口提交，并清楚说明期望补救方式。 支付轨道或 Escrow 只能执行已经实现的条件，不能保证商品质量或特定争议结果。 涉嫌欺诈或安全问题时进行升级，但不要公开订单、身份或付款隐私数据。 继续 打开托管应用 检查收费与经济模式 获取帮助 English canonical page" }, { "id": "zh-buy-checkout", "path": "/zh/buy/checkout", "canonical_url": "https://docs.mobazha.org/zh/buy/checkout", "title": "完成买家 Checkout", "summary": "创建或资助订单前，核对一个店铺、一份 Quote 和一套付款指示。", "status": "beta", "audiences": [ "买家", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/buy/checkout", "label": "完成买家 Checkout" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/apps/web/src/app/checkout", "label": "Unified Checkout 路由与 Node 订单合约" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "从已核对的卖家 Quote 创建订单，并保留恢复所需标识符。", "estimated_time": "5–10 分钟", "journey": "use", "primary_action": { "label": "开始 Checkout 检查", "href": "/zh/buy/checkout#开始前" }, "language": "zh-CN", "translation_of": "/buy/checkout", "search_text": "开始前 核对店铺身份、商品、数量、Variant、履约方式与退货政策。 使用连接到目标店铺与后端的当前浏览器会话。 确定使用账号 Checkout，还是店铺可选的 Guest Checkout。 准备准确的付款资产；在订单显示地址、金额和过期时间前不要转账。 绝不要复用其他订单、消息、截图或 Agent 回答中的地址、QR code、Quote 或金额。 Checkout 步骤 打开 /product/{slug} ，核对卖家与店铺上下文，选择必填选项并加入购物车。 打开 Cart ，确认每项商品属于目标卖家。Marketplace 可以组织发现并记录 attribution，但必须由获准卖家而不是 Marketplace projection 拥有 Checkout handoff 和产生的订单。 继续到 /checkout ；只填写此订单需要的交付与联系资料，并在需要时选择适用于目的地的配送方式。 核对商品小计、运费、折扣、税费、网络或服务商成本、可选服务与最终总额。 在付款方式步骤选择当前可用方式。可用性来自连接的后端与店铺政策，而不是本指南中的静态列表。 如果订单模式要求 moderator 或其他保障选择，确认前查看其范围与成本。 只有在卖家、收件人、最终总额、付款资产或服务商、适用政策及保障选择都清晰可见时才确认订单。 确认后保存订单标识符与追踪链接，再从订单绑定的 Payment Session 取得地址、服务商 payload、金额、过期时间与进度。 使用外部钱包付款 只使用应用订单政策后仍可见的付款选项。Protection 或 Settlement mode 可能有意移除缓存中的服务商或付款轨道。 在当前 Payment Session 中核对资产或 Token、显示时的 Network、准确金额、付款地址或 URI、Expiry 和 Order identifier。不能根据商品目录价格自行拼出这些值。 扫描当前 QR code，或复制当前地址与金额。在钱包中批准转账前，再将钱包解析的 Recipient 和 Amount 与 Payment Session 对照。 广播后保留 Transaction identifier，并让订单保持可供对账。分别读取 Observed transfer、Observed 或 Remaining amount、Observation status 和 Confirmation。 付款指令过期后停止使用其 QR code、URI、Address 和 Amount。通过产品刷新取得当前指令，不要向过期目标付款。 已观察到的转账仍可能处于 Pending、金额不足、已经 Reverted、使用错误网络，或未达到所需金额。只有后端的 Funded order state 才能证明该订单已经接受付款证据。 预期结果与验证 应用应显示带有权威状态和订单绑定 Payment Session 的新订单。核对商品版本、卖家、卖家拥有的后端、总额、canonical payment asset 或 provider、funding target、金额、settlement mode 与 expiry 是否和最终确认一致。Marketplace 页面或 referral 标签不是卖家，不得静默成为订单 owner。 不要把钱包广播、截图或 pending transaction 当作付款完成。等待订单页报告所需确认数与 funded 状态。 等待付款或付款验证的订单应留在付款流程。Canceled、Declined、Expired、Refunded 或 Processing error 订单不能显示为付款成功。已付款或履约状态可以进入确认页，但订单详情仍是恢复权威。 失败时 Quote 过期时返回 Checkout 请求新 Quote，不要发送旧金额。 商品变为不可用时返回 Cart 重新评估，不要反复提交。 付款资产或目的地意外变化时停止操作，核对店铺与后端身份。 订单已创建但页面丢失时，使用已保存的订单标识符或 Guest Order 追踪链接。 资金已发出但状态未推进时，保留 transaction ID 与 order ID，并按订单状态故障排查处理。 继续 安全使用 Guest Checkout 不附加卖家或管理员会话即可购买。 追踪付款与订单状态 理解当前状态能证明什么。 取消、退款与争议 只使用当前订单可用的转换。 English canonical page" }, { "id": "zh-buy-guest-checkout", "path": "/zh/buy/guest-checkout", "canonical_url": "https://docs.mobazha.org/zh/buy/guest-checkout", "title": "安全使用 Guest Checkout", "summary": "创建不绑定买家账号的订单，同时保留店铺路由上下文和可恢复的追踪链接。", "status": "beta", "audiences": [ "买家", "卖家", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/buy/guest-checkout", "label": "安全使用 Guest Checkout" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/packages/core/services/api/guestCheckout.ts", "label": "Unified Guest Checkout 实现与 Node 公开 Guest API" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "创建一笔不把买家账号附加到请求、并且可以恢复的订单。", "estimated_time": "5 分钟", "journey": "use", "primary_action": { "label": "检查 Guest Checkout 就绪状态", "href": "/zh/buy/guest-checkout#开始前" }, "language": "zh-CN", "translation_of": "/buy/guest-checkout", "search_text": "开始前 店铺必须展示 Guest Checkout，并至少有一种就绪的付款方式。 在同一个店铺完成购物车；Guest Checkout 不会合并无关店铺上下文。 准备立即保存生成的订单 token 或追踪链接；两者都丢失后可能难以恢复订单。 Guest Checkout 提供匿名 transport，不代表可以豁免店铺政策、付款确认或合法交付所需信息。 Guest Checkout 步骤 把符合条件的商品加入购物车并继续 Checkout。 在店铺提供该选项时选择 Guest Checkout 。 提交个人信息前，查看交付字段与卖家政策。 让应用请求 Supply Quote；它仅供参考，本身不会保留库存。 从后端当前展示的付款方式中选择一种。 创建订单后，立即把订单 token 或买家追踪链接保存到当前分页之外。 只按显示的地址与金额，在显示的过期时间前付款。 重新打开追踪链接，查看确认、配送证据与完成状态。 预期结果与验证 买家请求不应携带管理员、卖家或之前存储的用户凭据。请求可以保留同源店铺路由上下文，以到达正确店铺。追踪页面应显示订单 token、付款资产、付款目的地、所需确认数、过期时间和里程碑状态。 里程碑 含义 不能证明 Awaiting payment 订单已存在，等待所显示的付款 资金已结算 Funded 后端已接受所需付款证据 实体商品已送达 Shipped 卖家已记录发货或交付证据 买家已经收到或接受商品 Completed 订单到达完成转换 所有外部陈述或保修都得到保证 失败时 没有 Guest Checkout 时，后端可能已禁用、未通过就绪检查，或要求账号 Checkout。 追踪链接丢失时，不要创建多笔已付款订单；用脱敏付款证据联系卖家。 既有登录似乎影响 Guest 请求时，停止操作并报告可复现的客户端缺陷。 付款过期时，不要在未刷新订单指示的情况下付款。 安全与隐私 只向确有需要的参与方分享追踪链接。不要公开发布订单 token、交付资料或交易证据。Agent 可以帮助解释流程，但没有明确确认时不得创建或资助订单。 English canonical page" }, { "id": "zh-buy-order-status", "path": "/zh/buy/order-status", "canonical_url": "https://docs.mobazha.org/zh/buy/order-status", "title": "追踪付款与订单状态", "summary": "在判断订单是否已资助、发货、可退款或完成前，对照钱包证据与后端拥有的订单状态。", "status": "beta", "audiences": [ "买家", "支持人员", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/buy/order-status", "label": "追踪付款与订单状态" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/apps/web/src/components/orders/guestOrderStages.ts", "label": "Unified 订单里程碑与 Node Order API" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "判断当前订单状态能证明什么，以及下一步采取哪项恢复操作才安全。", "estimated_time": "3 分钟", "journey": "use", "primary_action": { "label": "核对订单", "href": "/zh/buy/order-status#开始前" }, "language": "zh-CN", "translation_of": "/buy/order-status", "search_text": "开始前 保留订单标识符或 Guest Order token，以及付款 transaction ID。 使用创建订单时的同一店铺与后端。 不要把私钥、恢复短语、已认证追踪 URL 或完整客户资料贴入支持聊天。 追踪步骤 对账号购买打开 Orders ；对 Guest Order 打开已保存的追踪链接。 解释状态前先核对卖家、商品、金额、付款资产与创建时间。 打开订单绑定的 Payment Session，将 session ID、canonical asset、funding target、预期金额、settlement mode 与 expiry 和钱包或服务商记录对照。 分别读取 observed amount、remaining amount、observations、适用时的 confirmations，以及后端 funding 状态。 事件通知状态变化时，通过产品 UI 或 GET /v1/orders/{orderID}/payment session 刷新。 采取下一项可用操作前，保存履约、取消、退款或争议证据。 预期结果与验证 订单页应显示由后端拥有、单调推进的业务状态视图。WebSocket 事件或钱包通知只是刷新信号；重要决定应通过已认证 HTTP API 或追踪端点复核当前订单。 观察结果 安全结论 Payment target ready 订单已有买家可在过期前使用的地址或服务商会话 Transaction broadcast 钱包尝试发布交易 Transaction detected 付款系统观察到候选交易 Required confirmations reached 已可能满足配置的确认 gate Backend state is funded 订单后端已接受这笔订单的付款证据 Seller marked shipped 已记录履约证据，仍需检查证据内容 Payment Session capability set，而不是静态按钮列表，决定 refresh、cancel、confirm、refund 或 completion 中哪些操作当前可用。 失败时 No transaction detected： 核对资产、网络、目的地、金额与 expiry，不要发送第二笔付款。 Confirmations stalled： 独立检查付款网络，并保留 transaction ID。 Wallet confirmed but order awaiting payment： 私下向运营者提供准确的 order 与 transaction 标识符。 不同页面状态冲突： 停止自动化操作并报告一致性缺陷。 追踪链接无法打开： 确认它属于当前 deployment 且未被截断。 恢复与升级处理 不要通过数据库编辑或直接 settlement call 修复买家订单。使用订单状态提供的操作，再携带脱敏证据获取帮助。 English canonical page" }, { "id": "zh-buy-order-notifications", "path": "/zh/buy/order-notifications", "canonical_url": "https://docs.mobazha.org/zh/buy/order-notifications", "title": "响应订单与争议通知", "summary": "使用通知进入相关订单或案件，再刷新权威状态，然后决定是否付款、履约、退款或争议。", "status": "beta", "audiences": [ "买家", "卖家", "支持人员", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/buy/order-notifications", "label": "响应订单与争议通知" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/apps/web/src/app/notifications/page.tsx", "label": "Unified 通知路由、分组与状态测试" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-14", "outcome": "把通知路由到目标业务记录，验证当前后端状态，并避免依据过期或不完整事件行动。", "estimated_time": "3–5 分钟", "journey": "use", "primary_action": { "label": "安全检查通知", "href": "/zh/buy/order-notifications#开始前" }, "language": "zh-CN", "translation_of": "/buy/order-notifications", "search_text": "开始前 使用拥有相关记录的账号、Store context 或 Guest Order recovery link。 对 Order identifier、Case identifier 或 Guest Order token 保密。 Read status、Grouping、Sound 和 Notification text 都是展示状态，不会改变 Order、Payment、Fulfillment、Refund、Dispute 或 Market membership state。 绝不能仅因为通知要求就付款、发货、退款、Release fund 或披露证据。打开相关记录并在那里验证动作。 检查通知 打开通知铃或 /notifications 。使用可用的 Order、Transaction、System 或其他 Filter 缩小列表。 阅读 Source、Event type、Time、Counterparty label 和 Order 或 Case context。分组通知可能展示最新事件，同时保留多个 Event identity。 打开通知。当前路由把普通 Order event 送到订单详情、Dispute event 送到订单 Dispute tab、卖家 Guest Order event 送到 Admin order view，并在上下文存在时把 Marketplace review event 送到相应市场卖家页。 在目标页核对 Order、Case、Seller、Buyer、Asset、Amount 和当前 State。执行不可逆或资金动作前，从拥有后端刷新状态。 把一个通知或一组通知标记为已读可以更新 Unread count，但不会确认履约、接受决定或批准交易。 在 Order 或 Dispute flow 中保存相关业务证据，不能只留在通知列表或外部聊天。 预期结果与验证 通知类型 预期目标 在目标页验证什么 Order created、funded、confirmed、shipped、completed、canceled 或 expired /orders/{orderID} 或卖家 Guest Order view 当前后端 Order 与 Payment Session state Payment received 或付款状态事件 相关订单详情 Asset、Target、Amount、Observation、Confirmation 和 Funded state Dispute opened 或 Case update 有标识符时进入 /orders/{orderOrCaseID}?tab=dispute Claim、Response、Evidence reference、Deadline、Moderator 和当前 Dispute state Marketplace seller review 有市场上下文时进入 /marketplace/{slug}/sell 当前 Membership record 与 Decision reason Chat message Chat interface 或 Drawer Sender、Room 或 Order context，以及是否另有 Order action 目标页应保留相关标识符并显示当前记录。重复 Notification identity 不应创建重复本地项目，但通知仍可能缺失或过期；业务记录始终是权威。 失败时 Dispute notification 没有 Order 或 Case identifier 时可能没有安全路由。手动打开相关 Order 或 Cases view，不要猜测标识符。 Mark as read 或删除通知失败时，不要改变业务动作，稍后只重试展示操作。 通知打开错误 Store、Order 或 Market context 时立即停止，使用脱敏 Notification 与目标标识符报告路由缺陷。 通知比显示订单状态更新时，通过产品或认证 API 刷新；不要重放底层 Mutation。 当前记录已不允许建议动作时，遵循当前 State，不要遵循旧通知文字。 继续 跟踪付款与订单状态 取消、退款或争议 携带脱敏证据获取帮助 English canonical page" }, { "id": "zh-buy-cancel-refund-dispute", "path": "/zh/buy/cancel-refund-dispute", "canonical_url": "https://docs.mobazha.org/zh/buy/cancel-refund-dispute", "title": "取消订单、申请退款或发起争议", "summary": "根据当前订单状态选择允许的转换，并保留解释所请求 remedy 所需的证据。", "status": "beta", "audiences": [ "买家", "卖家", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/buy/cancel-refund-dispute", "label": "取消订单、申请退款或发起争议" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/api-spec", "label": "Node 订单与争议合约" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-13", "outcome": "为当前订单选择有效解决路径，同时保留支持该请求的证据。", "estimated_time": "评估约 5 分钟", "journey": "use", "primary_action": { "label": "评估当前订单", "href": "/zh/buy/cancel-refund-dispute#开始前" }, "language": "zh-CN", "translation_of": "/buy/cancel-refund-dispute", "search_text": "开始前 打开权威订单详情并记录当前状态。 阅读订单显示的取消、退货、退款、交付与争议条款。 保留消息、Quote、付款引用、交付证据以及请求的 remedy。 确认下一项转换由哪一方控制；并非所有状态都允许单方面取消。 按订单模式与当前 capability 选择路径 路径 典型用途 必须验证 Cancel 在当前承诺或付款路径关闭取消前，停止符合条件的订单 当前订单状态、actor、Payment Session capability、expiry，以及已有资金时的退款目的地。 Refund 通过受支持付款路径返还符合条件的金额 收款方或退款地址、金额、资产、既有 observation、idempotency，以及产生的交易或服务商引用。 Dispute 请求受支持的保障或 moderation 路径检查证据与 remedy 订单模式、期限、dispute capability、角色、政策版本、证据与结算后果。 Complete 或 release 在模型支持时接受履约或释放受保护资金 交付证据、actor 权限、预期状态、金额与不可逆性。 订单详情可提供 Summary、Discussion、Dispute 与 Evidence。Discussion 用于协调，Evidence 支持主张；只有已允许的 Core action 能改变受保护的订单或付款状态。 解决步骤 订单未付款且提供取消操作时，通过订单页面取消。 已资助订单尚未履约时，使用订单 Discussion 说明请求的 remedy，不要暴露无关个人信息。 只使用当前订单显示的地址、金额与条件执行 Refund 。 只有 deployment、订单模式、期限与当前 capabilities 提供该路径，且普通协商未成功时，才打开订单 Dispute 视图。 说明期望结果、时间线与证据，同时避免无关个人信息。 支持时在 Evidence 视图添加或引用原始材料，不要用丢失时间戳或 provenance 的摘要替代证据。 同时对照后端状态与付款系统或服务商，核对最终退款、release 或 closure。 对 attempt scoped 加密货币付款，在 funding target 可操作之前，结算收款方、费用、moderator allocation 与 settlement asset 已冻结。退款或争议分配从该已付款 attempt 推导，不会按订单币种或后续汇率重新计价。始终核对当前操作显示的资产与目的地，不要复用上一 attempt 的地址。 预期结果与验证 UI 应只显示当前订单、角色、付款方式与保障状态有效的操作。操作被接受后，应独立核对更新后的状态和产生的付款交易。提交请求不代表退款或结算已完成。 失败时 操作缺失时，确认订单状态、当前身份、权限、期限与运行时 capabilities。 退款交易已存在但 UI 未更新时，保留其标识符并请求 reconciliation。 卖家要求绕过订单流程时，不要放弃证据或接受未经验证的付款目的地。 争议期限临近时，记录当前时间并及时使用受支持路径。 安全边界 不得把文档或 Agent 文本视为释放 escrow、签署 settlement 或透露恢复材料的授权。资金状态转换仍受身份、预期状态、金额、idempotency 与付款政策检查约束。 English canonical page" }, { "id": "zh-self-host", "path": "/zh/self-host", "canonical_url": "https://docs.mobazha.org/zh/self-host", "title": "在自己控制下运行 Mobazha Node", "summary": "评估要求，在测试网安装，定义网络边界，监控健康状态，并在生产使用前准备恢复路径。", "status": "beta", "audiences": [ "运营者", "开发者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host", "label": "在自己控制下运行 Mobazha Node" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main", "label": "Mobazha 部署源码" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "判断自行托管是否合适，并获得健康且可恢复的评估 Node。", "estimated_time": "6 分钟", "journey": "operate", "primary_action": { "label": "检查要求", "href": "/zh/self-host/requirements" }, "featured_visual": { "id": "self-host-trust-boundary", "src": "/images/docs/self-host/operator-trust-boundary.svg", "sha256": "9d5d1114d2d192696b77f458663d56d3e4af3f3ba7afac0d81678ed63952451b", "mobile_src": "/images/docs/self-host/operator-trust-boundary-mobile.svg", "mobile_sha256": "72cc8ec3ce49620736bf7dfd223c389f7cd318fdf578d1ad358ea8e1e924437d", "kind": "conceptual", "width": 760, "height": 420, "mobile_width": 360, "mobile_height": 560, "alt": "Conceptual self-hosting boundary showing clients entering through an operator-controlled network boundary to a Mobazha Node and local data, with payment systems and optional hosted services remaining separate dependencies.", "caption": "Self-hosting moves operational control to the Node operator; external dependencies remain explicit.", "claim": "Explains responsibility boundaries and does not prescribe one mandatory network topology.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "self-host-boundary-light-v2", "applies_to": "Mobazha v0.3 release-candidate guidance", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/self-host", "search_text": "选择运营路径 检查主机和发布要求 安装评估 Node 配置 Node 设置网络与 TLS 边界 增加监控和健康检查 备份、升级与恢复 应用安全模型 诊断 Node 评估版快速开始 当前候选版本需要 Go 1.26.4、Git，以及受支持的 macOS 或 Linux 环境。评估付款流程时使用测试网。 v0.3 用于评估和测试网。稳定二进制文件及签名发布制品尚未发布。 就绪的评估 Node 应有什么证据 边界 应保留的证据 构建与身份 精确源码提交、构建命令、版本、服务账号、网络和数据目录 本地健康 成功的服务状态、 doctor json 、内嵌 UI 和 runtime config 检查 网络暴露 符合预期的监听、Firewall、Proxy、DNS 和 TLS，且没有意外公开管理员入口 交易 在支持的测试网轨道上完成一次可丢弃的商品、报价、付款观察、履约和恢复流程 恢复 带时间戳的备份，以及使用兼容构建完成的隔离恢复测试 运维 明确的告警接收者、更新负责人、回滚负责人，以及存储、依赖和付款故障的安全首要动作 进程启动只是第一个证明。如果唯一店铺副本仍在运行主机上、能力只是从源码推测，或者没人负责告警与回滚，Node 就还没有达到运维就绪。 运营者责任 保护主机、管理员访问、秘密和网络边界。 在升级前备份数据和恢复材料。 监控存储、可用性、付款集成和发布说明。 只公开用户和 Agent 实际需要的接口。 运营循环 接受工作前： 确认健康、存储、备份时效、有效能力，以及外部支付或配送依赖。 事故期间： 停止宣传不可用的新工作，保留现有订单证据，隔离故障边界后再重试。 升级前： 阅读发布证据，创建并测试恢复点，明确维护窗口和回滚判断。 变更后： 验证诊断结果，以及受影响的一条代表性买家、卖家、付款、Webhook 和恢复路径。 监控 Node 安全备份和升级 不破坏证据地排障 可选托管连接 在服务提供时，运营者可以把自托管 Node 绑定到可选 Mobazha 账号以使用托管能力。绑定不会转移本地恢复材料的保管权，也不是独立运行的必要条件。 连接可选托管账号 English canonical page" }, { "id": "zh-self-host-requirements", "path": "/zh/self-host/requirements", "canonical_url": "https://docs.mobazha.org/zh/self-host/requirements", "title": "自行托管的要求与就绪条件", "summary": "安装 Mobazha Node 前，确认平台、责任归属、恢复、网络和运营能力。", "status": "beta", "audiences": [ "运营者", "评估者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host/requirements", "label": "自行托管的要求与就绪条件" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Node 构建与 standalone 部署源码" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "判断团队能否安全承担主机、网络、恢复、更新与事件响应。", "estimated_time": "10 分钟", "journey": "operate", "primary_action": { "label": "检查运营基线", "href": "/zh/self-host/requirements#当前软件基线" }, "language": "zh-CN", "translation_of": "/self-host/requirements", "search_text": "当前软件基线 要求 候选版本基线 重要性 操作系统 受支持的 macOS 或 Linux 环境 当前源码构建与服务路径在这些环境验证 Go 1.26.4 与公开构建流程一致 Git 当前受支持客户端 用于记录准确源码版本 网络 评估期间使用 Testnet 避免把预发布行为视为生产就绪 Listener 默认 loopback 保持管理边界私密 实际 CPU、内存、存储与带宽需求取决于 Listing、媒体、订单量、数据保留、集成与可用性目标。应测量代表性负载，不要把能启动的最低配置当作生产容量。 运营责任 明确由谁修补主机、控制管理员访问、监控健康并响应付款或订单事件。 定义数据保留、备份频率、恢复测试、恢复目标和异地存储。 明确 DNS、TLS、reverse proxy、firewall、RPC、indexer、webhook 与付款服务商负责人。 维护能代表生产部署的测试环境。 让授权运营者能够取得恢复材料，但不得放入源码控制或日常日志。 就绪决定 如果尚不能承担主机安全、备份、监控、更新和事件响应，应先使用托管方式评估。只有控制权与可移植性值得这些责任，且团队能在接受实质交易前证明可恢复时，才选择自行托管。 安装 Node 安全配置 备份与升级 English canonical page" }, { "id": "zh-self-host-install", "path": "/zh/self-host/install", "canonical_url": "https://docs.mobazha.org/zh/self-host/install", "title": "安装 Mobazha Node", "summary": "从公开源码构建候选版本，在本地和测试网启动，并在对外暴露前验证 UI 与运行边界。", "status": "beta", "audiences": [ "运营者", "开发者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host/install", "label": "安装 Mobazha Node" }, "evidence": { "source": "https://github.com/mobazha/mobazha#quick-start", "label": "Mobazha Node 快速开始" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "从记录过版本的公开源码启动本地测试网 Node，并验证健康边界。", "estimated_time": "15–30 分钟", "journey": "operate", "primary_action": { "label": "检查开始前条件", "href": "/zh/self-host/install#开始前" }, "language": "zh-CN", "translation_of": "/self-host/install", "search_text": "开始前 当前候选版本需要 Go 1.26.4、Git，以及受支持的 macOS 或 Linux 环境。先准备专用数据目录，确认磁盘空间、本地防火墙策略、备份位置以及管理员会话由谁控制。付款流程只能先在测试网评估。 查看详细要求 查看发布边界 安装步骤 克隆公开 Node 仓库，并记录准备评估的准确 commit。 使用下面的纯 Go 加密实现构建 Node module。当前 main checkout 的 Workspace 声明可能落后于 Module 的 Go 要求，因此源码构建使用 GOWORK=off 隔离 Module。 为服务账号初始化测试网数据目录。 在默认的仅本机监听地址启动 Node，并打开内嵌 UI。 保持终端可见，直到首次启动和健康检查完成。 执行前先审阅命令。v0.3 不是稳定生产版本，签名发布制品仍待正式发布。 预期结果与验证 首次启动会在需要时初始化默认数据目录。 内嵌 Web UI 与 HTTP API 默认监听 http://127.0.0.1:5102。 HTTP 位于 /v1/，WebSocket 位于 /ws，MCP Streamable HTTP 位于 /v1/mcp。 保持本地监听；在远程暴露前配置 TLS、认证、防火墙、更新与恢复方案。 在第二个终端运行： 确认诊断能够完成、内嵌 UI 可以打开、运行时快照使用受支持的 schema，并且尚未配置或不健康的可选能力保持不可用。 doctor json 会返回通过、警告和失败数量以及具名检查。路径、容量、版本与可选依赖结果会因主机而异；健康的本地 Node 应有零项失败，警告仍需按目标部署逐项审阅。 这里的列表经过缩短，只展示输出契约形状。运维时保留完整本地结果；公开分享前必须移除路径和环境细节。 可选后台服务 完成交互式启动验证后，再安装并检查受支持的后台服务。 失败时恢复 构建失败时，确认 go version 、检出的 commit、平台工具链和可用存储空间。 如果 Go 报告 go.work 声明的版本低于 go.mod ，先确认当前是计划评估的公开 revision，再使用文档中的 GOWORK=off 隔离构建；不要为了让候选版本编译而降低 Module 要求。 启动失败时，保留脱敏诊断，并确认数据目录所有权和端口占用。 UI 无法打开时，先测试本地监听，不要直接修改 DNS、TLS 或防火墙。 运行时能力未就绪时，检查配置和依赖，不要手动强制开启前端入口。 只能删除明确创建的可丢弃测试目录；不要为了重试安装而删除店铺的唯一数据副本。 继续 部署源码 English canonical page" }, { "id": "zh-self-host-configure", "path": "/zh/self-host/configure", "canonical_url": "https://docs.mobazha.org/zh/self-host/configure", "title": "配置自行托管的 Node", "summary": "明确且可恢复地设置部署模式、数据位置、网络暴露、付款与外部依赖。", "status": "beta", "audiences": [ "运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host/configure", "label": "配置自行托管的 Node" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Mobazha Node 命令与部署源码" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "运行一个数据、listener、依赖、备份与回滚负责人都明确的 Node profile。", "estimated_time": "20–40 分钟", "journey": "operate", "primary_action": { "label": "记录部署 profile", "href": "/zh/self-host/configure#开始前" }, "language": "zh-CN", "translation_of": "/self-host/configure", "search_text": "开始前 学习运营模型时使用专用数据目录与 Testnet。把准确 binary commit、flags、配置与外部依赖和备份程序一起记录。 修改不可丢弃的 profile 前先备份，并记录 binary commit、network、data directory、listener、reverse proxy、DNS、certificate、付款依赖与 rollback owner。 配置步骤 选择一个明确的数据目录，并把访问限制在 service account。 把管理 listener 保持在 loopback 或受信任私有网络。 只有确需远程管理时，才配置带认证的 TLS reverse proxy。 每次只启用一种付款或 Extension 依赖，并在每次变更后检查健康。 配置备份目的地、监控、日志保留与升级责任。 通过受支持的 service command 重启，并重新运行诊断。 安全与依赖检查 除非有意配置了带认证 reverse proxy 与 TLS 边界，否则管理接口只绑定受信任网络。 只启用 effective runtime capability set 报告、且卖家已配置的付款方式。 把 RPC、indexer、webhook、plugin 和远程媒体输入视为不受信任依赖。 Secret 不进入源码控制；恢复材料与普通服务配置分开。 生产使用前，记录 DNS、firewall、proxy、certificate、backup、monitoring 与 rollback 的负责人。 预期结果与验证 存在源码文件、可识别标识符、前端组件或配置字段，都不能证明能力已启用。实际可用性是 distribution allowlist、contract compatibility、installation 或 composition、authorization、configuration 与 health 的交集。 确认进程使用预定数据目录与网络、本地 UI 可访问、effective capabilities 与已配置依赖一致，并且没有管理接口意外公开。 运行时能力 兼容性政策 失败时 回滚最后一次配置变更，不要同时改变多个变量。 Node 读取了其他 profile 时，停止服务并核对 service arguments，再写入新数据。 远程访问失败时，先重新测试 loopback 健康，再排查 proxy 或 DNS。 capability 变为不健康时，停止展示新工作，同时保留既有订单的恢复路径。 只通过与版本兼容的流程从已验证备份恢复。 English canonical page" }, { "id": "zh-self-host-network-and-tls", "path": "/zh/self-host/network-and-tls", "canonical_url": "https://docs.mobazha.org/zh/self-host/network-and-tls", "title": "设计网络与 TLS 边界", "summary": "默认保持 Node 管理私密，只公开明确经过认证、加密并受监控的路由。", "status": "beta", "audiences": [ "运营者", "安全审核者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host/network-and-tls", "label": "设计网络与 TLS 边界" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Node listener 与 API 表面" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "选择一个保持管理私密、且只明确公开已认证路由的网络边界。", "estimated_time": "7 分钟", "journey": "operate", "primary_action": { "label": "查看建议边界", "href": "/zh/self-host/network-and-tls#建议边界" }, "language": "zh-CN", "translation_of": "/self-host/network-and-tls", "search_text": "建议边界 不要把默认管理 listener 直接暴露到互联网。Reverse proxy 不会让未认证路由自动安全；必须保留 Node authentication、request limits、body limits、timeouts、WebSocket upgrade handling 与 security headers。 路由注意事项 表面 默认路径 边界 Embedded UI 与 HTTP API http://127.0.0.1:5102 ，API 位于 /v1/ 不同 operation 的管理与商业授权要求不同 WebSocket /ws 认证连接，并保留重连限制 MCP Streamable HTTP /v1/mcp 要求 gateway identity、 ai:use 与 tool scopes Webhooks 从 Node 向外发送 验证 destination、TLS、signature、timeout 与 retry 行为 暴露检查 使用受维护配置终止 TLS，并安全自动更新 certificate。 把 Node 绑定到 loopback 或私有接口，限制主机 firewall ingress。 只通过受信任 proxy headers 转发原始 scheme 与 host。 设置 rate、connection、request size 与 timeout 限制，同时不破坏 WebSocket 或 MCP streaming。 把公开 Storefront 与管理员、token minting、wallet 和 system operation 分离。 监控认证失败与意外路由暴露。 验证 从受信任边界外枚举时，只应看到有意公开的路由，且管理操作会拒绝未认证请求。从内部验证部署需要的 UI、API、WebSocket 与 MCP 路径。每次 proxy 或 certificate 变更后重新测试。 English canonical page" }, { "id": "zh-self-host-monitoring", "path": "/zh/self-host/monitoring", "canonical_url": "https://docs.mobazha.org/zh/self-host/monitoring", "title": "监控自行托管的 Node", "summary": "在进程、存储、能力、付款、webhook 或恢复退化演变为订单事件前发现问题。", "status": "beta", "audiences": [ "运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host/monitoring", "label": "监控自行托管的 Node" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Node 诊断与运营源码" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "在进程、存储、能力和依赖退化演变为订单事件前发现问题。", "estimated_time": "20–40 分钟", "journey": "operate", "primary_action": { "label": "定义告警边界", "href": "/zh/self-host/monitoring#开始前" }, "language": "zh-CN", "translation_of": "/self-host/monitoring", "search_text": "开始前 明确谁接收告警、谁可以采取修正操作。 将监控凭据与 Node 管理员、签名凭据分开。 定义预期可用性、备份时效、磁盘余量与付款依赖健康标准。 监控设置步骤 从受信任本地 monitor 定期运行 mobazha service status 与 mobazha doctor json 。 监控进程重启、磁盘空间、文件系统错误、系统时间与备份时效。 轮询 runtime capability snapshot，并在 readiness 或付款方式意外变化时告警。 将 RPC、indexer、webhook 与外部服务商的延迟和失败，与 Node 健康分开监控。 追踪认证失败、重复 permission error、webhook dead letter 与订单 reconciliation failure。 测试告警发送，并为每类告警记录第一个安全响应。 预期结果与验证 监控应能区分进程不可用、依赖退化、能力被拒绝和业务操作失败。在非生产环境触发可控失败，确认告警能指出正确边界，同时不记录 secret 或客户 payload。 失败时 监控失去访问时，不要削弱 Node authentication；修复范围最窄的监控凭据或本地执行路径。 capability 变为不健康时，停止展示新工作，同时保留既有订单恢复。 磁盘或备份告警触发时，先保护当前数据，再重启或升级。 告警含有 secret 或个人资料时，按事件处理并轮换受影响凭据。 English canonical page" }, { "id": "zh-self-host-backup-and-upgrade", "path": "/zh/self-host/backup-and-upgrade", "canonical_url": "https://docs.mobazha.org/zh/self-host/backup-and-upgrade", "title": "安全备份与升级", "summary": "把升级就绪当作可恢复性演练，而不只是更新软件包。", "status": "beta", "audiences": [ "运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host/backup-and-upgrade", "label": "安全备份与升级" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/docs/releases", "label": "Mobazha 运营指南" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "生成经过验证的备份，并升级一个已审核版本，同时保留可恢复的回滚点。", "estimated_time": "30–60 分钟", "journey": "operate", "primary_action": { "label": "准备恢复点", "href": "/zh/self-host/backup-and-upgrade#开始前" }, "language": "zh-CN", "translation_of": "/self-host/backup-and-upgrade", "search_text": "开始前 阅读 release notes，识别 schema、付款、capability 与配置变更。 创建带版本信息的备份，并确认其可读取。 记录运行版本与配置；单独保护 secret。 变更生产环境前，规划 rollback 与维护窗口。 升级后验证健康、店铺访问、订单流程与付款 callback。 备份文件只有在隔离环境中按兼容版本流程检查并恢复过，才构成恢复计划。 备份与升级步骤 记录运行 binary version 或 commit、service arguments、data directory、配置与 effective capabilities。 阅读 Node 与客户端 release notes，识别 migration、已移除 flag、付款变更与 compatibility requirement。 运行诊断；升级前解决既有损坏、存储或依赖故障。 按 release procedure 停止或静止写入，并创建带时间戳的备份。 把备份与必要恢复材料复制到独立保护的位置。 在隔离环境中，用代表性数据测试新版本。 安排维护窗口，安装已审核 artifact 并启动服务。 验证诊断、Storefront、管理、订单读取、付款观察、webhook 投递与备份创建。 内置命令 版本变更前运行诊断并创建压缩备份。 备份命令会报告解析后的来源与输出路径，最后报告 archive 大小；路径和大小取决于部署。 预期结果与验证 备份命令应无错误完成，并在指定路径生成非空 archive。记录大小、创建时间、来源版本与 cryptographic checksum。即使 archive 内的数据已加密，也要用独立访问政策保护 secret 与恢复材料。 升级后比较 effective capabilities，并完成一条小额 Testnet 旅程。不能只凭进程健康宣告成功。 恢复与回滚 当前候选版本没有为所有历史版本发布通用的一键恢复承诺。使用 release specific migration 与 restore 指南，保留原始备份，并先在独立数据目录练习。只有旧 binary 支持升级后的数据格式时才可 rollback。 升级后启动失败时，停止反复写入并保留日志与升级后的数据副本。 migration 为单向时，恢复升级前备份，不要用旧 binary 打开已迁移数据。 订单或付款不一致时，让资金自动化 fail closed，同时进行 reconciliation。 缺少恢复说明应作为 release blocker 报告，而不是由运营者在生产环境临时发挥。 English canonical page" }, { "id": "zh-self-host-security", "path": "/zh/self-host/security", "canonical_url": "https://docs.mobazha.org/zh/self-host/security", "title": "保护自行托管的 Node", "summary": "把主机、管理边界、签名材料、付款集成、备份与恢复路径作为一个系统保护。", "status": "beta", "audiences": [ "运营者", "安全审核者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host/security", "label": "保护自行托管的 Node" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/SECURITY.md", "label": "Mobazha 安全政策与 Extension 安全模型" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "为自己运营的 Node 建立最低主机、身份、secret、付款、监控与恢复控制。", "estimated_time": "10 分钟", "journey": "operate", "primary_action": { "label": "检查运营者基线", "href": "/zh/self-host/security#最低运营者基线" }, "language": "zh-CN", "translation_of": "/self-host/security", "search_text": "最低运营者基线 使用专用、已修补的主机和最小权限 service account。 Admin API 默认保持私密；远程暴露前加入 TLS、authentication、rate limit 与 network policy。 分别保护 seed phrase、private key、API token、webhook secret 与 backup。 把每个 chain RPC、indexer、plugin、webhook 与 delivery integration 当作恶意输入边界审核。 监控健康、存储、认证失败、付款观察、webhook 投递与意外 capability 变更。 在版本或基础设施变更前测试 restore 与 rollback。 资金边界 只有 Core policy 可以改变付款、退款、争议或 settlement 状态。 Extension 与外部服务不得获得原始 seed phrase 或 private key。 付款 observation 不是结算权限；仍要检查预期状态、身份、金额、confirmations 与 idempotency。 禁用不健康 capability 必须 fail closed，不能静默选择另一种资金行为。 私下报告漏洞 怀疑存在漏洞、凭据泄露、签名密钥问题或 exploit 时，不要创建公开 issue。请从受影响仓库的 Security 页使用 GitHub private vulnerability reporting。 Node security policy Supply chain audit baseline English canonical page" }, { "id": "zh-self-host-troubleshooting", "path": "/zh/self-host/troubleshooting", "canonical_url": "https://docs.mobazha.org/zh/self-host/troubleshooting", "title": "排查 Mobazha Node 故障", "summary": "在不暴露敏感资料的前提下，诊断版本、进程、健康、能力、配置与依赖故障。", "status": "beta", "audiences": [ "运营者", "支持人员" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host/troubleshooting", "label": "排查 Mobazha Node 故障" }, "evidence": { "source": "https://github.com/mobazha/mobazha#operations", "label": "Mobazha Node 运营命令" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "隔离一个故障边界，并在进行恢复变更前保留可复现、已脱敏的测试。", "estimated_time": "10–30 分钟", "journey": "operate", "primary_action": { "label": "记录初始状态", "href": "/zh/self-host/troubleshooting#开始前" }, "language": "zh-CN", "translation_of": "/self-host/troubleshooting", "search_text": "开始前 修改数据、flag、版本或付款配置前，创建或找到当前备份。记录准确症状、首次发生时间、近期变更、版本、平台、network mode 与预定 data directory。 诊断步骤 确认 binary version、start flags、data directory、network mode、system time 与可用磁盘空间。 在不暴露 secret 的情况下检查 service status 与 diagnostics。 先测试本地 UI 与 runtime endpoint，再检查外部 DNS、proxy 或浏览器层。 将展示的 runtime capabilities 与失败 operation 对照。 区分 Node 故障与 RPC、indexer、network、payment provider、webhook consumer 或 browser 故障。 复现一条最小失败请求或 UI 旅程，并保留其脱敏标识符。 首轮检查 确认 binary version、start flags、data directory、network mode 与 system clock。 测试外部 DNS 或 proxy 前，先确认本地 UI 与健康端点响应。 将展示的 runtime capabilities 与失败 operation 对照。 区分 Node、RPC、indexer、network、payment provider、webhook consumer 或 browser 的故障。 症状 首先检查的边界 避免 进程无法启动 data directory 所有权、port、disk、既有 process 删除 profile 本地 UI 不可用 loopback listener 与 process health 先修改公开 DNS capability 缺失 runtime snapshot、configuration、dependency health 启用只存在于前端的 flag 未检测到付款 order、asset、address、amount、expiry、RPC health 发送第二笔付款 webhook 延迟 delivery history、endpoint response、signature handling 把重复投递当成新状态 可提供给支持人员的安全证据 记录准确 version 或 commit、操作系统、复现步骤、预期结果与脱敏错误。 只在不暴露客户资料或 secret 时提供 request、event 或 order 标识符。 移除 token、私有 endpoint、seed、key、wallet recovery material、原始客户资料与完整生产数据库。 怀疑安全问题时停止公开讨论，使用 private vulnerability reporting。 先恢复，再实验 修改数据、flag、版本或付款配置前创建并验证备份。优先采用可复现 rollback，不要反复手工修改店铺唯一数据副本。 预期结果与验证 诊断应找出故障边界与可复现测试，而不是只让症状消失。变更后重新运行诊断与受影响的最小旅程，再确认无关订单和付款路径仍稳定。 失败时 两次无法解释的重试后停止，并保留原始证据。 理解 rollback 时，撤回最后一次已知配置变更。 不要编辑 Core order 或 payment table 强制状态转换。 安全问题私下升级，运营缺陷通过 Node issue tracker 报告。 获取帮助 公开支持渠道 Node issues English canonical page" }, { "id": "zh-self-host-bind-account", "path": "/zh/self-host/bind-account", "canonical_url": "https://docs.mobazha.org/zh/self-host/bind-account", "title": "连接可选托管能力", "summary": "将本地 Node 所有权与任何可选账号或托管服务连接明确分开。", "status": "draft", "audiences": [ "运营者" ], "applies_to": "设计方向，不代表已交付承诺", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/self-host/bind-account", "label": "连接可选托管能力" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/README.md", "label": "Mobazha 公开发布边界" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "在交换 Node 或账号权限前，判断可选托管连接是否已有稳定公开合约。", "estimated_time": "4 分钟", "journey": "operate", "primary_action": { "label": "阅读当前状态", "href": "/zh/self-host/bind-account#目前稳定的内容" }, "language": "zh-CN", "translation_of": "/self-host/bind-account", "search_text": "目前稳定的内容 本地 standalone store 无需 Mobazha Hosting 账号，仍可用于管理、Listing、数据导出与受支持的 UTXO 付款流程。未来可选服务可能增加发现、搜索、路由、托管更新或支持。 目前还没有稳定的公开 Node to account binding contract。不要把内部 endpoint、旧截图或历史设计文档当作受支持流程。 连接任何服务前 确认正在管理目标 Node 与账号。 创建新备份，并将恢复材料保存在浏览器会话之外。 要求清楚说明 capability、data exchange、permission、revocation 与 price。 不要把 seed phrase、wallet private key 或 database credential 粘贴到账号绑定表单。 受支持流程的发布 gate 公开 Node 与客户端仓库描述同一个 versioned contract。 UI 显示 Node identity、requested permissions、exchanged data 与 revocation path。 Authentication 不暴露 Node recovery material，也不会静默扩大 runtime capabilities。 自动化测试覆盖 connection、denial、expiry、revocation 与 recovery。 English canonical page" }, { "id": "zh-build", "path": "/zh/build", "canonical_url": "https://docs.mobazha.org/zh/build", "title": "基于后端声明的能力构建", "summary": "集成应主动发现后端支持什么，不能假设每个 Mobazha 部署都公开相同接口。", "status": "beta", "audiences": [ "开发者", "agent 构建者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build", "label": "基于后端声明的能力构建" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开源码组织" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "为集成选择当前公开契约，并在不假设部署完全相同的前提下完成第一个有范围限制的调用。", "estimated_time": "5 分钟", "journey": "build", "primary_action": { "label": "完成第一个 API 调用", "href": "/zh/build/quickstart" }, "language": "zh-CN", "translation_of": "/build", "search_text": "集成规则 把连接后端的能力响应和版本信息作为运行时事实。文档解释接口和意图，但客户端必须处理能力不可用、被禁用或版本不同的情况。 接口类型 用于交易操作和实时更新的 HTTP 与 WebSocket 接口。 面向运营者控制的事件投递 Webhook。 带明确身份和授权边界的 MCP 与 Agent 接口。 只有连接部署明确声明时才可使用的插件和契约。 当前 Node 的 HTTP 入口位于 /v1/ ，WebSocket 位于 /ws ，MCP Streamable HTTP 位于 /v1/mcp 。具体操作仍取决于版本和能力。 开始构建 选择接口和集成契约 区分客户端壳、上下文路由、传输、事件和状态权威。 完成第一个认证 API 调用 发现能力并调用受保护的读取操作。 认证与 Scope 在 Basic、托管 JWT 和有 Scope 的 API Token 中选择。 错误、重试和幂等 在结果未知时保持业务正确性。 HTTP API 与 OpenAPI 使用生成的 operation 和 Schema 契约。 Webhook 验证签名、去重并对账。 WebSocket 把事件当成刷新提示，而不是最终事实。 MCP 与 Agent 初始化有 Scope 的 Streamable HTTP 客户端。 English canonical page" }, { "id": "zh-build-quickstart", "path": "/zh/build/quickstart", "canonical_url": "https://docs.mobazha.org/zh/build/quickstart", "title": "五分钟调用本地 Mobazha Node API", "summary": "发现运行时能力，使用声明的认证边界，并向本地评估 Node 发出一条只读请求。", "status": "beta", "audiences": [ "开发者", "agent 构建者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/quickstart", "label": "五分钟调用本地 Mobazha Node API" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/api-spec/openapi.json", "label": "生成的 Node OpenAPI 与运行时合约" }, "reviewed": "2026-07-14", "page_type": "task", "last_tested": "2026-07-04", "outcome": "确认连接到哪个 Node，并完成一条带 scope 的只读 API 请求。", "estimated_time": "5 分钟", "journey": "build", "primary_action": { "label": "运行首次调用", "href": "/zh/build/quickstart#首次调用" }, "language": "zh-CN", "translation_of": "/build/quickstart", "search_text": "首次调用 本地评估 Node 运行后，把带 scope 的 MBZ API TOKEN 放入环境变量；先发现运行时，再调用受保护的只读 endpoint。 Token 不是公开注册 key。Standalone 管理员通过受支持的 Admin 表面或 token API 创建它，只赋予集成所需 scope，并把一次性 secret 保存在源码外。运行受保护调用前先阅读Token 创建与撤销。 开始前 在默认 loopback listener 上运行 v0.3 候选版本 Node。 安装 curl 与 jq ；凭据放入环境变量，不留在 shell history。 使用可丢弃测试 profile，以及 operation 所需的最窄身份。 阅读当前 OpenAPI security 声明；公开 runtime discovery 不会让管理路由变成公开路由。 首次调用步骤 读取公开 runtime snapshot，记录 schema、deployment、readiness 与展示的 capabilities。 确认 Node version 和 operation 存在于生成的 OpenAPI 合约。 按 operation 声明选择 standalone Basic Auth、hosted Bearer JWT 或带 scope 的 mbz API token。 先调用只读 endpoint，同时检查 HTTP status 与 response envelope。 从终端输出、日志、截图和支持证据中移除凭据。 预期结果与验证 Runtime discovery 应无需管理凭据即可返回成功 envelope。只有 token 有效且具备所需 scope 时，受保护调用才成功。构建自动化前确认响应属于目标 Node。 还应在可丢弃环境测试一条 token scope 之外的路由，它应返回 403 ；如果成功，说明凭据比 quickstart 所需更宽，应在部署自动化前替换。 失败时 401 表示认证缺失或无效；不要用猜测凭据快速重试。 403 表示解析出的身份缺少所需 permission 或 scope。 404 可能表示 base URL、version、route 错误或 composition 不可用；检查 OpenAPI 与 runtime capabilities。 409 通常要求先核对状态再重试。 429 要求有限 backoff 并遵循服务端指示。 Transport 成功但 application error 仍需错误处理。 继续 认证、身份与 Scope 错误、重试与 Idempotency HTTP API 与 OpenAPI English canonical page" }, { "id": "zh-build-authentication", "path": "/zh/build/authentication", "canonical_url": "https://docs.mobazha.org/zh/build/authentication", "title": "认证、身份与 Scope", "summary": "选择连接 deployment 声明的身份与凭据模型，只授予单一集成需要的 scope。", "status": "beta", "audiences": [ "开发者", "运营者", "agent 构建者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/authentication", "label": "认证、身份与 Scope" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/api-spec/openapi.json", "label": "OpenAPI security schemes 与 Node auth token API" }, "reviewed": "2026-07-14", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "选择受支持身份，并签发单一集成所需的最窄凭据。", "estimated_time": "10 分钟", "journey": "build", "primary_action": { "label": "查看带 Scope 的 API Token", "href": "/zh/build/authentication#带-scope-的-api-token" }, "language": "zh-CN", "translation_of": "/build/authentication", "search_text": "Authentication 模型 凭据 预定边界 Transport Standalone administrator 本地运营者管理 在受信任 TLS 或 loopback 边界使用 HTTP Basic Hosted identity 托管用户或 service identity 由托管认证流程签发的 Bearer JWT Scoped standalone token 对 standalone Node 的自动化 带 mbz 前缀和明确 scopes 的 Bearer token Operation 的 OpenAPI security 声明是可接受凭据类型的权威。在一条路由被接受的 token，不代表拥有所有路由权限。 带 Scope 的 API Token 创建和列出本地 API token 需要管理员身份。使用受支持 Admin 表面或 /v1/auth/tokens ，记录用途与 owner；secret 只通过受支持的创建响应显示，并存入 secret manager。 验证凭据边界 在可丢弃环境调用一条集成所需只读路由和一条 scope 外路由。目标路由应成功，scope 外路由应返回 403 ，不要扩大 token。无效或已撤销 token 应返回 401 。记录 token owner、purpose、scopes、creation time、rotation plan 与 revocation path，但不记录 secret。 Authorization 与 Scope 规则 Read scope 与 create、manage、spend、settlement 或 administrative scope 分开授予。 MCP transport 边界要求 ai:use ，每个 tool 还要求相应 domain scope。 Buyer anonymous Guest Checkout 请求不得携带卖家或管理员凭据。 Multi store 或 hosted deployment 要明确解析当前 role 与 store context。 凭据暴露、角色变化、集成下线或出现无法解释的使用后，轮换并撤销 token。 错误与安全处理 401 是 authentication failure， 403 是 authorization failure；不要把两者合并成重试循环。 不要把 token 放入 URL query、文档示例、产品合约之外的 browser storage 或支持报告。 日志必须移除 authorization header 与 token creation response。 广泛 token 暴露时，先撤销，再调查后续使用。 Compatibility 自动化应固定到已测试 Node version，并在升级时重新读取 OpenAPI security 与 scope requirements。Frontend login cookie、旧 Basic credential 或 internal hosted token 不会自动成为受支持的公开集成凭据。 English canonical page" }, { "id": "zh-build-errors-and-idempotency", "path": "/zh/build/errors-and-idempotency", "canonical_url": "https://docs.mobazha.org/zh/build/errors-and-idempotency", "title": "错误、重试与 Idempotency", "summary": "在 transport failure、重复投递、conflict、timeout 和结果未知时保持业务正确。", "status": "beta", "audiences": [ "开发者", "agent 构建者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/errors-and-idempotency", "label": "错误、重试与 Idempotency" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/api-spec/openapi.json", "label": "Node API 错误合约与状态机实现" }, "reviewed": "2026-07-14", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "判断应停止、修正、核对还是重试，同时不重复执行受保护业务操作。", "estimated_time": "8 分钟", "journey": "build", "primary_action": { "label": "查看重试决定", "href": "/zh/build/errors-and-idempotency#重试决定" }, "language": "zh-CN", "translation_of": "/build/errors-and-idempotency", "search_text": "错误类别 Status 解释 默认响应 400 请求不符合声明合约 修正请求，不盲目重试 401 认证缺失或无效 刷新或替换预定凭据 403 身份缺少 permission 或 scope 停止并申请范围更窄的授权访问 404 Resource、route 或 deployment surface 不存在 核对 identity、version、path 与 capability 409 当前状态与尝试的转换冲突 决定前重载权威状态 429 超过 rate boundary Back off 并遵循服务端指示 5xx 服务端或依赖失败 仅在 operation 可安全核对时重试 读取结构化错误响应和合约定义的 stable code，不要把人类消息解析成机器状态。 重试决定 Idempotency 与 Reconciliation Endpoint 支持时，为 client operation 分配稳定标识。 发送资金或订单转换前持久化 request intent。 Timeout 后，先读取订单、付款、webhook delivery 或 action status，再重新提交。 按 delivery 与 event identity 对 webhook 去重。 把 WebSocket event 当作刷新信号，而不是命令。 Retry budget 必须有限；未知结果交由审核。 Authentication 与信息安全 错误日志可以包含 route、status、stable error code、correlation identifier 与脱敏 resource identity，但不得包含 Bearer token、Basic credential、seed、private key、customer payload 或未脱敏 webhook secret。 Compatibility 针对每个受支持 Node version 重新运行 negative、timeout、duplicate 与 conflict 测试。Happy path 成功并不能证明重试安全。 English canonical page" }, { "id": "zh-build-runtime-capabilities", "path": "/zh/build/runtime-capabilities", "canonical_url": "https://docs.mobazha.org/zh/build/runtime-capabilities", "title": "运行时能力与产品组合", "summary": "从后端发现有效行为，并把部署方式、产品体验、能力、权限和实验开关分开处理。", "status": "beta", "audiences": [ "开发者", "agent 开发者", "运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/runtime-capabilities", "label": "运行时能力与产品组合" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/tree/main/packages/core/config", "label": "Unified 运行时配置实现" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "判断功能是否实际可用，同时区分源码存在、产品组合、能力、权限和就绪状态。", "estimated_time": "8 分钟", "journey": "build", "primary_action": { "label": "查看有效能力交集", "href": "/zh/build/runtime-capabilities#新工作可用性" }, "language": "zh-CN", "translation_of": "/build/runtime-capabilities", "search_text": "新工作可用性 所有适用门槛都通过后，能力才能对外公开或接纳新的操作。源码存在、标识符被识别、前端有组件或配置中出现名称，都不代表能力已启用。 这个投影回答的是当前上下文下，连接的后端能否接纳新工作。它不会删除已持久化的提供方绑定，也不授权后端放弃既有支付、结算、交付、补偿或对账义务；这些决策仍由所属领域管理器和 Core 状态决定。 客户端必须失败关闭 在权威能力快照就绪前，不渲染或调用可选功能。 允许未知的新增字段，但对畸形或不兼容版本安全拒绝。 导航、路由、操作控件和 Agent 工具使用同一能力键。 能力快照可以隐藏或阻止新操作，而已经绑定的工作仍可能需要继续服务或对账。 客户端隐藏控件不能代替服务端授权。 产品组合维度 认证模式只选择认证传输方式，不启用产品能力。 部署方式描述托管、自托管或自主运行。 产品体验选择平台、商店或市场外壳。 能力描述后端实际实现的产品行为。 权限描述当前主体可以做什么。 功能开关只用于实验或紧急关闭，不能替代授权。 当前前端组合切片 无框架依赖的解析内核通过 @mobazha/commerce kit/composition 发布。它接收宿主拥有的产品档案、就绪状态、受支持档案矩阵、构建内特性目录，以及 capability 和 policy 判断函数。Unified 只负责把经过校验的 Runtime Config、展示渠道和店铺请求上下文适配到该内核。内核返回 pending 、 ready 或 invalid 、启用和排除的特性 ID，以及结构化诊断；路由、Provider、授权和最终物化仍由各应用拥有。 首批接入统一解析结果的特性是： Guest Checkout，由有效的 commerce.checkout 能力控制； 市场运营路由与导航，只在受支持的托管档案且非店铺请求上下文中出现； 市场卖家审核路由与导航，使用同一组合边界。 能力仍在加载时保持等待状态，不能被解释为权威拒绝。档案不受支持、特性 ID 重复、后端能力缺失、外部资源受限或构建产物没有对应代码时都必须失败关闭。路由可见之后，后端授权仍然是操作权威。 产品操作是 Commerce Kit 的第二个实际验证切片。共享的 CommerceProductActionButtons 契约负责稳定的 add to cart 与 buy now 操作身份、禁用状态、回调连接和可选的宿主渲染适配器。Unified 在桌面详情、移动详情和响应式底栏中使用它，同时继续拥有按钮、布局、本地化、库存、付款和资产政策。 购物车摘要是下一个实际验证切片。共享摘要内容统一商品数量、总额、结账禁用状态、结账操作和可选宿主渲染。Unified 在抽屉、桌面卖家分组底栏、多卖家总额和移动固定栏中使用它；卖家分组、登录或注册路由、币种显示、渠道专用操作、购物车存储和结账导航仍由宿主负责。 当前应用仍只把解析后的特性资格投影到路由与导航。单个商品或购物车的政策不是全局能力；产品操作和购物车摘要 API 在第二个独立应用验证相同边界前仍属于临时 0.x 契约。通用 Provider、工作流与操作贡献、浏览器扩展外壳接入、动态插件、远程 UI 和万能产品清单都不是当前公开契约。 一个下游自主发行也已经使用完整 runtime profile 与后端能力快照校验其构建内 catalog。本地 UI policy 可以隐藏已编入构建的特性，但后端能力缺失时不能暴露对应路由或导航。发行本地源码和产品词汇继续留在公共前端之外。 实现证据 兼容性政策 Unified 运行时配置代码 Commerce Kit 组合解析内核 前端产品组合实现说明 English canonical page" }, { "id": "zh-build-token-identifiers", "path": "/zh/build/token-identifiers", "canonical_url": "https://docs.mobazha.org/zh/build/token-identifiers", "title": "Token 与链上资产标识", "summary": "在客户端之间使用带版本、可解析的标识，同时让精确解析行为和支持标准继续受发布版本契约约束。", "status": "beta", "audiences": [ "开发者", "集成方", "agent 开发者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/token-identifiers", "label": "Token 与链上资产标识" }, "evidence": { "source": "https://github.com/mobazha/mobazha-unified/blob/main/packages/core/utils/tokenIdentifier.ts", "label": "Unified 代币标识实现与测试" }, "reviewed": "2026-07-04", "page_type": "concept", "outcome": "解析和比较 Token 标识，同时不把可识别性误认为所有权、价格、转移权限或运行时支持。", "estimated_time": "6 分钟", "journey": "build", "primary_action": { "label": "查看标识结构", "href": "/zh/build/token-identifiers#公共标识结构" }, "language": "zh-CN", "translation_of": "/build/token-identifiers", "search_text": "公共标识结构 新标识编码大写网络名、小写合约地址、Token 标准以及 tokenId 或 slotId，例如 SEPOLIA 0x1234... ERC721 42 、 SEPOLIA 0x1234... ERC1155 1 和 SEPOLIA 0x1234... ERC3525 1 。 精确解析器、标准支持范围、旧格式兼容和序列化字段属于带版本的实现契约。不能直接拼接未经验证的用户输入，也不能因为标识可解析就推断资产能力已经启用。 身份语义 ERC 721 与 ERC 1155 使用合约地址和 tokenId 共同确定资产身份。 ERC 3525 集成可以用 slotId 表示资产类别，但具体持有物仍有自己的 token 身份。 网络是标识的一部分；不同网络上的相同地址属于不同命名空间。 比较前必须规范化合约地址。 人类可读符号只用于展示，不能作为唯一身份。 兼容与安全 旧格式只能通过维护中的解析器处理，并在迁移时保留原值作为证据。 未知标准和畸形标识应判断为不支持，不能猜测。 网络、合约和 Token 元数据必须来自可信配置或已验证链上数据。 标识识别必须和运行时能力、授权、所有权、价格及结算支持分开判断。 Agent 不得仅凭可解析标识执行购买或转移，仍需有效能力和用户确认。 实现证据 标识实现 RWA 类型契约 运行时能力规则 English canonical page" }, { "id": "zh-build-api", "path": "/zh/build/api", "canonical_url": "https://docs.mobazha.org/zh/build/api", "title": "HTTP API 与 OpenAPI", "summary": "用生成的 Mobazha Node OpenAPI 合约查 operation 与 schema，并在调用可选能力前验证运行时 capability。", "status": "beta", "audiences": [ "开发者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/api", "label": "HTTP API 与 OpenAPI" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/api-spec/openapi.json", "label": "生成的 Mobazha Node OpenAPI 合约" }, "reviewed": "2026-07-14", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "确认当前 Node 合约与 capability，再针对其 versioned route 构建。", "estimated_time": "7 分钟", "journey": "build", "primary_action": { "label": "运行 Capability 调用", "href": "/zh/build/api#首次-capability-调用" }, "language": "zh-CN", "translation_of": "/build/api", "search_text": "合约与入口 Mobazha Node 在 /v1/ 下提供 versioned HTTP route，在 /ws 提供 WebSocket。生成的 OpenAPI 文档描述 API Reference 所示审核版本中的 request method、path、schema、response envelope 与声明的 authentication mechanism。 Specification 是候选版本合约，不能证明某个后端已启用所有可选 operation。公开可选 UI 或自动化前，读取 /v1/runtime config 与 capability endpoint。 浏览共用 API Reference 在只读、面向人的参考中搜索 operation 与 schema。 下载 OpenAPI JSON 对 generator、Agent 与 CI 使用同一份审核合约。 API source 与 generator 检查生成 artifact 与其所属仓库。 首次 Capability 调用 本地 Node 无需执行已认证业务 operation，即可公开 frontend runtime snapshot。构建可选 UI 或自动化前，用它验证 schema version、deployment composition、readiness、features 与 capabilities。 示例假定默认本地 listener。不要为了让示例工作而禁用认证或公开管理 listener。 预期结果 Runtime 调用应返回成功 JSON envelope，描述 Node schema、deployment composition、readiness 与 effective capabilities。记录准备使用的 Node version 与 capability。Capability 缺失或不可用意味着应停止或降级集成，而不是打开只存在于前端的 switch。 默认 standalone store 在把响应缩小到 composition 字段时，当前会返回以下代表性 projection；capability 与 feature 值依连接的 Node 而异，并保持权威。 Authentication 选择 Standalone 管理员边界可使用 HTTP Basic authentication。 Deployment 支持时，Bearer JWT 代表 hosted identity。 对受支持 standalone integration，带 scope 的 mbz API token 是首选自动化凭据。 选择最窄 credential 与 scope set，保存在源码外，暴露后及时轮换或撤销。 Client 要求 使用连接 deployment 要求的 authentication mechanism；凭据不进入 URL 或日志。 把 non success response 与 stable error code 当作状态机一部分，而不只是 transport failure。 对可能重试或有资金影响的 operation 使用 idempotency 与 reconciliation。 Integration 固定到已测试 Node version，升级前重跑 contract tests。 OpenAPI 或源码中出现 endpoint 但 effective capability 缺失时，不得推断支持。 Request 与 Response 工作流 消费 success envelope 前检查 HTTP status。精确内部 response schema 属于生成的 OpenAPI 合约。Client 配置中明确 base URL、Node version、credential type 与 expected capability。 错误、重试与 Compatibility 分别处理 401 、 403 、 404 、 409 、 429 与 5xx 。 订单、付款、退款或 settlement operation timeout 后核对权威状态。 Endpoint contract 未提供 idempotency 或 reconciliation 时，不重试资金 mutation。 升级前，让生成 client 与手写 integration 对准确 release tag 运行测试。 认证与 Scope 错误、重试与 Idempotency English canonical page" }, { "id": "zh-build-websocket", "path": "/zh/build/websocket", "canonical_url": "https://docs.mobazha.org/zh/build/websocket", "title": "WebSocket 事件", "summary": "使用已认证 WebSocket 事件及时更新 UI，再通过权威 HTTP API 核对重要状态。", "status": "beta", "audiences": [ "开发者", "客户端维护者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/websocket", "label": "WebSocket 事件" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/internal/api/ws.go", "label": "Mobazha WebSocket gateway 与 event registry" }, "reviewed": "2026-07-14", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "把已认证事件作为刷新信号，并在重连后恢复当前状态。", "estimated_time": "10 分钟", "journey": "build", "primary_action": { "label": "查看 Client 行为", "href": "/zh/build/websocket#client-行为" }, "language": "zh-CN", "translation_of": "/build/websocket", "search_text": "当前连接边界 默认 Node WebSocket endpoint 是 /ws 。路由多个 Node 的 deployment 也可能使用 Node specific path。Gateway 在连接加入 Node event hub 前完成认证。 完整、带版本的 AsyncAPI style event contract 尚未发布。当前 event envelope 只代表候选版本行为，应针对实际部署的准确 Node 与 client version 测试。 Client 行为 使用受支持 client authentication path；存在更安全 protocol 或 header mechanism 时，不把 token 放入 URL。 以有限 backoff 重连，并假定连接缺口会丢失 transient event。 对 persistent notification 去重，并容忍新增的未知 event type。 把 event 作为刷新受保护状态的信号；不得只凭未经验证的 push payload 结算、退款或完成订单。 即使 event 宣布 feature 或 action，也保留 route capability 与 authorization 检查。 预期结果 认证后，client 应只收到解析身份与 deployment 允许的 event。短暂断开后以有限 backoff 重连，并确认 client 先通过 HTTP 刷新当前 resource state，再启用操作。如果集成要求每个 transient event 都恰好一次、按业务状态顺序到达，则尚不完整。 Authentication 与 Connection Error 使用部署的 client 与 gateway 支持的认证方式。当有更安全的 session、cookie、header 或 subprotocol 边界时，不要在 WebSocket URL 中放入凭据。认证失败不得降级为匿名管理连接。 断开后使用带 jitter 的 backoff，并限制重试次数。 假定 gap 中会丢 event，重连后核对当前状态。 把 malformed 或 unknown event 当作非权威输入。 Event identity、version 或 resource binding 有歧义时，停止自动资金操作。 实现证据 WebSocket gateway Event registry Shared client English canonical page" }, { "id": "zh-build-mcp", "path": "/zh/build/mcp", "canonical_url": "https://docs.mobazha.org/zh/build/mcp", "title": "MCP 与 Agent 集成", "summary": "Agent 可以发现并调用获准商业能力，但不能取代用户同意、政策或后端授权。", "status": "beta", "audiences": [ "agent 构建者", "安全审核者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/mcp", "label": "MCP 与 Agent 集成" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/pkg/mcp", "label": "Mobazha Agent capability 源码" }, "reviewed": "2026-07-14", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "初始化已认证 MCP session，只发现其解析 scope 允许的 tool。", "estimated_time": "10 分钟", "journey": "build", "primary_action": { "label": "初始化 Transport", "href": "/zh/build/mcp#初始化-transport" }, "language": "zh-CN", "translation_of": "/build/mcp", "search_text": "当前 Transport Mobazha Node 在 /v1/mcp 通过 Streamable HTTP 提供 MCP，GET 与 POST 共用 endpoint。Discovery、authentication、scopes、tool availability 与 error 都是连接 Node version 的属性，而不是本页文字的属性。 当前 Authentication 与 Scope 合约 每个 /v1/mcp 请求首先通过 Node gateway authentication boundary。 Streamable HTTP front door 解析 caller identity，并要求 ai:use scope。 管理员身份取得适用 administrative scope set；API token 必须明确包含 ai:use 。 每个 tool 还要求 domain scope，例如 listings:read 、 orders:manage 、 wallet:read 或 chat:write 。 缺少所需 scope 的 tool 必须保持不可用或返回 permission denied；MCP 不绕过底层 HTTP authorization。 MCP scope guard Tool scope mapping 初始化 Transport 使用支持 Streamable HTTP 的 MCP SDK，并保留服务端返回的 session 信息。初始请求是已认证 /v1/mcp endpoint 上的标准 JSON RPC。 初始化后，完成 SDK 的 initialized notification、列出可用 tool，并只调用当前 identity 与 scope set 返回的 tool。 预期结果 Initialization 应返回与请求 protocol version 兼容的 MCP session。Tool discovery 只应展示 ai:use 、解析身份、domain scopes、runtime capabilities 与连接 Node version 共同允许的 tool。换一个更窄的可丢弃 token 重复 discovery，确认受保护 tool 消失或拒绝访问，而不是依赖 prompt 限制。 不可绕过的边界 认证适合该操作的人类、service 或 Agent identity。 请求最窄 scopes，明确 spend 或 settlement authority。 后端或政策要求时必须确认。 Prompt text 不得覆盖 order state、Quote terms、recipient amounts 或 authorization checks。 保留可审计 request、approval 与 result 标识，但不记录 secret。 Audit 与错误 Standalone server 记录结构化 MCP tool audit event，包含 tool name、result、duration、transport、可用时的 resolved identity 与脱敏 arguments。Bridge error 保留 API error boundary，包括 authentication、permission、conflict、rate limit 与 server failure。 Audit visibility 便于审核，但不会让广泛 token 变安全。创建范围窄、可撤销的 token，并让 secret 远离 prompt 与日志。 失败处理与 Compatibility Authentication 与 permission error 要修正 credential 或 scope，而不是重试 prompt。 Tool conflict 要重新读取底层 order 或 resource state。 Rate limit 与 transient server failure 使用有限 backoff。 Unknown tool 或 schema version 要重新 discovery，不盲调缓存定义。 Tool response 成功不能取代用户确认、付款证据或后端拥有的状态。 English canonical page" }, { "id": "zh-build-webhooks", "path": "/zh/build/webhooks", "canonical_url": "https://docs.mobazha.org/zh/build/webhooks", "title": "Webhook 集成合约", "summary": "在依赖事件投递前，让 consumer 能处理认证、重试、重复、乱序与版本变化。", "status": "beta", "audiences": [ "开发者", "运营者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/webhooks", "label": "Webhook 集成合约" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/pkg/webhook", "label": "Mobazha webhook engine 与 OpenAPI 合约" }, "reviewed": "2026-07-14", "page_type": "reference", "last_tested": "2026-07-04", "outcome": "认证、持久接收、去重并安全核对一次 webhook delivery。", "estimated_time": "15 分钟", "journey": "build", "primary_action": { "label": "实现 Delivery 验证", "href": "/zh/build/webhooks#delivery-envelope-与验证" }, "language": "zh-CN", "translation_of": "/build/webhooks", "search_text": "Consumer 检查清单 解析或处理 payload 前验证真实性。 使用稳定 event identifier 实现 idempotency。 只有持久接收后才返回 success。 通过权威 API 核对状态，不把 delivery order 当作 state order。 从日志与 dead letter 工具中移除凭据和个人资料。 当前管理表面 Node OpenAPI 合约在 /v1/webhooks 下包含 webhook registration、update、deletion、test delivery 与 delivery history operation。候选版本阶段，event name 与 payload schema 仍随版本变化。 Webhook source Signing、event、persistence、retry 与 delivery 合约。 OpenAPI JSON 查找当前 /v1/webhooks operation 与 schema。 Delivery Envelope 与验证 当前 event 使用 CloudEvents 1.0 structured JSON envelope。每次 delivery 包含 X Webhook ID 、 X Webhook Timestamp 与 X Webhook Signature header。Signature 是对 delivery ID、Unix timestamp 与准确 request body 计算的 HMAC SHA256，并带 sha256= 前缀。 用 endpoint secret 和未经修改的 raw body 验证 signature。 拒绝当前五分钟 replay window 之外的 timestamp。 用 CloudEvent ID 与 delivery ID 作为去重证据；不要假定到达顺序就是业务状态顺序。 只有持久接收 event 后才返回 2xx。 必须使用准确 raw request bytes；验证前 parse 再 serialize JSON 可能改变签名 body。 Signing implementation CloudEvent envelope 验证练习 注册非生产 endpoint，触发一次 test delivery 并保留 delivery ID。确认有效请求只持久接收一次；完全相同的 delivery 被去重；修改 body 后 signature verification 失败；replay window 之外的 timestamp 被拒绝。然后通过 HTTP API 核对相关 resource，而不是信任 event order。 Standalone 默认值 当前 standalone 默认最多投递五次，exponential backoff 从 30 秒开始、上限一小时，request timeout 为 10 秒，polling 为 5 秒，已完成 delivery 保留 7 天。Deployment 可以覆盖这些值，consumer 不得把默认值推断为保证的 retry schedule。 实际 delivery 是 at least once；重复与乱序是预期集成条件，而非异常 bug。 Authentication、错误与恢复 Webhook 管理 operation 要求受接受的 administrator、hosted 或 scoped API token identity。Receiver 使用 endpoint secret 与 signature header 认证 delivery。 只在持久接收后返回 2xx ；transient failure 应返回可重试的 non success。 执行业务效果前去重。 每个重要 event 后通过 API 核对 order 或 payment state。 手工 replay 前检查 delivery history 与 dead letter state。 Endpoint secret 暴露后轮换，并拒绝 replay window 之外的 signature。 English canonical page" }, { "id": "zh-build-extensions", "path": "/zh/build/extensions", "canonical_url": "https://docs.mobazha.org/zh/build/extensions", "title": "通过公共契约扩展 Mobazha", "summary": "选择最窄的类型化扩展机制，并保留 Core 权威、能力门槛、运行隔离、恢复和审计边界。", "status": "draft", "audiences": [ "扩展开发者", "架构师", "安全审核者" ], "applies_to": "设计方向，不代表已交付承诺", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/build/extensions", "label": "通过公共契约扩展 Mobazha" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/docs/extensions", "label": "Mobazha Open Core 扩展契约" }, "reviewed": "2026-07-04", "page_type": "concept", "outcome": "选择最窄的扩展机制，同时不转移 Core 对订单、付款、结算、密钥和审计的权威。", "estimated_time": "12 分钟", "journey": "build", "primary_action": { "label": "选择扩展机制", "href": "/zh/build/extensions#选择正确的机制" }, "language": "zh-CN", "translation_of": "/build/extensions", "search_text": "选择正确的机制 Port：替换 Core 所需能力的一种实现。 Module：把经过审核的能力组合进一个发行形态。 Function：定制有边界且确定性的业务决策。 Controller：协调外部系统或执行外部 I/O。 OrderExtension：把带版本的资源或跨阶段领域过程绑定到订单。 应选择只承担一个职责的最窄机制。一个包可以实现多个角色，但每个公共契约只能有一个权威边界。回调不会自动成为 Port，Module 也不是服务定位器。 保留 Core 权威 扩展只能提交声明、决策、观察或证明。Core 校验身份、授权、模式与契约版本、资源绑定、预期状态、幂等性、新鲜度和策略，然后才创建由 Core 拥有的命令或持久事实。 类型化领域契约可以表达需求时，不增加全局通用 Hook。 Core 保留发布策略、订单状态、支付验证、结算门槛、审计和密钥托管权威。 第三方代码不得导入 internal 包、接收完整 Core 对象或访问原始签名材料。 扩展不得写 Core 数据表，也不得直接调用内部状态迁移。 支付、退款、争议和结算变化必须重新进入带版本和幂等保护的 Core 命令与状态机。 设计规则 Ports 为窄小、由 Core 定义的能力提供可替换性。 Modules 提供不可变的启动期组合，并声明身份、版本、依赖、能力、配置、运行类型和生命周期。 Functions 有边界且确定性，不获得网络、数据库、密钥、时钟或状态迁移权限。 Controllers 消费持久 Core 事实来协调外部系统，只返回观察或证明。 各能力族遵守共享治理不变量，但领域管理器、业务契约和生命周期语义保持窄小、类型化和领域化。 新扩展点必须有所有者、模式、权限边界、失败语义、幂等与恢复模型、测试和移除计划。 不提供全局命名 Hook 总线、运行时可变注册表或万能 Core 服务定位器。 评审中的目标平台模型 Draft 状态的可组装扩展平台 RFC把长期目标整理为： 共享不变量覆盖身份、契约版本、作用域、提供方绑定、稳定原因和审计。支付、订单资源及未来领域管理器分别用自己的准入、运行、恢复和业务语义落实这些不变量。只有 Core 能决定输入是否可以改变 Core 拥有的状态。这不是一个中央控制面服务或万能 ModuleManager 。 以下维度彼此独立，不能压成一个混杂的插件分类： 维度 示例 包装与发布 Module 业务领域 支付、订单资源、库存、履约、税务、通知 契约角色 Port、Function、Controller、类型化领域契约 输出权威 声明、决策、观察、证明 交互方式 同步调用、持久事件、对账 运行方式 进程内静态组合、隔离进程或远程、Wasm 信任级别 第一方、经审核合作方、不可信 制品生命周期 Discovered、Verified、Rejected 提供方运行生命周期 Starting、Ready、Degraded、Draining、Stopped 能力暴露 Allowed、Configured、Advertised、Blocked 工作生命周期 Reserved、Funded、Delivering、Reconciling、Completed 数据所有权 Core、模块或外部系统 该模型目前是 Draft 方向，不代表每个领域管理器门槛和运行时都已可用。 保持领域能力族独立 支付是 Core 拥有的限界上下文。托管支付、直接观察支付和提供方结账会话可以使用不同适配器，但支付、退款、争议和结算状态仍由 Core 拥有。 OrderExtension 通过声明、预留、持久投递、观察或证明中的必要子契约，把订单关联资源或跨阶段领域过程绑定到订单。 库存、履约、税务、通知等提供方能力保留窄小的类型化契约和明确所有者。 内容、消息、密钥、存储等 Core 必需基础设施在用于替换实现时仍是 Port，不因此变成任意业务 Module。 共享治理不变量不等于一个万能描述符、管理器、生命周期或业务接口。 能力与信任门槛 能力可用性是带上下文的决策，不是一个全局布尔值。源码存在、标识符已知或代码已经链接，都不等于可以接纳新工作。 新工作必须通过适用的发行、兼容性、组合、授权、配置和就绪检查。 既有工作保留已持久化的提供方和契约绑定；关闭展示或新工作准入，不能遗弃结算、交付、补偿或对账义务。 因此领域管理器可以分别决定 admit new 、 service existing 和 reconcile 。 经审核的第一方模块默认静态链接。 独立分发或第三方基础设施默认在进程外运行。 商家编写的决策规则在该运行时引入后，应进入 Wasm 等受限沙箱。 降低隔离等级需要威胁分析和架构决策。 当前实现边界 受信任支付模块当前已经拥有领域专用的描述符、依赖排序、受限运行时授权、就绪与健康、setup gate、反向停止和回滚。静态 Order Extension v1 则独立校验精确契约、不可变启动期组合、依赖与循环、能力和接口一致性，并在缺失能力时失败关闭；同时提供只追加扩展记录、持久投递、类型化预留绑定，以及重新进入 Core 结算命令的结算证明。 这些已实现切片并不构成万能模块管理器。跨能力族治理记录、带租户和资源上下文的准入、第三方进程运行时及 Wasm Function 运行时仍是目标。健康、drain 和回滚只应在提供方运行语义确实需要时采用。 OrderExtension 范围与首个提供方 OrderExtension 不是 Collectibles 或 NFT 分类。当订单关联绑定必须在重启或提供方缺席时仍可恢复、稀缺容量需要在付款前预留、外部工作需要持久驱动，或者 Core 在自身状态迁移前必须校验证据时，才应使用该契约。 候选资源包括收藏卡 Hub 名额、限量库存、礼品卡兑换额度、活动门票、受监管商品批次和定制生产名额。它们只是建模候选，不代表对应提供方已经交付。每个提供方保留独立命名空间类型和私有领域载荷，并且只获得所需的子能力。 Collectibles 是首个已实现的提供方： 签名 NFT 元数据成为由 Collectibles 模块生成、带版本的 OrderExtension 声明。 Token 或库存分配在创建资金目标前通过模块拥有的 ReservationPort 完成。 铸造和交付是由持久扩展事件驱动的 Controller 工作。 交付证据成为由模块校验的 SettlementAttestation。 卖家收款仍由已有 Core 条件结算命令执行。 NFT、链、铸造、证书和提供方词汇不进入通用 Core API。 Collectibles 用来验证第一个实现切片，但不定义 OrderExtension 的范围，也不把 NFT 概念提升为万能 Core 抽象。开发期直接切换已经移除产品专用 Hook、结算命令、队列和 FiatMetadata 镜像。 评审新的扩展点 明确领域所有者、业务目的、调用者、声明者和授权者。 分别对输入、输出、描述符和兼容行为进行版本管理。 定义同步或持久投递、顺序、幂等、超时、重试、死信和对账行为。 声明能力门槛、权限、敏感数据以及重新进入 Core 状态机的位置。 提供迁移、回滚、移除、可观测性、负向测试和一致性证据。 如果这些答案尚不稳定，应把机制保留为私有实现细节，而不是发布另一个通用扩展点。 权威文档 ADR 018：Open Core 扩展架构 角色、权限边界、信任模型和架构不变量。 扩展架构入口 能力与安全模型 模块生命周期 Order Extension 契约 Collectibles Order Extension 演进 一致性测试 支付插件架构 Draft 可组装扩展平台 RFC 目标平台模型，不是已交付能力的权威来源。 English canonical page" }, { "id": "zh-reference", "path": "/zh/reference", "canonical_url": "https://docs.mobazha.org/zh/reference", "title": "参考与来源地图", "summary": "提议或自动化变更前，找到公开知识、运行时、合约与实现证据的权威。", "status": "current", "audiences": [ "开发者", "贡献者", "agent" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/reference", "label": "参考与来源地图" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha GitHub organization" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "找到拥有公开解释、运行时事实、版本合约或实现陈述的权威来源。", "estimated_time": "3 分钟", "journey": "build", "primary_action": { "label": "查看权威归属", "href": "/zh/reference#权威归属" }, "language": "zh-CN", "translation_of": "/reference", "search_text": "权威归属 mobazha/mobazha docs：canonical public knowledge、project policy、user guidance、跨仓库解释、RFC、project ADR 与 history。 mobazha/mobazha：community backend、生成合约、部署、code near architecture、conformance 与 Node release notes。 mobazha/mobazha unified：公开跨平台客户端实现、package 与 feature design、runtime capability handling 与 client release notes。 mobazha/mobazha.org：公开网站、定位与高层披露。 Evidence link 支持 canonical docs page，但不会成为第二个公开政策来源。连接的 backend、transaction record、generated contract 与 tagged release 仍是运行时与版本事实更具体的权威。 内部 Hosting 计划、凭据、运营 playbook、预测和未批准商业实验不是公开文档来源。 公开仓库 Mobazha Node Mobazha Unified Mobazha website Mobazha documentation English canonical page" }, { "id": "zh-project", "path": "/zh/project", "canonical_url": "https://docs.mobazha.org/zh/project", "title": "了解 Mobazha 项目", "summary": "区分当前产品模型、实现基础、长期方向与可依赖的项目事实，避免把愿景、政策和已交付能力混为一谈。", "status": "current", "audiences": [ "所有人", "贡献者", "评估者" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project", "label": "了解 Mobazha 项目" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开仓库与项目记录" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "根据问题进入正确的知识分组，并了解当前中文文档的覆盖边界。", "estimated_time": "4 分钟", "journey": "understand", "primary_action": { "label": "查看产品地图", "href": "/zh/project/product-map" }, "language": "zh-CN", "translation_of": "/project", "search_text": "按问题选择入口 想了解的问题 从这里开始 Mobazha 的店铺、市场、渠道和 Agent 如何组合？ 产品地图 订单如何经过支付、履约、完成和恢复？ 交易主线 费用由谁收取，如何理解经济边界？ 收费与经济模式 Mobazha 为什么存在，长期原则是什么？ 创始白皮书 当前版本、系统边界或治理记录具体是什么？ 英文项目事实入口 中文知识分组 左侧分组 用途 当前中文覆盖 产品模型 解释用户会遇到的对象、关系和交易主线 产品地图、身份与店铺、Offer 与履约、交易、市场、集成、Agent 产品基础 解释产品模型下面的运行与经济规则 系统架构、收费、兼容性、Packaging 与 Distribution 愿景与方向 解释项目存在的原因、长期原则与证据门槛 白皮书 v0.2、Draft 产品路线图 信任与治理 区分当前事实、政策、发布证据和治理记录 安全、法律与隐私、发布范围、治理、RFC、ADR、历史与 Release 顶部导航与英文站使用同一逻辑： 买卖、运营、开发、产品、项目、社区 。产品覆盖前三个解释性分组；项目承载信任与治理。Mobazha Docs 标志返回中文起始页。 当前中文覆盖边界 除已单独校验的白皮书外，当前 64 篇英文文档均已有同路径中文对应页。检查分别验证文件与导航覆盖、翻译元数据、内部链接和严重语义缺失；“中文文件存在”本身不再被视为内容完成。中文页应保留完成同一用户任务需要的决策、风险、验证、恢复和下一步，但英文仍是第一阶段政策与产品事实的 canonical authoring authority。 精确 API operation 与 Schema 继续由共用的 API Reference 和 OpenAPI JSON 提供，不复制 359 个 operation。 每个中文页保留与英文一致的 lifecycle status、page type、journey、version 与适用 visual，并明确链接英文 canonical page。 中文可以按照中文阅读习惯重组或压缩措辞，但不能把政策、任务或比较页缩减成摘要；白皮书继续使用独立版本与发布审阅。 产品代码中的 Route 或组件只作为文档需求线索。没有运行时能力、权限、失败路径、测试和发布证据时，不会把账号恢复、市场运营、高级经营、AI 或其他候选界面写成 Current 能力。 Runtime、交易、发布与法律事实仍由连接后端、订单记录、版本合约、tagged release 或其公开 policy owner 决定；翻译不会扩大产品、收费或治理承诺。 English canonical page" }, { "id": "zh-project-architecture", "path": "/zh/project/architecture", "canonical_url": "https://docs.mobazha.org/zh/project/architecture", "title": "Mobazha 系统与店铺网络如何协作", "summary": "比较 Direct P2P 和 Hybrid 店铺网络，并把请求追踪到拥有店铺与交易状态的后端。", "status": "beta", "audiences": [ "买家", "卖家", "运营者", "开发者", "评估者", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/architecture", "label": "Mobazha 系统与店铺网络如何协作" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开产品、Node、运行时与分发契约" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "区分 Direct P2P 与 Hybrid 店铺网络，识别每个决定的拥有后端，并追踪不同界面和服务之间的权威。", "estimated_time": "10 分钟", "journey": "understand", "primary_action": { "label": "比较两种拓扑", "href": "/zh/project/architecture#阅读拓扑" }, "featured_visual": { "id": "store-network-topologies", "src": "/images/docs/project/store-network-topologies.svg", "sha256": "5e26e8371ceff4a149019affbf4a2b3a2af3d6cc87465fd85001912ba19d5cb5", "mobile_src": "/images/docs/project/store-network-topologies-mobile.svg", "mobile_sha256": "9ec0813528f18df943a0ab0ef0efbac3143c8e6cf94cbad6a61b6be7cc5d63da", "kind": "conceptual", "width": 760, "height": 640, "mobile_width": 360, "mobile_height": 1040, "alt": "Two Mobazha store network topologies. Direct peer-to-peer shows a buyer resolving one self-hosted seller Node while another store remains a separate peer. Hybrid shows independent and hosted stores coexisting, with Hosting routing only hosted context and optional providers remaining separate.", "caption": "Direct P2P and Hybrid change how a store is reached and operated; the selected seller backend still owns its store and orders.", "claim": "Explains durable network and authority boundaries. It does not assert direct transport for every request, order replication between peers, or availability of every optional service in every distribution.", "privacy_review": "synthetic-only", "source": "https://github.com/mobazha/mobazha-docs", "source_revision": "store-network-topologies-v1", "applies_to": "Mobazha v0.3 release-candidate product and architecture model", "reviewed": "2026-07-06" }, "language": "zh-CN", "translation_of": "/project/architecture", "search_text": "阅读拓扑 Mobazha 是 Peer to peer，因为独立运营的店铺后端可以参与共享发现、签名内容、消息和交易协议，而无需把所有店铺或订单移入一个中心平台数据库。这 不表示 每个买家都要运行 Node、每个请求都必须在传输层直连，也不表示每个 Peer 都会收到所有订单副本。 两种拓扑都以选中的卖家后端作为稳定权威边界： 问题 Direct P2P 店铺网络 Hybrid 店铺网络 店铺运行在哪里？ 独立店铺自行运营的 Node 独立 Node 或托管 Commercial Node 买家如何访问？ Storefront、App、Direct link 或 Agent 解析卖家 Node 并请求动作 入口解析卖家上下文；Hosting gateway 路由托管上下文，独立上下文继续访问自己的 Node 哪些内容可以跨网络？ 已发布 Profile 和 Offer、发现信号、消息及明确协议请求 相同公开协议关系，加上单独启用的托管、索引、付款、配送、消息或自动化服务 哪些内容不会自动扩散？ 私有店铺数据、恢复材料、凭据和权威订单记录 独立 Node 数据和订单不会因为使用托管渠道或可选服务就移入 Hosting 谁决定订单是否改变状态？ 创建并拥有订单的选中卖家后端 选中的卖家后端，无论独立还是托管；不是入口渠道、Gateway、Index 或其他 Peer Direct P2P 指独立 Node 作为 Peer，而不是共享数据库。 Hybrid 指共存和有边界的服务组合，不是第三种订单所有者。一笔订单仍只有一个活跃后端上下文。 选择托管或自行托管 理解社群市场与分布式发现 检查连接后端能做什么 使用正确的架构视图 拓扑不会把所有 Actor、Client、Chain、Contract 和 Node component 放在同一张图上，因为它们属于不同架构维度。混在一起会让可选集成看似强制，或让共享服务看似权威。 视图 应回答的问题 使用来源 店铺网络拓扑 独立与托管店铺如何共存？哪个后端拥有订单？ 上述拓扑和本页 交易与保护流程 买家、卖家、付款证据、履约、退款、争议和仲裁责任如何交互？ 订单、付款与恢复和取消、退款或争议 体验与渠道拓扑 Web、Desktop、Mobile、Community、Embedded、Messaging 和 Agent 入口如何访问同一交易上下文？ 交互表面与集成 Node 组成 Core service、本地数据、内容存储、消息、钱包和服务商 Adapter 如何组成一个后端？ 下述六部分模型、自行托管及公开实现契约 付款与结算拓扑 一笔订单适用哪个 Rail、Wallet、Provider、Chain、Escrow 或 Settlement controller？ 卖家付款、订单绑定 Payment Session、运行时能力和适用服务商契约 只有当前能力和政策证据支持时，具体 Blockchain、Smart contract、Social client、Hosted service 或 Arbitration mechanism 才应出现在更具体的视图中。概念图中出现不表示普遍可用。 本页的位置 Mobazha 可以表现为 Storefront、Hosted application、Self hosted Node、Community market、Direct link、API 或 Agent workflow。它们不是相互独立的产品解释，而是围绕同一交易模型的界面和运营路径。 页面 回答的问题 产品地图 Mobazha 的主要产品概念和使用方式是什么？ 本架构页 哪些系统处理请求、状态位于哪里、哪个系统是权威？ 交易主线 订单如何经过付款、履约、完成和恢复？ 运行时能力 当前连接后端现在能做什么？ 发布范围 哪些能力有当前发布证据、受条件限制或仍是 Draft？ 如果只需要购买或销售，跟随任务指南即可。需要理解两个界面为何不一致、选择运营模式、集成服务或确定故障责任时再使用本页。 系统的六个部分 部分 用户看到或依赖什么 它可以决定什么 Presentation surface Storefront、Admin、托管 App、Web 或 Desktop client、Direct link、Community entry、Agent、API client 信息如何展示，以及请求哪个受支持动作 Selected backend 服务当前 Store 和 Order context 的托管或自行托管 Node 店铺数据、身份上下文、有效能力、授权和准入业务操作 Open Core 后端中的订单、付款验证、退款、争议、结算、保护和审计状态机 受保护转换是否有效，以及下一个权威状态 Adapter 与 Controller 付款、配送、消息、搜索、Webhook 和其他有边界集成 转换请求、观察和服务商结果，但不能直接创造 Core 状态 External system Blockchain、Wallet、Payment provider、Carrier、Messaging network、Indexer、AI provider 或其他明确服务 自己边界内的事实与动作 Public knowledge 与发布证据 Canonical docs、生成契约、Capability response、一致性测试和 Tagged release 公开政策的含义以及特定发布可以声明什么 长期规则很简单：界面可以请求动作，外部服务商可以报告事实，但拥有订单的后端决定这些输入是否形成有效业务状态变化。 一条请求如何经过系统 以买家打开 Offer 并付款为例： 界面解析上下文。 Storefront、Application 或 Agent 确定正在操作的 Store 和 Backend。 客户端发现可用性。 读取 Runtime configuration 和 Effective capability，而不是假设所有 Mobazha 部署相同。 后端创建业务记录。 创建订单前验证 Identity、Store policy、Listing revision、Quote、Authorization 和当前状态。 Core 绑定交易。 订单获得持久 Identity 与已接受条款快照；Payment Session 绑定预期 Rail、Amount、Funding target 或 Provider state、Expiry 和 Verification rule。 外部系统报告证据。 Chain observer、Wallet、Payment provider、Webhook 或运营者报告观察结果。报告是证据，不是跳过状态机的许可。 Core 接受或拒绝转换。 在推进付款或订单状态前核对预期 Order、Amount、Asset、Confirmation、Identity、Policy 和 Idempotency。 界面刷新权威状态。 买家、卖家、Webhook consumer 和 Agent 根据最新后端状态显示或行动，而不是仅根据通知。 配送、自提、取消、退款、争议和结算都遵循同一结构：集成提供有边界的输入，拥有后端验证受保护变化。 托管、自行托管与可选服务 运营路径 谁运行后端？ 谁负责运维？ 哪些内容仍独立？ 托管 托管服务运行适用商业分发并路由当前账号或店铺上下文 服务运营者按条款管理部署和可用性；店铺运营者仍负责 Catalog、Policy 和订单责任 Payment rail、Delivery、AI、Messaging 和其他服务仍是明确依赖 自行托管 卖家或独立运营者运行已发布 Node distribution 运营者负责主机安全、数据、备份、网络暴露、更新、监控与恢复 可选 Mobazha 或第三方服务单独启用，并披露交换数据和价格 Hybrid 自托管或托管后端调用选中的外部能力 责任按公开服务与交易契约分开 连接服务不会自动转移订单权威或本地恢复材料 托管和自行托管可以共享公开契约与 Core 行为，但不是同一 Distribution 或运营边界。买家不必理解仓库拓扑，运营者必须知道哪个后端拥有店铺以及谁为每项依赖负责。 选择托管或自行托管 运行和恢复自行托管 Node 查看分发与打包政策 在哪里找权威答案 用户问题 首先检查的权威 当前订单状态是什么？ 拥有订单的后端 应向哪里付款，已经验证了什么？ 订单绑定 Payment Session 与后端付款记录 此处是否提供该功能？ 连接后端 ready 的运行时能力响应 此人或 Agent 能否执行动作？ 后端 Authorization、Role、Scope、Store context 和当前状态 是否发生付款、配送或服务商事件？ 适用服务商证据，以及对其进行对账的后端记录 支持哪个精确请求和响应形状？ 生成契约和 Tagged release evidence 公开收费、安全或兼容规则是什么？ docs.mobazha.org 上的 canonical policy 此订单适用什么金额和收款方？ 公开政策范围内的已接受 Quote 与交易记录 文档用于解释这些权威，不能启用能力、改变订单或替代交易证据。 权威与恢复边界 Mobazha 把不同状态的权威留给各自负责的系统，避免互相竞争的事实来源。Presentation surface 可以请求动作，Externa" }, { "id": "zh-project-fees", "path": "/zh/project/fees", "canonical_url": "https://docs.mobazha.org/zh/project/fees", "title": "你支付什么，以及谁收取这些金额", "summary": "分别理解买家总额、卖家所得、服务费用、外部成本和退款规则，而不是把它们隐藏在一个模糊抽成里。", "status": "current", "audiences": [ "买家", "卖家", "运营者", "评估者", "agent" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/fees", "label": "你支付什么，以及谁收取这些金额" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Mobazha 公开收费政策、报价要求与发布证据" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "判断订单或服务的成本、每项金额的付款方与收款方、生效时间，以及取消或退款如何改变金额。", "estimated_time": "9 分钟", "journey": "understand", "primary_action": { "label": "阅读 Fee Quote", "href": "/zh/project/fees#阅读-fee-quote" }, "language": "zh-CN", "translation_of": "/project/fees", "search_text": "本页的位置 本页规定 Mobazha 应如何解释费用和成本。它不是价格表，也不会为某个托管套餐、付款轨道、卖家或交易虚构费率。 需要 应使用的来源 理解长期有效的收费与披露规则 本页 查看当前托管套餐或服务价格 Mobazha pricing 和 fees 确认某笔订单的最终总额和各收款方 付款前接受的最终 Fee Quote 或等价结账报价 理解商品、配送、付款和订单状态 结账指南和交易主线 理解长期经济原则 创始白皮书 直接回答 每笔 Mobazha 订单都要支付中心化抽成吗？ 不需要。在自己控制的基础设施上运行 Community 软件，本身不会产生强制 Mobazha 交易费。 开源是否等于所有东西都免费？ 不是。服务器、存储、支付网络、服务商、配送、插件、AI、支持、税费和可选托管服务都会产生真实成本。 Hybrid 是否意味着同时支付平台抽成和自托管成本？ 不是。Hybrid 表示组合方式，不是收费类别。运营者承担自己的基础设施，以及实际使用并单独接受的服务和外部成本。 每一项扣款都是 Mobazha 费用吗？ 不是。收款方可能是卖家、承运人、区块链网络、支付服务商、税务机关、运营者、推荐方或另一项明确服务。 买家何时应知道总额？ 在最终确认及资金投入前。后续页面不能悄悄增加新的强制费用。 卖家何时应知道净所得？ 在接受适用服务或订单条款前，包括卖家承担的费用和退款处理方式。 卖家、市场、运营者或 Agent 能否获得费用？ 在合法、明确出资、可归因、设有上限、充分披露，并正确处理退款或欺诈的前提下可以。 当前费率在哪里？ 在适用服务商或服务价格入口，以及当前交易 Quote 中；不在旧截图、讨论或示例百分比中。 阅读 Fee Quote Fee Quote 把买家付款和卖家所得分开。当前 Deal Link 代码路径使用名为 pilot zero fee v1 的启动政策：对于 $100.00 Offer，平台生成的买家总额和预计卖家净额都是 $100.00；如果 Node 订单含有 Quote 中没有的非零配送、税费、折扣或其他组件，接受流程会拒绝它。该名称描述价格尚未决定时的当前实现约束， 不是已批准的 Deal Link 费率、零费承诺或永久商业政策 。 下面故意使用非零假设报价，以便展示资金方向。它 不是当前 Mobazha 费率、税务判断或 Offer 。示例中买家承担配送和适用税费，卖家承担托管交易服务和付款成本： 项目 对买家总额的影响 对卖家所得的影响 收款方或处理方式 商品或服务 +$100.00 +$100.00 毛额 卖家 配送 +$8.00 收取 +$8.00，同时承担 −$8.00 履约义务 卖家或商家随订单收取并支付适用履约成本 适用税费 +$5.00 收取 +$5.00，同时承担 −$5.00 税务义务 卖家或商家收取；当前结算不会自动汇给税务机关 托管交易服务 — −$2.00 提供已披露服务的明确运营者 付款或结算成本 — −$1.00 明确的支付服务商或网络 示例结果 买家总额：$113.00 预计卖家经济所得：$97.00 配送和税费在示例中是代收义务，不是卖家收入 算式表达两个方向：由买家出资的项目增加结账批准金额；由卖家出资的项目从 $100.00 订单毛额中减少所得。真实 Quote 可以采用不同分配，但不能把同一项成本同时加给买家又从卖家扣除，除非它们是两个单独命名的费用。 钱包、区块链网络、支付服务商、承运人或税务机关仍可能在平台 Fee Quote 外收取适用外部金额。必须在资金投入前，于相应选择或结账步骤说明实际付款方和收款方。 当前标准结账中的税费 卖家配置匹配的税务规则后，当前标准店铺结账把商品展示价格视为未含税： 卖家定义百分比和适用的买家地区。 后端匹配买家配送国家，并按商品金额计算税费。 税费在订单总额中单独显示，并加入买家支付金额。 税费通过订单付款路径收取；当前系统不会拆分并直接汇给税务机关。适用税务处理仍由卖家或商家负责。 当前百分比应用于商品金额，不包括配送。Deal Link 接受流程会拒绝包含其启动 Fee Quote 中没有的非零税费、配送或折扣的 Node 订单。因此 Deal Link 目前不能把标准结账税费作为独立组件加入；这是能力限制，不是 Deal Link 必须永久零费的决定。 未来非零费用由谁出资 托管交易服务： 并非天然由买家或卖家支付。买家出资会增加买家总额；卖家出资会减少卖家所得。Quote 必须说明服务商、付款方、收款方、服务、金额或费率以及退款处理。 付款或网络成本： 可以由买家直接承担、卖家吸收，或包含在服务商价格中。Quote 或 Payment Session 必须说明实际方式，且不能重复计算。 税费： 当前标准结账能在商品展示价上增加卖家配置的地区税费，并随订单向买家收取。特定销售是否合法仍取决于适用法律、卖家或 merchant of record 安排、产品和地区。软件代收不表示 Mobazha 汇缴税款或承担税务义务。 配送： 所选履约条款决定成本包含在商品价内、加入买家总额、代承运人收取，还是由卖家吸收。 Offer 可以在买家选择配送或提供税费计算所需信息前显示商品价格。但如果已经知道存在必需附加费，就不能把该价格表述成最终应付总额；结账也不能在确认后悄悄增加费用。 未来接受任何非零 Quote 前，还必须说明： 货币或资产、汇率来源和时间、Quote 有效期； 固定和百分比组件、最低值、上限，以及百分比的计算基数； 每项是必需、可选、预估、可退还是取决于条件； 谁控制资金，以及何时向各收款方付款； 取消、部分退款、全额退款、争议、过期或付款失败后的处理； 随订单保存的政策与 Quote 版本。 如果产品无法生成这些信息，就不应悄悄扣除新费用。 五种不同金额 类别 购买的价值 常见收款方 必需披露 托管订阅 可用性、管理、配额、更新、备份、域名或支持 托管服务运营者 账期、包含容量、续费、取消、导出和超额条款 交易服务 付款执行、订单运营、配送协调、证据、争议处理或明确风险责任 实际提供服务的运营者 付款方、金额或费率、上限、覆盖服务、结算和退款处理 使用量或专业服务 AI、存储、CDN、通知、API、迁移、实施、培训或 SLA 明确服务商 计量方式、包含额度、超额价格、期限和退出路径 分发或推荐报酬 可归因的新增需求、策展或销售辅助 推荐方、市场运营者、Agent 发布者或其他已披露参与方 资金来源、受益方、归因窗口、上限、利益冲突和冲回规则 外部成本 Network gas、处理商费用、换汇、税费、承运费或第三方插件 网络、服务商、机关、承运人或插件运营者 原始成本或估算规则、收款方、波动性和已披露加价 “卖家收到的钱少于订单总额”不能证明存在平台抽成。结算记录必须保留每个差额的独立原因和收款方。 成本取决于运营路径 自托管 Community 软件 独立运行不要求托管订阅，也没有统一的中心 Mobazha 交易抽成。 运营者承担自己的基础设施、管理、备份、网络、支付和所选第三方成本。 可选 Mobazha 或第三方服务可以在披露服务商、价格、交换数据、续费和退出路径后单独收费。 托管服务 托管套餐可以对运营、可靠性、存储、域名、更新、自动化、AI、分析或支持收费。 免费 Beta 或免费层是当前服务政策，不是永久权利。 适用价格页和服务条款必须说明套餐、生效日期、限制、续费、取消和导出路径。 Hybrid 组合 自托管或托管店铺可以增加发现、消息、付款、配送、AI、支持或其他托管能力，而不转移订单权威。 每项新增服务必须说明服务商、付款方、收款方、计量或费率、交换数据、故障行为、续费和退出路径。 使用托管渠道触达独立店铺本身不会产生统一交易抽成。任何归因分发或交易服务费仍需明确出资和 Quote 披露。 应比较完整运营成本与责任，而不是只比较订阅、抽成或服务器账单标题。 Deal Link 或托管交易 交易相关费用只能由明确服务或责任支撑，例如执行、配送协调、证据、争议运营或风险处理。 低接触自动交付与高接触人工运营不必使用相同价格模型。 实际费率和金额由交易 Quote 决定，而不是本政策页。 分发、推荐与 Agent 报酬是可选的，必须有真实资金来源，通常由卖家或责任运营者选择。 只适用于披露窗口和上限内可归因、已结算的价值。 退款、欺诈和归因修正必须按已接受规则冲回或调整。 付费推荐和 Agent 利益冲突必须在影响付费决定前披露。 注册人数、招募层级和无限下级百分比不属于当前 Mobazha 政策。 资金如何经过订单 配置政策。 卖家、运营者和服务商发布适用的商品、配送、服务、推荐、税费和外部成本规则。 计算 Quote。 后端绑定当前商品版本、付款方、收款方、金额、货币或资产、有效期和适用规则。 买家确认。 在付款指令或服务商授权前展示最终总额和实质条件。 订单保存快照。 后续政策或价格变化不能悄悄重写已接受交易。 付款和结算对账。 系统记录指令、观察、验证、付给各方的金额和仍待处理部分。 恢复调整明确项目。 取消、退款、争议、失败或欺诈只能按已接受政策和当前状态调整授权金额，并保留审计记录。 Agent 可以比较或解释 Quote，但不能替代必要的用户确认、虚构收款方或把估算当成最终值。 各类用户应检查什么 买家 确认商品、" }, { "id": "zh-project-compatibility", "path": "/zh/project/compatibility", "canonical_url": "https://docs.mobazha.org/zh/project/compatibility", "title": "Mobazha 组件能否一起工作", "summary": "在连接系统或升级店铺前，检查客户端、后端、契约、能力、扩展、数据与分发版本的兼容性。", "status": "current", "audiences": [ "卖家", "运营者", "开发者", "分发者", "agent" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/compatibility", "label": "Mobazha 组件能否一起工作" }, "evidence": { "source": "https://github.com/mobazha/mobazha", "label": "Node 公开契约、运行时能力、迁移与一致性来源" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "判断两个 Mobazha 组件能否安全交换数据并保留业务含义，并确定部署前所需证据。", "estimated_time": "9 分钟", "journey": "understand", "primary_action": { "label": "执行兼容性检查", "href": "/zh/project/compatibility#快速兼容性检查" }, "language": "zh-CN", "translation_of": "/project/compatibility", "search_text": "本页的位置 兼容性比产品架构更具体，但不只是“请求返回了 JSON”。不同问题应使用不同来源： 问题 来源 哪个系统拥有请求或状态？ 系统架构 连接的后端现在能做什么？ 运行时能力 哪个 HTTP operation 或 Schema 存在？ API 与 OpenAPI 功能是否属于当前发布？ 发布范围 这些版本和组件能否安全协作？ 本页及适用发布证据 直接回答 客户端与后端都识别同名字段，是否代表兼容？ 不一定。授权、状态含义、幂等、确认、恢复和失败行为也是契约的一部分。 源码里存在 Adapter，客户端能否使用？ 只有分发版本包含它、契约版本匹配、运营者已授权和配置、依赖健康，且后端声明有效能力时才可以。 新客户端能否连接旧 Node？ 仅限客户端已经测试的版本和增量行为。缺少必需 Schema 或能力信息时必须 fail closed。 托管和自行托管店铺能否使用相同客户端与集成？ 可以共享公开契约，但认证、部署组成、启用能力、外部服务和运营责任可能不同。 成功的 happy path 是否证明兼容？ 不能。还必须覆盖冲突、重试、重复事件、超时、旧数据、迁移、降级和恢复路径。 快速兼容性检查 连接或升级两个组件前，回答以下七个问题： 身份： 涉及哪些精确客户端、后端、Package、Adapter 或分发版本？ 契约： 双方共同声明哪个生成的 HTTP、事件、Webhook、MCP、扩展或数据契约？ 能力： 连接后端是否把所需有效能力声明为 ready？ 授权： 当前身份是否拥有所需 Role、Scope、Store Context 和 Permission？ 语义： 双方是否对状态转换、金额、标识符、幂等、最终性和恢复达成一致？ 迁移： 现有数据、配置、凭据和服务商绑定能否安全升级和恢复？ 证据： 是否有覆盖这个精确组合的一致性、集成或发布测试？ 只要有一项未知，即使代码能编译或页面能显示，该组合仍未得到验证。 兼容性表面 表面 必须保持兼容的内容 应检查的证据 HTTP API Method、Path、Schema、Envelope、认证、稳定错误、幂等和状态影响 生成的 OpenAPI、负向测试、发布说明 Event 与 WebSocket Event identity、Payload version、排序假设、重连行为和刷新语义 事件契约、重复与重连测试 Webhook 签名、投递标识、重试、去重、Payload version 和对账 Webhook 契约、投递历史、消费者测试 Runtime configuration Schema version、Readiness、Deployment profile、Feature 与 Capability 含义 /v1/runtime config 、客户端 resolver 测试 交易状态 Order、Payment、Fulfillment、Refund、Dispute、Settlement 和 Protection 含义 状态机与交易一致性测试 标识符 权威 Asset、Chain、Payment、Store、Order 和 Capability identity 公开标识符契约与 normalization 测试 扩展与 Package 受支持的公开 Port、Module、Function、Controller 或进程外协议 版本化 Package 契约和组合测试 持久数据 Schema migration、服务商绑定、备份、恢复、回滚和导出 迁移测试、恢复后的代表性数据 数据库内部结构、具体 Constructor、私有 Hook、Composition Root 细节，以及可通过内部 Import 访问的代码，都不是公开兼容性承诺。 常见场景 新客户端连接旧后端 客户端应先读取 Runtime Schema 和 Capability Readiness。可以容忍增量未知字段，但不能把缺少的必需状态、畸形能力或不兼容 Schema 转换成“默认支持”。可选 UI 应保持不可用，而不是调用猜测出来的 Route。 集成识别了一个付款标识符 识别只证明标识符可解析或显示，并不证明分发版本包含 Adapter、卖家已启用、凭据存在、依赖健康，或当前 Order Mode 支持它。 服务商被禁用，但旧订单仍存在 新工作可以停止接纳，但已有订单会保留服务商绑定，仍可能需要观察、退款、结算或对账。兼容性包括履行这些历史义务的能力；悄悄选择另一服务商不是安全 fallback。 托管与自行托管共享 API Operation 形状可能相同，但认证、多店铺路由、限制、托管依赖和有效能力可能不同。集成必须发现上下文和能力，不能只按产品名称分支。 托管与自行托管店铺共享网络 共享发现、签名内容、消息或交易协议不会创建共享订单数据库。先解析选中的店铺和后端，再向该后端对账状态。Hosting gateway 可以路由托管店铺上下文，但不会因此成为独立 Node 的兼容代理或恢复权威。 Hybrid 兼容需要两层证据：Peer 或服务协议能够互操作，而且选中后端仍接受所需业务能力、身份和状态转换。 版本与变更规则 Patch release 应在修复缺陷和安全问题时保留受支持契约。 Minor release 可以增加向后兼容的 Operation、Field、Event、Capability 或 Extension point。 Major release 可以有意破坏受支持的 Wire、State、Package 或 Persisted data contract，但必须提供迁移指导。 RC 开发期间，即使看似很小的变更也需要明确审阅，因为稳定兼容性尚未声明。 改变状态含义、把可选服务改成强制、删除字段、削弱资金不变量或改变重试安全性，即使传输仍可解析，也属于 breaking change。 Breaking change 需要公开决策证据、迁移与降级指导、更新一致性测试、支持窗口、发布说明和文档影响审阅。 安全升级流程 记录运行中的后端、客户端、分发版本、契约、Capability Schema、配置和服务商版本。 阅读发布说明中的迁移、移除行为、能力变更和已知问题。 创建已验证备份，并保留上一个可运行制品和配置。 使用恢复数据测试代表性的店铺、订单、付款、Webhook、Agent 和恢复流程。 在受控环境升级，然后验证 Runtime Readiness 以及部署声明的每项能力。 接纳新工作前，对账现有订单和服务商绑定。 只沿文档说明的数据兼容路径回滚；旧 Binary 可能无法理解迁移后的数据。 安全备份和升级 处理错误、重试和幂等 什么能证明兼容 最强证据是使用代表性数据，对精确发布组合执行测试： 生成契约验证； Unit 与 State machine invariant； Standalone 与托管分发集成测试； 共享 Black box conformance test； 迁移、备份、恢复和降级演练； 重复、超时、冲突、依赖失败与恢复测试。 Mock 有助于开发，但不能证明生产分发、外部服务商或历史数据集兼容。记录精确版本，并把证据与发布或部署决定保存在一起。 English canonical page" }, { "id": "zh-project-distribution", "path": "/zh/project/distribution", "canonical_url": "https://docs.mobazha.org/zh/project/distribution", "title": "Mobazha 如何打包与运营", "summary": "比较源码构建 Node、托管服务、独立安装包和第三方 Appliance，避免混淆打包、能力和官方状态。", "status": "current", "audiences": [ "卖家", "运营者", "分发者", "安全审查者", "评估者", "agent" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/distribution", "label": "Mobazha 如何打包与运营" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/deploy/standalone", "label": "Standalone 打包、分发政策、发布与供应链检查" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "在保留能力事实、安全首次运行、用户控制、恢复、许可和诚实品牌声明的前提下选择或发布 Mobazha 分发版本。", "estimated_time": "10 分钟", "journey": "understand", "primary_action": { "label": "比较分发形式", "href": "/zh/project/distribution#分发形式" }, "language": "zh-CN", "translation_of": "/project/distribution", "search_text": "本页的位置 Distribution 是经过测试的 Mobazha Core、Adapter、Frontend、Configuration、Packaging、Update channel 和运营假设组合。安装器、品牌、主机或功能集合不同，并不会让它自动成为新交易协议。 问题 来源 应选择托管还是自行托管？ 选择部署方式 哪些系统拥有状态和依赖？ 系统架构 Package 是否允许且描述诚实？ 本页 制品是否就绪且兼容？ 发布范围、发布证据和兼容性 如何安装和恢复 Node？ 自行托管指南 分发形式 形式 谁运营？ 当前含义 主要责任 Community 源码构建 独立卖家或运营者 可在受支持环境构建和评估公开候选版本源码 主机、秘密、网络、数据、备份、更新、集成和事故响应 Mobazha 托管服务 Mobazha 或明确托管运营者 Beta 服务运营适用商业分发和托管基础设施 服务条款、可用性、租户隔离、数据处理、价格、导出和支持 Standalone 安装器或 Launcher 安装后的独立运营者 打包和更新机制可能处于预发布；稳定签名制品需要发布证据 制品完整性、首次运行、更新批准、回滚和本地恢复 Container、VPS Image 或 Appliance 独立分发者或运营者 在保留许可、安全、能力、来源和恢复规则时允许打包 安全镜像构建、披露、更新、支持和源码义务 品牌或垂直分发 其明确运营者 可选择 Profile、品牌、集成和服务组合，但不会创建新的 Core 权威 诚实品牌、兼容契约、明确本地功能，不做虚假官方声明 当前 v0.3 系列用于评估和测试网。打包源码或存在安装脚本并不能证明已发布稳定签名 Binary、自动更新或生产支持。 可以不同与必须保留的内容 Distribution 可以选择 Distribution 必须保留 托管或自行托管运营模式 拥有订单的后端和 Core 状态权威 包含的公开 Adapter 和 Build time feature 有效能力发现和 fail closed 行为 Store、Marketplace、Embedded 或 Vertical presentation 后端授权和受保护状态转换 品牌、域名、Theme、Support 和 Pricing 诚实披露服务商、付款方、收款方、数据和责任 基础设施服务商和更新渠道 制品来源、秘密安全、备份、恢复、导出和回滚 Distribution local feature 公开契约兼容，并与 Mobazha 项目政策明确分离 Frontend switch、Bundled adapter 或产品名称不能扩大后端安全实现的范围。分发者可以增加服务，但必须说明服务商，不能隐藏外部依赖或把资金权威移入展示代码。 用户如何选择分发版本 信任 Package 或托管服务前，询问： 谁发布和运营它？是否声称官方身份？ 包含哪个精确 Mobazha 版本、源码 revision、Capability manifest 和 Frontend？ 哪些服务是本地、托管、第三方、可选或必需？ 店铺数据、Identity key、Payment credential 和恢复材料存放在哪里？ 首次凭据如何生成，更新如何验证，备份如何创建，数据如何导出，失败如何回滚？ 适用哪些费用、限制、支持条款和外部 Endpoint？ 分发者或可选服务消失后，店铺和现有订单如何继续？ 如果发布者无法回答这些问题，安装器的便利性不能建立信任。 分发者要求 构建与来源 记录精确源码 commit 或 tag、构建输入、Capability manifest、Frontend revision、License、SBOM、Checksum、Provenance 和测试结果。 不得包含未批准付款能力、私有 Control plane code、隐藏支持访问、客户数据、服务商凭据或预生成用户秘密。 为精确制品履行对应源码、Notice、Attribution 和第三方 License 义务。 安全首次运行 在用户系统上生成管理员凭据、店铺身份、签名材料和本地秘密；若使用托管边界，必须明确披露。 以最小网络暴露启动，并要求明确配置 TLS、Proxy、Firewall、Domain 和远程管理。 展示外部 Endpoint、Telemetry、Update check 和可选托管连接；契约允许时应可禁用。 更新与恢复 通过文档化渠道签名并发布更新 Metadata，替换前验证完整性。 说明更新是自动、提示、运营者控制还是不可用。 迁移前备份，保留兼容回滚点，测试恢复，并说明 Reset 和 Export 路径。 禁用新能力后，仍应服务历史服务商绑定及现有订单恢复。 产品事实 只宣传该 Distribution 已包含、配置、授权、健康并测试的有效能力。 区分 Mobazha 项目政策与分发者自己的条款、价格、隐私、支持和本地功能承诺。 没有相应证据和授权，不得声称 Official、Certified、Audited、Production ready 或 Compatible。 品牌与认证 开源许可不授予 Mobazha 名称、Logo 或认证声明权。第三方 Image 可以准确说明包含 Mobazha 并标注源码 revision，但没有单独授权不能暗示 Mobazha 运营、认可、审计或支持该 Package。 未来认证项目可能检查来源、发布材料、能力事实、首次运行安全、更新、恢复和兼容性。参与公开契约不以认证为必要条件；认证项目正式发布前，“Mobazha Certified”不是有效公开状态。 重要使用前验证 安装到可丢弃环境或测试网。 验证制品身份、本地 Listener、Runtime profile、声明能力和外部连接。 创建店铺，完成一次代表性商品、Quote、付款、履约和恢复流程。 使用文档指定的兼容版本创建并恢复备份。 演练更新与回滚判断，不删除唯一店铺副本。 接受重要交易前记录运营者、支持路线、周期成本和事故负责人。 安装自行托管 Node 监控 Node 备份与升级 检查法律、隐私、许可与商标边界 English canonical page" }, { "id": "zh-project-whitepaper", "path": "/zh/project/whitepaper", "canonical_url": "https://docs.mobazha.org/zh/project/whitepaper", "title": "Mobazha 创始白皮书", "summary": "v0.2 公开讨论稿：面向 AI 时代的开放商业网络、独立经营单元、可问责参与和可持续公共能力。", "status": "draft", "audiences": [ "社区", "贡献者", "评估者" ], "applies_to": "设计方向，不代表已交付承诺", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/whitepaper", "label": "Mobazha 创始白皮书" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/blob/main/content/zh-CN/project/whitepaper.md", "label": "版本化的 Mobazha v0.2 中文公开讨论版" }, "reviewed": "2026-07-06", "page_type": "concept", "outcome": "理解 Mobazha 的开放商业网络、独立经营单元、双经济循环、参与原则和当前验证顺序。", "estimated_time": "22 分钟", "journey": "understand", "primary_action": { "label": "阅读摘要", "href": "/zh/project/whitepaper#0-摘要" }, "version": "0.2-discussion", "language": "zh-CN", "translation_of": "/project/whitepaper", "search_text": "发布状态 v0.2 是公开讨论稿，只表达原则和方向，不构成融资、Token、收益、所有权或已交付功能承诺。 0. 摘要 AI 正在把过去只有大型组织才能拥有的软件、内容、分析和执行能力分发给个人。但生产能力的普及并没有自动带来市场、信用、支付、分发和经营机会。一个人可以借助 Agent 完成更多工作，仍可能无法找到需求、取得信任、完成跨境交易、承担争议，或保留自己积累的商业关系。 Mobazha 希望建设一个由独立参与者共同使用并逐步参与建设的开放商业网络。个人、创作者、小型团队和 Agent 可以在共同规则上完成交易、建立店铺、经营市场、建设工具，并形成可核验的履约与参与记录。 这里所说的共同建设，建立在独立经营之上。参与者既可以经营自己的店铺、市场、服务或工具，也可以建设被其他经营单元复用的能力。共同基础设施连接这些单元，但不取代它们的品牌、客户关系、责任边界和退出自由。Mobazha 试图降低这种独立经营与相互协作的成本。 不是每一次参与都会自动产生经济价值。只有改善真实交易、经营结果、风险或公共能力的行为，才可能在明确规则和资金来源下获得回报。Mobazha 不以注册人数、关系位置、Token 价格或未来承诺制造繁荣，而以真实需求、真实履约和可持续收入检验自身。 1. 生产能力正在开放，商业机会仍然集中 工业时代和互联网时代的大型公司，把资本、人才、软件、分发、支付、数据和组织能力集中在同一边界内。规模降低了协作成本，也让大量商业机会只能通过公司职位或平台许可获得。 AI 正在降低执行成本和最小有效团队规模。个人与小团队可以更快地设计、开发、翻译、审核、营销和服务客户。但这不意味着大型平台会自然衰落。它们仍然拥有用户网络、品牌、数据、支付、物流、资本和合规能力，并且同样可以使用 AI 加强这些优势。 真正需要解决的不是“个人能否生产”，而是： 生产能力如何连接真实需求； 陌生参与者如何建立可承担责任的信任； 小型经营者如何使用过去只有大公司才能负担的商业基础设施； 建设市场、带来需求、维护工具和处理风险的人如何获得可解释的回报； 参与者如何在不依附单一公司或平台的情况下积累长期商业能力。 Mobazha 的机会不建立在某家公司必然向下的假设上，而建立在另一种结构性可能上：当通用生产能力越来越普及，开放网络可以让更多商业剩余保留在实际创造需求、供给、信任和能力的人手中。 2. 平台经济隐藏了哪些价值 一个市场从来不只由平台创造。它还依赖： 卖家的商品、服务、履约和售后； 买家的真实需求、验收和有效反馈； 运营者对品类、地区、规则和秩序的维护； 策展人和分发者对供需的筛选与连接； 开发者和 Agent 作者建设的工具； 验证者、仲裁者和基础设施运营者承担的责任。 在典型平台中，这些参与共同形成的数据、信用和网络效应，往往主要沉淀为平台资产。卖家难以带走声誉和客户关系，运营者难以证明自己带来的增量，贡献者的长期价值容易消失在公司职位、项目记录和封闭算法中，规则和分配也可以被单方面改变。 Mobazha 试图把其中可核验的部分重新表达为商业事实：谁完成了交易，谁承担了履约，谁带来了需求，谁维护了市场，什么工具被真实使用，什么风险被降低。事实可以被检查和申诉，并在有收入、预算和合规路径时进入经济分配。 3. Mobazha 是什么 Mobazha 是开放商业网络及其执行基础设施。它让独立经营者能够在共同规则上建立和连接交易、店铺、市场、工具与 Agent，同时保留各自的责任边界和经营自主性。 共同能力可以包括： 商品、服务和机器可读的交易条件； 支付、交付、退款、争议和证据； 店铺、市场、搜索、策展和分发； 可核验的履约、声誉和参与记录； Agent 的授权、执行、追踪和人工责任； SaaS、自托管和开放接口等不同使用方式。 Mobazha 不要求所有交易先进入一个中心商城。买卖双方可以在网站、社交网络、聊天、社群、线下关系或 Agent 中相遇，再使用 Mobazha 完成交易。不同市场也可以拥有自己的品牌、用户关系、经营规则和损益，而不必成为同一个中心市场的栏目。 开放不等于没有运营主体，也不等于没有收费。Hosting、支付执行、AI、搜索、争议处理、安全和支持都有真实成本。Mobazha 的商业主体应当通过透明服务获得收入，而不是隐藏费用、出售用户控制权或依赖投机性补贴。 4. 独立经营单元 Mobazha 的基本组织单元不是部门、职位或全平台积分，而是一个能够明确责任并单独核算的经营单元。 一个经营单元可能是： 一家独立店铺或一个商品系列； 一个垂直品类、地区或跨境市场； 一项支付、履约、验证或争议服务； 一个被真实交易使用的软件模块或 Agent 能力； 一个连接供给与需求的策展和分发网络。 无论形态如何，一个可持续经营单元都需要回答： 服务谁的真实需求； 谁提供商品、服务或能力； 谁负责日常经营和结果； 收入来自哪里； 直接成本、风险和损失由谁承担； 参与者按照什么规则获得回报； 如果经营失败，如何停止而不拖累整个网络。 这种结构允许不同的人做不同的事。有人拥有商品，有人理解一个地区，有人擅长连接社群，有人建设工具，有人负责验证和风险。参与者不需要先成为 Mobazha 的员工，也不需要所有人共同决定所有问题；他们可以在明确边界内承担一部分责任，并从这一部分的真实经营结果中获益。 经营自主性不等于法律意义上的股权或所有权。品牌、数据、收入、知识产权、决策权和退出权必须由实际产品能力、协议规则和明确合同分别界定，不能用“共同拥有”一句话代替。 5. 从一笔交易到开放网络 Mobazha 不假设必须先拥有巨大流量。更现实的演进顺序是： 5.1 成交 买卖双方已经在其他地方建立联系。Mobazha 帮助他们明确交易条件、接受可用支付、记录交付、处理退款或争议，并留下已结算结果。 5.2 店铺 重复交易的经营者形成商品、客户、履约和声誉账户，并选择适合自己的托管或自托管方式。 5.3 市场 多个卖家和经营者在自愿条件下被搜索、策展和连接，形成垂直市场、地区市场、合作伙伴渠道或其他独立发现入口。 5.4 网络 多个市场复用共同的支付、订单、身份、信用、Agent 和基础设施能力，又保留各自的品牌、责任、预算和规则。 5.5 协议共同体 当多个相互独立的经营者持续依赖并共同投入公共能力时，协议、安全、兼容性和公共预算才具备逐步共同治理的现实基础。 Agent 不是最后才添加的一层。它可以贯穿成交、店铺、市场和网络，帮助人发现机会、组织信息、执行任务和降低经营成本，但不能替代承担最终责任的人或组织。 6. 参与如何形成组织能力 开放网络不能只依赖创始团队寻找所有用户、运营所有市场和建设所有能力。它需要让机会、能力、责任和结果逐步可见，使合适的人能够在合适的边界内合作。 参与者可以从不同位置进入： 卖家和创作者提供合法商品、服务和持续履约； 买家提供真实需求、验收和有效反馈； 市场发起者和运营者选择方向、组织供给、维护规则并承担增长责任； 发现者、策展人和分发者降低寻找与筛选成本，带来可归因的需求； 建设者和 Agent 作者提供被实际经营持续使用的能力； 验证者、仲裁者和基础设施运营者处理证据、风险和可用性。 网络可以逐步形成公开的市场机会、能力需求和责任说明，由人和 Agent 辅助发现潜在合作，但是否适合、是否准入、如何分配收入和谁承担责任，必须由明确规则和可追责主体决定。 参与的路径不应停留在完成一次任务。能够持续创造结果的人，应有机会承担更完整的经营责任，发起新的经营单元，维护一个领域，或参与与其专业和风险相匹配的治理。 但参与记录不等于未来收入。推荐、策展和协作只有在降低成本、改善结果或带来已结算交易时，才可能获得有限、透明且可撤销的经济归因。网络不按人头、下线层级、早期位置或永久关系树分配收益。 7. 两个相互连接的经济循环 7.1 经营循环 这一循环首先属于具体经营单元。不同品类和地区拥有不同成本、风险和利润，不能用一套全局公式替代真实核算。 7.2 公共能力循环 只有扣除支付、基础设施、退款、坏账、争议、客服和必要风险准备后的余额，才可能成为可分配盈余。公共建设预算必须来自真实收入、明确拨款或已到账资助，不能依赖未来 Token 价格。 Mobazha 的商业价值来自两个结果：帮助独立经营单元更低成本地完成交易和增长，以及让多个经营单元共享原本难以单独负担的商业能力。只有参与者和基础设施双方都能形成可持续收入，这个网络才可能长期运转。 8. 价值记录与分配原则 8.1 真实结果优先 注册、浏览、持币、占位和制造活动数量不等于商业价值。完成交易、持续履约、带来真实需求、降低风险和建设被实际使用的能力，才可能进入经济估值。 8.2 事实、估值与兑现分离 系统先记录发生了什么，再由某个明确市场或预算决定如何估值，最后在具备资金、资格、地区和税务条件时兑现。贡献事实不能自动冒充收益权。 8.3 结算状态必须诚实 订单、分成和贡献应区分已观察、待确认、已结算、已撤销和争议中。退款期、验收期或责任未结束前，不能把可能发生的收入展示为最终收入。 8.4 回报与责任相匹配 经济回报来自商品销售、服务收入、订阅、使用费、明确营销预算或可分配盈余。治理影响来自持续责任、领域能力和可核验行为，而不是持币量、身份头衔或一次性贡献。 8.5 本地市场先于全球公式 每个经营单元先证明自己的收入、成本、风险和参与机制，再讨论跨市场公共预算。局部失败应能够停止，成功经验应能够被其他参与者复用。 9. 人与 Agent Mobazha 是 Agent 原生的，" }, { "id": "zh-project-roadmap", "path": "/zh/project/roadmap", "canonical_url": "https://docs.mobazha.org/zh/project/roadmap", "title": "Mobazha 接下来要证明什么", "summary": "了解 Mobazha 当前验证的产品结果、推进所需证据，以及仍属于探索而非承诺的想法。", "status": "draft", "audiences": [ "用户", "贡献者", "运营者", "开发者", "评估者", "agent" ], "applies_to": "设计方向，不代表已交付承诺", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/roadmap", "label": "Mobazha 接下来要证明什么" }, "evidence": { "source": "https://github.com/mobazha", "label": "公开发布范围、仓库里程碑、审计与经过审阅的产品路线图" }, "reviewed": "2026-07-14", "page_type": "concept", "outcome": "理解项目接下来要证明的用户结果、其价值，以及方向成为发布承诺前必须存在的证据。", "estimated_time": "8 分钟", "journey": "understand", "primary_action": { "label": "查看当前验证目标", "href": "/zh/project/roadmap#当前验证目标" }, "language": "zh-CN", "translation_of": "/project/roadmap", "search_text": "本页的位置 路线图描述期望的用户与产品结果。它不是所有讨论中功能的列表、交付日历，也不能证明某项能力已经存在。 需要 来源 当前发布中有什么？ 发布范围和连接后端 为什么构建 Mobazha？ 创始白皮书 项目下一步要证明什么结果？ 本路线图 哪项具体变更已提出或接受？ RFC、ADR 与决策 哪些实施工作正在进行？ 公开仓库 Issue、Project、测试和发布说明 内部计划上的日期或项目不会自动成为公开承诺；它必须经过接受、实施、测试、文档化和发布。 当前验证目标 近期目标不是功能数量，而是让不同用户都能完成并验证一条可信的候选发布闭环： 用户 要证明的结果 成功证据 买家 理解卖家、最终总额、付款指令、订单状态和恢复路径 一笔完整测试订单，Quote、Payment Session、履约和恢复状态都可检查 卖家 配置可识别店铺、发布 Offer、接收付款证据、履约并支持订单 可重复的店铺到订单运营，不依赖隐藏管理员修复 运营者 运行或提供健康、安全、可恢复的后端 诊断、监控、备份恢复、升级决策和事故责任证据 开发者或 Agent 构建者 发现能力、最小权限认证、调用公开契约并处理未知结果 版本化契约测试覆盖拒绝、重试、重复、冲突与恢复 评估者 区分当前行为、可选服务、费用、依赖和未来方向 公开发布、政策、兼容性与源码证据一致 在这条闭环可靠前，更大的 Marketplace、更多支付轨道或更多自动化只会扩大表面积，而不能证明核心价值。 近期结果轨道 结果轨道 要解决的用户问题 推进所需证据 买卖旅程 重要状态和恢复信息分散或含糊 经过测试的桌面与移动流程，清晰展示总额、付款进度、履约、退款和争议 独立运营 安装比安全长期运营容易 签名发布证据、安全首次运行、监控、备份恢复、迁移、回滚和支持指导 托管与独立一致性 不同组合中的产品行为可能漂移 共享契约、运行时能力事实、跨分发一致性和明确服务差异 付款与保护清晰度 Payment event、Verified payment、Order state、Settlement 和 Buyer protection 容易混淆 订单绑定 Payment Session、轨道特定恢复、可审计状态转换和诚实条款 公开集成表面 API、Event、Webhook、MCP、Extension 和 Agent 可能暗示越权 有 Scope 的凭据、稳定契约、幂等、能力 Gate、批准和失败测试 店铺与分发质量 发布 Listing 不等于完整商业体验 更好的身份、Storefront、履约、可见性、无障碍、国际化和运营证据 发布信任 源码存在常被误认为已支持 Checksum、Provenance、SBOM、兼容、迁移、已知问题和发布关联文档 这些轨道可以并行，但都不能绕过适用的安全、经济、法律、能力和发布门槛。 仍受门槛限制的探索 探索领域 潜在价值 必须先证明什么 更丰富的社群市场和垂直场景 连接聚焦需求与独立供给 运营责任、审核、发现质量、归因和可持续单位经济 Deal Link、Embedded 或社交入口 缩短已知需求到可归因订单的路径 不可变卖家与 Quote 绑定、隐私、渠道上下文、费用披露和恢复 更多付款与保护模型 服务更多地区、资产和风险偏好 保管、验证、最终性、退款、争议、合规、依赖与失败语义 AI、Agent 与可复用 Skill 减少设置和运营工作 有 Scope 的身份、批准、追踪、确定性政策、成本控制和人类责任 多店铺与更丰富 Storefront 让一个运营者区分品牌、Catalog、Policy 和受众 Store context、授权、数据所有权、路由、Analytics 和迁移边界 Browser、Messaging、TMA 或其他渠道 在需求所在位置触达用户 安全 Origin、认证上下文、能力发现、隐私和一致订单权威 Launcher 与托管更新 降低自托管摩擦 签名制品、平台验证、更新同意、健康检查、备份、回滚和恢复 更广泛扩展运行时 支持更多服务商和分发特定能力 稳定类型契约、隔离、最小权限、兼容、审阅和撤销 探索不等于计划发布。即使原型可用，也可能无法通过产品、安全、合规、运营成本或维护测试。 路线图不承诺什么 每个仓库设计或 Adapter 都会发布； 所有部署公开相同能力集合； 在发布证据存在前承诺稳定日期； 永久免费服务、零外部成本或统一抽成模型； Token 价值、交易挖矿、招募奖励、回购或投资回报； 旧数据、新 Binary、私有分发与第三方服务商自动兼容； Agent、Plugin、Marketplace 或托管服务可以绕过 Store、Order、Payment 或 User authority。 结果如何成为 Current 记录真实用户问题和目标结果。 审阅产品、安全、经济、法律和运营边界。 定义公开契约与 Capability 行为。 在相关分发版本测试实施和迁移路径。 用户流程、失败恢复、文档与支持证据保持一致。 发布范围、制品、已知问题和兼容性证据。 仓库 Issue 与 Project 跟踪执行细节，RFC 和 ADR 记录决策，Release note 说明实际交付。本页是公开结果地图，应在证据变化时更新，而不是随内部任务名称变化。 查看发布范围和成熟度 检查运行时能力 阅读公开决策与提案 English canonical page" }, { "id": "zh-project-security", "path": "/zh/project/security", "canonical_url": "https://docs.mobazha.org/zh/project/security", "title": "项目安全模型", "summary": "Mobazha 安全依赖明确权威、fail-closed capability、受保护签名材料、敌意输入假设与私下披露。", "status": "beta", "audiences": [ "运营者", "开发者", "安全审核者", "评估者" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/security", "label": "项目安全模型" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/SECURITY.md", "label": "Mobazha 公开安全来源" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "理解项目安全边界，并通过私下报告渠道处理疑似漏洞。", "estimated_time": "6 分钟", "journey": "understand", "primary_action": { "label": "查看安全报告方式", "href": "/zh/project/security#安全报告" }, "language": "zh-CN", "translation_of": "/project/security", "search_text": "信任边界 拥有订单的 backend 是其状态与受保护转换的权威。 Client 是不受信任输入与 presentation layer；隐藏控件不能替代 server authorization。 Payment rail、RPC、indexer、plugin、webhook、media 与 delivery system 是有独立 threat/failure model 的外部依赖。 Extension 取得最小 typed projection 与 scoped handle，而非通用 database 或 Core access。 敏感操作要可审计，但日志不应包含 secret 或无关个人资料。 Release 与供应链 当前 release 是 pre release candidate。最终 artifact 仍需 vulnerability scanning、dependency/license review、SBOM、checksum、provenance、reproducibility evidence、secret scan 与平台验证。 Node supply chain audit Unified supply chain audit 运营者安全 安全报告 使用受影响仓库的 GitHub private vulnerability reporting。不要在 issue、chat 或文档反馈中公开 exploit 细节、泄露凭据、签名密钥问题或客户数据。 English canonical page" }, { "id": "zh-project-legal-and-privacy", "path": "/zh/project/legal-and-privacy", "canonical_url": "https://docs.mobazha.org/zh/project/legal-and-privacy", "title": "法律、隐私、许可与商标边界", "summary": "区分软件许可、托管服务条款、隐私承诺、第三方义务与商标权。", "status": "current", "audiences": [ "用户", "运营者", "贡献者", "评估者" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/legal-and-privacy", "label": "法律、隐私、许可与商标边界" }, "evidence": { "source": "https://mobazha.org/terms", "label": "Mobazha 公开政策与仓库 Notice" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "确认某个 deployment 适用哪一份许可、条款、隐私声明、商标规则与运营者义务。", "estimated_time": "8 分钟", "journey": "understand", "primary_action": { "label": "确认适用文档", "href": "/zh/project/legal-and-privacy#适用哪份文档" }, "language": "zh-CN", "translation_of": "/project/legal-and-privacy", "search_text": "适用哪份文档 仓库 LICENSE、NOTICE、attribution 与 third party notice 约束源码使用与再分发。 Mobazha.org Terms 与 Privacy Policy 按其描述约束当前托管服务。 独立运营者负责自己的条款、隐私披露、合法商品、税务、数据处理与服务商。 源码许可不授予 Mobazha 名称、logo 或视觉身份权利；须查看 trademark policy。 Transaction specific Quote 与 seller policy 可以添加适用条款，但不能静默覆盖项目级公开边界。 Canonical 公开链接 Terms of Service Privacy Policy Fees and Paid Services Node license Node attribution Trademark policy 文档边界 本页提供导航与产品解释，不构成法律意见。文档冲突时，使用其公开 owner 的 effective policy 或 license，并报告不一致。 English canonical page" }, { "id": "zh-project-release-scope", "path": "/zh/project/release-scope", "canonical_url": "https://docs.mobazha.org/zh/project/release-scope", "title": "发布范围与成熟度", "summary": "文档会区分当前候选版本行为、Preview 与未来设计。", "status": "beta", "audiences": [ "所有人" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/release-scope", "label": "发布范围与成熟度" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/docs/releases", "label": "Mobazha Release 与仓库文档" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "区分当前 v0.3 候选版本行为、稳定保证、可选组合、提案与未来目标。", "estimated_time": "8 分钟", "journey": "understand", "primary_action": { "label": "查看当前发布边界", "href": "/zh/project/release-scope#当前-v0-3-候选版本边界" }, "language": "zh-CN", "translation_of": "/project/release-scope", "search_text": "状态词汇 Current：已审核公开政策或稳定项目事实。 Beta：已经可用或正在验证；兼容性与行为可能改变。 Draft：提案或文档合约；不能当作已交付行为依赖。 Historical：为上下文保留，并明确由其他内容取代。 当前 v0.3 候选版本边界 Mobazha Node 与 Mobazha Unified 是用于评估和 Testnet 的候选版本。 默认开源 Node 启用 BTC、BCH 与 LTC 付款方式，但仍受 effective runtime capabilities 与卖家配置约束。 源码中的 identifier 或 adapter 不会启用付款方式或创造兼容承诺。 稳定签名 binary 与 reproducibility attestation 仍待最终发布批准。 无法取得有效 runtime capability snapshot 时，client 必须 fail closed。 除明确维护的 translation 外，英文是仓库文档默认语言。 Community capability manifest Node v0.3.0 rc.1 notes Unified v0.3.0 rc.1 notes 依赖指南 问题 当前答案 需要验证 可以评估开源 Node？ 可以，在受支持环境从已审核公开源码构建 Commit、build prerequisites、Testnet、diagnostics 与 backup 可以使用托管应用？ 可以，作为 Beta 服务 条款、隐私、价格、服务状态与 deployment capabilities BTC、BCH、LTC 总是可用？ 否；它们在默认边界内，但实际可用仍有条件 Runtime capability、seller config、dependency health、Quote 与 payment instruction 每个 API/UI 都是受支持能力？ 否 Generated contract、runtime capability、authorization、configuration 与 release notes 稳定 installer 与 unattended update 已保证？ 否 Signed artifact、checksum、provenance、platform validation、rollback 与 final release notice Node to account binding 稳定？ 否，公开合约仍为 Draft Permission、exchanged data、revocation、test 与 version compatibility 实质使用应要求 tagged release 与配套 evidence，不要从 main branch、截图、设计文档或 feature name 推断 readiness。 Version specific 内容 准确 checksum、artifact、known issue、migration step、SBOM、provenance 与 implementation commit 属于每个 tagged repository release。本页管理共同成熟度语言与当前公开边界，不替代 release evidence。 English canonical page" }, { "id": "zh-project-governance", "path": "/zh/project/governance", "canonical_url": "https://docs.mobazha.org/zh/project/governance", "title": "文档与政策治理", "summary": "重要项目陈述需要 owner、source、review date、status 与清晰变更路径。", "status": "draft", "audiences": [ "贡献者", "维护者", "agent" ], "applies_to": "设计方向，不代表已交付承诺", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/governance", "label": "文档与政策治理" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/GOVERNANCE.md", "label": "Mobazha 公开治理与文档政策" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "确认政策、合约、发布、文档或实现变更所需的审核与发布路径。", "estimated_time": "8 分钟", "journey": "understand", "primary_action": { "label": "分类变更", "href": "/zh/project/governance#变更类别" }, "language": "zh-CN", "translation_of": "/project/governance", "search_text": "变更类别 Editorial：澄清措辞，不改变行为或政策。 Operational：改变安装、恢复、兼容或集成指南。 Policy：改变权利、责任、收费、治理、隐私或安全预期。 Protocol：改变互操作行为、状态转换或机器合约。 审核预期 项目级公开政策与解释在本仓库变更。运营与 protocol implementation 在 owner 仓库变更，并同步受影响文档、machine readable index、test、contract 与 release note。任何一层都不能静默覆盖 runtime state 或 versioned interface contract。 文档发布流程 Wave 0 盘点 authority、public source、lifecycle 与 stable URL。 Wave 1 保持 portal、兼容路由、source mapping、link check 与 deployment 健康。 Wave 2 从实现与公开合约生成 task first 用户、运营与开发指南。 Wave 3 发布审核后的 trust、security、economic、governance、ADR、RFC 与 whitepaper 内容。 Wave 4 评估 Agent 回答、维护 translation，并测量 freshness 与 support outcome。 Phase DOCS roadmap Content governance English canonical page" }, { "id": "zh-project-decisions", "path": "/zh/project/decisions", "canonical_url": "https://docs.mobazha.org/zh/project/decisions", "title": "公开决定与提案", "summary": "用 RFC 记录仍在评估的变更，用 ADR 记录已经作出的决定，用 History 保存被取代的公开材料。", "status": "current", "audiences": [ "贡献者", "维护者", "agent", "评估者" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/decisions", "label": "公开决定与提案" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/blob/main/docs/CONTENT_GOVERNANCE.md", "label": "Mobazha 文档决策流程" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "为要提出或检查的决定选择 RFC、ADR、政策页、Release note 或 History record。", "estimated_time": "5 分钟", "journey": "understand", "primary_action": { "label": "选择记录类型", "href": "/zh/project/decisions#选择正确记录" }, "language": "zh-CN", "translation_of": "/project/decisions", "search_text": "选择正确记录 RFC：仍需审核、证据或决定的重大公开提案。 ADR：持久架构或产品决定，记录上下文、替代方案、后果与 supersession。 History record：保留已替换或撤回的公开陈述，使旧链接和讨论仍可解释。 Task documentation：从当前权威推导的操作与解释，不能替代决策记录。 生命周期规则 Draft 或 Review RFC 不是已交付行为。 Accepted RFC 授权实现工作，但不能证明已实现或发布。 ADR 记录决定；运行时行为仍需 implementation、test、capability gate 与 release evidence。 被取代记录保持可读并链接 replacement。 安全敏感细节、凭据、私有运营、客户数据、预测与未批准商业假设不进入公开记录。 开始或检查记录 RFC 索引 ADR 索引 History 与 Supersession 文档治理 记录状态必须始终明确。不能从提案、已接受设计或代码存在推断 capability 可用。 English canonical page" }, { "id": "zh-project-rfcs", "path": "/zh/project/rfcs", "canonical_url": "https://docs.mobazha.org/zh/project/rfcs", "title": "征求意见稿（RFC）", "summary": "在把重大协议、政策、经济、安全、治理和跨仓库提案当成承诺前，先查看其状态与审阅记录。", "status": "current", "audiences": [ "贡献者", "维护者", "评估者", "agent" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/rfcs", "label": "征求意见稿（RFC）" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/tree/main/rfcs", "label": "Mobazha 公开 RFC 注册表" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "查找或发起公开提案，同时避免把 Draft 方向表述成已接受或已发布行为。", "estimated_time": "5 分钟", "journey": "understand", "primary_action": { "label": "打开 RFC 注册表", "href": "/zh/project/rfcs#当前注册表" }, "language": "zh-CN", "translation_of": "/project/rfcs", "search_text": "何时需要 RFC 公开协议或互操作契约发生变化。 订单、付款、结算、争议、身份、授权或保管边界发生变化。 费用、收款方、奖励、公共资金或经济政策发生变化。 新的可选托管依赖改变独立运行假设。 治理、许可、隐私、安全或跨仓库所有权发生实质变化。 状态模型 Draft： 编写尚未完成。 Review： 已准备好进行公开技术和产品审阅。 Accepted 或 Rejected： 已记录决定及理由。 Withdrawn： 作者不再提出该变更。 Superseded： 由另一份 RFC 取代。 Implemented： 发布证据确认已接受提案在明确范围内交付。 当前注册表 RFC 0001：创始白皮书发布契约 Review；规定白皮书升级状态所需证据和批准。 RFC 0002：可组合扩展平台模型 Draft；区分领域、契约角色、运行时、信任、生命周期和打包。 RFC 0003：可组合前端产品模型 Draft；区分部署、体验、渠道、代码包含关系和有效能力。 RFC 0004：Deal Link 单层归因 已由 RFC 0007 取代；保留早期仅人工审阅提案。 RFC 0005：Core 拥有的资源抵押品生命周期 Draft；提出独立的 Core 抵押品聚合，不与 Order Extension 或订单结算状态合并。 RFC 0006：Payment Kernel、Rails 与可信分发模块 Draft；提出类型化支付轨道、经过审阅的模块组合、按贡献路由和持久恢复边界。 RFC 0007：卖家出资的 Affiliate 归因与原子结算 Draft；提出把卖家出资的 Affiliate 输出纳入权威订单 release，而不增加第二套付款引擎。 RFC 0008：Node 密钥域与收款架构 Draft；提出拆分 Identity、Wallet 和 Settlement 域，并为订单授权密钥设置生产门槛。 RFC 0009：冻结 Payment Attempt 结算条款 Draft；提出在付款目标可用前冻结卖家付款、平台与取消费用、Affiliate、Moderator、Escrow 超时和争议政策。 RFC 0010：Guest Checkout 信任与保管模型 Draft；提出卖家保管的 Guest Checkout、逐链关闭门槛和订单 Scope 凭据。 RFC 0011：订单结算授权密钥 Draft；提出针对每个 attempt 的确定性硬化结算密钥，以及付款前 Moderator 可选性的密钥条件。 RFC 0012：内嵌钱包买家结算密钥与 Onramp 注资 Draft；提出由买家和卖家共同保管的参与者密钥类别，并允许经过审阅的内嵌钱包可信模块。 RFC 模板 必需 metadata 和审阅问题。 仓库 RFC 指南 Accepted 与 Implemented 是不同状态。只有发布证据和有效运行时能力才能证明能力已经交付。 English canonical page" }, { "id": "zh-project-adrs", "path": "/zh/project/adrs", "canonical_url": "https://docs.mobazha.org/zh/project/adrs", "title": "Architecture Decision Records", "summary": "保存持久技术与产品决定的理由、被拒替代方案，以及将来如何取代。", "status": "current", "audiences": [ "贡献者", "维护者", "架构师", "agent" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/adrs", "label": "Architecture Decision Records" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/tree/main/adrs", "label": "Mobazha 公开 ADR registry" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "查找 accepted architecture decision，并与提案或仓库本地实现说明区分。", "estimated_time": "5 分钟", "journey": "understand", "primary_action": { "label": "打开 ADR Registry", "href": "/zh/project/adrs#当前-registry" }, "language": "zh-CN", "translation_of": "/project/adrs", "search_text": "哪些内容属于 ADR 长期架构、权威、ownership、compatibility 或 publication decision。 不记录就会反复重新推导理由的选择。 影响多个 module、repository、deployment type 或 public contract 的决定。 Editorial change、日常实现细节与临时实验通常不需要 ADR。 当前 Registry ADR 0001: Markdown files are the documentation content authority Accepted。 ADR 0002: Mobazha Docs owns public knowledge Accepted。 ADR template Repository ADR guide 仓库拥有的架构决定 跨仓库索引只链接决定的 owner，不在本仓库复制或重新编号。 Open Core ADR 018: Extension architecture Open Core Extension 指南 安全阅读 ADR Accepted ADR 解释预定持久决定，但不会自行激活 capability、迁移 deployment，或证明每个仓库已完成。适用时仍要检查 implementation、conformance test、release note 与 effective runtime capability。 English canonical page" }, { "id": "zh-project-history", "path": "/zh/project/history", "canonical_url": "https://docs.mobazha.org/zh/project/history", "title": "History 与 Supersession", "summary": "保留已替换提案与指南，同时不让历史文本伪装成当前行为或政策。", "status": "current", "audiences": [ "社群", "贡献者", "评估者", "agent" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/project/history", "label": "History 与 Supersession" }, "evidence": { "source": "https://github.com/mobazha/mobazha-docs/tree/main/history", "label": "Mobazha 公开 History registry" }, "reviewed": "2026-07-14", "page_type": "policy", "outcome": "保留被取代的公开推理，同时不让历史提案伪装成当前政策。", "estimated_time": "5 分钟", "journey": "understand", "primary_action": { "label": "查看保存规则", "href": "/zh/project/history#保存规则" }, "language": "zh-CN", "translation_of": "/project/history", "search_text": "保存规则 历史材料可用于解释旧链接、比例、protocol idea 或 product assumption。必须放入明确 Historical 位置，并附原日期、旧状态、替换原因与当前权威 successor。 禁止事项 可以保存 supersession context 时，不静默删除被广泛引用的公开提案。 不把过期百分比或 capability claim 留在当前 task page。 不把历史设计写成受支持 API、付款方式、收费或治理规则。 不用 History storage 发布之前的私有材料。 当前 Registry 初始 content registry 尚未导入被取代公开 artifact。候选材料发布前要审核 source 与安全公开 provenance。 公开来源历史不变量 公开仓库只有一个已审核 public root，并只包含可发布 commit、tree、path、message 与 blob。Private provenance trailer、source to public map、Git note、replace ref、private ref 与 private only commit 不进入公开历史。License、notice 与可发布 authorship 承担 attribution；content safety、secret、license、architecture 与 test 仍是独立 gate。 History registry 与 template 当前收费 当前运行时能力 English canonical page" }, { "id": "zh-releases", "path": "/zh/releases", "canonical_url": "https://docs.mobazha.org/zh/releases", "title": "Releases", "summary": "使用仓库 Release 查找准确版本、Migration note、checksum 与 known issue。", "status": "current", "audiences": [ "运营者", "开发者" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/releases", "label": "Releases" }, "evidence": { "source": "https://github.com/mobazha/mobazha/tree/main/docs/releases", "label": "Mobazha GitHub Releases" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "找到当前 release evidence 与采用检查，不把 release candidate 当作稳定生产软件。", "estimated_time": "5 分钟", "journey": "understand", "primary_action": { "label": "查看当前候选版本", "href": "/zh/releases#当前候选版本" }, "language": "zh-CN", "translation_of": "/releases", "search_text": "当前候选版本 v0.3 用于评估与 Testnet。稳定 binary 与签名 release artifact 尚未发布。首个 release 默认启用 BTC、BCH 与 LTC，但受完整 effective capability 交集和卖家配置约束。 采用 Release 前 确认 repository、version、publication date 与 artifact integrity。 阅读 breaking change、migration、capability change 与 known issue。 在代表生产的环境测试 backup 与 rollback。 文档 Release Gate Node 与 Unified tag workflow 会验证 versioned release note 存在、必要公开指南可访问，且文档 source manifest 审核的正是将打 tag 的 commit。Tag 不得在公开指南仍描述另一 source revision 时创建 release。 此 gate 证明文档就绪，不替代 test、artifact provenance、signature、SBOM review、migration validation 或 runtime capability check。 Release 来源 Mobazha Node release notes Mobazha Unified release notes Published GitHub releases Reviewed public source revisions English canonical page" }, { "id": "zh-contribute", "path": "/zh/contribute", "canonical_url": "https://docs.mobazha.org/zh/contribute", "title": "参与 Mobazha", "summary": "选择 owner 仓库，提前讨论大型变更，保留公开合约，补测试、更新文档并为 commit sign off。", "status": "current", "audiences": [ "贡献者", "维护者", "agent" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/contribute", "label": "参与 Mobazha" }, "evidence": { "source": "https://github.com/mobazha/mobazha/blob/main/CONTRIBUTING.md", "label": "Mobazha 贡献与治理政策" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "把文档、client、Node、website、RFC 或 policy 贡献送到拥有它的仓库。", "estimated_time": "5 分钟", "journey": "community", "primary_action": { "label": "选择 Owner 仓库", "href": "/zh/contribute#选择仓库" }, "language": "zh-CN", "translation_of": "/contribute", "search_text": "选择仓库 Node business logic、deployment、public API、extension、conformance 与 release evidence：mobazha/mobazha。 Buyer/seller UI、responsive experience 与 runtime capability client behavior：mobazha/mobazha unified。 Brand website、pricing、service terms 与 public marketing：mobazha/mobazha.org。 项目级 public policy、task guidance、跨仓库解释、Agent discovery 与文档质量：mobazha/mobazha docs。 贡献合约 大型 architecture、protocol、payment、security 或 governance change 前先开 issue 或 discussion。 保持变更聚焦，并一起更新 test、schema、docs、migration guidance 与 release note。 不包含 credential、private endpoint、customer data、proprietary code 或 generated release binary。 Owner 仓库要求时，对源码贡献使用 DCO sign off。 漏洞通过私下渠道报告，不使用公开 PR 或 issue。 仓库指南 Contribute to Mobazha Node Contribute to Mobazha Unified Improve this documentation English canonical page" }, { "id": "zh-support", "path": "/zh/support", "canonical_url": "https://docs.mobazha.org/zh/support", "title": "获取帮助并报告问题", "summary": "可复现的产品问题使用公开支持，代码缺陷使用仓库 Issue，安全问题使用私密报告。", "status": "current", "audiences": [ "所有人" ], "applies_to": "当前公开项目政策或服务界面", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/support", "label": "获取帮助并报告问题" }, "evidence": { "source": "https://mobazha.org/status", "label": "Mobazha 公开支持入口" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "把产品问题、可复现缺陷、文档问题或安全问题送到正确的公开或私密渠道。", "estimated_time": "3 分钟", "journey": "community", "primary_action": { "label": "选择支持渠道", "href": "/zh/support#选择渠道" }, "language": "zh-CN", "translation_of": "/support", "search_text": "选择渠道 在 Mobazha Unified 中打开 Me → Help & Support → Documentation；桌面版 Footer 也链接到同一个权威文档站。 文档 Issue 文档过期、缺失、不清晰或互相冲突。 Node Issue 可复现的后端、部署、API、支付或运营缺陷。 Unified Issue 买家、卖家、浏览器、响应式或前端缺陷。 Telegram 社群帮助和当前服务问题。 Discord 社群讨论和帮助。 从故障边界开始 症状 首先检查 可复现时的最佳渠道 托管页面或登录不可用 服务状态、浏览器网络结果，以及其他公开页面是否可访问 当前服务问题先走社群支持；只有能复现产品缺陷时才提交仓库 Issue 本地 Node 无法启动 精确 commit、启动参数、数据目录权限、端口、磁盘和 doctor json Node Issue 缺少店铺控制项 runtime config 就绪状态、能力、当前身份、店铺上下文和卖家配置 展示问题走 Unified；后端能力错误走 Node 未观察到付款 订单 ID、预期资产、地址、金额、有效期、确认数和依赖健康状态 保存脱敏证据后提交 Node Issue；不要盲目再付一笔作为测试 订单、退款或争议状态异常 权威订单状态、付款记录、最近动作和生效政策 状态权威错误走 Node；后端正确但前端展示错误才走 Unified Webhook 或集成重复执行 投递或事件 ID、签名结果、端点响应和对账记录 投递行为走 Node；消费者去重问题由集成维护者处理 文档与行为冲突 页面 URL、审阅日期、部署版本、能力快照和冲突结果 文档 Issue 不要同时改变多个层。先在最小的本地或可丢弃边界复现，再报告拥有错误状态的组件。 写出有用的报告 说明是托管还是自行托管、精确版本或 commit、操作系统和相关能力状态。 提供最小复现步骤、预期行为、实际行为和脱敏证据。 搜索已有 Issue，并链接相关文档或发布说明。 不得包含 Access Token、私钥、助记词、钱包恢复材料、客户数据或私有基础设施详情。 订单或付款问题只提供关联记录所需的脱敏标识符。明确资金是仅收到指令、已观察、已验证、已结算、已退款还是仍未知；这些状态需要不同的恢复动作。 安全问题例外 疑似漏洞、泄露凭据、签名密钥问题和 Exploit 必须使用受影响 GitHub 仓库的私密漏洞报告，不能先发到社群聊天或公开 Issue。 English canonical page" }, { "id": "start", "path": "/start", "canonical_url": "https://docs.mobazha.org/start", "title": "Choose how you want to use Mobazha", "summary": "Start as a buyer, seller, Node operator, developer, or project evaluator without learning the repository layout first.", "status": "beta", "audiences": [ "everyone", "agents" ], "applies_to": "Mobazha v0.3 release candidate", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/start", "label": "Choose how you want to use Mobazha" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha public repositories" }, "reviewed": "2026-07-06", "page_type": "hub", "outcome": "Reach the shortest trustworthy path for the job you want to complete.", "estimated_time": "3 minutes", "journey": "start", "primary_action": { "label": "Explore the hosted app", "href": "https://app.mobazha.org" }, "language": "en", "search_text": "Choose your path Buy from a store Review the seller, total cost, payment instruction, order state, and recovery path. Start selling Prepare a store, publish listings, accept supported payments, and fulfill orders. Run your own Node Evaluate, install, secure, monitor, and recover a self hosted deployment. Build an integration Use the API, events, MCP, webhooks, and extension contracts. Understand the project Inspect architecture, release scope, economics, governance, and security. If the first decision is who should operate the backend, compare hosted and self hosted responsibilities before creating a store or moving data. What you should know before committing Buyer: identify the store operator, final total, payment instruction, order owner, and recovery route before sending funds. Seller: verify one complete listing to fulfillment journey, including payment observation and a failed order recovery path. Operator: prove health, backup, restore, updates, network protection, and incident ownership before accepting material transactions. Developer or Agent builder: discover runtime capabilities, authenticate with the narrowest scope, and reconcile unknown outcomes before retrying mutations. Evaluator: separate current release candidate behavior from Draft direction, and distinguish software fees from hosted, provider, network, delivery, and tax charges. Know the current maturity Mobazha is currently release candidate software. A page marked Current describes reviewed behavior; Beta may change; Draft communicates direction and is not a promise. The connected backend is authoritative for runtime capabilities. A document never grants a capability that the backend does not advertise. Go directly to a public surface Use the hosted application Explore the current hosted buyer and seller experience. Run the open source node Build the release candidate from source and operate it yourself. Inspect the shared frontend Review the client used by hosted and self hosted deployments." }, { "id": "zh-start", "path": "/zh/start", "canonical_url": "https://docs.mobazha.org/zh/start", "title": "选择使用 Mobazha 的方式", "summary": "无需先理解仓库结构，直接以买家、卖家、Node 运营者、开发者或项目评估者身份开始。", "status": "beta", "audiences": [ "所有人", "agent" ], "applies_to": "Mobazha v0.3 候选版本", "knowledge_authority": { "kind": "public-knowledge", "url": "https://docs.mobazha.org/zh/start", "label": "选择使用 Mobazha 的方式" }, "evidence": { "source": "https://github.com/mobazha", "label": "Mobazha 公开仓库" }, "reviewed": "2026-07-14", "page_type": "hub", "outcome": "为当前要完成的工作找到最短且可信的路径。", "estimated_time": "3 分钟", "journey": "start", "primary_action": { "label": "体验托管应用", "href": "https://app.mobazha.org" }, "language": "zh-CN", "translation_of": "/start", "search_text": "选择你的路径 从店铺购买 核对卖家、总成本、付款指令、订单状态和恢复路径。 开始销售 准备店铺、发布商品、接受支持的付款并完成履约。 运行自己的 Node 评估、安装、保护、监控并恢复自行托管部署。 构建集成 使用 API、事件、MCP、Webhook 和扩展契约。 理解项目 查看架构、发布范围、经济模式、治理和安全边界。 如果第一个问题是“由谁运营后端”，请在创建店铺或迁移数据前先比较托管与自行托管的责任。 正式投入前应知道什么 买家： 付款前确认店铺运营者、最终总额、付款指令、订单所有者和恢复路线。 卖家： 验证一次从商品发布到履约的完整流程，包括付款观察和失败订单的恢复路径。 运营者： 在接受重要交易前证明健康检查、备份、恢复、升级、网络防护和事故责任都已落实。 开发者或 Agent 构建者： 发现运行时能力，使用最小权限认证；写操作结果未知时先对账再重试。 评估者： 区分当前 RC 行为和 Draft 方向，也要区分软件本身、托管服务、服务商、网络、配送和税费。 了解当前成熟度 Mobazha 当前仍是候选发布软件。标记为 Current 的页面描述经过审阅的行为；Beta 可能变化；Draft 只表示方向，不构成承诺。 连接到的后端是运行时能力的权威来源。文档不会赋予后端没有声明的能力。 直接进入公开入口 使用托管应用 体验当前托管的买家和卖家流程。 运行开源 Node 从源码构建候选版本并自行运营。 查看共享前端 检查托管和自行托管部署共同使用的客户端。 English canonical page" } ] }