Swagger Page Gen — 主入口

目录结构

swagger-page-gen/
├── SKILL.md                              # 本文件，总入口与使用说明
├── foundation/
│   ├── config-validator.md              # 配置校验与落盘（必读，生成前执行）
│   ├── coding-conventions.md            # 编码规范（TS、composables、文件组织）
│   ├── api-contract.md                  # API 请求封装规范
│   └── page-schema.md                   # PageSchema 数据契约（各层通信接口）
├── domain/
│   ├── swagger-analyzer.md              # Swagger 解析与字段推断
│   ├── crud-list.md                     # 列表页模式（与UI无关）
│   ├── crud-form.md                     # 表单页模式（与UI无关）
│   └── crud-detail.md                   # 详情页模式（与UI无关）
├── adapter/
│   ├── element-plus.md                  # Element Plus 组件映射与用法
│   ├── ant-design-vue.md                # Ant Design Vue 组件映射与用法
│   └── http-client.md                   # axios 请求封装模板
└── workflow/
    ├── swagger-to-crud.md               # 主流程：一键从 swagger 生成全套页面
    └── incremental-update.md            # 增量更新：路由/API 增量合并

使用前：项目配置

在项目根目录创建 .page-gen.yml，所有生成行为依赖此配置，只需填写一次：

# .page-gen.yml
project:
  name: my-admin # 项目名称
  root: /path/to/project # 项目根目录绝对路径

tech:
  ui_library: element-plus # element-plus | ant-design-vue
  vue_version: 3
  language: typescript # typescript | javascript
  request_lib: axios

paths:
  views: src/views
  api: src/api
  router: src/router/index.ts
  composables: src/composables
  types: src/types
  request: src/utils/request # request 封装的导入路径（用于 import request from '...'）

# ─── HTTP 请求封装行为配置 ────────────────────────────────────────────────────
#
# 核心问题：你的 request.ts 拦截器是否已经剥掉响应包装体（code/message/data）？
#
# 情况 A（推荐，本项目默认）：
#   拦截器已处理，成功时直接返回 res.data，service 层拿到的就是业务数据本身。
#   此时 response_unwrapped: true，生成的 service 函数返回类型直接写业务类型。
#
# 情况 B：
#   拦截器未处理，service 层拿到的是完整包装体 { code, message, data }。
#   此时 response_unwrapped: false，生成的 service 函数返回类型需包含包装层。
#
request:
  # 拦截器是否已剥离响应包装体，直接返回 data
  response_unwrapped: true

  # 封装函数的导出方式
  # named:   import { get, post, put, del } from '@/utils/request'
  # default: import request from '@/utils/request'（用 request.get / request.post）
  export_style: named # named | default  优先使用 named 导出，若不支持则使用 default 导出

  # 函数名映射（export_style: named 时生效，按实际导出名填写）
  method_names:
    get: get
    post: post
    put: put
    delete: del # 注意：delete 是保留字，通常导出为 del

  # showAllRes 配置项名称（需要获取完整响应体时透传）
  # 若拦截器不支持此功能，置为 null
  show_all_res_option: showAllRes

  # returnRaw 配置项名称（完全绕过拦截器时透传）
  # 若拦截器不支持此功能，置为 null
  return_raw_option: returnRaw

  # hideGlobalMsg 配置项名称（静默错误时透传）
  # 若拦截器不支持此功能，置为 null
  hide_global_msg_option: hideGlobalMsg

codegen:
  author: your-name
  overwrite_view: true # 同名视图是否覆盖
  overwrite_api: false # 同名API是否覆盖（建议false，走增量更新）
  page_suffix:
    list: -list # 列表页后缀，例：user-list.vue
    form: -form # 表单页后缀，例：user-form.vue
    detail: -detail # 详情页后缀，例：user-detail.vue
  dir_suffix: -page # 目录后缀，例：user-page/

pagination:
  exclude_params: # 不参与用户交互的分页参数
    - pageSize
    - currentPage
    - pageNum

router:
  group_by_tag: true # 是否按 swagger tag 分组路由
  level1_suffix: Menu # 一级路由名称后缀
  level2_suffix: Page # 二级路由名称后缀

> 注意：.page-gen.yml 是人工填写的初始配置，可能与项目实际存在偏差。
> 技能启动时会自动执行配置校验（foundation/config-validator.md），
> 校验结论落盘至 .page-gen.lock.yml，后续代码生成和 QA 以 lock 文件为准。

快速开始

方式一：一键生成（推荐）

读取 workflow/swagger-to-crud.md，提供 swagger JSON 或 URL：

请根据以下 swagger 接口生成完整的 CRUD 页面：
[粘贴 swagger JSON 或提供 URL]

方式二：分步生成

1. 先读 domain/swagger-analyzer.md 解析接口，确认 PageSchema
2. 再读对应的 domain/crud-*.md 生成页面结构
3. 最后读对应的 adapter/*.md 落地为具体 UI 组件代码

Skill 读取规则

Claude 在执行任何生成任务前，必须按以下顺序读取：

1. foundation/page-schema.md — 了解数据契约（必读）
2. foundation/coding-conventions.md — 了解编码规范（必读）
3. foundation/api-contract.md — 了解 API 层规范（必读）
4. .page-gen.yml — 读取项目原始配置（必读）
5. foundation/config-validator.md — 执行配置校验，生成 .page-gen.lock.yml（必读，读取配置后立即执行）
6. 对应的 adapter/*.md — 根据 lock 文件中 verified.tech.ui_library 加载
7. 对应的任务 skill — 根据用户需求加载

不要跳过前五步，尤其是步骤 5——配置校验是代码质量的基础保障。
步骤 6 起，所有配置引用均来自 .page-gen.lock.yml 的 verified 节，不再直接使用 .page-gen.yml。

文件职责说明

.page-gen.lock.yml 建议加入版本控制（git），方便团队共享已验证的配置状态。