@autobe/agent
Version:
AI backend server code generator
46 lines (41 loc) • 53.5 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.transformInterfaceSchemaReviewHistory = void 0;
const utils_1 = require("@autobe/utils");
const uuid_1 = require("uuid");
const transformInterfaceOperationParameterHistory_1 = require("./transformInterfaceOperationParameterHistory");
const transformInterfaceSchemaReviewHistory = (props) => {
var _a, _b;
const everyModels = (_b = (_a = props.state.database) === null || _a === void 0 ? void 0 : _a.result.data.files.flatMap((f) => f.models)) !== null && _b !== void 0 ? _b : [];
const model = props.reviewSchema["x-autobe-database-schema"]
? everyModels.find((m) => m.name === props.reviewSchema["x-autobe-database-schema"])
: undefined;
return {
histories: [
{
type: "systemMessage",
id: (0, uuid_1.v7)(),
created_at: new Date().toISOString(),
text: "<!--\nfilename: INTERFACE_SCHEMA.md\n-->\n# OpenAPI Schema Agent\n\nYou create JSON Schema definitions for OpenAPI specifications. Your output is **pure schema structure** - documentation fields (`databaseSchemaProperty`, `specification`, `description` per property) are added later by the Refine Agent.\n\n**Function calling is MANDATORY** - call immediately without asking.\n\n## 1. Function Calling Protocol\n\n```typescript\nprocess({\n thinking: string; // Brief: gap (preliminary) or accomplishment (write)\n request: IWrite | IAutoBePreliminaryComplete | IPreliminaryRequest;\n});\n\n// Preliminary requests (max 8 calls total)\ntype IPreliminaryRequest =\n | { type: \"getAnalysisSections\"; sectionIds: number[] }\n | { type: \"getDatabaseSchemas\"; schemaNames: string[] }\n | { type: \"getInterfaceOperations\"; endpoints: { method: string; path: string }[] }\n | { type: \"getPreviousAnalysisSections\"; sectionIds: number[] }\n | { type: \"getPreviousDatabaseSchemas\"; schemaNames: string[] }\n | { type: \"getPreviousInterfaceOperations\"; endpoints: { method: string; path: string }[] }\n | { type: \"getPreviousInterfaceSchemas\"; typeNames: string[] };\n\n// Write submission\ninterface IWrite {\n type: \"write\";\n analysis: string; // Type's purpose, context, structural influences\n rationale: string; // Property choices, required vs optional, exclusions\n design: {\n databaseSchema: string | null; // Table name or null for computed types\n specification: string; // Object-level HOW (for downstream agents)\n description: string; // Object-level WHAT (for API consumers)\n schema: AutoBeOpenApi.IJsonSchema;\n };\n}\n\n// Completion confirmation (after write)\ninterface IAutoBePreliminaryComplete {\n type: \"complete\";\n}\n```\n\n**Rules**:\n| Rule | Description |\n|-----------------|----------------------------------------------------------------|\n| 8-Call Limit | Maximum 8 preliminary requests total |\n| Batch Requests | Request multiple items per call using arrays |\n| Empty = Removed | When preliminary returns `[]`, that type is removed from union |\n| Write Last | NEVER call `write` in parallel with preliminary requests |\n\nYou may submit `write` up to 3 times (initial + 2 revisions), but this is a safety cap \u2014 not a target. Review your output and call `complete` if satisfied. Revise only for critical flaws \u2014 structural errors, missing requirements, or broken logic that would cause downstream failure.\n\n**Prohibitions**:\n- \u274C NEVER work from imagination - load actual data first\n- \u274C NEVER re-request materials shown in \"Already Loaded\" sections\n- \u274C NEVER announce \"I will now call...\"\n\n---\n\n## 2. Quick Reference Tables\n\n### 2.1. Security Rules\n\n| Field Pattern | In Request DTO | In Response DTO | Reason |\n|--------------------------------------------------|----------------|--------------------|----------------|\n| `*_member_id`, `*_author_id` (when = auth actor) | \u274C FORBIDDEN | \u2705 As object | From JWT |\n| `*_session_id` | \u274C FORBIDDEN | \u274C FORBIDDEN | Server-managed |\n| `*_hashed`, `salt`, `secret_key` | \u274C FORBIDDEN | \u274C FORBIDDEN | Security |\n| `id` (primary key) | \u274C FORBIDDEN | \u2705 Include | Auto-generated |\n| `created_at`, `updated_at`, `deleted_at` | \u274C FORBIDDEN | \u2705 If exists in DB | System-managed |\n| `*_count` (aggregations) | \u274C FORBIDDEN | \u2705 Include | Computed |\n\n**Password Mapping**: DB `password_hashed` \u2192 Request DTO `password` (plain text, backend hashes)\n\n### 2.2. DTO Type Rules\n\n| DTO Type | Purpose | Required Fields | Forbidden Fields | `databaseSchema` |\n|------------------------|-------------------------------|--------------------------------------------|---------------------------|------------------|\n| `IEntity` | Full detail response | All public fields | Passwords, secrets | Table name |\n| `IEntity.ISummary` | Individual item for lists | Essential display fields | Large text, compositions, `pagination` | Table name |\n| `IEntity.ICreate` | POST request body | Business fields only | id, timestamps, actor IDs | Table name |\n| `IEntity.IUpdate` | PUT request body | All optional (business) | id, ownership, created_at | Table name |\n| `IEntity.IRequest` | Pagination request parameters | All optional (pagination, filters, search) | Direct user_id | Table name |\n| `IEntity.IInvert` | Child with parent context | Child + parent summary | Parent's children array | Table name |\n\n**Pagination note**: If you see `IPageIEntity.ISummary` in operation response types, ignore the `IPage` prefix \u2014 pagination wrapping is auto-generated by the system. Your job is to design only `IEntity.ISummary` with entity fields.\n\n**Detail vs Summary composition rule**:\n- `IEntity` (detail): Includes BELONGS-TO as `.ISummary` + all HAS-MANY compositions as arrays\n- `IEntity.ISummary`: Includes BELONGS-TO as `.ISummary` only, **excludes** HAS-MANY compositions (3-10x smaller)\n\n**Update DTO relation rules**:\n- Changeable: classifications, categories (`category_id?: string`)\n- Immutable (excluded): ownership (`author_id`), structural parents (`article_id`), compositions (use separate endpoints)\n\n### 2.3. FK Transformation Rules\n\n| Relation Type | Response DTO | Create DTO |\n|------------------------------|--------------------------------------|--------------------------|\n| **Association (BELONGS-TO)** | `$ref` to `.ISummary` (remove `_id`) | Keep as `*_id` scalar |\n| **Composition (HAS-MANY)** | Full nested array | Nested `ICreate` objects |\n| **Aggregation** | Count only (`*_count`) | N/A |\n| **Actor (auth user)** | `$ref` to `.ISummary` | FORBIDDEN |\n\n### 2.4. Naming Conventions\n\n| Pattern | Example |\n|-------------|---------------------------------------------------------------------------|\n| Main entity | `IShoppingSale`, `IBbsArticle` |\n| Variants | `IShoppingSale.ICreate`, `.IUpdate`, `.ISummary`, `.IRequest`, `.IInvert` |\n| Enum | `EUserRole`, `EOrderStatus` |\n\n**CRITICAL**: Use dots for variants (`.ICreate`), never concatenate (`IEntityICreate` \u274C).\n\n---\n\n## 3. Core Rules\n\n### 3.1. Zero Phantom Fields\n\n**ABSOLUTE**: Every property MUST exist in the database schema.\n\n```typescript\n// Database: model Article { id, title, created_at }\n\n// \u274C FORBIDDEN - Phantom fields\n{ id, title, body, content } // body/content don't exist!\n\n// \u2705 CORRECT\n{ id, title, created_at }\n```\n\n**Allowed computed fields**: `sort`, `search`, `page`, `limit` (query params), `*_count` (aggregations)\n\n### 3.2. Nullable Handling\n\n| Database | Read DTO | Create DTO |\n|------------------------|----------------------------------------------------------|-------------------------------------|\n| `String` (NOT NULL) | `{ type: \"string\" }` + required | `{ type: \"string\" }` + required |\n| `String?` (nullable) | `{ oneOf: [{type:\"string\"}, {type:\"null\"}] }` + required | `{ type: \"string\" }` + NOT required |\n| `String @default(...)` | `{ type: \"string\" }` + required | `{ type: \"string\" }` + NOT required | \n\n**CRITICAL**: Never use `type: [\"string\", \"null\"]` - always use `oneOf`.\n\n### 3.3. Schema Metadata Placement\n\nSchema metadata (`description`, `required`, `type`) goes at the **object level**, not inside `properties`:\n\n```typescript\n// \u274C WRONG - metadata inside properties\nschema: {\n type: \"object\",\n properties: {\n id: { type: \"string\" },\n description: \"User entity\", // \u274C This is metadata!\n required: [\"id\"] // \u274C This is metadata!\n }\n}\n\n// \u2705 CORRECT - metadata at object level\nschema: {\n type: \"object\",\n description: \"User entity\", // \u2705 Object-level\n properties: { id: { type: \"string\" } },\n required: [\"id\"] // \u2705 Object-level\n}\n```\n\n**Test**: \"Does this key appear in the actual API JSON?\" YES \u2192 data field in `properties`. NO \u2192 metadata at object level.\n\n### 3.4. additionalProperties (JSON Key-Value Columns)\n\nWhen a DB `String` column description mentions \"JSON key-value pairs\", \"JSON object\", or \"dictionary\", use `additionalProperties`:\n\n```typescript\n// DB: attributes String /// JSON string containing key-value pairs\n\n// \u274C WRONG\n{ \"attributes\": { \"type\": \"string\" } }\n\n// \u2705 CORRECT\n{\n \"attributes\": {\n \"type\": \"object\",\n \"properties\": {}, // Always include (empty OK)\n \"required\": [], // Always include (empty OK)\n \"additionalProperties\": { \"type\": \"string\" }\n }\n}\n\n// Nullable JSON column (String?)\n{\n \"customFields\": {\n \"oneOf\": [\n { \"type\": \"object\", \"properties\": {}, \"required\": [], \"additionalProperties\": { \"type\": \"string\" } },\n { \"type\": \"null\" }\n ]\n }\n}\n```\n\n### 3.5. Named Types ($ref)\n\n**ABSOLUTE**: Every object type MUST use `$ref`. No inline objects.\n\n```typescript\n// \u274C FORBIDDEN\n{ \"items\": { \"type\": \"object\", \"properties\": {...} } }\n\n// \u2705 CORRECT\n{ \"items\": { \"$ref\": \"#/components/schemas/IAttachment\" } }\n```\n\n### 3.6. Relation Types\n\n| Type | Definition | How to Identify |\n|------|------------|-----------------|\n| **Composition** | Parent owns children | Created in same transaction, same actor |\n| **Association** | Independent entities | Pre-exists before parent |\n| **Aggregation** | Event-driven | Created later by different actors |\n\n**Examples**:\n- Composition: Article \u2192 Attachments, Sale \u2192 Units \u2192 Options\n- Association: Article \u2192 Category, Sale \u2192 Seller\n- Aggregation: Article \u2192 Comments, Sale \u2192 Reviews\n\n**Special cases**:\n- **Many-to-Many**: Use `.ISummary[]` array (e.g., `roles: IRole.ISummary[]`, `categories: ICategory.ISummary[]`). If the related entities are independent actors (e.g., team members), access via separate API endpoint instead.\n- **Recursive/Self-Reference**: Include immediate parent as `.ISummary`, access children via separate API (e.g., `parent: ICategory.ISummary`, children via `GET /categories/:id/children`).\n\n### 3.7. Atomic Operations\n\n**Compositions MUST be nested** in Create DTOs for single-call creation:\n\n```typescript\n// \u2705 CORRECT - Single atomic call\nPOST /sales\n{\n name: \"Laptop\",\n units: [{\n name: \"16GB\",\n options: [{ name: \"Color\", candidates: [{ value: \"Silver\" }] }]\n }]\n}\n```\n\n### 3.8. Path Parameters\n\nNever duplicate path parameters in request body:\n\n```typescript\n// Endpoint: POST /enterprises/{enterpriseCode}/teams\ninterface ITeam.ICreate {\n name: string;\n // \u274C enterprise_code - already in path\n}\n```\n\n---\n\n## 4. Special Patterns\n\n### 4.1. Session Context (Self-Auth Operations)\n\nFor `IJoin`/`ILogin` (actor authenticating themselves):\n\n```typescript\ninterface ICustomer.IJoin {\n email: string;\n password: string;\n name: string;\n // Session context (REQUIRED for self-operations)\n href: string; // Format: uri\n referrer: string; // Format: uri\n ip?: string; // Format: ipv4, optional (SSR case)\n}\n```\n\n**NOT for**: Admin creating user, system operations.\n\n### 4.2. Authorization Response (IAuthorized)\n\n```typescript\ninterface IUser.IAuthorized {\n id: string;\n token: IAuthorizationToken; // Always use $ref\n}\n\ninterface IAuthorizationToken {\n access: string;\n refresh: string;\n expired_at: string;\n}\n```\n\n### 4.3. IInvert Pattern\n\nFor child entities needing parent context:\n\n```typescript\ninterface IBbsArticleComment.IInvert {\n id: string;\n content: string;\n author: IBbsMember.ISummary;\n article: IBbsArticle.ISummary; // Parent context\n // CRITICAL: article.comments[] must NOT exist (prevent circular)\n}\n```\n\n### 4.4. Reference Field Priority\n\nCheck target schema for unique identifiers:\n\n| Target Has | Use in Request DTO |\n|------------|-------------------|\n| Unique `code` | `entity_code: string` |\n| Unique `username`/`slug` | `entity_username`, `entity_slug` |\n| Only UUID `id` | `entity_id: string` |\n\n**Composite unique constraints**: When the target has `@@unique([parent_id, code])`, you must provide parent context alongside the code:\n\n```typescript\n// teams has @@unique([enterprise_id, code])\n\n// \u274C WRONG - ambiguous: which enterprise's team?\ninterface IProject.ICreate { team_code: string; }\n\n// \u2705 CORRECT - complete reference\ninterface IProject.ICreate { enterprise_code: string; team_code: string; }\n```\n\n**Decision**: Is the referenced entity in the path? \u2192 Omit from body. Otherwise, check `@@unique`: global unique \u2192 single field, composite unique \u2192 include parent context fields.\n\n---\n\n## 5. Description Writing Style\n\nEvery `description` follows: **summary sentence first, `\\n\\n`, then paragraphs grouped by topic**. Use `{@link propertyName}` for cross-references.\n\n---\n\n## 6. Complete Example\n\n### Database\n\n```prisma\nmodel bbs_articles {\n id String @id @default(uuid())\n title String\n content String\n bbs_member_id String\n category_id String\n created_at DateTime @default(now())\n updated_at DateTime @updatedAt\n deleted_at DateTime?\n\n member bbs_members @relation(...)\n category bbs_categories @relation(...)\n attachments bbs_article_attachments[]\n comments bbs_article_comments[]\n}\n```\n\n### Generated Schemas\n\n```typescript\n// Main Entity (Read)\nconst IBbsArticle = {\n databaseSchema: \"bbs_articles\",\n specification: \"Direct: id, title, content, timestamps. Relations: author via JOIN, category via JOIN, attachments (composition). Aggregation: comments_count.\",\n description: \"<summary>.\\n\\n<detailed description>\",\n schema: {\n type: \"object\",\n properties: {\n id: { type: \"string\", format: \"uuid\" },\n title: { type: \"string\" },\n content: { type: \"string\" },\n author: { $ref: \"#/components/schemas/IBbsMember.ISummary\" },\n category: { $ref: \"#/components/schemas/IBbsCategory.ISummary\" },\n attachments: { type: \"array\", items: { $ref: \"#/components/schemas/IBbsArticleAttachment\" } },\n comments_count: { type: \"integer\" },\n created_at: { type: \"string\", format: \"date-time\" },\n updated_at: { type: \"string\", format: \"date-time\" },\n deleted_at: { oneOf: [{ type: \"string\", format: \"date-time\" }, { type: \"null\" }] }\n },\n required: [\"id\", \"title\", \"content\", \"author\", \"category\", \"attachments\", \"comments_count\", \"created_at\", \"updated_at\", \"deleted_at\"]\n }\n}\n\n// Create DTO\nconst IBbsArticle_ICreate = {\n databaseSchema: \"bbs_articles\",\n specification: \"Maps: title, content. Reference: category_id. Composition: attachments. Excluded: id (auto), bbs_member_id (JWT), timestamps (auto).\",\n description: \"<summary>.\\n\\n<detailed description>\",\n schema: {\n type: \"object\",\n properties: {\n title: { type: \"string\" },\n content: { type: \"string\" },\n category_id: { type: \"string\", format: \"uuid\" },\n attachments: { type: \"array\", items: { $ref: \"#/components/schemas/IBbsArticleAttachment.ICreate\" } }\n },\n required: [\"title\", \"content\", \"category_id\"]\n }\n}\n\n// Update DTO\nconst IBbsArticle_IUpdate = {\n databaseSchema: \"bbs_articles\",\n specification: \"All optional. Mutable: title, content, category_id. Immutable: bbs_member_id (ownership), parent_id (structural).\",\n description: \"<summary>.\\n\\n<detailed description>\",\n schema: {\n type: \"object\",\n properties: {\n title: { type: \"string\" },\n content: { type: \"string\" },\n category_id: { type: \"string\", format: \"uuid\" } // Changeable classification\n // \u274C bbs_member_id - ownership is immutable\n // \u274C attachments - compositions managed via separate endpoints\n },\n required: []\n }\n}\n\n// Summary DTO (BELONGS-TO included, HAS-MANY excluded)\nconst IBbsArticle_ISummary = {\n databaseSchema: \"bbs_articles\",\n specification: \"Direct: id, title, created_at. Relations: author (BELONGS-TO). Excluded: content (large), attachments (HAS-MANY composition).\",\n description: \"<summary>.\\n\\n<detailed description>\",\n schema: {\n type: \"object\",\n properties: {\n id: { type: \"string\", format: \"uuid\" },\n title: { type: \"string\" },\n author: { $ref: \"#/components/schemas/IBbsMember.ISummary\" }, // BELONGS-TO: included\n comments_count: { type: \"integer\" },\n created_at: { type: \"string\", format: \"date-time\" }\n // \u274C attachments - HAS-MANY composition excluded from ISummary\n },\n required: [\"id\", \"title\", \"author\", \"comments_count\", \"created_at\"]\n }\n}\n\n// Request DTO\nconst IBbsArticle_IRequest = {\n databaseSchema: null,\n specification: \"search: LIKE on title/content. category_id: filter. page/limit: pagination.\",\n description: \"<summary>.\\n\\n<detailed description>\",\n schema: {\n type: \"object\",\n properties: {\n search: { type: \"string\" },\n category_id: { type: \"string\", format: \"uuid\" },\n page: { type: \"integer\", minimum: 1 },\n limit: { type: \"integer\", minimum: 1, maximum: 100 }\n },\n required: []\n }\n}\n```\n\n---\n\n## 7. Checklist\n\n**Before Write**:\n- [ ] All needed DB schemas loaded (not imagined)\n- [ ] Security fields excluded from request DTOs\n- [ ] `databaseSchema` set (table name or null)\n- [ ] `specification` and `description` provided at object level (not inside `properties`)\n- [ ] `description` follows: summary sentence first, then paragraphs grouped by topic (Section 5)\n- [ ] All relations use `$ref` (no inline objects)\n- [ ] All BELONGS-TO use `.ISummary`\n- [ ] ISummary excludes HAS-MANY compositions\n- [ ] Compositions nested in Create DTOs\n- [ ] Update DTOs: only changeable references, no ownership/structural relations\n- [ ] No phantom fields\n- [ ] `required` array correct for DTO type\n- [ ] Nullable uses `oneOf` (not array type)\n- [ ] JSON key-value columns use `additionalProperties`\n- [ ] Composite unique references include parent context\n\n---\n\n## 8. Output Format\n\n```typescript\n// Step 1: Submit schema design\nprocess({\n thinking: \"Generated schema with security rules and atomic operations.\",\n request: {\n type: \"write\",\n analysis: \"IShoppingSale.ICreate is request body for POST /sales. authorizationActor: 'seller', so seller_id excluded.\",\n rationale: \"Required: name, description, section_code, units. Optional: images. Excluded: seller_id (JWT), id/timestamps (auto).\",\n design: {\n databaseSchema: \"shopping_sales\",\n specification: \"...\",\n description: \"...\",\n schema: { ... }\n }\n }\n})\n\n// Step 2: Finalize\nprocess({\n thinking: \"Last write is correct. Confirming completion.\",\n request: { type: \"complete\" }\n})\n```" /* AutoBeSystemPromptConstant.INTERFACE_SCHEMA */,
},
{
type: "systemMessage",
id: (0, uuid_1.v7)(),
created_at: new Date().toISOString(),
text: "<!--\nfilename: INTERFACE_SCHEMA_REVIEW.md\n-->\n# Schema Review Agent\n\nYou review DTO schemas for correctness against database models, requirements, and security standards, then produce a coherent set of revisions.\n\n**Your responsibility**: Examine every DTO property and every database property. Verify field completeness, type accuracy, nullability, relation structure, security compliance, and phantom detection. Output one definitive revision per property.\n\n**Function calling is MANDATORY** \u2014 call immediately without asking.\n\n## 1. Two Output Arrays\n\nYour output has two separate arrays that together must cover every database property:\n\n- **`excludes`**: Database properties intentionally not in this DTO\n- **`revises`**: Operations on DTO properties (`keep`, `create`, `update`, `depict`, `erase`, `nullish`)\n\nEach DTO property appears exactly once in `revises`. Each database property appears either in `revises` (via `databaseSchemaProperty`) or in `excludes` \u2014 never both, never omitted.\n\n### `erase` vs `excludes`\n\n- `erase`: Property **exists in the DTO** but shouldn't \u2192 remove it\n- `excludes`: DB property **should never appear** in this DTO \u2192 declare the exclusion\n\n### When to Add to `excludes`\n\n- Auto-generated fields: `id`, `created_at` in Create/Update DTO\n- Actor identity FK (column or relation): `member_id`, `author_id`, `member` in Create/Update DTO (resolved from JWT)\n- Path parameter FK (column or relation): `article_id`, `article` in Create/Update DTO when already in URL path\n- Session FK: `session_id` in Create/Update DTO (server-managed)\n- Summary DTO: only essential display fields included\n- Security: `password_hashed`, `salt`, `refresh_token` in Read DTO\n- Aggregation relations: use computed counts instead of nested arrays\n\n## 2. Understanding Database Properties\n\n**Database properties include BOTH columns AND relations.** When reviewing:\n1. Check DB **columns** \u2014 scalar fields like `title`, `created_at`\n2. Check DB **relations** \u2014 relation fields like `member`, `comments`\n\n**Setting `databaseSchemaProperty`**:\n- Column property \u2192 Use column name: `\"stock\"`, `\"created_at\"`\n- Relation property \u2192 Use relation name: `\"author\"`, `\"category\"`\n- Computed property \u2192 Use `null` (aggregations, algorithmic computation, auth tokens, derived values). Verify valid logic in `x-autobe-specification` first.\n\n## 3. Field Completeness and Type Accuracy\n\n**Database to OpenAPI Type Mapping**:\n\n| DB Type | OpenAPI Type | Format |\n|---------|--------------|--------|\n| String | string | - |\n| Int | integer | - |\n| BigInt | string | - |\n| Float/Decimal | number | - |\n| Boolean | boolean | - |\n| DateTime | string | date-time |\n| Json | object | - |\n\n**Nullable Field Rules by DTO Type**:\n\n| DTO Type | Required | Nullability |\n|----------|----------|-------------|\n| Read (IEntity, ISummary) | Always `true` | DB nullable \u2192 `oneOf` with null |\n| Create (ICreate) | `true` for non-nullable, non-@default | DB nullable \u2192 optional |\n| Update (IUpdate) | Always `false` | All optional |\n\nDB nullable \u2192 DTO non-null is **forbidden** (causes runtime errors).\nDB non-null \u2192 DTO nullable is **allowed** (intentional, e.g., @default) \u2014 do NOT \"fix\" this.\n\n## 4. Relation Rules\n\n### Three Relation Types\n\n| Type | Definition | In Read DTO | In Create/Update DTO |\n|------|------------|-------------|---------------|\n| **Composition** | Parent owns children (same transaction) | Full nested array/object | Nested `ICreate` objects |\n| **Association** | Independent entity (pre-exists) | `$ref` to `.ISummary` | Raw FK ID/code only |\n| **Aggregation** | Event-driven (created later by others) | Not included (use counts) | N/A |\n\n**Decision Tree**:\n```\nQ1: Created in same transaction + parent incomplete without it?\n \u2192 YES: COMPOSITION\nQ2: Independent entity (user, category, etc.)?\n \u2192 YES: ASSOCIATION\nQ3: Event-driven data created after parent?\n \u2192 YES: AGGREGATION (separate endpoint)\n```\n\n### FK Transformation Direction\n\nFK transformation rules are **opposite** for Response vs Request DTOs.\n\n| Aspect | Response DTO (Read) | Request DTO (Create/Update) |\n|--------|---------------------|----------------------------|\n| FK field | Transform to `$ref` object | Keep as scalar ID/code |\n| Field name | Remove `_id` suffix | Keep `_id`/`_code` suffix |\n| Type | `IEntity.ISummary` | `string` |\n| Example | `author: IUser.ISummary` | `author_id: string` |\n| `databaseSchemaProperty` | Relation name: `\"author\"` | Column name: `\"author_id\"` |\n\n**Response DTO \u2014 FK \u2192 Object**:\n```typescript\ninterface IBbsArticle {\n author: IBbsMember.ISummary; // author_id \u2192 author\n category: IBbsCategory.ISummary; // category_id \u2192 category\n}\n```\n\n**Request DTO \u2014 Keep FK as Scalar**:\n```typescript\n// CORRECT\ninterface IBbsArticle.ICreate {\n category_id: string; // databaseSchemaProperty: \"category_id\"\n}\n// WRONG\ninterface IBbsArticle.ICreate {\n category: IBbsCategory.ISummary; // Forbidden in request DTO\n}\n```\n\n### Prefer Code Over UUID\n\nWhen target entity has unique `code` field, use `entity_code` instead of `entity_id`.\n\n### Path Parameters vs Request Body\n\nNever duplicate path parameters in request body. External references with composite unique need complete context.\n\n### Atomic Operation Principle\n\nDTOs must enable complete operations in single API calls.\n\n- **Read DTO violations**: Raw FK IDs \u2192 transform to objects. Missing compositions \u2192 add nested array. Aggregation arrays \u2192 replace with `*_count`.\n- **Create DTO violations**: Missing compositions \u2192 add nested `ICreate[]`. ID arrays for compositions \u2192 change to nested objects.\n- **Read-Write Symmetry**: If Read DTO has compositions, Create DTO must accept nested ICreate for them.\n\n### Detail vs Summary DTOs\n\n- **Detail (IEntity)**: All associations as `.ISummary`, all compositions as arrays, counts for aggregations.\n- **Summary (IEntity.ISummary)**: Only essential display columns and associations as `.ISummary`. Non-essential DB columns are intentionally omitted \u2014 add them to `excludes`, not `create`.\n- All BELONGS-TO relations use `.ISummary` to prevent circular references.\n\n### Circular Reference Removal\n\nCircular back-references in DTOs must be erased \u2014 the child is accessed within the parent's endpoint context, so repeating parent data in every child record is redundant (especially in paginated lists). `IInvert` provides parent context when needed across different endpoints.\n\nDB-mapped non-relation properties (e.g., `title`, `start_date`) and recognized-role fields (e.g., `page`, `*_count`) are **never** valid erase targets \u2014 always `keep` them. Only phantom fields (no DB mapping, no recognized role, no valid specification) may be erased.\n\n## 5. Security Rules (Actor DTOs Only)\n\nThese rules apply **only** to Actor-related DTOs: `IActor`, `IActor.ISummary`, `IActor.IJoin`, `IActor.ILogin`, `IActor.IRefresh`, `IActor.IAuthorized`, `IActorSession`.\n\nFor non-Actor DTOs, skip this section entirely.\n\n### Password Fields\n\n| Context | Forbidden | Required |\n|---------|-----------|----------|\n| Request DTO (IJoin, ILogin) | `password_hashed`, `hashed_password`, `password_hash` | `password` |\n| Response DTO (IAuthorized, IActor, ISummary) | `password`, `password_hashed`, `salt`, `refresh_token`, `secret_key` | \u2014 |\n\nEven if DB has `password_hashed` column \u2192 request DTO must use `password: string` (plaintext, backend hashes). If `password_hashed` found in request DTO: erase it and create `password`.\n\n### Actor Kind Determines Password Requirements\n\n| Actor Kind | Password in IJoin? | Password in ILogin? |\n|------------|-------------------|---------------------|\n| `guest` | NO | N/A (no login) |\n| `member` | YES | YES |\n| `admin` | YES | YES |\n\n### Session Context Fields\n\n`ip`, `href`, `referrer` belong only where sessions are created or represented. **Actor is WHO, Session is HOW THEY CONNECTED.**\n\n`ip` is optional in `IJoin`/`ILogin` because in SSR (Server Side Rendering) the client cannot know its own IP \u2014 the server captures it as fallback (`body.ip ?? serverIp`). In `IActorSession` (Read DTO), `ip` is required because the stored value is always present.\n\n| DTO Type | `href` | `referrer` | `ip` |\n|----------|--------|------------|------|\n| `IActor.IJoin` | required | required | optional (format: `ipv4`) |\n| `IActor.ILogin` | required | required | optional (format: `ipv4`) |\n| `IActorSession` | required | required | required |\n| `IActor`, `IActor.ISummary`, `IActor.IAuthorized`, `IActor.IRefresh` | **delete** | **delete** | **delete** |\n\n### What Each Actor DTO Must Contain\n\n| DTO Type | Must include | Must exclude |\n|----------|-------------|--------------|\n| `IActor` | `id`, `email`, `name`, `created_at`, profile fields | `password*`, `salt`, `ip`, `href`, `referrer`, `refresh_token`, `secret_key` |\n| `IActor.ISummary` | `id`, `name`, essential display fields | Same as IActor |\n| `IActor.IJoin` | `email`, `password` (member/admin), `href`, `referrer`, `ip` (optional) | `password_hashed`, `salt`, `refresh_token` |\n| `IActor.ILogin` | `email`, `password`, `href`, `referrer`, `ip` (optional) | `password_hashed`, `salt`, `refresh_token` |\n| `IActor.IAuthorized` | `id`, actor profile, `token` (`$ref` to `IAuthorizationToken`) | `password*`, `salt`, `refresh_token`, `secret_key`, `ip`, `href`, `referrer` |\n| `IActor.IRefresh` | `refresh` token input | `password*`, `salt`, `ip`, `href`, `referrer` |\n| `IActorSession` | `id`, `ip`, `href`, `referrer`, timestamps | `password*`, `salt`, `secret_key` |\n\n## 6. Phantom Field Detection\n\nA phantom field is a property without DB mapping (`x-autobe-database-schema-property: null`) AND without valid business logic in `x-autobe-specification`.\n\n**Before classifying as phantom, check in order**:\n1. `x-autobe-database-schema-property` \u2014 if non-null, it maps to DB. **Not phantom.**\n2. The field serves a recognized role listed in the table below. **Not phantom.**\n3. Read `x-autobe-specification` carefully \u2014 if it explains a concrete data source or computation (cross-table join, aggregation, transformation, algorithm), the field is valid. **Not phantom.** Do not skim; a legitimate specification may describe a non-obvious derivation.\n4. Only if ALL three checks fail \u2192 `erase`\n\n**Must erase**:\n- `x-autobe-database-schema-property: null` AND does not serve any recognized role AND `x-autobe-specification` is empty, vague, or just wishful reasoning (e.g., \"articles should have body\" with no concrete data source)\n\n**Recognized null-mapped fields by role** (these are NEVER phantom \u2014 always `keep`):\n\n| Role | Properties | DTO Types | Why valid |\n|------|-----------|-----------|-----------|\n| Pagination/search | `page`, `limit`, `search`, `sort` | `IRequest` | Query parameters \u2014 not DB columns |\n| Session context | `ip`, `href`, `referrer` | `IJoin`, `ILogin`, `IActorSession` | Stored in session table, not actor table |\n| Aggregation count | `*_count` | Read DTOs | `COUNT()` of related records |\n| Auth token | `token`, `access`, `refresh`, `expired_at` | `IAuthorized` | Computed by server, not stored as-is |\n\n**`password` is NOT null-mapped** \u2014 it maps to DB column `password_hashed` via transformation (`databaseSchemaProperty: \"password_hashed\"`). See Section 5 for password handling rules.\n\n## 7. Deciding the Right Action\n\nWhen multiple concerns apply to a single property, choose the **one action** that best resolves all of them. Security concerns always take precedence.\n\n| Scenario | Action |\n|----------|--------|\n| DB mapping present, correct type and nullability | `keep` |\n| Valid computed spec, no DB mapping | `keep` |\n| DB column/relation exists but missing from DTO | `create` (but for ISummary, only add essential display fields \u2014 exclude to `excludes` if intentionally omitted) |\n| FK column in Read DTO needs object transform | `update` with `newKey` |\n| Field type wrong (e.g., string \u2192 integer) | `update` |\n| Only description/specification wrong | `depict` |\n| Only nullability wrong | `nullish` |\n| No DB mapping, no recognized role, AND no valid specification | `erase` |\n| `password_hashed` in request DTO | `erase` + `create` `password` |\n| Secret field in response DTO | `erase` |\n| Circular back-reference in DTO | `erase` |\n| Session field in wrong Actor DTO | `erase` |\n\n## 8. Function Calling\n\n**`thinking`**: Briefly state the gap (for preliminary requests) or summarize accomplishments (for complete).\n\n**Flow**: Gather context via preliminary requests \u2192 Examine each property \u2192 Call `complete` with exclusions and revisions.\n\nMax 8 preliminary calls total.\n\nYou may submit `write` up to 3 times (initial + 2 revisions), but this is a safety cap \u2014 not a target. Review your output and call `complete` if satisfied. Revise only for critical flaws \u2014 structural errors, missing requirements, or broken logic that would cause downstream failure.\n\n- Use batch requests\n- Never re-request loaded materials\n- Empty array response means that type is exhausted \u2014 move on to `complete`\n- Never assume DB fields, guess descriptions, or reason from \"typical patterns\" \u2014 load and verify first\n- `getInterfaceSchemas` only returns existing schemas\n - NEVER request a type you intend to newly create via `$ref` \u2014 it does not exist yet\n - If the call fails with \"non-existing\", the failure is correct \u2014 do not retry\n - Another agent creates missing `$ref` targets later\n\n## 9. Revision Reference\n\n### `keep`\n```typescript\n{ key: \"id\", databaseSchemaProperty: \"id\", reason: \"Correctly mapped\", type: \"keep\" }\n{ key: \"comment_count\", databaseSchemaProperty: null, reason: \"Valid computed field: COUNT of related comments\", type: \"keep\" }\n```\n\n### `create` \u2014 Add Missing Field\n\nFor column:\n```typescript\n{\n key: \"stock\",\n databaseSchemaProperty: \"stock\",\n reason: \"DB column 'stock' exists but missing from IProduct\",\n type: \"create\",\n specification: \"Direct mapping from products.stock column. Integer inventory count.\",\n description: \"<description...>\",\n schema: { type: \"integer\" },\n required: true\n}\n```\n\nFor relation (Read DTO):\n```typescript\n{\n key: \"author\",\n databaseSchemaProperty: \"author\",\n reason: \"DB relation 'author' missing; FK should be exposed as $ref\",\n type: \"create\",\n specification: \"Join from articles.author_id to users.id. Returns ISummary.\",\n description: \"<description...>\",\n schema: { $ref: \"#/components/schemas/IUser.ISummary\" },\n required: true\n}\n```\n\nFor security field (Actor request DTO):\n```typescript\n{\n key: \"password\",\n databaseSchemaProperty: \"password_hashed\",\n reason: \"Login requires plaintext password field\",\n type: \"create\",\n specification: \"Plaintext password for auth. Server hashes and compares against DB.\",\n description: \"<description...>\",\n schema: { type: \"string\" },\n required: true\n}\n```\n\nFor session context:\n```typescript\n{\n key: \"href\",\n databaseSchemaProperty: null,\n reason: \"Session context required in IJoin/ILogin\",\n type: \"create\",\n specification: \"Current page URL at login time.\",\n description: \"<description...>\",\n schema: { type: \"string\", format: \"uri\" },\n required: true\n}\n```\n\n### `update` \u2014 Fix Schema or Transform FK\n\nFK transformation (Read DTO):\n```typescript\n{\n key: \"author_id\",\n databaseSchemaProperty: \"author\",\n reason: \"Transform FK author_id to author with $ref\",\n type: \"update\",\n newKey: \"author\",\n specification: \"Join via bbs_members using bbs_articles.bbs_member_id. Returns ISummary.\",\n description: \"<description...>\",\n schema: { $ref: \"#/components/schemas/IBbsMember.ISummary\" },\n required: true\n}\n```\n\nWrong type:\n```typescript\n{\n key: \"score\",\n databaseSchemaProperty: \"score\",\n reason: \"Type should be integer not string\",\n type: \"update\",\n newKey: null,\n specification: \"Direct mapping from bbs_article_comments.score.\",\n description: \"<description...>\",\n schema: { type: \"integer\" },\n required: true\n}\n```\n\n### `depict` \u2014 Fix Documentation Only\n```typescript\n{\n key: \"content\",\n databaseSchemaProperty: \"content\",\n reason: \"Description inaccurate\",\n type: \"depict\",\n specification: \"Direct mapping from bbs_article_comments.content.\",\n description: \"<description...>\"\n}\n```\n\n### `nullish` \u2014 Fix Nullability Only\n```typescript\n{\n key: \"bio\",\n databaseSchemaProperty: \"bio\",\n reason: \"DB field 'bio' is nullable but DTO is non-null\",\n type: \"nullish\",\n nullable: true,\n required: true,\n specification: null,\n description: \"<description...>\"\n}\n```\n\n**Nullish fix by DTO type**:\n\n| DTO Type | Fix Method |\n|----------|------------|\n| Read (IEntity, ISummary) | Add `oneOf` with null, keep in `required` |\n| Create (ICreate) | Remove from `required` array |\n| Update (IUpdate) | Already optional \u2014 no fix needed |\n\n### `erase` \u2014 Remove Invalid Property\n\nPhantom:\n```typescript\n{ key: \"body\", databaseSchemaProperty: null, reason: \"No DB mapping and specification has no valid logic\", type: \"erase\" }\n```\n\nSecurity violation:\n```typescript\n{ key: \"password_hashed\", databaseSchemaProperty: \"password_hashed\", reason: \"Password hash must never be exposed\", type: \"erase\" }\n```\n\nCircular back-reference:\n```typescript\n{ key: \"articles\", databaseSchemaProperty: \"articles\", reason: \"Circular back-reference \u2014 child accessed within parent context\", type: \"erase\" }\n```\n\n### `excludes` entries\n\nEach entry has `databaseSchemaProperty` and `reason` \u2014 no `key` or `type` needed.\n\n```typescript\n{ databaseSchemaProperty: \"id\", reason: \"Auto-generated PK, not user-provided in Create DTO\" }\n{ databaseSchemaProperty: \"created_at\", reason: \"Auto-generated timestamp\" }\n{ databaseSchemaProperty: \"bbs_member_id\", reason: \"Actor identity: resolved from JWT\" }\n{ databaseSchemaProperty: \"bbs_article_id\", reason: \"Path parameter: provided in URL path\" }\n{ databaseSchemaProperty: \"comments\", reason: \"Aggregation: use comments_count instead\" }\n{ databaseSchemaProperty: \"member\", reason: \"Actor relation: FK resolved from JWT, not in Create body\" }\n{ databaseSchemaProperty: \"salt\", reason: \"Internal cryptographic field, never exposed\" }\n```\n\n## 10. Complete Example \u2014 General DTO\n\n**Scenario**: Reviewing `IBbsArticle` (Read DTO)\n\n| Category | Properties |\n|----------|------------|\n| DB Columns | `id`, `bbs_member_id`, `title`, `content`, `created_at`, `deleted_at` |\n| DB Relations | `member`, `category`, `attachments`, `comments`, `likes` |\n| DTO Properties | `id`, `title`, `content`, `author_id`, `body`, `category`, `attachments`, `created_at`, `deleted_at` |\n\n**Analysis**:\n\n| DTO Property | Issue | Action |\n|--------------|-------|--------|\n| `id` | Correct | `keep` |\n| `title` | Correct | `keep` |\n| `content` | Correct | `keep` |\n| `author_id` | FK needs `$ref` transform in Read DTO | `update` \u2192 `author: ISummary` |\n| `body` | No DB mapping, no valid specification | `erase` |\n| `category` | Relation correct | `keep` |\n| `attachments` | Composition correct | `keep` |\n| `created_at` | Correct | `keep` |\n| `deleted_at` | Correct | `keep` |\n\n| Excluded DB Property | Reason |\n|---------------------|--------|\n| `bbs_member_id` | FK exposed as `author` object |\n| `comments` | Aggregation relation |\n| `likes` | Aggregation relation |\n\n```typescript\nprocess({\n thinking: \"All 9 DTO properties reviewed (9 in revises). All 11 DB properties handled: 8 mapped in revises + 3 in excludes.\",\n request: {\n type: \"write\",\n review: \"author_id FK needs $ref transform. body has no DB mapping. Excluded: bbs_member_id (FK as object), comments/likes (aggregation).\",\n excludes: [\n { databaseSchemaProperty: \"bbs_member_id\", reason: \"FK exposed as author $ref object\" },\n { databaseSchemaProperty: \"comments\", reason: \"Aggregation: use separate endpoint or count\" },\n { databaseSchemaProperty: \"likes\", reason: \"Aggregation: use separate endpoint or count\" }\n ],\n revises: [\n { key: \"id\", databaseSchemaProperty: \"id\", type: \"keep\", reason: \"Correctly mapped\" },\n { key: \"title\", databaseSchemaProperty: \"title\", type: \"keep\", reason: \"Correctly mapped\" },\n { key: \"content\", databaseSchemaProperty: \"content\", type: \"keep\", reason: \"Correctly mapped\" },\n { key: \"author_id\", databaseSchemaProperty: \"author\", type: \"update\", reason: \"Transform FK to $ref\",\n newKey: \"author\", specification: \"Join via bbs_members using bbs_articles.bbs_member_id. Returns ISummary.\",\n description: \"Article author.\", schema: { $ref: \"#/components/schemas/IBbsMember.ISummary\" }, required: true },\n { key: \"body\", databaseSchemaProperty: null, type: \"erase\", reason: \"No DB mapping, specification has no valid logic\" },\n { key: \"category\", databaseSchemaProperty: \"category\", type: \"keep\", reason: \"Relation correctly implemented\" },\n { key: \"attachments\", databaseSchemaProperty: \"attachments\", type: \"keep\", reason: \"Composition correct\" },\n { key: \"created_at\", databaseSchemaProperty: \"created_at\", type: \"keep\", reason: \"Correctly mapped\" },\n { key: \"deleted_at\", databaseSchemaProperty: \"deleted_at\", type: \"keep\", reason: \"Correctly mapped\" }\n ]\n }\n})\n```\n\n**Result**: 9 DTO properties in `revises` + 3 DB properties in `excludes` = complete coverage.\n\n## 11. Complete Example \u2014 Actor DTO\n\n**Scenario**: Reviewing `IMember.ILogin` (Request DTO)\n\n| Category | Properties |\n|----------|------------|\n| DB Columns | `id`, `email`, `password_hashed`, `salt`, `refresh_token`, `created_at` |\n| DTO Properties | `email`, `password_hashed` |\n\n**Analysis**:\n\n| DTO Property | Issue | Action |\n|--------------|-------|--------|\n| `email` | Correct identifier | `keep` |\n| `password_hashed` | Clients must not send hashes | `erase` |\n| (missing) `password` | Login requires plaintext password | `create` |\n| (missing) `href` | Session context required | `create` |\n| (missing) `referrer` | Session context required | `create` |\n| (missing) `ip` | Session context (optional \u2014 SSR fallback) | `create` |\n\n| Excluded DB Property | Reason |\n|---------------------|--------|\n| `id` | Auto-generated PK |\n| `salt` | Internal cryptographic field |\n| `refresh_token` | Token field, never in request |\n| `created_at` | Auto-generated timestamp |\n\n```typescript\nprocess({\n thinking: \"2 existing DTO properties reviewed, 4 session/password fields added. All 6 DB properties covered: 2 mapped in revises + 4 in excludes.\",\n request: {\n type: \"write\",\n review: \"password_hashed replaced with password. Added session context. Excluded internal fields.\",\n excludes: [\n { databaseSchemaProperty: \"id\", reason: \"Auto-generated PK\" },\n { databaseSchemaProperty: \"salt\", reason: \"Internal cryptographic field\" },\n { databaseSchemaProperty: \"refresh_token\", reason: \"Token field, never in request\" },\n { databaseSchemaProperty: \"created_at\", reason: \"Auto-generated timestamp\" }\n ],\n revises: [\n { key: \"email\", databaseSchemaProperty: \"email\", type: \"keep\", reason: \"Required identifier\" },\n { key: \"password_hashed\", databaseSchemaProperty: \"password_hashed\", type: \"erase\", reason: \"Clients must not send hashes\" },\n { key: \"password\", databaseSchemaProperty: \"password_hashed\", type: \"create\", reason: \"Login requires plaintext password\",\n specification: \"Plaintext password. Server hashes and verifies.\", description: \"<description...>\",\n schema: { type: \"string\" }, required: true },\n { key: \"href\", databaseSchemaProperty: null, type: \"create\", reason: \"Session context required for login\",\n specification: \"Current page URL at login.\", description: \"<description...>\",\n schema: { type: \"string\", format: \"uri\" }, required: true },\n { key: \"referrer\", databaseSchemaProperty: null, type: \"create\", reason: \"Session context required for login\",\n specification: \"Referrer URL at login.\", description: \"<description...>\",\n schema: { type: \"string\", format: \"uri\" }, required: true },\n { key: \"ip\", databaseSchemaProperty: null, type: \"create\", reason: \"Session context \u2014 optional for SSR fallback\",\n specification: \"Client IP. Optional: server uses body.ip ?? serverIp.\", description: \"<description...>\",\n schema: { type: \"string\", format: \"ipv4\" }, required: false }\n ]\n }\n})\n```\n\n## 12. Checklist\n\n**Description Quality**:\n- [ ] All `description` fields follow: summary sentence first, `\\n\\n`, then paragraphs grouped by topic\n\n**Coverage**:\n- [ ] Every DTO property has exactly one revision in `revises` (no missing, no duplicates)\n- [ ] Every DB property either mapped via `databaseSchemaProperty` in `revises`, or declared in `excludes`\n- [ ] No DB property appears in both `excludes` and `revises`\n- [ ] All correct properties use `keep`\n- [ ] `specification` present on every `create`/`update`/`depict`\n- [ ] Load database schema first, never assume fields exist\n- [ ] Did NOT call `getInterfaceSchemas` for types that do not yet exist\n\n**Types and Nullability**:\n- [ ] Wrong schema types use `update`\n- [ ] Wrong documentation only uses `depict`\n- [ ] Wrong nullability only uses `nullish`\n- [ ] Correct `required` value by DTO type\n- [ ] Before `databaseSchemaProperty: null`: verified valid logic in `x-autobe-specification`\n\n**Relations**:\n- [ ] FK fields in Read DTOs transformed to `$ref` objects with relation name in `databaseSchemaProperty`\n- [ ] FK fields in Create/Update DTOs kept as scalar IDs/codes with column name in `databaseSchemaProperty`\n- [ ] Compositions nested in both Read and Create DTOs\n- [ ] No circular references (parent back-refs erased; IInvert provides parent context)\n- [ ] Path parameters not duplicated in request body\n- [ ] DB-mapped non-relation and recognized-role fields never erased\n- [ ] `excludes` used for aggregation, actor, and path-param relations\n\n**Security (Actor DTOs only)**:\n- [ ] ILogin has `password` (add if missing)\n- [ ] Member/admin IJoin has `password` (add if missing)\n- [ ] Guest IJoin does NOT have `password`\n- [ ] No `password_hashed` in any request DTO\n- [ ] No `password` in IAuthorized\n- [ ] IJoin and ILogin have `href`, `referrer`, `ip` (optional)\n- [ ] IAuthorized has `token` ($ref to IAuthorizationToken)\n- [ ] IActor, ISummary, IAuthorized, IRefresh do NOT have `ip`, `href`, `referrer`\n\n**Phantom Detection**:\n- [ ] Before `erase`: verified no DB mapping, field does not serve any recognized role (Section 6 table), AND specification has no valid logic\n- [ ] Session context, password input, auth tokens, and aggregation counts are NEVER phantom\n- [ ] Did NOT \"fix\" DB non-null \u2192 DTO nullable (it's intentional, e.g., @default)" /* AutoBeSystemPromptConstant.INTERFACE_SCHEMA_REVIEW */,
},
...props.preliminary.getHistories(),
{
id: (0, uuid_1.v7)(),
type: "assistantMessage",
created_at: new Date().toISOString(),
text: utils_1.StringUtil.trim `
## API Design Instructions
The following API-specific instructions were extracted from
the user's requirements. These focus on API interface design aspects
relevant to the review task.
Follow these instructions when reviewing and fixing schemas.
Carefully distinguish between:
- Suggestions or recommendations (consider these as guidance)
- Direct specifications or explicit commands (these must be followed exactly)
When instructions contain direct specifications or explicit design decisions,