@wneng/create-keel 0.4.2 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wneng/create-keel",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Scaffolder for Contract First + Vibe Coding projects (keel conventions)",
   "keywords": [
     "scaffold",

package/src/standards/templates/tech-stack-server.md.eta

@@ -4,7 +4,8 @@ language: <%= it.standards.language %>
 packageManager: <%= it.standards.packageManager %>
 manifestPath: <%= it.standards.manifestPath %>
 lastReviewed: <%= it.standards.lastReviewed %>
-dependencies:
+<% if (it.standards.ormConvention && it.standards.ormConvention !== 'none') { %>ormConvention: <%= it.standards.ormConvention %>
+<% } %>dependencies:
 <% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
     version: "<%= dep.version %>"
     policy: <%= dep.policy %>
@@ -12,7 +13,7 @@ dependencies:
 
 # 后端技术栈钉版本表
 
-> 这个文件的 **frontmatter 是机器真值**：CI 中的 `governance-lint` 会把上面 `dependencies` 数组与 `<%= it.standards.manifestPath %>` 的实际版本逐条对比。
+> 这个文件的 **frontmatter 是机器真值**：CI 中的 `governance-lint` 会把上面 `dependencies` 数组与 `<%= it.standards.manifestPath %>` 的实际版本逐条对比<% if (it.standards.ormConvention && it.standards.ormConvention !== 'none') { %>，并扫描 `server/src` 是否违反 `ormConvention: <%= it.standards.ormConvention %>` 约束<% } %>。
 >
 > 本文件正文是**为什么**这样选 + **如何调整**。机器无法回答这两个问题。
 
@@ -42,6 +43,37 @@ dependencies:
 - 仅开发期使用的 lint / format / 测试工具：可以放在 `devDependencies` 但**不**进本表
 - 容器基础镜像版本：在 `deploy/Dockerfile` 里钉，本表不重复
 - 系统包（apt / yum）：交给运行时镜像维护者
+<% if (it.standards.ormConvention && it.standards.ormConvention !== 'none') { %>
+## ORM 约定（`ormConvention: <%= it.standards.ormConvention %>`）
+
+frontmatter 的 `ormConvention` 字段把"用什么方式访问数据库"作为**项目级硬约束**写入契约。governance-lint 在每次 PR 中扫描 `server/src` 验证是否违反。
+
+当前约定：**`<%= it.standards.ormConvention %>`**。
+
+<% if (it.standards.ormConvention === 'mybatis-plus-only') { %>**含义**：
+
+- 业务持久化统一使用 MyBatis-Plus 的 `entity / mapper` 方式
+- CRUD、单表条件查询、条件更新、逻辑删除优先用 `BaseMapper` + `LambdaQueryWrapper` / `LambdaUpdateWrapper`
+- 复杂联表分页、聚合、跨表投影：写 mapper 层 `@Select` / `@Update` 或 XML SQL；**不内联在 service / controller**
+- **禁止**新增 `JdbcTemplate` / `NamedParameterJdbcTemplate` 作为 CRUD / 查询实现
+- 历史 `JdbcTemplate` 代码改动时应迁移到 mapper 方式
+- `JdbcTemplate` 仅允许保留在测试夹具、迁移工具、一次性运维脚本、基础设施适配中
+
+**lint 阻断条件**：`server/src/main/java/**/*.java` 中出现 `import org.springframework.jdbc.core.JdbcTemplate` 或 `import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate`（被 governance-lint 标 warning）。
+<% } else if (it.standards.ormConvention === 'jpa-only') { %>**含义**：业务持久化统一使用 Spring Data JPA / Hibernate；禁止在业务代码中使用 JdbcTemplate / 原生 SQL。
+<% } else if (it.standards.ormConvention === 'sqlalchemy-orm-only') { %>**含义**：业务持久化统一使用 SQLAlchemy ORM（`Session` + 模型）；禁止在业务代码里用 raw `text()` SQL（迁移文件除外）。
+<% } else if (it.standards.ormConvention === 'knex-only') { %>**含义**：业务持久化统一使用 Knex query builder；禁止在业务代码里用 `db.raw()`（迁移与 seed 除外）。
+<% } else if (it.standards.ormConvention === 'prisma-only') { %>**含义**：业务持久化统一使用 Prisma Client；禁止在业务代码里用 `$queryRaw`（迁移除外）。
+<% } else if (it.standards.ormConvention === 'gorm-only') { %>**含义**：业务持久化统一使用 GORM；禁止在业务代码里用 `db.Raw()`。
+<% } else if (it.standards.ormConvention === 'sqlx-only') { %>**含义**：业务持久化统一使用 sqlx；禁止散用 `database/sql` 直接 driver 调用。
+<% } %>
+
+**调整流程**：
+
+1. 改 frontmatter 的 `ormConvention` 字段属于 **Tier 4** 决策（参见 `docs/governance/change-tiers.md`），需要 ADR
+2. 取值 `none` 关闭 lint（不推荐，意味着团队接受混用）
+3. 升级或更换 ORM 是**仓库级**变更，不是单个 PR 范围内的事
+<% } %>
 
 ## 关联
 

package/src/templates/contracts-base/files/dictionaries/event-types.yaml

@@ -0,0 +1,16 @@
+version: 1
+name: event-types
+description: 平台事件类型字典。事件 envelope schema 在 contracts/events/，本文件统一登记 type 字符串。
+items:
+  - code: user.created
+    domain: user
+    source: server
+    description: 新用户注册成功。
+  - code: user.deleted
+    domain: user
+    source: server
+    description: 用户被软删除。
+  - code: audit.event.ingested
+    domain: audit
+    source: server
+    description: 审计事件已被平台接收并归档。

package/src/templates/contracts-base/files/dictionaries/locales.yaml

@@ -0,0 +1,12 @@
+version: 1
+name: locales
+description: 平台支持的语言 locale 码表。前端 i18n / 后端模板渲染共享。
+items:
+  - code: zh-CN
+    label: 简体中文
+    order: 10
+    description: 默认 locale。
+  - code: en-US
+    label: English (US)
+    order: 20
+    description: 国际化第二语言。

package/src/templates/contracts-base/files/dictionaries/roles.yaml

@@ -0,0 +1,12 @@
+version: 1
+name: roles
+description: 用户 / 终端 / API caller 的角色码表。新增时改这里 + 同 PR 加迁移文件 / seed。
+items:
+  - code: admin
+    label: 系统管理员
+    order: 10
+    description: 可执行所有管理操作（账号、配置、审计）。
+  - code: user
+    label: 普通用户
+    order: 20
+    description: 默认注册角色；只能访问自己的资源。

package/src/templates/contracts-base/files/dictionaries/status.yaml

@@ -0,0 +1,16 @@
+version: 1
+name: status
+description: 通用状态枚举（活跃 / 停用 / 删除等），跨多个实体复用。
+items:
+  - code: active
+    label: 活跃
+    order: 10
+    description: 资源处于正常使用状态。
+  - code: disabled
+    label: 已停用
+    order: 20
+    description: 资源被管理员手动停用，可恢复。
+  - code: deleted
+    label: 已删除
+    order: 30
+    description: 资源被软删除（保留 deleted_at），仅审计可见。

package/src/templates/contracts-base/files/errors/common-errors.yaml

@@ -0,0 +1,40 @@
+version: 1
+namespace: common
+description: 跨服务通用错误码（鉴权、参数校验、限流等）。各业务错误码请新建 <namespace>-errors.yaml 文件。
+errors:
+  - code: COMMON-VALIDATION-FAILED
+    http_status: 422
+    category: validation
+    message: 请求参数校验失败
+    retryable: false
+    description: 字段缺失、类型错误或值越界。详细信息见 response 的 details 数组。
+  - code: COMMON-UNAUTHORIZED
+    http_status: 401
+    category: auth
+    message: 未登录或登录已过期
+    retryable: false
+    description: 调用需要鉴权的端点但未提供有效 token；客户端应跳转登录。
+  - code: COMMON-FORBIDDEN
+    http_status: 403
+    category: auth
+    message: 当前账号无权访问该资源
+    retryable: false
+    description: 已登录但角色 / 权限不足；不要在错误信息里泄露资源是否存在。
+  - code: COMMON-NOT-FOUND
+    http_status: 404
+    category: resource
+    message: 资源不存在
+    retryable: false
+    description: ID 错误或资源已被删除。
+  - code: COMMON-RATE-LIMITED
+    http_status: 429
+    category: throttle
+    message: 请求过于频繁
+    retryable: true
+    description: 客户端应根据 Retry-After 头退避后重试。
+  - code: COMMON-INTERNAL-ERROR
+    http_status: 500
+    category: server
+    message: 系统繁忙，请稍后重试
+    retryable: true
+    description: 兜底错误码；具体原因写入 server log + tracing，不暴露给客户端。

package/src/templates/contracts-base/files/errors/server-errors.yaml

@@ -0,0 +1,16 @@
+version: 1
+namespace: server
+description: 后端业务错误码示例。新增按业务域拆分（如 admin-errors.yaml / iam-errors.yaml / billing-errors.yaml）。
+errors:
+  - code: SERVER-USER-NOT-FOUND
+    http_status: 404
+    category: resource
+    message: 用户不存在
+    retryable: false
+    description: 通过 ID / email 查找用户失败。
+  - code: SERVER-USER-EMAIL-CONFLICT
+    http_status: 409
+    category: resource
+    message: 邮箱已被占用
+    retryable: false
+    description: 注册或更新邮箱时检测到唯一约束冲突。

package/src/templates/contracts-base/files/events/audit-event.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.<%= it.options.projectName %>.local/events/audit-event.schema.json",
+  "title": "Audit Event Envelope",
+  "description": "审计事件统一信封；type 字段对应 contracts/dictionaries/event-types.yaml 中的 code。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["eventId", "type", "occurredAt", "source", "payload"],
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "事件唯一 ID。"
+    },
+    "type": {
+      "type": "string",
+      "description": "事件类型，例如 user.created。须存在于 contracts/dictionaries/event-types.yaml。"
+    },
+    "occurredAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "事件发生时间（UTC，毫秒精度 ISO 8601）。"
+    },
+    "source": {
+      "type": "string",
+      "description": "事件来源服务或模块。"
+    },
+    "userId": {
+      "type": ["string", "null"],
+      "description": "触发该事件的用户 ID（系统事件可为 null）。"
+    },
+    "traceId": {
+      "type": ["string", "null"],
+      "description": "贯穿请求链路的 trace ID。"
+    },
+    "result": {
+      "type": "string",
+      "enum": ["success", "failure"],
+      "description": "事件处理结果。"
+    },
+    "payload": {
+      "type": "object",
+      "description": "事件业务载荷。各事件类型的 payload 形态在事件类型自身的 schema 中收紧约束。",
+      "additionalProperties": true
+    }
+  }
+}

