Cookbook — how do I…

…add a new service (request type)?

Not in code. Log in as an admin → دليل الخدمات → خدمة جديدة → fields, the route (each step with its holder, conditions and deadline) → نشر. To ship one as a seed, add it to modules/requests/Data/ServiceCatalog.*.cs using the FieldBuilders / ConditionBuilders helpers; the seed publishes it once on first start and never overwrites later edits.

…write a rule that is not in the builder's rows?

In the field or step dialog press «تعديلها كصيغة» and type a formula, such as days(go_date, back_date) > 3 and requester.branch = 4. See Rules and formulas. If a rule needs something no formula can say, add a function to Formula, never a new member on FormField or StepDef.

…let a rule read something about a chosen value?

Give its list a detail column in the list window (ColumnsJson, say «عدد المقاعد»), fill it per value, and read it in a rule as car.seats (RuleContext).

…make a list hold stock, and move it from a service?

In «القوائم المشتركة» open the list's window, tick «قيمها أصناف مخزون» and add its unit and minimum columns. In the service, add a table with a list column on that list and a number column, then a task's «حركة مخزون» on that table. See Lists and inventory.

…add a page to the Requests module?

Create modules/requests/Components/Pages/<Name>.razor with @page "/my-page" and [Authorize] (or [Authorize(Policy = "perm:X")]). Wrap the load in using var _ = Loading.Begin();. Add a NavItem in RequestsModule.Nav if it needs a menu link. Add a test.

…add a service class?

Put it in modules/requests/Services/, register it in RequestsModule.ConfigureServices, take IDbContextFactory<AppDbContext> in the constructor, and add a test in tests/ that mentions it (ArchitectureTests.EveryServiceIsMentionedByAtLeastOneTest refuses untested services).

…add a column or a grouping to a report?

Add the value to ReportValues (a card value under u: or a form value under f:): it becomes a column, a filter and a grouping at once, read in SQL. See Reports.

…add a permission?

Add a value to Permission in src/ErpDarAlBer.Core/Domain/Permission.cs, a name in Permissions.NameAr, and (optionally) a default grant in Permissions.Defaults. Check it with Me.CanAsync(Permission.X) or [Authorize(Policy = "perm:X")]. Never check a role name.

…add an approver position?

Not in code: المناصب → new position → assign it to employees → use it in a chain. Only the three relations (line manager, branch officer, and the requester on a task) are code, in src/ErpDarAlBer.Core/Domain/Relations.cs.

…add a whole new feature (module)?

Copy modules/_template → see Modules.

…show something on the home page or in the top bar?

Return a component type from IModule.HomeWidget / IModule.AppBarItem.

…add a UI component everyone can use?

src/ErpDarAlBer.Core/Components/Shared/. Use MudBlazor components; no global element CSS in app.css. Add a bUnit test in ComponentTests.

…change the database?

Change the entity, then dotnet ef migrations add <Name> -p src/ErpDarAlBer.Web -s src/ErpDarAlBer.Web -o Data/Migrations. verify.sh fails if the model and the last migration disagree.

…see why a request was routed somewhere?

The request page → سجل الطلب and the approval trail; the form values the chain was judged on are stored with the request, feature-computed ones (the room's type) included.

…run the checks?

./verify.sh — build with warnings as errors, all tests with a coverage threshold, catalog integrity, migration drift, and this documentation site. Run it before claiming anything works.