开发文档与接口查询

快速开始

git clone <仓库地址> && cd www.hejun1.com
npm ci
cp .env.example .env        # 按注释填 DATABASE_URL / REDIS_URL / NUXT_PUBLIC_SITE_URL
npx prisma db push          # 建表
npm run db:seed             # 写入管理员、四套系统、FAQ 等初始数据
npm run dev                 # http://localhost:3000

技术栈

选型原则是「一个人也能长期维护」：不要微服务、不要自建 SSR 框架、不引入需要专职运维的中间件。

目录结构

数据模型

来自 prisma/schema.prisma。 改结构后执行 npx prisma db push 同步到数据库。

API 接口

共 128 个，其中 95 个需要登录。 公开 接口前台可直接调用；JWT 需要登录态；RBAC 还要求角色具备对应权限点 （权限在后台「角色权限」里分配）。 说明取自源码注释：没写注释的接口不显示说明，只列出路径、鉴权与所在文件。

接口变更记录

接口是二次开发的合同，而合同会改。这里记录每次**接口 / 数据模型 / 页面 / 扩展规范**的变化 —— 它由 npm run api:changelog 从代码差异**生成**（不是手写的，所以不会过期）。 破坏性指老调用方或老扩展会坏：删接口、删字段、可选字段变必填、字段类型变化、 权限点变化、访问要求变严、删页面、扩展点或清单字段被移除；其余为兼容变更。 扩展作者可以用 GET /api/dev-docs?since=<引擎版本> 只取那之后的变化（返回里带 changelogSince）。

内容契约（主题/模块可依赖的数据）

二次开发与主题制作时，以下数据源是稳定承诺：字段只增不改名；弃用会先在「接口变更记录」公告。 主题侧统一经 useSiteContent(type) 读取（已做归一化与空值兜底），也可直接调用对应 API。

错误与状态码契约

所有接口的错误响应都是同一个形状，前端按 data.code 分支、 按 data.message 显示文案：

HTTP 409
{
  "statusCode": 409,
  "message": "表单 key 已存在",
  "data": { "code": "duplicate" }
}

状态码语义（选码时按这张表）

最常被搞错的两条：重名 / 受保护不能删是 409（不是 400）；邮箱格式、枚举越界、父级不存在是 422（不是 400）。 「请求不成形」才用 400。

服务端怎么写

用 server/utils/api-error.ts 的构造器 （Nitro 自动导入，不必写 import）。业务代码里不要手写createError({ statusCode: 400 }) —— 巡检会拦下来，而且那样带不上机器可读的 code。

const parsed = schema.safeParse(await readBody(event))
if (!parsed.success) throwZodError(parsed.error)      // 422 + validation_failed + 字段明细
if (!parent) throw validationError('父级菜单不存在或不合法')
if (exists) throw duplicate('表单 key 已存在')          // 409
throw protectedResource(`${key} 的内容由固定页面消费，不能删除`)   // 409
throw readOnlyTarget(`${key} 由系统写入，不能手工修改`)          // 403

前端与扩展怎么读

try {
  await $fetch('/api/admin/forms', { method: 'POST', body })
}
catch (e) {
  const msg = e?.data?.message || '操作失败'        // 文案：读 message
  if (e?.data?.code === 'duplicate') { /* 机器分支：提示改名 */ }
  for (const issue of e?.data?.issues ?? []) markField(issue.path, issue.message)
}

页面路由

新增页面时记得调用 useSeo()： 它会一次性输出 title / description / canonical / og / twitter / JSON-LD， 否则这一页在搜索结果里是裸链接。

组件与组合式函数

服务端构成

环境变量

完整清单见仓库根目录 .env.example。

引擎与扩展

本站的三套扩展机制。三者的边界是刻意划清的 —— 如果它们都能做同样的事， 社区贡献的扩展最后一定会互相打架。引擎版本 1.0.0， 当前已装 9 个扩展包，可声明的扩展点 4 个。 这一节的字段表、扩展点、示例清单全部由源码生成，不存在「文档写得过时」—— 另有同一份内容的离线版 docs/engine-spec.md 可直接交付给开发者。

