Appendix Quick Reference

This appendix holds the quick-reference content from the manual body: glossary, status tables, document relationships, permission codes, FAQ, entry conventions, historical import.

Appendix A Glossary (pinyin order, with English)

Appendix B Status Quick-reference

Supply-chain order (10 states)

Sale order (7 states)

Return order (4 states)

Cycle count

No state machine. The system counts in real time: move shelf / split / mark destroy, into the stock movement log, no total-stock change. Book-vs-physical discrepancies are corrected with proper documents (in/out/destroy).

Appendix C Document-relationship Diagram

This diagram connects the core documents: supply side (purchase → stock-in → AP), sale side (sale → stock-out → AR → return), and the cost chain from purchase to profit.

Supply side (AP line):

st=>start: Supplier
a=>operation: Supply-chain order
b=>inputoutput: Stock-in doc -> stock(5 dims) +, cost + freight per batch
c=>subroutine: Supply settlement (freight allocated by volume)
d=>operation: AP / payment records
e=>end: Cleared
st->a->b->c->d->e

Sale side (AR line + return branch):

st=>start: Merchant
a=>operation: Sale order (snapshot + freeze stock)
b=>inputoutput: Stock-out doc -> stock decrease, release occupied
c=>subroutine: Sale settlement (cost from supply batches)
d=>operation: AR / receipt records
ok=>end: Cleared
ret=>condition: Return happens?
r1=>operation: Return order -> return stock-in
r2=>operation: Price confirmed
r3=>end: Refund (return finance)
st->a->b->ret
ret(no)->c->d->ok
ret(yes, right)->r1->r2->r3

Any stock movement can be traced to its source document (stock-in / stock-out / return / transfer / destroy) via the Stock Movement Log.

Appendix D Permission-code List

Page permissions (page_*, one per sub-menu)

Data read/write permissions (supply & sale sides)

Product / brand / warehouse / finance modules have page permission only — open means read/write, no finer field split.

Appendix E FAQ & Troubleshooting

Appendix F Data-entry Conventions

• SKU code: keep stable once used; it's the join key across stock/order/finance. Renaming/recoding breaks links.
• Volume (m³): required and real. Per-unit volume drives freight allocation & loading; wrong → system-wide distortion. Derive from L/W/H (cm) if needed, but prefer direct m³.
• Has tax (has_tax): set by the product's true tax attribute; affects sale tax.
• Country of origin / customs code: mandatory for cross-border; fill once accurately at creation.
• Merchant region (tax zone): pick correctly when creating a merchant; decides tax rate.
• Naming: fill spec name in zh/trad/en separately for multilingual teams & portal display.
• Unit / UOM: unify to avoid the same product in different units.
• Tax zone / finance type: configure before opening business orders.

Appendix G Historical Data Import (non-daily module)

Used only at go-live initialization or data migration; not needed in daily ops. Entry is in System Admin's import functions.

Three import types:

Stock migration: confirm the replacement scope

The dashboard’s Historical stock import reads inventory_stock.csv. Review product and warehouse matches and select the rows to write. Quantities retain up to two decimal places in the SKU’s inventory unit; packaging does not multiply them. Blank, negative, invalid or overprecise quantities are blocked. Ambiguous codes require a deliberate match. Only repeated pairs with both source product and warehouse codes complete keep the last row. Records with missing codes stay separate until each target is identified. The preview and execution results show source row numbers for reconciliation. If separate records point to the same target SKU and warehouse, clarify whether they are duplicates or parts of a total before choosing the value to write.

This is a full replacement within the current owner account. Confirmation first zeros stock across every shelf and lot, including stock absent from the CSV, then sets the selected default-dimension quantities. Existing dimensions and costs remain, and movements are recorded. Reserved or blocked inventory prevents the reset; resolve the related business records before cutover.

A rejected batch stops the process. Retry includes every row in that batch and preserves completed batches. Skipped batches remain unmigrated. Leaving the page or switching accounts stops later requests; already submitted requests may have completed, so inspect stock and movements before continuing. The reset and individual batches are separate requests rather than one migration-wide transaction.

Agent-assisted data migration has a different scope. MCP opening_stock sets a SKU-and-warehouse’s default stock dimension, without an account-wide reset or a replacement of stock on every shelf and lot. The target cannot fall below that row’s reserved and blocked quantities. Review existing dimensions and choose opening balances or historical replay to count physical stock once. See Bring your data.

Product images: review, upload and retry

Name each image after its SKU code, such as CASE-12.png. Parse the selected files, review the matched products and select the images to import. Multiple source images for the same SKU or ambiguous product matches are excluded; keep one image per SKU before continuing. Confirming replaces that SKU's current picture.

The page uploads sequentially and stops at a failed item. Correct the issue and confirm again to resume there; earlier successful uploads are not repeated. Leaving the page or switching accounts stops subsequent uploads and clears local previews. An upload already received by the server may have completed, so check the actual picture before restarting after an uncertain result.

