@wneng/create-keel 0.4.1 → 0.5.0

package/src/templates/contracts-rest-events-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-events-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-events-by-audience/files/asyncapi.yaml

@@ -0,0 +1,8 @@
+asyncapi: 3.0.0
+info:
+  title: <%= it.options.projectName %>
+  version: 0.1.0
+  description: Event-driven contract. Document publish/subscribe channels here.
+channels: {}
+operations: {}
+components: {}

package/src/templates/contracts-rest-events-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-events-by-audience/fragment.yaml

@@ -0,0 +1,25 @@
+name: contracts-rest-events-by-audience
+version: 1.0.0
+appliesWhen:
+  contract: rest+events
+  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
+  - from: files/asyncapi.yaml
+    to: contracts/asyncapi/asyncapi.yaml
+    render: true

package/src/templates/docs-skeleton/files/governance-contracts-layout.md

@@ -0,0 +1,172 @@
+---
+last-reviewed: 2026-05-17
+---
+
+# contracts/ 目录布局与拆分策略
+
+> 本文档说明：契约（OpenAPI / 错误码 / 字典 / 事件）何时单文件、何时按受众拆分、何时再按业务域细拆。AGENTS.md §1（契约目录职责）与 `contracts/README.md`（SemVer、CHANGELOG、生成代码一致性）是上位文件。
+
+## 1. 三种 OpenAPI 布局
+
+scaffolder 通过 `--openapi-layout` 选项选择布局；生成后的项目通过 `.scaffolder.json#options.openapiLayout` 记录。
+
+### 1.1 single（默认）
+
+```
+contracts/openapi/
+└── api.yaml
+```
+
+适用：单团队、< 30 endpoints、所有调用方共享认证模型。**这是 90% 项目的起点**。`contracts-rest` / `contracts-rest-events` fragment 在 `openapiLayout=single` 时落到此布局。
+
+### 1.2 by-audience（按受众拆分）
+
+```
+contracts/openapi/
+├── admin-api.yaml        # 后台管理员（admin token / 审计严格）
+├── user-api.yaml         # C 端用户（user token / OIDC）
+├── agent-api.yaml        # 终端 / Agent（设备签名 / mTLS）
+└── _components/
+    ├── schemas.yaml      # 共享数据模型（User、Pagination、Error）
+    └── README.md
+```
+
+适用：以下任一信号出现：
+
+- **认证模型分裂**：admin / user / agent 三类调用方使用不同的 security scheme（JWT vs OIDC vs mTLS），同一文件内放三套 `securitySchemes` 让生成代码与 mock 都尴尬
+- **多团队负责**：不同团队各自维护各自的 audience，拆开避免 PR 合并冲突
+- **endpoints > 30**：单文件已超 1500 行，IDE 跳转 / spectral lint 反应慢
+- **rate limit / 版本节奏不同**：admin 偶尔升 v2，user 严格 v1 永久，agent 节奏由设备版本决定
+
+scaffolder 通过 `--openapi-layout by-audience` 选择此布局，对应 `contracts-rest-by-audience` 与 `contracts-rest-events-by-audience` fragment。
+
+跨文件 `$ref` 用法：
+
+```yaml
+# admin-api.yaml
+paths:
+  /admin/users:
+    post:
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: './_components/schemas.yaml#/User'
+```
+
+`_components/schemas.yaml` 是**唯一**的共享模型来源；任何 audience 文件**禁止**重复声明 `User`、`Pagination`、`ErrorResponse`。生成代码工具（openapi-generator / oapi-codegen）必须开启多文件 bundle 模式（先 `swagger-cli bundle` 或 `redocly bundle` 合一再生成）。
+
+### 1.3 by-domain（按业务域，未内置）
+
+```
+contracts/openapi/
+├── auth/
+│   ├── auth-api.yaml
+│   └── _components/schemas.yaml
+├── face-engine/
+│   ├── face-api.yaml
+│   └── _components/schemas.yaml
+├── ops/
+│   └── ops-api.yaml
+└── _components/
+    └── schemas.yaml      # 跨域共享（User、Tenant）
+```
+
+适用：**by-audience 仍嫌大**且业务域可清晰隔离，例如：
+
+- 同一 audience 下有 ≥ 5 个独立业务域，每个域 endpoints > 20
+- 业务域有独立的发布周期（face-engine 每周一发，ops 每月一发）
+- 业务域归属不同子团队，PR review 渠道完全隔离
+
+⚠️ **不要过早进 by-domain**：scaffolder **不内置**这个布局，需要时由项目自行创建子目录与 `$ref` 路径。`contracts-base` fragment 的 `dictionaries/` `errors/` `events/` 已经按域拆分（见 §3），通常这些就够了；OpenAPI 拆到 by-domain 是最后一步。
+
+## 2. 何时升级布局
+
+| 当前 | 信号 | 下一步 |
+| --- | --- | --- |
+| single | endpoints > 30 或 单文件 > 1500 行 或 出现第二种 securityScheme | by-audience |
+| by-audience | 单 audience 内 > 5 业务域且各自独立发布 | by-domain |
+
+升级是 **Tier 4**（架构变更）：
+
+1. 写 ADR 记录"为什么从 X 升 Y"
+2. 在同一 PR 内迁移所有 endpoints + 更新所有跨文件 `$ref`
+3. `contracts/CHANGELOG.md` 记 MINOR（路径变了但模型不变）或 MAJOR（路径 + 模型同时变）
+4. 更新 `docs/06-集成对接/` 中已有的对接文档（如果有）
+
+不要做"逐步迁移"——契约文件结构混搭比单一臃肿更难维护。
+
+## 3. 字典 / 错误码 / 事件的拆分
+
+`contracts-base` fragment 默认按域拆分，**不再**用单一聚合文件：
+
+```
+contracts/
+├── dictionaries/
+│   ├── roles.yaml          # 用户角色枚举
+│   ├── status.yaml         # 通用状态机（active/inactive/pending/...）
+│   ├── locales.yaml        # 支持的语言
+│   └── event-types.yaml    # 事件类型索引（同时是 events/*.schema.json 的目录）
+├── errors/
+│   ├── common-errors.yaml  # 横切错误（auth / validation / rate-limit）
+│   ├── server-errors.yaml  # 后端业务错误
+│   └── error-response.schema.json
+└── events/
+    └── audit-event.schema.json   # 每个事件域一份 schema，由 dictionaries/event-types.yaml 索引
+```
+
+新增字典 / 错误域时**直接添新文件**，不要往现有文件里塞：
+
+- 新加一个"支付状态"枚举 → `contracts/dictionaries/payment-status.yaml`，**不要**塞进 `status.yaml`
+- 新加一类"face-engine 业务错误" → `contracts/errors/face-engine-errors.yaml`
+- 新加一类"face-detected 事件" → `contracts/events/face-detected.schema.json`，并在 `dictionaries/event-types.yaml` 加一行索引
+
+域间引用通过 `$ref` 跨文件：
+
+```yaml
+# dictionaries/event-types.yaml
+event-types:
+  audit:
+    schema: ../events/audit-event.schema.json
+    description: 审计事件，所有用户敏感操作必须发
+  face-detected:
+    schema: ../events/face-detected.schema.json
+```
+
+## 4. CI 校验
+
+- `spectral lint contracts/openapi/**/*.yaml`：对 single 与 by-audience 都生效（递归 glob）
+- 多文件 bundle：`redocly bundle contracts/openapi/admin-api.yaml -o /tmp/admin.bundled.yaml` 后再 lint，确保跨文件 `$ref` 解析无错
+- `ajv` 校验 `contracts/events/*.schema.json` 与 `contracts/dictionaries/*.yaml`
+- 生成代码 diff 检查（`generated/` 重生成后必须无 diff）对所有布局通用
+
+scaffolder 生成的 `.gitee/pipelines/ci.yml` / `.github/workflows/ci.yml` 已覆盖 `contracts/openapi/**/*.yaml` 递归 glob，单文件 / by-audience 无需额外 CI 改动。
+
+## 5. 与生成代码 (`generated/`) 的关系
+
+无论哪种布局，`generated/` 都是**重新生成**的目标，禁止手改。布局变化时：
+
+- single → by-audience：生成器命令从 `--input api.yaml` 变成多次调用（每个 audience 一次），输出到独立的 `generated/admin/`、`generated/user/`、`generated/agent/` 子目录
+- by-audience → by-domain：在每个 audience 下再分子目录
+
+CI "重新生成 diff 为空" 的检查对所有布局保持通用——只要把 `make generate` / `npm run generate` 脚本里的命令同步更新即可。
+
+## 6. AGENTS.md / Tier 关系
+
+- 修改 `contracts/openapi/**/*.yaml` 任意文件 → 至少 **Tier 3**（contract-affecting），按 AGENTS.md §3.1 执行
+- 拆分布局（single → by-audience / by-audience → by-domain）→ **Tier 4**（架构变更），需 ADR
+- 在 by-audience 模式下加 endpoint 仅触及一个 audience 文件 → 仍是 Tier 3，PR 描述说明"只触及 admin-api"即可，不需要全文档投入
+
+## 7. FAQ
+
+**Q: by-audience 下的 `_components/schemas.yaml` 算几个文件？**
+A: 1 个共享模型仓库。`User` `Pagination` `ErrorResponse` 都放这里。当 schemas.yaml 自身 > 800 行时再考虑拆 `_components/user.yaml` `_components/pagination.yaml`。
+
+**Q: events 是否也按 audience 拆？**
+A: 不需要。事件天然是按业务域分的（`audit-event` / `face-detected` / `payment-completed`），`contracts/events/<domain>.schema.json` 已经满足；不要再人为加一层 audience。
+
+**Q: AsyncAPI 文件要不要按 audience 拆？**
+A: 默认 single（`contracts/asyncapi/asyncapi.yaml`）。事件总线一般是单一 broker（kafka / redis-stream），订阅端按 audience 区分是消费侧的事，不是契约侧的事。需要时再升级。
+
+**Q: 我现在是 single，未来会不会被强制升 by-audience？**
+A: 不会。AGENTS.md / governance 不强制升级；只在你**主动**遇到 §2 信号时升。single 项目永远可以保持 single。

