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

---
name: fp-mtms-version-checklist
description: >-
  Updates the FP-MTMS Version Programs and Functions Checklist Excel on each
  developer's synced SharePoint folder. Overflow beyond Latest+3 previous
  versions is appended to the Archive long-table Excel. Use only when the user
  explicitly invokes this skill or asks to update the FP-MTMS version control
  checklist, page/program version sheet, function version sheet, or archive.
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 **G — Name of Function within
  Program** (English symbol + source path only; see Column G 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 J / history
M,P,S) 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.

## Excel formatting (required on every write)

When writing with `openpyxl`, apply formatting so cells stay readable:

1. **Wrap text** — enable wrap on every multi-line cell you write (Purpose,
   Major Changes, Function name with multiple paths, Highlights). Prefer
   `Alignment(wrap_text=True, vertical="top")`.
2. **Line breaks** — use real Excel newlines (`\n`) between ZH/EN pairs and
   between file / line bullets; do not stuff everything onto one long line.
3. **Row height** — after writing multi-line cells, set a reasonable row
   height (or leave Excel auto-fit) so wrapped text is visible; do not leave
   multi-line content in a single-line-tall row if the sheet already uses
   taller history rows.
4. **Do not break headers** — never rename, reorder, or delete existing header
   labels; only fill data cells (and Archive append columns as defined).
5. **Match existing style** — when updating a row, keep the same wrap/alignment
   pattern as neighbouring filled cells on that sheet.
6. **Archive** — same wrap rules as main; no extra “Source” or helper columns.

## 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.**

### Archive Excel path

Same folder as the main checklist. Default:

`{USERPROFILE}/2Fi Business Solutions Limited/2Fi Business Solutions Limited - FP-MTMS VERSION CONTROL/FP-MTMS Version Programs and Functions Checklist v0.1 - Archive.xlsx`

If the user provides an archive path, use it. Confirm both main and archive
paths before writing. Do not edit `.url` shortcuts or Downloads copies unless
the user explicitly asks.

Use `openpyxl` to read/write. If either 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 and any Archive long-table appends).
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).
   Set **Page Ref. No. (B)** to that page row’s Ref. No.
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 | → **Archive Excel** (append long-table row; then clear 3rd on main) |

Then write the new change into **Latest** (version/date, highlights, Developed By).

If the old 3rd previous slot is **empty**, skip archive append for that shift.

### 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 **archive** old 3rd
(N/O/P) to the Archive Excel long table if filled; clear N/O/P on main; 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**: I (Function Version & Date), J (Major Changes), K (Developed By)
- **1st**: L, M, N
- **2nd**: O, P, Q
- **3rd**: R, S, T

Shift: `(I,J,K) → (L,M,N) → (O,P,Q) → (R,S,T)` then **archive** old 3rd
(R/S/T) to the Archive Excel long table if filled; clear R/S/T on main; write
new into I/J/K.
Leave A–H (Ref, **Page Ref. No.**, subsystem, page, page version/purpose,
function name/highlight) unchanged unless the preview explicitly updates them.

Always show the shift **and any archive appends** in the preview (old Latest →
new 1st, old 3rd → Archive, etc.).

#### Column B — Page Ref. No. (required)

**Page Ref. No. (B)** on every Functions row must equal the parent row’s
**Ref. No. (A)** on sheet `Page&Program Name`.

Rules:

1. Resolve the parent by matching **System Page / Program Name** (and
   subsystem when needed) on the Page sheet; use that page row’s A.
2. Never leave B blank on a Functions data row.
3. Do **not** invent a Page Ref that has no matching Page sheet row (unless
   that page row is included in the same approved preview as NEW).
4. Multiple function rows under the same page share the **same** Page Ref. No.
5. Function **Ref. No. (A)** stays independent (one per 功能 row).
6. Preview must show `Page Ref. No. = <n> → Page sheet Ref <n> (<page name>)`.

Page sheet columns A–P are unchanged by this field (Page sheet has no
Page Ref column).

## Archive Excel — long table (required on 3rd overflow)

When a filled **3rd previous** is pushed off the main checklist, **append one
row** to the Archive workbook (never overwrite existing archive rows).

Data starts at **row 5** (rows 1–3 title/notes, row 4 headers).

### Sheet: `Page&Program Name` (archive)

