docs: en wiki — narratives for all 1,864 stored procedures and functions

Pass 2 of the routine-narrative job (per en/scripts/narrate_routines.md). Every page under en/docs/auto-catalog/{procedures,functions}/ now has a business-context narrative replacing the auto-generated placeholder. 1,684 procedures + 177 functions + 3 setup samples = 1,864 narratives. Each narrative follows the three-section shape: - **Business context:** Chinese module path from gdsmodule.sChinese, preserved verbatim, plus the user action that triggers the routine. - **What it does:** terse mechanism naming actual tables/columns/procs. - **Invocation:** concrete dispatch channel — gdsmodule hook, gdsconfigformmaster sSqlStr, GenericProcedureCallController dispatch, workflow proc via gdsmoduleflow.sApplyProName, Sp_Invalid_backwriting or Sp_delete_backwriting indirect dispatch, JMS PRO_ERPMERGEBASE family, Quartz scheduler via Sp_Task_*, external HTTP dashboard, or "appears orphaned, no caller found in any channel". Pass 3 QA: 70 random samples + 25 targeted re-verifications (orphan claims, bug flags). Zero slop; one broken cross-link fixed. Narratives surface real maintainer audit signal: shadowed-name DELETE tautologies in three PRO_ERPMERGE family procs, broken Chinese-char regex in Fun_GetCh / GetChineseChar, sealed-but-still-bound report procs, ~501 confirmed orphans, multiple copy-paste COMMENT drift, tenant-baked GUIDs in workflow data-builders, and several under-deployed feature families (e.g. the Sp_Receivables_* HZ variants, the entire Sp_beforeSaveReturn_* shadow family).

