Project-Pro/aktualia.com.pl
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Jacek Pyziak
2026-04-27 17:46:12 +02:00
parent ed2f89567c
commit 11afc80a7b
27 changed files with 1245 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

283
.paul/phases/03-registration-form-settings/03-02-PLAN.md Normal file
View File

@@ -0,0 +1,283 @@
---
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>

132
.paul/phases/03-registration-form-settings/03-02-SUMMARY.md Normal file
View File

@@ -0,0 +1,132 @@
---
phase: 03-registration-form-settings
plan: 02
subsystem: ui
tags: [php, smarty, mysql, registration, form]
requires:
- phase: 01-registration-form-update
provides: MfParticipant model, IndexController save flow, Reg.tpl admin display
provides:
- additional_info TEXT column in mf_participant (idempotent migration)
- MfParticipant::getAdditionalInfo / setAdditionalInfo
- "Dodatkowe informacje" textarea in public registration form (Index.tpl, Index_good.tpl)
- KSeF helper note relocated above new field
- Field displayed in confirmation templates (IndexSent.tpl, IndexSent_good.tpl)
- Field displayed in admin Reg.tpl institution column
- Admin Reg table ordered newest-first (id_mf_participant DESC)
affects: []
tech-stack:
added: []
patterns:
- "Raw <textarea> for multi-line optional fields (formField plugin does not support textarea type)"
- "CalcController.php RegAction sort set via setSortBy — value injected directly into ORDER BY"
key-files:
created:
- _rejestracja/sql/2026-04-27-additional-info-field.sql
- _rejestracja/sql/apply-2026-04-27-additional-info-field.php
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
key-decisions:
- "Use raw <textarea rows=3> instead of {formField} — framework plugin does not support textarea type"
- "DB column named additional_info (TEXT) despite original KSeF context — generic name matches visible label"
- "KSeF helper note kept as dictionary translation but relocated above the new textarea (not inside NIP div)"
patterns-established:
- "Idempotent migration runner pattern: INFORMATION_SCHEMA column check before ALTER TABLE"
duration: ~15min
started: 2026-04-27T00:00:00Z
completed: 2026-04-27T00:00:00Z
---
# Phase 3 Plan 02: Dodatkowe informacje Field + Admin Table Order
**Optional free-text "Dodatkowe informacje" textarea added to registration form with DB persistence, KSeF helper note relocated above it, field shown in confirmations and admin panel, admin Reg table reversed to newest-first.**
## Performance
| Metric | Value |
|--------|-------|
| Duration | ~15 min |
| Tasks | 3/3 completed |
| Files modified | 8 |
| Files created | 2 |
## Acceptance Criteria Results
| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Field in Public Form | Pass | Helper note above textarea in Index.tpl and Index_good.tpl |
| AC-2: Value Persisted to DB | Pass | IndexController saves via setAdditionalInfo(Request::GetPost('additional_info')) |
| AC-3: Field in Confirmation | Pass | IndexSent.tpl and IndexSent_good.tpl show field after NIP |
| AC-4: Field in Admin Panel | Pass | Reg.tpl institution cell shows field after NIP |
| AC-5: Admin Table Reversed | Pass | CalcController RegAction: setSortBy('id_mf_participant DESC') |
| AC-6: Idempotent Migration | Pass | PHP runner checks INFORMATION_SCHEMA before ALTER TABLE |
## Accomplishments
- New `additional_info` TEXT column added to `mf_participant` with safe idempotent runner.
- KSeF helper text moved from inside NIP field div to above the new "Dodatkowe informacje" textarea.
- Field persisted on form submit and displayed in all output surfaces (confirmation, email, admin).
- Admin `/Calc/Reg` table now shows newest registrations first without any schema change.
## Files Created/Modified
| File | Change | Purpose |
|------|--------|---------|
| `_rejestracja/sql/2026-04-27-additional-info-field.sql` | Created | Raw ALTER TABLE SQL |
| `_rejestracja/sql/apply-2026-04-27-additional-info-field.php` | Created | Idempotent migration runner (?run=20260427) |
| `_rejestracja/core/model/MfParticipant.class.php` | Modified | Added additional_info field mapping, property, getter/setter |
| `_rejestracja/controller/IndexController.php` | Modified | Saves additional_info from POST |
| `_rejestracja/template/partial/Index/Index.tpl` | Modified | Moved helper text, added textarea below NIP |
| `_rejestracja/template/partial/Index/Index_good.tpl` | Modified | Same changes as Index.tpl |
| `_rejestracja/template/partial/Index/IndexSent.tpl` | Modified | Shows field in confirmation summary |
| `_rejestracja/template/partial/Index/IndexSent_good.tpl` | Modified | Shows field in alternate confirmation |
| `_rejestracja/Admin/template/partial/Calc/Reg.tpl` | Modified | Shows field in admin institution column |
| `_rejestracja/Admin/controller/CalcController.php` | Modified | RegAction sorted DESC by id_mf_participant |
## Decisions Made
| Decision | Rationale | Impact |
|----------|-----------|--------|
| Raw `<textarea>` not `{formField}` | `formField` Smarty plugin supports only `type="text"` / `type="hidden"` | Must use raw textarea for multi-line fields |
| Column name `additional_info` | Label changed from "ID KSeF" to "Dodatkowe informacje" — generic column name avoids future confusion | Neutral; column stores any free text |
## Deviations from Plan
None — plan executed exactly as written.
## Issues Encountered
None.
## Next Phase Readiness
**Ready:**
- Phase 3 feature work complete. Both plans (03-01 form settings admin page, 03-02 additional field) delivered.
- Production deployment requires two migration runners:
1. `/_rejestracja/sql/apply-2026-04-24-registration-form-settings.php?run=20260424` (from 03-01)
2. `/_rejestracja/sql/apply-2026-04-27-additional-info-field.php?run=20260427` (from 03-02)
**Concerns:**
- Plan 03-01 APPLY was completed but UNIFY was never run — no 03-01-SUMMARY.md exists. Phase not formally closed until 03-01 is also unified.
**Blockers:**
- None for further development. Deployment migration must precede production use of the new field.
---
*Phase: 03-registration-form-settings, Plan: 02*
*Completed: 2026-04-27*