# Alder Supply: customer preparation handbook

Prepare a reviewable handoff from six legacy customer records. Billing resolves uncertain values and business choices; engineering receives customer drafts, separate invoice plans, source records, and explanations. Alder Supply is a fictional supplier in an original Young Copy project. The workspace sends no requests to Stripe.

## Before starting

The source is a fixed batch, AS-104. Download source CSV provides the six original records; the workspace does not accept uploaded files. Changes exist only in the current tab’s memory. Reloading or confirming Reset sample batch clears corrections, decisions, and completion. Download the handoff before leaving. A downloaded handoff cannot be reloaded into this workspace.

The supplier requires an account identifier, company name, and billing email. Its supported terms are NET 15, NET 30, NET 45, and NET 60. These are scenario policies. Stripe Customer creation makes name and email optional. The seeded identifiers are present and unique; this prototype does not implement a general identifier-validation or duplicate-detection process.

## Operator procedure

1. Open **Review the export**. Check the original values for all six accounts. Northline Hardware, Juniper Supply, and Mason Fabrication start with no detected issues. Linden Industrial needs an email correction; Cedar Workshop needs a hold decision; Harbor Maintenance needs a terms decision.
2. Open **Review the mappings**. Select each source field or use Find a field. Read the API reference and supplier rule separately. Customer fields describe the account; invoice parameters describe later billing work.
3. Open **Resolve the exceptions**. Choose a record, enter the correction or decision, and save. Sample helper buttons fill the forms but do not save changes. Read the selected treatment and reason before recording.
4. Open **Review the handoff**. Select each prepared record to review its customer fields and invoice plan. Check deferred records, correction counts, and current decisions. A draft download remains available with unresolved records listed under open issues.
5. Select **Mark review complete** after every record has a treatment. Download the reviewed handoff. Completion records a local review timestamp; no import, invoice, or business authorization follows automatically.

The summary’s ready count includes deferred records because their review treatment is resolved. Customer drafts exclude deferred records. With Cedar deferred and the other exceptions resolved, the summary shows six ready records while the handoff contains five customer drafts, five invoice plans, and one deferred record.

## Exception decision procedure

### Linden Industrial: correct the recipient

The source value is `billing@linden`. Select the corrected sample email to enter `billing@linden.example`, or enter another syntactically valid sample value. Add a correction note explaining the basis for the change. Save correction records the previous value, replacement, note, and timestamp. Basic validation requires an address with a domain and limits the value to 512 characters; a successful check does not verify the recipient or deliverability.

Use the original export as the source record, then review the correction separately. Subsequent email corrections append entries to the corrections array. The form displays the latest correction, while the download retains the earlier correction entries. All sample addresses use the reserved `.example` domain.

### Cedar Workshop: determine the hold treatment

The source says On hold without explaining its scope. Choose **Defer this customer record** when the scenario does not establish permission to prepare the account. The handoff retains the source record and hold decision, excluding customer and invoice drafts for Cedar.

Choose **Prepare the customer draft; keep invoice preparation on hold** when the scenario permits preparation of customer details. Cedar then receives a customer draft and an invoice plan marked On hold. The instruction requires a separate business release decision. Neither the source status nor this instruction configures a Stripe billing restriction.

Both choices require a reviewer name and reason. The sample helper fills in example text. Business approval requires separate verification. Change this decision removes the current hold decision and reopens the exception. Earlier hold choices are not retained as history.

### Harbor Maintenance: replace unsupported terms deliberately

NET EOM cannot be treated as a fixed number of days. Select NET 15, NET 30, NET 45, or NET 60 only as an explicit scenario replacement, then record a reviewer and reason. Without a recorded choice, Harbor remains an open issue and receives no customer draft.

The original NET EOM value remains in the source records. The replacement is held in the decision object and used to build the invoice plan. Changing the choice requires reopening the decision. Earlier terms decisions are not retained. Any saved correction, new decision, or reopened decision clears completed-review status and requires another completion step.

## Data dictionary and mapping contract

| Source CSV field | Internal property | Handoff destination | Rule |
| --- | --- | --- | --- |
| account_id | id | source_account_id; fields.metadata.legacy_account_id | Preserve the seeded source identifier. Metadata preserves the source reference. Duplicate prevention requires separate logic. |
| company_name | company | customer_drafts[].fields.name | Trim surrounding spaces; require a nonempty value no longer than 256 characters. |
| billing_email | email | customer_drafts[].fields.email | Trim surrounding spaces; require basic address syntax and no more than 512 characters. |
| payment_terms | terms | invoice_plans[].future_invoice_parameters.days_until_due | Convert supported NET periods to 15, 30, 45, or 60. A recorded replacement takes precedence. |
| account_status | status | deferred_records or invoice-plan treatment | On hold requires a decision. No source status is sent as a Stripe Customer field. |

The NET parser accepts letter-case variations and whitespace between NET and the allowed number. The parser does not implement calendar-based terms. Invoice plans always pair `days_until_due` with `collection_method: "send_invoice"`. These parameters are separate from the customer fields.

The interface exposes correction controls for the three seeded exceptions. The interface has no general editor for company names, identifiers, or additional source records. Although the model checks company names, there is no company-name correction form. Defer bypasses the other issue checks for the held record, because that record will not enter the prepared drafts.

