---
phase: 03-registration-form-settings
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
  - _rejestracja/core/model/MfParticipant.class.php
  - _rejestracja/controller/IndexController.php
  - _rejestracja/template/partial/Index/Index.tpl
  - _rejestracja/template/partial/Index/Index_good.tpl
  - _rejestracja/template/partial/Index/IndexSent.tpl
  - _rejestracja/template/partial/Index/IndexSent_good.tpl
  - _rejestracja/Admin/template/partial/Calc/Reg.tpl
  - _rejestracja/Admin/controller/CalcController.php
  - _rejestracja/sql/2026-04-27-additional-info-field.sql
  - _rejestracja/sql/apply-2026-04-27-additional-info-field.php
autonomous: true
delegation: off
---

<objective>
## Goal
Add a new optional "Dodatkowe informacje" textarea to the registration form (below NIP), with the existing KSeF helper note moved above it. Persist the value to the database, display it in the confirmation summary and admin panel, and reverse the admin Reg table so newest registrations appear first.

## Purpose
Participants need a free-text field for supplementary information (e.g. internal KSeF identifier). The helper note currently embedded inside the NIP field guides the user to this field, so it must move above the new textarea. The table order reversal makes reviewing new sign-ups faster.

## Output
- SQL ALTER TABLE migration and PHP runner for the new `additional_info` column (TEXT NULL).
- Updated `MfParticipant` model with `additionalInfo` property, getter, and setter.
- Updated IndexController persisting `additional_info` from POST.
- Updated public form templates: KSeF helper text moved above the new "Dodatkowe informacje" textarea.
- Updated confirmation templates (IndexSent, IndexSent_good) showing the field after NIP.
- Updated admin Reg.tpl showing the field after NIP.
- CalcController RegAction sorted descending by `id_mf_participant`.
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md

## Prior Work
@.paul/phases/01-registration-form-update/01-01-SUMMARY.md

## Source Files
@_rejestracja/core/model/MfParticipant.class.php
@_rejestracja/controller/IndexController.php
@_rejestracja/template/partial/Index/Index.tpl
@_rejestracja/template/partial/Index/Index_good.tpl
@_rejestracja/template/partial/Index/IndexSent.tpl
@_rejestracja/template/partial/Index/IndexSent_good.tpl
@_rejestracja/Admin/template/partial/Calc/Reg.tpl
@_rejestracja/Admin/controller/CalcController.php
</context>

<acceptance_criteria>

## AC-1: "Dodatkowe informacje" Field in Public Form
```gherkin
Given a visitor opens the registration form at /_rejestracja/index
When the form renders below the NIP Instytucji field
Then a helper note "Do wypełnienia w przypadku posiadania identyfikatora wewnętrznego w KSEF i prośba o podanie KSeF ID wew." appears above a small textarea labelled "Dodatkowe informacje" that accepts free text and is not required
```

## AC-2: Value Persisted to Database
```gherkin
Given a visitor submits the registration form with text in "Dodatkowe informacje"
When the form is processed by IndexController
Then the value is stored in the additional_info column of mf_participant for that participant row
```

## AC-3: Field in Confirmation Summary
```gherkin
Given a registration was submitted with a value in "Dodatkowe informacje"
When the confirmation page (IndexSent.tpl / IndexSent_good.tpl) renders
Then the institution data section shows "Dodatkowe informacje: <value>" after NIP Instytucji
```

## AC-4: Field in Admin Panel
```gherkin
Given an administrator opens /_rejestracja/Admin/Calc/Reg
When the registration list renders
Then each participant row shows the additional_info value (or empty) in the institution data cell after NIP Instytucji
```

## AC-5: Admin Reg Table Reversed Order
```gherkin
Given registrations exist in the mf_participant table
When an administrator opens /_rejestracja/Admin/Calc/Reg
Then the table displays registrations in descending order by id_mf_participant (newest first)
```

