======================== MODULE CONFIG (CHANGE THIS EACH TIME) ======================== DomainName: {DOMAIN_NAME} (e.g., Followers, Settlements) FeatureSlug: {FEATURE_SLUG} (snake_case, e.g., followers, auth_otp) FeatureFolder: {FEATURE_FOLDER} (e.g., 01_register, 02_login) AdminDirectoryName: {ADMIN_DIRECTORY} (e.g., followers, settlements) ModelClass: {MODEL_FQCN} (e.g., App\Models\Follower) ServiceClass: {SERVICE_FQCN} (e.g., App\Services\Followers\FollowerService) RepositoryContract: {REPO_CONTRACT_FQCN} (e.g., App\Repositories\Followers\Contracts\FollowerRepositoryInterface) RepositoryEloquent: {REPO_ELOQUENT_FQCN} (e.g., App\Repositories\Followers\Eloquent\FollowerRepository) Policy/Permissions: MANUAL (DO NOT CHANGE) Routes: AdminSidebarParentUri: {PARENT_URI} (e.g., 'followers-management') AdminIndexUri: {INDEX_URI} (e.g., 'followers') ApiPrefix: {API_PREFIX} (usually 'api') Locales: SupportedLocales: {LOCALES} (e.g., ['ar','en'] or ['ar']) Documentation Outputs (MANDATORY — ALL FOUR MUST BE PRODUCED): docs/features/{FEATURE_FOLDER}/README.md ← per-feature docs/features/{FEATURE_FOLDER}/openapi.json ← per-feature docs/README.md ← project-level (UPDATE, do not replace) docs/openapi.json ← project-level (UPDATE, do not replace) ======================== REQUIREMENTS (CHANGE THIS EACH TIME) ======================== Feature Name: {FEATURE_NAME} Actors: - {ACTOR_1} - {ACTOR_2} Business Order: {BUSINESS_ORDER} Business Phase: {BUSINESS_PHASE} Depends On: - {DEPENDENCY_1} - {DEPENDENCY_2} ======================== SOURCES (MANDATORY) ======================== SOURCE PRIORITY (NON-NEGOTIABLE): 1. Business rules & constraints → analysis_fragment.md 2. UI fields & screen flows → figma_fragment.json 3. On conflict: business rules override UI 4. Every field/rule MUST carry a SourceTag: BUSINESS_RULE | UI_FIELD | UI_ONLY | SPEC_ONLY --- ## UI SOURCE (FIGMA) figma_fragment_file: docs/features/{FEATURE_FOLDER}/figma_fragment.json frames_used_for_this_feature: - {FRAME_NAME_1} - {FRAME_NAME_2} Agent instructions for FIGMA parsing: - Extract: form inputs, required/optional hints, field labels, placeholders, buttons/actions, table columns, filters, statuses, expected response attributes. - If Figma does NOT provide types → infer from label + typical patterns + analysis. - If UI shows a field not in this file → include it tagged as UI_ONLY, note in NOTES section. - UI-derived response attributes MUST appear in API Resources and OpenAPI examples. - GEOGRAPHIC RULE: "موقع جغرافي" or "العنوان" → map to map_desc (string), lat (decimal), lng (decimal). Do NOT use city_id or country_id. --- ## BUSINESS SOURCE (ANALYSIS) analysis_fragment_file: docs/features/{FEATURE_FOLDER}/analysis_fragment.md analysis_scope_for_this_feature: - {SECTION_OR_HEADING} (pages: {FROM}–{TO}) Agent instructions for ANALYSIS parsing: - Extract: business rules, statuses, transitions, constraints, edge cases, permissions notes (do NOT implement permissions), calculations/formulas. - Convert narrative into implementable rules & validations. - GEOGRAPHIC RULE: same as above — map_desc, lat, lng. ======================== GEOGRAPHIC LOCATION RULE (MANDATORY) ======================== "موقع جغرافي" or "العنوان" → use exactly: map_desc string — text description lat decimal — latitude lng decimal — longitude Do NOT use city_id, country_id, or address_id. Apply in: migrations, DTOs, requests, resources, OpenAPI. ======================== FEATURE IDENTIFICATION ======================== This feature must be definable by: - a distinct UI flow/frame group from FIGMA - AND a distinct business workflow/ruleset from ANALYSIS If this feature overlaps with another: - Define clear in/out-of-scope boundaries - List dependencies & referenced endpoints ======================== ARCHITECTURE & RULES REFERENCE ======================== → ALL architecture, DTO, FormRequest, Repository, Response, OpenAPI, Admin, Factory, Seeder, and Quality Gate rules are defined in: docs/agent/laravel_constitution.md ← READ THIS BEFORE WRITING ANY CODE ======================== BUSINESS FLOW (FROM FIGMA + ANALYSIS) ======================== Describe the flow steps: 1. ... 2. ... 3. ... Include: entry points, exit states (success/failure), calculations. ======================== ENTITIES / TABLES ======================== - Table: {TABLE_NAME} Purpose: Columns: - {column}: {type} | required/optional | {SourceTag} Indexes/Unique: - ... Relationships: - ... Notes: - UI-only field → tag UI_ONLY - Analysis-only field → tag SPEC_ONLY ======================== ENUMS (IF ANY) ======================== - EnumClass: {ENUM_CLASSNAME} Cases: {CASE1, CASE2, ...} Enum i18n: lang/{locale}/enums.php → '{EnumClassKey}' => ['{CASE}' => 'Label'] ======================== API ENDPOINTS ======================== For each endpoint: [METHOD] {/path} Auth: yes / no Purpose: ... Request: - {field}: {type} | required/optional | {validation} | {SourceTag} Response: - MUST use Resource + ResponseTrait::jsonResponse() - Response attributes must cover all UI needs from Figma - Top-level shape MUST match ResponseTrait contract Message Keys (apis.php): - apis.{domain}.created - apis.{domain}.updated - apis.{domain}.deleted Notes: - Response fields required by UI MUST appear in Resource output - Relations used in Resource MUST be eager loaded in Repository ======================== ADMIN SCREENS (DERIVED FROM ENTITIES + BUSINESS NEEDS) ======================== Admin UI design is NOT provided. Derive screens from entities and business rules. Index (AJAX): Columns: - ... Filters: - ... Actions: - view / create / edit / delete / multi-delete / approve / reject (as needed) Message Keys (admin.php): - admin.{domain}.created - admin.{domain}.updated - admin.{domain}.deleted - admin.{domain}.bulk_deleted Create / Edit / Show: Fields/Sections: - ... ======================== VALIDATION RULES ======================== List validation rules per request field. Validation Attributes (validation.php → attributes): field_name: "Human readable label" Each rule must come from: - UI hints (required/format) - ANALYSIS constraints (ranges, requiredness, business rules) ======================== BUSINESS RULES ======================== (All rules MUST come from analysis_fragment.md — do NOT invent rules) - ... Include: calculations, status transitions, points/rewards, non-functional constraints. ======================== EDGE CASES ======================== - ... ======================== FACTORY & SEEDER NEEDS ======================== - Factory for: ... - Seeder for: ... ======================== FEATURE TESTS (MINIMUM MATRIX) ======================== API tests: - index: success + pagination - store: success + validation failure (422) + unauthorized (401) if applicable - update: success + validation failure + unauthorized if applicable - delete: success + unauthorized if applicable - forbidden (403) when applicable Admin tests: - index AJAX table: success - store: success - update: success - delete: success - multi-delete: success ======================== NOTES (MISMATCHES / QUESTIONS) ======================== - List mismatches between UI and ANALYSIS with SourceTags - Ask for confirmation ONLY when mismatch blocks implementation - Unknown values → mark as TODO, never invent