What a historical order import changes

Purchase imports create receipts, add inventory and confirm purchase costs. Sales imports create dispatch records, deduct inventory and calculate costs when enough stock with purchase costs is available; otherwise the order remains placed. Both imports create tax invoices. No payment records are generated by default: actual amounts and dates are required to record cash flows. Verify the original documents, inventory and actual payments before importing.

Expand an order preview to enter a positive actual payment amount in CAD and its actual date. You can also add the optional Wholety extension columns Paid Amount (CAD) and Payment Date to the header CSV. Dates accept YYYY-MM-DD or YYYY/MM/DD and use the Toronto business date. For a payment in another currency, supply all three independent columns: Paid Currency, Paid Amount (FC) and Paid Exchange Rate. The foreign amount must equal the CAD amount multiplied by the payment exchange rate. The order's own currency amount and exchange rate are not payment evidence.

A closed order, posting date or due date does not prove payment, and a partial payment does not mean the balance is settled. Confirmation shows the payment count and total CAD amount; results show recorded payments and orders imported without payment records separately. Orders can be imported without payment evidence, then actual cash flows can be recorded through Finance.

Source numbers, retries and canceled documents

The header CSV's Internal Number is an external source reference. Wholety generates an independent order ID and shows the source-to-system ID mapping in the results. Use the system ID for order lookup, later payments or dispatch. Different owner accounts can use the same source number with separate data. Existing historical order IDs and amounts remain unchanged.

Within one owner account, each order type and source number is imported once. Editing the visible remark does not allow a retry to repeat inventory movements or payments. Duplicate header numbers, including 500 and 000500, block submission. Source numbers must be positive integers within the exact integer range; scientific notation is rejected.

For the source Canceled / Cancelled flag, N means normal, Y canceled and C a cancellation document. Canceled and cancellation documents cannot enter the normal inventory and finance import; invalid flags also block submission. Document Status=C means closed and is evaluated separately: an uncanceled closed document can still be imported, and closed status does not prove payment. Retaining canceled history requires a separate process; it cannot justify normal receipts, dispatch or cash flows. This guard does not automatically reverse existing historical inventory or payments.

Reviewing import amounts

Purchase payables use imported goods amount plus the order discount. Tax is recorded separately, and freight is accounted for separately. Sales receivables use imported goods amount plus all discounts (negative) plus tax. The original Document Total is retained for comparison; it cannot replace the calculated payable or receivable, or prove an actual payment.

Expand “Import amount review (CAD)” to enter an additional order discount (negative for a reduction) or adjust the tax for this import. The header CSV also accepts the optional Wholety extension Order Discount (CAD). Sales line discounts from the original before/after unit prices are preserved; the additional order discount is allocated on top of those line discounts. Do not enter the same discount twice. Unexplained differences in source totals are not automatically treated as discounts.

CAD goods amounts prefer the original CAD row total divided by the original quantity. Without a row total, they use unit price and the currency exchange rate. Imports use delivered quantity when provided, otherwise the original quantity. Partial deliveries include only the goods and tax for the imported portion; enter only that portion's additional order discount. Header-only tax is allocated by goods amount, or quantity when goods amount is zero, with allocations adding up to the exact cents.

Differences in source totals, tax or quoted prices, and partial deliveries, require an explicit review of the import amounts. Changing discount or tax resets that review. Sales CAD unit prices support two decimal places and purchase unit prices six; original prices, currencies, quantities and row totals are retained in the source log. Invalid numbers, excessive precision and discounts exceeding net goods value block submission and cannot be bypassed with the review checkbox. Confirmation shows purchase payables or sales receivables separately from actual payment totals.

Owners have full access. Subaccounts need the Order Import page permission together with the relevant order write, approval, purchase cost write or sales price write, supply or sales finance, warehouse in/out and finance board (tax invoice) permissions. Any missing permission rejects the request before records are created, and the page lists what is missing. Agent API Keys need write access for imports.

Available stock for sales imports is physical stock minus blocked quantities and other orders' reservations. Only purchase stock with recorded acquisition costs is used. Orders can draw from multiple warehouses; each actual receipt or dispatch has its own record with quantity, cost and warehouse source. Subaccounts can import orders only for suppliers or merchants in their visible scope.

Results show created, dispatched and still-placed order counts separately, with stock or settlement failure reasons for orders that were not dispatched. A created order may still need dispatch through the normal workflow after its blocking issue is resolved. Importing the same document again skips it.

General flow: download system template → fill by template → upload & validate → system batch-writes.

⚠️ The template's column structure (required fields, format) follows the actually downloaded template in the system. Always pilot a small batch and verify before writing, to avoid dirty data polluting master data. Import is irreversible writing — confirm data correctness before acting. Specific template fields & examples should be added here after viewing the system import UI (pending screenshot verification).

Appendix ends. The manual body (Ch.1–12) + Appendix (A–G) form the complete user manual. System screenshots are in place; the English (En) version is complete and switchable from the top bar.