# Project plan — snell-freestock (Freestock Requisition)

Evidence date: 2026-10-02.

Source repository: `git@bitbucket.org:overdrive/snell-freestock.git`.

Inspected revision: `master` at `477f559` (2026-09-18, "Merged in sync/from-live-20260918 (pull request #2)"). The scan-host path named in the onboarding task (`~/projects/sonar_scan/repos/snell-freestock`) was not present on this machine. Evidence comes from a read-only clone of `origin/master`.

The onboarding task recorded last commit `f6a9391` (2025-06-04, "removed debugging code") on `master`. That commit is an ancestor. `master` has moved.

This plan describes what the repository contains. It does not decide what the product should become.

## Product

The page title and footer name the system **Freestock Requisition** (`$SYSTEM` in `include/system.inc.php`). Staff reach the app through IIS, the app matches `LOGON_USER` to an active `mstUser` row, and those users list, create, and authorise freestock requisitions (pink slips) for bill-to and ship-to customer accounts.

Provenance: **Implemented**. There is no README and no requirements document in the repository. Inline comments date product work from about 2010 through 2026 (Stephen, Yusiry, pj, maanie, and the 2026-09-18 hotfix comments).

The footer still prints version **2.0.1s** and date **31 May 2016**. The comment above that constant says "v2.0.1s - added user management". What a newer release number would be is **Unknown / Requires Confirmation**.

## Related repository

Silicon Ark already documents `snell-freestock-5.6` (`git@bitbucket.org:overdrive/snell-freestock-5.6.git`, `main` at `812337f`, 2025-06-13). Both trees use the screen title Freestock Requisition and a similar PHP layout. They are different remotes and different heads. This document set is only for `snell-freestock` at `477f559`. Whether one site replaced the other is **Unknown / Requires Confirmation**.

Notable difference on this head: the line that would set `$OVERRIDE_USERNAME` to `AzureAD\UrielBalela` is commented out in `LogginUser`. The 5.6 tree was documented with that assignment active. Do not treat the two write-ups as interchangeable.

## Branch reality

`origin/HEAD` is `master`. Nineteen commits, 2021-02-19 through 2026-09-18. Authors from `git shortlog`: Renier van Rooyen (7), Uriel_Balela (5), Lloyd (4), maanie (2), AzureAD\LloydSherewa (1).

