朱子纯 / erp-framework-wiki

Editorial pass per user direction: stop justifying the architecture.
For every "why this design works" passage, name the costs the design
imposes — not as a parenthetical aside but as substantive critical
analysis. Each major architectural-claim page now carries an explicit
drawbacks/costs section.

Pages revised:

concepts/thesis.md
- "The reward" → "What the design enables (and what each enabler still costs)":
  for each promised benefit (single codebase, PMs evolve without
  engineering, customisations layered cleanly), name the limit. Added
  closing observation that data-driven design redistributes complexity
  to people and tools the framework can't compile-check.
- "When it breaks down": rewrote to call out that "bypassing the
  framework" via 18 customer dirs makes the data-driven thesis
  partial, not complete.

concepts/semantic-fk.md
- "Why xly disabled FKs": added critical analysis. Both reasons
  could be addressed surgically; the chosen "no FKs anywhere" is the
  trade for DB-enforced integrity, paid every day the system runs.

concepts/master-slave.md
- "Slave naming caveat": stop framing retention as wise pragmatism.
  The naming was a poor choice; preservation has a real ongoing cost.

concepts/modules-forms-vtables.md
- "Three nouns, one engine": the universal dispatch path concentrates
  3,500+ lines + edge cases + special-case hardcodes in one class.
  Naming the trade.

concepts/multi-tenancy.md
- "How the design scales" → "How the design scales — and where it
  doesn't": shared schema = shared contention; tenant-filter index
  discipline; no physical hard-delete; rigid (sBrandsId,
  sSubsidiaryId) tenancy unit.

concepts/customization-channels.md
- Soften "90%+ should live here" claim — that's an aspirational
  target, not a measured fact. The 18 customer override directories
  are evidence the channel-2 demand is non-trivial.

concepts/api-surface.md
- "Why three tiers, not one" → "Why three tiers (and what splitting
  them costs)": three WARs to deploy, duplicate code, no shared
  session, three reverse-proxy entries. Note the alternative
  (single-WAR with package boundaries) and what that would cost
  vs gain.

reference/maintainer/proc-dispatch.md
- "Why dynamic proc dispatch matters": added five concrete costs
  (no compile-time check, no type safety, no call-site discoverability,
  no static analysis, broken stack traces). Reframed: dynamic
  dispatch made it cheap to keep adding procs, which made the pile
  grow, which made the pile harder to audit.

reference/maintainer/cache-invalidation.md
- New "Drawbacks of this design" section: confusing co-named systems,
  eviction in same transaction as write (silent corruption on
  Redis outage), allEntries=true blunt eviction, no batching,
  direct DB writes bypass everything. Also fixed the "if cache is
  local" hedge in section 3 (we've now empirically confirmed Redis-
  backed, so cache is shared).

reference/maintainer/bi-engine.md
- New "Drawbacks of the homebrewed approach" section: every chart
  needs a SQL author, charts run heavy SQL on OLTP DB, no semantic
  consistency between charts, no drill-down, customer-divergent KPI
  logic. Also dedup'd the duplicated "What this is not" section.

reference/maintainer/sql-templates.md
- "Why this is a 'template' library and not a code generator" →
  added costs: no enforcement, no regeneration, no template-origin
  tracking, customer overrides drift from scaffold. The 1,687 procs
  the schema carries are the evidence that "discipline rather than
  enforcement" doesn't fully hold.

reference/maintainer/activiti.md
- "Why this design works for xly's audience" → "Why xly avoided
  Activiti — and what that costs": scattered workflow logic, no
  central audit trail, no parallel-branch/reassignment, invisible
  flow-graph evolution, idle Activiti engine paying boot cost
  anyway.
- "Why xly bothered with Activiti at all" → "Why xly bothered with
  Activiti — and whether it was worth it": named the costs (second
  engine, second schema, second auth surface, modeler UI to learn)
  and the damning fact that on this dev DB the engine is idle. A
  future cleanup could plausibly remove Activiti entirely.

