feat: V1.2 P0 批次入库——四页合规/作品详情页/后端详情接口

This commit is contained in:
Sisyphus committed 2026-08-15 15:13:51 +08:00
1 parent f53f0a2b25
commit 346f41d391
23 files changed
+3495 -173

No files matched your search

+201 -3
View File
@@ -2,12 +2,16 @@
* chibi Showcase 作品 API。
*
* POST /api/showcase/works(T-099 发布接口)
* Request: { title: string, imageData: string, tags?: string[], source?: string }
* 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 服务器内部错误
*
* GET /api/showcase/works(T-100 展示页列表)
@@ -16,6 +20,12 @@
* total, page, limit }(items 按 created_at DESC, id DESC)
* 400 { error: "分页参数无效" } 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 无对应记录
*
* GET /api/showcase/meta(T-101 展示页 SEO 元数据)
* Query: lang=zh|en(缺省 zh)
* Response: 200 { title, description, ogImage, jsonLd }
@@ -25,7 +35,12 @@ import { Router } from "express";
import type { Request, Response } from "express";
import type Database from "better-sqlite3";
import { getDb } from "../db/index.js";
import { insertWork, type ShowcaseWorkRow } from "./service.js";
import {
insertWork,
getWorkById,
type ShowcaseWorkRow,
type MaterialLine,
} from "./service.js";
/** 标题最大长度。 */
const MAX_TITLE_LENGTH = 100;
@@ -36,6 +51,21 @@ const MAX_TAGS = 20;
/** 单个标签最大长度。 */
const MAX_TAG_LENGTH = 30;
/** 图纸单边最大格数(与服务端导出能力 512×512 对齐)。 */
const MAX_GRID_SIZE = 512;
/** 用料清单最大条目数(与前端分享码 256 色上限对齐)。 */
const MAX_MATERIALS = 256;
/** 品牌名最大长度。 */
const MAX_BRAND_LENGTH = 50;
/** 用料清单单行色号最大长度。 */
const MAX_MATERIAL_CODE_LENGTH = 20;
/** 用料清单单行名称最大长度。 */
const MAX_MATERIAL_NAME_LENGTH = 30;
/** base64 dataURL:data:image/<type>;base64,<data>(data 可含 +/ 与 = 填充)。 */
const DATA_URL_RE = /^data:image\/[a-zA-Z0-9.+-]+;base64,[A-Za-z0-9+/=]+$/;
@@ -106,7 +136,38 @@ export function createShowcaseRouter(injectedDb?: Database.Database): Router {
? body.source.trim().slice(0, 50)
: "manual";
const id = insertWork(resolveDb(injectedDb), { title, imageData, tags, source });
// ---- 规格字段(T-131:详情页需要的尺寸/品牌/用料信息,均可选)----
const width = validateOptionalGridSize(body.width);
if (width.error !== null) {
res.status(400).json({ error: width.error });
return;
}
const height = validateOptionalGridSize(body.height);
if (height.error !== null) {
res.status(400).json({ error: height.error });
return;
}
const brand = validateBrand(body.brand);
if (brand.error !== null) {
res.status(400).json({ error: brand.error });
return;
}
const materials = validateMaterials(body.materials);
if (materials.error !== null) {
res.status(400).json({ error: materials.error });
return;
}
const id = insertWork(resolveDb(injectedDb), {
title,
imageData,
tags,
source,
width: width.value,
height: height.value,
brand: brand.value,
materials: materials.value,
});
res.status(201).json({ id });
} catch (err) {
console.error("POST /api/showcase/works error:", err);
@@ -152,6 +213,31 @@ export function createShowcaseRouter(injectedDb?: Database.Database): Router {
res.status(200).json({ items, total: totalRow.total, page, limit });
});
/**
* GET /api/showcase/works/:id — 作品详情(T-131)。
* 按 id 查询单作品:返回基础字段 + spec 规格块(尺寸/品牌/用料清单,缺省可空)。
* id 非正整数 → 400;记录不存在 → 404。
*/
router.get("/works/:id", (req: Request, res: Response): void => {
try {
const id = parsePositiveId(req.params["id"]);
if (id === null) {
res.status(400).json({ error: "作品 ID 无效" });
return;
}
const db = resolveDb(injectedDb);
const row = getWorkById(db, id);
if (row === undefined) {
res.status(404).json({ error: "作品不存在" });
return;
}
res.status(200).json(toWorkDetail(row));
} catch (err) {
console.error("GET /api/showcase/works/:id error:", err);
res.status(500).json({ error: "服务器内部错误,请稍后重试" });
}
});
/**
* GET /api/showcase/meta — 展示页 SEO 元数据(多语言)。
* 供前端注入 og:title / og:description / og:image,并附带 JSON-LD
@@ -248,6 +334,118 @@ function toShowcaseWork(row: ShowcaseWorkRow): {
};
}
/** 解析路径参数 :id 为合法正整数(AUTOINCREMENT id ≥ 1);非法返回 null。 */
function parsePositiveId(raw: unknown): number | null {
if (typeof raw !== "string" || raw.trim() === "") return null;
if (!/^[1-9]\d*$/.test(raw.trim())) return null;
const n = Number(raw.trim());
if (!Number.isSafeInteger(n) || n < 1) return null;
return n;
}
/** 校验可选规格整数(1..MAX_GRID_SIZE);缺省/空返回 null,非法返回错误信息。 */
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) {
return { value: 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: "品牌格式无效" };
const trimmed = raw.trim();
if (trimmed === "" || trimmed.length > MAX_BRAND_LENGTH) {
return { value: null, error: "品牌格式无效" };
}
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) {
return { value: null, error: "用料清单格式无效" };
}
const lines: MaterialLine[] = [];
for (const item of raw) {
if (typeof item !== "object" || item === null) {
return { value: null, error: "用料清单格式无效" };
}
const rec = item as Record<string, unknown>;
if (
typeof rec.code !== "string" ||
rec.code.trim() === "" ||
rec.code.length > MAX_MATERIAL_CODE_LENGTH
) {
return { value: null, error: "用料清单格式无效" };
}
if (typeof rec.count !== "number" || !Number.isInteger(rec.count) || rec.count < 1) {
return { value: null, error: "用料清单格式无效" };
}
const line: MaterialLine = { code: rec.code.trim(), count: rec.count };
if (rec.name !== undefined) {
if (
typeof rec.name !== "string" ||
rec.name.trim() === "" ||
rec.name.length > MAX_MATERIAL_NAME_LENGTH
) {
return { value: null, error: "用料清单格式无效" };
}
line.name = rec.name.trim();
}
lines.push(line);
}
return { value: lines, error: null };
}
/** 解析 materials JSON 文本为用料清单;缺省/脏数据返回 null。 */
function parseMaterials(raw: string | null): MaterialLine[] | null {
if (raw === null || raw === "") return null;
try {
const parsed: unknown = JSON.parse(raw);
if (!Array.isArray(parsed)) return null;
return parsed.filter(
(l): l is MaterialLine =>
typeof l === "object" &&
l !== null &&
typeof (l as MaterialLine).code === "string" &&
typeof (l as MaterialLine).count === "number",
);
} catch {
return null;
}
}
/** 详情接口响应结构:基础字段 + spec 规格块(尺寸/品牌/用料,缺省可空)。 */
function toWorkDetail(row: ShowcaseWorkRow): {
id: number;
title: string;
imageUrl: string;
tags: string[];
source: string;
createdAt: string;
spec: {
width: number | null;
height: number | null;
brand: string | null;
materials: MaterialLine[] | null;
};
} {
const base = toShowcaseWork(row);
return {
...base,
spec: {
width: row.width,
height: row.height,
brand: row.brand,
materials: parseMaterials(row.materials),
},
};
}
/** 规范化 lang 参数:zh/zh-CN/zh-TW → zh;en/en-US/en-GB → en;其余 → zh。 */
export function normalizeLang(raw: unknown): "zh" | "en" {
if (typeof raw !== "string") return "zh";
+42 -3
View File
@@ -18,6 +18,17 @@ export interface ShowcaseWorkRow {
tags: string;
source: string;
created_at: string;
width: number | null;
height: number | null;
brand: string | null;
materials: string | null;
}
/** 用料清单单行:MARD 色号 + 数量(name 可选)。 */
export interface MaterialLine {
code: string;
count: number;
name?: string;
}
/** 发布作品的入参(已通过路由层校验)。 */
@@ -26,17 +37,45 @@ export interface InsertWorkInput {
imageData: string;
tags: string[];
source: string;
width?: number | null;
height?: number | null;
brand?: string | null;
materials?: MaterialLine[] | null;
}
/**
* 插入一条作品记录,返回自增主键 id。
* 规格字段可选(T-131):缺省时写入 NULL,详情接口返回可空规格。
*/
export function insertWork(db: Database.Database, input: InsertWorkInput): number {
const info = db
.prepare(
`INSERT INTO showcase_works (title, image_data, tags, source)
VALUES (?, ?, ?, ?)`,
`INSERT INTO showcase_works (title, image_data, tags, source, width, height, brand, materials)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
)
.run(input.title, input.imageData, JSON.stringify(input.tags), input.source);
.run(
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 Number(info.lastInsertRowid);
}
/**
* 按 id 查询单条作品记录;不存在返回 undefined(详情接口主查询)。
*/
export function getWorkById(
db: Database.Database,
id: number,
): ShowcaseWorkRow | undefined {
return db.prepare(`SELECT * FROM showcase_works WHERE id = ?`).get(id) as
| ShowcaseWorkRow
| undefined;
}