cgraphx 1.4.1 → 2.0.0

package/dist/web/pages-detail.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * 知识库文档详情页(spec §3.4 / §5.2 / §8 / §11 #6/#7)。
+ *
+ * 只读 SSR:GET /doc/<ident> → 元数据网格 + 摘要块 + 源文件 markdown 全文
+ * 服务端渲染 + 双向引用导航 + 文档 ID/路径展示;未找到与源文件缺失各自有
+ * 明确状态(spec §8)。
+ *
+ * 数据消费硬约定:只经 markdown 子系统门面(MarkdownQuery / stripFrontmatter /
+ * DocumentNotFoundError),不伸手进内部模块。每请求以基座进程级连接构造
+ * `new MarkdownQuery(db)`(无状态、廉价,只读 SELECT)。
+ *
+ * 转义边界(XSS 契约,spec §3.2):所有元数据字段 / 路径 / 引用标题插值前过
+ * escapeHtml;**仅** markdown-it 输出(renderMarkdownBody)作为可信 HTML 直出。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDetailPage = renderDetailPage;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const markdown_1 = require("../core/markdown");
+const constants_1 = require("./constants");
+const layout_1 = require("./layout");
+const render_utils_1 = require("./render-utils");
+const markdown_2 = require("./markdown");
+// ----- 局部渲染 ------------------------------------------------------------
+/** 文档未找到内容区(spec §8:未找到状态 + 返回列表入口)。 */
+function renderNotFoundContent(ident) {
+    return `
+    <section class="placeholder">
+      <h1>文档未找到</h1>
+      <p>没有与 <code>${(0, render_utils_1.escapeHtml)(ident)}</code> 匹配的文档。</p>
+      <p><a href="/">返回知识库首页</a></p>
+    </section>`;
+}
+/** 列表型元数据值;空数组 → 「—」占位(spec §3.4,不崩)。 */
+function renderListValue(items, opts = {}) {
+    if (items.length === 0)
+        return '<span class="meta__empty">—</span>';
+    return items
+        .map((i) => opts.mono === true
+        ? `<code class="meta__code">${(0, render_utils_1.escapeHtml)(i)}</code>`
+        : `<span class="meta__item">${(0, render_utils_1.escapeHtml)(i)}</span>`)
+        .join(' ');
+}
+/** 时间型元数据值;null → 「—」占位。纯日期不挂 data-local-time(避免 UTC 解析偏移)。 */
+function renderTimeValue(t) {
+    if (t === null)
+        return '<span class="meta__empty">—</span>';
+    const localAttr = /^\d{4}-\d{2}-\d{2}$/.test(t.datetime) ? '' : ' data-local-time';
+    return `<time datetime="${(0, render_utils_1.escapeHtml)(t.datetime)}"${localAttr}>${(0, render_utils_1.escapeHtml)(t.text)}</time>`;
+}
+/** 头部:类型徽标 + 大标题 + alias/领域/状态辅助行(spec §3.4)。 */
+function renderDetailHeader(doc) {
+    const tone = constants_1.TYPE_TONES[doc.documentType];
+    const alias = doc.aliases.length > 0
+        ? `<span class="detail__alias">${(0, render_utils_1.escapeHtml)(doc.aliases.join(' / '))}</span>`
+        : '';
+    const domains = doc.domains.length > 0
+        ? `<span class="detail__domains">${(0, render_utils_1.escapeHtml)(doc.domains.join(' / '))}</span>`
+        : '';
+    return `
+    <header class="detail__head">
+      <div class="tbadge tbadge--${tone}"><b>${(0, render_utils_1.escapeHtml)(constants_1.TYPE_LABELS[doc.documentType])}</b><i>${(0, render_utils_1.escapeHtml)(doc.documentType.toUpperCase())}</i></div>
+      <h1 class="detail__title">${(0, render_utils_1.escapeHtml)(doc.title)}</h1>
+      <div class="detail__aux">
+        ${alias}
+        ${domains}
+        <span class="status status--${doc.status}"><b></b>${(0, render_utils_1.escapeHtml)(constants_1.STATUS_LABELS[doc.status])} ${(0, render_utils_1.escapeHtml)(doc.status)}</span>
+      </div>
+    </header>`;
+}
+/** 文档标识区:文档 ID(等宽)+ 项目相对路径(spec §3.4,便于回 CLI/编辑器定位)。 */
+function renderIdentity(doc) {
+    return `
+    <section class="detail__identity">
+      <div class="detail__seclab">文档标识 <i>IDENT</i></div>
+      <dl class="detail__ids">
+        <dt>文档 ID</dt><dd><code class="detail__docid">${(0, render_utils_1.escapeHtml)(doc.id)}</code></dd>
+        <dt>项目相对路径</dt><dd><code class="detail__path">${(0, render_utils_1.escapeHtml)(doc.path)}</code></dd>
+      </dl>
+    </section>`;
+}
+/** 元数据网格八组(spec §3.4:负责人/领域/创建/更新/概念/标签/相关代码/索引时间)。 */
+function renderMetaGrid(doc) {
+    const cell = (zh, en, body) => `<div class="meta__cell"><div class="meta__lab">${(0, render_utils_1.escapeHtml)(zh)} <i>${(0, render_utils_1.escapeHtml)(en)}</i></div><div class="meta__val">${body}</div></div>`;
+    return `
+    <div class="meta-grid">
+      ${cell('负责人', 'OWNERS', renderListValue(doc.owners))}
+      ${cell('领域', 'DOMAINS', renderListValue(doc.domains))}
+      ${cell('创建时间', 'CREATED', renderTimeValue((0, render_utils_1.docTime)(doc.createdAt)))}
+      ${cell('更新时间', 'UPDATED', renderTimeValue((0, render_utils_1.docTime)(doc.updatedAt)))}
+      ${cell('概念', 'CONCEPTS', renderListValue(doc.concepts))}
+      ${cell('标签', 'TAGS', renderListValue(doc.tags))}
+      ${cell('相关代码', 'RELATED CODE', renderListValue(doc.relatedCode, { mono: true }))}
+      ${cell('索引时间', 'INDEXED', renderTimeValue((0, render_utils_1.epochTime)(doc.indexedAt)))}
+    </div>`;
+}
+/** 摘要块:索引中的 summary_text(spec §3.4;空摘要不渲染)。 */
+function renderSummary(doc) {
+    if (doc.summary.trim() === '')
+        return '';
+    return `
+    <section class="detail__summary">
+      <div class="detail__seclab">摘要 <i>SUMMARY</i></div>
+      <p>${(0, render_utils_1.escapeHtml)(doc.summary)}</p>
+    </section>`;
+}
+/** 源文件缺失/不可读提示(spec §8:转义路径,HTTP 200 下的全文区状态)。 */
+function renderMissingSource(docPath) {
+    return `<div class="detail__missing">源文件缺失或不可读: <code>${(0, render_utils_1.escapeHtml)(docPath)}</code></div>`;
+}
+/**
+ * 读取源文件并渲染全文(spec §5.2 路径边界 / §8 源文件缺失)。
+ *
+ * 数据源 = path.join(projectRoot, doc.path),doc.path **只取自 getDocumentDetail
+ * 返回值**,路由侧不接受任何文件路径参数。纵深防御:path.resolve 后校验仍在
+ * projectRoot 内,否则按源文件缺失处理(绝不越界读取)。readFileSync 抛错
+ * (被删/无权限)→ 缺失提示,详情页其余部分照常渲染,HTTP 200。
+ */
+function renderSourceBody(projectRoot, doc) {
+    const root = path.resolve(projectRoot);
+    const absPath = path.resolve(root, doc.path);
+    // 纵深防御:解析后必须仍在项目根内,否则视为源文件缺失。
+    const withinRoot = absPath === root || absPath.startsWith(root + path.sep);
+    if (!withinRoot) {
+        return renderMissingSource(doc.path);
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(absPath, 'utf-8');
+    }
+    catch {
+        return renderMissingSource(doc.path);
+    }
+    return `<div class="prose">${(0, markdown_2.renderMarkdownBody)((0, markdown_1.stripFrontmatter)(raw))}</div>`;
+}
+/** 引用分区条目:标题 + 项目相对路径(小字),整条为 /doc/<target.id> 链接。 */
+function renderRefList(targets, emptyText) {
+    if (targets.length === 0)
+        return `<p class="refs__empty">${(0, render_utils_1.escapeHtml)(emptyText)}</p>`;
+    const items = targets
+        .map((t) => `
+        <li class="refs__item">
+          <a class="refs__link" href="/doc/${encodeURIComponent(t.id)}">
+            <span class="refs__title">${(0, render_utils_1.escapeHtml)(t.title)}</span>
+            <span class="refs__path">${(0, render_utils_1.escapeHtml)(t.path)}</span>
+          </a>
+        </li>`)
+        .join('');
+    return `<ul class="refs__list">${items}
+      </ul>`;
+}
+/**
+ * 双向引用栏(spec §3.4):出向(本文档 → 其他)与入向(其他 → 本文档)分区。
+ * 引用条目不含类型徽标(避免对每条引用回查类型造成 N+1,已记录的设计偏差)。
+ */
+function renderReferences(refs) {
+    return `
+    <aside class="refs">
+      <div class="refs__group">
+        <div class="refs__lab">引用 →(${refs.outgoing.length})</div>
+        ${renderRefList(refs.outgoing, '无出向引用')}
+      </div>
+      <div class="refs__group">
+        <div class="refs__lab">← 被引用(${refs.incoming.length})</div>
+        ${renderRefList(refs.incoming, '无入向引用')}
+      </div>
+    </aside>`;
+}
+/**
+ * 渲染文档详情页完整 HTML(壳 + 主区)。
+ *
+ * @param db 基座进程级单连接(每请求 new MarkdownQuery(db),只读 SELECT)。
+ * @param projectRoot 项目根(源文件读取基准;源文件路径仅从索引 DB 解析)。
+ * @param ident decodeURIComponent 后的 64 位十六进制 ID 或项目相对路径。
+ */
+function renderDetailPage(db, projectRoot, ident, ctx) {
+    const query = new markdown_1.MarkdownQuery(db);
+    const doc = query.getDocumentDetail(ident);
+    if (doc === null) {
+        return {
+            status: 404,
+            html: (0, layout_1.renderShellPage)({
+                title: '文档未找到',
+                active: 'knowledge',
+                contentHtml: renderNotFoundContent(ident),
+                version: ctx.version,
+                localHost: ctx.localHost,
+            }),
+        };
+    }
+    // 引用视图与详情同一 ident 取(门面硬约定);doc 已存在 ⇒ 正常路径不抛错,
+    // 仍以 try/catch 兜底 DocumentNotFoundError(防御性),其余错误原样上抛由
+    // 基座 500 兜底。
+    let refs;
+    try {
+        refs = query.getReferences(ident);
+    }
+    catch (err) {
+        if (err instanceof markdown_1.DocumentNotFoundError) {
+            return {
+                status: 404,
+                html: (0, layout_1.renderShellPage)({
+                    title: '文档未找到',
+                    active: 'knowledge',
+                    contentHtml: renderNotFoundContent(ident),
+                    version: ctx.version,
+                    localHost: ctx.localHost,
+                }),
+            };
+        }
+        throw err;
+    }
+    const contentHtml = `
+  <div class="detail">
+    <a class="detail__back" href="/">‹ 返回知识库</a>
+    <div class="detail__layout">
+      <div class="detail__main">
+        ${renderDetailHeader(doc)}
+        ${renderIdentity(doc)}
+        ${renderMetaGrid(doc)}
+        ${renderSummary(doc)}
+        <section class="detail__fulltext">
+          <div class="detail__seclab">正文 <i>FULL TEXT</i></div>
+          ${renderSourceBody(projectRoot, doc)}
+        </section>
+      </div>
+      ${renderReferences(refs)}
+    </div>
+  </div>`;
+    return {
+        status: 200,
+        html: (0, layout_1.renderShellPage)({
+            title: doc.title,
+            active: 'knowledge',
+            contentHtml,
+            version: ctx.version,
+            localHost: ctx.localHost,
+        }),
+    };
+}
+//# sourceMappingURL=pages-detail.js.map

package/dist/web/pages-detail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages-detail.js","sourceRoot":"","sources":["../../src/web/pages-detail.ts"],"names":[],"mappings":"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"}

package/dist/web/pages-overview.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 知识库总览页(spec §3.3):URL 查询参数模型 + 视图模型组装 + 页面入口。
+ *
+ * 形态(plan index 第 4 节拍板):服务端渲染 HTML,筛选/排序/分页全部走
+ * URL 查询参数(可收藏、刷新不丢状态)。URL ↔ 查询模型的解析/序列化与
+ * pill/分页的多值参数增删均为纯函数(单测覆盖,见 knowledge-overview
+ * 测试「overview url model」组)——多值参数保留与移除是最易出 bug 处。
+ *
+ * 只经门面消费 markdown 子系统(门面硬约定):每请求以基座进程级连接
+ * 构造 `new MarkdownQuery(db)`(无状态、廉价),不持有额外 DB 连接。
+ */
+import type { DocumentType, DocumentStatus } from '../core/markdown';
+import type { SqliteDatabase } from '../core/db';
+/** 总览页 URL 状态模型(经规范化:非法枚举已剔除、page 已守卫)。 */
+export interface OverviewQuery {
+    /** 关键词(单值);空串/空白 → undefined。 */
+    q?: string;
+    types: DocumentType[];
+    statuses: DocumentStatus[];
+    domains: string[];
+    concepts: string[];
+    /** updated(默认,映射 findPaged 'recency')| title。 */
+    sort: 'updated' | 'title';
+    /** ≥1 整数;非法输入按 1。 */
+    page: number;
+}
+/** pill / 增删辅助可作用的维度。 */
+export type PillDimension = 'q' | 'types' | 'statuses' | 'domains' | 'concepts';
+/**
+ * URLSearchParams → 规范化查询模型(plan index §7.5 逐字):
+ * type/status 非法枚举值忽略(从激活集剔除,不报错);page 非法按 1;
+ * q 空白按未传;各多值维度去重。
+ */
+export declare function parseOverviewQuery(params: URLSearchParams): OverviewQuery;
+/**
+ * 查询模型 → 规范化 URL。参数顺序固定(q → type* → status* → domain* →
+ * concept* → sort → page);缺省值不出现(sort=updated / page=1 不入 URL)。
+ * URLSearchParams 负责百分号编码(中文概念/领域名自动编码)。
+ */
+export declare function buildOverviewUrl(query: OverviewQuery): string;
+/** 移除一个激活值(其余参数保留;移除使结果集变宽,page 保持)。 */
+export declare function withoutValue(query: OverviewQuery, dim: PillDimension, value: string): OverviewQuery;
+/**
+ * 追加一个概念筛选(保留其余筛选参数;已存在 → 原样返回)。
+ * 追加使结果集变窄,page 重置为 1(避免落在超界页)。
+ */
+export declare function withConceptAdded(query: OverviewQuery, name: string): OverviewQuery;
+export declare function withSort(query: OverviewQuery, sort: 'updated' | 'title'): OverviewQuery;
+export declare function withPage(query: OverviewQuery, page: number): OverviewQuery;
+/**
+ * 渲染知识库总览页完整 HTML(壳 + 主区)。
+ *
+ * @param db 基座进程级单连接(每请求 new MarkdownQuery(db),只读 SELECT)。
+ * @param params 请求 URL 的查询参数。
+ */
+export declare function renderOverviewPage(db: SqliteDatabase, params: URLSearchParams, ctx: {
+    version: string;
+    localHost: string;
+}): string;
+//# sourceMappingURL=pages-overview.d.ts.map

package/dist/web/pages-overview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages-overview.d.ts","sourceRoot":"","sources":["../../src/web/pages-overview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAc,MAAM,kBAAkB,CAAC;AACjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAuBjD,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iDAAiD;IACjD,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IAC1B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yBAAyB;AACzB,MAAM,MAAM,aAAa,GAAG,GAAG,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAOhF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAuBzE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAW7D;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAanG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAGlF;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,aAAa,CAEvF;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAE1E;AAoMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC1C,MAAM,CAUR"}

package/dist/web/pages-overview.js

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * 知识库总览页(spec §3.3):URL 查询参数模型 + 视图模型组装 + 页面入口。
+ *
+ * 形态(plan index 第 4 节拍板):服务端渲染 HTML,筛选/排序/分页全部走
+ * URL 查询参数(可收藏、刷新不丢状态)。URL ↔ 查询模型的解析/序列化与
+ * pill/分页的多值参数增删均为纯函数(单测覆盖,见 knowledge-overview
+ * 测试「overview url model」组)——多值参数保留与移除是最易出 bug 处。
+ *
+ * 只经门面消费 markdown 子系统(门面硬约定):每请求以基座进程级连接
+ * 构造 `new MarkdownQuery(db)`(无状态、廉价),不持有额外 DB 连接。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOverviewQuery = parseOverviewQuery;
+exports.buildOverviewUrl = buildOverviewUrl;
+exports.withoutValue = withoutValue;
+exports.withConceptAdded = withConceptAdded;
+exports.withSort = withSort;
+exports.withPage = withPage;
+exports.renderOverviewPage = renderOverviewPage;
+const markdown_1 = require("../core/markdown");
+const constants_1 = require("./constants");
+const layout_1 = require("./layout");
+const overview_templates_1 = require("./overview-templates");
+const render_utils_1 = require("./render-utils");
+/** 保序去重。 */
+function dedupe(list) {
+    return [...new Set(list)];
+}
+/**
+ * URLSearchParams → 规范化查询模型(plan index §7.5 逐字):
+ * type/status 非法枚举值忽略(从激活集剔除,不报错);page 非法按 1;
+ * q 空白按未传;各多值维度去重。
+ */
+function parseOverviewQuery(params) {
+    const qRaw = params.get('q');
+    const q = qRaw !== null && qRaw.trim() !== '' ? qRaw.trim() : undefined;
+    const types = dedupe(params.getAll('type')).filter((t) => markdown_1.DOCUMENT_TYPES.includes(t));
+    const statuses = dedupe(params.getAll('status')).filter((s) => markdown_1.DOCUMENT_STATUSES.includes(s));
+    const domains = dedupe(params.getAll('domain').map((d) => d.trim())).filter((d) => d !== '');
+    const concepts = dedupe(params.getAll('concept').map((c) => c.trim())).filter((c) => c !== '');
+    const sort = params.get('sort') === 'title' ? 'title' : 'updated';
+    const pageRaw = params.get('page');
+    let page = 1;
+    if (pageRaw !== null && /^\d+$/.test(pageRaw)) {
+        const n = Number(pageRaw);
+        if (n >= 1)
+            page = n;
+    }
+    return { q, types, statuses, domains, concepts, sort, page };
+}
+/**
+ * 查询模型 → 规范化 URL。参数顺序固定(q → type* → status* → domain* →
+ * concept* → sort → page);缺省值不出现(sort=updated / page=1 不入 URL)。
+ * URLSearchParams 负责百分号编码(中文概念/领域名自动编码)。
+ */
+function buildOverviewUrl(query) {
+    const p = new URLSearchParams();
+    if (query.q !== undefined)
+        p.append('q', query.q);
+    for (const t of query.types)
+        p.append('type', t);
+    for (const s of query.statuses)
+        p.append('status', s);
+    for (const d of query.domains)
+        p.append('domain', d);
+    for (const c of query.concepts)
+        p.append('concept', c);
+    if (query.sort === 'title')
+        p.append('sort', 'title');
+    if (query.page > 1)
+        p.append('page', String(query.page));
+    const s = p.toString();
+    return s === '' ? '/' : `/?${s}`;
+}
+/** 移除一个激活值(其余参数保留;移除使结果集变宽,page 保持)。 */
+function withoutValue(query, dim, value) {
+    switch (dim) {
+        case 'q':
+            return { ...query, q: undefined };
+        case 'types':
+            return { ...query, types: query.types.filter((v) => v !== value) };
+        case 'statuses':
+            return { ...query, statuses: query.statuses.filter((v) => v !== value) };
+        case 'domains':
+            return { ...query, domains: query.domains.filter((v) => v !== value) };
+        case 'concepts':
+            return { ...query, concepts: query.concepts.filter((v) => v !== value) };
+    }
+}
+/**
+ * 追加一个概念筛选(保留其余筛选参数;已存在 → 原样返回)。
+ * 追加使结果集变窄,page 重置为 1(避免落在超界页)。
+ */
+function withConceptAdded(query, name) {
+    if (query.concepts.includes(name))
+        return query;
+    return { ...query, concepts: [...query.concepts, name], page: 1 };
+}
+function withSort(query, sort) {
+    return { ...query, sort };
+}
+function withPage(query, page) {
+    return { ...query, page };
+}
+/** 芯片「添加」链接辅助:保序追加(已存在则原样),page 重置为 1。 */
+function added(list, value) {
+    return list.includes(value) ? list : [...list, value];
+}
+/** 是否有任何激活筛选(计数徽章 / 空态②判定用)。 */
+function hasActiveFilters(query) {
+    return (query.q !== undefined ||
+        query.types.length > 0 ||
+        query.statuses.length > 0 ||
+        query.domains.length > 0 ||
+        query.concepts.length > 0);
+}
+// ----- 视图模型组装 --------------------------------------------------------
+/** 组装总览页全量视图模型。所有 href 在此计算,模板侧只做字符串渲染。 */
+function assembleOverviewModel(db, query) {
+    const queryApi = new markdown_1.MarkdownQuery(db);
+    const stats = queryApi.getStats();
+    // 查询模型 → FindFilter(复数字段,维度内 OR、维度间 AND;空数组不传)。
+    const filter = {};
+    if (query.q !== undefined)
+        filter.q = query.q;
+    if (query.types.length > 0)
+        filter.documentTypes = query.types;
+    if (query.statuses.length > 0)
+        filter.statuses = query.statuses;
+    if (query.domains.length > 0)
+        filter.domains = query.domains;
+    if (query.concepts.length > 0)
+        filter.concepts = query.concepts;
+    // URL sort=updated → 显式 recency(有 q 时亦不走相关度,plan index §7.5)。
+    const sort = query.sort === 'title' ? 'title' : 'recency';
+    let result = queryApi.findPaged(filter, {
+        offset: (query.page - 1) * constants_1.PAGE_SIZE,
+        limit: constants_1.PAGE_SIZE,
+        sort,
+    });
+    // 超界页:渲染末页 + 提示(spec §11 #10;仅超界时多一次查询)。
+    const totalPages = result.total === 0 ? 1 : Math.ceil(result.total / constants_1.PAGE_SIZE);
+    let effectivePage = query.page;
+    let notice = null;
+    if (result.total > 0 && query.page > totalPages) {
+        effectivePage = totalPages;
+        notice = `第 ${query.page} 页不存在,已显示第 ${totalPages} 页(共 ${totalPages} 页)`;
+        result = queryApi.findPaged(filter, {
+            offset: (effectivePage - 1) * constants_1.PAGE_SIZE,
+            limit: constants_1.PAGE_SIZE,
+            sort,
+        });
+    }
+    // ---- 筛选面板(计数为全库口径,不随筛选联动,plan index 第 4 节)----
+    const typeChips = markdown_1.DOCUMENT_TYPES.map((t) => ({
+        type: t,
+        count: stats.byType[t],
+    }))
+        .sort((a, b) => b.count - a.count || (a.type < b.type ? -1 : a.type > b.type ? 1 : 0))
+        .map(({ type, count }) => {
+        const active = query.types.includes(type);
+        const href = active
+            ? buildOverviewUrl(withoutValue(query, 'types', type))
+            : buildOverviewUrl({ ...query, types: added(query.types, type), page: 1 });
+        return { label: constants_1.TYPE_LABELS[type], raw: type, count, active, tone: constants_1.TYPE_TONES[type], href };
+    });
+    const statusChips = markdown_1.DOCUMENT_STATUSES.map((s) => {
+        const active = query.statuses.includes(s);
+        const href = active
+            ? buildOverviewUrl(withoutValue(query, 'statuses', s))
+            : buildOverviewUrl({ ...query, statuses: added(query.statuses, s), page: 1 });
+        return { label: constants_1.STATUS_LABELS[s], raw: s, count: stats.byStatus[s], active, href };
+    });
+    const domainChips = queryApi.listDomains().map((d) => {
+        const active = query.domains.includes(d.name);
+        const href = active
+            ? buildOverviewUrl(withoutValue(query, 'domains', d.name))
+            : buildOverviewUrl({ ...query, domains: added(query.domains, d.name), page: 1 });
+        return { label: d.name, raw: d.name, count: d.documentCount, active, href };
+    });
+    // 概念行:篇数占比条宽度 = documentCount / 全库文档数(纯 CSS 宽度)。
+    const conceptRow = (name, count) => {
+        const active = query.concepts.includes(name);
+        const percent = stats.documentCount > 0 ? Math.round((count / stats.documentCount) * 100) : 0;
+        const href = active
+            ? buildOverviewUrl(withoutValue(query, 'concepts', name))
+            : buildOverviewUrl(withConceptAdded(query, name));
+        return { name, count, percent, active, href };
+    };
+    const allConcepts = queryApi.listConcepts();
+    const topConcepts = allConcepts.slice(0, constants_1.CONCEPT_PANEL_TOP).map((c) => conceptRow(c.name, c.documentCount));
+    const moreConcepts = allConcepts.slice(constants_1.CONCEPT_PANEL_TOP).map((c) => conceptRow(c.name, c.documentCount));
+    // ---- 激活筛选 pill(每激活值一个;≥2 追加「清除全部」)----
+    const pills = [];
+    if (query.q !== undefined) {
+        pills.push({ dimension: '关键词', value: query.q, removeHref: buildOverviewUrl(withoutValue(query, 'q', query.q)) });
+    }
+    for (const t of query.types) {
+        pills.push({ dimension: '类型', value: constants_1.TYPE_LABELS[t], removeHref: buildOverviewUrl(withoutValue(query, 'types', t)) });
+    }
+    for (const s of query.statuses) {
+        pills.push({ dimension: '状态', value: constants_1.STATUS_LABELS[s], removeHref: buildOverviewUrl(withoutValue(query, 'statuses', s)) });
+    }
+    for (const d of query.domains) {
+        pills.push({ dimension: '领域', value: d, removeHref: buildOverviewUrl(withoutValue(query, 'domains', d)) });
+    }
+    for (const c of query.concepts) {
+        pills.push({ dimension: '概念', value: c, removeHref: buildOverviewUrl(withoutValue(query, 'concepts', c)) });
+    }
+    // ---- 文档卡(referencesCount/owners/aliases 由 findPaged hydrate 填出,
+    //      页面侧不逐卡查询,禁 N+1)----
+    const cards = result.items.map((d) => {
+        const alias = d.aliases?.[0];
+        const conceptTags = d.concepts.map((name) => ({
+            name,
+            active: query.concepts.includes(name),
+            href: buildOverviewUrl(withConceptAdded(query, name)),
+        }));
+        return {
+            detailHref: `/doc/${encodeURIComponent(d.id)}`,
+            tone: constants_1.TYPE_TONES[d.documentType],
+            typeLabel: constants_1.TYPE_LABELS[d.documentType],
+            typeRaw: d.documentType,
+            title: d.title,
+            alias: alias ?? null,
+            summary: d.summary,
+            conceptTags,
+            ownersText: d.owners !== undefined && d.owners.length > 0 ? d.owners.join(' / ') : null,
+            status: d.status,
+            statusLabel: constants_1.STATUS_LABELS[d.status],
+            statusRaw: d.status,
+            domainsText: d.domains.length > 0 ? d.domains.join(' / ') : null,
+            referencesCount: d.referencesCount ?? 0,
+            updated: (0, render_utils_1.docTime)(d.updatedAt),
+        };
+    });
+    // ---- 空状态(spec §8 两态,文案严格区分)----
+    const empty = stats.documentCount === 0 ? 'kb-empty' : result.total === 0 ? 'no-match' : 'none';
+    const active = hasActiveFilters(query);
+    const countBadge = active ? `${result.total} / ${stats.documentCount}` : `${stats.documentCount} 篇`;
+    const searchHidden = [];
+    for (const t of query.types)
+        searchHidden.push({ name: 'type', value: t });
+    for (const s of query.statuses)
+        searchHidden.push({ name: 'status', value: s });
+    for (const d of query.domains)
+        searchHidden.push({ name: 'domain', value: d });
+    for (const c of query.concepts)
+        searchHidden.push({ name: 'concept', value: c });
+    if (query.sort === 'title')
+        searchHidden.push({ name: 'sort', value: 'title' });
+    return {
+        stats: {
+            documentCount: stats.documentCount,
+            conceptCount: stats.conceptCount,
+            domainCount: stats.domainCount,
+            tagCount: stats.tagCount,
+            latestIndexed: stats.latestIndexedAt === null ? null : (0, render_utils_1.epochTime)(stats.latestIndexedAt),
+        },
+        search: { q: query.q ?? '', hiddenInputs: searchHidden },
+        typeChips,
+        statusChips,
+        domainChips,
+        topConcepts,
+        moreConcepts,
+        conceptTotal: allConcepts.length,
+        countBadge,
+        sortLinks: [
+            { label: '最近更新', active: query.sort === 'updated', href: buildOverviewUrl(withSort(query, 'updated')) },
+            { label: '名称', active: query.sort === 'title', href: buildOverviewUrl(withSort(query, 'title')) },
+        ],
+        pills,
+        clearAllVisible: pills.length >= 2,
+        cards,
+        empty,
+        pager: {
+            visible: result.total > 0,
+            info: `第 ${effectivePage} / ${totalPages} 页 · 共 ${result.total} 篇`,
+            prevHref: effectivePage > 1 ? buildOverviewUrl(withPage(query, effectivePage - 1)) : null,
+            nextHref: effectivePage < totalPages ? buildOverviewUrl(withPage(query, effectivePage + 1)) : null,
+            notice,
+        },
+    };
+}
+// ----- 页面入口 ------------------------------------------------------------
+/**
+ * 渲染知识库总览页完整 HTML(壳 + 主区)。
+ *
+ * @param db 基座进程级单连接(每请求 new MarkdownQuery(db),只读 SELECT)。
+ * @param params 请求 URL 的查询参数。
+ */
+function renderOverviewPage(db, params, ctx) {
+    const query = parseOverviewQuery(params);
+    const model = assembleOverviewModel(db, query);
+    return (0, layout_1.renderShellPage)({
+        title: '知识库',
+        active: 'knowledge',
+        contentHtml: (0, overview_templates_1.renderOverviewContent)(model),
+        version: ctx.version,
+        localHost: ctx.localHost,
+    });
+}
+//# sourceMappingURL=pages-overview.js.map