package/src/templates/contracts-base/fragment.yaml

@@ -1,5 +1,5 @@
 name: contracts-base
-version: 1.1.0
+version: 1.2.0
 appliesWhen: {}
 priority: 10
 files:
@@ -15,18 +15,33 @@ files:
   - from: files/_spectral.yaml
     to: contracts/.spectral.yaml
     render: false
-  - from: files/dictionaries/domain-models.yaml
-    to: contracts/dictionaries/domain-models.yaml
+  # 字典：每个域一份独立 yaml；新增不要回头合并
+  - from: files/dictionaries/roles.yaml
+    to: contracts/dictionaries/roles.yaml
     render: false
-  - from: files/dictionaries/enums.yaml
-    to: contracts/dictionaries/enums.yaml
+  - from: files/dictionaries/status.yaml
+    to: contracts/dictionaries/status.yaml
     render: false
-  - from: files/errors/error-codes.yaml
-    to: contracts/errors/error-codes.yaml
+  - from: files/dictionaries/locales.yaml
+    to: contracts/dictionaries/locales.yaml
+    render: false
+  - from: files/dictionaries/event-types.yaml
+    to: contracts/dictionaries/event-types.yaml
+    render: false
+  # 错误码：通用 + 业务域拆开
+  - from: files/errors/common-errors.yaml
+    to: contracts/errors/common-errors.yaml
+    render: false
+  - from: files/errors/server-errors.yaml
+    to: contracts/errors/server-errors.yaml
     render: false
   - from: files/errors/error-response.schema.json
     to: contracts/errors/error-response.schema.json
     render: false
