rui-docs/superpowers/specs/2026-06-08-api-portal-design.md

API Portal — 睿核科技 API 文档门户 设计文档

日期：2026-06-08 状态：待审核 作者：AI + 张晟

---

一、项目概述

1.1 项目名称

• 前端项目：api-portal（睿核科技 API 文档门户）
• 后端服务：rui-service-apidoc（API 文档管理微服务）

1.2 核心目标

构建一个精美的 API 文档门户系统，具备以下能力：

1. 多源 API 文档聚合 — 自动同步微服务 OpenAPI JSON + 手动导入
2. 自定义多级菜单 — 3 级菜单树，自由组织，不受 Controller 结构限制
3. 文档补全增强 — 管理后台补充中文说明、示例、注意事项
4. 精美文档展示 — VitePress 风格三栏布局，代码高亮
5. AI 结构化接口 — 提供完整 API 信息供 AI 读取、代码生成、变更感知
6. 多项目管理 — 可自由创建项目，每个项目独立菜单和文档

1.3 用户角色

角色	说明
匿名访客	浏览公开项目的 API 文档
开发者	浏览 + 搜索 + 测试 API
管理员	管理项目、菜单、同步 API、补全文档
AI Agent	通过专用接口读取结构化 API 数据

---

二、系统架构

┌──────────────────────────────────────────────────────────────────┐
│                          整体架构                                 │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  微服务集群                                                       │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐       │
│  │ rui-user  │ │rui-system │ │rui-cashier│ │rui-payment│       │
│  │/v3/api-   │ │/v3/api-   │ │/v3/api-   │ │/v3/api-   │       │
│  │ docs      │ │ docs      │ │ docs      │ │ docs      │       │
│  └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘       │
│        │              │              │              │              │
│        ▼              ▼              ▼              ▼              │
│  ┌──────────────────────────────────────────────────────┐        │
│  │           rui-service-apidoc（独立微服务）              │        │
│  │                                                       │        │
│  │  同步引擎          文档管理           AI 接口          │        │
│  │  - 定时拉取        - 菜单 CRUD        - 结构化查询    │        │
│  │  - 手动触发        - 文档补全         - 变更检测      │        │
│  │  - JSON 导入       - 版本管理         - 代码生成数据  │        │
│  └──────────┬───────────────────┬───────────────────────┘        │
│             │                   │                                 │
│    ┌────────▼────────┐  ┌──────▼──────────┐                     │
│    │    admin-ui      │  │   api-portal    │                     │
│    │  (管理后台)       │  │  (文档门户)      │                     │
│    │  补全信息/管理菜单 │  │  精美展示/公开   │                     │
│    └─────────────────┘  └─────────────────┘                     │
│                                                                  │
│    ┌────────────────────────────────────────┐                    │
│    │           AI Agent (Codex 等)           │                    │
│    │  通过 /ai/* 接口读取结构化 API 数据      │                    │
│    └────────────────────────────────────────┘                    │
└──────────────────────────────────────────────────────────────────┘

---

三、后端设计 — rui-apidoc

3.1 技术栈

项目	选型	说明
语言	Java 21	和框架一致
框架	Spring Boot 3 + Spring Cloud	和框架一致
数据库	MySQL 8	和框架一致
ORM	MyBatis-Plus	继承 BaseEntity
API 文档	SpringDoc (OpenAPI 3)	和框架一致
注册中心	Nacos	复用现有
包管理	Maven	parent: rui-parent

3.2 模块结构

遵循 业务应用模块创建规则，作为 app/ 下的独立业务模块：

app/
└── rui-apidoc/
    ├── pom.xml                       # parent: rui-app
    ├── rui-apidoc-api/               # [可部署] REST API + 启动类
    │   └── src/main/java/com/rui/apidoc/api/
    │       ├── ApidocApplication.java
    │       └── controller/
    │           ├── PortalController.java      # 文档门户 API（公开）
    │           ├── ApidocController.java      # 管理后台 API（需认证）
    │           └── AiController.java          # AI 专用 API
    ├── rui-apidoc-common/            # [库] DTO、VO、枚举
    │   └── src/main/java/com/rui/apidoc/
    │       ├── dto/
    │       ├── vo/
    │       └── enums/
    ├── rui-apidoc-core/              # [库] Entity、Mapper、Service
    │   └── src/main/java/com/rui/apidoc/core/
    │       ├── entity/
    │       ├── mapper/
    │       ├── service/
    │       └── config/
    └── rui-apidoc-task/              # [库] 定时同步任务
        └── src/main/java/com/rui/apidoc/task/
            └── SyncTask.java

POM 层级：

app/pom.xml (rui-app)
  └── rui-apidoc/pom.xml (parent: rui-app)
        ├── rui-apidoc-api     → parent: rui-apidoc
        ├── rui-apidoc-common
        ├── rui-apidoc-core
        └── rui-apidoc-task

依赖关系：

common → rui-common-core
core   → rui-common-mybatis, rui-common-security, common
task   → core, common
api    → core, task, rui-common-security, rui-common-web

3.3 核心数据模型

所有实体继承 BaseEntity，自动包含 id, tenant_id, deleted, created_by, created_at, updated_by, updated_at 字段。 建表 SQL 只写业务字段，公共字段由 BaseEntity 规范统一。

3.3.1 项目表 apidoc_project

CREATE TABLE apidoc_project (
    -- 业务字段
    project_key     VARCHAR(64)  NOT NULL COMMENT '项目唯一标识，如 rui-framework',
    name            VARCHAR(128) NOT NULL COMMENT '项目名称',
    description     TEXT         DEFAULT NULL COMMENT '项目描述',
    visibility      TINYINT      NOT NULL DEFAULT 0 COMMENT '可见性 0=公开 1=需登录 2=仅管理员',
    logo_url        VARCHAR(512) DEFAULT NULL COMMENT '项目 Logo',
    sort_order      INT          NOT NULL DEFAULT 0 COMMENT '排序',
    -- BaseEntity 公共字段
    id              BIGINT       NOT NULL COMMENT '主键ID（雪花算法）',
    tenant_id       BIGINT       NOT NULL DEFAULT 0 COMMENT '租户ID',
    deleted         TINYINT      NOT NULL DEFAULT 0 COMMENT '逻辑删除 0=正常 1=已删',
    created_by      BIGINT       DEFAULT NULL COMMENT '创建者ID',
    created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_by      BIGINT       DEFAULT NULL COMMENT '更新者ID',
    updated_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    PRIMARY KEY (id),
    UNIQUE KEY uk_project_key (project_key)
) COMMENT='API文档项目';

3.3.2 微服务注册表 apidoc_service

CREATE TABLE apidoc_service (
    -- 业务字段
    project_id      BIGINT       NOT NULL COMMENT '所属项目ID',
    service_name    VARCHAR(128) NOT NULL COMMENT '服务名，如 rui-service-user',
    service_url     VARCHAR(512) DEFAULT NULL COMMENT '服务地址，如 http://rui-service-user:8080',
    sync_mode       TINYINT      NOT NULL DEFAULT 0 COMMENT '同步模式 0=自动同步(URL) 1=手动导入',
    sync_status     TINYINT      NOT NULL DEFAULT 0 COMMENT '同步状态 0=未同步 1=同步中 2=成功 3=失败',
    last_sync_at    DATETIME     DEFAULT NULL COMMENT '最后同步时间',
    openapi_json    MEDIUMTEXT   DEFAULT NULL COMMENT '缓存的 OpenAPI JSON',
    -- BaseEntity 公共字段
    id              BIGINT       NOT NULL COMMENT '主键ID（雪花算法）',
    tenant_id       BIGINT       NOT NULL DEFAULT 0 COMMENT '租户ID',
    deleted         TINYINT      NOT NULL DEFAULT 0 COMMENT '逻辑删除',
    created_by      BIGINT       DEFAULT NULL,
    created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_by      BIGINT       DEFAULT NULL,
    updated_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    INDEX idx_project (project_id)
) COMMENT='API文档微服务注册';

3.3.3 多级菜单表 apidoc_menu

CREATE TABLE apidoc_menu (
    -- 业务字段
    project_id      BIGINT       NOT NULL COMMENT '所属项目ID',
    parent_id       BIGINT       NOT NULL DEFAULT 0 COMMENT '父级菜单ID，0=顶级',
    name            VARCHAR(128) NOT NULL COMMENT '菜单名称',
    icon            VARCHAR(64)  DEFAULT NULL COMMENT '图标',
    menu_type       TINYINT      NOT NULL DEFAULT 0 COMMENT '类型 0=目录 1=自定义内容页 2=接口组',
    sort_order      INT          NOT NULL DEFAULT 0 COMMENT '同级排序',
    service_id      BIGINT       DEFAULT NULL COMMENT '关联的微服务(menu_type=2时)',
    endpoint_paths  JSON         DEFAULT NULL COMMENT '关联的API路径列表',
    content         MEDIUMTEXT   DEFAULT NULL COMMENT 'Markdown自定义内容(menu_type=1时)',
    -- BaseEntity 公共字段
    id              BIGINT       NOT NULL COMMENT '主键ID（雪花算法）',
    tenant_id       BIGINT       NOT NULL DEFAULT 0 COMMENT '租户ID',
    deleted         TINYINT      NOT NULL DEFAULT 0 COMMENT '逻辑删除',
    created_by      BIGINT       DEFAULT NULL,
    created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_by      BIGINT       DEFAULT NULL,
    updated_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    INDEX idx_project_parent (project_id, parent_id)
) COMMENT='API文档菜单';

3.3.4 API 端点表 apidoc_endpoint

CREATE TABLE apidoc_endpoint (
    -- 业务字段
    service_id      BIGINT       NOT NULL COMMENT '所属微服务ID',
    menu_id         BIGINT       DEFAULT NULL COMMENT '关联菜单ID',
    method          VARCHAR(10)  NOT NULL COMMENT 'HTTP方法 GET/POST/PUT/DELETE/PATCH',
    path            VARCHAR(512) NOT NULL COMMENT '接口路径',
    summary         VARCHAR(256) DEFAULT NULL COMMENT '接口摘要(来自OpenAPI)',
    description     TEXT         DEFAULT NULL COMMENT '接口描述(来自OpenAPI)',
    deprecated      TINYINT      NOT NULL DEFAULT 0 COMMENT '是否废弃',
    tags            JSON         DEFAULT NULL COMMENT 'OpenAPI tags',
    request_params  JSON         DEFAULT NULL COMMENT '查询参数 [{name,type,required,description}]',
    request_body    JSON         DEFAULT NULL COMMENT '请求体 JSON Schema',
    request_headers JSON         DEFAULT NULL COMMENT '请求头',
    path_params     JSON         DEFAULT NULL COMMENT '路径参数',
    response_200    JSON         DEFAULT NULL COMMENT '200 响应 JSON Schema',
    response_error  JSON         DEFAULT NULL COMMENT '错误响应 Schema',
    raw_openapi     JSON         DEFAULT NULL COMMENT '原始 OpenAPI operation 对象',
    content_hash    VARCHAR(64)  DEFAULT NULL COMMENT '内容哈希，用于变更检测',
    -- BaseEntity 公共字段
    id              BIGINT       NOT NULL COMMENT '主键ID（雪花算法）',
    tenant_id       BIGINT       NOT NULL DEFAULT 0 COMMENT '租户ID',
    deleted         TINYINT      NOT NULL DEFAULT 0 COMMENT '逻辑删除',
    created_by      BIGINT       DEFAULT NULL,
    created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_by      BIGINT       DEFAULT NULL,
    updated_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY uk_service_method_path (service_id, method, path),
    INDEX idx_service (service_id),
    INDEX idx_menu (menu_id)
) COMMENT='API端点';

3.3.5 文档补充表 apidoc_extra

CREATE TABLE apidoc_extra (
    -- 业务字段
    endpoint_id     BIGINT       NOT NULL COMMENT '关联端点ID',
    custom_title    VARCHAR(256) DEFAULT NULL COMMENT '自定义标题(覆盖summary)',
    custom_desc     TEXT         DEFAULT NULL COMMENT '自定义说明(中文描述)',
    use_cases       TEXT         DEFAULT NULL COMMENT '使用场景说明',
    notes           TEXT         DEFAULT NULL COMMENT '注意事项',
    request_example JSON         DEFAULT NULL COMMENT '请求示例',
    response_example JSON        DEFAULT NULL COMMENT '响应示例',
    error_example   JSON         DEFAULT NULL COMMENT '错误响应示例',
    test_cases      JSON         DEFAULT NULL COMMENT '测试用例 [{name,params,expected}]',
    -- BaseEntity 公共字段
    id              BIGINT       NOT NULL COMMENT '主键ID（雪花算法）',
    tenant_id       BIGINT       NOT NULL DEFAULT 0 COMMENT '租户ID',
    deleted         TINYINT      NOT NULL DEFAULT 0 COMMENT '逻辑删除',
    created_by      BIGINT       DEFAULT NULL,
    created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_by      BIGINT       DEFAULT NULL,
    updated_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY uk_endpoint (endpoint_id)
) COMMENT='API文档补充信息';

3.3.6 版本快照表 apidoc_version

CREATE TABLE apidoc_version (
    -- 业务字段
    service_id      BIGINT       NOT NULL COMMENT '所属微服务ID',
    version         VARCHAR(32)  NOT NULL COMMENT '版本号，如 v1.2.0',
    openapi_json    MEDIUMTEXT   DEFAULT NULL COMMENT 'OpenAPI JSON 快照',
    change_log      TEXT         DEFAULT NULL COMMENT '变更日志(Markdown)',
    -- BaseEntity 公共字段
    id              BIGINT       NOT NULL COMMENT '主键ID（雪花算法）',
    tenant_id       BIGINT       NOT NULL DEFAULT 0 COMMENT '租户ID',
    deleted         TINYINT      NOT NULL DEFAULT 0 COMMENT '逻辑删除',
    created_by      BIGINT       DEFAULT NULL,
    created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_by      BIGINT       DEFAULT NULL,
    updated_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    INDEX idx_service (service_id)
) COMMENT='API文档版本快照';

3.4 核心 API 设计

所有接口统一使用 Result<T> 返回封装（error=0 成功，code 为业务编码，message 提示，data 业务数据）。 Controller 路径遵循 /{模块}/{功能}/{方法} 规范。

3.4.1 文档门户 API（公开，免认证）

方法	路径	返回类型	说明
GET	/apidoc/portal/project/list	Result<List<ProjectVO>>	公开项目列表
GET	/apidoc/portal/project/{key}	Result<ProjectVO>	项目详情
GET	/apidoc/portal/project/{key}/menu	Result<List<MenuTreeVO>>	项目菜单树
GET	/apidoc/portal/project/{key}/menu/{menuId}	Result<MenuDetailVO>	菜单详情
GET	/apidoc/portal/endpoint/{id}	Result<EndpointDetailVO>	端点详情(含补充信息)
GET	/apidoc/portal/search	Result<List<EndpointVO>>	全文搜索

3.4.2 管理后台 API（需认证 + 管理员权限）

遵循 Controller 分类规范，管理接口使用 ApidocController：

方法	路径	返回类型	说明
POST	/apidoc/admin/project	Result<Long>	创建项目
PUT	/apidoc/admin/project/{id}	Result<Void>	更新项目
DELETE	/apidoc/admin/project/{id}	Result<Void>	删除项目
POST	/apidoc/admin/service	Result<Long>	注册微服务
POST	/apidoc/admin/service/{id}/sync	Result<Void>	手动触发同步
POST	/apidoc/admin/service/{id}/import	Result<Void>	手动导入 OpenAPI JSON
POST	/apidoc/admin/menu	Result<Long>	创建菜单
PUT	/apidoc/admin/menu/{id}	Result<Void>	更新菜单
DELETE	/apidoc/admin/menu/{id}	Result<Void>	删除菜单
PUT	/apidoc/admin/menu/sort	Result<Void>	批量排序
POST	/apidoc/admin/menu/{id}/bind	Result<Void>	菜单绑定 API 端点
PUT	/apidoc/admin/extra/{endpointId}	Result<Void>	更新补充信息
POST	/apidoc/admin/service/{id}/snapshot	Result<Void>	创建版本快照

3.4.3 AI 专用 API

方法	路径	返回类型	说明
GET	/apidoc/ai/projects	Result<List<AiProjectVO>>	所有项目(含服务概况)
GET	/apidoc/ai/project/{key}/endpoints	Result<List<AiEndpointVO>>	项目全部端点(完整结构化)
GET	/apidoc/ai/endpoint/{id}	Result<AiEndpointDetailVO>	单个端点完整信息
GET	/apidoc/ai/endpoint/search	Result<List<AiEndpointVO>>	搜索端点(keyword/method/path)
GET	/apidoc/ai/project/{key}/changes	Result<List<ApiChangeVO>>	API 变更(增量,since参数)
POST	/apidoc/ai/query	Result<List<AiEndpointVO>>	AI 自然语言查询

AI 接口返回示例（GET /apidoc/ai/endpoint/{id}）：

{
  "error": 0,
  "code": null,
  "message": "操作成功",
  "data": {
    "id": 1001,
    "method": "POST",
    "path": "/v1/user/users",
    "summary": "创建用户",
    "description": "管理员创建新用户，需要管理员权限",
    "deprecated": false,
    "tags": ["用户管理"],
    "auth": "需要 Bearer Token，角色：ADMIN",
    "requestParams": [],
    "pathParams": [],
    "requestHeaders": [
      { "name": "Authorization", "required": true, "description": "Bearer Token" },
      { "name": "Content-Type", "required": true, "value": "application/json" }
    ],
    "requestBody": {
      "type": "object",
      "required": ["username", "password", "phone"],
      "properties": {
        "username": { "type": "string", "description": "用户名，4-20位字母数字", "example": "zhangsan" },
        "password": { "type": "string", "description": "密码，8-32位", "example": "Pass@123" },
        "phone": { "type": "string", "description": "手机号", "example": "13800138000" },
        "email": { "type": "string", "description": "邮箱(可选)", "example": "zhangsan@example.com" }
      }
    },
    "response200": {
      "type": "object",
      "properties": {
        "error": { "type": "integer", "description": "0=成功", "example": 0 },
        "code": { "type": "string", "example": "SUCCESS" },
        "message": { "type": "string", "example": "操作成功" },
        "data": {
          "type": "object",
          "properties": {
            "id": { "type": "integer", "description": "用户ID", "example": 1001 },
            "username": { "type": "string", "example": "zhangsan" },
            "created_at": { "type": "string", "format": "date-time" }
          }
        }
      }
    },
    "responseError": {
      "400": { "error": 400, "code": "PARAM_INVALID", "message": "参数校验失败" },
      "401": { "error": 401, "code": "UNAUTHORIZED", "message": "未登录" },
      "403": { "error": 403, "code": "FORBIDDEN", "message": "无权限" }
    },
    "extra": {
      "customTitle": "创建新用户",
      "customDesc": "管理员通过此接口创建新用户，创建后用户处于启用状态",
      "useCases": "后台管理 > 用户管理 > 新增用户",
      "notes": "用户名唯一，不可重复。密码需满足复杂度要求。",
      "requestExample": { "username": "zhangsan", "password": "Pass@123", "phone": "13800138000" },
      "responseExample": { "error": 0, "code": null, "message": "操作成功", "data": { "id": 1001, "username": "zhangsan" } },
      "testCases": [
        {
          "name": "正常创建",
          "params": { "username": "testuser01", "password": "Pass@123", "phone": "13900139001" },
          "expected": { "error": 0 }
        },
        {
          "name": "用户名重复",
          "params": { "username": "admin", "password": "Pass@123", "phone": "13900139002" },
          "expected": { "error": 400, "code": "USER_EXISTS" }
        }
      ]
    },
    "service": { "name": "rui-service-user", "project": "rui-framework" },
    "updatedAt": "2026-06-08T10:00:00"
  }
}

3.5 同步引擎设计

自动同步流程：
1. rui-apidoc-task 中的定时任务(可配置周期) 或 手动触发
2. 遍历 apidoc_service 中 sync_mode=0 且 sync_status!=1 的服务
3. HTTP 请求 {service_url}/v3/api-docs 获取 OpenAPI JSON
4. 使用 JsonUtil 解析 JSON，提取所有 Path + Operation
5. 计算每个 Operation 的 content_hash，与 apidoc_endpoint 现有数据对比
6. 新增/更新/标记废弃 端点，记录变更
7. 更新 sync_status=2, last_sync_at, openapi_json

手动导入流程：
1. 管理员在管理后台粘贴 OpenAPI JSON 或上传文件
2. 同上解析入库逻辑，sync_mode=1

3.6 启动类

package com.rui.apidoc.api;

import com.rui.common.security.annotation.EnableResourceServer;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableResourceServer
public class ApidocApplication {
    public static void main(String[] args) {
        SpringApplication.run(ApidocApplication.class, args);
    }
}

3.7 Nacos 白名单配置

security:
  oauth2:
    ignore-urls:
      - /apidoc/portal/**
      - /apidoc/ai/**

/apidoc/portal/** 和 /apidoc/ai/** 免认证公开访问。 /apidoc/admin/** 需管理员权限。

四、前端设计 — api-portal

4.1 技术栈

项目	选型	说明
框架	Vue 3 + TypeScript	组合式 API (setup)，和 admin-ui 一致
构建	Vite 6	和 admin-ui 一致
样式	UnoCSS	原子化 CSS，和 admin-ui 一致
路由	Vue Router 4	侧边栏联动
HTTP	Axios	统一封装 request，复用 admin-ui 模式
代码高亮	Shiki	和 VitePress 同款高亮引擎
Markdown 渲染	markdown-it + 自定义插件	自定义内容页
图标	@iconify-json/carbon	专业文档风格

api-portal 是独立项目（不依赖 Element Plus），UI 全部基于 UnoCSS 原子化样式构建。

4.2 页面结构

三栏布局（接口文档页）

┌─────────────────────────────────────────────────────────────────┐
│  🏠 Rui API Portal     🔍 搜索接口...          🌙 主题  🌐 中文 │
├────────────┬──────────────────────────────────┬─────────────────┤
│            │                                  │                 │
│ 📖 快速开始 │  POST /v1/user/users             │  请求示例       │
│            │  ━━━━━━━━━━━━━━━━━━━━            │                 │
│ ▸ 用户管理  │  创建新用户                       │  curl -X POST \ │
│   登录     │                                  │  /v1/user/users \│
│   注册     │  管理员通过此接口创建新用户，创建     │  -H 'Auth...' \ │
│   用户列表  │  后用户处于启用状态。               │  -d '{...}'    │
│   用户详情  │                                  │                 │
│   创建用户  │  ⚡ 需要管理员权限                  │─────────────────│
│   更新用户  │  🔒 Bearer Token                  │  响应示例       │
│ ▸ 订单管理  │                                  │                 │
│   创建订单  │  请求参数                         │  200 OK         │
│   查询订单  │  ┌──────┬──────┬────┬────┐       │  {              │
│   取消订单  │  │ 参数  │ 类型  │必填│说明 │       │    "error":0,  │
│ ▸ 支付     │  ├──────┼──────┼────┼────┤       │    "data":{...}│
│   发起支付  │  │username│string│ ✓ │用户名│      │  }             │
│   支付回调  │  │password│string│ ✓ │密码 │      │                 │
│   退款     │  └──────┴──────┴────┴────┘       │─────────────────│
│            │                                  │  测试用例       │
│            │  响应参数                         │  ✅ 正常创建    │
│            │  ┌──────┬──────┬────┐            │  ❌ 用户名重复  │
│            │  │ 字段  │ 类型  │说明 │            │                 │
│            │  ├──────┼──────┼────┤            │                 │
│            │  │  id   │ long │用户ID│           │                 │
│            │  └──────┴──────┴────┘            │                 │
│            │                                  │                 │
└────────────┴──────────────────────────────────┴─────────────────┘

项目首页

┌─────────────────────────────────────────────────────────────────┐
│  🏠 Rui API Portal     🔍 搜索接口...          🌙 主题  🌐 中文 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│                     睿核科技 API 文档中心                         │
│              探索、测试、集成我们的 API 服务                       │
│                                                                 │
│         ┌──────────────────────────────────┐                    │
│         │     🔍 搜索所有 API 接口...       │                    │
│         └──────────────────────────────────┘                    │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ 📦 rui-frame │  │ 📦 rui-cashier│  │ 📦 rui-payment│          │
│  │   work       │  │              │  │              │            │
│  │  基础平台框架  │  │   收银系统    │  │   支付系统    │            │
│  │  128 接口    │  │   56 接口    │  │   32 接口    │            │
│  │  5 模块      │  │   3 模块    │  │   2 模块    │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

4.3 路由设计

/                           → 项目首页（项目卡片列表）
/:projectKey                → 项目页（菜单 + 欢迎页）
/:projectKey/menu/:menuId   → 菜单页（自定义内容 / 接口组）
/:projectKey/endpoint/:id   → 单个接口详情页
/search?keyword=&projectId= → 搜索结果页

4.4 核心功能

功能	说明
多级菜单导航	3 级可折叠侧边栏，图标 + 名称
接口文档渲染	方法/路径/参数/响应/示例，结构化表格展示
代码高亮	请求示例(curl/JS/Java)、响应示例 JSON
Markdown 自定义页	菜单项关联自定义 Markdown 内容（快速开始、认证说明等）
全文搜索	搜索接口名、路径、描述、参数名
深色模式	主题切换
响应式	移动端适配（侧边栏折叠）
"试一试"	简易 API 测试面板（填参数发请求）

4.5 项目结构

遵循 admin-ui 的目录约定：service 层使用 BaseService 模式，composables 存放组合式函数，views 存放页面。

api-portal/
├── package.json
├── vite.config.ts
├── uno.config.ts
├── tsconfig.json
├── index.html
├── public/
│   └── favicon.svg
├── src/
│   ├── main.ts
│   ├── App.vue
│   ├── service/                      # API 请求封装（和 admin-ui 一致）
│   │   ├── BaseService.ts            # 通用 CRUD 基类（复用 admin-ui 模式）
│   │   ├── portalService.ts          # 文档门户接口
│   │   └── types.ts                  # TypeScript 类型定义
│   ├── composables/                   # 组合式函数
│   │   ├── useTheme.ts               # 主题切换
│   │   ├── useMenu.ts                # 菜单状态
│   │   └── useSearch.ts              # 搜索
│   ├── components/
│   │   ├── layout/
│   │   │   ├── AppHeader.vue         # 顶部导航
│   │   │   ├── AppSidebar.vue        # 侧边栏
│   │   │   ├── AppFooter.vue         # 底部
│   │   │   └── ThreeColumn.vue       # 三栏布局容器
│   │   ├── endpoint/
│   │   │   ├── EndpointHeader.vue    # 方法 + 路径 + 标签
│   │   │   ├── ParamsTable.vue       # 参数表格
│   │   │   ├── ResponseSchema.vue    # 响应结构
│   │   │   ├── CodeBlock.vue         # 代码块(Shiki 高亮)
│   │   │   └── TryIt.vue             # "试一试"面板
│   │   ├── markdown/
│   │   │   └── MarkdownRenderer.vue  # Markdown 渲染
│   │   └── search/
│   │       └── SearchDialog.vue      # 搜索弹窗
│   ├── views/                        # 页面（和 admin-ui 命名一致）
│   │   ├── HomePage.vue              # 首页
│   │   ├── ProjectPage.vue           # 项目页
│   │   ├── MenuPage.vue              # 菜单内容页
│   │   ├── EndpointPage.vue          # 接口详情页
│   │   └── SearchPage.vue            # 搜索结果页
│   ├── router/
│   │   └── index.ts
│   ├── stores/                       # Pinia 状态管理
│   │   └── project.ts               # 项目状态
│   ├── styles/
│   │   ├── variables.css             # CSS 变量(主题色)
│   │   └── prose.css                 # 文档内容样式
│   └── utils/
│       ├── request.ts                # Axios 封装（复用 admin-ui 模式，baseURL 指向 apidoc 服务）
│       └── format.ts                 # 格式化工具
└── env.d.ts

4.6 request.ts 设计

复用 admin-ui 的 request 封装模式，但 api-portal 是公开文档站，不需要 Token/租户拦截。

// src/utils/request.ts
import axios from 'axios'

const request = axios.create({
  baseURL: '/api',     // 通过网关转发到 rui-apidoc
  timeout: 10000,
})

// 响应拦截 — 复用 Result<T> 的 error 判断逻辑
request.interceptors.response.use(
  (response) => {
    const { data } = response
    if (data.error !== 0) {
      console.error(data.message || '请求失败')
      return Promise.reject(data)
    }
    return data
  },
  (error) => {
    console.error('网络错误', error.message)
    return Promise.reject(error)
  },
)

export { request }

4.7 service 层设计

遵循 admin-ui 的 BaseService 模式，但 api-portal 以只读查询为主。

// src/service/portalService.ts
import { request } from '@/utils/request'

/** 获取公开项目列表 */
export function getProjectList() {
  return request({ url: '/apidoc/portal/project/list', method: 'get' })
}

