26 KiB

Raw Blame History

name	description	disable-model-invocation
fp-mtms-version-checklist	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.	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):

批號追溯 / 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:

工單提料執行頁面（/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:

If the user provides a full path, use it.
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
If missing, search under {USERPROFILE} for FP-MTMS Version Programs and Functions Checklist v0.1.xlsx (real .xlsx only).
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:

Infer all planned adds/updates from conversation context, git diff, PR, feature description, and existing Excel rows.
Before any write, show a full preview of every row that will be added or changed (including history shifts).
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.
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:

Open the workbook and search both sheets for the target System Page / Program Name (and for Functions sheet, also Name of Function within Program).
Match on existing rows when the program/page already exists.
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).
If nothing matches and the user intends a new program or function, say so clearly in the preview as NEW ROW.
Do not invent duplicate rows for the same page + same function.
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):

Summary — short ZH then EN (what the release did).
Per changed file — repo-relative path.
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.
Short explanation by line/range — what that hunk does (ZH then EN, or one ZH+EN pair per bullet).

Cell layout example:

轉倉出庫批次 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:

<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):

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):

<ClassName>.<fun1> / .<fun2> — <path-to-that-file>

Multi-file example:

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

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:

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:

The owning page purpose (what page C is for), and
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:

工單提料執行頁面（/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:

提料單管理。
Pick Order management.
使用／呼叫來源：批號追溯（追溯流程／單據生命週期查詢）。
Used / called from: Item Tracing (trace flow / document lifecycle query).

Function lives on 成品出倉 but is deep-linked from tracing:

成品出倉（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. 批號追溯):

…頁面目的（中文）…
…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:

Path exists — each repo-relative path resolves under the correct workspace (FPSMS-frontend or FPSMS-backend). Prefer Glob / Read / Grep; do not guess.
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.
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:
```
ItemTracingSummary — …/ItemTracingSummary.tsx
ItemTracingLocations — …/ItemTracingLocations.tsx
```
- Do not join multiple files with ; on one line.
Wrong location — if the symbol lives elsewhere, correct the path to the real file; do not keep a convenient-but-false path.
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:

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

Confirm Excel path exists (and is writable when saving).
Infer target sheets and rows from the user’s change description / diff.
Pre-check existing program/page/function rows in Excel.
For each Functions row: fact-check English symbol + every source path against the codebase (see Fact-check column F). Correct or drop failures.
For each Functions row: set E with page purpose and usage／呼叫來源 (owning page vs caller page; see Column E rule).
For each existing match: plan history shift + new Latest values (only shift function history when that function’s F symbols changed).
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).
For each new function/page: plan a new Ref. No. row (next integer after max used).
Present the full preview (verified F + file/line Major Changes) → ask once if correct.
On approval: apply shifts + writes with openpyxl, save, report sheet names, row numbers, Ref. Nos., and key Latest fields.
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).
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:

Ref. No. — Functions sheet Ref. No. for that row
Version — Latest Function Version (column H), e.g. v1.0.0
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):

/** 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):

/** 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:

/**
 * 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.:

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

26 KiB Raw Blame History