Capability Rebuild Packet Template¶
- Status:
CURRENT REBUILD PACKET TEMPLATE - Context:
Context Appendix N - Use: one packet per business capability or atomic process selected for reconstruction or React + Next.js migration
- Do not use: to copy a legacy page, route or helper as the target design
1. Packet Identity¶
Capability / Process ID:
Capability name:
Product outcome:
Owning module/domain:
Operating profiles:
Current lifecycle:
Migration readiness input:
Current source revision:
Document owner:
Process owner/reviewer:
Target-role reviewer:
Related Phase/Task:
2. Original Business Requirement¶
State the original user/business request in concrete terms.
Include:
- the problem being solved;
- the user-visible result;
- the operating consequence if the capability is missing or wrong;
- the distinction between required behavior and incidental current implementation;
- explicitly rejected or out-of-scope interpretations.
3. Actors, Roles And Capabilities¶
| Actor | Normal responsibility | Allowed commands | Read-only visibility | Review/correction | Escalation |
|---|---|---|---|---|---|
Document:
- personal-account requirement;
- manager/Office override;
- super-admin/impersonation behavior;
- role versus module versus menu versus record-level authorization;
- profile-specific capability selection;
- negative/denied behavior;
- current compatibility gaps;
- target server-side enforcement.
Do not use numeric tenant IDs or customer names as policy definitions.
4. Trigger, Preconditions And Completion¶
Trigger¶
What event, request or business condition starts this capability?
Preconditions¶
- required record/state;
- required actor/capability;
- required related records;
- physical/provider/file/device prerequisites;
- configuration and module prerequisites.
Completion¶
Define completion through authoritative readback.
Command accepted
+ transaction committed
+ authoritative record reread
+ required downstream checkpoint/effect disposition visible
= capability result
Non-implication¶
List what this completion does not mean.
Example:
Loader Complete
!= Final Review Confirmed
!= Inventory Reconciled
5. Normal Operator Flow¶
| Step ID | Actor | Entry/page | Context to verify | Minimum input | Command/action | Visible result | Authoritative reread | Next owner |
|---|---|---|---|---|---|---|---|---|
STEP-010 |
Add a sequence diagram.
sequenceDiagram
participant User
participant UI
participant App
participant DB
User->>UI: Open capability
UI->>App: Query current context
App->>DB: Read authoritative state
DB-->>App: Current result
App-->>UI: Typed view model
User->>UI: Submit primary action
UI->>App: Command
App->>DB: Conditional transaction
DB-->>App: Committed record
App-->>UI: Exact readback
6. State Model¶
State table¶
| State | Business meaning | Entry predicate | Allowed next states | Blocked commands | User-visible wording |
|---|---|---|---|---|---|
State diagram¶
stateDiagram-v2
[*] --> INITIAL
INITIAL --> ACTIVE: Approved command
ACTIVE --> COMPLETE: Completion command
COMPLETE --> ACTIVE: Approved correction/reopen
Separate:
- business state;
- assignment/job attempt state;
- provider/effect state;
- user-facing derived status;
- compatibility mirror.
7. Data Contract¶
Authoritative records¶
| Record/table/entity | Identity | Owns | Tenant scope | Lifecycle | Retention/audit |
|---|---|---|---|---|---|
Relationships¶
erDiagram
PRIMARY ||--o{ CHILD : contains
PRIMARY ||--o{ AUDIT : records
Field contract¶
For every consequential field document:
| Field | Meaning | Type/unit | Required/default | Source | Validation | Mutable states | Audit/reversal |
|---|---|---|---|---|---|---|---|
Include:
- current numeric ID and durable UUID responsibility;
- natural key and tenant uniqueness;
- units/precision/rounding;
- original versus canonical value;
- soft delete;
- derived/cache/mirror fields;
- provider IDs;
- file/evidence references;
- migration mapping.
8. Command Contract¶
Create one section per command.
<CommandName>¶
Purpose:
Normal actor:
Profile/capability:
Input DTO:
Current state predicate:
Validation:
Authorization:
Transaction owner:
Authoritative writes:
Audit/evidence:
Effect intents:
Return/readback:
Idempotency key:
Duplicate behavior:
Conflict behavior:
Timeout/unknown-result recovery:
Manual recovery:
Current adapters:
Target adapters:
Do not define a command as arbitrary table/column mutation.
9. Query Contract¶
Create one section per query.
<QueryName>¶
Purpose:
Audience:
Input/filter:
Tenant/role scope:
Source records:
Join/derivation rules:
Freshness requirement:
Pagination/sort:
Output DTO:
Empty state:
Denied state:
Error state:
Cache policy:
Current adapters:
Target adapters:
A derived query must identify the authoritative records it projects and must not become a mutation owner.
10. Event And Effect Contract¶
| Event/effect | Triggering local commit | Intent identity | Adapter | Result states | Retry | Reconciliation | Manual recovery |
|---|---|---|---|---|---|---|---|
Distinguish:
business command committed
provider/file/device intent recorded
provider accepted request
provider final result reconciled
operator-visible completion
Document whether the current source calls a provider inside, before or after the local transaction and how the target design changes that boundary.
11. Exception And Recovery Matrix¶
| Exception ID | Detection | Possible committed state | What must be reread | Safe next action | Must not repeat | Owner/escalation |
|---|---|---|---|---|---|---|
EXC-010 |
Required cases:
- invalid input;
- unauthorized role/record;
- stale state/conflict;
- duplicate click/request;
- timeout before known result;
- partial local result;
- provider/file/device partial result;
- physical/system mismatch;
- missing related record;
- correction/Reopen/Undo/Void/Reversal;
- manual recovery.
12. UI Contract¶
Current UI¶
| Surface | Responsibility | Current source | Known coupling/debt | Must preserve |
|---|---|---|---|---|
Target React UI¶
Route:
Page/layout:
Server Component queries:
Client Components:
Form/action boundaries:
Loading state:
Empty state:
Denied state:
Validation state:
Conflict/partial state:
Success/readback state:
Next-work navigation:
Mobile/accessibility:
Stable Wiki link:
Next.js adapter boundary¶
Route Handler:
Server Action, if any:
Authentication/session bridge:
Tenant context:
Request validation:
Application command/query called:
HTTP/error mapping:
File/upload path:
Cache/revalidation policy:
No React or Next.js file owns business SQL or process transition policy.
13. Current Runtime Caller Map¶
| Caller | Type | Operation | Current owner | Compatibility reason | Target disposition | Caller-zero proof |
|---|---|---|---|---|---|---|
| page/API/helper/job/provider |
Include:
- pages and modal/action entry points;
- API v2 and legacy routes;
- helper/includes;
- direct SQL;
- cron/worker/webhook;
- reports and exports;
- provider callbacks;
- external clients;
- Wiki/manual links.
14. Target Component Map¶
flowchart LR
React[React UI]
Next[Next.js adapter]
App[TypeScript application]
Domain[Domain policy]
Repo[Repository]
DB[(MySQL)]
Outbox[Outbox]
Worker[Worker]
Provider[Provider]
React --> Next
Next --> App
App --> Domain
App --> Repo
Repo --> DB
App --> Outbox
Outbox --> Worker
Worker --> Provider
Specify exact package/module ownership rather than generic shared utilities.
15. Migration And Coexistence¶
Read migration¶
current query characterization
-> TypeScript query against MySQL
-> shadow compare
-> React/Next.js read-only surface
-> target-role parity
Write migration¶
legacy writer remains sole owner
-> new command validates/shadows without write
-> bounded cutover selects new writer
-> exact readback and effect observation
-> rollback disables new entry
-> accepted stabilization
-> source/runtime caller-zero
-> legacy retirement
Required matrix¶
| Scenario | Legacy expected | New expected | Comparison evidence | Rollback trigger |
|---|---|---|---|---|
| Normal | ||||
| Denied | ||||
| Duplicate | ||||
| Timeout | ||||
| Partial effect | ||||
| Correction |
One-writer rule¶
Name the authoritative writer before, during and after cutover.
Before:
During shadow:
During bounded new cohort:
Rollback:
After acceptance:
16. Operational Runbook And Wiki¶
Runbook¶
- target audience;
- normal entry;
- exact steps;
- visible result;
- recovery/escalation;
- diagrams;
- current limitations.
Wiki¶
Current slug:
Proposed/stable slug:
Role/audience:
Page outline:
Required diagrams:
Related procedures:
Status glossary:
Recovery page links:
Current T_WIKI_PAGE review state:
Publication/readback state:
Migration URL/redirect rule:
17. Verification And Acceptance Plan¶
Documentation must define the tests that establish confidence even when the current documentation session does not execute them.
| Layer | Scenario | Environment/account | Evidence | Required for |
|---|---|---|---|---|
| Pure logic | Engineering candidate | |||
| DB integration | Transaction confidence | |||
| API contract | Adapter confidence | |||
| Browser normal | Target-role acceptance | |||
| Browser denied | Role safety | |||
| Retry/recovery | Operational safety | |||
| Provider/device | Effect readiness | |||
| Deployment/readback | Release acceptance | |||
| Field observation | Stabilization/value |
18. Open Decisions¶
| Decision | Current fact | Options | Recommendation | Owner | Blocks |
|---|---|---|---|---|---|
Do not close an unknown by silently choosing the easiest implementation.
19. Definition Of Ready For Implementation¶
- [ ] Product outcome and profile scope accepted;
- [ ] owner, roles and authorization explicit;
- [ ] normal/recovery process accepted;
- [ ] state/data/identity contract explicit;
- [ ] command/query/effect contracts explicit;
- [ ] current callers inventoried;
- [ ] React/Next.js/TypeScript/worker responsibility explicit;
- [ ] one-writer/rollback accepted;
- [ ] parity and target-role test matrix defined;
- [ ] Runbook/Wiki impact defined;
- [ ] no unresolved decision that changes data integrity or live access.
20. Definition Of Complete¶
- [ ] implementation matches the packet;
- [ ] normal, denied, duplicate, timeout, partial and recovery scenarios verified;
- [ ] target roles accept the visible workflow;
- [ ] effects are reconciled;
- [ ] Wiki and Runbook are current;
- [ ] release/deployment readback complete;
- [ ] observation/stabilization complete;
- [ ] legacy source and runtime callers are zero;
- [ ] retirement and rollback records preserved.
---¶
Source:
docs/reconstruction/CAPABILITY_REBUILD_PACKET_TEMPLATE.md— ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.