从零做一个插件（五分钟）

插件是最容易上手的类型：一个目录、一个清单、一个 TS 文件。下面五步能把全流程走通， 不需要读内核代码，也不需要改任何核心文件。

1. ① 生成骨架npm run engine:new -- --type plugin --id my-plugin --name "我的插件"

   生成 engines/plugins/my-plugin/，包含 manifest.json、hooks.ts、README.md。骨架本身是干净的（零错误零告警）。

   已生成 engines\plugins\my-plugin

2. ② 自检npm run engine:validate

   必须「零错误零告警」再往下走。这一步同时会校验规范快照与源码是否一致，所以它也能挡住「文档过期」。

   插件（2）
     ✓ lead-dup-guard   1.0.0  线索重复提示
     ✓ my-plugin        1.0.0  我的插件
   共 2 个包，其中 0 个清单有问题

3. ③ 写实现编辑 hooks.ts 与 manifest.json

   在 hooks.ts 里 on('lead:created', …)；同时把 lead:created 写进 manifest.json 的 hooks。两边必须一致：声明了没实现会被拒绝，实现了没声明则不会被注册。

4. ④ 启用npm run dev → 后台「引擎与扩展」→ 重新扫描 → 启用

   插件与钩子是运行时加载的：改完源码只需要再点一次「重新扫描」，不用重新构建、也不用重启。新装的包默认是停用的。

5. ⑤ 验证前台 /contact 提交一条需求

   扩展点被触发。控制台里能看到带扩展名前缀的日志，可据此确认自己写的逻辑真的跑到了。

   [engine:my-plugin] 收到新线索 …

包内部布局（名字是硬约束）

目录名必须等于清单里的 id； 下面这些位置是引擎识别能力的唯一依据 —— 放到别处不会生效，而且不会报错，所以照着放最省事。

manifest.json 全部字段

共 20 个字段。这张表由 server/utils/engine/manifest.ts 直接生成 —— 它永远等于引擎真正执行的那套规则，不存在「文档落后于代码」。 未知字段会直接报错，不会被静默忽略。

settings 数组里每一项的子字段

设置项会在后台「引擎与扩展」里按 type 渲染成表单。 组件里靠键名与 props 同名自动接收：清单里声明 key: "title"， 组件里写 defineProps<{ title?: string }>() 即可，不用自己取数据。 只有 public: true 的项才会下发给前台接口。

扩展点清单

当前可声明 4 个扩展点。 标记「未实现」的不要声明 —— 它们还在设计里，声明会被校验直接拒绝： 宁可报错，也不让你写出一个「装上了但什么都不发生」的扩展。 扩展点里的异常会被引擎吞掉并记日志：「顺带做的事」不该让主流程（提交需求、保存产品）失败。

hooks.ts 的接口

导出默认函数，参数是引擎注入的能力；用不到的可以不接（解构里不写就行）。

export default function setup({
  on,            // (hook, handler, priority?) => void   注册扩展点；hook 必须在 manifest.hooks 里声明过
  settings,      // Record<string, string>                后台里填的设置（已合并清单默认值）
  log,           // (message, detail?) => void            带 [engine:<id>] 前缀的日志
  prisma,        // Prisma Client                         可用已有表；模块自建表需先跑 engine:schema
  version,       // string                                本扩展的版本号
  engineVersion, // string                                引擎版本，用于兼容判断
}) {
  // priority 越小越先执行，不传默认 100
  on('lead:created', async ({ lead, source }) => {
    log('收到新线索 ' + lead.id, { source })
  }, 100)
}

生命周期回调（可选）

setup() 的返回值可以是生命周期回调。 只在状态切换时触发：第一次装载只建立基线 —— 否则每次重启都会重跑一遍初始化副作用 （重复发通知、重复写 seed 数据），这类问题最难查。