package/src/templates/docs-skeleton/fragment.yaml

@@ -120,6 +120,9 @@ files:
   - from: files/governance-database.md
     to: docs/governance/database.md
     render: false
+  - from: files/governance-contracts-layout.md
+    to: docs/governance/contracts-layout.md
+    render: false
   - from: files/governance-checklists.md
     to: docs/governance/checklists.md
     render: true

package/src/templates/root-files/files/AGENTS.md

@@ -186,6 +186,7 @@
 | 修改路径 | 必读 |
 | --- | --- |
 | `contracts/**` | `contracts/README.md`、`docs/governance/integrations.md`、`docs/governance/checklists.md` |
+| `contracts/openapi/**` | 上一行 + `docs/governance/contracts-layout.md`（single / by-audience 选型与升级） |
 | `docs/**`（除 `docs/governance/` 与 `docs/06-集成对接/`） | `docs/README.md`、`docs/governance/docs-references.md`、`docs/governance/checklists.md` |
 <% if (it.options.integrations) { %>| `docs/06-集成对接/**` | `docs/governance/integrations.md` |
 <% } %>| `docs/governance/**` | `docs/governance/README.md`；同一 PR 必须同步本文件中对应摘要 |
@@ -223,6 +224,7 @@
 | tools / scripts 完整规则 | [`docs/governance/tools-scripts.md`](docs/governance/tools-scripts.md) |
 | 变更分级（六档 Tier） | [`docs/governance/change-tiers.md`](docs/governance/change-tiers.md) |
 | 数据库目录 / 迁移工具 / SQL 归属 | [`docs/governance/database.md`](docs/governance/database.md) |
