# Project Items with actual `pending` changes

- The essential issue with the current pending chage workflow is that the project items are edited immediately, and we store a history of their state so we can revert them back if the change is rejected. We need to reverse this process so that when a pending change is made, we leave the items as they are and store a representation of what they will become. Then update the items to their new state if the change is accepted.

## Technical details

### project_item

- We store the original details of a project item inside the `pending_changes.changed_fields` as well as the `action` that is needed to restore them to their previous state (update, create, destroy). The pending change is created via callbacks on the ProjectItem that come from the PendingChanges module. Since we don't want to actually edit the items until the change request is accepted, we need to essentially reverse this workflow. That way, when the item is edited, we don't actually change it but instead store the new attributes somewhere else.

### projects_controller

- A ChangeRequest is created during the #process_pending_changes action on projects_controller with the `owner` set to the finance project. If the price was adjusted, we also create a ProjectAdjustment at this time. We also create these records during the #process_project_visit_pending_changes action.

## Main Concerns
- Since we will be fundamentally changing the way that `project_items` handle changes, this necessitates significant consideration for how to display project_item changes in the UI.
- We need to keep logic in place for displaying old `pending_changes` so that they can be viewed in the notes and history of older projects.

## Solution

### General

- Create a new table, `proposed_project_item_changes`, that will store the possible "future" state of a project_item. Reference this new model for future project_item updates and update project_items to their desired state when the change request is accepted. Mark proposed_project_item_changes as processed, completed, whatever terminology is appropriate.

### Breakdown

#### UI Update

1. Acquire NUX/Product approved mocks that show Project Item current & pending changes [GLC-300](https://nitro.powerhrg.com/runway/backlog_items/GLC-300)
2. Create "Show Proposed Project Item Changes" feature toggle to protect delivering visual feature.
3. Based on complexity of mocks, chop up UI changes into stories - projected by FT that implements territory level lookup.
4. Turn on FT in prod, and remove use of visual feature toggle from codebase.

#### Happy path ProposedProjectItemChanges (PPICs) workflow

1. Create "Use Proposed Project Item Changes" feature toggle to protect new data workflow. [GLC-300](https://nitro.powerhrg.com/runway/backlog_items/GLC-300)
2. Create new ProposedProjectItemChange model with all necessary fields and callback logic to set prices (do not implement commissionable_sale_amount - it is unwanted/unneeded). Use FT in ProjectItemsController#update that implements territory level FT lookup. When off, use current logic. When on, DON'T create project_items, create proposed_project_item_changes instead. Store all relevant data. (MySQL GUI ninja testing) * See addendum for all `proposed_project_item_changes` fields [GLC-301](https://nitro.powerhrg.com/runway/backlog_items/GLC-3001)

--- At this point, UI section must be finished to move forward ---

3. Update UI to display PPIC data in the exact same way as pulling that info from the `pending_changes`. This does not need feature toggle protection, because the creation of the PPICs is already protected.
4. Implement updating PPICs upon a user accepting and rejecting a proposed change. Handle the creation of Project related pending changes; handle the creation creation of a change_request; handle the creation of project adjustments.
5. Implement finalizing PPICs upon finance accepting and rejecting a pending change. Handle the updating of Project related pending changes; handle the updating of a change_request; handle the updating of project adjustments; handle the updating of `projects.price`; handle the updating/creation/destroying of `project_items`. Remember to "skip_pending_change" callbacks.
6. Update Project Amendment logic (a generated PDF) to display PPICs the same way that it displayed PI pending_changes.
7. Update/verify that all history modals for project items display information as expected. Compare to history of pending changes from previous implementation.
8. At this point, we should have parody with the old process. So - turn on "Use Proposed Project Item Changes" FT in prod. Monitor for a day.
9. Remove "Use Proposed Project Item Changes" usage from codebase (crucial).

#### Edge Case ProposedProjectItemChange (PPIC) workflow

- Incrementally address all other scenarios that create ProjectItem `pending_changes` and move them over, one at a time, in to the PPIC workflow. We KNOW of two right now:
- NAM related ProjectItem updates.
- ProjectVisit related project_item updates.
- Code audit for any pending_changes code that hasn't been addressed.
- Once production is no longer creating any ProjectItem `pending_changes`, remove the ProjectItem pending_change callbacks altogether - never remove the Project related ones. -- Ninjas can/will assist in identifying any places in Nitro that still create these and address.
- At this point, we are done. But re-evaluate the state of everything one more time in case more tweaks are needed.

## Addendum

`proposed_project_item_changes` fields (Everything except fields that are not in use):

Only when implementing this can this be made totally final. We should only need to copy over what is editable from the update action. If it isn't editable, then it's not part of a proposed_change.

- `project_id`
- `order_from_supplier` ? need this?
- `location`
- `quantity`
- `width`
- `height`
- `depth`
- `product_id`
- `product_name`
- `product_model`
- `product_style`
- `product_details`
- `product_config`
- `comment`
- `leg`
- `cost`
- `pii_report_info_*` (leave out if automated outside of edit form)
- `man_days` ? (leave out if automated outside of edit form)
- `vendor_so_number` ? (leave out if automated outside of edit form)
- `nam_item` (true/false)
- `indent_measurement`
- `returned_to_stock` (needed when checking if a pending_change record is required)
- `returned_to_stock_reason_id`
- `parent_item_id` - (verify - is this something updatable via the config form?) - This is related only to solar
- `design_id` - solar related
- `key_photo_id` (likely solar related)
- `retail_price`
- `ceiling_price`
- `marketing_discount_price`
- `adjusted_marketing_discount_price`
- `qa_ceiling_price`

Fields NOT copied over:
- `created_by` (this will exist, but unique to record)
- `updated_by` (this will exist, but unique to record)
- `created_at` (this will exist, but unique to record)
- `updated_at` (this will exist, but unique to record)
- `vertical_grid_count` - All of these are NULL in prod
- `horizontal_grid_count` - All of these are NULL in prod
- `note` - Let whatever note was on the item BEFORE the change stay there. Can't apply a 'note' to a pending change (I think)
- `purchase_order_id` (verify - but likely not something updatable via the config form)
- `install_task_id` (verify - but likely not something updatable via the config form)
- `commissionable_sale_amount` - This will be re-evaluated once a PI is updated. But no reason to do so in a proposed item
- `product_retail_price` - Always NULL, column that should be deleted
- `delivery_date` (verify - but likely not something updatable via the config form)
- `discounted_price` (this old field is not always correct)
- `financing_discount_price` (although, this older field is believe to be incorrect)

New fields:

- `action` (creation - updation - deletion) ENUM DEFAULT 'creation'
- `project_item_id` BIGINT NOT NULL
- `created_by_id` INT DEFAULT NULL (auditor_creator)
- `updated_by_id` INT DEFAULT NULL (auditor_updator)
- `status` (proposed - requestor_declined - requestor_approved - finance_declined - finance_approved) ENUM DEFAULT 'proposed'
- `processed` (true/false) BOOLEAN DEFAULT false