reference/maintainer/runtime.md
- New "What 'universal CRUD' means in practice" section: 3,500-line
  single-point-of-failure class, no type system on Map<String,Object>,
  poor discoverability ("what endpoints write to table X" is
  unanswerable). The trade: adding a module is essentially free,
  touching the runtime essentially never is.
- Updated cache-invalidation cross-link to drop the "open question"
  hedge (now empirically resolved).

slices/04-custom-field.md
- "Why it works without code changes" → "Why it works without code
  changes — and what that costs": merge runs on every request,
  three near-empty tables on every schema, display-only extension
  (real persisted fields still need ALTER TABLE), debuggability
  requires diffing 3 overlay tables.

slices/05-customer-sql-override.md
- Added drawbacks: no version control on the deployed body, no
  type-safety bridge, compounds the BI problem. Reframed the
  "right rule of thumb": 18 customer override directories suggest
  the channel-2 demand is structural, not exceptional — that's
  evidence the metadata model isn't expressive enough, not a
  celebration of the escape hatch.

slices/06-hardware.md
- "The cleanest story xly tells about an awkward problem" →
  removed the "cleanest" framing. Added costs of "DB as the only
  contract": no backpressure, no request/response, bridge-side
  state invisible to the framework, three layers of polling
  multiply latency, hardest code (byte protocols) gets least CI.
  A real-time-aware architecture would use streaming end-to-end;
  xly's choice trades latency, observability, flow control for
  operational simplicity. Liveable for press tempo, not for
  faster shop-floor signals.

Plan: /Users/reporkey/.claude/plans/noble-tumbling-sparkle.md

Inventory: 33 hedge entries / open verification items across 12 hand-
written pages, clustered into 5 groups by why-they're-not-verified.

Cluster A — closed inline by reading source / running DB queries:

- slices/02-multi-tenancy item 1: edition gating is **not** sVersionFlowId
  → sisversionflow. Verified: `grep sVersionFlowId xly-src --include='*.java'
  --include='*.xml'` returns ZERO mapper hits. The actual filter is
  `MenuChildServiceImpl.getBuMenuSql` line 64: `AND m.sId in
  (#{sVersionFlowId... wait sVerifyLicense})`. sVerifyLicense is sourced
  from the TrueLicense-bound `VerifyLicense.getModelAllList()` and
  injected via xlyApi RequestAddParamUtil:50 or controller-level param
  assembly. sVersionFlowId/Code are catalogue tags, NOT runtime gates.
  Wiki body of "How modules are filtered per edition" rewritten.
- slices/02 item 2: closed; cross-link to the activiti.md rewrite that
  documents Activiti is wired-but-idle.
- slices/02 item 3: session→tenant chain mapped:
  AuthorizationInterceptor.preHandle → RedisTokenManager.getToken
  (AES-decrypts bearer, checkToken validates Redis at <sLoginType><userId>)
  → @CurrentUser via CurrentUserMethodArgumentResolver →
  RequestAddParamUtil.addParams injects 16 keys.
- slices/04 item 3: bVisible semantics closed.
  BusinessGdsconfigformsServiceImpl.java:413-433 — customslave row
  matches base by sControlName/sName, REPLACES base. Lines 446-468 —
  user-overlay then explicitly sets bVisible=false at line 464 when
  user-row hides the field. Hides at either layer; scope differs
  (per-tenant vs per-user).
- slices/05 item 1: DbToDbServiceImpl is inter-DB sync (getData/
  getDataDetail/etc. over Druid+JDBC), NOT a script-applier.
  `grep "script/客户" xly-src --include='*.java'` returns zero. Manual
  application via mysql CLI confirmed.
- slices/06 item 2: PlcScheduledTasks ships two @Scheduled cron methods
  (`0/30 * * * * ?` line 74, `0/1 * * * * ?` line 105). Per-profile
  tuning is parameter-side, not cron-side.
