feat(busca): pin-number queries in every language, pin answer card

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -6,6 +6,25 @@ Tudo o que muda de relevante no ESPDocs está aqui. O formato segue o
 
 ## [Não lançado]
 
+## [1.7.0] - 2026-11-02
+
+### Adicionado
+
+- A busca inteligente entende pinos específicos, nos seis idiomas: `pino 32 esp32-s3`,
+  `pin 32 esp32-s3`, `broche 32 esp32-s3`, `esp32-s3 32号引脚`. O resultado é um cartão
+  com tudo o que o diagrama diz sobre o pino (nome, funções, categorias e avisos) e o
+  link para o diagrama filtrado, como já acontecia com memória, energia e outros assuntos.
+  - Como "pino 32" pode ser o pino físico ou o GPIO32, os dois aparecem quando são
+    pinos diferentes.
+  - Sem o chip (`pino 32`), vem um quadro com o que há nesse pino em cada série; com um
+    número que o chip não tem, a busca avisa até onde vão os pinos.
+  - O pino reconhecido aparece junto do chip na faixa "Entendi" e nos exemplos da busca.
+
+### Corrigido
+
+- Linhas repetidas num cartão da busca (por exemplo, vários avisos de um pino) saíam
+  duplicadas e fora de ordem.
+
 ## [1.6.1] - 2026-11-02
 
 ### Corrigido
@@ -255,7 +274,8 @@ entrada resume tudo desde o primeiro commit, em 2025-10-21, até a imagem Docker
   otimização de imagens (GHSA-2464-fhr4-w9xw), e `postcss` fixado acima da cópia
   embutida no `next`.
 
-[Não lançado]: https://git.lucasrguerra.dev.br/lucasrguerra/ESPDocs/compare/v1.6.1...HEAD
+[Não lançado]: https://git.lucasrguerra.dev.br/lucasrguerra/ESPDocs/compare/v1.7.0...HEAD
+[1.7.0]: https://git.lucasrguerra.dev.br/lucasrguerra/ESPDocs/compare/v1.6.1...v1.7.0
 [1.6.1]: https://git.lucasrguerra.dev.br/lucasrguerra/ESPDocs/compare/v1.6.0...v1.6.1
 [1.6.0]: https://git.lucasrguerra.dev.br/lucasrguerra/ESPDocs/compare/v1.5.0...v1.6.0
 [1.5.0]: https://git.lucasrguerra.dev.br/lucasrguerra/ESPDocs/compare/v1.4.2...v1.5.0

components/SearchDialog.jsx

