朱子纯 / erp-framework-wiki

narrate_routines.md 7.53 KB

Routine Narratives — Playbook

Long-running job: write a business-context narrative for every procedure (1,687) and function (177) page in en/docs/auto-catalog/{procedures,functions}/, replacing the auto-generated _No human-written narrative yet._ placeholder under each page's ## Narrative heading.

Goal: a maintainer reading the page learns what business action this routine serves, not just what its parameter list is. The file:line citations live in reference/maintainer/; routine narratives stay business-first.

Narrative shape (≤ ~15 lines per routine)

**Business context:** [module path from gdsmodule.sChinese — leaf → root,
" → " separated] — [one sentence: what user action / business outcome
triggers this]

**What it does:** [terse mechanism, 1-3 sentences]

**Invocation:** [how it's reached — form-master sSqlStr, gdsmodule hook,
chained from another proc, JMS CHANGE_GDS_MODULE path, or "no callers
found (candidate dead code)"]

[Caveats / bugs / edge cases — only when worth flagging]

Three already-written samples for reference:

  • en/docs/auto-catalog/functions/Fn_find_modleAllId.md
  • en/docs/auto-catalog/procedures/sp_get_sOppositeColor.md (orphan example)
  • en/docs/auto-catalog/procedures/PRO_ERPMERGEBASESISWORKCENTER.md (denorm-merge family)

Lookup recipe (per routine)

ROUTINE="<name>"

# 1. Body
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai \
  -e "SHOW CREATE {PROCEDURE|FUNCTION} $ROUTINE"

# 2. Business-module location — form embeds (procs primarily)
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai -e "
  SELECT gfm.sId AS form_sId, m.sId AS module_sId, m.sChinese, m.sParentId
  FROM gdsconfigformmaster gfm
  LEFT JOIN gdsmodule m ON gfm.sParentId = m.sId
  WHERE gfm.sSqlStr      LIKE '%$ROUTINE%'
     OR gfm.sConfigSqlStr LIKE '%$ROUTINE%'
     OR gfm.sSqlCondition LIKE '%$ROUTINE%'"

# 3. Business-module location — module hooks (procs only)
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai -e "
  SELECT sId, sChinese, sParentId,
         sSaveProName, sSaveProNameBefore, sDeleteProName, sProcName
  FROM gdsmodule
  WHERE sSaveProName       = '$ROUTINE'
     OR sSaveProNameBefore = '$ROUTINE'
     OR sDeleteProName     = '$ROUTINE'
     OR sProcName          = '$ROUTINE'"

# 4. Climb the module tree for any sId found in #2 or #3 (replace MID)
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai -e "
  SELECT 1 d, sId, sChinese, sParentId FROM gdsmodule WHERE sId='MID'
  UNION SELECT 2, sId, sChinese, sParentId FROM gdsmodule
        WHERE sId=(SELECT sParentId FROM gdsmodule WHERE sId='MID')
  UNION SELECT 3, m3.sId, m3.sChinese, m3.sParentId
        FROM gdsmodule m3
        JOIN gdsmodule m2 ON m3.sId = m2.sParentId
        JOIN gdsmodule m1 ON m2.sId = m1.sParentId
        WHERE m1.sId = 'MID'
  ORDER BY d"

# 5. Other-routine callers (procs that CALL it, funcs that reference it)
mysql --defaults-file=~/.my.cnf xlyweberp_saas_ai -sNe "
  SELECT ROUTINE_TYPE, ROUTINE_NAME
  FROM information_schema.ROUTINES
  WHERE ROUTINE_SCHEMA = 'xlyweberp_saas_ai'
    AND ROUTINE_NAME != '$ROUTINE'
    AND ROUTINE_DEFINITION LIKE '%$ROUTINE%'"

# 6. Java / MyBatis XML / SQL-template refs
grep -rln "$ROUTINE" /Users/reporkey/Desktop/revs_engi_wiki/xly-src \
  --include="*.java" --include="*.xml" --include="*.sql" 2>/dev/null

Orphan rule: if #2 + #3 + #5 + #6 are all empty, the routine has no discoverable caller. Flag in the narrative as Status: appears orphaned. No caller found in any channel — candidate for maintainer audit.

sSaveProName/sSaveProNameBefore/sDeleteProName/sProcName live on gdsmodule, not on gdsconfigformmaster. The auto-catalog page text and older wiki drafts sometimes confuse this — trust the queries above.

Style rules

  • Keep Chinese module names in Chinese. sChinese is what the user sees in BACK. Don't translate 工作中心, 选择工序(轮转), etc. — translating breaks searchability against the live UI.
  • Use the three headings literally: **Business context:**, **What it does:**, **Invocation:**. Consistent shape aids scanning.
  • 1–3 sentences per section. ≤15 lines total. If the body is small and self-explanatory, the narrative can be shorter. Don't pad.
  • No file:line citations to xly-src in routine narratives. Those belong in reference/maintainer/. Exception: if the routine is uniquely tied to a single Java caller, name the class (not the line).
  • Cross-link only when load-bearing. Relative paths: ../../slices/..., ../../reference/maintainer/..., ../procedures/<other>.md, ../functions/<other>.md. Test that the target exists before adding the link.
  • Don't translate identifiers — proc/function/column/table names stay as written.
  • Don't editorialize ("interestingly", "it's worth noting") — state directly.
  • Don't claim Java callers without grepping. The lookup recipe's step 6 is the ground truth.

Resume protocol — what counts as "done"

A routine is done when its .md file's ## Narrative block contains anything other than _No human-written narrative yet._.

To get the live pending count and next batch:

cd /Users/reporkey/Desktop/revs_engi_wiki/xly-wiki

# Pending count
grep -l "_No human-written narrative yet._" \
  en/docs/auto-catalog/procedures/*.md \
  en/docs/auto-catalog/functions/*.md | wc -l

# Next 20 pending (alphabetical)
grep -l "_No human-written narrative yet._" \
  en/docs/auto-catalog/procedures/*.md \
  en/docs/auto-catalog/functions/*.md | sort | head -20

Persistence — gen_catalog.py is patched

Both en/scripts/gen_catalog.py and zh/scripts/gen_catalog.py now snapshot the ## Narrative (en) / ## 说明 (zh) block before the shutil.rmtree, and re-inject preserved content during the regen. So re-running the generator does not wipe human prose. Safe to regen at any time.

zh translation is a follow-up pass after en is complete. For now, write English narratives only.

Subagent prompt template

When the user says "continue", spawn ONE subagent with this prompt:

Read /Users/reporkey/Desktop/revs_engi_wiki/xly-wiki/en/scripts/narrate_routines.md
in full. It contains the goal, narrative shape, lookup recipe, style rules,
and resume protocol for adding business-context narratives to xly's stored
procedures and functions.

Identify the next N pending routines using the resume-protocol command in the
playbook. N = 20 (or fewer if the routines are large/complex — judge from the
ROUTINE_DEFINITION size: large bodies take longer to read; aim for ≤90 minutes
of work).

For each routine, in alphabetical order:

1. Run the Lookup recipe end-to-end. Capture findings.
2. Write the narrative in the shape the playbook specifies — three labelled
   sections, business-first, Chinese module names preserved.
3. Edit the .md file: replace `_No human-written narrative yet._` with the
   narrative prose. Leave the `## Narrative` heading and surrounding blanks
   intact.

Don't dispatch sub-subagents. Don't rebuild the site. Don't run gen_catalog.py.
Don't translate anything to Chinese.

When done with the batch:
- List the routine names processed, one per line.
- Run the resume-protocol command and print the new pending count.
- Note any orphans found (status: "no callers found") so the user can audit.
- Append a row to the Progress log table in narrate_routines.md.

Progress log

Date Procedures done Functions done Pending Notes
2026-05-11 2 1 1861 Initial 3 samples + gen_catalog.py preservation patch (en + zh)