- slices/06 item 3: xlyRxtx git history — added in commit daf581311
  ("1、添加串口功能"), commented out in cleanup branch for builds where
  serial isn't needed. xlyPlc runs without RXTX on TCP/Ethernet press
  models; serial-only models would re-enable.
- builder/define-vtable item 1: 11 of 307 sTbName values (3.6 %) don't
  resolve to a base table. Breakdown: 4 point at views (viw_*),
  3 at procs (Sp_*), 4 at case-drift / dropped tables.
  Audit query embedded.
- builder/define-vtable hedge: real worked example added — `包装方式 /
  SisPacking` with 10 slave columns mapped to physical columns.

Cluster B — closed via live BACK browser session:

- slices/04 item 1: 界面显示内容配置 (gdsmodule.sId=11, /jmnrpz)
  renders three form-master panels. Third panel
  (sId=19211681019715596285250620, sTbName=gdsconfigformcustomslave)
  is the customslave editor. Verified live via clicking the menu and
  inspecting the GET /business/getBusinessDataByFormcustomId call.

Cluster D — left in place with "Deferred (needs populated DB)" admonition:

- slices/03 item 1 (view-with-print-template): no view-backed forms
  with a sysreport row — DB query returns 0.
- slices/04 item 4 (real customslave example): COUNT(*) = 0.
- slices/07 stub (active workflow): act_re_procdef = 0; bCheckflowCheck
  hard-disabled regardless.
- builder/attach-workflow stub: same — recipe is code-derived
  hypothesis, not live-verified.

Cluster E — left in place with "Deferred (outside repository)" admonition:

- slices/06 item 1 (wire protocols): vendor docs, not source.
- deployment.md "Open: production URL routing": nginx config in
  deployment ops, not the codebase.

Cluster F — converted to "Future-work backlog" callouts:

- slices/03 hedge "future revision should pick a module with print
  template": demoted to a future-work callout adjacent to the open
  item.
- slices/05 items 2 & 3: re-cast as "Future-work backlog item — not a
  verification claim" with the workable command/mitigation noted.
- concepts/customization-channels line 66: rephrased — the choice is
  about *runtime divergence visibility in source control*, not
  maintainer opinion.

Bonus closure:
- slices/03 item 3 (tenant-leaky views): DB audit returns 19 of 305
  viw_* lacking sBrandsId (~6.2 %). Embedded the SQL + the count.
- slices/04 line-41 hedge ("needs verification by clicking through
  BACK"): replaced with the verified mapping from item 1.

After-state: of the original 33 entries:
- 19 newly closed with evidence,
- 4 left as deferred-because-DB-state with concrete blocker query,
- 2 left as deferred-because-outside-repo with concrete blocker note,
- 4 demoted to "Future-work backlog" callouts,
- 4 already closed in earlier passes.

Build verified `mkdocs --strict` green.

Documents the xly (小羚羊) printing-industry ERP framework. Built with
MkDocs Material; CJK search via jieba; 3,076 auto-generated catalog
pages from recon/*.tsv plus hand-written prose for the framework's
core mental model and end-to-end vertical slices.

Phase 0 recon: stack, schema shape, framework metadata layer, scope.
Phase 1 wiki: scaffold + auto-catalog + Slices 1-6 (Slice 7 deferred).

Slice coverage:
  1. CRUD module (Hello World) — observed network + cited source
  2. Multi-tenancy & product editions — sBrandsId/sSubsidiaryId/sVersionFlowId
  3. View-backed module (read-only report)
  4. Custom field overlay (gdsconfigformcustomslave)
  5. Per-customer SQL override (script/客户/<customer>/)
  6. Hardware integration (xlyPlc, optional)
  7. Workflow (deferred — Activiti tables empty in dev DB)

Concepts: thesis, modules-forms-vtables, master/slave, semantic-FK,
customization channels & layers, multi-tenancy, request lifecycle.

Reference (Builder): define-form, define-vtable, permissions,
attach-workflow (deferred).

Reference (Maintainer): runtime, proc-dispatch, cache-invalidation,
sql-templates, deployment, activiti.