Alharith alsubhi submission branch

.gitignore

@@ -1,5 +1,9 @@
 HELP.md
 target/
+logs/
+data/
+src/main/resources/application-oracle-local.properties
+src/main/resources/application-docker-local.properties
 .mvn/wrapper/maven-wrapper.jar
 !**/src/main/**/target/
 !**/src/test/**/target/

.run/Docker Oracle DbVisualizer.run.xml

@@ -0,0 +1,10 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Docker Oracle DbVisualizer" type="SpringBootApplicationConfigurationType" factoryName="Spring Boot">
+    <option name="ACTIVE_PROFILES" value="docker" />
+    <module name="oraclequantapi" />
+    <option name="SPRING_BOOT_MAIN_CLASS" value="com.oraclequantapi.oraclequantapi.OraclequantapiApplication" />
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

.run/Local Mac DbVisualizer.run.xml

@@ -0,0 +1,10 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Local Mac DbVisualizer" type="SpringBootApplicationConfigurationType" factoryName="Spring Boot">
+    <option name="ACTIVE_PROFILES" value="local" />
+    <module name="oraclequantapi" />
+    <option name="SPRING_BOOT_MAIN_CLASS" value="com.oraclequantapi.oraclequantapi.OraclequantapiApplication" />
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

.run/Oracle XE.run.xml

@@ -0,0 +1,10 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Oracle XE" type="SpringBootApplicationConfigurationType" factoryName="Spring Boot">
+    <option name="ACTIVE_PROFILES" value="oracle" />
+    <module name="oraclequantapi" />
+    <option name="SPRING_BOOT_MAIN_CLASS" value="com.oraclequantapi.oraclequantapi.OraclequantapiApplication" />
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.0.0] - 2026-05-20
+
+### Added
+- **Core Conversion Engine**: Implemented `z*[^z]` decoder logic to convert measurement input strings into package inflow total lists. Supports standard characters (`a-y`), multiplier prefixes (`z`), empty/zero values (`_`), and case insensitivity.
+- **Persistent REST History Endpoints**: Exposes standard endpoints to interact with history database tables:
+  - `GET /convert-measurements` (accepts `input` / `convert-measurements` query parameter, converts, logs, and persists details).
+  - `GET /history` (returns all records).
+  - `GET /history/{id}` (returns a specific record).
+  - `PUT /history/{id}` (replaces/updates record).
+  - `PATCH /history/{id}` (patches specific fields).
+  - `DELETE /history` (clears history record table).
+- **Dual Persistence Architecture**: Setup standard H2 in-memory configuration by default (for out-of-the-box local testing) and added a dedicated `prod` profile using `ojdbc11` to persist history records on production Oracle XE databases.
+- **7-day Rolling Log System**: Configured custom Logback rolling file appenders that generate structured daily logs under `logs/pkc-api.log` with a strict 7-day retention policy.
+- **Full Automated Testing**: Added `ConversionEngineTest` to verify correctness on all requirements and edge cases.

README.md

