Skip to content

Commit 4688529

Browse files
dadachiclaude
dadachi
and
claude
committed
Add Phase 2 pre-step doc for Number Tag → Item Tag rename
Planning doc describing the iOS client label rename that aligns UI strings with the ItemTag identifier ahead of Phase 2 Part A cleanup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 605e08c commit 4688529

1 file changed

Lines changed: 252 additions & 0 deletions

File tree

‎docs/phase2-prestep-number-tag-rename.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Phase 2 Pre-step: Rename "Number Tag" Labels to "Item Tag" (iOS Paid)
2+
3+
**Repo:** `~/pg/iphone/NativeAppTemplate`
4+
**Branch:** `main` only (NOT `v1-with-nfc`)
5+
**Goal:** Align UI labels with the `ItemTag` identifier, so the agent's humanize-based string-literal rename logic (Phase 6) can rewrite them consistently alongside the identifier.
6+
7+
## Context
8+
9+
The Rails API substrate (Phase 1) renamed `queue_number` → `name` at the data layer. The iOS client still shows "Number Tag" and "Tag Number" labels in its UI, which do not align with the `ItemTag` identifier. For the agent to rename UI strings automatically by applying humanize/pluralize rules to the identifier, the UI label must match:
10+
11+
- Identifier: `ItemTag` → humanized: `"Item Tag"` (singular) / `"Item Tags"` (plural)
12+
- Identifier: `itemTag.name` → UI label: `"Name"`
13+
14+
## Scope
15+
16+
**In scope** (rename in this commit):
17+
- Generic "Number Tag" labels that describe the ItemTag entity itself
18+
- The field label "Tag Number" that corresponds to `itemTag.name`
19+
20+
**Out of scope** (keep as-is; will be deleted in Phase 2 Part A alongside NFC/scan removal):
21+
- Queue-flow specific messages ("Swipe a number tag below", "Server Number Tags Webpage", etc.)
22+
- Onboarding descriptions explaining the queue flow
23+
- Scan-related strings ("Read a NFC Number Tag...")
24+
- Reset-related strings ("Reset Number Tags", "All number tags reset")
25+
26+
The rationale: queue-specific strings will be removed entirely when the corresponding NFC/scan/reset code is deleted in Phase 2. Renaming them now would be churn.
27+
28+
## v1-with-nfc branch
29+
30+
**Do NOT modify.** The `v1-with-nfc` branch is preserved as an immutable queue-template snapshot for potential future use. Queue-specific "Number Tag" labels are semantically correct in that context.
31+
32+
---
33+
34+
## Execution Steps
35+
36+
### Step 1: Baseline check
37+
38+
```bash
39+
cd ~/pg/iphone/NativeAppTemplate
40+
41+
# Confirm on main and clean
42+
git branch --show-current
43+
git status
44+
45+
# Confirm baseline build is green
46+
xcodebuild build -scheme NativeAppTemplate \
47+
-destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' 2>&1 | tail -3
48+
```
49+
50+
Expected: `** BUILD SUCCEEDED **`
51+
52+
### Step 2: Pre-check grep
53+
54+
Find all occurrences of "Number Tag" labels and the `tagNumber*` identifiers in the codebase (NOT just Constants.swift). This reveals if any Swift file uses these strings directly, bypassing the Constants.swift pattern.
55+
56+
```bash
57+
# Swift files using "Number Tag" as string literal
58+
grep -rn "Number Tag" --include="*.swift" . | grep -v "\.build\|DerivedData"
59+
60+
# Swift files using "Tag Number" or "tag number" as string literal
61+
grep -rn "Tag Number\|tag number" --include="*.swift" . | grep -v "\.build\|DerivedData"
62+
63+
# Identifier usage
64+
grep -rn "shopSettingsManageNumberTagsLabel\|tagNumber\b\|addTagDescription\b\|tagNumberIsInvalid\b" \
65+
--include="*.swift" . | grep -v "\.build\|DerivedData"
66+
```
67+
68+
Save the output for reference. The rename in later steps must cover every match from these greps (except those in out-of-scope Constants.swift entries).
69+
70+
### Step 3: Edit Constants.swift (Category B — in-scope labels only)
71+
72+
In `NativeAppTemplate/Constants.swift`, apply these exact changes:
73+
74+
**Line 176** (identifier + value):
75+
```swift
76+
// BEFORE
77+
static let shopSettingsManageNumberTagsLabel = "Manage Number Tags"
78+
79+
// AFTER
80+
static let shopSettingsManageItemTagsLabel = "Manage Item Tags"
81+
```
82+
83+
**Line 188** (value only — identifier stays as `tagNumber` for now to minimize churn; will be reconsidered if needed):
84+
```swift
85+
// BEFORE
86+
static let tagNumber = "Tag Number"
87+
88+
// AFTER — value only changes; identifier may be updated if it doesn't break too many references
89+
static let tagNumber = "Name"
90+
```
91+
92+
**Note on line 188 identifier**: Renaming the identifier `tagNumber` → something else (e.g. `itemTagName`) would cascade into many files. Keeping the identifier and changing only the displayed string is safer for this small commit. The identifier rename can be tackled as a follow-up commit or during Phase 2 Part A's ItemTag refactor. Document this decision as a comment or in the commit message.
93+
94+
**Line 191** (value only):
95+
```swift
96+
// BEFORE
97+
static let addTagDescription = "Add a new number tag and start changing the tag status."
98+
99+
// AFTER
100+
static let addTagDescription = "Add a new item tag and start changing the tag status."
101+
```
102+
103+
**Line 194** (value only):
104+
```swift
105+
// BEFORE
106+
static let tagNumberIsInvalid = "Tag number is invalid."
107+
108+
// AFTER
109+
static let tagNumberIsInvalid = "Item tag name is invalid."
110+
```
111+
112+
**Do NOT change these** (Category A — out of scope, will be deleted in Phase 2):
113+
- Line 166: `swipeNumberTagBelow`
114+
- Line 168: `serverNumberTagsWebpageWillBeUpdated`
115+
- Line 170: `serverNumberTagsWebpage`
116+
- Line 177: `shopSettingsNumberTagsWebpageLabel`
117+
- Line 178: `resetNumberTagsDescription`
118+
- Line 179: `resetNumberTags`
119+
- Line 181: `// MARK: Number Tags Web Pages` (comment — delete with section in Phase 2)
120+
- Line 209: `completeScanHelp`
121+
- Line 210: `showTagInfoScanHelp`
122+
- Line 296: `shopReset`
123+
- Line 297: `shopResetError`
124+
- Line 396, 403, 404, 406: `onboardingDescription*` (queue flow)
125+
126+
### Step 4: Update callers of `shopSettingsManageNumberTagsLabel`
127+
128+
Since this identifier changed, all callers need updating. Grep and replace:
129+
130+
```bash
131+
grep -rn "shopSettingsManageNumberTagsLabel" --include="*.swift" . | grep -v "\.build\|DerivedData"
132+
```
133+
134+
For each match, replace `shopSettingsManageNumberTagsLabel` with `shopSettingsManageItemTagsLabel`.
135+
136+
Typical places to check:
137+
- `NativeAppTemplate/UI/Shop Settings/` (multiple Swift files likely reference this)
138+
- Any test files under `NativeAppTemplateTests/UI/Shop Settings/`
139+
140+
### Step 5: Verify no other "Number Tag" or "Tag Number" direct literals in scope
141+
142+
```bash
143+
# Any Swift file still contains "Number Tag" outside of Constants.swift's intentional kept strings
144+
grep -rn "Number Tag" --include="*.swift" . | grep -v "\.build\|DerivedData" | grep -v "Constants.swift"
145+
146+
# Any Swift file still contains "Tag Number" as a literal
147+
grep -rn "Tag Number" --include="*.swift" . | grep -v "\.build\|DerivedData"
148+
```
149+
150+
If matches are found, evaluate each:
151+
- If the context is queue-specific (scan flow, reset flow, NFC) → leave it (out of scope)
152+
- If the context is generic (ItemTag management) → update to "Item Tag" or "Name"
153+
154+
### Step 6: Build green
155+
156+
```bash
157+
xcodebuild build -scheme NativeAppTemplate \
158+
-destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' 2>&1 | tail -10
159+
```
160+
161+
Expected: `** BUILD SUCCEEDED **`
162+
163+
If build fails, most likely cause is an unresolved reference to the renamed identifier. Re-run Step 4's grep and fix missed callers.
164+
165+
### Step 7: Test green
166+
167+
```bash
168+
xcodebuild test -scheme NativeAppTemplate \
169+
-destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' 2>&1 | tail -20
170+
```
171+
172+
Expected: all tests pass. If any test asserts the old string values (e.g. `#expect(label == "Manage Number Tags")`), update the test to assert `"Manage Item Tags"`.
173+
174+
### Step 8: Commit
175+
176+
```bash
177+
git add -A
178+
git diff --cached --stat # Verify scope is what you expect
179+
git commit -m "Rename Number Tag labels to Item Tag for identifier alignment
180+
181+
- 'Manage Number Tags' → 'Manage Item Tags'
182+
- 'Tag Number' → 'Name' (aligns with ItemTag.name field after Phase 1 API refactor)
183+
- 'Add a new number tag...' → 'Add a new item tag...'
184+
- 'Tag number is invalid.' → 'Item tag name is invalid.'
185+
- Identifier: shopSettingsManageNumberTagsLabel → shopSettingsManageItemTagsLabel
186+
187+
Queue-specific strings (swipeNumberTagBelow, serverNumberTagsWebpage*,
188+
resetNumberTags*, onboardingDescription*) are intentionally kept for now;
189+
they will be deleted alongside NFC/scan/reset code in Phase 2 Part A."
190+
```
191+
192+
### Step 9: create PR
193+
194+
create PR
195+
196+
### Step 10: Verify v1-with-nfc is untouched
197+
198+
```bash
199+
git log v1-with-nfc --oneline -3
200+
```
201+
202+
The v1-with-nfc branch should NOT have this rename commit. Confirmed by the output showing only the original queue-template commits.
203+
204+
---
205+
206+
## Completion Checklist
207+
208+
- [ ] Baseline build was green before changes
209+
- [ ] Constants.swift: 4 values updated, 1 identifier renamed
210+
- [ ] All callers of `shopSettingsManageNumberTagsLabel` updated to new name
211+
- [ ] `grep -rn "Number Tag" --include="*.swift"` in main app code returns only out-of-scope Constants entries
212+
- [ ] `grep -rn "Tag Number" --include="*.swift"` returns only the `tagNumber` identifier (not string literals)
213+
- [ ] Build green after changes (`** BUILD SUCCEEDED **`)
214+
- [ ] Tests green
215+
- [ ] 1 commit to `main` with descriptive message
216+
- [ ] Pushed to `origin/main`
217+
- [ ] `v1-with-nfc` branch unchanged
218+
219+
---
220+
221+
## Common Pitfalls
222+
223+
### 1. Forgetting to update test fixtures
224+
225+
If any test file hard-codes `"Manage Number Tags"` as an expected label, the test will fail after the Constants value change. Update these to `"Manage Item Tags"`.
226+
227+
### 2. String catalog (.xcstrings) files
228+
229+
The audit showed no `.xcstrings` or `Localizable.strings` files in this repo — strings are directly in Constants.swift. If these are discovered during grep (e.g., in build artifacts), ignore them.
230+
231+
### 3. Identifier rename cascades
232+
233+
The Swift compiler will catch missed references immediately via build errors. If build fails after Step 4, read the error location and update that caller. Do not revert the change — fix forward.
234+
235+
### 4. Commit message length
236+
237+
The commit message above is descriptive. Feel free to shorten if preferred — but keeping the "Queue-specific strings kept for Phase 2" note helps future readers understand why some "Number Tag" strings remain.
238+
239+
### 5. Accidentally changing v1-with-nfc
240+
241+
If at any point you're unsure which branch you're on, run `git branch --show-current`. All work for this checklist must happen on `main`. Never run `git push origin v1-with-nfc` during this work.
242+
243+
---
244+
245+
## After this Pre-step
246+
247+
Proceed to Phase 2 Part A (to be written after this is merged):
248+
- Delete NFCManager.swift, QRCodeGenerator.swift, ScanView, ScanViewModel
249+
- Refactor ItemTag model (remove queueNumber, scanState, customerReadAt, alreadyCompleted; add description, position)
250+
- Remove NFC entries from Info.plist and entitlements
251+
- Remove queue-specific Constants entries (the Category A ones kept in this pre-step)
252+
- Update ItemTag UI to use new schema

0 commit comments

Comments
 (0)