# Counselor forms / نماذج المرشد التربوي

## Purpose and status

Planning inventory extracted on 2026-10-24 from the [original HTML prototype](<../%D9%85%D8%B3%D8%A7%D8%B1%20_%20%D9%85%D9%86%D8%B5%D8%A9%20%D8%A7%D9%84%D8%A7%D9%95%D8%B1%D8%B4%D8%A7%D8%AF%20%D8%A7%D9%84%D8%AA%D8%B1%D8%A8%D9%88%D9%8A%20(%D9%86%D8%B3%D8%AE%D8%A9%20%D8%AA%D8%AC%D8%B1%D9%8A%D8%A8%D9%8A%D8%A9).html>). This document lists the forms that the school counselor (المرشد التربوي) can fill in, so we can implement them in stages. The field inventory describes the prototype; the implementation status is recorded separately below.

The prototype contains **seven ordinary registers plus one case-study form**. All eight forms are implemented with supervisor review: student interviews, parent meetings, vocational guidance, bulletins, studies, counseling committee activities, home visits and the 12-section case study. Existing student management is a separate feature. Attachments are now supported for the four school-level forms described below. Printing, notifications and production/visual acceptance remain separate work; implementation does not establish production readiness.

The HTML stores demonstration data in browser local storage. Its role switch, saves, review actions, and statistics are reference behavior, not production API or authorization guarantees. Field keys below are prototype keys, not an approved database schema.

## First implemented form — 2026-10-24

**سجل المقابلات والاستشارات الطلابية** is available at `/portal/counselor/interviews`.

- Choose a currently assigned, active school, then an existing student from that school. Student search is paginated, and grade/section are displayed from the student record. As in the HTML, one record links to one student even when its type is Group; a group-participant model is not implemented.
- Student and date are required. Type defaults to Individual, referral source to Self, and follow-up to No follow-up needed. These selects always submit a valid canonical value. Empty dates are rejected rather than silently replaced. Supported dates stay within the MySQL DATE range (1000-01-01 through 9999-12-31).
- Problem summary, impact, student understanding, and counseling action are optional, each limited to 5,000 characters. Student/class data comes from the current student record; no separate historical student snapshot is stored.
- List/search by student name or number, filter by month/type/follow-up, and paginate 25 records at a time. Create/Edit open shared dialogs with fixed actions, scrolling, unsaved-change protection, and Arabic/English support. Student names link to student details; dates and View link to the interview details.
- Only the creating counselor can change interview answers, and only while they retain access to the school. Their currently assigned supervisor can view/review it under the scope below. Sharing a school alone does not expose another counselor's counseling notes. The server rechecks active role, directorate, school and current assignment under transaction locks.
- Saving persists directly to MySQL. There is **no separate Submit action**: new records enter Pending review immediately. Supervisors can mark them Reviewed or Approved and add a note, as described below. The prototype return-with-note action remains reference material and is not a separate status in this implementation.
- Creation uses a stable per-dialog UUID to prevent duplicate records on retry. Reusing the same key with changed content returns 409. Edits and deletion require the version opened by the editor; stale changes return 409 and keep the draft visible.
- Delete requires an explicit confirmation, soft-deletes the interview, and keeps the student. Audits store action/field names only, without counseling-note values. There is no user-facing restore UI in this increment.
- API: session/CSRF-protected counselor GET/POST `/api/v1/counselor/schools/{school}/interviews`; GET/PUT/DELETE `/api/v1/counselor/interviews/{interview}`. Supervisors have the separate, limited review API below; heads receive no interview access.

Apply the additive migration from `backend/` after checking/backing up the target database:

```powershell
& C:/laragon/bin/php/php8.3/php.exe artisan migrate --no-interaction
```

## Supervisor review — 2026-10-24

- Open **Counselor forms / نماذج المرشدين** at `/portal/supervisor/interviews`. The first available type is student interviews and consultations. Parent meetings have a separate tab and the same review rules. Other form types will be added when implemented.
- The supervisor sees a paginated table with counselor/school links, student name, date, status, and a View/Review action. Search by student name/number and filter by month or review status. School/counselor IDs can narrow the already authorized query; they never grant access.
- Records must belong to an active counselor currently supervised by this supervisor, with a current assignment to the record's active school in the same directorate. Soft-deleted records, inactive schools/counselors, ended assignments, cross-directorate records, and unrelated counselors in a shared school are excluded from lists, details and review writes.
- Read answers on the detail page, then open the review dialog. Choose **Reviewed / تم الاطلاع** or **Approved / معتمد**. An optional supervisor note is limited to 5,000 characters. Viewing a page alone never changes status.
- Supervisors can update their review decision/note, but cannot edit answers, change students, delete interviews, or manage school/student/counselor data. Student names on supervisor form details are plain text; no new student-detail API is exposed.
- Counselors see the effective status in their records table and the latest supervisor note/name/date on details and Edit. New/unreviewed records use **Pending review / بانتظار المراجعة**. This increment adds no separate returned/rejected state, notification, or inbox.
- An actual change to any counselor answer increments `content_version` and resets status to Pending review. A save without answer changes preserves the status. Previous notes are retained and clearly marked as belonging to an earlier version. Each successful supervisor decision appends a review-history row; the UI currently displays the latest review only.
- Review saves use the version opened by the dialog. If a counselor or another reviewer saves first, return 409, keep the unsaved supervisor note/status, and offer the latest record in a new tab. Both content and review writes advance the shared `lock_version`, preventing silent overwrites.
- API: supervisor GET `/api/v1/supervisor/interviews`, GET `/api/v1/supervisor/interviews/{interview}`, POST `/api/v1/supervisor/interviews/{interview}/review`. Staff sessions, supervisor middleware, CSRF, throttling and no-store responses remain required. Audit logs contain action/field names, not note contents; review text is stored in the dedicated review history.