@@ -1,61 +1,155 @@
-## Submission Instructions
-
-To submit your Oracle JAVA Spring Boot Maven project as a solution, please follow these steps:
-
-### Step 1: Install git on your PC
-- Install "git" as shown in this tutorial: [How to install git](https://youtu.be/iYkLrXobBbA?si=_l0haibv_X9NpIjJ)
-- Open command prompt and run
-  ```bash
-  git version
-  ```
-- If you see the version, then git is successfully installed.
-
-### Step 2: Fork the Repository
-- Navigate to [this repository](https://github.com/CodelineAtyab/oraclequantapi) provided by Codeline.
-- Click on the "Fork" button at the top-right corner of the page to create a copy of the repository under your own GitHub account.
-
-### Step 3: Clone the Forked Repository
-- Open your terminal or command prompt.
-- Clone the forked repository to your local machine using the following command:
-  ```bash
-  git clone https://github.com/your-username/repo-name.git
-  ```
-
-### Step 4: Create a new branch
-- Navigate to the cloned repository directory
-  ```bash
-  cd repo-name
-  ```
-- Create a new branch for your code submissions (Replace your-name with your name in your-name-submission-branch):
-  ```bash
-  git checkout -b your-name-submission-branch
-  ```
-
-
-### Step 5: Add Your Code
-- Implement the API
-
-### Step 6: Commit your changes
-- Run the following commands in order to commit your changes:
-  ```bash
-  git add *
-  git commit -m "Meaningful commit message here"
-  ```
-
-### Step 7: Push Your Branch to GitHub
-- Run the following commands to upload the changes to the forked github repository (Replace your-name with your name in your-name-submission-branch):
-  ```bash
-  git push origin your-name-submission-branch
-  ```
-
-### Step 8: Create a Pull Request
-- Go to your forked repository on GitHub.
-- You should see a prompt to create a pull request. Click on "Compare & pull request".
-- Provide a title and description for your pull request, then click "Create pull request".
-
-### Step 9: Notify Codeline
-- Notify on slack that you have created a PR for your solution.
-
-## Note: If you face any issues in the process above, Please do the following:
-- Watch [this youtube tutorial](https://www.youtube.com/watch?v=a_FLqX3vGR4)
-- Contact Ikhlas or Atyab.
+# My OracleQuant API notes
+
+This is my small project for the evaluation.  
+You send text like `aa` → you get `[1]`. It saves everything in **MEASUREMENT_HISTORY**.  
+Jar: **pkc-api.jar** · runs on port **8081**
+
+I am still learning so this readme is just my story day by day.
+
+---
+
+## Day 1 · Tuesday 20 May 2026
+
+**What I tried to do**  
+Start the task. Read the PDF. I did not understand everything at first (packages, letters a-z = numbers, etc).
+
+**What I did**  
+- Opened the project in IntelliJ  
+- Made the conversion code (`ConversionEngine`)  
+- Ran unit tests — the 8 examples from PDF passed (I was happy here)  
+- Started Spring Boot with **H2** database (teacher said easier for first step)
+
+**Challenges**  
+- PDF is long and has many rules  
+- I confused where to put my files in the package folder  
+- First time using Spring Boot + Maven together
+
+**What worked at end of day**  
+Tests green. I could think the math part is OK.
+
+---
+
+## Day 2 · Wednesday 21 May 2026
+
+**What I tried to do**  
+Make the API real — controller, history save, try Postman.
+
+**What I did**  
+- Added `/convert-measurements` and `/history` endpoints  
+- Every Postman call should save a row (input, output, IP, time)  
+- Fixed a stupid mistake: class name must match file name (`PackageConversionApplication`)  
+- Connected **DbVisualizer** to H2 file database  
+- Saw table **MEASUREMENT_HISTORY** with my test data
+
+**Challenges**  
+- App would not compile sometimes (JPA package missing in IDE)  
+- Had to run `mvn compile` to see real errors  
+- Did not know JDBC URL for H2 at first
+
+**What worked at end of day**  
+Postman: `http://localhost:8081/convert-measurements?input=aa` → `[1]` and row in DbVisualizer.
+
+---
+
+## Day 3 · Thursday 22 May 2026
+
+**What I tried to do**  
+Move from H2 to **real Oracle** (because assignment wants Oracle XE).
+
+**What I did**  
+- Installed Oracle XE on Mac  
+- Wrote SQL scripts for user **pkc_user** password **PkcPassword1**  
+- Made `oracle` profile in `application.properties`  
+- Tried DbVisualizer with `localhost:1521` and service **XEPDB1**
+
+**Challenges**  
+- **ORA-01017** — login failed (I typed wrong password many times)  
+- **ORA-01045** — user exists but cannot connect (needed GRANT CREATE SESSION)  
+- App started very slow or failed when Oracle was off  
+- I did not understand SYS vs SYSTEM vs pkc_user at first
+
+**What worked at end of day**  
+User `pkc_user` can login in SQL*Plus / DbVisualizer. Table created.
+
+---
+
+## Day 4 · Friday 23 May 2026
+
+**What I tried to do**  
+Run the app on **Oracle Linux VM** (assignment also talks about Linux server).
+
+**What I did**  
+- VM name: **AlharithLinux**, user **alharith**  
+- Built jar: `mvn clean package` → copied **pkc-api.jar** to `/home/alharith/`  
+- Tried SSH from Mac (port 2222) — did not work, used VM screen instead  
+- Ran `java -jar pkc-api.jar` on Linux
+
+**Challenges**  
+- I ran `pkc-api.out` once by mistake (that is not the app file)  
+- Tried `mvn spring-boot:run` on VM → error **no plugin spring-boot** (no pom.xml there, only jar)  
+- DbVisualizer from Mac to VM IP `10.0.2.15` → **timeout** (NAT network, I learned later)  
+- Port 8081 sometimes already used from old run  
+- Connection refused in Postman because app stuck on database
+
+**What worked at end of day**  
+I understand: on VM you only need `java -jar`, not Maven. Scripts saved in `scripts/` folder.
+
+---
+
+## Day 5 · Saturday 24 May 2026
+
+**What I tried to do**  
+Make everything work on **my Mac** with **Docker + DbVisualizer + Postman** (my main setup now).
+
+**What I did**  
+- Oracle in Docker container **oracle-xe**  
+- Script `docker-setup-db-only.sh` for pkc_user  
+- Script `mac-start-docker.sh` to start DB + API  
+- API runs **inside Docker** on network **pkc-net** with profile **docker-internal**  
+- DbVisualizer on Mac still uses `127.0.0.1:1521`
+
+**Challenges**  
+- Docker said container name already exists — had to `docker start oracle-xe` not create new one  
+- `mvn spring-boot:run` with docker profile on Mac **hangs** forever (HikariPool) — big confusion  
+- Postman **ECONNREFUSED** — app never really started  
+- Port **8081 in use** — needed `scripts/stop-pkc-api.sh` first
+
+**What worked at end of day (finally)**  
+```bash
+bash scripts/stop-pkc-api.sh
+bash scripts/mac-start-docker.sh
+```
+Postman OK. DbVisualizer shows **MEASUREMENT_HISTORY**. I can show my trainer.
+
+---
+
+## Quick run (what I use now)
+
+```bash
+cd /Users/mac/IdeaProjects/oraclequantapi
+bash scripts/stop-pkc-api.sh
+bash scripts/mac-start-docker.sh
+```
+
+- Postman: `http://127.0.0.1:8081/convert-measurements?input=aa`  
+- History: `http://127.0.0.1:8081/history`  
+- DbVisualizer: `jdbc:oracle:thin:@//127.0.0.1:1521/XEPDB1` · user `pkc_user` · pass `PkcPassword1`
+
+Build jar: `mvn clean package`
+
+---
+
+## Small hints (for me later)
+
+- docker profile + mvn on Mac = bad (hangs)  
+- use `.jar` not `.out`  
+- stop old app before start (8081)  
+- VM = `java -jar` only if no project folder
+
+---
+
+## Submit
+
+branch `alharith-alsubhi-submission-branch` → push → PR → Slack trainer
+
+*last update 24 May 2026*