| Col | Header |
|-----|--------|
| A | Ref. No. |
| B | Name of Subsystem / Module / Menu Selection |
| C | System Page / Program Name |
| D | Version & Date |
| E | Major Changes Highlights |
| F | Developed By |
| G | Archived At |

Map from main page row 3rd slot: A←A, B←B, C←C, D←N, E←O, F←P.
`Archived At` = today's date (`YYYY-MM-DD`).
Do **not** add a Source column.

### Sheet: `Functions in Page&Program` (archive)

| Col | Header |
|-----|--------|
| A | Ref. No. |
| B | Page Ref. No. |
| C | Name of Subsystem / Module / Menu Selection |
| D | System Page / Program Name |
| E | Name of Function within Program |
| F | Version & Date |
| G | Major Changes Highlights |
| H | Developed By |
| I | Archived At |

Map from main functions row 3rd slot:
A←A, B←B (Page Ref. No.), C←C, D←D, E←G, F←R, G←S, H←T;
`Archived At` (I) = today.
Always copy **Page Ref. No.** so archive rows stay linked to the parent page.
Do **not** add a Source column.

### Archive write rules

1. **Append only** — find the next empty data row (after last non-empty row ≥ 5).
2. Keep **中英對照** and Major Changes content exactly as they were on main 3rd.
3. Do **not** invent archive rows for empty 3rd slots.
4. Do **not** edit older archive rows.
5. Write archive **before or in the same approved batch as** the main shift; if
   archive save fails (lock), do not leave main half-shifted — abort and ask the
   user to close the file, then retry the whole approved batch.
6. Never commit either Excel file to git.

### 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 G 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 I→L→O→R **only** when this row’s
  function(s) actually changed (diff touches the verified G symbol(s) / paths).
- If a commit updates the **page** but not this function:
  - You may refresh column **E** (Latest Page Version) to match the page row.
  - Leave **I/J/K** 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 I = v1.0.2; optional E = 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 J and history M/P/S),
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 G, 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 G 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 | Page Ref. No. |
| C | Name of Subsystem / Module / Menu Selection |
| D | System Page / Program Name |
| E | Latest Page Version & Date |
| F | Page Purpose Highlights |
| G | Name of Function within Program |
| H | Functions Highlight |
| I | Latest Function Version & Date |
| J | Major Changes Highlights |
| K | Developed By |
| L | 1st Previous Page Version & Date |
| M | 1st Major Changes Highlights |
| N | Developed By |
| O | 2nd Previous Page Version & Date |
| P | 2nd Major Changes Highlights |
| Q | Developed By |
| R | 3rd Previous Page Version & Date |
| S | 3rd Major Changes Highlights |
| T | Developed By |

(Main workbook may also show helper note columns such as U `Archive`; do
**not** require filling them unless the user asks. Page Ref. No. is the
required parent link.)

#### Column B — Page Ref. No. (see also history section)

Must point at the parent `Page&Program Name` row’s **Ref. No. (A)**. Required
on every Functions data row (main and archive).

#### Column G — English symbol + source file (required)

**Name of Function within Program (G)** 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 G.

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), G 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 (H)** and **Major Changes (J)** must be 中英對照
(Chinese then English on the next line). Prefer i18n terms. Page /
subsystem names (C/D) use `中文 / English`.

#### Column F — Page Purpose + where the function is used (required)

On **Functions in Page&Program**, **Page Purpose Highlights (F)** 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 F 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 G 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 G. Omit the row or ask the user; never write an unverified G.

In the preview, mark verified rows (optional short note), e.g.
`G verified: symbol+path OK`. If any G failed fact-check, fix before asking
for confirmation.

## Preview format (required before save)

Show a clear preview, for example:

