Home

StackPanel 开发者指南

StackPanel 是 API-first、微内核插件化的数字商品与主机业务管理系统。下面的目录按内核开发、插件开发、主题开发、前端包开发与 REST API 对接分组。

技术栈

层	选型
运行时	Node.js 22+（engines 要求 >=22，CI 使用 Node 24）
前端	React 19 / Next.js 16（App Router、Turbopack）/ Tailwind CSS 4 / Base UI
后端	Fastify 5 / Prisma 7 / PostgreSQL（唯一存储引擎）/ TypeScript 6 strict
包管理	pnpm 11.5.1 monorepo（无 Turborepo）
进程管理	PM2 7

文档导航

核心开发

内核的环境准备、运行、构建、架构与项目结构。

文档	说明
准备工作	环境要求、依赖安装、数据库初始化
运行项目	PM2 部署、开发模式热重载
构建项目	构建命令、产物说明
架构概览	微内核架构、六大职责、请求流转
项目结构	monorepo 目录结构与模块划分
站内通知	平台通知能力、API、插件写入与收件箱

插件开发

插件的清单、生命周期、路由、扩展点、事件、权限与打包。

文档	说明
介绍	插件系统概念与能力总览
准备工作	开发环境与脚手架
插件项目结构	目录布局说明
插件清单	manifest.json 字段详解
生命周期	register → activate → deactivate → unregister
路由定义	声明 HTTP 路由、请求/响应类型
扩展点	内核扩展点与注册机制
事件总线	发布/订阅事件
密钥存储	插件命名空间加密密钥
插件依赖	requires/provides/consumes
权限与 RBAC	权限声明与角色模板
履约/交付物	付款后把商品变成交付物：SPI、异步队列、服务详情
商品类型与上游	store 纯底层：类型插件 + 上游商品关联
打包与签名	ZIP 打包、Ed25519 签名、上传安装

主题开发

主题清单、CSS Token、设置与打包。

文档	说明
介绍	主题系统概念
主题结构	目录布局
主题清单	theme.json 字段详解
CSS Token 规范	theme.css 约束与可用变量
主题设置	设置表单与设置存储
主题前端包	主题携带前端模板
打包与上传	ZIP 打包、签名、安装

前端包开发

主题与插件共用的前端包系统：清单、页面、Layout、Finder、后台扩展。

文档	说明
快速上手	从零做一个最小插件前端
前端包介绍	前端包概念、两个入口与三条硬约束
前端清单	frontend/manifest.json 字段详解
页面路由	pages 声明、动态参数、通配
命名 Layout	layout 声明与包装
Finder 数据源	Finder 声明、输入解析与数据调用
管理后台扩展	adminRoutes / adminPages / actions
设置 Schema	settingsSchema 表单生成
UI 与样式约定	可用组件、Tailwind 与样式规则
常见问题与排查	症状 → 原因 → 修法

RESTful API

REST API 的认证、端点参考、SDK 客户端与错误模型。

文档	说明
介绍	API 概览与在线文档
认证方式	会话、API Token、OAuth
API 路由参考	全部端点的分类列表
SDK 客户端	@stackpanel/sdk 类型安全客户端
错误处理	错误响应格式与状态码