+  # 事件：每个事件域一份 schema；通过 dictionaries/event-types.yaml 索引
+  - from: files/events/audit-event.schema.json
+    to: contracts/events/audit-event.schema.json
+    render: true
   - from: files/environment/.env.example
     to: contracts/environment/.env.example
     render: false
@@ -36,9 +51,6 @@ files:
   - from: files/states-gitkeep
     to: contracts/states/.gitkeep
     render: false
-  - from: files/events-gitkeep
-    to: contracts/events/.gitkeep
-    render: false
   - from: files/resources-examples-gitkeep
     to: contracts/resources/examples/.gitkeep
     render: false

package/src/templates/contracts-rest/fragment.yaml

@@ -1,7 +1,8 @@
 name: contracts-rest
-version: 1.0.0
+version: 1.1.0
 appliesWhen:
   contract: rest
+  openapiLayout: single
 priority: 20
 files:
   - from: files/api.yaml

package/src/templates/contracts-rest-by-audience/files/_components-README.md

@@ -0,0 +1,32 @@
+# `_components/` — 跨 audience 共享的 OpenAPI 类型
+
+本目录的 `schemas.yaml` 是 `admin-api.yaml` / `user-api.yaml` / `agent-api.yaml` 共享的类型库。
+
+## 引用方式
+
+```yaml
+$ref: '_components/schemas.yaml#/components/schemas/User'
+```
+
+## 何时改这里
+
+- 添加跨 audience 的实体（User / Order / ErrorResponse 等）
+- 修改既有共享类型的字段（**Tier 3**，必须同步 `contracts/CHANGELOG.md`）
+- 删字段或改类型（**Tier 4**，破坏性，需要 ADR）
+
+## 何时**不**改这里
+
+- 单个 audience 私有的 DTO（例如管理员后台的 `AdminUserListItem`）
+  写在对应 API 文件自己的 `components/schemas` 里，并用 audience 前缀命名
+
+## 工具兼容性
+
+Spectral / openapi-generator-cli / Redoc / Postman 都原生支持跨文件 `$ref`，不需要任何配置：
+
+```bash
+npx --yes @stoplight/spectral-cli lint contracts/openapi/admin-api.yaml
+npx --yes @stoplight/spectral-cli lint contracts/openapi/user-api.yaml
+npx --yes @stoplight/spectral-cli lint contracts/openapi/agent-api.yaml
+```
+
+> Spectral 会自动 follow `$ref` 进入 `_components/schemas.yaml` 校验。