/** 获取项目详情 */
export function getProject(key: string) {
  return request({ url: `/apidoc/portal/project/${key}`, method: 'get' })
}

/** 获取项目菜单树 */
export function getMenuTree(key: string) {
  return request({ url: `/apidoc/portal/project/${key}/menu`, method: 'get' })
}

/** 获取菜单详情 */
export function getMenuDetail(key: string, menuId: string) {
  return request({ url: `/apidoc/portal/project/${key}/menu/${menuId}`, method: 'get' })
}

/** 获取端点详情 */
export function getEndpoint(id: string) {
  return request({ url: `/apidoc/portal/endpoint/${id}`, method: 'get' })
}

/** 搜索 */
export function searchEndpoints(keyword: string, projectId?: string) {
  return request({ url: '/apidoc/portal/search', method: 'get', params: { keyword, projectId } })
}

五、部署架构

┌──────────────────────────────────────────────────┐
│  Nginx / Gateway                                  │
│  ├─ / → api-portal 静态资源                        │
│  ├─ /admin → admin-ui 静态资源                     │
│  └─ /api/apidoc/* → rui-service-apidoc            │
└──────────────────────────────────────────────────┘

api-portal 构建产物部署为静态资源，通过 Nginx 或 CDN 分发。
rui-service-apidoc 注册到 Nacos，通过 Gateway 路由。

---

六、开发优先级

Phase 1：MVP（最小可用）

1. 后端：项目/菜单/端点 CRUD + OpenAPI JSON 手动导入
2. 前端：三栏布局 + 菜单导航 + 接口文档渲染

Phase 2：增强

3. 后端：自动同步引擎（定时拉取 /v3/api-docs）
4. 后端：文档补全管理
5. 前端：搜索 + 深色模式

Phase 3：AI + 高级功能

6. 后端：AI 专用结构化接口
7. 后端：API 变更检测 + 版本管理
8. 前端："试一试" API 测试面板

---

七、参考风格

参考站点	地址	借鉴点
VitePress	https://vitepress.dev	整体风格、三栏布局、深色模式
Nuxt UI Pro	https://ui.nuxt.com/pro	文档模板、导航设计
Stripe API	https://stripe.com/docs/api	代码示例、交互体验
Scalar	https://scalar.com	现代 API 文档 UI

---

本文档仅涵盖设计，不涉及具体实现代码。实施前需团队审核确认。