# Python Plugin Guidelines

> Plugin development conventions for Kingdee Enterprise IronPython scripts.

---

## Scope

Use this guide for Kingdee Enterprise IronPython script plugins and small automation scripts. If the behavior is large, shared, performance-sensitive, or transaction-critical, prefer C# service/plugin implementation and keep Python as a thin adapter only.

---

## When Python Is Appropriate

| Good fit | Poor fit |
| --- | --- |
| Small form/bill behavior customization | Complex domain service logic |
| Simple field derivation or validation | Heavy batch processing |
| Temporary integration glue with clear owner | Security-sensitive credential handling |
| Thin wrapper around existing platform/service APIs | Large reusable libraries |

---

## Plugin Structure

Keep script plugins explicit and small:

```python
# -*- coding: utf-8 -*-

# Constants
FIELD_AMOUNT = "FAmount"
FIELD_STATUS = "FStatus"


def before_save(ctx):
    """Validate required fields before save."""
    bill = ctx.BillData
    amount = bill.get(FIELD_AMOUNT)
    if amount is None:
        raise Exception("保存失败：金额不能为空。")
```

Rules:

- Put field keys and operation keys in constants.
- Keep one clear entry point per lifecycle event.
- Move repeated logic into small helper functions in the same script or an approved shared module.
- Do not hide platform calls behind vague helpers such as `do_work()`.

---

## Metadata and Runtime Rules

- Verify field keys, form IDs, operation keys, and enum values before use.
- Do not infer identifiers from localized captions.
- Guard all optional object access; IronPython failures often appear only at runtime.
- Avoid global mutable state unless the platform lifecycle is verified.
- Avoid importing unavailable CPython packages; IronPython compatibility is the default assumption.

---

## Error Handling and Logging

| Situation | Rule |
| --- | --- |
| User validation | Raise/return platform-recognized business message |
| Required relation missing | Fail fast; do not continue with partial data |
| Optional side effect fails | Log or collect warning only if business behavior allows continuing |
| Unexpected exception | Include safe context for administrators; show sanitized message to users |

Do not expose stack traces, SQL, secrets, or full payloads to end users.

---

## Deployment Safety

Before deployment:

- [ ] Confirm target environment and script binding location.
- [ ] Confirm file encoding is UTF-8 and Chinese messages render correctly.
- [ ] Confirm required imports exist in the target runtime.
- [ ] Confirm rollback path: disable script, restore previous script, or revert binding.
- [ ] Run the affected form/operation manually in a test environment when possible.

---

## Review Checklist

- [ ] Script is small enough to review in one screen or has clearly named helpers.
- [ ] All platform keys are constants or verified literals.
- [ ] No CPython-only dependency is used without confirmation.
- [ ] No global mutable cache is introduced without lifecycle evidence.
- [ ] User messages are actionable and sanitized.
- [ ] Deployment and rollback steps are known.