| Commit | Date | Message |
|---|---|---|
| `8f7a155` | 2021-02-19 | Initial commit |
| `e7cc780` | 2021-02-19 | inital commit |
| `80551f1` | 2023-11-02 | repo reconciliation |
| `38e5937` | 2023-11-28 | php 8 upgardes |
| `ea0bd6e` | 2023-11-28 | php upgrades |
| `54a047a` | 2025-06-03 | active / inactive user changes |
| `552bae2` | 2025-06-03 | added blnActive to login query |
| `7c66258` | 2025-06-04 | Handle additional URL encoded characters |
| `0c07935` | 2025-06-04 | escape strings in custom decode function |
| `721ed68` | 2025-06-04 | user filter |
| `5f46bb5` | 2025-06-04 | more user filter changes |
| `f6a9391` | 2025-06-04 | removed debugging code |
| `43c1254` | 2026-09-17 | Enhance AJAX functions and error handling in requisition form |
| `307d804` | 2026-09-17 | Merged in FRS_debug_fixes (pull request #1) |
| `45460cd` | 2026-09-18 | Restore deployed 18 Sep baseline for requisition hotfix files |
| `3e1f167` | 2026-09-18 | Stop requisitions losing their items and block empty submissions |
| `520b1c4` | 2026-09-18 | fix(requisition): close hotfix review gaps |
| `a52a245` | 2026-09-18 | Restore remaining live 18 Sep files from production backup |
| `477f559` | 2026-09-18 | Merged in sync/from-live-20260918 (pull request #2) |

No tags were present on the clone. Other remote branches were not listed beyond `origin/master` and `origin/HEAD`.

Commit messages on 2026-09-18 say the tree was restored from a production backup and merged from `sync/from-live-20260918`. That is evidence the authors treated this repository as the live site on that date. Whether this commit is what is deployed today is **Unknown / Requires Confirmation**.

## Objectives (inferred from the application, not from a written plan)

No project plan exists in the repository. The following are **Inferred** from screens, SQL, and comments:

- Let a Snell user raise a freestock requisition against a region, a promotional bill-to account, and a ship-to account.
- Price requested cases and bottles from `dwdProduct` and show a rounded rand total.
- Route a submitted requisition to a manager under R10 000 and to an executive manager at or above that amount.
- Record submit and approve as rows in `sysCronJob` for a worker that is not in this repository.
- Let a special user (`blnSpecial = 1`) maintain `mstUser` rows, including marking users inactive.
- Keep a requisition from losing its header id on save, and keep an empty requisition out of submit and approve (2026-09-18 comments).

## Scope

### In this repository

- PHP pages: login, logout, authorisation list, requisition form, user administration, an AJAX XML endpoint, and `test.php`.
- Includes for layout, requisition and user classes, ODBC access, and a vendored adLDAP tree.
- `web.config` setting `index.php` as the IIS default document.
- A dated copy `include/requisition.cls.20210503.php` that no page includes.
- PHP session files under `Sessions/`, committed even though `.gitignore` lists `Sessions/`.

### Not in this repository

- The SQL Server schema, migrations, and the process that loads `dwdCustomer` and `dwdProduct`.
- The worker that reads `sysCronJob` types `FSR_NewRequisition` and `FSR_RequisitionApproved`.
- Email templates. The form builds `mailto:` links. A `Link` query parameter is commented as "logs in via email", but the mail that would add `Link` is not here.
- Automated tests, Composer or npm manifests, CI config, and a README.
- `sonar-project.properties` and `sonarqube_scan.bat`. The onboarding task listed both at the repository root. Neither file is in Git history. Provenance: **Unknown** — they may have been untracked files on the scan host.

## System shape

Browser pages on IIS include `include/system.inc.php`, which opens an ODBC connection and starts a PHP session. Authenticated pages render through `include/layout.full.inc.php`. That layout redirects to `login.php` when `$_SESSION[USER]` is missing. Data is SQL Server, reached through the ODBC class. Writes go to `fsrRequisition`, `fsrItem`, `mstUser`, `mstUsageLog`, and `sysCronJob`. Reads also use `mstUserGroupFreeStock`, `mstBranch`, `mstBrand`, `fsrRequestType`, `dwdCustomer`, `dwdProduct`, and the view `vieRequsitionManager`.

Provenance: **Implemented**. Host names, the IIS site path, and which SQL Server instance the DSN points at are **Unknown / Requires Confirmation**.

## Major components

| Component | Role | Evidence |
|---|---|---|
| `login.php` / `LogginUser` | Match `LOGON_USER` to an active user and start the session | `include/system.functions.inc.php` |
| `requisition.php` | Filterable authorisation list | `Requisition::getFilters`, `getList` |
| `requisitionForm.php` | Create, edit, submit, approve, decline, cancel, remove a line | Page switch plus `Requisition` |
| `ajax.functions.php` | XML for bill-to, ship-to, ship-to search, and products | No session check |
| `user.php` | User list and edit for `blnSpecial` menu users | `User` class |
| `sysCronJob` | Queue rows for new and approved requisitions | Inserts in `Requisition::Submit` and `Approve` |
| adLDAP tree | Present and `require`d, not constructed | `login.php` comments out `new adLDAP()` |

## Milestones visible in Git

There is no milestone document. The history that can be stated:

1. **2021-02-19** — PHP tree first committed.
2. **2023-11-02** — "repo reconciliation".
3. **2023-11-28** — commits titled as PHP 8 upgrades. The runtime version on the server is not pinned in the repo.
4. **2025-06-03 to 2025-06-04** — inactive-user behaviour, `blnActive` on login, user-list filter, URL-decoding fixes.
5. **2026-09-17** — AJAX error handling merged as pull request #1 (`FRS_debug_fixes`).
6. **2026-09-18** — production-backup restore and requisition hotfix merged as pull request #2. Empty submit/approve blocked. Save keeps the posted requisition id. Failed saves do not change status.

Anything after 2026-09-18 is **Unknown**.

## Implementation plan

No forward plan is written in the repository. Current status, from the code and the 2026-09-18 merge messages: the application is a maintained IIS/PHP site, last changed in Git to match a live backup and to stop requisitions losing items. Open product questions are listed under confirmation, not as a roadmap.

## Known dependencies

- IIS with PHP, Windows logon (`LOGON_USER`), and ODBC.
- SQL Server database reached as ODBC DSN `snell_fsr`. When the host is not `sql-server`, the code then calls `setDatabase("snell_2015")`, which opens a connection whose DSN argument is the string `snell_2015`.
- A password is hardcoded next to that DSN in `include/system.inc.php`. The secret is omitted here.
- Product and customer tables (`dwdProduct`, `dwdCustomer`) and branch regions (`mstBranch`). How they are loaded is not in this repo.
- A consumer of `sysCronJob` outside this repo.
- jQuery 1.4.2, loaded by the page header. Other jQuery files sit in `include/javascript/` and are not referenced by the header.

## Current project status

**Implemented and present on `master` at `477f559`.** No open branch, issue tracker, or TODO file was in the clone. The footer version has not been updated since the 2016 user-management note.

## Confirmation still required

- Whether `477f559` is the build currently deployed, and the IIS host name and path (`snell_freestock` vs `snell_freestock_PHP` appear only as session-path strings).
- Relationship to `snell-freestock-5.6`: successor, parallel site, or abandoned fork.
- What "2.0.1s" means relative to the repository name, and the PHP version actually running.
- Who or what processes `sysCronJob`, and whether status **Completed** is set outside this repository. Nothing in this tree writes `Completed`.
- Whether committed files under `Sessions/` should be removed from the repository. `.gitignore` already names that directory, but the files are tracked.
- Whether `sonar-project.properties` and `sonarqube_scan.bat` exist only on the scan host.