Official references recorded by the project, checked September 17, 2026: [Customer creation](https://docs.stripe.com/api/customers/create), [Invoice creation](https://docs.stripe.com/api/invoices/create), and [Metadata](https://docs.stripe.com/api/metadata). Confirm the chosen API version and current requirements before implementation.

## Handoff JSON contract

Downloads are named `alder-AS-104-review-draft.json` or `alder-AS-104-reviewed-handoff.json`. Both use the same structure. `review_status` is Draft review or Review complete, and `reviewed_at` is null until completion. The export time recorded in `generated_at` is independent of the last edit. Timestamps use ISO 8601 UTC strings.

| Top-level keys | Contents |
| --- | --- |
| project, batch, generated_at | Project label, AS-104, export timestamp. |
| review_status, reviewed_at, context | Local review state and explicit project boundaries. |
| sources, sources_checked, supplier_rules | Official URLs, reference date, scenario policies. |
| customer_drafts, invoice_plans | Prepared customer values and separate planning instructions, joined by source_account_id. |
| deferred_records, open_issues | Excluded records with their hold decisions or unresolved issue objects. |
| decisions, corrections | Current business decisions keyed by account; cumulative email correction entries. |
| original_source_records, reviewed_source_records | Original six records and current six records. Only email corrections change reviewed source values. |
| implementation_checklist | Conditions for later integration planning. |

These are exact-shape excerpts from the exported arrays. A Northline customer draft contains:

```json
{
  "source_account_id": "AS-10482",
  "target": "POST /v1/customers",
  "fields": {
    "name": "Northline Hardware",
    "email": "accounts@northline.example",
    "metadata": { "legacy_account_id": "AS-10482" }
  }
}
```

Its separate invoice plan contains:

```json
{
  "source_account_id": "AS-10482",
  "state": "For implementation review",
  "instruction": "Use the customer ID returned by Customer creation when planning the invoice. Verify remaining invoice requirements separately.",
  "future_invoice_parameters": {
    "collection_method": "send_invoice",
    "days_until_due": 30
  },
  "note": "Invoice instructions only. No invoice, customer ID, line items, or charges have been created."
}
```

Before Linden is corrected, its open-issue entry is:

```json
{
  "source_record": {
    "id": "AS-10483",
    "company": "Linden Industrial",
    "email": "billing@linden",
    "terms": "NET 30",
    "status": "Active"
  },
  "issues": [
    { "kind": "email", "label": "Billing email needs correction" }
  ]
}
```

A correction entry contains `record_id`, `field: "billing_email"`, `original`, `replacement`, `note`, and `recorded_at`. A decision is nested under the account ID and `hold` or `terms`, with `choice`, `reviewer`, `reason`, `recorded_at`, and `context: "Scenario decision; not verified business approval"`. Hold choices are `defer` and `prepare_hold`; terms choices are strings such as `NET 45`. A deferred entry contains `source_record` and `decision`.

The file has no schema-version property, authenticated reviewer identity, persistent event log, Stripe Customer IDs, invoice line items, or API responses. Treat every field as review input. Never send the full handoff object as an API payload.

## Developer integration plan

The developer integration plan describes requirements for future implementation. Automated integration is outside the completed project scope.

First, establish the real source schema and approval process. Define identifier uniqueness, permitted changes, authoritative billing contacts, and the owner of held accounts. Add input validation and a versioned handoff schema before supporting arbitrary batches. Local completion alone cannot authorize production changes.

Next, choose and pin the API version. Validate approved customer fields on a server, manage credentials there, and test in a Stripe sandbox. Define duplicate detection and idempotency before creating any customer. Retaining a legacy identifier in metadata does not make repeated requests safe by itself.

For every successful Customer creation, record the returned Customer ID against the source account ID. Capture request outcomes, failures, and retry state in durable storage. Define a reconciliation report so operations can distinguish prepared, attempted, created, rejected, and deferred records. The current browser state supplies none of those execution records.

Plan invoicing separately. Obtain the actual customer reference and applicable invoice details, including approved line items and other required business data. Review the billing lifecycle before enabling invoice actions. For a held account, implement an enforceable release check in the integration; a text instruction or metadata value cannot enforce that policy.

Finally, design authenticated review, durable storage, permissions, and an append-only decision history if the workflow becomes operational. Specify retention and recovery. The current terms and hold objects represent current decisions only, while email corrections accumulate within one tab session.

## Acceptance and reconciliation checklist

- Initial batch: six source records, three customer drafts, three invoice plans, three open issues, and no deferred records.
- Email correction: invalid syntax or a blank note prevents saving; a valid correction updates the reviewed record while preserving the original export.
- Terms decision: a supported choice, reviewer, and reason are required. A NET 45 replacement produces 45 invoice days without changing source NET EOM.
- Hold preparation: after all exceptions are resolved, six customer drafts and six invoice plans appear, including one plan on hold.
- Hold deferral: after the other exceptions are resolved, five customer drafts, five invoice plans, and one deferred record appear. Every source account belongs to exactly one of customer drafts, deferred records, or open issues.
- Completion: unresolved issues prevent completion. Saving or reopening a decision clears the completion timestamp. Download labels follow the current review state.
- Export review: check original and reviewed records, cumulative email corrections, current decisions, and source links. Confirm no invented Customer IDs or invoice line items appear.
- Session recovery: save the JSON before reset or reload. Both return the workspace to its original six-record state.

The project README records model and browser validation covering both hold paths, source preservation, form errors, NET 45, exports, completion invalidation, keyboard modal behavior, mapping search, reset, mobile overflow, and the absence of external requests and page errors. Re-run relevant checks after changing rules, controls, or export structure.

## Maintaining the documentation

Keep rule changes synchronized between `model.js`, mapping and form content in `workflow.js`, the implementation guide in `index.html`, and this handbook. Update reference dates only after checking the cited sources. Regenerate screenshots after interface changes, and verify examples against a fresh export. The standalone HTML, CSS, and JavaScript files make the interface and accompanying documentation straightforward to publish together; no automated documentation publishing pipeline is implemented.