# Product Requirements Document

## Validation Checklist

- [x] All required sections are complete
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Problem statement is specific and measurable
- [x] Problem is validated by evidence (not assumptions)
- [x] Context → Problem → Solution flow makes sense
- [x] Every persona has at least one user journey
- [x] All MoSCoW categories addressed (Must/Should/Could/Won't)
- [x] Every feature has testable acceptance criteria
- [x] Every metric has corresponding tracking events
- [x] No feature redundancy (check for duplicates)
- [x] No contradictions between sections
- [x] No technical implementation details included
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision
Every backstock action — individual or bulk — produces a clear, specific, user-attributed audit trail that store managers can review, filter, and use for accountability.

### Problem Statement
Backstock bulk actions (Spec 042) write to the action log, but the log entries are **practically useless** for audit purposes:

1. **Indistinguishable actions**: Location changes, category changes, age updates, note additions, and tag additions all log as action code 6 ("added items to bin") — a manager reviewing the log cannot tell what actually happened.
2. **Missing action types**: Hide (7) and unhide (8) actions are logged but produce **blank readable strings** in the activity feed because `getReadableString()` has no case for them.
3. **No bulk indicator**: A manager cannot tell whether 1 bin was updated individually or 50 bins were updated in a batch — the log entries look identical.
4. **No change detail**: The log records THAT something changed but not WHAT changed (e.g., "moved from Back Room to Storage Unit 111" vs generic "added items to bin").
5. **Print labels not logged**: The only mass action that produces no audit record at all.

The consequence: **store managers cannot hold team members accountable for bulk changes**, and investigating "who moved all these bins?" requires guessing from timestamps.

### Value Proposition
A meaningful audit trail transforms bulk actions from a black box into a transparent, accountable system. Managers get per-action specificity ("Casey moved 12 bins to Storage Unit 111"), batch grouping ("this was part of a single bulk operation"), and the ability to filter the activity feed by action type and user.

## User Personas

### Primary Persona: Store Manager
- **Demographics:** Store owner or senior manager, moderate technical skill, uses backstock daily
- **Goals:** Maintain accountability for inventory changes, investigate discrepancies quickly, understand team activity at a glance
- **Pain Points:** Can't tell who did what when reviewing the activity log; bulk operations are invisible; has to ask team members directly instead of checking the log

### Secondary Persona: Team Member
- **Demographics:** Store employee performing daily backstock tasks, basic technical skill
- **Goals:** Complete bulk operations efficiently, see their own recent actions for verification
- **Pain Points:** No way to confirm their bulk action completed correctly by reviewing the log; generic "added items" message doesn't help them verify

## User Journey Maps

### Primary User Journey: Investigating Inventory Discrepancies
1. **Awareness:** Manager notices bins are in wrong locations or have unexpected categories
2. **Consideration:** Manager opens the backstock activity feed or bin history to investigate
3. **Usage:** Manager filters by action type (e.g., "location changes") or by user to find who made changes
4. **Resolution:** Manager identifies the specific bulk operation — who did it, what changed, how many bins were affected — and addresses the issue with the team member
5. **Retention:** Manager trusts the audit trail and checks it regularly for oversight

### Secondary User Journey: Verifying Bulk Operation Results
1. **Awareness:** Team member just performed a bulk action on 20 bins
2. **Usage:** Team member opens the activity feed and sees their bulk operation grouped together with a clear description
3. **Verification:** Team member confirms the right bins were updated with the right values
4. **Confidence:** Team member trusts the system recorded their work accurately

## Feature Requirements

### Must Have Features

#### Feature 1: Specific Action Codes for Each Bulk Operation
- **User Story:** As a store manager, I want each type of bulk action to have a unique, descriptive log entry so that I can tell exactly what was done without guessing.
- **Acceptance Criteria:**
  - [ ] Location changes log as "moved [bin] to [location name]" (not generic "added items")
  - [ ] Category changes log as "changed category of [bin] to [category name]"
  - [ ] Age date updates log as "updated age date of [bin]"
  - [ ] Note additions log as "added note to [bin]"
  - [ ] Tag additions log as "added tags to [bin]"
  - [ ] Tag removals log as "removed tags from [bin]"
  - [ ] Empty bins log as "emptied [bin]" (already works via action code 0)
  - [ ] Hide actions log as "hid [bin]" (currently blank)
  - [ ] Unhide actions log as "unhid [bin]" (currently blank)

#### Feature 2: Change Detail Capture
- **User Story:** As a store manager, I want to see what specifically changed (old value → new value) in the activity log so that I can understand the impact of each action.
- **Acceptance Criteria:**
  - [ ] Location changes record the destination location name
  - [ ] Category changes record the new category name
  - [ ] Tag changes record which tags were added or removed
  - [ ] The activity feed displays these details alongside the action description

#### Feature 3: Bulk Operation Grouping
- **User Story:** As a store manager, I want bulk operations to be visually grouped in the activity feed so I can see that 20 bins were changed as part of one operation rather than 20 separate individual actions.
- **Acceptance Criteria:**
  - [ ] Bulk actions include a batch identifier linking all actions from the same operation
  - [ ] The per-bin activity history shows which entries came from a bulk operation
  - [ ] The global activity feed can collapse/expand bulk operation groups

#### Feature 4: Fix Hidden/Unhidden Display
- **User Story:** As a store manager, I want hide and unhide actions to display properly in the activity log instead of showing blank entries.
- **Acceptance Criteria:**
  - [ ] Action code 7 displays as "hid [bin]" in the activity feed
  - [ ] Action code 8 displays as "unhid [bin]" in the activity feed
  - [ ] Both are displayed in the per-bin action history endpoint

### Should Have Features

#### Feature 5: Print Labels Logging
- **User Story:** As a store manager, I want to see when labels were printed for bins so I have a complete picture of all actions taken.
- **Acceptance Criteria:**
  - [ ] Mass print label actions log a record for each bin printed
  - [ ] Log entry reads "printed label for [bin]"

#### Feature 6: Activity Feed Filtering by Action Type
- **User Story:** As a store manager, I want to filter the activity feed by action type (e.g., show only location changes, or only empty actions) so I can investigate specific kinds of changes efficiently.
- **Acceptance Criteria:**
  - [ ] Activity feed provides a dropdown or filter UI for action type
  - [ ] Selecting an action type shows only matching entries
  - [ ] Filter can be combined with existing date/user filtering if present

### Could Have Features

#### Feature 7: Activity Feed Filtering by User
- **User Story:** As a store manager, I want to filter the activity feed by team member so I can review a specific person's actions.
- **Acceptance Criteria:**
  - [ ] Activity feed provides a user selector
  - [ ] Selecting a user shows only their actions

### Won't Have (This Phase)
- **Undo/revert bulk operations** — would require snapshotting previous state which is a much larger scope
- **Notification/alerts on bulk operations** — could be added later if managers want real-time oversight
- **Detailed before/after values for every field** — capturing destination is enough; full diff tracking is over-engineered for this use case
- **Audit log separate from bsActions** — we enhance the existing table rather than creating a parallel system

## Detailed Feature Specifications

### Feature: Specific Action Codes + Change Detail
**Description:** Each mass edit action type gets its own action code (or enhanced metadata) so the activity feed can render a specific, human-readable description including what changed.

**User Flow:**
1. User selects multiple bins on the backstock overview page
2. User clicks a bulk action (e.g., "Change Location")
3. User confirms the action in the modal
4. System performs the bulk operation
5. System logs one `bsActions` entry per affected bin with:
   - The specific action code for "location change"
   - The user who performed it
   - A detail string recording the destination (e.g., "Back Room")
   - A batch identifier linking all entries from this operation
6. Activity feed displays: "Casey moved [Bin A] to Back Room (bulk: 12 bins)"

**Business Rules:**
- Rule 1: Every bulk action type must produce a distinguishable log entry
- Rule 2: The user performing the action is always captured from the authenticated session
- Rule 3: Skipped bins (already at target state) do NOT generate a log entry
- Rule 4: Failed bins do NOT generate a log entry
- Rule 5: Print label actions generate a log entry even though they don't modify the bin

**Edge Cases:**
- Scenario 1: User performs bulk action on 0 bins (all filtered/skipped) → Expected: No log entries created, no batch record
- Scenario 2: Mid-operation failure (some bins succeed, some fail) → Expected: Only successful bins get log entries, batch still created for the subset
- Scenario 3: Category or location is deleted after logging → Expected: Log displays "[Deleted Category]" or "[Deleted Location]" gracefully
- Scenario 4: Same user performs two bulk operations in quick succession → Expected: Each gets its own batch ID, they don't merge

## Success Metrics

### Key Performance Indicators

- **Completeness:** 100% of bulk action types produce specific, readable log entries (currently 0% are specific)
- **Accuracy:** Log entries correctly identify the action type, user, and change detail in all cases
- **Adoption:** Activity feed is viewable and useful without any "Unknown Action" or blank entries
- **Investigation Time:** Managers can identify who performed a bulk action and what changed within 30 seconds of opening the activity feed

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| bulk_action_logged | actionType, binCount, userId, batchId | Verify all bulk actions are captured |
| activity_feed_viewed | filterType, filterValue | Understand how managers use the feed |
| activity_feed_filtered | actionTypeFilter, userFilter | Validate filter feature adoption |

---

## Constraints and Assumptions

### Constraints
- Must use the existing `bsActions` table (enhanced with new columns via migration) — no separate audit system
- Must not break existing individual action logging (codes 0-3, 6)
- Must not degrade bulk operation performance significantly (logging should not add noticeable latency)
- New action codes must not conflict with existing codes (0, 1, 2, 3, 6, 7, 8)

### Assumptions
- The activity feed is consumed in two places: the global actions endpoint (`GET /actions`) and the per-bin history endpoint (`GET /bin/:id/actions`)
- Managers will use the per-bin history more than the global feed for investigations
- The `bsActions` table can be extended with new columns (detail, batchId) via the migration system
- Existing action code values (0-8) can be extended with new values (9+) without breaking consumers

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Adding columns to bsActions breaks existing queries using `SELECT *` | Medium | Low | New columns are nullable, existing code tolerant of extra columns |
| Batch grouping adds complexity to activity feed rendering | Medium | Medium | Keep batch display simple — just a visual indicator, not a collapsible tree |
| Large bulk operations (500+ bins) create many log rows | Low | Low | bsActions already handles this volume from individual operations; add index on batchId |
| New action codes confuse `getReadableString()` consumers | Medium | Low | Add cases for all new codes; default case returns "updated [bin]" instead of empty |

## Open Questions

- [x] Do bulk actions currently log anything? **YES — they log to bsActions but with generic/broken action codes**
- [x] Is the existing `bsActions` table the right place for this? **YES — enhance rather than replace**

---

## Supporting Research

### Existing System Analysis
- `bsActions` table: columns `id`, `binID`, `action` (int), `employeeID`, `categoryID`, `timePerformed`
- Action codes in use: 0 (empty), 1 (add category), 2 (remove some), 3 (remove all category), 6 (generic update), 7 (hide), 8 (unhide)
- `getReadableString()` only handles cases 0-3 and 6 — missing 7, 8, and all mass-specific codes
- Per-bin history endpoint at `GET /bin/:id/actions` has its own switch with cases 0-3 and default "Unknown Action"
- Global activity feed at `GET /actions` uses `getAllRecentActions()` which calls `getReadableString()`

### Gap Summary
| Mass Action | Current Code | Current Display | Desired Display |
|-------------|-------------|-----------------|-----------------|
| Change Location | 6 | "added items to bin" | "moved [bin] to [location]" |
| Empty Bins | 0 | "removed everything from bin" | OK (already correct) |
| Change Category | 6 | "added items to bin" | "changed category of [bin] to [category]" |
| Change Tags (add) | 6 | "added items to bin" | "added tags to [bin]" |
| Change Tags (remove) | 3 | "removed all of [cat] from bin" | "removed tags from [bin]" |
| Hide | 7 | (blank) | "hid [bin]" |
| Unhide | 8 | (blank) | "unhid [bin]" |
| Print Labels | none | (not logged) | "printed label for [bin]" |
| Update Age | 6 | "added items to bin" | "updated age of [bin]" |
| Add Notes | 6 | "added items to bin" | "added note to [bin]" |