From 0e38d7cdedb0ae965844cc670efa77f2b2809981 Mon Sep 17 00:00:00 2001 From: Ahmad Besher Dabbagh <109789519+Ahmad7757@users.noreply.github.com> Date: Fri, 12 Jun 2026 16:26:51 +0300 Subject: [PATCH] Delete Trust & Verification - Ahmad.txt --- Trust & Verification - Ahmad.txt | 276 ------------------------------ 1 file changed, 276 deletions(-) delete mode 100644 Trust & Verification - Ahmad.txt diff --git a/Trust & Verification - Ahmad.txt b/Trust & Verification - Ahmad.txt deleted file mode 100644 index d945573..0000000 --- a/Trust & Verification - Ahmad.txt +++ /dev/null @@ -1,276 +0,0 @@ -PART 1: TRUSTMETRIC & AGENTBADGE (USER STORIES) -──────────────────────────────────────────────────────────── - -US-01 — View Trust Score Details ------------------------------------------- -As a: Admin -I want: To view the trust score details for any agent -So that: I can make an informed decision about granting or revoking the badge - -Acceptance Criteria: -• The admin can view the total trust_score for any agent -• The admin can view each criterion score separately -• The date of the last calculation (calculated_at) is displayed - -Edge Cases: -‣ Record exists but is partially complete -> missing fields are displayed as 0 instead of null -‣ Outdated data (last calculation is very old) -> the system may indicate that the data is not up-to-date while still displaying it - -US-02 — Grant Professional Agent Badge ------------------------------------------- -As a: Admin -I want: To grant the "Professional Agent" badge to a specific agent -So that: Users can recognize trusted agents on the platform - -Acceptance Criteria: -• The admin can only grant the badge to users with role = agent -• trust_score must be >= 80 at the time of granting -• The agent’s profile photo must be verified and approved by the admin (has_photo_verified_by_admin = true) -• granted_by, granted_at, and granted_at_score are recorded -• The badge status is set to active immediately upon granting - -Edge Cases: -‣ The agent temporarily meets the criteria due to a sudden score spike -> an optional waiting period can be applied before granting - -US-03 — Revoke Professional Agent Badge ------------------------------------------- -As a: Admin -I want: To revoke the "Professional Agent" badge from a specific agent -So that: The badge remains credible and reflects current actual performance - -Acceptance Criteria: -• The badge is automatically revoked when trust_score drops to <= 70 -• revoked_by, revoked_at, and revoked_at_score are recorded -• The badge status changes from active to revoked -• The badge is immediately hidden from the agent’s profile - - -US-04 — Display Professional Agent Badge ------------------------------------------- -As a: Regular User -I want: To see the "Professional Agent" badge on the agent’s profile -So that: I can trust the agent I interact with - -Acceptance Criteria: -• The badge is displayed only when status = active -• No badge is displayed if the agent never received it or if it has been revoked - - -VERIFICATION REQUEST (USER STORIES) -──────────────────────────────────────────────────────────── - -US-01 — Submit Property Listing for Review ------------------------------------------- -As a: Regular User or Agent -I want: To publish a property listing -So that: It becomes visible to the public - -Acceptance Criteria: -• Any user with role = regular, agent can submit a property listing -• A VerificationRequest record is automatically created upon submission -• VerificationRequest.status defaults to pending -• Property.status defaults to pending -• The listing is not visible to other users until status = active -• A clear and deterministic state mapping between VerificationRequest.status and Property.status must be defined and enforced as follows: - – pending ⟶ Property.status = pending - – approved ⟶ Property.status = active - – rejected ⟶ Property.status = rejected - – needs_edit ⟶ Property.status = pending -• State transitions must be deterministic with no undefined or implicit behaviors -• Property.status can only become active through an approved VerificationRequest transition - -Edge Cases: -‣ If a listing is submitted without required fields → the operation is rejected before creating Property or VerificationRequest -‣ If edits are requested and the user does not respond within one week → VerificationRequest.status is set to rejected and Property.status = rejected -‣ A property cannot become visible (active) except through an explicit approved transition - - -US-02 — Upload Supporting Documents ------------------------------------------- -As a: User -I want: To upload supporting documents with my property listing -So that: The admin can verify the property and grant a trust mark - -Acceptance Criteria: -• The user can upload one or more documents to VerificationRequest -• Documents are stored in the documents_url field -• Uploading documents does not automatically change the status ← admin reviews manually - -Edge Cases: -‣ User uploads an unsupported file format -> rejected with a clear error message -‣ User uploads a file exceeding the allowed size -> rejected with a clear error message - -US-03 — Admin Review of Property Listing ------------------------------------------- -As a: Admin -I want: To review the submitted property listing -So that: I can approve it, request edits, or reject it - -Acceptance Criteria: -• The admin can view all VerificationRequest records with status = pending -• The admin can change the status to: approved, needs_edit, or rejected -• reviewed_by is set to the admin’s User.id upon any action -• reviewed_at is recorded at the time of action -• The admin can add an admin_note to explain the decision - -Edge Cases: -‣ Two admins open the same request simultaneously -> the first action is applied, the second admin sees the updated status -‣ Admin rejects without admin_note -> the system requires a note for rejected and needs_edit - -US-04 — Request Edits on Property Listing ------------------------------------------- -As a: Admin -I want: To request edits on the property listing -So that: The user can correct it before publishing - -Acceptance Criteria: -• Admin sets status = needs_edit with mandatory admin_note -• The user is notified of required changes -• The user can edit and resubmit the listing -• Upon resubmission, status returns to pending and a new review cycle begins -• reviewed_by and reviewed_at are updated with each admin action - -Edge Cases: -‣ User ignores needs_edit for a long period -> the listing is automatically deleted - -US-05 — Reject Property Listing ------------------------------------------- -As a: Admin -I want: To reject a property listing that does not meet platform standards -So that: Low-quality or fake listings are removed - -Acceptance Criteria: -• Admin sets status = rejected with mandatory admin_note -• Property.status is set to rejected -• The listing is not visible to other users -• The user is notified of the rejection and its reason - -Edge Cases: -‣ Admin rejects without admin_note -> the system requires adding a note before confirming rejection - -US-06 — Grant Property Verification Mark ------------------------------------------- -As a: Admin -I want: To grant a verification mark to a property listing when supporting documents are available -So that: Users trust the authenticity of the listed property - -Acceptance Criteria: -• Admin sets status = approved and Property.is_verified = true only when documents are uploaded -• If no documents exist, the admin may approve but is_verified remains false -• verified_by is set to the admin’s User.id -• verified_at is recorded at the time of verification - -Edge Cases: -‣ Admin attempts to set is_verified = true without uploaded documents -> the system prevents the action or displays a confirmation warning - - -PART 2: DATABASE SCHEMA -──────────────────────────────────────────────────────────── - -RealEstateCompany: -- id: (PK) -- name: VARCHAR -- license_number: VARCHAR (UNIQUE) -- logo_url: VARCHAR -- verified: BOOLEAN -- created_at: TIMESTAMP - -User: -- id: (PK) -- name: VARCHAR -- email: VARCHAR (UNIQUE) -- phone: VARCHAR -- password_hash: VARCHAR -- role: ENUM (regular, agent, company_admin, admin) -- company_id: (FK → RealEstateCompany.id, nullable) -- created_at: TIMESTAMP - -VerificationRequest: -- id: (PK) -- property_id: (FK → Property.id) -- reviewed_by: (FK → User.id, nullable) -- status: ENUM (pending, approved, needs_edit, rejected) -- documents_url: TEXT[] -- admin_note: TEXT (nullable) -- created_at: TIMESTAMP -- reviewed_at: TIMESTAMP - -TrustMetric: -- id: (PK) -- agent_id: (FK → User.id) -- has_photo_verified_by_admin: BOOLEAN -- professional_posts_ratio: DECIMAL(3,2) -- posts_this_month: INT -- active_days_last_30: INT -- posts_prof_score: DECIMAL(5,2) -- monthly_posts_score: DECIMAL(5,2) -- activity_score: DECIMAL(5,2) -- trust_score: DECIMAL(5,2) -- calculated_at: TIMESTAMP - -AgentBadge: -- id: (PK) -- agent_id: (FK → User.id) -- granted_by: (FK → User.id) -- revoked_by: (FK → User.id, nullable) -- badge_name: VARCHAR (DEFAULT 'Professional Agent') -- status: ENUM (active, revoked) -- granted_at: TIMESTAMP -- revoked_at: TIMESTAMP (nullable) -- granted_at_score: DECIMAL(5,2) -- revoked_at_score: DECIMAL(5,2) - - -PART 3: API ENDPOINTS -──────────────────────────────────────────────────────────── - -POST — Create Agent Badge --------------------------- -POST /agent-badges -Host: Shaqqa.com -Accept: application/json - -Request: -{ - "agent_id": "12", - "badge_name": "Professional Agent", - "granted_at_score": 82.5 -} - -Response: -HTTP/1.1 201 Created -{ - "id": "1", - "agent_id": "12", - "granted_by": "845", - "badge_name": "Professional Agent", - "status": "active", - "granted_at": "2026-04-29T10:00:00Z", - "granted_at_score": 82.5 -} - -PUT — Revoke Agent Badge --------------------------- -PUT /agent-badges/{id} -Host: Shaqqa.com -Accept: application/json - -Request: -{ - "status": "revoked", - "revoked_at_score": 58.0 -} - -Response: -{ - "id": "1", - "agent_id": "12", - "granted_by": "845", - "revoked_by": "154", - "badge_name": "Professional Agent", - "status": "revoked", - "granted_at": "2026-04-20T09:00:00Z", - "revoked_at": "2026-04-29T12:00:00Z", - "granted_at_score": 82.5, - "revoked_at_score": 58.0 - }