# Cross-Layer Thinking Guide

> Use this before changing behavior that spans plugin UI, business service, metadata, database, or API contracts.

---

## Layer Map

| Layer | Facts to verify |
| --- | --- |
| UI plugin | Form ID, control keys, lifecycle event, editable/readonly timing |
| Operation plugin | Operation key, selected data shape, transaction boundary, validator order |
| Service/helper | Existing helper APIs, error style, idempotency, batch behavior |
| Metadata | Entity ID, field key, DB column, enum values, base data relationships |
| Database/KSQL | DB key, table names, dialect, indexes, row scope, rollback path |
| API/OpenAPI | Request/response schema, compatibility, error code, pagination |

---

## Required Flow

1. Identify every layer touched by the change.
2. Find existing examples in the same product line or plugin type.
3. Verify metadata before using keys or tables in code or scripts.
4. Define the user-visible behavior and the data invariants separately.
5. Choose validation commands for each affected layer.

---

## Common Kingdee Failure Modes

| Symptom | Likely missed layer |
| --- | --- |
| Field value disappears after refresh | UI lifecycle wrote during the wrong event |
| Operation succeeds but data is inconsistent | Transaction helper returned instead of throwing |
| Query works in one environment only | DB key, dialect, or metadata column was guessed |
| API change breaks integration | Contract changed without versioning or compatibility notes |
| Plugin compiles but fails at runtime | Wrong Kingdee base class or lifecycle method |

---

## Stop Conditions

Stop and ask or gather more evidence when:

- The target platform cannot be identified.
- Metadata cannot be verified.
- A change requires cross-database writes.
- Existing behavior and requested behavior conflict.
- Rollback cannot be described for a data-changing script.