@@ -88,11 +88,11 @@ const TIPOS_ZH = {
 
 const INTELIGENTES = new Set(["resposta", "pino"]);
 
-const EXEMPLOS_EN = ["flash s3", "usb pins c6", "gpio0 esp32", "brownout", "LVGL", "FreeRTOS"];
+const EXEMPLOS_EN = ["flash s3", "usb pins c6", "pin 32 esp32-s3", "gpio0 esp32", "brownout", "LVGL"];
-const EXEMPLOS_ES = ["flash s3", "pines usb c6", "gpio0 esp32", "brownout", "LVGL", "FreeRTOS"];
+const EXEMPLOS_ES = ["flash s3", "pines usb c6", "pin 32 esp32-s3", "gpio0 esp32", "brownout", "LVGL"];
-const EXEMPLOS_FR = ["flash s3", "broches usb c6", "gpio0 esp32", "brownout", "LVGL", "FreeRTOS"];
+const EXEMPLOS_FR = ["flash s3", "broches usb c6", "broche 32 esp32-s3", "gpio0 esp32", "brownout", "LVGL"];
-const EXEMPLOS_DE = ["flash s3", "usb pins c6", "gpio0 esp32", "brownout", "LVGL", "FreeRTOS"];
+const EXEMPLOS_DE = ["flash s3", "usb pins c6", "pin 32 esp32-s3", "gpio0 esp32", "brownout", "LVGL"];
-const EXEMPLOS_ZH = ["s3 闪存", "c6 usb 引脚", "esp32 gpio0", "brownout", "LVGL", "FreeRTOS"];
+const EXEMPLOS_ZH = ["s3 闪存", "c6 usb 引脚", "esp32-s3 32号引脚", "esp32 gpio0", "brownout", "LVGL"];
 
 function Destaque({ texto, termos }) {
 	if (!termos.length) return texto;
@@ -298,7 +298,7 @@ export default function SearchDialog() {
 		}
 	}
 
-	const entendeu = interpretacao.chips.length > 0 || interpretacao.topicos.length > 0;
+	const entendeu = interpretacao.chips.length > 0 || interpretacao.topicos.length > 0 || (interpretacao.pinos?.length ?? 0) > 0;
 
 	return (
 		<>
@@ -361,6 +361,9 @@ export default function SearchDialog() {
 									{interpretacao.chips.map((c) => (
 										<Pilula key={c.chave} forte>{c.nome}</Pilula>
 									))}
+									{interpretacao.pinos?.map((p) => (
+										<Pilula key={p}>{p}</Pilula>
+									))}
 									{interpretacao.topicos.map((t) => (
 										<Pilula key={t.id}>{t.nome}</Pilula>
 									))}
@@ -489,8 +492,8 @@ export default function SearchDialog() {
 
 												{item.linhas && (
 													<dl className="mt-2 grid gap-x-4 gap-y-1 text-xs sm:grid-cols-[auto_1fr]">
-														{item.linhas.map((l) => (
+														{item.linhas.map((l, i) => (
-															<div key={l.k} className="contents">
+															<div key={`${l.k}-${i}`} className="contents">
 																<dt className="font-semibold text-ink-soft">{l.k}</dt>
 																<dd className="text-ink">{l.v}</dd>
 															</div>

lib/searchEngine.js

@@ -16,7 +16,7 @@ const STOP = new Set([
 	"para", "pra", "pro", "com", "sem", "que", "qual", "quais", "como", "e", "ou", "ver", "sobre", "eh",
 	"preciso", "quero", "onde", "fica", "ficam", "esta", "estao", "meu", "minha", "usar", "uso",
 ]);
-const INTENCAO_PINOS = new Set(["pino", "pinos", "pinagem", "pinout", "pin", "pins", "gpios"]);
+const INTENCAO_PINOS = new Set(["pino", "pinos", "pinagem", "pinout", "pin", "pins", "gpios", "pines", "broche", "broches", "brochage", "pinbelegung"]);
 const INTENCAO_DADOS = new Set([
 	"dados", "especificacao", "especificacoes", "spec", "specs", "informacao", "informacoes", "info",
 	"quanto", "quantos", "quantas", "capacidade", "limite", "limites", "tem", "possui", "suporta",
@@ -137,9 +137,17 @@ function casarTermo(termo, livres) {
 	return null;
 }
 
+// "pino 32", "pin 32", "broche 32", "引脚 32", "32号引脚": número do pino físico do diagrama.
+const PINO_FISICO = /\b(?:pino|pinos|pin|pins|pines|broche|broches)\s*(?:n[ºo°.]?\s*|numero\s*|number\s*|nummer\s*)?(\d{1,3})\b(?![.,]\d)/g;
+const PINO_FISICO_ZH = /第?(\d{1,3})\s*(?:号|脚)?\s*(?:引脚|管脚|针脚)|(?:引脚|管脚|针脚)\s*第?(\d{1,3})(?![.,\d])/g;
+
 export function interpretar(indice, consulta) {
-	const bruto = normalizar(consulta)
+	const pinNums = [];
+	const semPinos = normalizar(consulta)
 		.replace(/gpio\s*-?\s*(\d+)/g, "gpio$1")
+		.replace(PINO_FISICO, (_, n) => (pinNums.push(n), " "))
+		.replace(PINO_FISICO_ZH, (_, a, b) => (pinNums.push(a ?? b), " "));
+	const bruto = semPinos
 		.replace(/([\u3400-\u9fff])([a-z0-9])/g, "$1 $2")
 		.replace(/([a-z0-9])([\u3400-\u9fff])/g, "$1 $2")
 		.replace(/[^a-z0-9.+\-_ \u3400-\u9fff]/g, " ");
@@ -231,7 +239,7 @@ export function interpretar(indice, consulta) {
 
 	cjkUsados.forEach((i) => usados.add(i));
 	const restantes = tokens.filter((_, i) => !usados.has(i)).flatMap((t) => (CJK.test(t) ? segmentar(t) : [t]));
-	return { tokens, chips, topicos, gpios, funcoes, restantes, querPinos, querDados };
+	return { tokens, chips, topicos, gpios, funcoes, restantes, querPinos, querDados, pinNums: [...new Set(pinNums)].slice(0, 3) };
 }
 
 const rotuloPino = (p) => {
@@ -253,6 +261,27 @@ function pinosDoTopico(serie, topico) {
 	return { forte, fraco };
 }
 
+const corta = (s, max = 110) => (s.length > max ? `${s.slice(0, max - 1).trimEnd()}…` : s);
+
+/** Cartão com tudo o que o diagrama diz sobre um pino (nome, funções, categorias, avisos). */
+function cartaoPino(I, chave, serie, p, titulo) {
+	const T = I.t;
+	const linhas = [
+		{ k: T.kPino, v: String(p.n) },
+		{ k: T.kNome, v: rotuloPino(p) },
+	];
+	if (p.f?.length) linhas.push({ k: T.kFuncoes, v: corta(p.f.join(" · ")) });
+	if (p.c?.length) linhas.push({ k: T.kCategorias, v: p.c.join(", ") });
+	(p.a ?? []).slice(0, 3).forEach((a) => linhas.push({ k: T.kAviso, v: corta(a) }));
+	return {
+		tipo: "resposta",
+		titulo,
+		descricao: T.pinoDesc,
+		linhas,
+		href: hrefPinos(I, chave, [p], fmt(T.motivoPino, { pino: rotuloPino(p) })),
+	};
+}
+
 const hrefPinos = (I, chave, pinos, motivo) =>
 	`${I.rotas.series}/${chave}?pinos=${pinos.map((p) => p.n).join(",")}&motivo=${encodeURIComponent(motivo)}#connections`;
 
@@ -307,7 +336,19 @@ function respostas(indice, it) {
 			(it.querPinos ? [cartaoPinos, cartaoSpec] : [cartaoSpec, cartaoPinos]).filter(Boolean).forEach((c) => saida.push(c));
 		}
 
-		if (!it.topicos.length && !it.gpios.length && !it.funcoes.length) {
+		// "pino 32 s3": o pino físico 32 do diagrama e, se for outro, o GPIO32.
+		for (const n of it.pinNums) {
+			const fisico = serie.pinos.find((p) => String(p.n) === n);
+			const gpio = (indice.porFuncao.get(`gpio${n}`) ?? []).find((a) => a.chave === chave)?.pino;
+			if (fisico) saida.push(cartaoPino(I, chave, serie, fisico, fmt(T.pinoFisico, { n, serie: serie.nome })));
+			if (gpio && gpio !== fisico) saida.push(cartaoPino(I, chave, serie, gpio, fmt(T.pinoNo, { pino: rotuloPino(gpio), serie: serie.nome })));
+			if (!fisico && !gpio) {
+				const max = Math.max(0, ...serie.pinos.map((p) => Number(p.n) || 0));
+				saida.push({ tipo: "pino", titulo: fmt(T.pinoInexistente, { n, serie: serie.nome }), descricao: fmt(T.pinoInexistenteDesc, { max }), href: `${I.rotas.series}/${chave}#connections` });
+			}
+		}
+
+		if (!it.topicos.length && !it.gpios.length && !it.funcoes.length && !it.pinNums.length) {
 			if (it.querPinos && serie.pinos.length) {
 				saida.push({
 					tipo: "pino",
@@ -337,6 +378,18 @@ function respostas(indice, it) {
 		}
 	}
 
+	// Pino físico sem chip: o que há nele em cada série.
+	if (!alvos.length) {
+		for (const n of it.pinNums) {
+			const linhas = [];
+			for (const chave of indice.chaves) {
+				const p = indice.series[chave].pinos.find((x) => String(x.n) === n);
+				if (p) linhas.push({ k: indice.series[chave].nome, v: corta(rotuloPino(p), 46) });
+			}
+			if (linhas.length) saida.push({ tipo: "resposta", titulo: fmt(T.pinoEmCada, { n }), descricao: fmt(T.pinoEmCadaDesc, { n }), linhas, href: I.rotas.series });
+		}
+	}
+
 	// GPIO26 e nomes de função: "gpio26 s3", "mtck"
 	const buscas = [...it.gpios, ...it.funcoes];
 	for (const termo of buscas) {
@@ -387,6 +440,7 @@ export function buscar(indice, consulta) {
 	const interpretacao = {
 		chips: it.chips.map((c) => ({ chave: c, nome: indice.series[c]?.nome ?? c })),
 		topicos: it.topicos.map((t) => ({ id: t.id, nome: indice.topicosLoc?.[t.id]?.nome ?? t.nome })),
+		pinos: it.pinNums.map((n) => fmt((BUSCA_I18N[indice.locale] ?? BUSCA_I18N.pt).t.chipPino, { n })),
 	};
 
 	const smart = respostas(indice, it).map((r, i) => ({ id: `r${i}`, keywords: "", ...r }));
@@ -436,11 +490,11 @@ export function buscar(indice, consulta) {
 	const sugestoes = [];
 	if (it.topicos.length && !it.chips.length) {
 		for (const c of indice.chaves.slice(0, 12)) sugestoes.push({ rotulo: indice.series[c].nome, anexar: c });
-	} else if (it.chips.length && !it.topicos.length && !it.gpios.length) {
+	} else if (it.chips.length && !it.topicos.length && !it.gpios.length && !it.pinNums.length) {
 		for (const nome of EXEMPLOS_TOPICOS) sugestoes.push({ rotulo: nome, anexar: nome });
 	}
 
 	return { resultados: [...smart, ...texto], interpretacao, sugestoes, totalRespostas: smart.length };
 }
 
-export const EXEMPLOS_DE_BUSCA = ["flash s3", "pinos usb c6", "deep sleep p4", "gpio0 esp32", "secure boot c3", "psram"];
+export const EXEMPLOS_DE_BUSCA = ["flash s3", "pinos usb c6", "pino 32 esp32-s3", "gpio0 esp32", "secure boot c3", "psram"];

lib/searchI18n.js

@@ -29,6 +29,18 @@ export const BUSCA_I18N = {
 			compDesc: "Comparativo rápido · adicione o chip na busca para detalhar",
 			pinoNo: "{pino} no {serie}",
 			motivoPino: "Pino {pino}",
+			pinoFisico: "Pino físico {n} do {serie}",
+			pinoDesc: "Dados do pino no diagrama",
+			kPino: "Pino",
+			kNome: "Nome",
+			kFuncoes: "Funções",
+			kCategorias: "Categorias",
+			kAviso: "Aviso",
+			pinoInexistente: "O {serie} não tem o pino {n}",
+			pinoInexistenteDesc: "Os pinos vão de 1 a {max} · abre o diagrama",
+			pinoEmCada: "Pino {n} em cada série",
+			pinoEmCadaDesc: "O que há no pino físico {n} de cada chip",
+			chipPino: "Pino {n}",
 		},
 	},
 	en: {
@@ -51,6 +63,18 @@ export const BUSCA_I18N = {
 			compDesc: "Quick comparison · add the chip to your search for details",
 			pinoNo: "{pino} on the {serie}",
 			motivoPino: "Pin {pino}",
+			pinoFisico: "Physical pin {n} on the {serie}",
+			pinoDesc: "Pin data from the diagram",
+			kPino: "Pin",
+			kNome: "Name",
+			kFuncoes: "Functions",
+			kCategorias: "Categories",
+			kAviso: "Warning",
+			pinoInexistente: "The {serie} has no pin {n}",
+			pinoInexistenteDesc: "Pins run from 1 to {max} · opens the diagram",
+			pinoEmCada: "Pin {n} across all series",
+			pinoEmCadaDesc: "What sits on physical pin {n} of each chip",
+			chipPino: "Pin {n}",
 		},
 	},
 	es: {
@@ -73,6 +97,18 @@ export const BUSCA_I18N = {
 			compDesc: "Comparativa rápida · añade el chip a la búsqueda para ver el detalle",
 			pinoNo: "{pino} en el {serie}",
 			motivoPino: "Pin {pino}",
+			pinoFisico: "Pin físico {n} del {serie}",
+			pinoDesc: "Datos del pin en el diagrama",
+			kPino: "Pin",
+			kNome: "Nombre",
+			kFuncoes: "Funciones",
+			kCategorias: "Categorías",
+			kAviso: "Aviso",
+			pinoInexistente: "El {serie} no tiene el pin {n}",
+			pinoInexistenteDesc: "Los pines van del 1 al {max} · abre el diagrama",
+			pinoEmCada: "Pin {n} en cada serie",
+			pinoEmCadaDesc: "Qué hay en el pin físico {n} de cada chip",
+			chipPino: "Pin {n}",
 		},
 	},
 	fr: {
@@ -95,6 +131,18 @@ export const BUSCA_I18N = {
 			compDesc: "Comparatif rapide · ajoutez la puce à la recherche pour détailler",
 			pinoNo: "{pino} sur le {serie}",
 			motivoPino: "Broche {pino}",
+			pinoFisico: "Broche physique {n} du {serie}",
+			pinoDesc: "Données de la broche dans le schéma",
+			kPino: "Broche",
+			kNome: "Nom",
+			kFuncoes: "Fonctions",
+			kCategorias: "Catégories",
+			kAviso: "Avertissement",
+			pinoInexistente: "Le {serie} n'a pas de broche {n}",
+			pinoInexistenteDesc: "Les broches vont de 1 à {max} · ouvre le schéma",
+			pinoEmCada: "Broche {n} dans chaque série",
+			pinoEmCadaDesc: "Ce qui se trouve sur la broche physique {n} de chaque puce",
+			chipPino: "Broche {n}",
 		},
 	},
 	de: {
@@ -117,6 +165,18 @@ export const BUSCA_I18N = {
 			compDesc: "Schnellvergleich · fügen Sie den Chip zur Suche hinzu, um Details zu sehen",
 			pinoNo: "{pino} beim {serie}",
 			motivoPino: "Pin {pino}",
+			pinoFisico: "Physischer Pin {n} des {serie}",
+			pinoDesc: "Pin-Daten aus dem Diagramm",
+			kPino: "Pin",
+			kNome: "Name",
+			kFuncoes: "Funktionen",
+			kCategorias: "Kategorien",
+			kAviso: "Hinweis",
+			pinoInexistente: "Der {serie} hat keinen Pin {n}",
+			pinoInexistenteDesc: "Die Pins reichen von 1 bis {max} · öffnet das Diagramm",
+			pinoEmCada: "Pin {n} in jeder Serie",
+			pinoEmCadaDesc: "Was an physischem Pin {n} jedes Chips liegt",
+			chipPino: "Pin {n}",
 		},
 	},
 	"zh-CN": {
@@ -139,6 +199,18 @@ export const BUSCA_I18N = {
 			compDesc: "快速对比 · 在搜索中加上芯片可查看详情",
 			pinoNo: "{serie} 的 {pino}",
 			motivoPino: "引脚 {pino}",
+			pinoFisico: "{serie} 的物理引脚 {n}",
+			pinoDesc: "图中的引脚数据",
+			kPino: "引脚",
+			kNome: "名称",
+			kFuncoes: "功能",
+			kCategorias: "类别",
+			kAviso: "警告",
+			pinoInexistente: "{serie} 没有引脚 {n}",
+			pinoInexistenteDesc: "引脚编号为 1 到 {max} · 打开引脚图",
+			pinoEmCada: "各系列的引脚 {n}",
+			pinoEmCadaDesc: "各芯片物理引脚 {n} 上的内容",
+			chipPino: "引脚 {n}",
 		},
 	},
 };

scripts/verifica-busca.mjs

@@ -59,5 +59,49 @@ for (const loc of idiomas) {
 		}
 	}
 }
+// Consulta por pino físico: "pino 32 esp32-s3" traz o cartão do pino 32, com nome, funções e avisos.
+const comoDizer = {
+	pt: ["pino 32 esp32-s3", "pino 32", "pino 999 s3"],
+	en: ["pin 32 esp32-s3", "pin 32", "pin 999 s3"],
+	es: ["pin 32 esp32-s3", "pin 32", "pin 999 s3"],
+	fr: ["broche 32 esp32-s3", "broche 32", "broche 999 s3"],
+	de: ["pin 32 esp32-s3", "pin 32", "pin 999 s3"],
+	"zh-CN": ["esp32-s3 32号引脚", "引脚 32", "s3 999号引脚"],
+};
+for (const loc of idiomas) {
+	const res = await fetch(`${base}/api/busca/${loc}`);
+	if (!res.ok) continue;
+	const indice = preparar(await res.json());
+	const [comChip, semChip, inexistente] = comoDizer[loc];
+	const a = buscar(indice, comChip);
+	const cartao = a.resultados.find((r) => r.tipo === "resposta" && r.linhas?.[0]?.v === "32");
+	if (!cartao || !cartao.linhas.some((l) => l.k && l.v) || cartao.linhas.length < 3) {
+		console.log(`FALHOU [${loc}] "${comChip}": sem cartão do pino 32`);
+		falhas++;
+	} else if (!cartao.href.startsWith(`/${loc}/`)) {
+		console.log(`FALHOU [${loc}] "${comChip}": link fora do idioma: ${cartao.href}`);
+		falhas++;
+	}
+	if (!a.interpretacao.pinos?.length) {
+		console.log(`FALHOU [${loc}] "${comChip}": o pino não aparece em "entendi"`);
+		falhas++;
+	}
+	const b = buscar(indice, semChip);
+	const geral = b.resultados.find((r) => r.tipo === "resposta" && (r.linhas?.length ?? 0) >= 8);
+	if (!geral) {
+		console.log(`FALHOU [${loc}] "${semChip}": sem o quadro "pino 32 em cada série"`);
+		falhas++;
+	}
+	const c = buscar(indice, inexistente);
+	if (!c.resultados.some((r) => r.tipo === "pino" && r.titulo.includes("999"))) {
+		console.log(`FALHOU [${loc}] "${inexistente}": sem aviso de pino inexistente`);
+		falhas++;
+	}
+	if (loc !== "pt") {
+		for (const r of [...a.resultados, ...b.resultados, ...c.resultados]) {
+			for (const s of strings(r)) if (SO_PT.test(s)) { console.log(`FALHOU [${loc}]: português em "${s.slice(0, 80)}"`); falhas++; }
+		}
+	}
+}
 if (falhas === 0) console.log(`  ✔ Busca: respostas e links corretos em ${idiomas.join(", ")}.`);
 process.exit(falhas > 0 ? 1 : 0);