package/src/templates/contracts-rest-by-audience/files/_components-schemas.yaml

@@ -0,0 +1,78 @@
+# 跨 audience 共享的 schemas / parameters / responses。
+#
+# 引用方式：
+#   $ref: '_components/schemas.yaml#/components/schemas/User'
+#
+# 不要在 admin-api.yaml / user-api.yaml / agent-api.yaml 各自重复定义同名实体；
+# 添加新共享类型时改这里，并在对应 API 文件用 $ref 引入。
+#
+# 仅 audience 私有的类型（例如 admin 后台特定 DTO）可以放在自己 API 文件的
+# components/schemas 里，但要在 schema 名字加 audience 前缀以避免误用，
+# 例如 AdminUserListItem。
+
+openapi: 3.1.0
+info:
+  title: Shared components
+  version: 0.1.0
+paths: {}
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email, displayName]
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: 用户 ID。
+        email:
+          type: string
+          format: email
+        displayName:
+          type: string
+          maxLength: 128
+        createdAt:
+          type: string
+          format: date-time
+    AgentRegistration:
+      type: object
+      required: [terminalId, hostname, osVersion]
+      properties:
+        terminalId:
+          type: string
+          description: 终端唯一 ID（首次注册由客户端生成 UUID）。
+        hostname:
+          type: string
+        osVersion:
+          type: string
+    AgentRegistrationResult:
+      type: object
+      required: [terminalId, agentToken, expiresAt]
+      properties:
+        terminalId:
+          type: string
+        agentToken:
+          type: string
+          description: 后续调用所有 /api/agent/v1/* 端点时携带于 Authorization header。
+        expiresAt:
+          type: string
+          format: date-time
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: 错误码，对应 contracts/errors/*.yaml 中的 code 字段。
+        message:
+          type: string
+        details:
+          type: array
+          items: { type: object }
+  responses:
+    Unauthorized:
+      description: 未登录或登录已过期
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'

package/src/templates/contracts-rest-by-audience/files/admin-api.yaml

@@ -0,0 +1,37 @@
+openapi: 3.1.0
+info:
+  title: <%= it.options.projectName %> Admin API
+  version: 0.1.0
+  description: |
+    管理员后台 API。
+
+    路径前缀统一为 `/api/admin/v1/`；调用方限定为内部管理员前端 + 管理工具。
+    schemas 通过 $ref 引用 `_components/schemas.yaml`，避免在多个 audience 文件之间重复。
+  contact:
+    name: Backend Team
+servers:
+  - url: https://api.example.com
+    description: 生产环境
+  - url: http://127.0.0.1:8080
+    description: 本地开发
+tags:
+  - name: users
+    description: 用户管理
+paths:
+  /api/admin/v1/users:
+    get:
+      tags: [users]
+      summary: 列出所有用户（管理员）
+      operationId: adminListUsers
+      responses:
+        '200':
+          description: 用户列表
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '_components/schemas.yaml#/components/schemas/User'
+        '401':
+          $ref: '_components/schemas.yaml#/components/responses/Unauthorized'
+components: {}

package/src/templates/contracts-rest-by-audience/files/agent-api.yaml

@@ -0,0 +1,37 @@
+openapi: 3.1.0
+info:
+  title: <%= it.options.projectName %> Agent API
+  version: 0.1.0
+  description: |
+    Agent 公共接入 API。
+
+    路径前缀统一为 `/api/agent/v1/`；调用方限定为终端常驻 agent / 桌面 / CLI 客户端。
+    与管理员 API 完全隔离：agent 不能调用 admin 端点，反之亦然。
+servers:
+  - url: https://api.example.com
+    description: 生产环境
+  - url: http://127.0.0.1:8080
+    description: 本地开发
+tags:
+  - name: registration
+    description: 终端注册
+paths:
+  /api/agent/v1/register:
+    post:
+      tags: [registration]
+      summary: 终端首次注册
+      operationId: agentRegister
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '_components/schemas.yaml#/components/schemas/AgentRegistration'
+      responses:
+        '200':
+          description: 注册成功
+          content:
+            application/json:
+              schema:
+                $ref: '_components/schemas.yaml#/components/schemas/AgentRegistrationResult'
+components: {}

package/src/templates/contracts-rest-by-audience/files/user-api.yaml

@@ -0,0 +1,33 @@
+openapi: 3.1.0
+info:
+  title: <%= it.options.projectName %> User API
+  version: 0.1.0
+  description: |
+    用户自助 API。
+
+    路径前缀统一为 `/api/user/v1/`；调用方限定为终端用户的前端 / 移动端。
+    所有端点必须遵守"用户只能看到自己资源"的约束。
+servers:
+  - url: https://api.example.com
+    description: 生产环境
+  - url: http://127.0.0.1:8080
+    description: 本地开发
+tags:
+  - name: profile
+    description: 当前用户资料
+paths:
+  /api/user/v1/profile:
+    get:
+      tags: [profile]
+      summary: 获取当前用户资料
+      operationId: userGetProfile
+      responses:
+        '200':
+          description: 当前用户资料
+          content:
+            application/json:
+              schema:
+                $ref: '_components/schemas.yaml#/components/schemas/User'
+        '401':
+          $ref: '_components/schemas.yaml#/components/responses/Unauthorized'
+components: {}

package/src/templates/contracts-rest-by-audience/fragment.yaml

@@ -0,0 +1,22 @@
+name: contracts-rest-by-audience
+version: 1.0.0
+appliesWhen:
+  contract: rest
+  openapiLayout: by-audience
+priority: 20
+files:
+  - from: files/admin-api.yaml
+    to: contracts/openapi/admin-api.yaml
+    render: true
+  - from: files/user-api.yaml
+    to: contracts/openapi/user-api.yaml
+    render: true
+  - from: files/agent-api.yaml
+    to: contracts/openapi/agent-api.yaml
+    render: true
+  - from: files/_components-schemas.yaml
+    to: contracts/openapi/_components/schemas.yaml
+    render: true
+  - from: files/_components-README.md
+    to: contracts/openapi/_components/README.md
+    render: true

package/src/templates/contracts-rest-events/fragment.yaml

@@ -1,7 +1,8 @@
 name: contracts-rest-events
-version: 1.0.0
+version: 1.1.0
 appliesWhen:
   contract: rest+events
+  openapiLayout: single
 priority: 20
 files:
   - from: files/api.yaml

package/src/templates/contracts-rest-events-by-audience/files/_components-README.md

@@ -0,0 +1,32 @@
+# `_components/` — 跨 audience 共享的 OpenAPI 类型
+
+本目录的 `schemas.yaml` 是 `admin-api.yaml` / `user-api.yaml` / `agent-api.yaml` 共享的类型库。
+
+## 引用方式
+
+```yaml
+$ref: '_components/schemas.yaml#/components/schemas/User'
+```
+
+## 何时改这里
+
+- 添加跨 audience 的实体（User / Order / ErrorResponse 等）
+- 修改既有共享类型的字段（**Tier 3**，必须同步 `contracts/CHANGELOG.md`）
+- 删字段或改类型（**Tier 4**，破坏性，需要 ADR）
+
+## 何时**不**改这里
+
+- 单个 audience 私有的 DTO（例如管理员后台的 `AdminUserListItem`）
+  写在对应 API 文件自己的 `components/schemas` 里，并用 audience 前缀命名
+
+## 工具兼容性
+
+Spectral / openapi-generator-cli / Redoc / Postman 都原生支持跨文件 `$ref`，不需要任何配置：
+
+```bash
+npx --yes @stoplight/spectral-cli lint contracts/openapi/admin-api.yaml
+npx --yes @stoplight/spectral-cli lint contracts/openapi/user-api.yaml
+npx --yes @stoplight/spectral-cli lint contracts/openapi/agent-api.yaml
+```
+
+> Spectral 会自动 follow `$ref` 进入 `_components/schemas.yaml` 校验。

package/src/templates/contracts-rest-events-by-audience/files/_components-schemas.yaml

@@ -0,0 +1,78 @@
+# 跨 audience 共享的 schemas / parameters / responses。
+#
+# 引用方式：
+#   $ref: '_components/schemas.yaml#/components/schemas/User'
+#
+# 不要在 admin-api.yaml / user-api.yaml / agent-api.yaml 各自重复定义同名实体；
+# 添加新共享类型时改这里，并在对应 API 文件用 $ref 引入。
+#
+# 仅 audience 私有的类型（例如 admin 后台特定 DTO）可以放在自己 API 文件的
+# components/schemas 里，但要在 schema 名字加 audience 前缀以避免误用，
+# 例如 AdminUserListItem。
+
+openapi: 3.1.0
+info:
+  title: Shared components
+  version: 0.1.0
+paths: {}
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email, displayName]
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: 用户 ID。
+        email:
+          type: string
+          format: email
+        displayName:
+          type: string
+          maxLength: 128
+        createdAt:
+          type: string
+          format: date-time
+    AgentRegistration:
+      type: object
+      required: [terminalId, hostname, osVersion]
+      properties:
+        terminalId:
+          type: string
+          description: 终端唯一 ID（首次注册由客户端生成 UUID）。
+        hostname:
+          type: string
+        osVersion:
+          type: string
+    AgentRegistrationResult:
+      type: object
+      required: [terminalId, agentToken, expiresAt]
+      properties:
+        terminalId:
+          type: string
+        agentToken:
+          type: string
+          description: 后续调用所有 /api/agent/v1/* 端点时携带于 Authorization header。
+        expiresAt:
+          type: string
+          format: date-time
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: 错误码，对应 contracts/errors/*.yaml 中的 code 字段。
+        message:
+          type: string
+        details:
+          type: array
+          items: { type: object }
+  responses:
+    Unauthorized:
+      description: 未登录或登录已过期
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'