# Cosmic API Design Guidelines

> Contract design, versioning strategy, request/response formats, and error codes for Kingdee Cosmic integrations.

---

## Scope

Use this guide when implementing or modifying Cosmic-facing APIs, service endpoints, integration adapters, OpenAPI documents, or DTO contracts. For pure UI plugin lifecycle work, read [conventions.md](./conventions.md). For SQL/KSQL scripts, read [ksql.md](./ksql.md).

---

## Contract First

Before changing an API, identify:

- Caller type: frontend, third-party system, scheduled job, plugin-to-plugin call, or data sync task
- Stability expectation: internal, partner-facing, or public integration
- Request schema: required fields, optional fields, enum values, pagination, filters
- Response schema: success shape, error shape, timestamps, IDs, localized text
- Compatibility impact: additive, behavior-changing, or breaking

Breaking changes require an explicit versioning or migration plan.

---

## Request Rules

| Concern | Rule |
| --- | --- |
| IDs | Use stable business/entity IDs; do not expose temporary row indexes as contract IDs |
| Field keys | Use documented API field names; do not leak DB column names unless the API is explicitly data-fix/internal |
| Enum values | Verify actual platform enum values before publishing or consuming them |
| Pagination | Use explicit `pageNo/pageSize` or cursor contract; document max page size |
| Filters | Validate and whitelist filter fields; never concatenate raw filter strings into KSQL/SQL |
| Time | Specify timezone and precision; prefer ISO-8601 for external APIs |
| Batch input | Define max batch size and partial failure semantics |

---

## Response Rules

Standard response shape for project APIs should be consistent within the target codebase. When no local standard exists, use:

```json
{
  "success": true,
  "data": {},
  "message": ""
}
```

For failures:

```json
{
  "success": false,
  "errorCode": "COSMIC_BIZ_001",
  "message": "User-facing explanation",
  "details": []
}
```

Rules:

- Do not expose stack traces, SQL, table names, or internal class names to external callers.
- Include enough information for the caller to correct input when validation fails.
- Preserve existing field names and nullability for compatible changes.
- Add fields as optional first; make required only in a versioned contract.

---

## Error Code Taxonomy

| Prefix | Meaning | Example |
| --- | --- | --- |
| `COSMIC_VALIDATION_*` | Input shape or required field problem | missing bill number |
| `COSMIC_BIZ_*` | Business rule rejection | duplicate submit |
| `COSMIC_AUTH_*` | Permission/session issue | no operation permission |
| `COSMIC_DATA_*` | Metadata or data integrity issue | referenced base data missing |
| `COSMIC_DEP_*` | External dependency failure | remote sync unavailable |
| `COSMIC_SYSTEM_*` | Unexpected platform/system failure | unhandled SDK error |

---

## Compatibility Rules

| Change | Compatibility |
| --- | --- |
| Add optional response field | Compatible |
| Add optional request field with default | Compatible |
| Add required request field | Breaking unless versioned |
| Rename/remove field | Breaking |
| Change enum value | Breaking unless old value is still accepted |
| Change error code semantics | Breaking for integrations that branch on code |

---

## Implementation Checklist

- [ ] DTOs are validated before service logic.
- [ ] Metadata-derived fields/enums are verified.
- [ ] API layer stays thin; business rules live in services/helpers.
- [ ] Data-changing calls are idempotent or explicitly documented as non-idempotent.
- [ ] Batch operations define all-or-nothing vs partial success.
- [ ] Logs include correlation/context IDs when available, not sensitive payloads.
- [ ] Tests cover validation, happy path, business rejection, dependency failure, and compatibility cases.