## AC-6: Deployment Migration
```gherkin
Given the production database does not yet have the additional_info column
When the PHP migration runner is executed
Then ALTER TABLE adds additional_info TEXT NULL DEFAULT NULL without affecting existing rows
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Add additional_info Column, Model, and Controller Persistence</name>
  <files>
    _rejestracja/sql/2026-04-27-additional-info-field.sql,
    _rejestracja/sql/apply-2026-04-27-additional-info-field.php,
    _rejestracja/core/model/MfParticipant.class.php,
    _rejestracja/controller/IndexController.php
  </files>
  <action>
    **SQL migration** (`2026-04-27-additional-info-field.sql`):
    ```sql
    ALTER TABLE `mf_participant` ADD COLUMN `additional_info` TEXT NULL DEFAULT NULL AFTER `nip`;
    ```
    Use TEXT (not VARCHAR) to accommodate longer free-text input.

    **PHP runner** (`apply-2026-04-27-additional-info-field.php`):
    Follow the same pattern as `apply-2026-04-24-registration-form-settings.php`:
    - Require `?run=20260427` query param guard.
    - Check INFORMATION_SCHEMA whether `additional_info` column already exists in `mf_participant`.
    - Run the ALTER only if missing; print success or skip message either way.

    **MfParticipant.class.php** (`core/model/` only — do NOT edit `core/_model/`):
    - Add `'additional_info' => 'additionalInfo'` to `static $fields` array after the `'nip'` entry.
    - Add `private $additionalInfo;` property after `$nip`.
    - Add `$additionalInfo = null` parameter to `__construct` signature after `$nip`, before `$phone`.
    - Assign `$this->additionalInfo = $additionalInfo;` in constructor body.
    - Add getter and setter after the existing getNip/setNip block:
      ```php
      public function getAdditionalInfo() { return $this->additionalInfo; }
      public function setAdditionalInfo($additionalInfo) { $this->additionalInfo = $additionalInfo; }
      ```

    **IndexController.php**:
    After `$objParticipant->setNip(Request::GetPost('nip'));` add:
    ```php
    $objParticipant->setAdditionalInfo(Request::GetPost('additional_info'));
    ```
    Do not touch any other part of IndexController.
  </action>
  <verify>
    - `php -l _rejestracja/core/model/MfParticipant.class.php` — no syntax errors
    - `php -l _rejestracja/controller/IndexController.php` — no syntax errors
    - `php -l _rejestracja/sql/apply-2026-04-27-additional-info-field.php` — no syntax errors
    - Confirm `getAdditionalInfo` and `setAdditionalInfo` methods and `'additional_info' => 'additionalInfo'` in `$fields` exist.
  </verify>
  <done>AC-2 and AC-6 satisfied: additional_info column migration ready, model maps it, controller persists from POST.</done>
</task>

<task type="auto">
  <name>Task 2: Public Form — Move Helper Text, Add "Dodatkowe informacje" Textarea</name>
  <files>
    _rejestracja/template/partial/Index/Index.tpl,
    _rejestracja/template/partial/Index/Index_good.tpl
  </files>
  <action>
    **Index.tpl** — current NIP block (lines ~74–79) looks like:
    ```html
    <div class="entry">
        <div class="label">{translate word='NIP Instytucji'}:</div>
        <div class="value">
            {formField  name="nip" type="text" errorClass="warning"}
            <div style="font-size: 11px; line-height: 1.3; margin-top: 4px;">{translate word='Do wypełnienia w przypadku posiadania identyfikatora wewnętrznego w KSEF i prośba o podanie KSeF ID wew.'}</div>
        </div>
    </div>
    ```
    Replace with two blocks:
    1. NIP entry with helper `<div>` removed — NIP value div contains only the formField.
    2. New entry immediately after NIP:
    ```html
    <div class="entry">
        <div class="label">Dodatkowe informacje:</div>
        <div class="value">
            <div style="font-size: 11px; line-height: 1.3; margin-bottom: 4px;">{translate word='Do wypełnienia w przypadku posiadania identyfikatora wewnętrznego w KSEF i prośba o podanie KSeF ID wew.'}</div>
            <textarea name="additional_info" rows="3" style="width:100%; box-sizing:border-box;">{if isset($smarty.post.additional_info)}{$smarty.post.additional_info|escape}{/if}</textarea>
        </div>
    </div>
    ```
    Use a raw `<textarea>` (not `{formField}`) since `{formField}` does not support textarea type in this framework.
    The `rows="3"` keeps it compact. The existing `{$smarty.post.additional_info|escape}` pattern re-populates the field on validation error, consistent with how other fields work via the formField plugin.

    **Index_good.tpl** — NIP block (lines ~74–76) has no helper text inside.
    Add the same new entry (label + helper note + textarea) immediately after the NIP entry.
    Do not change any other entries.
  </action>
  <verify>
    - Open Index.tpl: confirm helper text `<div>` is no longer inside the NIP value div.
    - Confirm the new entry with `name="additional_info"` textarea and the helper note `<div>` above it exists after NIP in both templates.
  </verify>
  <done>AC-1 satisfied: helper note appears above the "Dodatkowe informacje" textarea in both public form templates.</done>
</task>

<task type="auto">
  <name>Task 3: Display Field in Confirmations and Admin + Reverse Table Order</name>
  <files>
    _rejestracja/template/partial/Index/IndexSent.tpl,
    _rejestracja/template/partial/Index/IndexSent_good.tpl,
    _rejestracja/Admin/template/partial/Calc/Reg.tpl,
    _rejestracja/Admin/controller/CalcController.php
  </files>
  <action>
    **IndexSent.tpl** — institution data section (line ~40):
    After `NIP Instytucji: {$objParticipant->getNip()|default:$registrationMissing}<br>`, add:
    ```
    Dodatkowe informacje: {$objParticipant->getAdditionalInfo()|default:$registrationMissing}<br>
    ```

    **IndexSent_good.tpl** — institution data section (line ~32):
    After `NIP Instytucji: {$objParticipant->getNip()|default:'brak'}<br>`, add:
    ```
    Dodatkowe informacje: {$objParticipant->getAdditionalInfo()|default:'brak'}<br>
    ```

    **Reg.tpl** — institution data cell (line ~55):
    After `NIP Instytucji: {$obj->getNip()}</br>`, add:
    ```
    Dodatkowe informacje: {$obj->getAdditionalInfo()}</br>
    ```

    **CalcController.php** — RegAction method (around line 248–252):
    After `$dalData->addCondition('location', $location);` add:
    ```php
    $dalData->setSortBy('id_mf_participant DESC');
    ```
    `setSortBy` value is injected directly into `ORDER BY`, so DESC is valid here.
    Do not alter any other controller methods.
  </action>
  <verify>
    - `php -l _rejestracja/Admin/controller/CalcController.php` — no errors
    - Confirm `getAdditionalInfo()` calls in IndexSent.tpl, IndexSent_good.tpl, and Reg.tpl.
    - Confirm `setSortBy('id_mf_participant DESC')` present in CalcController.php RegAction.
  </verify>
  <done>AC-3, AC-4, and AC-5 satisfied: field shows in confirmations and admin list; Reg table ordered newest-first.</done>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- `core/_model/MfParticipant.class.php` — legacy copy, not loaded by autoloader.
- `mf_participant` existing columns other than adding `additional_info`.
- Any other admin controllers or templates beyond CalcController.php RegAction sort.
- Existing `mf_parameters` pricing logic, form field names, or dictionary keys from Phase 1 and 2.
- Smarty compiled cache files under `temp/compile`.

## SCOPE LIMITS
- Do not add validation for `additional_info` — field is optional, no format constraint.
- Do not add the field to the admin RegEdit form — display only, no edit via admin.
- Do not modify `RegPAN.tpl` (panel location=2 view).
- Do not touch `_rejestracja/template/partial/Index/_/IndexSent.tpl` (archived copy).

</boundaries>

<verification>
Before declaring plan complete:
- [ ] `php -l _rejestracja/core/model/MfParticipant.class.php` — no errors
- [ ] `php -l _rejestracja/controller/IndexController.php` — no errors
- [ ] `php -l _rejestracja/Admin/controller/CalcController.php` — no errors
- [ ] `php -l _rejestracja/sql/apply-2026-04-27-additional-info-field.php` — no errors
- [ ] `getAdditionalInfo()` and `setAdditionalInfo()` exist in MfParticipant.class.php
- [ ] `'additional_info' => 'additionalInfo'` in `$fields` array
- [ ] `<textarea name="additional_info"` present in Index.tpl and Index_good.tpl
- [ ] Helper text no longer inside the NIP value div in Index.tpl
- [ ] `getAdditionalInfo()` called in IndexSent.tpl, IndexSent_good.tpl, and Reg.tpl
- [ ] `setSortBy('id_mf_participant DESC')` in CalcController.php RegAction
</verification>

<success_criteria>
- All tasks completed with no PHP syntax errors.
- All verification checks pass.
- No existing registration behavior, pricing logic, or dictionary phrases are affected.
- Deployment SQL runner is idempotent (safe to run on production even if column already exists).
</success_criteria>

<output>
After completion, create `.paul/phases/03-registration-form-settings/03-02-SUMMARY.md`
</output>