docs: en wiki — narratives for all 1,864 stored procedures and functions
Pass 2 of the routine-narrative job (per en/scripts/narrate_routines.md). Every page under en/docs/auto-catalog/{procedures,functions}/ now has a business-context narrative replacing the auto-generated placeholder. 1,684 procedures + 177 functions + 3 setup samples = 1,864 narratives. Each narrative follows the three-section shape: - **Business context:** Chinese module path from gdsmodule.sChinese, preserved verbatim, plus the user action that triggers the routine. - **What it does:** terse mechanism naming actual tables/columns/procs. - **Invocation:** concrete dispatch channel — gdsmodule hook, gdsconfigformmaster sSqlStr, GenericProcedureCallController dispatch, workflow proc via gdsmoduleflow.sApplyProName, Sp_Invalid_backwriting or Sp_delete_backwriting indirect dispatch, JMS PRO_ERPMERGEBASE family, Quartz scheduler via Sp_Task_*, external HTTP dashboard, or "appears orphaned, no caller found in any channel". Pass 3 QA: 70 random samples + 25 targeted re-verifications (orphan claims, bug flags). Zero slop; one broken cross-link fixed. Narratives surface real maintainer audit signal: shadowed-name DELETE tautologies in three PRO_ERPMERGE family procs, broken Chinese-char regex in Fun_GetCh / GetChineseChar, sealed-but-still-bound report procs, ~501 confirmed orphans, multiple copy-paste COMMENT drift, tenant-baked GUIDs in workflow data-builders, and several under-deployed feature families (e.g. the Sp_Receivables_* HZ variants, the entire Sp_beforeSaveReturn_* shadow family).
zichun
1 parent 3aff6ac0
Showing 1862 changed files with 10439 additions and 2448 deletions
en/docs/auto-catalog/functions/CALC_MATERIALS_SMAIL.md
en/docs/auto-catalog/functions/FUN_DISTINCTJSON_REMOVE_BYNAME.md
en/docs/auto-catalog/functions/FUN_GET_CALCPLAN_DATE_END.md
en/docs/auto-catalog/functions/FUN_GET_CALC_DATE.md
en/docs/auto-catalog/functions/FUN_GET_CALC_DATE_END.md
en/docs/auto-catalog/functions/FUN_GET_DATE_BC.md
en/docs/auto-catalog/functions/FUN_GET_DATE_BC_ADDTIME.md
en/docs/auto-catalog/functions/FUN_GET_DATE_BC_STARTDATE.md
en/docs/auto-catalog/functions/FUN_GET_DATE_BC_STARTDATE_NEW.md
en/docs/auto-catalog/functions/FUN_GET_DATE_BC_STARTDATE_NEWTYPE.md
en/docs/auto-catalog/functions/FUN_GET_DATE_BC_STARTDATE_NOW.md
en/docs/auto-catalog/functions/FUN_GET_DATE_DIFF_MINUTE.md
en/docs/auto-catalog/functions/FUN_GET_DATE_KT.md
en/docs/auto-catalog/functions/FUN_GET_DATE_KT_ADD.md
en/docs/auto-catalog/functions/FUN_GET_DATE_UKT.md
en/docs/auto-catalog/functions/FUN_GET_DATE_UKT_ADD.md
en/docs/auto-catalog/functions/FUN_GET_DATE_YX.md
en/docs/auto-catalog/functions/FUN_GET_DECOMPOSECUSTOMIZE.md
en/docs/auto-catalog/functions/FUN_GET_to_pinyin.md
en/docs/auto-catalog/functions/FUN_JSON_CHAR.md
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Material yield estimator for cuts taken from a stock board capped at 305 cm per side (board dimensions in cm). Header comment is `两变都小于305的材料（单位CM）` ("both sides under 305, unit CM"). Counts how many 305-cm stock boards a batch of `dQty` pieces of size `dWidth × dLength` will consume, including offcut reuse.
+
+**What it does:** sorts the long/short side, peels off any "whole-board" multiples when a side exceeds 305, then loops the remaining pieces along a 305-cm running cutline and uses a JSON list to track usable offcuts (`料头`). Returns the total board count. Does not read or write any table — pure arithmetic.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit.
@@ -19,4 +19,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Generic JSON-array dedup helper — given a JSON array of objects and the name of one key, returns a new JSON array with rows whose value at that key has already been seen filtered out. Sits with the rest of the JSON-utility family used to clean up dropdown / pick-list data assembled inside form-master sSqlStr blocks.
+
+**What it does:** validates `sJson`, iterates `0..JSON_LENGTH-1`, extracts each element's `$.<sName>`, keeps a running comma-joined seen-list, and `JSON_MERGE`s only first-occurrence elements onto the output array. Returns a JSON array; invalid JSON falls through to an empty array.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Production-planning shift-aware end-time calculator. Given the start datetime, total task minutes, and a machine id, returns the forecast end datetime taking into account the machine's shift schedule, weekend off-days (`sWkDayId` = 1 weekends, 3 Saturday only, 4 Sunday only), and the configured break windows (morning/lunch/afternoon/evening). Header comment is `几台Id，传入时间加时间,得出来结束时间` ("machine id + start + minutes → end").
+
+**What it does:** loads the machine's `elemachine` shift configuration (`sOffWork`, `sWorkType`, `sShiftsWork`, six break-window pairs, `sWkDayId`, `dWeek`). Computes how many full shifts the workload spans (`p_dDayHour DIV (dWeek*60)`) and the leftover minutes. Walks one day at a time, skipping weekend days as configured, then forwards the date by the unsuspended-shift count and the remaining minutes via [`FUN_GET_DATE_BC_ADDTIME`](FUN_GET_DATE_BC_ADDTIME.md). For each scheduled break window (`FUN_GET_DATE_UKT_ADD` per window) it pushes the end-time forward by the break length if the job spans it. Finally normalizes back onto a shift boundary via [`FUN_GET_DATE_BC_STARTDATE`](FUN_GET_DATE_BC_STARTDATE.md).
+
+**Invocation:** referenced in the source file under `script/标版/30100101/schedule/settime算休息时间/`. Status: appears orphaned in the live DB — no other routine, form-master sSqlStr, gdsmodule hook, or Java caller references it. Body also references `p_tStartDate`, `sBrId`, `sSuId` which are not declared as parameters — verify before invoking.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Production-planning shift-rollover helper — when a job under day-shift mode overruns the shift's clock-out time, this function nudges the timestamp forward by one off-shift window so the next work segment starts on the following shift. Header comment is `时间后移动计算` ("forward time-shift calc"). Companion to [`FUN_GET_CALC_DATE_END`](FUN_GET_CALC_DATE_END.md).
+
+**What it does:** for day-shift (`sWorkType='1'`), if `p_date` is past the day's `sShiftsWork` boundary, returns `DATE_ADD(p_date, INTERVAL (1440 - p_dMinute) MINUTE)`. Otherwise returns `p_date` unchanged. Read-only.
+
+**Invocation:** referenced in the source file shipped with the unified-planning calc bundle (`script/标版/30100101/schedule/settime算休息时间/`). The corresponding callers (`Sp_unifiedPlanning_BtnCalculation_workorder`, `..._calc`) currently have the call commented out — see the surviving call to `FUN_GET_CALC_DATE_END` in the same blocks. Status: live in DB, paths to invoke it currently disabled — verify before relying on it.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Production-planning time-arithmetic helper — given a job's start date, its duration in minutes, and the machine's shift type, returns the calendar end timestamp. Used by the unified-planning recalc path to roll forecast end times forward when work is rescheduled. Header comment is `时间后移动计算(不考虑双休日之类的)` ("forward time-shift calc, ignores weekends etc.").
+
+**What it does:** coalesces defaults (`p_sWorkType=2`, `p_date=NOW()`, hour/minute=0), then `DATE_ADD(p_date, INTERVAL <minutes> MINUTE)` where the minute count is `p_dHour` for two-shift mode (`sWorkType=2`) and `FLOOR(p_dHour/p_dMinute)*(1440-p_dMinute) + p_dHour` for day-shift mode (`sWorkType=1`) — the latter inflates by a full off-shift window each time the day-shift cap is crossed.
+
+**Invocation:** called by `Sp_unifiedPlanning_BtnCalculation_workorder` and `Sp_unifiedPlanning_BtnCalculation_workorder_calc` — the work-order recalc step of unified production planning (生产管理 → 生产运营报表 family). No form-master, gdsmodule-hook, or Java caller.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Returns the shift-label string (`YYYY-MM-DD 白班` / `YYYY-MM-DD 晚班`) that a given timestamp belongs to. This is the value stored in `mftproductionplanslave.sDivRow` and friends — production reports, BI rollups, and the schedule grid all bucket by this string. The two shift names are pulled from the const table (`dayShift` / `nightShift` via `Fun_Sis_GetConst`), so multi-tenant overrides keep their own labels.
+
+**What it does:** for `sWorkType='1'` (day-shift only), returns today's `dayShift` label. Otherwise, if `p_Date` is inside today's `sWorkOff` → `sShiftsWork` window returns today's `dayShift` label; if not, returns `nightShift`. When the time is before `sWorkOff` on the date (i.e. early-morning continuation of the prior night shift), the date is rolled back one day.
+
+**Invocation:** central helper for the production-scheduling and reporting chain. Called by ~25 procs spanning BI workshop rollups, equipment-output reports, manufacturing time-set / time-trace, production-plan lock/unlock buttons (`Sp_productionPlan_BtnEventLock*`, `Sp_productionPlan_BtnEventunLock*`), unified-planning calc, and `Sp_Manufacture_BtnEventCopyPlanSlave`. A private same-named method in `WorkOrderPlanServiceImpl` reimplements the same logic in Java but doesn't invoke the SQL function.
@@ -24,4 +24,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Production-planning time-addition helper. Adds `p_dMinute` to a base datetime, but for day-shift mode (`sWorkType='1'`) routes any overrun past the shift's end (`sShiftsWork`) to start counting again from the next day's clock-on (`sWorkOff`). Header comment is `根据传入时间获取时间` ("get date based on input date").
+
+**What it does:** for `sWorkType=1`, computes `p_sDqbcsy = TIMESTAMPDIFF(MINUTE, p_Date, today_at_sShiftsWork)`. If the requested minute increment exceeds that remaining-in-shift window, returns `next_day_at_sWorkOff + (p_dMinute - p_sDqbcsy) MINUTE`. Otherwise (and for `sWorkType` ≠ 1) returns plain `DATE_ADD(p_Date, INTERVAL p_dMinute MINUTE)`.
+
+**Invocation:** called by [`FUN_GET_CALCPLAN_DATE_END`](FUN_GET_CALCPLAN_DATE_END.md) and `Sp_Manufacture_SetTime_BB` (manufacturing time-setter for production-plan rows). Production-scheduling subsystem, 生产管理.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Day-shift normalizer at the core of the production-scheduling time-math chain. For a day-shift machine, if the passed timestamp falls in the off-shift window, snaps it to the relevant clock-off boundary so all downstream interval math is shift-aligned. For two-shift mode (`sWorkType=2`) returns `p_Date` unchanged.
+
+**What it does:** for `sWorkType=1`, classifies whether `p_Date` is in the off-shift window (`sWorkOff` → `sShiftsWork`). If yes, returns `today_sWorkOff` when `p_Date < today_sWorkOff`, else `tomorrow_sWorkOff`. Otherwise (and for non-day-shift) returns `p_Date`.
+
+**Invocation:** core helper called by [`FUN_GET_CALCPLAN_DATE_END`](FUN_GET_CALCPLAN_DATE_END.md) and a wide span of production-scheduling and MES procs — BI workshop rollups (`Sp_bi_workshop_1/2/3`), board reports (`Sp_Bd_bi20_*`), machine-time calc (`Sp_BtnCalculation_Machine_time_byMachineType(End)`), `Sp_MachineSpeedanalysis_2_new`, `Sp_Manufacture_SetTime_BB`, `Sp_Manufacture_SetTimeDivRow`, MES event-report procs, and the unified-planning recalc family.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Production-reporting shift-anchor helper — snaps an arbitrary timestamp onto the start of whichever shift it falls into so production reports and machine-utilization stats roll up by shift, not by raw minute. Used by the workshop / BI roll-up reports under 生产管理 → 生产运营报表 and the production-report analysis path. Header comment is `根据传入时间获取时间` ("get date based on input date").
+
+**What it does:** if `HOUR(p_Date)` is between `p_sWorkStart` and `p_sWorkOff` (i.e. the work-day shift is active), returns today's `sWorkStart` timestamp. Otherwise, if `p_Date` is past midnight on the same day, returns today's `sWorkOff`; else returns the previous day's `sWorkOff` — i.e. the night-shift starts the prior day.
+
+**Invocation:** called by `Sp_Bd_bi20_1_newZZT`, `Sp_Bd_bi20_2new`, `Sp_Bd_bi20_hh`, `Sp_bi_workshop_1/2/3`, `Sp_BtnCalculation_Machine_time_byMachineType`, `Sp_MachineSpeedanalysis_2_new`, `Sp_Mes_EventReport(Old)`, and the production-report analysis proc (`Sp_Bd_mftproductionreport_analysis`). MES event-report and BI rollup chain.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Variant of [`FUN_GET_DATE_BC_STARTDATE_NEW`](FUN_GET_DATE_BC_STARTDATE_NEW.md) that branches on shift type. For two-shift mode (`sWorkType=2`), snaps the input to whichever shift it falls into. For day-shift mode (`sWorkType=1`), instead returns the next day's clock-on when the input is in the late-evening window (≥20:00). Used by manufacturing time-set and MES event-report procs that need shift-anchoring sensitive to whether the shop runs single or double shifts.
+
+**What it does:** `IF sWorkType=2`: returns today's `sWorkStart` when `HOUR(p_Date)` is in the active window; otherwise returns either today's `sWorkOff` (when past 20:00) or yesterday's `sWorkOff`. `ELSE` (day-shift): returns today's `sWorkStart` when in-window; otherwise tomorrow's `sWorkStart` when `HOUR ≥ 20`, else today's `sWorkStart`.
+
+**Invocation:** called by `Sp_BtnCalculation_Machine_time_byMachineType` (machine-time recalc on schedule button), `Sp_Mes_EventReport`, and `Sp_Mes_EventReportOld`. MES event-reporting and machine-time recalc chain. Body of [`FUN_GET_DATE_BC_STARTDATE_NEW`](FUN_GET_DATE_BC_STARTDATE_NEW.md) is referenced from the same source bundle.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Day-shift overflow normalizer used to compute the planning end timestamp from a job's start time. For a day-shift machine (`sWorkType=1`), pushes the timestamp to the next clock-off boundary minus the off-shift window length, so a job that ends after the shift "wraps" to the equivalent point on the following shift. Companion to [`FUN_GET_DATE_BC_STARTDATE`](FUN_GET_DATE_BC_STARTDATE.md), with a leading-comment block preserving the older simpler version.
+
+**What it does:** for `sWorkType=1`, classifies whether `p_Date` falls inside the off-shift window (`sWorkOff` → `sShiftsWork` on the same day). If it does (`p_sWorkTypeValue=2`), computes a new candidate `p_DateRet` at the appropriate `sWorkOff` boundary (same day if `p_Date < today_sWorkOff`, else tomorrow's). Then subtracts the off-shift span (`24*60 - working span`) from the running diff and applies it. Returns the shifted timestamp.
+
+**Invocation:** called by `Sp_BtnCalculation_Machine_time_byMachineTypeEnd` (the end-time recalc twin of `Sp_BtnCalculation_Machine_time_byMachineType`). Production-scheduling chain.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Returns the minute-length of a clock-time window (`HH:MM:SS` strings), wrapping across midnight when the end is "earlier" than the start (i.e. a night-shift break window like `23:30 → 00:30`). Used to compute break-window durations (lunch, dinner, midnight) for the production-scheduling time-arithmetic chain.
+
+**What it does:** wraps both clock strings with today's date via `CONCAT(DATE_FORMAT(NOW(),'%Y-%m-%d'),' ', …)` and casts to datetime. If start ≤ end, returns `TIMESTAMPDIFF(MINUTE, start, end)`. Else returns the diff to `end + 1 DAY`. Coalesces NULL to 0.
+
+**Invocation:** called by [`FUN_GET_CALCPLAN_DATE_END`](FUN_GET_CALCPLAN_DATE_END.md) (to compute the six break-window lengths), `Sp_Manufacture_SetTimeDivRow`, `Sp_Manufacture_SetTime_BB`, `Sp_Manufacture_SetTime_process`. Production-scheduling time-math chain.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** 生产排程 → 生产计划管理 → 生产管理 — cross-midnight (跨天/夜班) rest-period shifter used by the workcenter-scheduling time engine. When `Sp_Manufacture_SetTime*` is walking a job along a machine's working calendar and the next free instant lands inside a night-shift's main rest window (default 23:30–00:30, but the window may span midnight), this function pushes the cursor to the end of that window.
+
+**What it does:** treats `p_sStartDate`/`p_sEndDate` as wall-clock times of a rest window that crosses midnight. It tests whether `p_tCStartTime` falls in the window either on the previous calendar day (start-1d … end-today) or on the current day (start-today … end-tomorrow), and if so returns the corresponding end boundary (today or tomorrow). Otherwise returns `p_tCStartTime` unchanged.
+
+**Invocation:** called from `Sp_Manufacture_SetTimeDivRow`, `Sp_Manufacture_SetTime_BB`, and `Sp_Manufacture_SetTime_process` — only on the `p_sWorkType = '2'` (night shift) branch, paired with the `p_sYxStartDate`/`p_sYxEndDate` (夜休) parameters. Ultimately reached via the Java `BtnCalculationService` "计算排程时间" button (Sp_unifiedPlanning_BtnCalculation / Sp_Manufacture_SetTime path).
@@ -24,4 +24,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Production-scheduling break-window push helper for a planning interval. If the planned interval crosses a configured break window (e.g. lunch 12:00–13:00) the running end-time gets pushed by the window length so the break doesn't count as production time. "KT" matches the `kt`/`ukt` naming on the sister functions ([`FUN_GET_DATE_UKT`](FUN_GET_DATE_UKT.md) family). Day-shift companion of [`FUN_GET_DATE_UKT_ADD`](FUN_GET_DATE_UKT_ADD.md), which covers the night-shift break window.
+
+**What it does:** defaults the window to `23:30:00 → 00:30:00` if unset. Computes `p_i = (p_tCStartTime ≤ today_at_sStartDate)` and `p_j = (p_tAddTime > today_at_sStartDate)`. If both are true (i.e. the interval straddles the break window's start), adds `p_addMinut` minutes to `p_tAddTime`. Returns the (possibly adjusted) `p_tAddTime`.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — only the source file `FUN_GET_DATE_KT_ADD.sql` itself was found. Sister `FUN_GET_DATE_UKT_ADD` is live in [`FUN_GET_CALCPLAN_DATE_END`](FUN_GET_CALCPLAN_DATE_END.md); this `KT_ADD` form looks like a leftover companion — candidate for maintainer audit.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** 生产排程 → 生产计划管理 → 生产管理 — within-day rest-period shifter used by the workcenter-scheduling time engine. Companion to `FUN_GET_DATE_KT` for rest windows that do NOT cross midnight (lunch 午休, afternoon tea 午茶, dinner 晚餐, etc.). Default window 11:30–12:30.
+
+**What it does:** checks whether `p_tCStartTime` sits between `start_today` and `end_today`; if yes, jumps it forward to `end_today`. Otherwise returns the input unchanged. NULL-safe via `IFNULL` defaults.
+
+**Invocation:** called from `Sp_Manufacture_SetTimeDivRow`, `Sp_Manufacture_SetTime_BB`, `Sp_Manufacture_SetTime_Employ`, `Sp_Manufacture_SetTime_process`, and the helper `FUN_GET_CALCPLAN_DATE_END`. Day-shift branch passes it the lunch/breakfast/dinner window pairs (`p_sWxStartDate`/`p_sWxEndDate`, etc.) one after another to skip whichever rest period the cursor falls in. Reached via `BtnCalculationService` "计算排程时间" button.
@@ -24,4 +24,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** 生产排程 → 生产计划管理 → 生产管理 — duration-stretching variant used by the workcenter-scheduling engine. Called when a job's *task duration* straddles the start boundary of a within-day rest window: if work starts at or before the rest window begins but is scheduled to end after the window opens, push the projected end time forward by `p_addMinut` minutes (the length of that rest period) so the elapsed work time still equals the planned duration.
+
+**What it does:** with `p_tCStartTime` (task start) and `p_tAddTime` (current projected end), tests `start ≤ restWindowStart < end`; if true, adds `p_addMinut` minutes to the end time and returns it. Otherwise returns end time unchanged.
+
+**Invocation:** called from `Sp_Manufacture_SetTime`, `Sp_Manufacture_SetTime_Employ`, `Sp_Manufacture_SetTime_process`, and `FUN_GET_CALCPLAN_DATE_END`. Day-shift loop chains the call across each defined rest window (`p_sWxStartDate`/`p_sWfStartDate`/`p_sWyStartDate`/`p_sYxStartDate`/`p_sYfStartDate`/`p_sYyStartDate` etc.). Reached via `BtnCalculationService` "计算排程时间" button.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** 生产排程 → 生产计划管理 → 生产管理 — orphaned variant of the cross-midnight rest-shifter. Body is structurally identical to `FUN_GET_DATE_KT` (same `p_sStartDate`/`p_sEndDate` default 23:30 → 00:30 cross-midnight window logic), differing only in the branch-2 fallback: where `FUN_GET_DATE_KT` rolls `p_tCStartTime` to *next day's `p_sEndDate`*, this one only assigns it on the cross-midnight branch and leaves the same-day branch untouched.
+
+**What it does:** if `p_tCStartTime` falls in the (prev-day-start … today-end) cross-midnight window, jump it to tomorrow's `p_sEndDate`; else if it falls in the (today-start … tomorrow-end) window, jump it to today's `p_sEndDate`; otherwise unchanged.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master, gdsmodule hooks, other routines, exhaustive xly-src grep across all extensions) — only its own `.sql` def file exists. Likely superseded by `FUN_GET_DATE_KT`. Candidate for maintainer audit.
@@ -24,4 +24,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** 生产排程 → 生产计划管理 → 生产管理 — when an MftPlan (生产工单 / production plan) row is being inserted and the work-order's "印面" (sheet face) is configured with a custom 分拆 (decomposition) scheme — by 贴数 (signature count) or 折页贴数 (folding signatures) — this function resolves the per-index face-name string the slave row should carry.
+
+**What it does:** if no control-face-name input is provided, returns the plain `p_sFaceName`. If `p_iArrangeSrcValue` is 3 (按贴) or 4 (按折页贴), reads `sControlFaceName_tmp.sControlFacesChar` for the supplied `iIndex` and concatenates with `p_titleEnd` (正/反 marker). Otherwise returns the original control-face-name unchanged. Other 分拆 modes (1 无需分拆, 2 按印版付数, 5 按装订贴数, 6 按书刊贴数, 7 按实际米数) take the no-op path.
+
+**Invocation:** called from `Sp_Manufacture_InsertMftPlanSlave` while it splits a slave plan row into per-signature instances. Sp_Manufacture_InsertMftPlan* chain is invoked by the production-plan generation flow (排程 module). No direct form-master or gdsmodule hook reference.
@@ -18,4 +18,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Converts a Chinese display string to its lowercase pinyin equivalent — a generic name-to-pinyin helper. Returns the original characters untouched if they are ASCII.
+
+**What it does:** hex-encodes the input, then walks two bytes at a time. For each high-byte > 128 (Chinese GBK character) it computes the GBK code point and looks up the pinyin prefix in `t_base_pinyin` (`CODE_ >= ABS(mycode) ORDER BY CODE_ ASC LIMIT 1`); ASCII bytes pass through. Returns the concatenated lowercase string.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. The companion `t_base_pinyin` table exists, suggesting this was wired up for a pinyin-search feature that never shipped.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Tiny JSON-string accessor. Intended to support the `sp_btn_action` button-event dispatcher in reading textual fields out of `sButtonParam` / change-value JSON payloads.
+
+**What it does:** Validates `sParam` is JSON; returns `JSON_UNQUOTE(JSON_EXTRACT(sParam, sKey))` or `''` if missing/invalid. Two-line helper.
+
+**Invocation:** Orphan-via-dead-chain. Only two routine callers (`sp_btn_action`, `sp_btn_action_updatequoquotationslave`) — both themselves orphans (no form, no module hook, no Java reference). One customer override script in `xly-src/script/客户/万昌/计件工资/sp_btn_WorkOrderAssessmentPassRate.sql` references it, but that proc is not deployed in the live DB. Candidate for maintainer audit.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Integer-typed sibling of `FUN_JSON_CHAR`. Reads a key out of a JSON payload and casts to signed int. Designed for the same `sp_btn_action` button-event dispatcher to evaluate flag fields (`bSubmit`, `bCheck`, `bTecnologe`, …).
+
+**What it does:** If `sParam` is valid JSON, extracts `sKey`, strips quotes, casts to signed integer; defaults to 0.
+
+**Invocation:** Orphan-via-dead-chain. Only callers are `sp_btn_action` + `sp_btn_action_updatequoquotationslave`, both themselves orphans (no form-master, module-hook, or Java reference anywhere). Candidate for maintainer audit.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Material-cutting estimator for the printing/box-making workshop — computes how many full sheets ("整根") are needed to fulfill `dQty` pieces at `dLength × dWidth` (cm), assuming a 305 cm stock sheet and reusing offcuts. Header gloss: "两变都小于305的材料（单位CM）" (both dimensions under 305 cm).
+
+**What it does:** Swaps so length ≥ width, peels off whole stock-sheet multiples for any dimension > 305, then runs a greedy bin-packing loop tracking the running offcut (`clys`) and a JSON queue of reusable scraps (`jsonlist`) — each piece consumes length then width, replenishing `clys = 305 - dLength` when exhausted. Returns full-sheet count + scrap-sheet count.
+
+**Invocation:** Status: appears orphaned. No form-master, module-hook, other-routine, or xly-src caller. Candidate for maintainer audit.
@@ -19,4 +19,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Simplified ↔ Traditional Chinese character conversion utility. xly stores parallel `sChinese` / `sBig5` columns on most master tables so reports rendered for Taiwan/HK customers (or for printing plates targeting Big5 locales) can show the Traditional form. This function is the per-string mapper.
+
+**What it does:** walks each character of `str` and looks it up in the `codetable(gb, big)` table — direction chosen by `toBIG` (1 = GB→Big5, else Big5→GB). Falls back to the original character when no row matches. Pure read; one row lookup per character.
+
+**Invocation:** wrapped by `Fun_Gb2Big_ChineseToBig` and `Sp_Gb2Big_ChineseToBig`, which apply the conversion column-by-column (`sChinese → sBig5`, `sChineseDepart → sBig5Depart`, etc.) on master records during save flows.
@@ -18,4 +18,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Quotation reporting — renders a JSON parameter list as a human-readable string for display on the printed quotation. Each parameter row has a code (`sParamKey`), label (`sParamName`), and value (`sParamValue`); the output collapses them into `name:【value】;name:【value】;…` form.
+
+**What it does:** uses `JSON_TABLE` to fan the JSON array out into rows and `GROUP_CONCAT` to assemble the display string. Pure transformation; no schema dependencies.
+
+**Invocation:** called only by `Sp_reportdata_Quo_JT` — the data-prep proc behind the JT-flavoured quotation report template.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Pinyin-initials helper for auto-generated codes. The `Sp_Sis_GetMaxNo` family (which builds the next sequential business code for orders, materials, products, etc.) calls this when a code template embeds a pinyin abbreviation of a name field — e.g., turning customer `北京华佳` into `BJHJ` so it can be used as a code prefix.
+
+**What it does:** walks each character of `P_NAME` (after normalizing full-width parens to ASCII) and concatenates `Fn_fristPinyin(char)` for each. Falls back to the original `P_NAME` if every char yielded empty. Pure string transformation; no table reads.
+
+**Invocation:** called by `Sp_Sis_GetMaxNo`, `Sp_Sis_GetMaxNo_1`, `Sp_Sis_GetMaxNo_New`, and `Sp_Sis_GetMaxNo_copy1` — the next-code generator invoked by save flows across most master forms.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Backup / snapshot variant of `Fn_find_pinyin` (`_copy1` suffix). Per wiki convention, backup objects are not narrated (see [the index](../../index.md#whats-out-of-scope)).
+
+**What it does:** Same as `Fn_find_pinyin` at the time of copy.
+
+**Invocation:** Not expected to be called from production code; verify before relying on it.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Returns the first pinyin letter of a single Chinese character. Building block of `Fn_find_pinyin`, which assembles full pinyin abbreviations used as code prefixes by the `Sp_Sis_GetMaxNo` family.
+
+**What it does:** if the input is single-byte ASCII it returns it unchanged. Otherwise converts the first byte of the GBK-encoded character to its hex value and bucket-matches it against the standard GBK pinyin-range boundary table to pick a letter A–Z. No `I`, `U`, `V` (Mandarin has no surname/initial in those ranges by convention). No table I/O.
+
+**Invocation:** called only by `Fn_find_pinyin` and indirectly by the `Sp_Sis_GetMaxNo*` next-code generators that wrap it. A `_copy1` backup of `Fn_find_pinyin` also references it.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Hand-rolled JSON value extractor — predates xly's adoption of MySQL's native `JSON_EXTRACT`. Used heavily in cost/quotation/work-order calculation procs that store inline JSON snippets on detail rows (config parameters, dynamic field bags) and need to pull a single scalar out without strict JSON validity.
+
+**What it does:** searches `p_jsonstr` for `"<key>":"..."` and returns the substring up to the next `"`; if that fails it falls back to `"<key>":...,` (unquoted value) and returns up to the next `,` or `}`. Pure regex/substring; tolerant of malformed JSON in a way `JSON_EXTRACT` is not.
+
+**Invocation:** called from ~20 production procs including the calc family (`Sp_Calc_sMpt`, `Sp_Calc_sScd`, `Sp_Calc_sSod`, `Sp_Calc_sWod`), the manufacturing planning info procs (`Sp_Manufacture_ProductionPlanInfo*`), MES OEE state probes (`Sp_Manufacture_GetAPSState*`), `Sp_Sis_GetMaxNo*`, and the graphic report engine (`Sp_Graphic_Report_Analysis_Data`).
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Counts how many tokens a delimited string would produce when split on `splitstr`. Building block used throughout the save-return / before-save-return validation procs (`Sp_saveReturn_*`, `Sp_beforeSaveReturn_*`) — those procs iterate over comma-joined id lists coming from the FROUNT save payload, and this gives them the loop bound.
+
+**What it does:** `length(str) - length(replace(str, splitstr, '')) + 1` — one-liner that subtracts the trimmed length from the original to count delimiters, then adds one. Returns 1 even when the input has no delimiter at all.
+
+**Invocation:** called from ~80 production procs, dominated by the `Sp_saveReturn_*` and `Sp_beforeSaveReturn_*` document save flows (sales order `_sSod`, work order `_sWod`, quotation `_sQtt`, packing `_sPkg`, etc.) and a handful of cost-calc / reporting procs.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Returns the Nth token from a delimited string — the indexed-access companion to `Fn_spit_length`'s count. The pair is the standard string-list iteration kit used across the save-return validation flows and many reports.
+
+**What it does:** `reverse(substring_index(reverse(substring_index(str, splitstr, strindex)), splitstr, 1))` — slices off the first `strindex` tokens, reverses, slices off the last one, reverses back. Returns the 1-based Nth token.
+
+**Invocation:** called from ~100 production procs, including all `Sp_saveReturn_*` / `Sp_beforeSaveReturn_*` document save flows, the work-order cost-calc data-pack procs (`Sp_WorkOrder_CalcDataPack*`), the AutoOrder production-plan procs (`Sp_productionPlan_BtnEventAutoOrder*`), and a handful of utility funcs (`Fun_bFilter_toWhere`, `Fun_getPartNameStatus`, `Fun_getPlanDate`).
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Flattens a JSON array of row objects into a delimited display string — the workhorse used by manufacturing-plan reports and work-order data-pack procs to render embedded detail lists (process steps, color sequences, parts lists) as a single column on a report row.
+
+**What it does:** loops the `p_json` array. For each row, loops the comma-separated `cloumnNames` and extracts `$[i].column` via `JSON_EXTRACT`, stripping the JSON quotes. Each value gets the per-column suffix from `splitNames` (e.g., `+,+,*`); rows are joined by `,` unless `splitNames` is supplied (in which case rows are concatenated directly). Returns the original `p_json` untouched if input is empty or invalid.
+
+**Invocation:** called from the MFT plan inserters (`Sp_Manufacture_InsertMftPlan`, `Sp_Manufacture_InsertMftPlanProcess`, `Sp_Manufacture_InsertMftPlanToErp`), the production-report check procs (`Sp_Check_mftProductionReportValue*`), the OEE reports (`Sp_OEE_ProductionReport*`), the work-order reports (`Sp_reportdata_WorkOrder*`), `Sp_WorkOrder_CalcDataPackProductStd`, and `Sp_WorkOpsOutProcess`.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Variant of [`Fun_AnalysisListJson`](Fun_AnalysisListJson.md) tuned for work-order report rendering — on the last row of the JSON array it strips embedded newlines from the per-column suffix so the final display string doesn't end with a trailing line break.
+
+**What it does:** same loop as `Fun_AnalysisListJson` (walks the JSON array, extracts `$[i].col` per column, joins with `splitNames` suffixes). The only difference is the special-case at `p_handle = p_length`: applies `REPLACE(splitName, '\n', '')` to the suffix.
+
+**Invocation:** called only by the work-order data-prep reports `Sp_reportdata_WorkOrder`, `Sp_reportdata_WorkOrder1`, `Sp_reportdata_WorkOrder3`.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Predecessor of [`Fun_AnalysisListJson`](Fun_AnalysisListJson.md) — same JSON-array-to-delimited-string shape but missing the `JSON_VALID` / empty-input guards and always uses `,` as the row separator. Kept as the `_Old` snapshot, presumably from before the validation patch.
+
+**What it does:** walks the JSON array; per row, extracts each named column via `JSON_EXTRACT`, strips quotes, appends the per-column `splitName` suffix, and concatenates rows with a hard-coded `,` separator. Crashes if `p_json` isn't valid JSON (no guard).
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. The active version is `Fun_AnalysisListJson`.
@@ -24,4 +24,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Color-count accumulator used during work-order product-standard cost calculation. Walks a JSON array of color rows, splitting them into "process colors" (CMYK + composite `C+M+Y+K`) versus "spot colors" depending on `iColorOrder`, and sums the matching quantity column.
+
+**What it does:** for each row, extracts a name from `cloumnNames` and a quantity from `cloumnNames1`. If `iColorOrder=1` adds the quantity when the name matches one of `C`, `M`, `Y`, `K`, `C+M+Y+K`; otherwise adds the quantity when it does not. Returns the integer total (signature returns `int` even though intermediate is decimal). Despite the shared name, this is *not* a string-list flattener like the sibling functions — only the loop shape is shared.
+
+**Invocation:** called only by `Sp_WorkOrder_CalcDataPackProductStd` — the data-pack cost calculator for packaging product standards.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Backup / snapshot variant of `Fun_AnalysisListJson` (`_copy1` suffix). Per wiki convention, backup objects are not narrated (see [the index](../../index.md#whats-out-of-scope)).
+
+**What it does:** Same as `Fun_AnalysisListJson` at the time of copy.
+
+**Invocation:** Not expected to be called from production code; verify before relying on it.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Purchasing/quotation/work-order — "most recent purchase price" lookup for a material, optionally filtered by supplier. The cost-calculation procs use this to default a material line's unit cost when the user hasn't typed one in. Header comment is `获取最近采购价(物料)` ("get most-recent purchase price for material").
+
+**What it does:** reads `elematerialssupply.dQuantityPrice` for the given material, tenant-scoped by `sBrId`/`sSuId`, only over `bCheck = 1` rows, taking the latest by `tCreateDate`. Tries narrowing filters in order: (supplier + style) → (supplier alone) → (style alone) → (material alone). Returns the price as a varchar; `'0'` when nothing matches.
+
+**Invocation:** referenced from form-master `sId 192116810113315263819752160` ("1/4 采购申请->采购订单") and `101251240115016347243410860` ("待入库客来料任务列表"). Called directly by the quotation calc family (`Sp_Quotation_CalcData*`), work-order calc family (`Sp_WorkOrder_CalcData*`), `Sp_Inventory_MaterialsInventoryV56Price`, `Sp_Manufacture_sWodPurchareMaterials_copy1`, the materials check proc `Sp_Check_sMcd`, and the `_Quo` quotation variant of itself.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Quotation-side material-price lookup. Wraps [`Fun_Cashier_GetMaterialsPrice`](Fun_Cashier_GetMaterialsPrice.md) and applies the tenant-configured quotation markup so the quoted price differs from the underlying purchase price. Source columns are `SysSystemSettings.sValue` for `NetPrice` (rounding decimals) and `NetVeryHighPercentage` (markup %).
+
+**What it does:** first reads `NetPrice` and `NetVeryHighPercentage` for the tenant, then computes `ROUND(Fun_Cashier_GetMaterialsPrice(...), NetPrice) * (1 + NetVeryHighPercentage/100)`. If that comes back 0 (no historical purchase), falls back to the same ladder of direct `elematerialssupply` reads as the base function. Returns `'0'` as a final fallback.
+
+**Invocation:** Status: appears orphaned at the leaf level. No caller found in form-master, gdsmodule hooks, other routines, or xly-src grep — candidate for maintainer audit. The `_Quo` suffix and the markup wiring point to quotation flows, but the live quotation-calc family (`Sp_Quotation_CalcData*`) currently calls the plain `Fun_Cashier_GetMaterialsPrice`, not this variant.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Newer revision of [`Fun_Cashier_GetMaterialsPrice`](Fun_Cashier_GetMaterialsPrice.md) — same "most recent purchase price" lookup for a material under the same fallback ladder. The two versions are bodies-identical in the section seen here; the diff (if any) sits in trailing logic this lookup didn't pull out.
+
+**What it does:** reads `elematerialssupply.dQuantityPrice` filtered by material + (optional supplier, style), tenant-scoped, `bCheck = 1` only, latest by `tCreateDate`. Returns `'0'` if no match.
+
+**Invocation:** called only by `Sp_Check_sMcd` — the material-check proc invoked from material-card save flows. Not referenced by any form-master, gdsmodule hook, or xly-src file. The stable variant `Fun_Cashier_GetMaterialsPrice` is the one used by the cost-calc family.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Sales-side — "most recent sale price" for a finished product, used to default product-line prices on sales documents. Despite the header comment `获取最近采购价(产品)` ("most-recent purchase price for product"), the body reads sales views, not purchasing views; the comment is a copy-paste leftover from the materials sibling.
+
+**What it does:** reads `dProductPrice` from `Viw_SalSalesChecking` first (settled sales rows, `dLossMoney = 0`), then falls back through `Viw_SalDeliverGoods` and `Viw_SalSalesOrder`, all `bCheck = 1`, tenant-scoped, latest by `tCreateDate`. Returns `'0'` if nothing matches.
+
+**Invocation:** referenced from form-master `sId 101251240115016087911499840` ("选择材料(销售)" — material selector on sales forms) and called by `Sp_Save_CheckSaveAfter` for the after-save sales validations.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Newer revision of [`Fun_Cashier_GetProductPrice`](Fun_Cashier_GetProductPrice.md). Drops the `Viw_SalSalesChecking` and `Viw_SalDeliverGoods` reads and adds a fallback into `viw_pitproductinit` (the product-init cost view) — i.e., when no recent sales-order price exists, defaults to the configured init cost rather than 0.
+
+**What it does:** queries `Viw_SalSalesOrder.dProductPrice` for the latest `bCheck = 1` tenant-scoped row; if 0, queries `viw_pitproductinit.dCostPrice` under the same filter. Returns `'0'` if both miss.
+
+**Invocation:** called by `Sp_Save_CheckSaveAfter` — specifically the after-save validation path that backfills `dProductPrice` and `dProfitLossMoney` on the sales detail when the user leaves them blank. Not referenced by form-master, gdsmodule hooks, or xly-src.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Box-typesetting (拼版) layout configuration helper for the imposition / nesting (`sisboxtypesetting`) feature. For a given product-type id, returns the type's child layout rules as a JSON array — each rule packed as `{iIncrement, sId, sBrandsId, sSubsidiaryId, iOrder, sParentId, sName, sChinese, showName, sBig5, iFitWidth, sCode, sSettingMethod, iFAngle, sFLengthOffset/sFWidthOffset, iSAngle, sSLengthOffset/sSWidthOffset, sSGroupOffset, sSecondLongitudinalOffset/sSecondorizontalOffset}`. Header comment is `获取排除算法` ("get exclusion algorithm").
+
+**What it does:** runs one `SELECT` against `sisboxtypesetting` filtered by `sParentId = sProductTypeId`, builds each row's JSON via `JSON_OBJECT`, joins them with `GROUP_CONCAT ORDER BY iOrder`, and wraps the result in `[...]`. Returns the empty string when no rows match.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Token-substitution helper used by the formula-resolution family of procs (`Sp_System_ReplaceField*`) when expanding the variable placeholders inside a formula string (e.g. quote-price formulas, work-order calc formulas). One call replaces one `[name]` placeholder with its concrete value, plus a "concatenated trace" copy `[name]value` so downstream code can render the audit trail. Header comment is `公式计算解析函数` ("formula calc parsing function").
+
+**What it does:** if `toReplaceValue` is purely numeric (regex `[^0-9.]=0`), it normalizes via `ROUND(CONVERT(...)+0,4)` to strip trailing zeros. Lowercases both keys. Returns `''` for empty input. Then `REPLACE`s the placeholder (in both `[name]` and full-width `【name】` forms) with `toReplaceValue` and with the concatenated `nametoReplaceValue` trace token.
+
+**Invocation:** called from `Sp_System_ReplaceFieldNew`, `Sp_System_ReplaceField_Detail`, `Sp_System_ReplaceField_NEW`, `Sp_System_ReplaceField_NEW_ACT` — the formula-substitution upgrades shipped under `script/标版/upgrade/20220111公式解析实际详情` and `20220321计算获取公式解析`.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Per-process parameter-pack builder for the routing-step (`sisprocesssparam`) configuration. For a given process id, returns a JSON-object string describing every parameter that step exposes — its display name, default value, and dropdown options — so the work-order UI can render the right form fields when a worker chooses that process. Header comment is `公式计算解析函数` ("formula calc parsing function"). Example payload in the body comments shows hot-stamp ("烫金") params like `生产方式`, `做版要求`, `测试方法`.
+
+**What it does:** counts the rows in `sisprocesssparam` for `p_sProcessId`; if zero, returns `''`. Otherwise opens a cursor ordered by `iOrder` and, for each row, concatenates `"sParam<i>":"<name>","sParamDefault<i>":"<default>"` plus an optional `"sParamDropDown<i>":{"v1","v2",…}` block built from the up-to-13 `sParamValue1..13` columns. Joins entries with `,` and wraps the whole thing in `{…}`. Returns the result or `''`.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. Body design suggests it's invoked from form-master sSqlStr to populate process-param dropdowns, but no such row references it.
@@ -17,4 +17,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Bulk simplified-Chinese → Traditional-Chinese (Big5) refresh for the metadata catalog. Every UI label across `gdsmodule`, `gdsconfigformmaster`, `gdsconfigcharmaster`, `gdsconfigformslave`, `gdsformconst`, `gdsjurisdiction` is shipped in `sChinese` (simplified); the `sBig5` columns next to them hold the traditional rendering shown to Big5 tenants. This function re-derives `sBig5` from `sChinese` in one pass by piping every label through the lower-level `F_Gb2Big` per-string converter.
+
+**What it does:** runs an unconditional `UPDATE … SET sBig5 = F_Gb2Big(sChinese, 1)` on each of those six tables (plus the related `sBig5Depart`, `sBig5UnMemo`, `sBig5WorkFruit` on `gdsmodule` and `sBig5DropDown` on the const slave rows). Returns the empty string. Note: a sibling **procedure** of the same name (~2.2K body) does this in 1000-row paginated batches via cursor — likely the safer alternative on large catalogs.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. Typically run manually after deploying a new metadata catalog.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Bill-number arithmetic — `获取新增的单据号`. Takes a bill number with a numeric tail (e.g. `SO-2024-0001`) and produces the same prefix with the trailing counter incremented by `p_num`, preserving the original zero-padding width.
+
+**What it does:** splits the input by reusing `Fun_GetGb` (alpha-only prefix) and `Fun_GetNum` (digits-only tail). Casts the digits to int, adds `p_num`, then re-prefixes with the original prefix and re-pads with leading zeros so the total length matches the input. Returns the new bill number.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. Bill-number assignment in production flows through `SysBillNoSettings` / `Fun_GetBillNo`, not this helper.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** JSON-object builder — `组装MapJSON`. Appends a single `"key":"value"` pair to an existing JSON object (or creates a new one if empty), returning the merged JSON string.
+
+**What it does:** strips `{` and `}` from `p_JSON` to gauge non-emptiness. If empty, returns `{"p_Cloumn":"p_value"}`. Otherwise, snips the trailing `}` off `p_JSON` and concatenates `,"p_Cloumn":"p_value"}`. Pure string manipulation — does not parse or validate JSON.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. MySQL's native `JSON_SET` / `JSON_OBJECT` are preferred elsewhere in the codebase.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Inverse of `Fun_GetMaterialsQtyUnit` — given an **auxiliary** quantity (the purchasing/storage unit, e.g. 张/PCS/m) plus a material spec, returns either the equivalent **stocking-unit** quantity (when `iType=0`) or the auxiliary-unit name (when `iType=1`). Used during reverse formula calculation: `sFormulaIdType = sReComputeId`.
+
+**What it does:** reads the material's `EleMaterials` row (`sMaterialsUnit`, `sAuxiliaryUnit`, `dGramWeight`, `sConversionUnit`, `bReel`, `dCoefficient`, `bInverse`) plus tenant system settings `CbxMaterialsUnit` (MM/CM/INCH), `NetSquareM` (m² rounding decimals), `NetConversionRate` (inch conversion). Branches by spec format (`W*L`, `W*L*H`, plain numeric, blank) × unit family (Ton/吨/噸, KG, M2, M3, m, reel) × MM/CM/INCH dimension base. Each branch derives `dMaterialsQty` from `dAuxiliaryQty` using gram-weight or sheet-area math, picks a default `sAuxiliaryUnit` (`张`/`張`/`PCS`/`m`), and finally rounds: 张/PCS → `CEILING`; m → `ROUND(qty, NetSquareM)` (or CEILING if NetSquareM=0). Returns the quantity (iType=0) or unit string (iType=1).
+
+**Invocation:** invoked by `ReplaceFieldServiceImpl.getReplaceFieldReslut()` when the formula type is `sReComputeId` — the Java service synthesizes `SELECT Fun_GetAuxiliaryQtyUnit(...)` from material + slave-row context and runs it through `businessBaseDao.getByMap`. Also referenced by the bill-check family (`Sp_Check_sCmt`, `sLok`, `sMpa`, `sOis`, `sOpc`, `sOpi`, `sOpkg`, `sOpn`, `sOpn1`, `sOpp`, `sPca`, `sPca1`, `sPis`, `sPkg`, `sPmd`, `sPod`, `sPpa`) and inventory in/out procs (`SP_Inventory_InOutWarehouse`, `_All`, `_220709`, `_221111`).
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Numeric ID generator — header comment `生成27位纯数字的ID 模仿后台Java代码生成` ("27-digit numeric ID, mimics the Java backend"). The xly Java code mints all-numeric IDs by stitching together a timestamp and a counter; this is the SQL equivalent for procs that need to allocate IDs without a round-trip.
+
+**What it does:** returns `DATE_FORMAT(NOW(),'%y%m%d%H%i%s')` (12 digits, yyMMddHHmmss) concatenated with `LPAD(iIndex,2,'0')`. Final length is 14 — not 27 as the comment claims. Caller is expected to supply a monotonically increasing `iIndex` per second to avoid collisions.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. Production ID minting happens Java-side via `IdWorker`/`SnowflakeId`, leaving this as a stale convenience.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Per-form bill-number print/status setting — header `获取系统设定中 单据号设定 打印状态`. The bill-number admin module (`SysBillNoSettings`) lets tenants configure, per form × brand × subsidiary, how the bill number behaves at print/save time (auto-generate, manual, audit-locked etc., encoded in `sStatusType`). This function pulls that flag.
+
+**What it does:** if `sFormGuid` is non-empty, selects `sStatusType` from `SysBillNoSettings` where `sFormId/sBrandsId/sSubsidiaryId` match. Returns the value, or 0 if no row or no form.
+
+**Invocation:** invoked by the material-shortage / pull-pending bill family — `Sp_BillOfApply` and `Sp_BillOfApplyLine` (material apply by work order, gdsmodule `根据工单领料申请`), `Sp_BillOfNoPicking`, `_Cljg`, `_copy1` (no-pull-yet pending lists) — to gate behavior on the tenant's bill-number policy for the calling form.
@@ -18,4 +18,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Book-binding glue-allocation rounding rule. In book manufacturing, glue/`贴` is dispensed in quarter-unit increments; the planning system rounds fractional sticker quantities to the discrete pour size before charging materials.
+
+**What it does:** lookup table on `dQty`: 0.125 → 0.125; 0.25 → 0.25; 0.375 → 0.25; 0.5/0.625/0.75/0.875 → 0.5; all other values pass through unchanged. Returns 0 if NULL.
+
+**Invocation:** called from `Sp_Manufacture_InsertMftPlanBook` (book-style manufacturing plan generator) and the formula-engine replace-field family `Sp_System_ReplaceField`, `Sp_System_ReplaceFieldNew`, `Sp_System_ReplaceField_Detail`, `Sp_System_ReplaceField_NEW`, `Sp_System_ReplaceField_NEW_ACT` — those procs in turn are driven by `BtnCalculationServiceImpl` (`doSetTimeCalcMachineHour`) via the cost-formula module `成本公式`.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Sheets-per-stock estimator (`Ks` = 开数, the printing trade's "ups count"): given a parent sheet `dMatLength × dMatWidth` and a finished piece `dLength × dWidth`, returns how many finished pieces can be cut from one parent sheet. Used by the quotation and work-order calculation procs to derive material consumption.
+
+**What it does:** simple axis-aligned packing — returns `(dMatLength div dLength) * (dMatWidth div dWidth)`. The full mixed-orientation packing logic (vertical + horizontal arrangements) is commented out in the body, leaving only the straight tile. `Fun_GetCalcMaterialsKs1` is the kept-alive richer variant that the commented branches would have called.
+
+**Invocation:** invoked by the quotation calc family (`Sp_Quotation_CalcDataBookStd`, `_CalcDataFlex`, `_CalcDataPackStd`, `_CalcDataSetStd`, `_CalcDataStd`, `_CalcDataPackLastStd`, `_CalcDataPackLastStd_zr`, `_CalcDataPackPartsStd`) and the work-order calc family (`Sp_WorkOrder_CalcDataBookStd`, `_CalcDataFlex`, `_CalcDataPackLastStd`, `_CalcDataPackPartsStd_child`, `_CalcDataPackStd`, `_CalcDataSetStd`, `_CalcDataStd`, `_CalcDataStdBeforeAfter`, `_CalcDataStdCenterProcess`, `_CalcDataStdCenterPrsAfter`) — all of which sit on the `报价&估计管理` quotation modules and the `轮转工单`/`合版工单` work-order modules.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Mixed-orientation `Ks` (开数, ups count) variant of `Fun_GetCalcMaterialsKs`. Computes how many finished pieces can be cut from a parent sheet using a vertical-then-horizontal hybrid layout, with optional row/column deductions (`iMinusL`, `iMinusW`) to reserve gripper/trim margins.
+
+**What it does:** normalizes long/short sides of both parent and piece. Computes two candidate tile counts: vertical-row (`(L div pL - iMinusL) * (W div pW)`) and horizontal-row (`(L div pW) * (W div pL - iMinusW)`), each augmented with a "leftover strip" rotated-piece bonus when the residual width fits. Returns the larger of the two, clamped at 0.
+
+**Invocation:** referenced by `Fun_GetCalcMaterialsKs` — but only inside commented-out lines (variant comparison was disabled). With those branches dormant, this function has no live caller in any channel — candidate for maintainer audit.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** String filter — header says `获取字符串中数字` ("extract digits from a string") but the body actually returns characters that do **not** match the regex `[u0391-uFFE5]` (the literal `u`-prefixed pattern is invalid; MySQL falls back to matching only the letter `u` and the ASCII range `0391`-`FFE5`, so the filter is effectively a no-op character whitelist). After stripping `-` and `+`, it accumulates the remaining characters.
+
+**What it does:** strips `-` and `+`, then walks the string one char at a time appending each character whose REGEXP test against `'[u0391-uFFE5]'` is not 1. Effective behavior: returns the input with `-`/`+` removed. Header comment is inconsistent with the body.
+
+**Invocation:** called from `Sp_Create_sControlFaceNameTable` and `Sp_Create_sControlFaceNameTableFive` (control/process-name table builders). With the regex broken, the filter step is a no-op — flag as bug suspect for maintainer audit.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Walks up the multi-level production BOM tree for a manufactured product (parts → semi-finished → finished). Returns either the top-level product sId (`iFlag=0`) or the matching sales-order line sId for that top-level product (`iFlag=1`). Used by work-order calc to resolve "what finished good does this sub-part belong to".
+
+**What it does:** queries `viw_mftproduct` (BOM view) for the row matching `sProductId`, then climbs through `sFatherSlaveId → sSlaveId` ancestors in a WHILE loop until `sFatherSlaveId` is empty (i.e. reached the root). For `iFlag=0` returns the root `sProductId`. For `iFlag=1`, if `sSrcId` (sales-order master sId) is supplied, looks up the matching `salsalesorderslave` line by `sParentId+sProductId` and returns its sId; otherwise returns the root product sId.
+
+**Invocation:** Status: appears orphaned in the live DB — the only references in xly-src are install scripts (`script/标版/30100101/Sp_Calc_sWod.sql` and `script/标版/optimize/Sp_Calc_sWod.sql`). The shipped `Sp_Calc_sWod` body in the live database does **not** reference this function, suggesting the call was removed from the 生产工单/轮转工单/合版工单 `Sp_Calc_sWod` calc proc after the install scripts were authored. Candidate for maintainer audit.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Prefix extractor — pulls the non-digit prefix of a bill-number-style string (the "header"/`国标` letters before the running counter). Header comment `获取字符串中数字` is misleading; the body keeps **non-digit** characters, not digits. Paired with `Fun_GetNum` (digits-only) it lets routines split `SO-2024-0001` style codes into prefix `SO-` and number `20240001`.
+
+**What it does:** walks the input one character at a time. For each char, tests `REGEXP '[0-9]'`; if it does **not** match (i.e. non-digit), appends to the result. Returns the assembled non-digit prefix.
+
+**Invocation:** called from `Fun_GetAddBillNo` (bill-number incrementer) and from the auto-scheduling family `Sp_OneDatePlan_Machine` (single-day machine-plan generator on form `1921168137117916508762815480` 机台计划达成日报), and `Sp_productionPlan_BtnEventAutoOrder3/4/5/6` (production-plan auto-order button events). Also referenced by `Sp_Create_sControlFaceNameTable`, `_TableFive/Four/One/Three/Two` (process-name builders).
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** "Hump" (峰) difference — `获取驼峰之间的差值`. Takes a comma-separated integer time-series and sums the rise heights of every monotonically increasing run (peak − trough), then totals them. Used by the production-dashboard reports to derive output-counter deltas from monotonically-resetting machine counters.
+
+**What it does:** two-pass. Pass 1 normalizes the series — for each comma-token, if the value drops vs. previous, inserts a `0` between them; this re-anchors each rising run to start from 0. Pass 2 walks the normalized series tracking current `p_min` and `p_max`; on each descent or at end-of-series, adds `max-min` to `p_diff`. Returns `p_diff`.
+
+**Invocation:** widely used by the production-board (`bd_` = 报表板/business dashboard) family — `Sp_Bd_bi16…bi24`, `Sp_Bd_cq_workshop_*` (车间 workshop boards: hh/mt/pj/pm/sy/ys), `Sp_Bd_hy_workshop_oy`, `Sp_bd_MachinePlanTemplate*` (机台计划 templates), `Sp_bd_McPlanConter`, `Sp_bd_McPlanRate`, `Sp_bd_TmComplianceRate*`, `Sp_bd_TmSpeed*`, `Sp_bd_TmYield*`. Customer override exists at `script/客户/.../Sp_Bd_Cqzy_Report*` (前一天/今天 白班/晚班).
@@ -18,4 +18,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** JSON-array length helper. Trivially thin wrapper for callers that want a `"未解析到Key"` sentinel instead of an error when the input is malformed.
+
+**What it does:** if `JSON_VALID(sJson) = 1`, returns `JSON_LENGTH(sJson)`. Otherwise returns the string `"未解析到Key"`.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** KPI/SLA deadline calculator (`获取任务截至时间`). Given a form id and a starting timestamp, projects a "must-finish-by" datetime using the per-form working-hour configuration stored in `kpimodule` — used pervasively by the overdue/未付/未收 warning reports (采购预警, 应付/应收, 销售未发货, etc.).
+
+**What it does:** reads `kpimodule.dLimitation`/`sLimitTime`/`sWorkDate` for the form (matched on `sBrandsId`, `sSubsidiaryId`, `sModelId = sFormId`). Snaps the start time inside the configured working window, then converts the limitation hours into working-minutes and walks forward whole work-days plus a partial day, returning the projected deadline.
+
+**Invocation:** called from `Sp_Cashier_OrderMoneyWarning`, `Sp_Manufacture_PurPurchaseChecking`, `Sp_Manufacture_SalSalesChecking`, `Sp_Manufacture_sSodPurchareMaterials`, `Sp_NotPayAbles*` family, `Sp_NotReceivables*` family, `Sp_OEE_PlanByProcess`, `Sp_OverdueNoCheck`, `Sp_OverdueNotReceivables`, `Sp_Sales_NotDeliverGoodMaterials*`, `Sp_SalSalesCheck_YanBao` — every overdue/limit-aware report runs each row through this. Java references in `KpiServiceImpl` and `CommonFromSqlServiceImpl` are commented out; current invocation path is proc-only.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Pretty-printer for an entire JSON array of key/value objects — renders every row of an embedded JSON parameter list as `name:【value】` joined by `;` for display in a single report cell. Sibling of `Fun_GetListJson_ByKey` (which fetches one keyed value) and the `_split`/`_wrap` variants (which add line breaks every N items).
+
+**What it does:** iterates `sJson`. For each element extracts `$.sKey` (becomes the name) and `$.sGetKey` (becomes the value), strips JSON quotes, and appends `name:【value】` to the running string with `;` between rows. Returns empty string when `sJson` is not valid JSON.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Pretty-printer for a JSON array of key/value objects with periodic line-break wrapping — same family as `Fun_GetListByJson_ByKey`, but inserts a `\n` every `iNum` items so long parameter lists wrap cleanly in a fixed-width report cell.
+
+**What it does:** iterates `sJson`, extracts `$.sKey` and `$.sGetKey` from each element, strips quotes, and appends `name:【value】` joined by `;`. When the row index modulo `iNum` is zero (and not the first row), inserts `\n` before the next `;`. Returns empty string for invalid JSON.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Pretty-printer variant of `Fun_GetListByJson_ByKey_split` with a slightly different wrap rule. The `\n` is placed after the `;` separator and the wrap-condition uses `p_i <> 1` instead of `<> 0`, which produces a different first-row behaviour.
+
+**What it does:** iterates `sJson`, extracts `$.sKey` and `$.sGetKey` per element, strips quotes, joins with `;`. Inserts `\n` between the separator and the next item once per `iNum` rows. Returns empty string for invalid JSON.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. Almost certainly a tweak experiment alongside `_split`.
@@ -18,4 +18,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Combined-parts label builder used by the work-order data-pack reports. When a work-order has a 拼版 / combine layout that ganged-up several child parts, this function renders the part-name list (joined by `+`) for the work-order report row.
+
+**What it does:** splits the comma-separated `sCombineChildControlId` via `Fn_split_string`, looks up `sPartsName` from `mftworkordercontrol` for each id, and concatenates with `+` separators. Returns empty string if no ids.
+
+**Invocation:** called by `Sp_reportdata_WorkOrder`, `Sp_reportdata_WorkOrder1`, `Sp_reportdata_WorkOrder3` against `A.sCombineChildControlId` and `B.sCombineChildControlId` when rendering work-order print-data packs.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Generic key-indexed lookup against a JSON array. Given an array `sJson` and a `(sKey, sKeyValue)` pair, finds the first element where `$.sKey = sKeyValue` and returns the value at `$.sGetKey`. Used by production-report check and OEE/work-order data-pack procs to pull a named field out of a JSON parameter list.
+
+**What it does:** iterates the array; for each element extracts `$.sKey`, compares against `sKeyValue`; on match returns `REPLACE(JSON_EXTRACT($.sGetKey), '"', '')`. Returns `"未解析到Key"` when no element matches or input is not valid JSON.
+
+**Invocation:** called from `Sp_Check_mftProductionReportValue`, `Sp_Check_mftProductionReportValueTest`, `Sp_OEE_ProductionReport`, `Sp_OEE_ProductionReportAll`, `Sp_WorkOrder_CalcDataPackProductStd`.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Variant of `Fun_GetListJson_ByKey` where the lookup key is hard-coded to `$.sParamKey`. Given an array of `{sParamKey: X, …}` objects, finds the element with `sParamKey = sKeyValue` and returns the value at `$.sKey`. Tailored to the JSON-encoded parameter pairs used in the MFT/work-order schema.
+
+**What it does:** iterates `sJson`, reads `$.sParamKey` per element, compares to `sKeyValue`; on match returns the stripped `$.sKey`. Returns `"未解析到Key"` on no match or invalid JSON. (The `Else RETURN p_sKeyValue` branch is commented out.)
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. The script file `Fun_GetListJson_ByKey1.sql` is the function definition itself, not a caller.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Near-duplicate of `Fun_GetListJson_ByKey1` — same hard-coded `$.sParamKey` lookup, same return-on-match logic. The only difference is the commented-out `Else` branch is removed in this version. Used in the same production-report and work-order data-pack procs that consume JSON parameter lists.
+
+**What it does:** iterates `sJson`, reads `$.sParamKey` per element, compares to `sKeyValue`; on match returns the stripped `$.sKey`. Returns `"未解析到Key"` on no match or invalid JSON.
+
+**Invocation:** called from `Sp_Check_mftProductionReportValue`, `Sp_Check_mftProductionReportValueTest`, `Sp_OEE_ProductionReportAll`, `Sp_WorkOrder_CalcDataPackProductStd`.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Identical-shape variant of `Fun_GetListJson_ByKey2` — same hard-coded `$.sParamKey` lookup over a JSON array — but returns the empty string `""` instead of `"未解析到Key"` when no element matches. Useful when the caller wants to fold the result into a `CONCAT` without sentinel pollution.
+
+**What it does:** iterates `sJson`, reads `$.sParamKey` per element, compares to `sKeyValue`; on match returns the stripped `$.sKey`. Returns `""` on no match or invalid JSON.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Byte-for-byte the same shape as `Fun_GetListJson_ByKey5` — hard-coded `$.sParamKey` lookup returning `""` on miss. Differs only in name; presumably a copy made for a specific caller.
+
+**What it does:** iterates `sJson`, reads `$.sParamKey` per element, compares to `sKeyValue`; on match returns the stripped `$.sKey`. Returns `""` on no match or invalid JSON.
+
+**Invocation:** called from `Sp_OEE_ProductionReport`.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** "New" variant of `Fun_GetListJson_ByKey` — accepts the lookup column as a parameter `sKey` (rather than hard-coding `$.sParamKey`) and on match returns the value at `$.sGetKey`. Effectively a duplicate of `Fun_GetListJson_ByKey`; likely created during a refactor and never adopted by callers.
+
+**What it does:** iterates `sJson`, extracts `$.sKey` per element, compares to `sKeyValue`; on match returns the stripped `$.sGetKey`. Returns `"未解析到Key"` on no match or invalid JSON.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Backup / snapshot variant of `Fun_GetListJson_ByKey` (`_copy1` suffix). Per wiki convention, backup objects are not narrated (see [the index](../../index.md#whats-out-of-scope)).
+
+**What it does:** Same as `Fun_GetListJson_ByKey` at the time of copy.
+
+**Invocation:** Not expected to be called from production code; verify before relying on it.
@@ -19,4 +19,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Named-parameter extractor for the standard `{sParamName, sParamValue}` JSON shape used to pickle MFT/scheduling/report run-time settings (`喷头个数`, `码样`, `喷码类型`, `走纸方向`, `印刷类型正面`, …). Given a JSON array and a name, returns the matching value.
+
+**What it does:** iterates `sJson`, reads `$.sParamName` per element, compares to `sGetKey`; on match returns the stripped `$.sParamValue`. Returns `"未解析到Key"` on no match or invalid JSON.
+
+**Invocation:** called from `Sp_GetMachineByApsRule` (APS machine-selection rule engine) and `Sp_Manufacture_ProductionPlanInfoTree_Base_TC` (production-plan info-tree builder, where it decodes the per-row `sReportParams` to populate `sReportParams1..N` display columns).
@@ -19,4 +19,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** APS-flavoured variant of `Fun_GetListJson_ByName` — same `{sParamName, sParamValue}` lookup, but returns the empty string on miss instead of `"未解析到Key"`. Used by the APS machine-selection rule engine to decode equipment-attribute parameters without polluting downstream `CONCAT`s.
+
+**What it does:** iterates `sJson`, reads `$.sParamName` per element, compares to `sGetKey`; on match returns the stripped `$.sParamValue`. Returns `""` on no match or invalid JSON.
+
+**Invocation:** called from `Sp_GetMachineByApsRule`.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Login-id resolver. Looks up a user in `sftlogininfo` by either username or sId (`sUserName = sLogin_id OR sId = sLogin_id`) scoped to `(sBrandsId, sSubsidiaryId)`, and returns the canonical `sId`. Used both by the workflow/messaging Java layer to normalize todo-list user ids and by the embedded SQL of the 采购管理 / 生产管理 detail forms.
+
+**What it does:** `SELECT sId INTO p_sReturn FROM sftlogininfo WHERE sBrandsId = … AND sSubsidiaryId = … AND (sUserName = sLogin_id OR sId = sLogin_id) LIMIT 1`. Returns the value (or `NULL`).
+
+**Invocation:** invoked from `SysWebSocketOffLineMsgServiceImpl` (resolves `todo_user_id` and `copyto_user_id` to user sIds when assembling offline workflow messages); embedded in form-master sSqlStr for 采购申请明细, 采购订单明细, 生产补料明细, 生产领料明细, 生产退料明细 under 采购管理 / 生产管理. Also reused by the workflow `Sp_Apply_Flow_*` and `Sp_Add_Flow` family.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Login-language resolver. Returns the per-user UI language code (`sLanguage`) for a username-or-id within a `(sBrandsId, sSubsidiaryId)` tenant. Used to localize numeric formatting and field labels in the 采购/生产明细 reports and in receivable/payable summary procs.
+
+**What it does:** `SELECT sLanguage INTO p_sReturn FROM sftlogininfo WHERE sBrandsId = … AND sSubsidiaryId = … AND (sUserName = sLogin_id OR sId = sLogin_id) LIMIT 1`.
+
+**Invocation:** embedded in form-master sSqlStr for the same five detail forms as `Fun_GetLoginUser` (采购申请明细, 采购订单明细, 生产补料明细, 生产领料明细, 生产退料明细). Also called from `Sp_Calc_sPmt`, `Sp_Calc_sRct`, `Sp_Manufacture_ProductionArrange2`, `Sp_NotReceivables_hz`.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Backup / snapshot variant of `Fun_GetLoginUserLanguage` (`_copy1` suffix). Per wiki convention, backup objects are not narrated (see [the index](../../index.md#whats-out-of-scope)).
+
+**What it does:** Same as `Fun_GetLoginUserLanguage` at the time of copy.
+
+**Invocation:** Not expected to be called from production code; verify before relying on it.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Login-display-name resolver — the inverse of `Fun_GetLoginUser`. Given a username or user sId, returns the human-readable `sUserName` from `sftlogininfo`, scoped to a `(sBrandsId, sSubsidiaryId)` tenant. Used by the workflow/check-flow procs to render reviewer names in approval-history strings and notification messages.
+
+**What it does:** `SELECT sUserName INTO p_sReturn FROM sftlogininfo WHERE sBrandsId = … AND sSubsidiaryId = … AND (sUserName = sLogin_id OR sId = sLogin_id) LIMIT 1`.
+
+**Invocation:** called from `Sp_Bill_Used`, `sp_get_unTodo`, `sp_get_unTodo_Apply`, `Sp_Quotion_CheckFlow_BH1`, `SP_Return_Flow`, `Sp_System_CheckFlow` — every place where an approver/reviewer id needs to be expanded to a display name for notification or audit text (e.g., `GROUP_CONCAT(Fun_GetLoginUserName(U.sUserId, …))`).
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Login-permission helper — intended to flag whether the supplied login is the `sysadmin` super-user (returns `'1'`) so callers can skip data-scope filters.
+
+**What it does:** Selects `sType` from `sftlogininfo` for the given (brand, subsidiary, login). Returns `'1'` if `sType = 'sysadmin'`, else `'0'`.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master, gdsmodule hooks, other routines, xly-src grep) — candidate for maintainer audit. Note the page header `获取客户查看权限` matches the role of the sibling pair `Fun_GetLookCustomer`/`Fun_GetLookProcess`, which embed the sysadmin check inline instead of delegating here.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Customer data-scope filter — when system setting `CkxLookCustomer = 1` and the caller is not `sysadmin`, returns the comma-separated `EleCustomer.sId` list this login is allowed to see (joined through `sftlogininfocustomergroup.sSalesManId`); otherwise returns `''` meaning "no restriction".
+
+**What it does:** Reads `SysSystemSettings.CkxLookCustomer`, checks `SftLoginInfo.sType`, then `GROUP_CONCAT`s the customer IDs assigned to the login's permission group.
+
+**Invocation:** Embedded as an `IN (Fun_GetLookCustomer(...))` filter clause in sales / receivables / manufacturing reports — called by `Sp_financial_CustomerGrossProfit`, `Sp_financial_OrderGrossProfit*` (multiple variants), `Sp_financial_SaleManGrossProfit`, `Sp_financial_EasyCost`, `Sp_Manufacture_MftPlanPhase*`, `Sp_Manufacture_ProcessReport`, `Sp_Manufacture_ProductionArrange`, `Sp_Inventory_ProductInOutStore_new`, `Sp_GetOrder_Process`, etc.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Process (工序) data-scope filter — when system setting `CkxProcessFilter = 1` and the caller is not `sysadmin`, returns the comma-separated `sProcessClassifyId` list this login may see (joined through `sftlogininfoprocessgroup`); otherwise returns `''`.
+
+**What it does:** Reads `SysSystemSettings.CkxProcessFilter`, looks up `SftLoginInfo.sType`, then `GROUP_CONCAT`s the process-classification IDs bound to the login's permission group.
+
+**Invocation:** Embedded in manufacturing / quality-inspection report SQL — called by `Sp_Manufacture_PlanReport`, `Sp_Manufacture_ProcessReport`, `Sp_Manufacture_ProductionPlanInfo_WorkCenter`, `Sp_Manufacture_ProductionReport`, `Sp_Manufacture_Report`, `Sp_OEE_PlanByProcess`, `Sp_OEE_ProductionReport`, `Sp_Mobile_PatrolInspection`, `Sp_PC_FirstInspection`, `Sp_PC_PatrolInspection`, `Sp_Productionplan_Pie_Char*`. Sibling of `Fun_GetLookCustomer`.
@@ -19,4 +19,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Hard-coded machine-size matching helper — returns `1` if the long side exceeds 1020 or the short side exceeds 720 (probably the limits of a specific press size class), else `0`. The thresholds are literal magic numbers in the body.
+
+**What it does:** Sorts the two dimensions so length ≥ width, then flags when the sheet exceeds 1020×720.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master, gdsmodule hooks, other routines, xly-src grep) — earlier substring matches against `Sp_GetMachineByApsRule` resolve to the sibling `Fun_GetMachineLenWidthAPS`, not this one. Candidate for maintainer audit; the parameterised APS variant has superseded it.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** APS (advanced planning) machine-eligibility check — given a sheet's `sMachineLength`/`sMachineWidth` and a candidate machine's `(dMin..dMax) × (dMin..dMax)` window, returns `1` when the sheet falls outside the window (i.e. the machine is unsuitable), else `0`.
+
+**What it does:** Sorts length ≥ width, then flags out-of-range against the four limits in either orientation.
+
+**Invocation:** Called by `Sp_GetMachineByApsRule` — the procedure that ranks/filters machines when auto-assigning a work order to a press, comparing the order's sheet size against each machine's configured min/max. Parameterised replacement for the now-orphan `Fun_GetMachineLenWidth`.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Machine shift-window helper — given a press (`iPlcNo`), returns the **end** of the current shift based on the machine's `elemachine.sOffWork` / `sShiftsWork` clock settings (default `8:00` / `17:30`). Counterpart to `Fun_GetMachineWorkStartDate` and `Fun_GetMachineWorkWorkType`.
+
+**What it does:** Reads the machine's day-shift boundaries from `elemachine`, classifies `NOW()` as day or night side, then returns the corresponding `'sOffWork'`/`'sShiftsWork'` datetime on today's date.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master, gdsmodule hooks, other routines, xly-src grep beyond the routine's own deployment SQL) — candidate for maintainer audit. The sibling `Fun_GetMachineWorkStartDate` and `Fun_GetMachineWorkWorkType` are reachable via `Sp_bd_MachinePlanStatus`/`Sp_bd_McPlanConter`/`Sp_bd_McPlanRate`; the End variant has no current consumer.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Machine shift-window helper — given a press (`iPlcNo`), returns the **start** of the current shift, including the previous shift when `NOW()` falls in the night window (i.e. before `sOffWork`). Used to define "current shift" for machine OEE / 排产 dashboards.
+
+**What it does:** Reads `elemachine.sOffWork` / `sShiftsWork` (default `8:00` / `17:30`), classifies `NOW()` as day-side or night-side, then returns either today's `sOffWork` or yesterday's `sShiftsWork`/`sOffWork` accordingly.
+
+**Invocation:** Called by `Sp_bd_MachinePlanStatus`, `Sp_bd_McPlanConter`, `Sp_bd_McPlanRate` — the machine-board (机台看板) status / completion / rate procedures that surface real-time shift progress on the production-floor displays.
@@ -22,4 +22,10 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Machine shift-window classifier — given a press (`iPlcNo`), returns the literal string `'sOffWork'` when `NOW()` is in the day-shift window or `'sShiftsWork'` when in the night/off-hours window. The catalog header `获取当前机台属于什么班` summarises the intent.
+
+**What it does:** Reads `elemachine.sOffWork` / `sShiftsWork` (default `8:00` / `17:30`); compares `NOW()` against today's `[sOffWork, sShiftsWork)` interval.
+
+**Invocation:** Called by `Sp_bd_McPlanConter` — the machine-board shift-completion counter that needs to know which shift to attribute current output to. Sibling of `Fun_GetMachineWorkStartDate` (full window) and the orphan `Fun_GetMachineWorkEndDate`.
+
+Note: declared return type is `datetime` but body returns a `varchar` literal — type mismatch is harmless but worth flagging.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Material-quantity / unit conversion core — given an auxiliary qty in sheets (张/PCS), the material spec (size `WxH` or `WxHxThickness` and `EleMaterials` row), returns either the **converted material qty** in the storage unit (`iType=0`) or the **resolved auxiliary unit name** (`iType=1`). Drives every quotation, work-order, inventory, and check procedure that needs to translate between purchase units (吨/Ton/KG/M2/M3/M) and counting units (张/PCS).
+
+**What it does:** Reads `EleMaterials.dGramWeight`, `sMaterialsUnit`, `sAuxiliaryUnit`, `bReel`, `dCoefficient`, `bInverse`; parses the `*`-delimited style; branches on (dimension count, reel flag, material unit) and applies the appropriate area×gram-weight formula scaled by the global `CbxMaterialsUnit` system setting (`MM`/`CM`/`INCH`) — `INCH` uses `NetConversionRate` to convert to metric.
+
+**Invocation:** Called dynamically by Java service code — `CalculationStdServiceImpl` builds `Select Fun_GetMaterialsQtyUnit(...)` SQL during quotation/work-order standard-cost calculation, and `ReplaceFieldServiceImpl` substitutes the function name as `sFunName` when resolving derived columns. Also called from many `Sp_Calc_s*` / `Sp_Check_s*` / `Sp_Quotation_Calc*` / `Sp_WorkOrder_Calc*` / `SP_Inventory_InOutWarehouse*` procedures (52 stored-routine callers). Sibling: `Fun_GetMaterialsQtyUnitSupple` (board-with-thickness variant).
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Supplementary material-qty conversion — the board / 瓦楞 (corrugated) variant of `Fun_GetMaterialsQtyUnit`. Loads the same `EleMaterials` row but additionally pulls `dThickness`, then forces the carrier unit to `'M'` (length) and folds thickness into `dGramWeight`, so the same area×weight formulas yield linear-meter consumption for sheet/board stock.
+
+**What it does:** Same dispatch as `Fun_GetMaterialsQtyUnit` (parse style, branch on dimension count / unit / reel flag, apply `CbxMaterialsUnit`-scaled formula), but with `sMaterialsUnit ← sAuxiliaryUnit`, `sAuxiliaryUnit ← 'M'`, `dGramWeight *= IFNULL(NULLIF(dThickness,0),1)` applied up front.
+
+**Invocation:** Called by `Sp_Quotation_CalcDataFlex` and `Sp_WorkOrder_CalcDataFlex` — the soft-pack / 柔性 quotation and work-order cost-calculation procedures (the "Flex" branch in 报价 / 工单 standard-cost). Sibling of `Fun_GetMaterialsQtyUnit`.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Numeric-substring extractor — pulls the digits (and `.`) out of a free-form string while preserving the **first run** of contiguous digits/decimals, dropping leading zeros until a `1-9` appears. Used in 排产 / 控制面 编号 helpers where a bill number or table name embeds a number that needs to be peeled out.
+
+**What it does:** Walks `str` char by char; once a `1-9` is seen, appends subsequent digits and `.` to the output; non-numeric chars are skipped; returns the accumulated string.
+
+**Invocation:** Called by `Sp_Create_sControlFaceNameTable` / `*Two` / `*Three` / `*Four` (control-face table-name builders), `Sp_Manufacture_ProductionPlanInfo_detail` / `*Lock_detail`, `Sp_productionPlan_BtnEventAutoOrder3`–`9` (auto-排产 button handlers), and function `Fun_GetAddBillNo` (bill-number incrementor).
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** First-digit-position locator — returns the 1-indexed position of the first `0-9` in `str`, or `0` if none. Catalog header: `获取字符串中数字首次出现位置`.
+
+**What it does:** Walks `str` char by char, regex-tests `[0-9]`, returns the index on first hit.
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master, gdsmodule hooks, other routines, xly-src grep beyond the routine's own deployment SQL) — candidate for maintainer audit. Sibling `Fun_GetNum` is heavily used; this position-only variant has no current consumer.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** OEE管理 → 打印成品标签(OEE) — when printing finished-product carton labels, decides how many pieces go into one pack based on the product's paper size (A5/A4/A3/A2/A1, 32开/16开/8开/4开/2开, or explicit `WxH` like `210*140`, `285*210`, `570*870`) so each carton stays under a per-size cap (5000, 2500, or 2000 pieces, scaled by `CEIL(qty/cap)`).
+
+**What it does:** A large `CASE` keyed on `LOCATE(<size>, p_sProductStyle)`; for each size class, returns either the full qty when it fits in one carton, or `qty / CEIL(qty / cap)` (an even split into the minimum number of cartons). Unknown styles return `null`.
+
+**Invocation:** Embedded in form `gdsconfigformmaster.sId='16054917120005195223325896784000'` (parent module `打印成品标签(OEE)` → `OEE管理`), alongside the sibling `Fun_GetTrunkQty`, against `mftworkorderslave` + `eleproduct`.
@@ -23,4 +23,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Process-step area conversion — when a process records its qty in 张 (sheets) but the material is stocked in `M2`, converts sheet-count to square-metres using the sheet size (`WxH` parsed from `sMaterialsStyle`) and the global `CbxMaterialsUnit` system setting (`MM`/`CM`/`INCH`, with `NetConversionRate` for inch→m). When the auxiliary unit already matches the material unit or the material unit isn't `M2`, returns `dAuxiliaryQty` unchanged.
+
+**What it does:** Loads `CbxMaterialsUnit` (and `NetConversionRate` for INCH) via `Fun_GetSystemSetting`; counts `*` in style; if exactly one `*` and the units differ and material is `M2`, splits dimensions, computes `qty * left * right` with the scale factor for `MM`/`CM`/`INCH`; else passes qty through.
+
+**Invocation:** Called by `Sp_Check_sOis`, `Sp_Check_sOpc`, `Sp_Check_sOpkg`, `Sp_Check_sOpn`, `Sp_Check_sOpn1` — the `Sp_Check_*` audit procedures that verify per-process auxiliary quantities against material-unit totals in inspection/check workflows.
@@ -24,4 +24,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Reel (卷筒) variant of [`Fun_GetAuxiliaryQtyUnit`](Fun_GetAuxiliaryQtyUnit.md) — performs the same auxiliary-unit ↔ purchase-unit conversion for materials but is keyed off `MftWorkOrderMaterials` instead of `MftPurchaseDetailMaterials`. The work-order context lets it consult both the materials master (`EleMaterials.dGramWeight`, `bReel`, `bInverse`, `dCoefficient`) and the per-line auxiliary unit (`MftWorkOrderMaterials.sAuxiliaryUnit`).
+
+**What it does:** reads `NetSquareM`, `CbxMaterialsUnit` and `NetConversionRate` from `SysSystemSettings` (via `Fun_GetSystemSetting`); reads gram-weight/reel-flag/coefficient/inverse-flag from `EleMaterials` and the auxiliary/main unit from `MftWorkOrderMaterials`. Branches on `sMaterialsStyle` (e.g. `787*1092`), the material's main unit (`吨/噸/Ton/KG/克/M/M2`), and `iReel`, returning the converted quantity in the requested target unit. `iType=0` returns the converted quantity, `iType=1` returns the unit string.
+
+**Invocation:** referenced only by `Sp_saveReturn_sPmd` (which itself has no discoverable caller). No form-master sSqlStr, gdsmodule hook, in-scope routine caller, or xly-src reference uses this function directly. Status: appears orphaned via dead-caller chain — candidate for maintainer audit. Compare with the production-active siblings `Fun_GetAuxiliaryQtyUnit` and `Fun_GetMaterialsQtyUnit`.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Logistics-type report-id dispatch — maps a logistics document type flag (`1` = 送货单 / delivery note, anything else = 其它单 / generic logistics doc) onto one of two hard-coded `report.sId` GUIDs so the print step can pick the right template.
+
+**What it does:** `IF p_iLogType='1' RETURN '17090989...'` (送货单 report) else `RETURN '17091030...'` (其它单 report).
+
+**Invocation:** no form-master sSqlStr, gdsmodule hook, other routine, or xly-src reference uses this function. Status: appears orphaned. No caller found in any channel — candidate for maintainer audit. Tenant-specific report `sId`s.
@@ -20,4 +20,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Core key-value reader for `SysSystemSettings` — the per-tenant system-config table that holds switches and numeric coefficients used throughout 生产 / 库存 / 销售 calculations (e.g. `CbxMaterialsUnit` = MM/CM/INCH unit choice, `NetSquareM` square-meter rounding flag, `NetConversionRate` for INCH→metric, plus hundreds of other named scalars). Every "should this branch behave one way or another?" question routes through this function.
+
+**What it does:** `SELECT sValue FROM SysSystemSettings WHERE sName=str AND sBrandsId=sBrId AND sSubsidiaryId=sSuId`, defaults to `'0'` when missing. Returns a `varchar(100)` — callers cast to numeric where they need to.
+
+**Invocation:** referenced by 37 stored routines and many xly-src `Sp_Calc_s*` / `Sp_Manufacture_*` SQL scripts. Heavy hitters include `Fun_GetAuxiliaryQtyUnit`, `Fun_GetMaterialsQtyUnit`, `Fun_GetMaterialsQtyUnitSupple`, `Fun_GetReelAuxiliaryQtyUnit`, `Fun_GetProcessAuxiliaryQty` and the entire `Sp_Calc_s*` family (s`Mma`, `Mmm`, `Mpa`, `Opi1`, `Paj`, `Pmd`, `Psa`, `Cut`, `Dgd`, `DYDgd`...) and `Sp_BillOf*` (`Apply`, `ApplyLine`, `NoPicking`, etc.). It is the canonical xly-side feature-flag/coefficient lookup.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Sample/打样 sales-order monthly counter — counts how many `salsalesorderslave` rows belong to orders of type `5` (打样 / sample order) created in the same calendar month as `tCreateDate`. `iType=1` adds an `iSucceed=1` filter to count only successful samples. Used for sample-volume KPI/打样次数 calculations. The header comment `获取字符串中数字` is wrong/copy-pasted from `Fun_GetNum` — body has nothing to do with digit extraction.
+
+**What it does:** branches on `iType`. Joins `salsalesorderslave` to `salsalesordermaster`, filters `sOrderType=5` and the month-window `[YYYY-MM-01, next-month-01)`, counts `sId`. Returns the count.
+
+**Invocation:** no form-master sSqlStr, gdsmodule hook, other routine, or xly-src reference uses this function. Status: appears orphaned. No caller found in any channel — candidate for maintainer audit (likely a KPI helper that was wired into a deprecated sample-order analysis form).
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Per-material sample-order monthly counter — sibling of [`Fun_GetTestCount`](Fun_GetTestCount.md). Counts how many sample-order (`sOrderType=5`) line rows reference a given material `sId` within the calendar month of `tCreateDate`. Used to gauge per-material 打样 frequency. The header comment `获取字符串中数字` is wrong/copy-pasted from `Fun_GetNum`.
+
+**What it does:** joins `salsalesorderslave` to `salsalesordermaster`, filters `sOrderType=5`, `sMaterialsId=sMaterialsId`, and the same `[YYYY-MM-01, next-month-01)` month window. Counts `sId`.
+
+**Invocation:** no form-master sSqlStr, gdsmodule hook, other routine, or xly-src reference uses this function. Status: appears orphaned. No caller found in any channel — candidate for maintainer audit.
@@ -21,4 +21,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Trunk/箱 count estimator for OEE finished-goods labelling (生产管理 → OEE → 打印成品标签(OEE), form sId `16054917120005195223325896784000`). Given a product style code (paper-size names like `A4`, `A3`, `8开`, or millimetre styles like `210*285`) and a piece count, returns how many shipping trunks the run will fill.
+
+**What it does:** big `CASE` over `LOCATE(<style-tag>, p_sProductStyle) > 0`: A5/210*140/32开/A4/210*285/16开 → `CEIL(qty/5000)`; A3/285*420/8开/A2/420*570/4开/A1/570*870/2开 → `CEIL(qty/2500)`; otherwise `NULL`. Returns the integer trunk count.
+
+**Invocation:** referenced by the OEE label-print form-master sSqlStr at sId `16054917120005195223325896784000` (生产管理 → OEE → 打印成品标签(OEE)). The xly-src copy lives under `script/标版/30000101/Fun_GetTrunkQty.sql` and the form-master upgrade script under `script/标版/20210323/gdsconfigformmaster.sql`. The conversion ratios are hard-coded paper-product values; non-paper businesses will see `NULL`.
@@ -18,4 +18,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Tiny string-utility — returns the contents of the first `[…]` bracket pair in the input. Building-block for the formula-resolution path that needs to extract one placeholder name at a time.
+
+**What it does:** one line: `substring_index(substring_index(userstr,']',1),'[',-1)`. Splits at the first `]`, takes the part before it, then splits that at `[` and returns everything after the last `[`. No table access.
+
+**Invocation:** called by [`Fun_Get_BracketContentAll_JSON`](Fun_Get_BracketContentAll_JSON.md), which loops to extract every `[…]` token in a string. No other caller in any channel.
@@ -18,4 +18,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Extracts every `[…]` placeholder out of a formula / template string and returns the names as a comma-joined, quoted list ready to splice into an `IN (...)` clause. Companion to [`Fun_Get_BracketContent`](Fun_Get_BracketContent.md), one level up in the same formula-resolution chain.
+
+**What it does:** counts the `[` characters in `userstr`, then in a loop pulls the first bracket pair via `Fun_Get_BracketContent`, appends `'<token>',` to the accumulator, and removes `[<token>]` from the source. Leaves when no more `[` remain. Returns the accumulator with the trailing comma trimmed (or empty string if no bracket was found).
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Plate color/ink counter — header `根据 + 分隔符，确定颜色数`. Operates on a JSON color-list string with optional face-doubling and process/spot color filter. Used by the work-order/quotation calc procs for paperboard/box products to estimate ink-station usage per face.
+
+**What it does:** upper-cases the input; counts how many `"SNAME":"C"`, `"M"`, `"Y"`, `"K"` substrings appear (CMYK process colors) and the total number of `}` (one per color entry). Then branches: `iFace=2` doubles the result (two-sided print); `iColorOrder=1` returns CMYK process count, `iColorOrder=2` returns the spot-color complement `(total - CMYK)`. Returns 0 for any other combination.
+
+**Invocation:** invoked by `Sp_Manufacture_InsertMftPlanSlave` (轮转/合版 manufacturing-plan slave), `Sp_Quotation_CalcDataPackProductStd` (paperboard quotation calc), and `Sp_WorkOrder_CalcDataBsProductStd` (paperboard work-order calc) — together with the customer-override copies in `script/客户/{千彩,快马,金宣发,上海亚峰}` indicating site-specific tweaks against this same routine.
@@ -22,4 +22,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** Body is byte-identical to `Fun_Getcolorcount`. `Test` suffix per wiki convention marks a staging copy retained for development comparison.
+
+**What it does:** same as `Fun_Getcolorcount` — counts CMYK process colors vs. spot colors in a JSON color list with face-doubling, branching on `iColorOrder` (1 = CMYK count, 2 = spot count) and `iFace` (2 = double for two-sided printing).
+
+**Invocation:** Status: appears orphaned. No caller found in any channel (form-master sSqlStr, gdsmodule hooks, other routines, exhaustive xly-src grep, dynamic-dispatch search) — candidate for maintainer audit. Test-only artifact; safe to drop after confirming with `Fun_Getcolorcount`.
@@ -18,4 +18,8 @@ _Body is not pre-cached. To inspect: `mysql --defaults-file=~/.my.cnf -e &#39;SHOW C
  
 ## Narrative
  
-_No human-written narrative yet._
+**Business context:** CMYK ink-count summer for the printing planner. Each plate-color JSON entry carries `sName` (C/M/Y/K or a spot-color name) and `dColor` (ink-station count). This variant counts only the CMYK process colors (`sName ∈ {C, M, Y, K, "C+M+Y+K"}`).
+
+**What it does:** walks the JSON array; per entry, if `sName` is one of the CMYK process names, accumulates `dColor`; non-process (spot) colors contribute 0. Returns the running sum. `Fun_Getcolorcount_CalcQty2` is the inverse — it sums spot colors only.
+
+**Invocation:** called from `Sp_Manufacture_InsertMftPlanSlave` (轮转工单 / 合版工单 manufacturing-plan slave inserter), where it splits the color/ink JSON into process-ink stations vs. spot-ink stations for the per-plate quantity bookkeeping.