```text
Excel: <resolved main path>
Archive: <resolved archive path>
Sheet: Functions in Page&Program

Row 12 (UPDATE existing | Ref 7 | Page Ref 3 → 批號追溯 / Item Tracing | Function: ItemTracingFlowGraphSearch — src/components/ItemTracing/ItemTracingFlowGraphSearch.tsx)
  History shift:
    old Latest (I/J/K) → 1st
    old 1st → 2nd
    old 2nd → 3rd
    old 3rd → ARCHIVE (append)
  Archive append (Functions in Page&Program):
    A: 7
    B: 3
    C: 倉庫管理 / Store Management
    D: 批號追溯 / Item Tracing
    E: ItemTracingFlowGraphSearch — src/components/ItemTracing/ItemTracingFlowGraphSearch.tsx
    F: <old 3rd version & date>
    G: <old 3rd major changes>
    H: <old 3rd developed by>
    I: 2026-07-16
  New Latest:
    I: v1.2.0 2026-07-14
    J: 新增流程圖節點搜尋。
    Add flow-graph node search.
    ItemTracingFlowGraphSearch.tsx
      L42–88: 搜尋框與節點高亮。
      L42–88: search box and node highlight.
    K: <developer>

Row NEW (append | next Ref 15 | Page Ref 3 → 批號追溯 / Item Tracing | Function: ItemTracingScanBar — src/components/ItemTracing/ItemTracingScanBar.tsx)
  A: 15
  B: 3
  C: 倉庫管理 / Store Management
  D: 批號追溯 / Item Tracing
  F: …頁面目的（中文）…
  …page purpose (English)…
  使用／呼叫來源：本頁（批號追溯 / Item Tracing）。
  Used / called from: this page (批號追溯 / Item Tracing).
  G: ItemTracingScanBar — src/components/ItemTracing/ItemTracingScanBar.tsx
  H: 相機掃碼／手動查詢
  Camera scan / manual search
  ...
  I/J/K: <new latest>
  history slots: empty

Row NEW (… | Page Ref <n> → 工單提料 / Job Order Pick Execution | Function: CompleteJobOrderRecord — …)
  B: <page Ref. No.>
  D: 工單提料 / Job Order Pick Execution
  F: 工單提料執行頁面（/jodetail）。
  Job Order Pick Execution page (/jodetail).
  使用／呼叫來源：批號追溯（單據深連結）。
  Used / called from: Item Tracing (doc deep-link).
  G: 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 **main and archive** Excel paths exist (and are 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 G). Correct or drop failures.
   Also set / verify **Page Ref. No. (B)** against the parent Page sheet Ref.
5. For each Functions row: set **F** with page purpose **and** usage／呼叫來源
   (owning page vs caller page; see Column F rule).
6. For each existing match: plan history shift + new Latest values
   (**only** shift function history when that function’s G symbols changed).
   If old 3rd is filled, plan an **Archive long-table append**.
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 G + Page Ref + file/line Major Changes +
   archive appends) → ask once if correct.
10. On approval: with `openpyxl`, **append archive rows first** (if any), then
    apply main shifts + writes; apply **Excel formatting** (wrap text /
    newlines); save both workbooks; report sheet names, row numbers,
    Ref. Nos., Page Ref. Nos., archive rows appended, 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 G 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 I), e.g. `v1.0.0`
3. **Update date** — the date from column I, e.g. `2026-07-14`

### Canonical format

Parse column I `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 G.
- **Service / controller**: above **each** listed member function
  (e.g. both `trace` and `traceLocation`).
- Multi-line G (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 J 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 G)**: English code symbol + source file path only
  (no 中英對照). **Fact-check** symbol+path before preview.
- **Page Purpose (F)**: 中英對照 + usage／呼叫來源 lines (ZH then EN).
- **Page Ref. No. (B)**: parent Page sheet Ref. No. for column D’s page.
- **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
- Drop a filled **3rd previous** without appending it to the Archive long table
- Add or fill an Archive **Source** column (removed; do not reintroduce)
- Overwrite or edit existing Archive rows (append only)
- Skip Excel formatting (wrap text / newlines) on multi-line cells you write
- Push or invent **function** history (I–T) for a commit that did not change
  that row’s column G 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 J and matching history cols)
- Write Chinese-only or English-only prose in bilingual-required columns
  (everything except Function name G, versions, Developed By, Ref. No., Page 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 G (keep symbol + path English-only)
- Omit usage／呼叫來源 from **Page Purpose Highlights (F)** when the function
  is invoked from another page (e.g. 批號追溯 deep-link into 工單提料)
- Cite a `*Service` / `*Controller` class in G without its relevant member
  function names (e.g. write `ItemLotTraceService.trace / .traceLocation`,
  not only `ItemLotTraceService`)
- Write a G value whose symbol or path was not verified in the codebase
- Leave **Page Ref. No. (B)** blank or pointing at a non-existent Page row
- 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 shift/archive 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