Known Limitations and Phase History

Known limitations, by area

Live end-to-end verification. Across nearly every apply flow in this guide (accounting accounts, mappings, inventory account category, cost centers, product catalog prerequisites/categories/items), the actual internal-endpoint HTTP round trip through a genuinely running Shumoul.Api process was not exercised — verification instead relies on mocked-repository unit tests plus, in several phases, direct SQL inspection of a real dev database. The Tenant Starter Kit's own live verification (Phase 5F) is the one exception that did exercise a real TenantDbContext against the real dev database (see below) — but even that run had the actual internal-bridge HTTP hop mocked.

No downgrade cleanup. If a tenant loses a SubscriptionFeature (e.g. a plan downgrade), any settings values already patched by onboarding, or any starter data already applied, are never reverted or cleaned up. Entitlement checks only ever gate future applies.

Ambiguous multi-row cases are reported, never guessed. A tenant with more than one active InventoryAccountCategory row, more than one BusinessType/ProductDepartment sharing a name, or more than one AccountingChartTemplate marked default for the same activity all resolve to a blocked apply with a clear message — never a best-guess pick. A real "which one is the default" design for the genuine multi-category-tenant case is a deliberately unbuilt future need.

No JSON/Excel import for Cost Center or Product Catalog templates — only Accounting Chart Templates have both import paths today; the others are admin-CRUD-only. A bounded, precedented future addition following AccountingChartTemplatesController's existing import pattern if ever needed.

MenuClaimSeeder's AppController model has no nested sub-controller support — see SaaS Admin Authorization and MenuClaims.

The "non-root caller restricted to its own tenant" branch of TenantAccessGuardBehavior has no way to be exercised by a real caller today — the seeder never grants TenancyPermissions.* to any non-root tenant. Pure defense-in-depth, not a currently-reachable code path.

Shared-DB tenants processed back-to-back in one host process could transiently see stale settings (FIXED). A cross-tenant IAppSettingService/CashierAppsSettings caching artifact was found while live-verifying the Cash/Bank GL-currency linking step for a second shared-DB tenant processed in the same long-lived process. Never a Starter Kit orchestration defect — the root cause (a tenant-unaware cache key shared by a process-wide IEasyCachingProvider singleton) and its fix (every AppSettings cache key now embeds the resolved tenant id) are documented in Subscription Packages & Entitlements, Chapter 17.

First-login automatic trigger deliberately deferred. Neither tenant entitlement provisioning nor any starter-template apply is triggered automatically at first login — touching the login/auth path was judged high-risk before real production subscribers existed on the platform. A manual repair endpoint and the existing onboarding-apply trigger were judged sufficient in the interim. Whether/when to add a first-login hook remains an open, deliberately-deferred decision.

Product Catalog Product-matching is scoped to Category, unlike the real ERP's own duplicate check (which is effectively global) — see Product Catalog Items and Units, a documented, intentional deviation, not a bug.

Phase 5F — what was verified live

The Tenant Starter Kit's own live E2E pass ran a real TenantStarterKitService backed by a real SQL Server TenantDbContext against a designated, safe E2E test tenant (a dedicated, non-shared, explicitly labeled test database, active subscription, confirmed Features.AccountManagement/CostCenterSettings entitlement, known BusinessActivityCode = RestaurantCafe, needsCostCenters = Mandatory, zero pre-existing apply-log rows). Only the four per-step ITenant*ApplyService interfaces and the two entitlement services were mocked. Preview correctly resolved every default template (RestaurantCafe_Saudi_USStyle_COA_v1, its linked inventory-category template, and RestaurantCafe_Default_CostCenters_v1) and never wrote the apply log; Apply (with the bridge itself still mocked) wrote exactly one log row, self-cleaned afterward.

This pass also found the internal apply-bridge configuration surface was entirely missing from both Shumoul.Framework.MultiTenancy.Host's appsettings.json and Shumoul.Api's appsettings.Development.json — affecting all four accounting apply flows at once, since they share one bridge/key. Documented (but disabled, placeholder-valued) configuration sections were added as a fix.

Phase 5G — the corrected finding

Phase 5F had separately concluded that no host could ever produce a genuinely-authorized call to any SaaS admin controller. Phase 5G found this specific claim incorrect by direct code inspection — see SaaS Admin Authorization for the full correction. Phase 5F's document was updated with a corrective pointer note rather than rewritten, preserving the original as historical record.

Phase list

Phase	Focus
3	SubscriptionFeature → SettingsGroups entitlement link
3.2	Settings-group ownership gap closed (ProjectSettings/SalesmanSettings/MarketerSettings)
4	Saas.BusinessActivities master data
5A / 5A.1	Accounting chart template catalog + JSON/Excel import
5B.1 / 5B.1.1	Apply chart accounts to tenant; real Features.AccountManagement
5B.2	Chart-template mapping resolution into InventoryAccountCategory
5B.3	Inventory account category templates + safe apply
5C	Cost center templates + safe apply
5D	Activity-specific Saudi/US-style default chart templates
Schema Convention Cleanup	Name/FName rename correction
5E	Tenant Starter Kit orchestration (accounting chain)
5F	Live E2E verification + configuration hardening
5G	SaaS admin authorization hardening (TenantAccessGuardBehavior, Swagger grouping)
6	Product Catalog Templates (categories only)
6A.1	Product Catalog Prerequisites (BusinessType/ProductDepartment/UnitOfMeasure)
6B	Product Catalog Items and Units
6C	Product Catalog composed into Tenant Starter Kit

This phase history runs in parallel with, and is entirely separate from, the Business Onboarding & Smart Configuration chapter's own phase history (Phase 1.1 through Phase 8, plus its own entitlement-adjacent work referenced above) — the two phase numbering schemes are unrelated to each other; "Phase 4" here has no relationship to "Phase 4" in any other chapter of this Developer Portal.