Signed customers still get reminders from outdated agreements
Objective
- Stop clients who have already signed from receiving agreement reminder emails and texts when an outdated or extra agreement row still sits on the work order next to the valid signed agreement (or when stale / superseded rows keep comms alive).
- When an agreement moves to Outdated (data:
isStaleon a signed agreement after content drift), automatically archive that agreement document and automatically create a new agreement for the same inspection + template inpendingstatus with up-to-date merged content so it can be signed—without waiting for staff to use Recreate Outdated or manual archive. - Align cleanup expectations with operations: service changes should not leave orphan signing obligations that fight the denormalized agreement-present / agreement-signed gates used in flows—decision needed on full parity with reports when services drop off.
Background
- Support and scheduling describe cases where the customer already signed, but duplicate reminder emails and texts still went out because an outdated agreement remained on the job until staff removed it.
- Example repro context — work order: May 9 inspection — workorder tab.
- Product language vs schema: the UI label “Outdated” maps to
Agreement.isStale(withstaleAt).statusremainspending,viewed,signed, ordeclinedinattik-backend/src/models/agreementSchema.ts; there is no separateoutdatedenum value—staleness is orthogonal tostatus. - Stale detection today:
attik-backend/src/events/bullmq/agreementStaleWorker.tscompares regenerated content tosignedContentHash(or legacy content hash) and setsisStale/staleAton signed agreements when content would differ; it does not archive, does not enqueue a replacementpendingrow, and does not cancel comms by itself. - Manual staff path today:
attik-frontend/src/app/tools/inspections/[id]/components/Agreements.tsxexposes Recreate Outdated, which callsPOST /agreement/manual(implemented inattik-backend/src/routes/agreements.ts) to addpendingrows when a template has a signed + stale agreement and no non-stale row; archive is a separatePATCHaction (handleSetArchived). The new bar is automatic archive + automatic recreate at the moment an agreement becomes outdated. - Active-agreement guard:
rejectIfActiveAgreementExistsinattik-backend/src/routes/agreements.tstreats active as not archived, not stale, not declined—stale rows already do not block a new instance, but unarchived stale signed rows may still interact with reminder and portal list behavior until archived and superseded. - Denormalized gate:
inspection.agreement.presentandinspection.agreement.signedare recomputed from active Agreement documents when rows change (attik-backend/src/events/streamHandlers/agreementStream.tswithagreementLockStateFromDbLeaninattik-backend/src/util/functions/agreements/agreementLockSync.ts). Flow conditions useagreement-signedandagreement-presentviaattik-backend/src/util/functions/actionFlows/attributePathResolver.ts;handleEventTriggerdByBulldrives scheduled email and sms. - Auto-generation today:
attik-backend/src/util/functions/agreements/autoGenerateAgreements.tscreates missing template agreements and regenerates unsigned content when charges change; it does not implement delete-on-service-removal or the new archive + replace on stale behavior—decision needed for interaction with charge streams.
Scope
Backend
- Stale transition hook: extend or follow
agreementStaleWorker(attik-backend/src/events/bullmq/agreementStaleWorker.ts) so that when a signed agreement first becomesisStale, the system can archive that document (todayPATCHallowsarchivedonly forsignedrows—seeattik-backend/src/routes/agreements.tsPATCH /:id) and then create apendingreplacement equivalent toPOST /agreement/manual(template merge viamergeAgreementBlocksToContent,InspectionFullPopulatedForFlow,hashContent—same route file). - Idempotency and ordering: ensure one replacement
pendingper template per transition and safe behavior if staff or other jobs also mutate rows—decision needed (compare to existingrejectIfActiveAgreementExistsand queue dedup inqueueAgreementStaleCheck). - Reminder / flow evaluation: trace
handleEventTriggerdByBulland time-based steps so archived + superseded rows no longer satisfy unsigned signing nudges; relate toinspectionStream/chargeStreamcallers ofqueueAgreementStaleCheck. - Activity:
attik-backend/src/util/functions/activity/agreementHandlers.tslogsisStalechanges—consider whether automated archive/create should emit clearer audit trails.
Frontend
Agreements.tsx—staleAgreementsNeedingRecreation,handleRecreateOutdated,handleSetArchivedmay become partially redundant or need copy/UX updates if the server always performs the two steps.templateIdsBlockedByActiveAgreements(attik-frontend/src/util/agreements/templateIdsBlockedByActiveAgreements.ts) must stay consistent with backend active definition if automation changes timing of stale vs archived.AgreementsNeeded.tsxand portal lists — confirm tasks and client surfaces match single active signing obligation per template after automation.
Config / product
- Company-configured flows (reminder cadence) may need audit per brand—decision needed whether automation is global or configurable (see related ATT-1609).
- Decision needed: behavior when
isStaleis cleared (worker unmarks stale if content matches again)—whether to leave archived history vs other product rules.
References
- Example inspection — workorder tab
- Related: ATT-1609 — configurable agreement staleness / inspection triggers
attik-backend/src/models/agreementSchema.tsattik-backend/src/routes/agreements.ts—rejectIfActiveAgreementExists,POST /manual,PATCH /:id(archive rules)attik-backend/src/events/bullmq/agreementStaleWorker.tsattik-backend/src/events/streamHandlers/agreementStream.tsattik-backend/src/util/functions/agreements/agreementLockSync.tsattik-backend/src/util/functions/actionFlows/attributePathResolver.tsattik-backend/src/util/functions/actionFlows/handleEventTriggerdByBull.tsattik-backend/src/util/functions/agreements/autoGenerateAgreements.tsattik-frontend/src/app/tools/inspections/[id]/components/Agreements.tsxattik-frontend/src/components/task-check/AgreementsNeeded.tsx
Status: Completed
Log in to comment and vote
No comments yet
Be the first to share your thoughts.