## Demo data for the first form

The opt-in `DemoInterviewSeeder` adds six fictional interviews per eligible demo school/counselor pair using existing seeded students. Each pair gets two Pending, two Reviewed and two Approved examples, with labeled narratives and sample supervisor notes. Current assignments and active accounts/schools are required. Missing students or a missing valid demo supervisor cause affected slots to be skipped. Stable request UUIDs preserve manual edits, review decisions and soft deletions on reruns; no accounts or student records are changed.

From `backend/`, run `php artisan masar:seed-demo-interviews` to preview, then add `--apply` to write. See [the demo commands and prerequisites](../README.md#demo-interview-data). Locally seeded and verified on 2026-10-24: **66 interviews / 11 schools**, **22 in each review status**, and **44 sample reviews**. The sample counselor sees six; the sample supervisor sees 66.

## Parent meetings — 2026-10-24

**سجل مقابلات أولياء الأمور** is now available at `/portal/counselor/parent-meetings` and `/portal/supervisor/parent-meetings`.

- Select a currently assigned active school and an existing student from that school. Student and date are required; grade/section display automatically from the current student record.
- Meeting type: **In person / حضور شخصي**, **Phone call / اتصال هاتفي**, or **School invitation / استدعاء من المدرسة**. Default: In person. Follow-up uses the existing None/Ongoing/Completed options, defaulting to None.
- Optional reason for the meeting and counseling action, each limited to 5,000 characters. The form follows the prototype: it does not create a guardian account or add separate guardian identity/contact fields. No referral source, student-problem impact or student-understanding fields belong to this register.
- Paginated records table with student prefix search and month/type/follow-up/review-status filters. Create/Edit dialogs retain drafts across language switches and failed saves. Real links open student and meeting details. Confirmed deletion soft-deletes only the meeting.
- Supervisors view authorized forms and save an optional note with Reviewed/Approved. Counselors see the latest review. Actual answer edits reset status to Pending; no-op saves preserve it. Previous reviews remain tied to their content version. Stale edits/reviews/deletes return 409 without overwriting newer changes.
- Uses separate typed `parent_meetings` and `parent_meeting_reviews` tables, scoped transactional saves/reviews, stable create-request UUIDs, and privacy-preserving audits. Does not change student-interview records, reviews, or demo seeders.
- API: counselor GET/POST `/api/v1/counselor/schools/{school}/parent-meetings` and GET/PUT/DELETE `/api/v1/counselor/parent-meetings/{meeting}`. Supervisor GET `/api/v1/supervisor/parent-meetings`, GET `/api/v1/supervisor/parent-meetings/{meeting}`, POST `/api/v1/supervisor/parent-meetings/{meeting}/review`.
- Apply the normal additive migration before using this form. Parent-meeting examples are now available through `masar:seed-demo-forms`; existing interview seeding stays unchanged.

## Available forms

| # | Form in the prototype | Purpose |
| --- | --- | --- |
| 1 | سجل المقابلات والاستشارات الطلابية | توثيق المقابلات الفردية والجماعية والاستشارات مع الطلبة، مع الإجراء الإرشادي والمتابعة. |
| 2 | سجل مقابلات أولياء الأمور | توثيق لقاءات أولياء الأمور وأسباب الزيارة والإجراء الإرشادي المتخذ. |
| 3 | سجل التوجيه المهني | حصص التوجيه المهني: الموضوع وسير الحصة وعدد الطلبة المستفيدين والتقييم. |
| 4 | سجل النشرات | النشرات الإرشادية الصادرة: الاسم والفئة المستهدفة والأهداف وعدد النسخ. |
| 5 | سجل الدراسات | الدراسات التي أجراها المرشد: العنوان والعينة والهدف والنتائج. |
| 6 | ملف اللجنة الإرشادية | أنشطة اللجنة الإرشادية وعدد المشاركين من داخلها وخارجها وتقييم النشاط. |
| 7 | ملف الزيارات المنزلية | الزيارات المنزلية للطلبة: نوع الزيارة وسير المقابلة والإجراء الإرشادي والمتابعة. |
| 8 | دراسة الحالة | A student case study, proposed treatment plan, counseling sessions, and closing evaluation. |

## Vocational guidance — 2026-10-25

**سجل التوجيه المهني** is available at `/portal/counselor/vocational-guidance` and `/portal/supervisor/vocational-guidance`.

- A record describes a class activity in an assigned active school, not an individual student's counseling session. No student selection, student account, referral source, meeting type or follow-up field is required.
- Required: topic (up to 255 characters) and date (MySQL DATE range: 1000-01-01 through 9999-12-31). Optional grade and section are separate text fields, each up to 50 characters, using the school's actual class names rather than the prototype's fixed sample list. No new class-management module is introduced.
- Session count is optional, whole numbers 1–10,000. Beneficiary count is optional, whole numbers 0–100,000. Leaving a count empty stores null; an explicit zero beneficiaries remains zero. These are bounded input limits, not verified school capacity. Activity description (`course`) and observations/evaluation (`evaluation`) are optional, each up to 5,000 characters.
- Counselor tables support topic-prefix search, month/review-status filtering and pagination. Create/Edit/confirmed soft-delete use the shared dialogs, retained drafts, Arabic/English, RTL/LTR and current themes. Topic/date link to details; related school/counselor links keep their authorized destinations.
- Records remain private to their creating counselor and authorized current supervisor. Current active school/directorate/counselor and exact school/supervision assignments are rechecked in SQL and under write locks. Sharing a school does not expose another counselor's activity records.
- Review status starts Pending. Supervisors may add an optional note and mark Reviewed or Approved without editing answers. Actual answer changes reset review to Pending and preserve older review history; no-op saves preserve approval. Version conflicts retain the open draft, and stable create UUIDs prevent duplicate retries.
- Uses separate `vocational_guidance_records` and `vocational_guidance_reviews` tables. API: counselor GET/POST `/api/v1/counselor/schools/{school}/vocational-guidance`, GET/PUT/DELETE `/api/v1/counselor/vocational-guidance/{guidance}`; supervisor GET `/api/v1/supervisor/vocational-guidance`, GET `/{guidance}`, POST `/{guidance}/review` beneath that path. All require the existing staff session, role/scope checks and CSRF for writes.
- Apply `2026_10_25_064232_create_vocational_guidance_records_table` through normal `php artisan migrate --no-interaction` after verifying/backing up the target. No new dependency is added. Demo examples use `masar:seed-demo-forms`. Printing, bulk approval, notifications and return/reject states remain future work.

## Bulletins register — 2026-10-25

**سجل النشرات** is available at `/portal/counselor/bulletins` and `/portal/supervisor/bulletins`.

- Records describe counseling bulletins issued in an assigned active school. They are private counselor records and do not create or publish landing-page news/articles. There is no individual student link or class field.
- Required: bulletin name (up to 255 characters), date (MySQL DATE range: 1000-01-01 through 9999-12-31) and a valid target audience. The UI defaults to All students. Supported canonical audiences: `all_students`, `grade_9`, `grade_10`, `parents`, `teachers`, with complete Arabic/English labels.
- Optional copy count: whole numbers 0–100,000. Blank stores null; explicit zero remains zero. Optional objectives (`goals`): up to 5,000 characters. Bulletins now support optional private attachments as described below; printing and publishing remain future work.
- Counselors choose an assigned school, then use a paginated table with name-prefix search and month/audience/review-status filters. Create/Edit/confirmed soft-delete use the shared modal, visible actions and draft protection. Names/dates link to record details. Related school and counselor links retain their authorized destinations.
- Only the creating counselor and currently assigned authorized supervisor can access each record. Scope checks include active roles/directorate/school, exact current school and supervision assignments, and soft-deletion. Shared-school membership alone never grants another counselor's records.
- Supervisors read answers and save an optional note with Reviewed or Approved. Answer changes reset review to Pending and preserve older history; no-op saves preserve approval. Shared version checks reject stale content/review/deletion writes. Stable create UUIDs and payload checks prevent duplicate or inconsistent retries. General audits record field/action names, not objective or review text.
- Uses separate `counselor_bulletins` and `bulletin_reviews` tables. Session/CSRF-protected API: counselor GET/POST `/api/v1/counselor/schools/{school}/bulletins`, GET/PUT/DELETE `/api/v1/counselor/bulletins/{bulletin}`; supervisor GET `/api/v1/supervisor/bulletins`, GET `/{bulletin}`, POST `/{bulletin}/review` beneath that path.
- Apply `2026_10_25_065723_create_counselor_bulletins_table` through normal migrations after verifying/backing up the target. No dependency is added. Demo examples use `masar:seed-demo-forms`. Existing sample publications remain separate and unchanged.

## Studies register — 2026-10-25

**سجل الدراسات** is available at `/portal/counselor/studies` and `/portal/supervisor/studies`.

- A private school-level record follows the prototype's study title, date, sample, purpose and results. It does not require individual student selection or create public articles.
- Required: title (up to 255 characters) and study date (MySQL DATE range: 1000-01-01 through 9999-12-31). Optional sample description: up to 255 characters. Optional purpose (`goal`) and results: up to 5,000 characters each. Omitted/blank optional fields store null. No audience enum, class selector or copy/session count belongs to this register.
- Counselors select a currently assigned active school, then search titles by prefix, filter by month/review status, and paginate records. Shared Create/Edit/confirmed soft-delete dialogs retain drafts on language changes, validation failures and conflicts. Titles/dates link to details; related school/counselor links remain scoped. Both Arabic/English and the existing theme/responsive layout rules are supported.
- Records are private to their creating counselor and authorized current supervisor. SQL and transactional checks require active same-directorate users/school, the counselor's current school assignment, and the exact current supervision assignment. Sharing a school alone does not expose another counselor's studies.
- Supervisor decisions are Reviewed/Approved with an optional note, without editing answers. Answer changes reset review to Pending and retain prior-version notes/history; unchanged answers preserve approval. Shared version checks reject stale saves/reviews/deletion. Stable create UUIDs prevent duplicate retries, including replay after soft deletion. General audits contain field/action names, not study/review text.
- Separate tables: `counselor_studies` and `study_reviews`. Session/CSRF API: counselor GET/POST `/api/v1/counselor/schools/{school}/studies`, GET/PUT/DELETE `/api/v1/counselor/studies/{study}`; supervisor GET `/api/v1/supervisor/studies`, GET `/{study}`, POST `/{study}/review` beneath that path.
- Apply `2026_10_25_071703_create_counselor_studies_table` through normal migrations after verifying/backing up the target. No new dependency or export workflow is introduced. Optional private attachments are described below. Demo examples use `masar:seed-demo-forms`.

## Counseling committee register — 2026-10-25

**ملف اللجنة الإرشادية** is available at `/portal/counselor/committee-activities` and `/portal/supervisor/committee-activities`.

- Records follow the prototype's activity name/date, participants from the committee, participants outside it, participating teachers, activity evaluation and objectives. This is a private school-level activity record without individual student or teacher-account links. No committee membership-management module is introduced.
- Required: activity name (up to 255 characters), date (MySQL DATE range 1000-01-01 through 9999-12-31), and valid evaluation. Evaluation defaults to Excellent and uses `excellent`, `very_good`, `good`, `acceptable`, with Arabic/English labels. Activity evaluation is the counselor's answer, separate from the supervisor's review status.
- Three participant counts are independently optional whole numbers 0–100,000. Blank stores null; explicit zero remains zero. The prototype does not establish overlap between participant/teacher counts; no invented sum/subset constraint is imposed. Optional objectives (`goals`) are bounded to 5,000 characters.
- Counselor tables provide activity-prefix search, month/evaluation/review-status filters and pagination. Create/Edit/confirmed soft-delete use shared draft-preserving dialogs and visible actions. Activities/dates link to details; related school/counselor links remain scoped. Both languages, reading directions and existing theme/responsive rules are supported.
- Only the creator and their authorized current supervisor can access each record. Current active same-directorate school/roles and exact school/supervision assignments are enforced in SQL and transactional writes. Sharing a school alone never exposes another counselor's activities.
- Supervisor decisions are Reviewed/Approved with optional notes; answers remain read-only. Actual answer changes reset Pending, no-op saves preserve approval, and earlier reviews remain versioned. Stable create UUIDs and shared version checks prevent duplicate retries and stale edits/reviews/deletion. Audits omit narrative/note values.
- Separate tables: `committee_activities`, `committee_activity_reviews`. Session/CSRF API: counselor GET/POST `/api/v1/counselor/schools/{school}/committee-activities`, GET/PUT/DELETE `/api/v1/counselor/committee-activities/{committee_activity}`; supervisor GET `/api/v1/supervisor/committee-activities`, GET `/{committee_activity}`, POST `/{committee_activity}/review` beneath that path.
- Apply `2026_10_25_073811_create_committee_activities_table` after verifying/backing up the target. No dependency or export workflow is introduced. Optional private attachments are described below. Demo examples use `masar:seed-demo-forms`.

## Home visits register — 2026-10-25

**ملف الزيارات المنزلية** is available at `/portal/counselor/home-visits` and `/portal/supervisor/home-visits`.

- Select a currently assigned active school and an existing student from that school; student/date are required. Grade/section are displayed from the current student record, without editable duplicate class fields or a historical snapshot.
- Visit types: `preventive` (زيارة وقائية), `remedial` (زيارة علاجية), `absence_follow_up` (متابعة غياب). Default: Preventive. Follow-up uses `none`, `ongoing`, `completed`, defaulting to None. Both selects submit valid canonical values. Dates must be within MySQL's 1000-01-01 through 9999-12-31 range.
- The prototype has one combined narrative: visit/interview details and counseling action (`course`), optional up to 5,000 characters. No separate parent-meeting reason/action, address, guardian identity, attachment or location-tracking field is added. No student login is created.
- Counselor tables support student-name/number prefix search, month/type/follow-up/review-status filters and pagination. Shared create/edit/confirmed soft-delete dialogs retain drafts through language changes, validation and conflicts. Student/date/detail links use real scoped routes. Supervisors see read-only student names and gain no student-detail permission.
- Creator/current-school/exact-supervisor scope applies to all reads and transactional writes, including active same-directorate users/school and current assignments. Shared-school membership alone never exposes another counselor's notes. Stable create UUIDs prevent duplicate retries; shared versions reject stale edits/reviews/deletion, including replay after soft deletion.
- Supervisors can save optional notes with Reviewed/Approved without editing answers. Actual answer edits reset Pending, unchanged answers preserve approval, and earlier reviews stay tied to their content version. General audits omit narrative/review values.
- Separate tables: `home_visits`, `home_visit_reviews`. API: counselor GET/POST `/api/v1/counselor/schools/{school}/home-visits`, GET/PUT/DELETE `/api/v1/counselor/home-visits/{visit}`; supervisor GET `/api/v1/supervisor/home-visits`, GET `/{visit}`, POST `/{visit}/review` beneath that path. Existing staff sessions, role checks, CSRF, throttling and no-store behavior apply.
- Apply `2026_10_25_074331_create_home_visits_table` after verifying/backing up the target. No dependency is added. Demo examples use `masar:seed-demo-forms`. Printing, bulk review and notifications remain future work.

## Case-study implementation — 2026-10-25

**دراسة الحالة** is available at `/portal/counselor/case-studies` and `/portal/supervisor/case-studies`.

- The counselor selects a currently assigned active school and an existing student. Student and registration date are required; the remaining narrative sections may be filled gradually. Referral defaults to Self, case type to Behavioral and student employment to No. Case types are `behavioral`, `academic`, `psychosocial`, `family`; referral values are `self`, `teacher`, `school`, `guardian`, `peers`.
- The 12 sections follow the inventory below: general information, family circumstances, academic achievement, school adjustment, health, interests, economics, registration, problem/baseline, proposed plan, counseling sessions, closing/evaluation. Name and grade/section come from the current student record and are read-only. Student identity cannot be changed after creation. Other general/family information belongs to this case; saving does not overwrite student details. No historical student-identity snapshot is introduced.
- Optional short fields are limited to 255 characters, including address/guardian contacts/education/employment/economic summaries/allowance/signature. Narrative fields are limited to 5,000 characters each. Dates use MySQL's 1000-01-01 through 9999-12-31 range. Birth date cannot be after registration; closing/session dates cannot precede registration. A dated session cannot be after a supplied closing date.
- Family size is optional, whole numbers 1–100. Working hours are optional, numeric 0–24 with at most two decimal places. Selecting No for employment clears/disables work type/hours; the API rejects nonempty work details when employment is No. Daily allowance remains bounded text to avoid inventing a currency. Signature is plain text, not a digital signature or upload.
- Up to 50 ordered goals, each with optional goal/action narratives, and 100 ordered sessions, each with optional date/homework/notes, can be added or removed. Partial rows are allowed to support gradual drafts. Each nested narrative is limited to 5,000 characters. Rows are saved in separate typed child tables, not a universal JSON field. Unknown child keys and excessive row counts are rejected. The case and all child changes commit or roll back together.
- The sectioned modal editor has Previous/Next and a section selector, shared fixed actions/scrolling, and an informational section-completion count. Completion is not a final-submission or approval gate. Read-only details show all 12 sections and the repeatable rows. Both languages, directions and existing themes/layout rules apply.
- The first save is explicit. Reopened cases autosave after 900 ms without input and offer manual Save. Only an acknowledged response is labeled Saved. Requests are serialized and use the server's returned version; edits made during a request remain dirty and save next. Validation/network/conflict errors stop automatic retries, keep the draft open and require a deliberate retry. A lost creation response retries the original UUID and original payload before saving newer edits, preventing duplicate cases. Language switches and background refetches do not overwrite the draft. Unsaved closing/refresh is guarded. Sensitive drafts are held in memory, not browser local storage; only acknowledged saves survive closing/reloading. A failed save is not durable.
- Progress is derived separately from review: `new` when there is no session or closing date; `in_follow_up` with at least one session and no closing date; `closed` when a closing date exists. The API derives this value and rejects supplied progress. Closing/reopening is done by setting/clearing the closing date, subject to date/version checks. Review is independently Pending/Reviewed/Approved.
- Supervisors may read/review cases from their exact currently supervised active counselor, in that counselor's currently assigned active same-directorate school. They may save only decision/note/version; no editing of case answers, children or student management is granted. Actual scalar/goal/session/order changes increment content version and reset Pending; no-op saves retain approval. Prior review notes/history remain tied to their content version. Both review and content writes use the same optimistic lock to reject stale saves.
- Case lists are paginated and filter student prefix/month/case type/progress/review status. Lists fetch selected summary columns and omit health/family narratives and child collections. Full details are fetched only through authorized detail routes. Shared schools do not expose another counselor's cases. General audits contain action/field names, never case or review text.
- Delete requires confirmation and soft-deletes the case while retaining goals, sessions and review history; the student remains. There is no restore UI. No full historical answer-snapshot/audit viewer is introduced beyond the established versioned review history.
- Tables: `case_studies`, `case_study_goals`, `case_study_sessions`, `case_study_reviews`. Session/CSRF API: counselor GET/POST `/api/v1/counselor/schools/{school}/case-studies`, GET/PUT/DELETE `/api/v1/counselor/case-studies/{caseStudy}`; supervisor GET `/api/v1/supervisor/case-studies`, GET `/{caseStudy}`, POST `/{caseStudy}/review` beneath that path. PUT sends the full current draft, including goals/sessions; omitted optional sections normalize to null/empty rows rather than acting as a PATCH.
- Apply `2026_10_25_074748_create_case_studies_table` after verifying/backing up the target. No dependency is added. Demo examples use `masar:seed-demo-forms`. Keep the server request body limit large enough for bounded long case drafts (the deployment guide's 8 MB example). Printing, attachment uploads, formal submission, rejection/return inboxes and notifications remain future work.

## Shared register fields and behavior

- Required means marked with `req` in the source. Every register marks its date and its first text field as required. However, saving an empty date replaces it with today before validation; this is prototype behavior to reconsider later.
- Dates initially use today. Selects initially use their first option. Other fields initially start empty. The prototype only checks required values; numeric ranges, text lengths, and business rules still need a production specification.
- Class options below are fixed sample values, not a complete school grade/class model.
- Student names are free text in these prototype forms. They are not linked to the application student table yet.

| Shared list | Options in the HTML |
| --- | --- |
| Class/section (CLASSES) | السابع أ / السابع ب / الثامن أ / الثامن ب / التاسع أ / التاسع ب / العاشر أ / العاشر ب |
| Referral source (SRC) | ذاتي / معلم / إدارة المدرسة / ولي الأمر / زملاء |
| Follow-up (FU) | لا يحتاج متابعة / متابعة مستمرة / تمت المتابعة |

## Ordinary register field inventory

### 1. سجل المقابلات والاستشارات الطلابية

Prototype identifier: `interviews`.

| Field | Prototype key | Input | Required | Options |
| --- | --- | --- | --- | --- |
| اسم الطالب | `student` | Text | Yes | — |
| الصف والشعبة | `cls` | Select | No | السابع أ / السابع ب / الثامن أ / الثامن ب / التاسع أ / التاسع ب / العاشر أ / العاشر ب |
| التاريخ | `date` | Date | Yes | — |
| نوع المقابلة | `type` | Select | No | فردية / جماعية / استشارة |
| مصدر التحويل | `src` | Select | No | ذاتي / معلم / إدارة المدرسة / ولي الأمر / زملاء |
| المتابعة | `fu` | Select | No | لا يحتاج متابعة / متابعة مستمرة / تمت المتابعة |
| خلاصة الصعوبة (المشكلة) | `summary` | Long text | No | — |
| أثر المشكلة على المسترشد | `effect` | Long text | No | — |
| مفهوم الطالب للصعوبة | `concept` | Long text | No | — |
| الإجراء الإرشادي | `action` | Long text | No | — |

**List columns:** اسم الطالب / الصف والشعبة / التاريخ / نوع المقابلة / مصدر التحويل / الإجراء الإرشادي / المتابعة.

### 2. سجل مقابلات أولياء الأمور

Prototype identifier: `parents`.

| Field | Prototype key | Input | Required | Options |
| --- | --- | --- | --- | --- |
| اسم الطالب | `student` | Text | Yes | — |
| الصف / الشعبة | `cls` | Select | No | السابع أ / السابع ب / الثامن أ / الثامن ب / التاسع أ / التاسع ب / العاشر أ / العاشر ب |
| التاريخ | `date` | Date | Yes | — |
| نوع المقابلة | `type` | Select | No | حضور شخصي / اتصال هاتفي / استدعاء من المدرسة |
| المتابعة | `fu` | Select | No | لا يحتاج متابعة / متابعة مستمرة / تمت المتابعة |
| سبب الزيارة | `reason` | Long text | No | — |
| الإجراء الإرشادي | `action` | Long text | No | — |

**List columns:** اسم الطالب / الصف / الشعبة / التاريخ / نوع المقابلة / سبب الزيارة / المتابعة.

### 3. سجل التوجيه المهني

Prototype identifier: `vocational`.

| Field | Prototype key | Input | Required | Options |
| --- | --- | --- | --- | --- |
| موضوع الحصة | `topic` | Text | Yes | — |
| الصف / الشعبة | `cls` | Select | No | السابع أ / السابع ب / الثامن أ / الثامن ب / التاسع أ / التاسع ب / العاشر أ / العاشر ب |
| التاريخ | `date` | Date | Yes | — |
| عدد الحصص | `sessions` | Number | No | — |
| عدد الطلبة المستفيدين | `benef` | Number | No | — |
| سير الحصة | `course` | Long text | No | — |
| الملاحظة والتقييم | `eval` | Long text | No | — |

**List columns:** موضوع الحصة / الصف / الشعبة / التاريخ / عدد الحصص / عدد الطلبة المستفيدين / الملاحظة والتقييم.

### 4. سجل النشرات

Prototype identifier: `bulletins`.

| Field | Prototype key | Input | Required | Options |
| --- | --- | --- | --- | --- |
| اسم النشرة | `name` | Text | Yes | — |
| تاريخ النشرة | `date` | Date | Yes | — |
| الفئة المستهدفة | `target` | Select | No | جميع الطلبة / طلبة الصف التاسع / طلبة الصف العاشر / أولياء الأمور / المعلمون |
| عدد النسخ | `copies` | Number | No | — |
| أهداف النشرة | `goals` | Long text | No | — |

**List columns:** اسم النشرة / تاريخ النشرة / الفئة المستهدفة / أهداف النشرة / عدد النسخ.

### 5. سجل الدراسات

Prototype identifier: `studies`.

| Field | Prototype key | Input | Required | Options |
| --- | --- | --- | --- | --- |
| عنوان الدراسة | `title` | Text | Yes | — |
| تاريخ إجراء الدراسة | `date` | Date | Yes | — |
| عينة الدراسة | `sample` | Text | No | — |
| الهدف من الدراسة (الغرض) | `goal` | Long text | No | — |
| نتائج الدراسة | `results` | Long text | No | — |

**List columns:** عنوان الدراسة / تاريخ إجراء الدراسة / عينة الدراسة / الهدف من الدراسة (الغرض) / نتائج الدراسة.

### 6. ملف اللجنة الإرشادية

Prototype identifier: `committee`.

| Field | Prototype key | Input | Required | Options |
| --- | --- | --- | --- | --- |
| النشاط | `activity` | Text | Yes | — |
| التاريخ | `date` | Date | Yes | — |
| عدد المشاركين من اللجنة | `inC` | Number | No | — |
| عدد المشاركين من خارج اللجنة | `outC` | Number | No | — |
| المعلمون المشاركون | `teachers` | Number | No | — |
| التقييم | `eval` | Select | No | ممتاز / جيد جداً / جيد / مقبول |
| أهداف النشاط | `goals` | Long text | No | — |

**List columns:** النشاط / التاريخ / عدد المشاركين من اللجنة / عدد المشاركين من خارج اللجنة / المعلمون المشاركون / التقييم.

### 7. ملف الزيارات المنزلية

Prototype identifier: `home`.

| Field | Prototype key | Input | Required | Options |
| --- | --- | --- | --- | --- |
| اسم الطالب | `student` | Text | Yes | — |
| الصف / الشعبة | `cls` | Select | No | السابع أ / السابع ب / الثامن أ / الثامن ب / التاسع أ / التاسع ب / العاشر أ / العاشر ب |
| التاريخ | `date` | Date | Yes | — |
| نوع الزيارة | `type` | Select | No | زيارة وقائية / زيارة علاجية / متابعة غياب |
| المتابعة | `fu` | Select | No | لا يحتاج متابعة / متابعة مستمرة / تمت المتابعة |
| سير المقابلة والإجراء الإرشادي | `course` | Long text | No | — |

**List columns:** اسم الطالب / الصف / الشعبة / التاريخ / نوع الزيارة / سير المقابلة والإجراء الإرشادي / المتابعة.

## Prototype register save and supervisor review (reference behavior)

1. The counselor creates a record using the register page's inline form. Existing records open in an edit modal. Each register also supports search, month filtering, and printing.
2. Saving a new record sets its review status to `pending` (قيد المراجعة). There is no separate draft or Submit button in the prototype.
3. The supervisor can approve a record (`approved` / معتمد), or return it with a required written note (`returned` / أُعيد بملاحظة). Bulk approval affects pending records in the selected register.
4. Returned records appear in the counselor's supervisor-notes inbox. Editing and saving a returned record resets its review status to `pending`.
5. Editing an approved record leaves it approved in the prototype. The implemented application instead resets review after an actual answer change, as described above.
6. The counselor can delete ordinary records after confirmation. These prototype actions do not establish the future deletion or audit policy.

The supervisor-notes inbox, dashboard, statistics, search/filter controls, and printing are supporting screens/actions, not additional counselor submission forms. The return-note form belongs to the supervisor.

## 8. دراسة الحالة — Case-study form

One case study contains all 12 sections below. No case fields are marked required and no final submission validation exists in the prototype. The progress indicator measures populated fields plus whether at least one goal and one session exist; it is not an approval or completeness check.

### Case-study sections

#### 1. معلومات عامة

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| الاسم | `name` | Text | — |
| الصف | `cls` | Select | السابع أ / السابع ب / الثامن أ / الثامن ب / التاسع أ / التاسع ب / العاشر أ / العاشر ب |
| تاريخ الولادة | `dob` | Date | — |
| العنوان | `addr` | Text | — |
| اسم ولي الأمر | `guardian` | Text | — |
| صلة القرابة | `rel` | Text | — |
| المهنة | `job` | Text | — |
| الهاتف | `phone` | Text | — |
| التحصيل الأكاديمي | `acad` | Text | — |
| الوضع الصحي | `health` | Text | — |
| الوضع الاقتصادي | `econ` | Text | — |

#### 2. الوضع الأسري

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| يعيش مع | `livesWith` | Text | — |
| عدد أفراد الأسرة | `fam` | Number | — |
| مستوى تحصيل الأب | `fEdu` | Text | — |
| مهنة الأب | `fJob` | Text | — |
| مستوى تحصيل الأم | `mEdu` | Text | — |
| مهنة الأم | `mJob` | Text | — |

#### 3. التحصيل الأكاديمي

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| في المرحلة السابقة | `prev` | Long text | — |
| في المرحلة الحالية | `curr` | Long text | — |

#### 4. التكيف المدرسي

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| مع الزملاء | `peers` | Long text | — |
| مع المعلمين | `teachers` | Long text | — |
| مع النظام المدرسي | `system` | Long text | — |

#### 5. الحالة الصحية

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| الحالة الصحية | `healthDetail` | Long text | — |

#### 6. الاهتمامات والنشاطات

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| اهتمامات الطالب ونشاطاته في المدرسة وخارجها | `interests` | Long text | — |

#### 7. الحالة الاقتصادية

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| معدل المصروف اليومي للطالب | `allowance` | Text | — |
| هل يعمل الطالب بعد الدوام | `works` | Select | لا / نعم |
| نوع العمل | `workType` | Text | — |
| عدد الساعات التي يقضيها في العمل | `workHours` | Number | — |

#### 8. تسجيل الحالة

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| تاريخ تسجيل الحالة | `regDate` | Date | — |
| مصدر الإحالة | `src` | Select | ذاتي / معلم / إدارة المدرسة / ولي الأمر / زملاء |
| نوع الحالة | `ctype` | Select | سلوكية / أكاديمية / نفسية واجتماعية / أسرية |

#### 9. وصف المشكلة

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| تحديد المشكلة (التي سيبدأ العمل بها) | `problem` | Long text | — |
| الخط القاعدي للمشكلة (تكرار أو شدة السلوك) | `baseline` | Long text | — |

#### 10. البرنامج العلاجي المقترح

Repeatable goals table (`goals`):

| Field | Prototype key | Input |
| --- | --- | --- |
| الأهداف | `g` | Long text |
| الإجراءات الإرشادية | `a` | Long text |

Actions: add a goal row or delete a goal row.

#### 11. الجلسات الإرشادية

Repeatable counseling-sessions table (`sessions`):

| Field | Prototype key | Input |
| --- | --- | --- |
| الرقم | Derived row number | Display only |
| التاريخ | `date` | Date; initially today |
| الواجب البيتي | `hw` | Long text |
| ملاحظات المرشد | `notes` | Long text |

Actions: add a session or delete a session.

#### 12. الختام والتقييم

| Field | Prototype key | Input | Options |
| --- | --- | --- | --- |
| تاريخ الانتهاء من دراسة الحالة | `endDate` | Date | — |
| التقييم | `eval` | Long text | — |
| ملاحظات المرشد حول الحالة | `notes` | Long text | — |
| توقيع المرشد | `sign` | Text | — |

### Case-study actions and status

- Create a case, open it from the case list, move between sections using the section menu or Previous/Next, and return to all cases.
- Changes save automatically on input/change in browser storage. Adding/removing goals or sessions also saves immediately. There is no explicit Save, Submit, Approve, or Return workflow for cases.
- New cases initialize registration date to today, class to the first sample class, referral source to the first source, case type to سلوكية, and whether the student works to لا.
- Status is derived: جديدة when there is no session and no end date; قيد المتابعة when there is at least one session and no end date; منتهية when an end date exists.
- The counselor can print a case or delete it and its sessions after confirmation. The supervisor can view case details read-only through a separate details modal.
- The counselor signature field is plain text. No signature image upload, digital signature, file attachment, or generated Excel import for these forms exists in the HTML.

## Remaining decisions and deferred workflows

The implementation contracts above resolve the current field/ownership/draft/review choices. The following remain planning topics, not additional requirements found in the HTML:

- Plan any future access to historical records after transfers/reassignment; current scope requires current assignments and does not grant historical access automatically.
- Decide reporting/printing/export needs and whether attachments are required.
- Decide formal submit/return/reject workflows, notifications and retention/restore UI separately from the current save/review flow.
- Plan server-side access checks for sensitive case/family/health information, audit events, and reliable saves. Do not copy browser role switching or local storage as authorization or permanent storage.
- Continue following the [backend instructions](BACKEND_INSTRUCTIONS.md), [project instructions](PROJECT_INSTRUCTIONS.md), and [responsive requirements](RESPONSIVE_REQUIREMENTS.md), including Arabic/English, RTL/LTR, scoped APIs, paginated tables, accessible scrolling and the implemented sectioned case editor. Complete live visual/mobile acceptance before declaring the UI verified.

## Source map for later development

| Source definition/function | What it establishes |
| --- | --- |
| `REGS`, `CLASSES`, `SRC`, `FU` | Seven registers, fields, list columns, and select options. |
| `CASE_SECTIONS`, `caseView` | Twelve case sections and repeatable goal/session fields. |
| `fld`, `defv`, `doSave` | Input rendering, defaults, validation, and register review transitions. |
| `pageReg`, `openRec`, `inbox`, `A` action handlers | Create/edit/delete, filtering, printing, supervisor notes, and review actions. |
| `caseProgress`, `caseStatus`, `caseInput`, `A.newcase` | Case progress, derived status, autosave, and initial values. |
| `A.viewcase`, `persist` | Supervisor case viewing and local-storage persistence. |

## Demo examples for all newer forms — 2026-10-25

`DemoCounselorFormSeeder` and `masar:seed-demo-forms` now provide opt-in fictional examples for all seven forms after interviews. From `backend/`, run `php artisan masar:seed-demo-forms` to preview, then add `--apply` to insert missing examples. Select one register with `--form=case-studies` or another preview key. Run management and student seeders first. The command requires local/testing MySQL and refuses staging/production; it is not part of `DatabaseSeeder`.

Verified locally: **66 records per form across 11 schools**, **22 Pending / 22 Reviewed / 22 Approved per form**, and **308 reviews overall**. Cases include all 12 sections, 132 goals and 66 sessions, with 22 cases in each progress state. Dates, enum choices, optional values and narratives vary; examples and sensitive narratives are explicitly fictional. Student interviews and their 44 reviews remain unchanged.

Stable UUID slots preserve manual edits, reviews and deleted records. Missing student/current assignment/supervisor prerequisites are skipped and counted. Normal typed save/review services enforce authorization and transactional writes. Existing accounts, passwords and assignments are preserved. API checks confirmed the sample counselor sees six per form and the supervisor 66 per form. See [commands and deployment restrictions](DEPLOYMENT.md#8-seeders-local-demo-only).


## Directorate-head viewing — 2026-10-25

The directorate head can view all eight saved form types at `/portal/directorate/{form}`: interviews, parent meetings, vocational guidance, bulletins, studies, committee activities, home visits and case studies. Each has the existing filtered/paginated table and details, including Pending/Reviewed/Approved status, latest supervisor note, reviewer/date and stale-review indication when answers have changed. Case details include goals and sessions. There is no new formal submission/completion state; case progress remains separate from review status.

Access is read-only and limited to forms whose school and counselor belong to the head's own directorate. Historical records remain visible after assignments end. Heads cannot create/edit/delete forms or save supervisor decisions. School/counselor hyperlinks stay in the head workspace; general student management/detail permissions are unchanged. Arabic/English instructions describe read-only viewing. Existing counselor and supervisor flows retain their permissions.


## Multiple records and student history — 2026-10-25

A student may have multiple interviews, parent meetings, home visits and case studies, including several of the same type on the same date. Each record keeps its own answers, review status/notes and revision history. The student's detail page now includes a paginated Student forms section with type buttons, review-status filter and links to individual records. Create opens the existing modal with that student preselected and fixed; repeating Create starts a separate record. The counselor sees only their authorized records in currently assigned schools.

Counselor school lists for these four student-linked types accept `student_id` alongside existing filters. All eight types support repeated entries; vocational guidance, bulletins, studies and committee activities remain school/class records. Existing schema already permits multiple entries, so no migration, reset or reseeding is required.


## Supporting attachments — 2026-10-25

The source HTML has no binary upload fields. The following optional support files are a new extension to its school-level registers:

| Form | Supporting documents |
| --- | --- |
| Studies | Study report, results document or spreadsheet |
| Bulletins | The bulletin document or image |
| Vocational guidance | Activity worksheets, presentations saved as PDF, or supporting images |
| Committee activities | Activity report, participant spreadsheet or supporting images |

Save the form, open its details, then use Attachments. Drag files into the drop zone or use Choose files, review selected names, then Upload files. PDF, DOCX, XLSX, JPG/JPEG and PNG are supported, up to 10 MB each and five active attachments per record. Uploads are sequential; failed selections remain for retry. File selection alone is not a saved upload. Create/edit dialogs explain this save-first flow. No new attachment fields are added to interviews, parent meetings, home visits or case studies.

Only the authorized owner uploads/removes. Supervisors and heads can download within the same form-view scope they already have. Preview is by downloading and opening the file, with no embedded viewer. Files stay on private storage, and every download rechecks the parent/file relationship and current access. Upload/removal advances the form revision and returns it to Pending review; earlier supervisor notes remain visible with their historical-version warning. Removal hides a file but retains its bytes privately for history; it is not a permanent purge.

API paths are `/api/v1/{workspace}/forms/{form}/{record}/attachments` (GET; counselor POST), `/{attachment}/download` (GET), and counselor `/{attachment}` (DELETE). Uploads require file, request UUID and current parent lock version; deletion requires current parent lock version. Mutation responses return the new version; lists return bounded public metadata and the current version. Parent form JSON lists remain unchanged. See [deployment/storage/cleanup instructions](DEPLOYMENT.md#form-attachment-storage).
