# 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`

```sql
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`

```sql
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`

```sql
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`

```sql
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`

```sql
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`

```sql
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}`）**：

```json
{
  "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 启动类

```java
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 白名单配置

```yaml
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/租户拦截。

```typescript
// 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 以只读查询为主。

```typescript
// 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 |

---

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