feat: 后端 SQLite→PostgreSQL 迁移(双驱动)——codes/showcase/sync/chibi/payment/security 全链路支持 pg,修复 grant 保留字,schema 双 DDL 导出

This commit is contained in:
Sisyphus committed 2026-08-19 19:12:26 +08:00
1 parent 346f41d391
commit 605af4cdd3
17 files changed
+1516 -2202

No files matched your search

+99 -75
View File
@@ -5,26 +5,15 @@
* Request: { title: string, imageData: string, tags?: string[], source?: string,
* width?: number, height?: number, brand?: string, materials?: MaterialLine[] }
* Response: 201 { id: number }
* 400 { error: "请输入作品标题" } 标题为空
* 400 { error: "作品标题过长" } 标题超过 100 字符
* 400 { error: "图片格式无效" } imageData 非 base64 dataURL 也非 http(s) URL
* 400 { error: "标签格式无效" } tags 不是数组
* 400 { error: "尺寸参数无效" } width/height 非 1..512 整数
* 400 { error: "品牌格式无效" } brand 非字符串/超长
* 400 { error: "用料清单格式无效" } materials 非法
* 500 服务器内部错误
* 400 参数错误
*
* GET /api/showcase/works(T-100 展示页列表)
* Query: page=1&limit=12&tag=卡通动漫&source=chibi
* Response: 200 { items: [{ id, title, imageUrl, tags, source, createdAt }],
* total, page, limit }(items 按 created_at DESC, id DESC)
* 400 { error: "分页参数无效" } page/limit 非正整数
* Response: 200 { items, total, page, limit }
*
* GET /api/showcase/works/:id(T-131 作品详情)
* Response: 200 { id, title, imageUrl, tags, source, createdAt,
* spec: { width, height, brand, materials } }
* 400 { error: "作品 ID 无效" } id 非正整数
* 404 { error: "作品不存在" } id 无对应记录
* Response: 200 { id, title, imageUrl, tags, source, createdAt, spec }
* 400 / 404
*
* GET /api/showcase/meta(T-101 展示页 SEO 元数据)
* Query: lang=zh|en(缺省 zh)
@@ -33,8 +22,8 @@
import { Router } from "express";
import type { Request, Response } from "express";
import type Database from "better-sqlite3";
import { getDb } from "../db/index.js";
import type { Db, PgDb, SqliteDb } from "../db/index.js";
import { getDb, isPgDb } from "../db/index.js";
import {
insertWork,
getWorkById,
@@ -51,10 +40,10 @@ const MAX_TAGS = 20;
/** 单个标签最大长度。 */
const MAX_TAG_LENGTH = 30;
/** 图纸单边最大格数(与服务端导出能力 512×512 对齐)。 */
/** 图纸单边最大格数。 */
const MAX_GRID_SIZE = 512;
/** 用料清单最大条目数(与前端分享码 256 色上限对齐)。 */
/** 用料清单最大条目数。 */
const MAX_MATERIALS = 256;
/** 品牌名最大长度。 */
@@ -66,20 +55,18 @@ const MAX_MATERIAL_CODE_LENGTH = 20;
/** 用料清单单行名称最大长度。 */
const MAX_MATERIAL_NAME_LENGTH = 30;
/** base64 dataURL:data:image/<type>;base64,<data>(data 可含 +/ 与 = 填充)。 */
/** base64 dataURL。 */
const DATA_URL_RE = /^data:image\/[a-zA-Z0-9.+-]+;base64,[A-Za-z0-9+/=]+$/;
/** http(s) 绝对 URL(图片外链)。 */
/** http(s) 绝对 URL。 */
const HTTP_URL_RE = /^https?:\/\/[^\s]+$/i;
/** Resolve the database instance: injected DB for tests, else global singleton. */
function resolveDb(injected?: Database.Database): Database.Database {
/** Resolve the database instance. */
function resolveDb(injected?: Db): Db {
return injected ?? getDb();
}
/**
* 校验图片字段:必须是 base64 dataURL 或 http(s) URL。
*/
/** 校验图片字段。 */
function isValidImageData(value: string): boolean {
return DATA_URL_RE.test(value) || HTTP_URL_RE.test(value);
}
@@ -87,14 +74,14 @@ function isValidImageData(value: string): boolean {
/**
* 创建 Showcase 路由。接受可选注入数据库以便测试。
*/
export function createShowcaseRouter(injectedDb?: Database.Database): Router {
export function createShowcaseRouter(injectedDb?: Db): Router {
const router = Router();
router.post("/works", (req: Request, res: Response): void => {
router.post("/works", async (req: Request, res: Response): Promise<void> => {
try {
const body = (req.body ?? {}) as Record<string, unknown>;
// ---- title:非空字符串,长度限制 ----
// ---- title ----
const title = typeof body.title === "string" ? body.title.trim() : "";
if (!title) {
res.status(400).json({ error: "请输入作品标题" });
@@ -105,14 +92,14 @@ export function createShowcaseRouter(injectedDb?: Database.Database): Router {
return;
}
// ---- imageData:base64 dataURL 或 http(s) URL ----
// ---- imageData ----
const imageData = typeof body.imageData === "string" ? body.imageData : "";
if (!imageData || !isValidImageData(imageData)) {
res.status(400).json({ error: "图片格式无效" });
return;
}
// ---- tags:必须是数组,元素过滤为合法字符串 ----
// ---- tags ----
const rawTags = body.tags;
if (rawTags !== undefined && !Array.isArray(rawTags)) {
res.status(400).json({ error: "标签格式无效" });
@@ -130,13 +117,13 @@ export function createShowcaseRouter(injectedDb?: Database.Database): Router {
return;
}
// ---- source:可选字符串,默认 manual ----
// ---- source ----
const source =
typeof body.source === "string" && body.source.trim() !== ""
? body.source.trim().slice(0, 50)
: "manual";
// ---- 规格字段(T-131:详情页需要的尺寸/品牌/用料信息,均可选)----
// ---- 规格字段 ----
const width = validateOptionalGridSize(body.width);
if (width.error !== null) {
res.status(400).json({ error: width.error });
@@ -158,7 +145,8 @@ export function createShowcaseRouter(injectedDb?: Database.Database): Router {
return;
}
const id = insertWork(resolveDb(injectedDb), {
const db = resolveDb(injectedDb);
const id = await insertWork(db, {
title,
imageData,
tags,
@@ -177,9 +165,8 @@ export function createShowcaseRouter(injectedDb?: Database.Database): Router {
/**
* GET /api/showcase/works — 展示页列表(分页 + 标签筛选 + 来源筛选)。
* 按 created_at DESC, id DESC 排序,返回契约字段 items/total/page/limit。
*/
router.get("/works", (req: Request, res: Response): void => {
router.get("/works", async (req: Request, res: Response): Promise<void> => {
const page = parsePositiveInt(req.query["page"], DEFAULT_PAGE);
const limitRaw = parsePositiveInt(req.query["limit"], DEFAULT_LIMIT);
if (page === null || limitRaw === null) {
@@ -192,33 +179,54 @@ export function createShowcaseRouter(injectedDb?: Database.Database): Router {
const source = parseQueryString(req.query["source"]);
const db = resolveDb(injectedDb);
const { where, params } = buildFilter(tag, source);
const totalRow = db
.prepare(`SELECT COUNT(*) AS total FROM showcase_works w ${where}`)
.get(...params) as { total: number };
const isPg = isPgDb(db);
const { where, params, limitPh, offsetPh } = buildFilter(tag, source, isPg);
const offset = (page - 1) * limit;
const rows = db
.prepare(
let total: number;
let rows: ShowcaseWorkRow[];
if (isPg) {
const pg = db as PgDb;
const totalRes = await pg.query<{ total: number }>(
`SELECT COUNT(*)::int AS total FROM showcase_works w ${where}`,
params,
);
total = totalRes.rows[0]!.total;
const listRes = await pg.query<ShowcaseWorkRow>(
`SELECT w.id, w.title, w.image_data, w.tags, w.source, w.created_at
FROM showcase_works w
${where}
ORDER BY w.created_at DESC, w.id DESC
LIMIT ? OFFSET ?`,
)
.all(...params, limit, offset) as ShowcaseWorkRow[];
LIMIT ${limitPh} OFFSET ${offsetPh}`,
[...params, limit, offset],
);
rows = listRes.rows as ShowcaseWorkRow[];
} else {
const sql = db as SqliteDb;
const totalRow = sql
.prepare(`SELECT COUNT(*) AS total FROM showcase_works w ${where}`)
.get(...params) as { total: number };
total = totalRow.total;
rows = sql
.prepare(
`SELECT w.id, w.title, w.image_data, w.tags, w.source, w.created_at
FROM showcase_works w
${where}
ORDER BY w.created_at DESC, w.id DESC
LIMIT ${limitPh} OFFSET ${offsetPh}`,
)
.all(...params, limit, offset) as ShowcaseWorkRow[];
}
const items = rows.map(toShowcaseWork);
res.status(200).json({ items, total: totalRow.total, page, limit });
res.status(200).json({ items, total, page, limit });
});
/**
* GET /api/showcase/works/:id — 作品详情(T-131)。
* 按 id 查询单作品:返回基础字段 + spec 规格块(尺寸/品牌/用料清单,缺省可空)。
* id 非正整数 → 400;记录不存在 → 404。
*/
router.get("/works/:id", (req: Request, res: Response): void => {
router.get("/works/:id", async (req: Request, res: Response): Promise<void> => {
try {
const id = parsePositiveId(req.params["id"]);
if (id === null) {
@@ -226,7 +234,7 @@ export function createShowcaseRouter(injectedDb?: Database.Database): Router {
return;
}
const db = resolveDb(injectedDb);
const row = getWorkById(db, id);
const row = await getWorkById(db, id);
if (row === undefined) {
res.status(404).json({ error: "作品不存在" });
return;
@@ -240,8 +248,6 @@ export function createShowcaseRouter(injectedDb?: Database.Database): Router {
/**
* GET /api/showcase/meta — 展示页 SEO 元数据(多语言)。
* 供前端注入 og:title / og:description / og:image,并附带 JSON-LD
* CollectionPage 结构化数据(可整段写入 <script type="application/ld+json">)。
*/
router.get("/meta", (req: Request, res: Response): void => {
const lang = normalizeLang(req.query["lang"]);
@@ -268,7 +274,7 @@ const DEFAULT_PAGE = 1;
const DEFAULT_LIMIT = 12;
const MAX_LIMIT = 100;
/** 解析正整数查询参数;缺失回退默认值,非法(非整数 / <1)返回 null。 */
/** 解析正整数查询参数。 */
function parsePositiveInt(raw: unknown, fallback: number): number | null {
if (raw === undefined) return fallback;
if (typeof raw !== "string" || raw.trim() === "") return fallback;
@@ -277,36 +283,54 @@ function parsePositiveInt(raw: unknown, fallback: number): number | null {
return n;
}
/** 解析可选查询字符串参数;空值 / 非字符串返回 null。 */
/** 解析可选查询字符串参数。 */
function parseQueryString(raw: unknown): string | null {
if (typeof raw !== "string") return null;
const trimmed = raw.trim();
return trimmed === "" ? null : trimmed;
}
/** 构建标签 / 来源筛选的 WHERE 子句与参数(标签用 json_each 精确匹配)。 */
function buildFilter(tag: string | null, source: string | null): {
/**
* 构建标签 / 来源筛选的 WHERE 子句与参数。
* 占位符编号统一:tag → $1, source → $2, LIMIT → $M, OFFSET → $M+1(pg 风格);
* sqlite 用 ? 占位符,通过 ph() 生成。
*/
function buildFilter(
tag: string | null,
source: string | null,
pg: boolean,
): {
where: string;
params: unknown[];
limitPh: string;
offsetPh: string;
} {
const clauses: string[] = [];
const params: unknown[] = [];
let n = 1;
const ph = (): string => (pg ? `$${n++}` : "?");
if (tag !== null) {
clauses.push("EXISTS (SELECT 1 FROM json_each(w.tags) je WHERE je.value = ?)");
const p = ph();
clauses.push(
pg
? `EXISTS (SELECT 1 FROM jsonb_array_elements_text(w.tags::jsonb) je WHERE je = ${p})`
: `EXISTS (SELECT 1 FROM json_each(w.tags) je WHERE je.value = ${p})`,
);
params.push(tag);
}
if (source !== null) {
clauses.push("w.source = ?");
clauses.push(`w.source = ${ph()}`);
params.push(source);
}
return {
where: clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "",
params,
};
const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
const limitPh = ph();
const offsetPh = ph();
return { where, params, limitPh, offsetPh };
}
/** 解析 tags JSON 文本为字符串数组;非法 JSON / 非数组回退空数组。 */
/** 解析 tags JSON 文本为字符串数组。 */
function toShowcaseWork(row: ShowcaseWorkRow): {
id: number;
title: string;
@@ -334,7 +358,7 @@ function toShowcaseWork(row: ShowcaseWorkRow): {
};
}
/** 解析路径参数 :id 为合法正整数(AUTOINCREMENT id ≥ 1);非法返回 null。 */
/** 解析路径参数 :id 为合法正整数。 */
function parsePositiveId(raw: unknown): number | null {
if (typeof raw !== "string" || raw.trim() === "") return null;
if (!/^[1-9]\d*$/.test(raw.trim())) return null;
@@ -343,7 +367,7 @@ function parsePositiveId(raw: unknown): number | null {
return n;
}
/** 校验可选规格整数(1..MAX_GRID_SIZE);缺省/空返回 null,非法返回错误信息。 */
/** 校验可选规格整数(1..MAX_GRID_SIZE)。 */
function validateOptionalGridSize(raw: unknown): { value: number | null; error: string | null } {
if (raw === undefined || raw === null) return { value: null, error: null };
if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1 || raw > MAX_GRID_SIZE) {
@@ -352,7 +376,7 @@ function validateOptionalGridSize(raw: unknown): { value: number | null; error:
return { value: raw, error: null };
}
/** 校验可选品牌名(非空字符串,≤50 字符);非法返回错误信息。 */
/** 校验可选品牌名。 */
function validateBrand(raw: unknown): { value: string | null; error: string | null } {
if (raw === undefined || raw === null) return { value: null, error: null };
if (typeof raw !== "string") return { value: null, error: "品牌格式无效" };
@@ -363,7 +387,7 @@ function validateBrand(raw: unknown): { value: string | null; error: string | nu
return { value: trimmed, error: null };
}
/** 校验可选用料清单({code, count, name?}[],≤256 行);非法返回错误信息。 */
/** 校验可选用料清单。 */
function validateMaterials(raw: unknown): { value: MaterialLine[] | null; error: string | null } {
if (raw === undefined || raw === null) return { value: null, error: null };
if (!Array.isArray(raw) || raw.length > MAX_MATERIALS) {
@@ -401,7 +425,7 @@ function validateMaterials(raw: unknown): { value: MaterialLine[] | null; error:
return { value: lines, error: null };
}
/** 解析 materials JSON 文本为用料清单;缺省/脏数据返回 null。 */
/** 解析 materials JSON 文本为用料清单。 */
function parseMaterials(raw: string | null): MaterialLine[] | null {
if (raw === null || raw === "") return null;
try {
@@ -419,7 +443,7 @@ function parseMaterials(raw: string | null): MaterialLine[] | null {
}
}
/** 详情接口响应结构:基础字段 + spec 规格块(尺寸/品牌/用料,缺省可空)。 */
/** 详情接口响应结构。 */
function toWorkDetail(row: ShowcaseWorkRow): {
id: number;
title: string;
@@ -446,7 +470,7 @@ function toWorkDetail(row: ShowcaseWorkRow): {
};
}
/** 规范化 lang 参数:zh/zh-CN/zh-TW → zh;en/en-US/en-GB → en;其余 → zh。 */
/** 规范化 lang 参数。 */
export function normalizeLang(raw: unknown): "zh" | "en" {
if (typeof raw !== "string") return "zh";
const lower = raw.trim().toLowerCase();
@@ -454,7 +478,7 @@ export function normalizeLang(raw: unknown): "zh" | "en" {
return "zh";
}
/** 展示页 SEO 文案(zh / en)。 */
/** 展示页 SEO 文案。 */
export const SHOWCASE_META: Readonly<Record<"zh" | "en", { title: string; description: string }>> = {
zh: {
title: "拼豆艺术作品展示 | PERLER LAB 拼豆图纸生成器",
@@ -467,8 +491,8 @@ export const SHOWCASE_META: Readonly<Record<"zh" | "en", { title: string; descri
},
};
/** og:image 默认路径;可用环境变量 SHOWCASE_OG_IMAGE 覆盖为完整 URL。 */
/** og:image 默认路径。 */
function resolveOgImage(): string {
const custom = process.env["SHOWCASE_OG_IMAGE"];
return custom !== undefined && custom.trim() !== "" ? custom.trim() : "/og-showcase.png";
}
}
+60 -14
View File
@@ -1,5 +1,5 @@
/**
* chibi Showcase 作品数据层:showcase_works 表的插入操作。
* chibi Showcase 作品数据层:showcase_works 表的插入/查询操作。
*
* 作品信息:
* - title: 作品标题(非空)
@@ -8,7 +8,8 @@
* - source: 作品来源(如 chibi / manual)
*/
import type Database from "better-sqlite3";
import type { Db, PgDb, SqliteDb } from "../db/index.js";
import { isPgDb } from "../db/index.js";
/** showcase_works 表行结构。 */
export interface ShowcaseWorkRow {
@@ -43,11 +44,12 @@ export interface InsertWorkInput {
materials?: MaterialLine[] | null;
}
/**
* 插入一条作品记录,返回自增主键 id。
* 规格字段可选(T-131):缺省时写入 NULL,详情接口返回可空规格。
*/
export function insertWork(db: Database.Database, input: InsertWorkInput): number {
// ---------------------------------------------------------------------------
// SQLite 实现(同步,测试路径)
// ---------------------------------------------------------------------------
/** 插入一条作品记录,返回自增主键 id(SQLite,同步)。 */
function insertWorkSqlite(db: SqliteDb, input: InsertWorkInput): number {
const info = db
.prepare(
`INSERT INTO showcase_works (title, image_data, tags, source, width, height, brand, materials)
@@ -68,14 +70,58 @@ export function insertWork(db: Database.Database, input: InsertWorkInput): numbe
return Number(info.lastInsertRowid);
}
/**
* 按 id 查询单条作品记录;不存在返回 undefined(详情接口主查询)。
*/
export function getWorkById(
db: Database.Database,
id: number,
): ShowcaseWorkRow | undefined {
function getWorkByIdSqlite(db: SqliteDb, id: number): ShowcaseWorkRow | undefined {
return db.prepare(`SELECT * FROM showcase_works WHERE id = ?`).get(id) as
| ShowcaseWorkRow
| undefined;
}
// ---------------------------------------------------------------------------
// PostgreSQL 实现(异步,生产路径)
// ---------------------------------------------------------------------------
async function insertWorkPg(db: PgDb, input: InsertWorkInput): Promise<number> {
const res = await db.query<{ id: number }>(
`INSERT INTO showcase_works (title, image_data, tags, source, width, height, brand, materials)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
RETURNING id`,
[
input.title,
input.imageData,
JSON.stringify(input.tags),
input.source,
input.width ?? null,
input.height ?? null,
input.brand ?? null,
input.materials === undefined || input.materials === null
? null
: JSON.stringify(input.materials),
],
);
return res.rows[0]!.id;
}
async function getWorkByIdPg(db: PgDb, id: number): Promise<ShowcaseWorkRow | undefined> {
const res = await db.query<ShowcaseWorkRow>(`SELECT * FROM showcase_works WHERE id = $1`, [id]);
return res.rows[0] as ShowcaseWorkRow | undefined;
}
// ---------------------------------------------------------------------------
// 公共 Dispatcher
// ---------------------------------------------------------------------------
type MaybePromise<T> = T | Promise<T>;
export function insertWork(db: SqliteDb, input: InsertWorkInput): number;
export function insertWork(db: PgDb, input: InsertWorkInput): Promise<number>;
export function insertWork(db: Db, input: InsertWorkInput): MaybePromise<number>;
export function insertWork(db: Db, input: InsertWorkInput): MaybePromise<number> {
return isPgDb(db) ? insertWorkPg(db, input) : insertWorkSqlite(db, input);
}
export function getWorkById(db: SqliteDb, id: number): ShowcaseWorkRow | undefined;
export function getWorkById(db: PgDb, id: number): Promise<ShowcaseWorkRow | undefined>;
export function getWorkById(db: Db, id: number): MaybePromise<ShowcaseWorkRow | undefined>;
export function getWorkById(db: Db, id: number): MaybePromise<ShowcaseWorkRow | undefined> {
return isPgDb(db) ? getWorkByIdPg(db, id) : getWorkByIdSqlite(db, id);
}