目录结构与配置

server/addons/{name}/

├── addon.yaml                  # 扩展元信息（必须）

├── module.go                   # 入口文件：路由注册（必须）

├── middleware.go               # 自定义鉴权中间件（仅双控制器模式）

├── api/                        # API 定义（请求/响应结构体）

│   └── {name}_xxx.go

├── controller/                 # 控制器

│   ├── controller.go           # struct 定义（ControllerV1 / AdminControllerV1）

│   └── xxx.go                  # 具体业务方法

├── logic/                      # 业务逻辑

│   └── xxx/xxx.go

├── model/                      # 数据模型

│   └── xxx.go

├── service/                    # 服务接口（gf gen service 生成）

│   └── xxx.go

├── queues/                     # 消息队列消费者（按需创建）

│   └── xxx.go

├── crons/                      # 定时任务（按需创建）

│   └── xxx.go

├── install/                    # 安装 SQL

│   ├── pgsql.sql

│   └── mysql.sql

├── uninstall/                  # 卸载 SQL

│   ├── pgsql.sql

│   └── mysql.sql

└── upgrade/                    # 升级 SQL（幂等写法）

    ├── pgsql.sql

    └── mysql.sql

web/src/addons/{name}/

├── api/                        # 前端 API 接口

│   └── xxx.ts

└── views/                      # 页面组件

    └── xxx/

        ├── index.vue

        └── modules/

            └── xxx-dialog.vue

# 基础信息

name: shop                        # 扩展标识（英文小写，与目录名一致）

version: "1.0.0"                  # 当前版本号（语义化版本）

title: "商城管理"                  # 显示名称

description: "在线商城功能"        # 描述

author: "开发者A"                  # 作者


# 版本控制

min_version: "1.3.0"              # 要求的最低系统版本

min_upgrade_from: ""              # 最低可升级版本（留空不限制）


# 更新日志（升级时展示给用户）

changelog:

  - "新增订单管理"

  - "修复支付回调问题"



# 功能声明（仅用于说明，不影响逻辑）

features:

  routes: true

  websocket: false

  queue: false

  cron: false



# 菜单声明（安装时自动写入数据库）

menus:

  admin:                          # 后台管理菜单

    - title: "商城管理"

      name: "ShopManage"          # 必须以扩展名的 PascalCase 开头

      path: "shop"

      icon: "ri:shopping-cart-line"

      type: 1                     # 1=目录, 2=菜单, 3=按钮

      sort: 60

      children:

        - title: "订单管理"

          name: "ShopOrderList"

          path: "order"

          component: "@addons/shop/views/order"   # 前端组件路径

          type: 2

          sort: 1

          children:

            - title: "新增/编辑"

              name: "ShopOrderEdit"

              type: 3

              perms: "/admin/shop/order/edit"      # 权限标识

              sort: 1

            - title: "删除"

              name: "ShopOrderDelete"

              type: 3

              perms: "/admin/shop/order/delete"

              sort: 2

  tenant: []                      # 租户端菜单（结构相同）

@addons/shop/views/order → web/src/addons/shop/views/order/index.vue