mirror of https://github.com/KwiTsukasa/kt-template-online-api.git synced 2026-05-27 15:44:54 +08:00

sunlei 7291fed682 feat: 支持数据库字典映射并整理公共能力

- 新增 dict 实体表，字典查询改为从数据库读取
- 使用 childrenKey 实现组件一级类型到二级字典的关系映射
- Component 查询后通过 DecodeDictKey 和 AfterLoad 自动补充翻译字段
- 移除 ComponentDto、本地字典常量和本地 seed 文件
- 将 common 能力按 decorators/interceptors/services/swagger 重新分层
- 使用全局 SaveBodyInterceptor 替代 SaveMiddleware 统一处理 save 请求
- 更新 MinIO、组件、字典接口的 Swagger 响应和少量关键注释
- 重写 README.md 和 API.md，补充项目功能、目录结构和接口说明

BREAKING CHANGE: 字典数据依赖数据库 dict 表维护，不再使用本地字典常量。

2026-05-13 15:33:38 +08:00

3.8 KiB

Raw Blame History

KT Template Online API

kt-template-online-api 是 KT Template Online 的 Nest.js 后端服务，负责组件模板管理、数据库字典映射和 MinIO 文件能力。

技术栈

Node.js + TypeScript
Nest.js
TypeORM + MySQL
MinIO
Swagger / Knife4j

功能概览

Component

管理图表/组件模板：

组件列表、分页列表、详情
新增、编辑、逻辑删除
查询阶段自动补充 typeMsg、componentTypeMsg

Dict

维护数据库字典：

字典项存储在 dict 表
COMPONENT_TYPE.children_key 关联二级字典，例如 CHART、COMPONENT
服务会将数据库字典刷新到进程缓存，供实体 AfterLoad 阶段同步翻译字段

MinIO

提供文件服务：

检查/创建 bucket
上传文件
查询对象列表
获取临时访问地址
下载和删除对象

Common

项目通用能力：

统一响应 Swagger 注解
字典翻译注解
POST */save 请求体规范化拦截器
通用响应、分页和查询条件工具

目录结构

src
  common
    decorators/     # 通用装饰器
    interceptors/   # 全局/通用拦截器
    services/       # 通用服务
    swagger/        # Swagger 响应注解封装
    index.ts        # common 统一出口
  component/        # 组件模板模块
  dict/             # 数据库字典模块
  minio/            # MinIO 文件模块
  types/            # 全局类型声明
  app.module.ts
  main.ts

环境变量

项目默认读取 .env，生产环境会读取 .env.prod。

DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=shy_template
DB_SYNC=true

MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=kt-template-online

DB_SYNC=true 时 TypeORM 会按实体同步表结构。生产环境建议关闭同步，改用迁移脚本维护表结构。

数据库字典

dict 表是字典翻译的唯一数据源，代码中不再维护本地字典列表。

核心字段：

字段	说明
`dict_key`	字典分组，例如 `COMPONENT_TYPE`、`CHART`、`COMPONENT`
`label`	展示文本
`value`	字典值
`children_key`	子字典分组，例如一级类型 `1` 指向 `CHART`
`sort`	排序
`is_deleted`	逻辑删除标记

组件类型示例：

dict_key	value	label	children_key
COMPONENT_TYPE	1	图表	CHART
COMPONENT_TYPE	2	组件	COMPONENT

全局 Save 规则

项目注册了 SaveBodyInterceptor，会对 POST */save 请求统一删除 body.id，避免新增接口误用前端传入的主键。

如果某个接口需要保留 id，可以使用：

@SkipSaveBodyNormalize()

启动项目

安装依赖：

pnpm install

开发环境：

pnpm start:dev

普通启动：

pnpm start

生产启动：

pnpm start:prod

文档地址

服务默认监听 48085：

Swagger UI：http://localhost:48085/api
OpenAPI JSON：http://localhost:48085/api-json
Knife4j：由 nestjs-knife4j-plus 根据 /api-json 提供增强文档

接口细节见 API.md。

常用校验

类型检查：

pnpm exec tsc --noEmit

格式化：

pnpm exec prettier --write "src/**/*.ts" "test/**/*.ts"

测试：

pnpm test
pnpm test:e2e

3.8 KiB Raw Blame History Unescape Escape