# Cosmic Development Guidelines

> Best practices for Kingdee Cosmic / BOS Java development.

---

## Scope

Use this layer for Cangqiong, Cosmic, BOS, Xinghan, and related Java extension projects. These rules cover form plugins, bill plugins, list plugins, operation service plugins, validators, BOTP plugins, metadata-based queries, and KSQL/data-fix scripts.

Do not use this layer for Enterprise C# or IronPython plugins.

---

## Guidelines Index

| Guide | Description | When to Read |
| --- | --- | --- |
| [conventions.md](./conventions.md) | Java plugin base classes, naming, lifecycle, platform helpers | Any Java plugin or helper change |
| [ksql.md](./ksql.md) | KSQL/query constraints, metadata verification, rollback script shape | Data query or correction |
| [api-design.md](./api-design.md) | Cosmic-facing service/API contracts and compatibility | API endpoint or integration contract |
| [error-handling.md](./error-handling.md) | Exception categories, rollback behavior, logging, user prompts | Any error path or transaction change |
| [testing.md](./testing.md) | JUnit/Mockito conventions and branch coverage expectations | Adding or changing tests |
| [review.md](./review.md) | Self-review gates and severity levels | Before delivery or review |

---

## Related KCode Skills

| Scenario | Skill / extension |
| --- | --- |
| Java plugin and SDK implementation | ok-cosmic |
| Code review | kd-cosmic-review |
| Unit tests | cosmic-unittest |
| KSQL/data-fix scripts | kd-ksql |
| Metadata (readonly SQL + LLM parse) | `skills/_shared/metadata-db-query.md` |

| Community/API knowledge | kd_cosmic_qa tool |

Read [../../shared/kcode-skills.md](../../shared/kcode-skills.md) for the full routing table.

---

## Pre-Development Checklist

- [ ] Confirm the target is Cosmic/BOS Java, not Enterprise C#.
- [ ] Read [conventions.md](./conventions.md) for base class and lifecycle rules.
- [ ] Search for similar plugin/service/helper code in the same product line.
- [ ] Verify entity/form/field metadata when keys, tables, enums, or DB columns are used.
- [ ] Identify transaction boundaries and rollback behavior before writing data changes.
- [ ] Select the project build/test command (`mvn test`, `gradle test`, or project script).

---

## Core Rules Summary

| Rule | Reference |
| --- | --- |
| Prefer `kd.cd.common.plugin` Ext base classes for new plugins | [conventions.md](./conventions.md) |
| Do not call UI/model APIs from operation plugins | [conventions.md](./conventions.md) |
| Use platform helpers (`OpUtils`, `DynamicObjectUtils`, `BotpUtils`, etc.) before custom code | [conventions.md](./conventions.md) |
| Verify metadata before KSQL or field/table references | [ksql.md](./ksql.md) |
| Every data update script needs impact query, backup, verification, and rollback | [ksql.md](./ksql.md) |
| Transaction helpers must throw when consistency is at risk | [error-handling.md](./error-handling.md) |
| User-facing errors must be actionable and not expose stack traces | [error-handling.md](./error-handling.md) |
| API contracts must preserve compatibility unless versioned | [api-design.md](./api-design.md) |
| Tests must cover branch, boundary, and early-return behavior | [testing.md](./testing.md) |

---

## Quality Check

Before delivering Java/Cosmic work:

1. Run `git diff --name-only` and map each changed file to the relevant guideline.
2. Check [review.md](./review.md) for hard blockers.
3. Run the focused build/test command:

```bash
mvn test
# or
gradle test
```

If the project has no runnable test command, report that clearly and perform compile/static review where possible.