no message

.cursor/skills/fp-mtms-version-checklist/SKILL.md

@@ -0,0 +1,643 @@
+---
+name: fp-mtms-version-checklist
+description: >-
+  Updates the FP-MTMS Version Programs and Functions Checklist Excel on each
+  developer's synced SharePoint folder. Use only when the user explicitly
+  invokes this skill or asks to update the FP-MTMS version control checklist,
+  page/program version sheet, or function version sheet.
+disable-model-invocation: true
+---
+
+# FP-MTMS Version Checklist Excel
+
+## Purpose
+
+Maintain the team **FP-MTMS System Version Control Checklist**: page/program
+level and function-level version history in a shared SharePoint Excel file.
+
+## Language
+
+Keep Excel **column headers** exactly as in the file (English).
+
+### 中英對照 (required for cell content)
+
+All written cell values must be **Traditional Chinese + English**
+(中英對照), using i18n labels where they exist.
+
+**Exception — do NOT bilingualize:**
+
+- `Functions in Page&Program` column **F — Name of Function within
+  Program** (English symbol + source path only; see Column F rule)
+- Version & Date fields (e.g. `v1.0.0 2026-07-14`)
+- Developed By (person name as-is)
+- Ref. No. (number)
+
+### Format
+
+**Short labels** (subsystem / page names):
+
+```text
+批號追溯 / Item Tracing
+倉庫管理 / Store Management
+```
+
+**Longer prose** (purpose, highlights, major changes): Chinese first,
+then English on the **next line**. For usage／呼叫來源, keep it on its
+own line(s) as well:
+
+```text
+工單提料執行頁面（/jodetail）。
+Job Order Pick Execution page (/jodetail).
+使用／呼叫來源：批號追溯（單據深連結開啟已完成提料紀錄）。
+Used / called from: Item Tracing (doc deep-link to open completed pick record).
+```
+
+**Major Changes** (Page col F / history I,L,O and Functions col I / history
+L,O,R) must also list **file + line range + short per-line explanation** —
+see **Major Changes: file, lines, explanation** below.
+
+Prefer EN/ZH pairs from `src/i18n/en/*` and `src/i18n/zh/*` for menu and
+feature terms. Enable Excel wrap text when a cell has multiple lines.
+
+## Excel path (per developer)
+
+Path varies by Windows user / OneDrive sync root. Resolve in this order:
+
+1. If the user provides a full path, use it.
+2. Else try under the user profile home:
+
+   `{USERPROFILE}/2Fi Business Solutions Limited/2Fi Business Solutions Limited - FP-MTMS VERSION CONTROL/FP-MTMS Version Programs and Functions Checklist v0.1.xlsx`
+
+3. If missing, search under `{USERPROFILE}` for
+   `FP-MTMS Version Programs and Functions Checklist v0.1.xlsx` (real `.xlsx` only).
+4. **Always confirm the resolved path with the user before writing.**
+
+Do not edit `.url` shortcuts or Downloads copies unless the user explicitly asks.
+
+Use `openpyxl` to read/write. If the file is locked (PermissionError), ask the
+user to close Excel / Excel Online sync lock, then retry.
+
+## Hard rule: preview first — do not interview column by column
+
+**Never** ask the user one question per cell / column.
+
+Instead:
+
+1. Infer all planned adds/updates from conversation context, git diff, PR,
+   feature description, and existing Excel rows.
+2. Before any write, show a **full preview** of every row that will be added or
+   changed (including history shifts).
+3. Ask **one** confirmation: whether this preview is correct (yes / no / what
+   to fix). Prefer the Ask Questions tool when available; otherwise ask once
+   in chat.
+4. Only after explicit approval, write with `openpyxl` and save.
+
+If the preview is wrong, adjust and show a **revised preview**; do not write
+until approved.
+
+If critical facts are truly unknown (e.g. version number or developer name
+cannot be inferred), ask at most a short batch of missing items — never walk
+the sheet column by column.
+
+## Pre-check: matching program / feature must exist
+
+Before drafting or writing any row:
+
+1. Open the workbook and search both sheets for the target
+   **System Page / Program Name** (and for Functions sheet, also
+   **Name of Function within Program**).
+2. Match on existing rows when the program/page already exists.
+3. If updating a function: the parent page/program should already exist on
+   `Page&Program Name` (or be included in the same preview as a new page row).
+4. If nothing matches and the user intends a **new** program or function, say so
+   clearly in the preview as `NEW ROW`.
+5. Do **not** invent duplicate rows for the same page + same function.
+6. Different **功能** (distinct functions) → **different Ref. No. rows**, even
+   under the same System Page / Program Name.
+
+## History shift (required on every update)
+
+Each page or function keeps **Latest** plus up to **3 previous** history slots
+(1st, 2nd, 3rd). On every new change to an existing row, **push history
+rightward** before writing the new Latest:
+
+| Before write | After shift |
+|--------------|-------------|
+| Latest       | → 1st previous |
+| 1st previous | → 2nd previous |
+| 2nd previous | → 3rd previous |
+| 3rd previous | → **deleted** (dropped) |
+
+Then write the new change into **Latest** (version/date, highlights, Developed By).
+
+### Page&Program Name — fields that shift together
+
+Treat each “slot” as a triple:
+
+- **Latest**: D (Version & Date), F (Major Changes), G (Developed By)
+- **1st**: H, I, J
+- **2nd**: K, L, M
+- **3rd**: N, O, P
+
+Shift: `(D,F,G) → (H,I,J) → (K,L,M) → (N,O,P)` then drop old 3rd; write new into D/F/G.
+Leave identity columns A–C and purpose E unchanged unless the user asked to
+change them (purpose may be refreshed if the preview says so).
+
+### Functions in Page&Program — fields that shift together
+
+- **Latest**: H (Function Version & Date), I (Major Changes), J (Developed By)
+- **1st**: K, L, M
+- **2nd**: N, O, P
+- **3rd**: Q, R, S
+
+Shift: `(H,I,J) → (K,L,M) → (N,O,P) → (Q,R,S)` then drop old 3rd; write new into H/I/J.
+Leave A–G (Ref, subsystem, page, page version/purpose, function name/highlight)
+unchanged unless the preview explicitly updates them.
+
+Always show the shift in the preview (old Latest → new 1st, etc.).
+
+### Function history only when that function changed (required)
+
+**Do not** push or invent a Functions-sheet history slot for a commit / release
+that did **not** change the symbols listed in column F for that row.
+
+- **Page&Program Name** may still advance Latest / history for a page-level
+  release (e.g. backend-only fix under the same page).
+- **Functions in Page&Program**: shift H→K→N→Q **only** when this row’s
+  function(s) actually changed (diff touches the verified F symbol(s) / paths).
+- If a commit updates the **page** but not this function:
+  - You may refresh column **D** (Latest Page Version) to match the page row.
+  - Leave **H/I/J** and previous function history **unchanged**.
+  - Do **not** write filler Latest/history text such as「頁面版本對齊；本功能無程式變更」
+    / “Page version align; no UI change this release”.
+- When mapping several commits into history for a **new** function row: include
+  only commits that changed that function; leave unused 1st/2nd/3rd slots empty.
+  Different function rows under the same page may have **different** Latest
+  versions and history depths.
+
+Example: page Latest = v1.0.3 (backend TRF fix). Frontend transfer UI row last
+changed at v1.0.2 → keep function H = v1.0.2; optional D = v1.0.3; no fake
+v1.0.3 function history slot.
+
+### Major Changes: file, lines, explanation (required)
+
+For every **Major Changes Highlights** cell written into Excel (Page sheet
+Latest F and history I/L/O; Functions sheet Latest I and history L/O/R),
+include concrete code locations from the commit / diff — not only a summary
+sentence.
+
+**Required content (中英對照 for prose; paths/lines stay as-is):**
+
+1. **Summary** — short ZH then EN (what the release did).
+2. **Per changed file** — repo-relative path.
+3. **Line range(s)** — current file line numbers after the change (prefer
+   `start–end`; single line OK). Re-resolve with `git show` / Read / Grep;
+   do not guess.
+4. **Short explanation by line/range** — what that hunk does (ZH then EN, or
+   one ZH+EN pair per bullet).
+
+**Cell layout example:**
+
+```text
+轉倉出庫批次 ledger 餘額鏈結修正。
+TRF stock-out batch ledger balance chaining fix.
+StockOutLineService.kt
+  L1518: ledger 查詢改為 findFirstByItemIdAndDeletedFalseOrderByDateDescIdDesc。
+  L1518: ledger lookup → findFirstByItemIdAndDeletedFalseOrderByDateDescIdDesc.
+  L2318–2347 (createStockOutBatch): 同 batch 多行依 runningLedgerBalance 扣帳，不再每次用 onHandQty。
+  L2318–2347 (createStockOutBatch): chain per-item running ledger balance within a batch instead of onHandQty each line.
+StockInLineService.kt
+  L269 / L312: assignLotNo / assignLotNoForJo 改為 open fun（無邏輯變更）。
+  L269 / L312: assignLotNo / assignLotNoForJo marked open (no logic change).
+```
+
+**Rules:**
+
+- Fact-check path + line numbers against the repo at write time (lines drift;
+  re-check before save).
+- Group by file; under each file, one bullet per meaningful hunk / line range.
+- Prefer the member / symbol name in the explanation when helpful
+  (e.g. `createStockOutBatch`, `assignLotNo`).
+- If many files: keep bullets short; still list each touched path that belongs
+  to this row (Functions row → only files/symbols in column F, plus closely
+  related hunks in those files for this change).
+- Page-sheet Major Changes may summarize all files for that page release;
+  Functions-sheet Major Changes stay scoped to that function row’s F symbols
+  and their files.
+- Show the same file/line bullets in the **preview** before write.
+- Pure i18n-only or one-liner UI copy changes: still cite file + line(s)
+  (e.g. `InventoryLotLineTable.tsx L508–518: success message by API code`).
+
+## Batch updates
+
+Many rows may change in one invocation (multiple pages and/or functions).
+
+- Build **one combined preview** covering all affected rows.
+- One approval covers the whole batch.
+- Still one Ref. No. row per distinct 功能 / function.
+
+## Sheets and columns
+
+Data starts at **row 5** (rows 1–4 are title/headers).
+
+### Sheet: `Page&Program Name`
+
+| Col | Header |
+|-----|--------|
+| A | Ref. No. |
+| B | Name of Subsystem / Module / Menu Selection |
+| C | System Page / Program Name |
+| D | Latest Page Version & Date |
+| E | Page Purpose Highlights |
+| F | Major Changes Highlights |
+| G | Developed By |
+| H | 1st Previous Page Version & Date |
+| I | 1st Major Changes Highlights |
+| J | Developed By |
+| K | 2nd Previous Page Version & Date |
+| L | 2nd Major Changes Highlights |
+| M | Developed By |
+| N | 3rd Previous Page Version & Date |
+| O | 3rd Major Changes Highlights |
+| P | Developed By |
+
+### Sheet: `Functions in Page&Program`
+
+| Col | Header |
+|-----|--------|
+| A | Ref. No. |
+| B | Name of Subsystem / Module / Menu Selection |
+| C | System Page / Program Name |
+| D | Latest Page Version & Date |
+| E | Page Purpose Highlights |
+| F | Name of Function within Program |
+| G | Functions Highlight |
+| H | Latest Function Version & Date |
+| I | Major Changes Highlights |
+| J | Developed By |
+| K | 1st Previous Page Version & Date |
+| L | 1st Major Changes Highlights |
+| M | Developed By |
+| N | 2nd Previous Page Version & Date |
+| O | 2nd Major Changes Highlights |
+| P | Developed By |
+| Q | 3rd Previous Page Version & Date |
+| R | 3rd Major Changes Highlights |
+| S | Developed By |
+
+#### Column F — English symbol + source file (required)
+
+**Name of Function within Program (F)** must use the real English
+identifier from code (component / class / function / endpoint name),
+**and** state which file(s) it comes from. Do **not** put only a
+localized UI label in F.
+
+Format:
+
+```text
+<EnglishSymbol> — <repo-relative path>
+```
+
+Examples:
+
+- `ItemTracingScanBar — src/components/ItemTracing/ItemTracingScanBar.tsx`
+- `GoodPickExecutionWorkbenchRecord — src/components/DoWorkbench/GoodPickExecutionWorkbenchRecord.tsx`
+
+If one checklist function spans multiple primary files, put **each**
+symbol + path on its **own new line** (do not join with `; ` on one line):
+
+```text
+ItemTracingSummary — src/components/ItemTracing/ItemTracingSummary.tsx
+ItemTracingLocations — src/components/ItemTracing/ItemTracingLocations.tsx
+```
+##### Service / controller / class files — also list member functions
+
+When the primary symbol is a **service, controller, or other class**
+(not a React page component), F must also name the **member function(s)**
+that were added or changed — not only the class name.
+
+Put **each class + its methods + its path on its own line** (Excel `\n`,
+wrap text). Do not squeeze multiple files onto one line with `; `.
+
+Format (one file per line):
+
+```text
+<ClassName>.<fun1> / .<fun2> — <path-to-that-file>
+```
+
+Multi-file example:
+
+```text
+ItemLotTraceService.trace / .traceLocation — src/main/java/com/ffii/fpsms/modules/stock/service/ItemLotTraceService.kt
+InventoryLotLineController.traceLot / .traceLocation — src/main/java/com/ffii/fpsms/modules/stock/web/InventoryLotLineController.kt
+```
+
+```text
+PickOrderLifecycleController.getLifecycle / .getLifecycleByCode — src/main/java/.../PickOrderLifecycleController.kt
+PickOrderLifecycleService.getLifecycle / .getLifecycleByCode — src/main/java/.../PickOrderLifecycleService.kt
+```
+
+For multi-file **component** rows, also one path per line:
+
+```text
+ItemTracingSummary — src/components/ItemTracing/ItemTracingSummary.tsx
+ItemTracingLocations — src/components/ItemTracing/ItemTracingLocations.tsx
+```
+
+Fact-check each listed member function exists in that file (same casing).
+If only one method changed, list that one method. Do not cite a class
+without its relevant `fun` / method names when the change is in a
+`*Service` / `*Controller` (or similar) file.
+**Functions Highlight (G)** and **Major Changes (I)** must be 中英對照
+(Chinese then English on the next line). Prefer i18n terms. Page /
+subsystem names (B/C) use `中文 / English`.
+
+#### Column E — Page Purpose + where the function is used (required)
+
+On **Functions in Page&Program**, **Page Purpose Highlights (E)** must
+include:
+
+1. The owning page purpose (what page C is for), **and**
+2. **Where this function is used / called from** — especially when the
+   caller is a **different** page than column C.
+
+Owning page (C) = where the code/feature primarily lives.
+Usage location = which page(s) invoke, deep-link into, or depend on it.
+
+Examples:
+
+- Function lives on `工單提料` but is opened from Item Tracing doc links:
+
+  ```text
+  工單提料執行頁面（/jodetail）。
+  Job Order Pick Execution page (/jodetail).
+  使用／呼叫來源：批號追溯（單據深連結開啟已完成提料紀錄）。
+  Used / called from: Item Tracing (doc deep-link to open completed pick record).
+  ```
+
+- Function lives on `提料單` (lifecycle API) but is consumed for tracing:
+
+  ```text
+  提料單管理。
+  Pick Order management.
+  使用／呼叫來源：批號追溯（追溯流程／單據生命週期查詢）。
+  Used / called from: Item Tracing (trace flow / document lifecycle query).
+  ```
+
+- Function lives on `成品出倉` but is deep-linked from tracing:
+
+  ```text
+  成品出倉（DO Workbench）揀貨與紀錄作業。
+  DO Workbench pick execution and records.
+  使用／呼叫來源：批號追溯（單據深連結開啟成品出倉紀錄）。
+  Used / called from: Item Tracing (doc deep-link to open DO Workbench record).
+  ```
+
+- Function lives on and is only used by the same page (e.g. 批號追溯):
+
+  ```text
+  …頁面目的（中文）…
+  …page purpose (English)…
+  使用／呼叫來源：本頁（批號追溯 / Item Tracing）。
+  Used / called from: this page (批號追溯 / Item Tracing).
+  ```
+
+Put **使用／呼叫來源** (and its English line) on **new lines** after the
+page-purpose ZH/EN pair. Do not run usage on the same line as purpose.
+
+When inferring usage, fact-check callers (imports, links, API consumers)
+from the change/diff. Do not invent a caller. If usage is only the owning
+page, say `本頁（<page>）`. If multiple callers, list them (i18n names).
+
+Do **not** leave E as only the generic page blurb when the function was
+added/changed for another page’s flow (e.g. refs that support 批號追溯
+but sit under 工單提料／提料單／成品出倉).
+
+#### Fact-check column F before preview (required)
+
+Never invent a symbol or path. For **every** Functions-sheet row in the
+preview (new or updated), verify against the real repos:
+
+1. **Path exists** — each repo-relative path resolves under the correct
+   workspace (`FPSMS-frontend` or `FPSMS-backend`). Prefer `Glob` / `Read`
+   / `Grep`; do not guess.
+2. **Symbol is in that file** — the English symbol must actually be defined
+   or exported in the cited file (e.g. `const ItemTracingScanBar`,
+   `export default ItemTracingScanBar`, `open class ItemLotTraceService`,
+   `fun traceLot`, `class PickOrderLifecycleController`). Match casing
+   exactly as in code (`CompleteJobOrderRecord`, not `completeJobOrderRecord`).
+   For service/controller rows, also verify each listed **member function**
+   (e.g. `trace`, `traceLocation`, `getLifecycle`) exists in that file.
+3. **Multi-path rows** — each symbol + path must be on its **own line**:
+   - Every line’s symbol must be defined in that line’s file.
+   - Example OK:
+
+     ```text
+     ItemTracingSummary — …/ItemTracingSummary.tsx
+     ItemTracingLocations — …/ItemTracingLocations.tsx
+     ```
+
+   - Do not join multiple files with `; ` on one line.
+4. **Wrong location** — if the symbol lives elsewhere, correct the path to
+   the real file; do not keep a convenient-but-false path.
+5. **Not found** — if the file or symbol cannot be verified, do **not** put
+   it in F. Omit the row or ask the user; never write an unverified F.
+
+In the preview, mark verified rows (optional short note), e.g.
+`F verified: symbol+path OK`. If any F failed fact-check, fix before asking
+for confirmation.
+
+## Preview format (required before save)
+
+Show a clear preview, for example:
+
+```text
+Excel: <resolved path>
+Sheet: Functions in Page&Program
+
+Row 12 (UPDATE existing | Ref 7 | Page: 批號追溯 | Function: ItemTracingFlowGraphSearch — src/components/ItemTracing/ItemTracingFlowGraphSearch.tsx)
+  History shift:
+    old Latest (H/I/J) → 1st
+    old 1st → 2nd
+    old 2nd → 3rd
+    old 3rd → DROP
+  New Latest:
+    H: v1.2.0 2026-07-14
+    I: 新增流程圖節點搜尋。
+    Add flow-graph node search.
+    ItemTracingFlowGraphSearch.tsx
+      L42–88: 搜尋框與節點高亮。
+      L42–88: search box and node highlight.
+    J: <developer>
+
+Row NEW (append | next Ref 15 | Page: 批號追溯 / Item Tracing | Function: ItemTracingScanBar — src/components/ItemTracing/ItemTracingScanBar.tsx)
+  A: 15
+  B: 倉庫管理 / Store Management
+  C: 批號追溯 / Item Tracing
+  E: …頁面目的（中文）…
+  …page purpose (English)…
+  使用／呼叫來源：本頁（批號追溯 / Item Tracing）。
+  Used / called from: this page (批號追溯 / Item Tracing).
+  F: ItemTracingScanBar — src/components/ItemTracing/ItemTracingScanBar.tsx
+  G: 相機掃碼／手動查詢
+  Camera scan / manual search
+  ...
+  H/I/J: <new latest>
+  history slots: empty
+
+Row NEW (… | Page: 工單提料 / Job Order Pick Execution | Function: CompleteJobOrderRecord — …)
+  C: 工單提料 / Job Order Pick Execution
+  E: 工單提料執行頁面（/jodetail）。
+  Job Order Pick Execution page (/jodetail).
+  使用／呼叫來源：批號追溯（單據深連結）。
+  Used / called from: Item Tracing (doc deep-link).
+  F: CompleteJobOrderRecord — src/components/Jodetail/completeJobOrderRecord.tsx
+  JodetailSearch — src/components/Jodetail/JodetailSearch.tsx
+  …
+
+Confirm: Is this preview correct? [Yes / No — tell me what to change]
+```
+
+For page-sheet rows, use the same style with D/F/G and H–P history.
+
+## Workflow
+
+1. Confirm Excel path exists (and is writable when saving).
+2. Infer target sheets and rows from the user’s change description / diff.
+3. **Pre-check** existing program/page/function rows in Excel.
+4. For each Functions row: **fact-check** English symbol + every source path
+   against the codebase (see Fact-check column F). Correct or drop failures.
+5. For each Functions row: set **E** with page purpose **and** usage／呼叫來源
+   (owning page vs caller page; see Column E rule).
+6. For each existing match: plan history shift + new Latest values
+   (**only** shift function history when that function’s F symbols changed).
+7. For each Major Changes cell (page + functions, Latest and any filled history
+   slots): resolve **file path + line range(s) + short per-hunk explanation**
+   from git diff / current sources (see Major Changes: file, lines, explanation).
+8. For each new function/page: plan a new Ref. No. row (next integer after max used).
+9. Present the **full preview** (verified F + file/line Major Changes) → ask once
+   if correct.
+10. On approval: apply shifts + writes with `openpyxl`, save, report sheet names,
+    row numbers, Ref. Nos., and key Latest fields.
+11. **Code comments** — for every Functions-sheet symbol that was added or
+    updated, add or refresh the FP-MTMS checklist comment on that
+    component / class member (see Code comments rule). Include this in the
+    preview (list of files/symbols that will get comments).
+12. Note that OneDrive may take a few seconds to sync; refresh Excel Online if open.
+
+## Code comments on every updated function (required)
+
+After the user approves the checklist preview (or as part of the same
+approved batch), **add or update a source comment** on every function /
+component listed in column F for each affected Functions-sheet row.
+
+### Comment contents (required fields)
+
+Must include:
+
+1. **Ref. No.** — Functions sheet Ref. No. for that row
+2. **Version** — Latest Function Version (column H), e.g. `v1.0.0`
+3. **Update date** — the date from column H, e.g. `2026-07-14`
+
+### Canonical format
+
+Parse column H `vX.Y.Z YYYY-MM-DD` into version + date.
+
+**TypeScript / TSX** (JSDoc immediately above the component / export /
+function):
+
+```ts
+/** FP-MTMS Version Checklist | Functions Ref. No. 1 | v1.0.0 | 2026-07-14 */
+const ItemTracingScanBar: React.FC<ScanBarProps> = (...) => {
+```
+
+**Kotlin** (KDoc immediately above the `fun` / class member):
+
+```kotlin
+/** FP-MTMS Version Checklist | Functions Ref. No. 7 | v1.0.0 | 2026-07-14 */
+open fun trace(...): ItemLotTraceResponse = ...
+```
+
+If a KDoc/JSDoc already exists, **prepend or merge** this checklist line
+into it (do not delete useful existing documentation). Prefer keeping the
+checklist line as the first line of the block:
+
+```kotlin
+/**
+ * FP-MTMS Version Checklist | Functions Ref. No. 7 | v1.0.0 | 2026-07-14
+ * Lazy-load: returns the full location-scoped trace block...
+ */
+```
+
+### Placement rules
+
+- **React component**: above the primary `const ComponentName` / `export
+  default` that matches column F.
+- **Service / controller**: above **each** listed member function
+  (e.g. both `trace` and `traceLocation`).
+- Multi-line F (one symbol per line): comment **each** symbol in its file.
+- On later checklist updates to the same row: **replace** the old Ref/version/date
+  in the comment with the new Latest values (do not stack duplicate checklist lines).
+
+### Preview
+
+The Excel preview must also list planned comment updates, e.g.:
+
+```text
+Code comments to add/update:
+  Ref 7 → ItemLotTraceService.trace / .traceLocation (v1.0.0 | 2026-07-14)
+  Ref 1 → ItemTracingScanBar (v1.0.0 | 2026-07-14)
+```
+
+Only edit comments after preview approval (same gate as Excel write), unless
+the user explicitly asks to sync comments only.
+
+## Inference hints (for filling the preview)
+
+- **Version & Date**: next patch/semver from conversation/git if known; else
+  `vX.Y.Z YYYY-MM-DD` with today’s date.
+- **Developed By**: `git config user.name` or chat context.
+- **Purpose / Changes / Function highlight**: 中英對照; short bullets from
+  recent PR/diff; prefer i18n terms.
+- **Major Changes (Page F / Functions I and history slots)**: summary ZH/EN
+  **plus** each changed file, line range(s), and short per-hunk explanation
+  (see Major Changes: file, lines, explanation). Resolve lines from git diff
+  + current file; do not omit locations.
+- **Subsystem / Page names**: `中文 / English` from i18n EN+ZH.
+- **Function name (col F)**: English code symbol + source file path only
+  (no 中英對照). **Fact-check** symbol+path before preview.
+- **Page Purpose (E)**: 中英對照 + usage／呼叫來源 lines (ZH then EN).
+- **Ref. No.**: for new rows, next integer after the last used Ref. No. on that sheet.
+- Prefer updating an existing row over creating a duplicate when page +
+  English function symbol (and file) match.
+
+## Do not
+
+- Ask the user to fill cells one column at a time
+- Save without an approved preview
+- Skip history shift when updating an existing Latest
+- Push or invent **function** history (H–S) for a commit that did not change
+  that row’s column F symbols — no “page align / no code change” filler slots
+- Write Major Changes as summary-only without **file path + line range(s) +
+  short per-hunk explanation** (Page F / Functions I and matching history cols)
+- Write Chinese-only or English-only prose in bilingual-required columns
+  (everything except Function name F, versions, Developed By, Ref. No., and
+  the path/line tokens inside Major Changes)
+- Put only a Chinese UI label in **Name of Function within Program** without
+  the English symbol and source file
+- Bilingualize column F (keep symbol + path English-only)
+- Omit usage／呼叫來源 from **Page Purpose Highlights (E)** when the function
+  is invoked from another page (e.g. 批號追溯 deep-link into 工單提料)
+- Cite a `*Service` / `*Controller` class in F without its relevant member
+  function names (e.g. write `ItemLotTraceService.trace / .traceLocation`,
+  not only `ItemLotTraceService`)
+- Write an F value whose symbol or path was not verified in the codebase
+- Guess file paths or rename symbols to “look right” without opening the file
+- Put two different 功能 on the same Ref. No. row
+- Create a function row when the parent program/page was neither found nor
+  included in the same approved preview as a new page row
+- Clear history columns without showing that drop in the preview
+- Skip adding/updating FP-MTMS checklist comments on code for Functions rows
+  that were just written (must include Ref. No., version, and update date)
+- Commit the Excel file to git
+- Edit cloud URLs / `.url` files as if they were workbooks