docs: 7421 client-processing-documentation

[ttoomey]

Merging this PR

• use the squash-merge strategy for PRs targeting a release-X branch

Description

Address documentation gaps around client processing. See issue description for details

Type of change

Documentation

Checklist before requesting review

• I have performed a self-review of my code

[gigxz]

In HMIS code (and adhoc developer action), we run invalidate_processing! on the enrollment or set of enrollments. The logic is:

hmis-warehouse/app/models/concerns/hud_concerns/enrollment.rb

Lines 47 to 57 in 7627fed

	def self.invalidate_processing!
	update_all(processed_as: nil, processed_hash: nil)
	end
	def invalidate_processing!
	# use update_columns to avoid stale object errors when this method is called from Service after_commit hooks
	self.class.without_optimistic_locking do
	update_columns(processed_as: nil, processed_hash: nil)
	end
	end

It seems like the difference is:

• invalidate_processing! clears both processed_as and processed_hash on the specified enrollment(s)
• invalidate_source_data! clears processed_as on the enrollment AND on any household member's enrollments

So I have a couple questions:

• Is it safe to say it is the callers responsibility to ensure that ALL household enrollments are invalidated when necessary (i.e. by using invalidate_source_data! or invoking invalidate_processing! for each member)? (There is no built-in logic to Service History Enrollment processing to ensure that all household members are reprocessed when one is invalidated?)
• What is the significance of clearing processed_hash vs not clearing it?

[gigxz]

Depending on the answers to those questions, probably worth adding something here about significance of reprocessing a whole household together.

I think an example is: one Enrollment in the household is deleted, leading to the household composition to change from 'adults with children' to 'adults only' (not exact terms, but we have something like that on SHE). In addition to the newly deleted Enrollment being reprocessed, all remaining Enrollments must also be reprocessed in order to reflect the updated composition of the household for those enrollments.

[gigxz]

great additions and clarifications, thank you!