export default function setup(ctx) {
  ctx.on('content:changed', async ({ kind, paths }) => { /* … */ })

  return {
    onEnable(ctx)    { /* 启用时触发（首次启用也走这里，可当安装初始化） */ },
    onDisable(ctx)   { /* 停用时触发；此时它的扩展点已全部撤销 */ },
    onUninstall(ctx) { /* 由 npm run engine:remove 调用，清理自己写入的数据 */ },
  }
}

只做生命周期、不注册任何扩展点是合法的（此时 hooks 留空即可）。 依赖别的扩展用清单里的 requires 声明（写「类型/id」）： 依赖没满足时本扩展会被判为不可用，而不是半启动；循环依赖会让环上全部失效。

模块自带后台接口与权限点

这是模块化的关键：不必改核心的 route-perms.ts。在清单里声明权限点， 接口放进包内 server/api/admin/， 核心的鉴权中间件就会按 routes 匹配；声明过的权限点会自动出现在后台「角色权限」里等待分配。

// manifest.json
"permissions": [
  {
    "key": "order:manage",
    "name": "订单管理",
    "routes": ["GET /api/admin/orders", "POST /api/admin/orders", "DELETE /api/admin/orders"]
  }
]

// 包内 server/api/admin/orders/index.get.ts —— 不需要 import，prisma 等由 Nitro 自动导入
export default defineEventHandler(async () => {
  return prisma.order.findMany({ orderBy: { createdAt: 'desc' } })
})

注意：不要写 '../../server/utils/xx' 这类回到项目的相对路径 —— 包的位置一变层级数就错，写错一个会让整站 500。

接口里可以直接用的名字（不用 import）

引擎编译扩展接口时会注入下面这些名字，取的是运行中进程的同一批对象（同一份 Prisma 客户端）。 其它依赖请显式 import（例如 import { z } from 'zod'）。

两条硬约束：接口必须放在包内 server/api/ 下； 不能占用核心已有的接口（核心优先，冲突时扩展接口会被跳过并告警）。 两者的检查结果都会出现在「重新扫描」的返回里。

组件与页面（运行时编译）

