On this page
- System profile
- Mandatory layer separation
- Read before any shop change
- Routing contract
- Data model contract
- Critical technical invariants
- Configuration contract
- Payment security
- Channel security
- Rights and trust
- Template and Design Contract
- Task-to-file matrix
- Forbidden abbreviations
- Workflow for AI agents
- Minimum tests by area
- Final report of an AI
Reference status: 2026-07-24
This reference is the binding short context for AI agents who analyze or expand the shop. The technical declaration for people is under Shop guide.
System profile
domain: dbxShop
runtime: PHP/dbxapp
frontend_module: dbxShop
admin_module: dbxShop_admin
database_server: dbxShop|dbxShop.db3
schema_source: dbx/modules/dbxShop/dd
frontend_service: dbx/modules/dbxShop/include/dbxShopService.class.php
repository: dbx/modules/dbxShop/include/dbxShopRepository.class.php
admin_service: dbx/modules/dbxShop_admin/include/dbxShopAdmin.class.php
admin_access_group: admin
schema_sync_version: shop-dd-20260713-2
development_data_allowed: true
Mandatory layer separation
dbxShop.class.php
-> wertet dbx_run1 aus
-> delegiert an dbxShopService
dbxShopService
-> steuert Frontend-Use-Cases
-> verwendet dbxForm/dbxTPL
-> ruft dbxShopRepository und Provideradapter
dbxShopRepository
-> synchronisiert DD
-> liest und schreibt Shop-Fachdaten über dbxDB
-> berechnet/verwaltet Zuordnungen, Orders, Bestand und History
dbxShop_admin.class.php
-> delegiert an dbxShopAdmin
dbxShopAdmin
-> steuert Admin-Use-Cases
-> verwendet dbxForm/dbxReport/dbxTPL
-> ruft dasselbe Repository
No SQL queries in templates. No checkout or pricing logic in JavaScript. No second repository or ORM layer next to dbxDB/DD.
Read before any shop change
Depending on the order at least:
17_Shop_Leitfaden.md
dbx/modules/dbxShop/dbxShop.class.php
dbx/modules/dbxShop/include/dbxShopService.class.php
dbx/modules/dbxShop/include/dbxShopRepository.class.php
dbx/modules/dbxShop/cfg/config.php
dbx/modules/dbxShop/dd/{betroffene-dd}.dd.php
dbx/modules/dbxShop/fd/{betroffene-fd}.fd.php
dbx/modules/dbxShop/tpl/htm/{betroffene-template}.htm
dbx/modules/dbxShop_admin/include/dbxShopAdmin.class.php
dbx/modules/dbxShop_admin/fd/{betroffene-fd}.fd.php
For payments:
dbxShopPayPal.class.php
dbxShopAmazonPay.class.php
fd/checkout.fd.php
At Channels:
dbxShopChannelConnector.class.php
dd/shopChannel.dd.php
dd/shopProductChannel.dd.php
Routing contract
frontend:
default: catalog
routes:
catalog: catalog
start: catalog
product: product
detail: product
cart: cart
checkout: checkout
paypal_start: paypalStart
paypal_return: paypalReturn
paypal_cancel: paypalCancel
amazon_pay_return: amazonPayReturn
amazon_pay_cancel: amazonPayCancel
order: orders
orders: orders
invoice_pdf: invoicePdf
channel_webhook: channelWebhook
legal: legal
terms: legal
return: withdrawal
returns: withdrawal
withdrawal: withdrawal
admin:
default: dashboard
routes:
- dashboard
- install
- products
- product_edit
- product_tree_move
- product_channel_mapping
- products_help
- groups
- attributes
- product_attributes
- shipping_groups
- channel_groups
- channels
- media
- assign_media
- orders
- order_detail
- order_invoice
- order_invoice_pdf
- legal
- returns
- settings
- payment_test
New routes are registered in the module router and delegated to a named service method. No hidden actions only over unchecked $ GET-/$ POST-Introduce branches.
Data model contract
Each table needs:
primary_field: id
primary_semantics: integer-autoincrement
schema_owner: DD
database_access: dbxDB
Current DD/table mapping:
shopProduct: shop_product
shopProductGroup: shop_product_group
shopProductGroupMap: shop_product_group_map
shopProductImage: shop_product_image
shopAttributeDefinition: shop_attribute_definition
shopProductAttributeValue: shop_product_attribute_value
shopShippingGroup: shop_shipping_group
shopProductShippingGroupMap: shop_product_shipping_group_map
shopChannel: shop_channel
shopProductChannel: shop_product_channel
shopChannelGroup: shop_channel_group
shopChannelGroupChannel: shop_channel_group_channel
shopProductChannelGroupMap: shop_product_channel_group_map
shopOrder: shop_order
shopOrderItem: shop_order_item
shopOrderHistory: shop_order_history
shopWithdrawal: shop_withdrawal
Relationship rules:
product_primary_group:
denormalized_field: shop_product.product_group_id
normalized_map: shop_product_group_map
primary_marker: is_primary
product_shipping_groups:
map: shop_product_shipping_group_map
product_channels:
direct: shop_product_channel
inherited_via:
- shop_product_channel_group_map
- shop_channel_group_channel
product_images:
product_reference: product_id
group_reference: group_id
cms_media_reference: media_id
orders:
header: shop_order
items: shop_order_item
events: shop_order_history
withdrawals: shop_withdrawal
A DD change requires:
- Adjust DD file.
- Check database-dependent defaults and indices.
- schema sync version Increase consistently in repository and configuration when the automatic sync needs to run again.
- Check sync on an empty and an already initialized test database.
- For each new table id/Autoincrement on all supported DB drivers.
Critical technical invariants
Article 1
sku: stable-and-unique-business-key
slug: url-safe
active_catalog_visibility: active=1 AND trash=0 AND channel=shop
price_authority: server
tax_authority: server
shipping_authority: server
stock_authority: server
Order
order_no: stable-public-reference
items: snapshot-at-order-time
legal_text: optional-snapshot-at-order-time
withdrawal_text: optional-snapshot-at-order-time
payment_payload: provider-result-not-authorization
history: append-business-events
foreign_order_access: forbidden
duplicate_provider_return: must-not-create-duplicate-order
Article prices or titles may exist shop order item-Do not change snapshots afterwards.
Shopping cart
storage: PHP session
key: dbxShop_cart
trusted_price: false
trusted_tax: false
trusted_stock: false
The shopping cart stores selection and quantity. Before checkout, product, availability and prices can be read from the repository on the server side again.
Configuration contract
Source: dbx()->get cfg('dbxShop').
general:
- enabled
- default_channel
- default_currency
- price_display
- tax_display_enabled
- default_tax_class
- tax_rates
- b2b_mode
- stock_enabled
- channels_enabled
checkout:
- checkout_guest_allowed
- legal_snapshot_enabled
- withdrawal_button_enabled
mail:
- mail_customer_enabled
- mail_admin_enabled
- mail_from
- mail_admin_to
payment:
- payment_bank_transfer_*
- payment_invoice_*
- payment_paypal_*
- payment_amazon_pay_*
delivery:
- delivery_digital_download_enabled
- delivery_flat_shipping_enabled
- delivery_flat_shipping_gross_price
media:
- media_usage_content_id
- media_usage_slot
Do not introduce equivalent values in a second configuration file. cfg/payment.php is currently only a PayPal fallback; The admin configuration is in dbxShop-Config.
Payment security
providers:
offline:
- bank_transfer
- invoice
online:
- paypal
- amazon_pay
secrets:
render_in_html: false
log_plaintext: false
commit_real_values: false
provider_result:
verify_server_side: true
bind_to_order: true
persist_status: true
append_history: true
A redirect or query parameter is not evidence of payment. The adapter must process the provider response on the server side and assign the order based on a stored reference.
Channel security
default_channels:
- shop
- amazon
- ebay
- kleinanzeigen
- mobile
webhook_route: "?dbx_modul=dbxShop&dbx_run1=channel_webhook&channel={key}"
required_controls:
- active_channel
- order_import_enabled
- webhook_secret_or_provider_signature
- normalized_payload
- stable_external_reference
- duplicate_protection
- failure_logging_without_secrets
A prepared connector is not a guarantee of production API coverage. If changes are made, check official provider requirements, existing credentials and the specific code. No live calls as part of a normal local test without an explicit order.
Rights and trust
admin_module_group: admin
request_ids_trusted: false
session_ids_trusted: false
posted_prices_trusted: false
posted_status_trusted: false
uploaded_filenames_trusted: false
webhook_json_trusted: false
An ID from $ SESSION helps to recover, but does not replace property/rights verification. For Order, Invoice, Withdrawal and Media, record reference plus authorization must always be validated.
Template and Design Contract
- Shop edition used dbxShop|...-templates.
- Product cards and details may be selected via article groups.
- Template names are validated as allowed module templates.
- Global page shell comes from the active frontend design.
- Shop-CSS remains under dbxShop/designNot as a copy in any global design.
- Shop-Admin-CSS remains under dbxShop admin/design.
- Joint amendments shall be made to: dbxapp and Flowers be tested.
Task-to-file matrix
| Task | Primary files |
|---|---|
| New front-end route | dbxShop.class.php, dbxShopService.class.php, template |
| New admin route | dbxShopAdmin.class.php, Admin Template/FD |
| New data field | relevant DD, repository, FD/Form, template |
| New table | new DD, repository synclist, schema version |
| Catalogue filters | Repository/Service, Filter-FD, catalog templates |
| Product presentation | Product group fields, shop templates, shop-CSS |
| New payment method | own adapter, Checkout-FD, Service, Settings-FD |
| New channel | Channel-DD/Defaults, connector, admin form, mapping |
| New admin list | dbxReport, Selection-FD, Report Template |
| new input mask | dbxForm, DD/FD, template |
Forbidden abbreviations
- No table directly only with CREATE TABLE Create.
- No manual ID assignment as a replacement for Autoincrement.
- Do not accept prices or permissions from the browser.
- Leave no external secrets in source code/Testdaten.
- Do not issue orders based on a free ID alone.
- Mark no production payment by simulated return as successful.
- Do not import channel message without authentication.
- Do not treat an empty webhook secret as implicit sharing and do not read webhook secrets from GET query strings.
- No browser return, order no-Treat parameters or cancel link as evidence of payment.
- No major HTML output new as a PHP string build if a template fits.
- No kernel change as long as the problem is solved within the shop module.
Workflow for AI agents
- Read actual status in router, service, repository, DD, FD and template.
- Name affected invariants and rights.
- Design data model change first in DD.
- Implement domain logic in Repository/Service.
- output and input via template, dbxForm or dbxReport tethering.
- Consider error paths, repetition and transaction limits.
- perform tests with existing test data; Test data may remain.
- Empty database, existing database and autoincrement check if the scheme is affected.
- Guest, user and admin check if access is affected.
- Update human and AI documentation when a contract changes.
Minimum tests by area
schema:
- empty_database_sync
- existing_database_sync
- id_autoincrement
- foreign_key_like_references
catalog:
- active_visibility
- shop_channel_visibility
- query_search
- group_filter
- attribute_filter
cart_checkout:
- add_update_remove
- server_price_recalculation
- invalid_customer_data
- missing_legal_acceptance
- stock_conflict
order:
- unique_order
- item_snapshot
- own_access
- foreign_access_denied
- invoice_access
payment:
- disabled_provider_hidden
- missing_credentials_hidden
- success
- cancel
- provider_error
- repeated_return
admin:
- non_admin_denied
- forms
- reports
- bulk_actions
- secret_masking
channel:
- inactive_rejected
- invalid_signature_rejected
- duplicate_payload
- export_error_persisted
design:
- dbxapp
- flowers_light
- flowers_dark
- responsive
Final report of an AI
The report separates:
- Data model /Schema,
- Repository/Fachlogik,
- front end,
- administration,
- external provider/Channels,
- tests and test data used,
- open risks or deliberately non-production integrations.