+| 契约多文件布局（single / by-audience） | [`docs/governance/contracts-layout.md`](docs/governance/contracts-layout.md) |
 | 完整 checklist | [`docs/governance/checklists.md`](docs/governance/checklists.md) |
 | 治理细则索引 | [`docs/governance/README.md`](docs/governance/README.md) |
 

package/src/templates/welcome-html/files/WELCOME.md

@@ -0,0 +1,39 @@
+# 👋 欢迎 — <%= it.options.projectName %>
+
+本项目由 [keel](https://gitee.com/wangneng521/keel) 框架（@wneng/create-keel <%= it.scaffolderVersion %>）生成。
+
+## 🚀 第一次进项目，先看这个
+
+打开 [`.keel/welcome.html`](.keel/welcome.html) — 这是一份**面向新成员的可视化指南**，含：
+
+- 目录速查 / 关键概念（Tier、Doc Weight、Contract First）
+- 按任务找入口（修 bug / 加 API / 重构 / 升级依赖）
+- 常用命令（按本项目实际选型生成）
+- AI 协作规则
+- 常见问题
+
+> 双击文件即可在浏览器打开；IDE 里也能 Open in Browser。完全离线，不依赖外部 CDN。
+
+## 📚 给开发者 / AI 的入口
+
+| 看什么 | 进哪儿 |
+|---|---|
+| AI 协作总纲 | [`AGENTS.md`](AGENTS.md) |
+| 文档门户（人类） | [`docs/README.md`](docs/README.md) |
+| 契约（机器真值） | [`contracts/README.md`](contracts/README.md) |
+| 治理细则 | [`docs/governance/`](docs/governance/) |
+| 变更分级 | [`docs/governance/change-tiers.md`](docs/governance/change-tiers.md) |
+<% if (it.options.database !== 'none') { %>| 数据库目录 | [`docs/governance/database.md`](docs/governance/database.md) |
+<% } %>
+
+## 🧑‍💻 想直接动手？
+
+```bash
+<% if (it.options.backend === 'node') { %>cd server && npm install && npm test
+<% } else if (it.options.backend === 'java') { %>cd server && mvn -B verify
+<% } else if (it.options.backend === 'python') { %>cd server && python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]" && pytest -q
+<% } else if (it.options.backend === 'go') { %>cd server && go mod download && go test ./...
+<% } %><% if (it.options.frontend === 'react' || it.options.frontend === 'vue') { %>cd web && npm install && npm run dev
+<% } %>```
+
+完整命令见 `.keel/welcome.html` §5。

package/src/templates/welcome-html/files/keel-README.md

@@ -0,0 +1,28 @@
+# .keel/
+
+keel 框架的**元数据 / 资料目录**，与 `.kiro/` `.github/` 等 IDE / 平台目录区分开。
+
+## 文件清单
+
+| 文件 | 用途 |
+|---|---|
+| `welcome.html` | 面向新成员的可视化指南（双击打开）。包含目录速查、关键概念、任务入口、常用命令、FAQ |
+| `README.md` | 本文件 |
+
+> 项目根的 `.scaffolder.json` 是 keel scaffolder 的**机器元数据**，不在本目录——它要保持在仓库根才能让升级 / 校验工具找到。
+
+## 是否要进版本控制？
+
+`.keel/` 目录建议**进**版本控制：
+
+- `welcome.html` 是面向**全团队**的入门资料，不是个人偏好
+- 升级 keel 后 `welcome.html` 会被新生成的版本覆盖；如果你做过本地修改要备份
+- 不要把任何机密、个人 IDE 配置放进 `.keel/`
+
+## 想自己改 welcome.html？
+
+`welcome.html` 是单文件、内联 CSS / JS、无外部依赖的纯静态页面，可以直接改。
+但下次跑 `npx @wneng/create-keel ...` 升级会覆盖它。如要保护本地改动：
+
+- 选项 1：把改动写进 `docs/` 下的对应 markdown，让 welcome.html 仍是"上游版本"
+- 选项 2：在文件顶部加 `<!-- keep-local -->`（未来 scaffolder 升级时会跳过覆盖；目前是约定，未自动化）