引擎在服务端把包里的 .vue 就地编译成 ESM： 改完点一次「重新扫描」即生效，不用重新构建。支持的写法： <script setup> + 模板、 <style scoped>、 Vue API（ref / computed / onMounted…）、 上面清单里的 Nuxt 组合式函数、包内 composables/*.ts 的导出、 组件之间互相 import（import Foo from './Foo.vue'）、 其它 npm 依赖（会被打进产物）。

两条边界要知道：① 页面 运行时只保证「能跑」—— 落在默认布局、不认 definePageMeta（layout 与 route middleware 不生效）， 要这些能力就重新构建一次（构建期注册那条路是完整语义）； ② 组件 同名时会覆盖构建期注册的那份（所以改模板立刻生效），编译失败则不会被覆盖，自动退回构建期兜底。 不支持 SCSS 等预处理器、<style module>， 也不能与项目自带页面撞路径（核心页面优先）。

模块要建表怎么办

1. 1. 在包目录下建 schema.prisma，只写自己的 model（不要写 datasource / generator）。
2. 2. 执行 npm run engine:schema：片段会以标记块形式合并进 prisma/schema.prisma，审查 diff 时一眼可见。
3. 3. 执行 npx prisma db push 建表，然后 停掉 dev server 跑 npx prisma generate（Windows 上 dev server 占用着查询引擎 dll，不停服会报 EPERM）。
4. 4. 重启服务。数据表是唯一绕不开重启的部分 —— Prisma Client 由构建期生成，运行时加不了 model。

随源码交付的示例扩展

这三张是「照着改就能变成你自己的扩展」的模板，分别覆盖三类扩展的完整写法。

在页面里使用扩展区块

<!-- 主题自带的区块：直接当组件用（主题激活时它的组件就已注册） -->
<FeatureSteps :title="'交付流程'" />
<CaseStudies />
<PricingPlans />

<!-- 点名某个扩展包的区块（按包 id；块随包走时才这么写） -->
<TemplateSection id="扩展包 id" :props="{ title: '…' }" />

<!-- 页面只留位置，让声明了该区域的扩展自己注入（没有扩展时什么都不渲染） -->
<TemplateSlots region="home.after-systems" />

区域清单以站点源码为准：完整可用区域在 npm run engine:validate 输出的末尾（当前 9 个）；清单里声明了站点不存在的区域，校验会直接失败。

命令行

打包、分发与安装

npm run engine:pack -- --type module --id <id> 产出两个文件：包本体 .tar.gz（包内路径是 <id>/…）与同名描述文件 .json（含 sha256、作者、引擎兼容范围与签名）。

签名与「信任白名单」

npm run engine:keygen 生成一对 ed25519 密钥： 私钥 ENGINE_PRIVATE_KEY 只留在你自己机器上， 公钥交给站主。打包时加 --sign 即签名 （描述文件里会带上 keyId，站主据此知道是谁签的）。

站主在后台 →「引擎与扩展 → 信任密钥」里把公钥加进白名单（可以有多把，一个合作者一把）。 白名单里只要有一把未吊销的密钥，安装就强制验签：没有签名、签名对不上、或签名者不在名单里的包 一律拒绝。白名单为空时只靠「仅超级管理员可安装」把关，后台会明确显示「未启用签名校验」。

吊销一把密钥会连带停用由它签名的扩展（可逆：不删文件、不删数据），它的接口也会一起下线； 重新信任不会自动启用它们。装进来的包都会记下签名者，出事时查得出「这个包是谁给的」。 注意：签名保证的是「装进来的东西 == 被签名的那个东西」与「谁给的」， 保证不了「签的人是好人」—— 只把公钥加给你真正信任的人。

要收费？用离线授权码

清单里声明 activation.required 之后， 站主必须贴进一张由你签发的授权码才能启用它：装得上、看得见，但没授权就不跑 （钩子、接口、组件一起下线）。授权码用签包那把私钥签发，离线可验 —— 你的服务器宕机也不影响客户站点。

# 签发一张授权码（买断 2.x、一年有效、绑客户域名、带 15 天宽限）
npm run engine:license -- issue --type module --id order-board \
  --to "某某科技" --per-major --days 365 --grace 15 --domain client-a.com

# 自查（发出去之前先确认它是对的）与台账（卖出记录）
npm run engine:license -- verify --file dist/licenses/module-order-board-xxxx.license.txt
npm run engine:license -- list

三个收费选择都是签发参数，不需要改代码：--domain 决定绑不绑域名、 --per-major 决定买断某个大版本还是永久、 --days / --expires 决定有效期。 贴进后台时会先校验再保存：读不出来、不是给这个包的、签名对不上、签发者不在信任列表、 域名或大版本不匹配 —— 都会当场说明原因；已过期的照收，但显示「已过期，请续期」。

它不是 DRM：校验跑在站主自己的服务器上，他拥有代码与数据库，有能力改掉。 它给的是「明确的契约状态 + 防误用」—— 真正的约束力来自合同与交付关系。

自建扩展源（索引）

把描述文件汇总成一份索引放到任何静态托管（字段与描述文件一致），再在服务器 .env 里配置 ENGINE_INDEX_URL 指向它： 「扩展市场」就会列出这些包，并标注本机已装版本、是否可更新、是否与引擎版本兼容。

{
  "format": "hejun-engine-index/1",
  "updatedAt": "2026-09-23T00:00:00.000Z",
  "packages": [
    {
      "type": "module",
      "id": "announcement-bar",
      "name": "顶部公告条",
      "version": "1.0.0",
      "description": "页面顶部展示一条可关闭的公告",
      "author": "禾君科技",
      "license": "MIT",
      "engine": ">=1.0.0",
      "sha256": "…",
      "signature": "…",
      "tarball": "module-announcement-bar-1.0.0.tar.gz"
    }
  ]
}

三种安装方式

• ① 后台上传（推荐）：扩展市场 → 上传安装，选 .tar.gz；服务器配了公钥还要贴签名。
• ② 后台从索引安装：配置了索引后，在扩展市场里点「安装 / 更新」。
• ③ 手工放目录：解压到 engines/<类型>/ 下，点一次「重新扫描」。

三者效果一样：接口、扩展点、组件与页面都立即生效，不需要重新构建； 只有带 schema.prisma（数据表片段）的模块需要额外走 engine:schema → db push → 停服 prisma generate → 重启。 第三方扩展装上默认停用，要在「引擎与扩展」里显式启用。

安装侧的安全：先校验 sha256 与签名，再解包——只接受普通文件与目录（符号链接一律拒绝）、拒绝绝对路径与 ..、包内只允许一个顶层目录且必须等于清单 id、体积有上限； 校验不过不会在磁盘上留下半个包。完整规则见仓库 docs/engine-spec.md §11。

改了什么之后要做什么

这一节是最容易踩坑的地方：扩展的加载方式分两类，做错了会以为「改了没反应」。

常见报错对照

扩展能做到什么深度

「我想做的事，扩展能不能做、做到什么程度、代价是什么」—— 按场景对着找即可。 字段级规范见 docs/engine-spec.md， 完整版（含每条天花板的成因）见 docs/engine-capabilities.md。

做不到的六件事（有意如此）

• 不能改核心 —— 与核心接口冲突的扩展接口会被跳过并告警；扩展页面撞上核心页面路径会永远命中不到。 对策：换路径（公开接口建议放 /api/engine/ 下）或把改动提给核心。
• 带表的模块安装必须停服重建 —— Prisma 客户端是构建期生成的，运行时无法凭空多出一个 model。 对策：按安装结果的提示跑一遍 engine:schema → db push → 停服 generate → 重启。
• 运行时装上的页面不认 definePageMeta —— 它是 Nuxt 的编译期宏，运行时编译拿不到。 对策：需要完整后台语义（admin 布局 + 鉴权中间件）就随源码构建一次。
• 接口只能写在包内 server/api/ 下 —— 包内 server/ 路径原样映射到站点根，工具链与文档都以 server/api/** 为准。 对策：放对位置即可，路径就是 /api/**。
• 组合式函数只在自己包内可用 —— 引擎按包注入替身，避免全局命名空间互相覆盖。 对策：跨包复用做成插件 + 扩展点，或直接调对方接口。
• 没有沙箱 —— 运行时加载 = 执行装进来的代码，Node 里做不出可靠沙箱。 对策：用信任白名单 + 签名控制来源，只把你信任的人加进白名单。

改了什么时候生效

最快的判断方式：除了「带数据表的模块」与「彻底回收旧版本内存」，其余一切都只要一次「重新扫描」。

门禁与巡检

这套系统把踩过的坑都写成了可复跑的检查，一条命令跑完 15 个域： npm run audit（动态，打运行中的站点）与 npm run audit:full（再加静态闸门）。 退出码非 0 即失败，可直接进 CI。

它挡住的都是真实出过的问题

判定约定（读报告时按这个看）

• 失败：必须修。它代表某条不变量被破坏（产物漏出、契约漂移、类型回归…）。
• 存疑：需要人来判断，不是自动结论。例如安全头的取舍、依赖内部的类型缺陷。
• 信息 / 跳过：只做记录；跳过会写明原因（例如生产机只部署产物，源码类静态检查无从判定）。

部署

docker compose up -d --build
docker compose exec app npx prisma db push   # 首次部署建表
docker compose exec app npm run db:seed      # 首次部署写入初始数据

二次开发指南

下面是四件最常做的事，按顺序照做即可，不需要先通读整个代码库。

开发常见问题