@godcreator/word-report 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,6 @@
 
 文档站平台、按功能划分的功能包，以及两个 gwb 工作台插件。任何站点都是「fumadocs 官方 React Router 模板 + 挑选的功能包」：
 平台包 `@godcreator/god-docsite` 带唯一的站点模板与建站器，功能包各自经 fumadocs 与 React Router 原生的扩展点接入站点。
-仓正在重构，设计未定，以代码和 `AGENTS.md` 为准。
 
 | 包（`packages/`） | 做什么 |
 | --- | --- |
@@ -46,7 +45,7 @@ pnpm doc:render                                # 只重新生成生成物
 
 ## 文档在哪
 
-`docs-site/` 是全仓唯一的文档站：总览、fumadocs 原理、写页面、Gitea 与 NAS、维护。轨迹卡在 `docs-site/trajectory/`。
+`docs-site/` 是全仓唯一的文档站：总览、建站与写页面、包（一个包一页）、插件、Gitea 与 NAS、维护、背景（fumadocs 原理）。轨迹卡在 `docs-site/trajectory/`。
 随插件发布的说明书正本在 `docs-site/content/docs/outputs/skills/`，生成到 `plugins/docsite/skills/` 与 `plugins/collab/skills/`。
 
 **这份 README 与仓根 `CLAUDE.md` 是生成物**（正本在 `docs-site/content/docs/outputs/`），`AGENTS.md` 手写；改 mdx 正本再在 `docs-site/` 里 `pnpm doc:render`。
@@ -59,8 +58,8 @@ pnpm build          # 按依赖序构建全部包、两个插件与各站
 pnpm check          # 逐个包跑 check（typecheck、快的一级测试，有 lint 的再 lint），一分钟左右
 pnpm test:slow      # 慢的一级测试（各包的 *.slow.test.ts：真建站、大量调 git 的），只在显式要求时跑，近三分钟
 pnpm test:deps      # 包之间的依赖方向、包内分层、模块之间不许有环（规则在 tests/dependency-rules.cjs，要先 pnpm build）
-pnpm verify         # 最终交付之前（推送、交给人验收、发版前）：build → check → test:slow → test:deps → test:scaffold → test:e2e
-pnpm test:pack      # 发版前再跑：把包打成 tarball 装进测试站的副本，跑同样的端到端检查
+pnpm verify         # 全量：build → check → test:slow → test:deps → test:scaffold → test:e2e；只在升共用依赖时跑，平时看改到了什么只跑相关的几项（见 AGENTS.md）
+pnpm test:pack      # 把包打成 tarball 装进测试站的副本，跑同样的端到端检查；改了包的 exports、files、依赖时跑
 
 cd docs-site
 pnpm doc

package/dist/{page-data-UaiHPCZA.d.mts → page-data-DIsywo6U.d.mts}

@@ -1,4 +1,5 @@
 import { r as AssemblyResult } from "./types-BYcLlSjZ.mjs";
+import { CommentsAccess, PageThreadSummary } from "@godcreator/comments/site";
 //#region src/site/page-data.d.ts
 /** 报告列表里的一行：报告读不对时 problem 是原话，标题退回报告 id */
 type ReportSummary = {
@@ -24,16 +25,22 @@ type ReportTocItem = {
   url: string;
   depth: number;
 };
+/** 报告页上的评论：归属这一页的评论串，以及本机身份能不能写 */
+type ReportPageComments = {
+  threads: PageThreadSummary[];
+  access: CommentsAccess;
+};
 type ReportPageData = {
   siteName: string;
   hrefBase: string;
   reportId: string;
   report: AssemblyResult;
   toc: ReportTocItem[];
+  comments: ReportPageComments;
 };
 /** 报告页地址 */
 declare const reportHrefOf: (hrefBase: string, reportId: string) => string;
 /** 报告里一张图的地址：组装后图的路径是 assets/<文档 id>/<文件名>，挂在报告页地址下面 */
 declare const reportAssetHrefOf: (hrefBase: string, reportId: string, compiledPath: string) => string;
 //#endregion
-export { reportAssetHrefOf as a, ReportTocItem as i, ReportPageData as n, reportHrefOf as o, ReportSummary as r, ReportListData as t };
+export { ReportTocItem as a, ReportSummary as i, ReportPageComments as n, reportAssetHrefOf as o, ReportPageData as r, reportHrefOf as s, ReportListData as t };

package/dist/page-data-DLPoVgXy.mjs

@@ -0,0 +1,7 @@
+//#region src/site/page-data.ts
+/** 报告页地址 */
+const reportHrefOf = (hrefBase, reportId) => `${hrefBase}/${reportId}`;
+/** 报告里一张图的地址：组装后图的路径是 assets/<文档 id>/<文件名>，挂在报告页地址下面 */
+const reportAssetHrefOf = (hrefBase, reportId, compiledPath) => `${reportHrefOf(hrefBase, reportId)}/${compiledPath}`;
+//#endregion
+export { reportHrefOf as n, reportAssetHrefOf as t };

package/dist/site-server.d.mts

@@ -1,10 +1,14 @@
-import { i as ReportTocItem, n as ReportPageData, r as ReportSummary, t as ReportListData } from "./page-data-UaiHPCZA.mjs";
+import { a as ReportTocItem, i as ReportSummary, n as ReportPageComments, r as ReportPageData, t as ReportListData } from "./page-data-DIsywo6U.mjs";
 //#region src/site/loaders.server.d.ts
-/** 报告功能的站点信息：站点目录（报告在它的 reports/ 下）、站名、报告页的地址前缀 */
+/**
+ * 报告功能的站点信息：站点目录（报告在它的 reports/ 下）、站名、报告页的地址前缀，
+ * 以及按评论归属键取一页评论的函数（报告页的归属键是它的地址，如 /reports/sample）
+ */
 type WordReportSite = {
   siteDir: string;
   siteName: string;
   hrefBase: string;
+  pageComments: (page: string) => ReportPageComments;
 };
 /** loader 用到的路由参数：报告页是 :report，图片再加 * */
 type ReportRouteArgs = {
@@ -17,4 +21,4 @@ declare function reportPageLoader({ params }: ReportRouteArgs, site: WordReportS
 /** 报告里的一张图：地址是组装后的路径 assets/<文档 id>/<文件名>，只给这份报告用到的图 */
 declare function reportAssetLoader({ params }: ReportRouteArgs, site: WordReportSite): Promise<Response>;
 //#endregion
-export { type ReportListData, type ReportPageData, ReportRouteArgs, type ReportSummary, type ReportTocItem, WordReportSite, reportAssetLoader, reportListLoader, reportPageLoader };
+export { type ReportListData, type ReportPageComments, type ReportPageData, ReportRouteArgs, type ReportSummary, type ReportTocItem, WordReportSite, reportAssetLoader, reportListLoader, reportPageLoader };

package/dist/site-server.mjs

@@ -1,5 +1,6 @@
 import { t as assembleDocument } from "./assemble-Czu-J7tB.mjs";
 import { i as reportIdsOf, n as readReportFiles, r as reportEntryOf, t as REPORT_ID_PATTERN } from "./report-files-DwLdh0QQ.mjs";
+import { n as reportHrefOf } from "./page-data-DLPoVgXy.mjs";
 import path from "node:path";
 import { createReadStream } from "node:fs";
 import { Readable } from "node:stream";
@@ -78,7 +79,8 @@ async function reportPageLoader({ params }, site) {
 		hrefBase: site.hrefBase,
 		reportId,
 		report: result,
-		toc: tocOf(result)
+		toc: tocOf(result),
+		comments: site.pageComments(reportHrefOf(site.hrefBase, reportId))
 	};
 }
 const imageContentTypes = {

package/dist/site.d.mts

@@ -1,8 +1,17 @@
 import { g as ReportDocument, r as AssemblyResult } from "./types-BYcLlSjZ.mjs";
-import { a as reportAssetHrefOf, i as ReportTocItem, n as ReportPageData, o as reportHrefOf, r as ReportSummary, t as ReportListData } from "./page-data-UaiHPCZA.mjs";
+import { a as ReportTocItem, i as ReportSummary, n as ReportPageComments, o as reportAssetHrefOf, r as ReportPageData, s as reportHrefOf, t as ReportListData } from "./page-data-DIsywo6U.mjs";
+import { CommentAvatar, CommentBodyComponent } from "@godcreator/comments/site";
 //#region src/site/report-pages.d.ts
 declare function ReportListPage(): import("react").JSX.Element;
-declare function ReportDocumentPage(): import("react").JSX.Element;
+interface ReportDocumentPageProps {
+  /** 评论表单提交到的地址：站点的评论写入路由（comments 功能的 /comments） */
+  commentAction: string;
+  /** 站点的评论正文组件与头像组件（站点 app/lib/content 里的 CommentBody、commentAvatar） */
+  CommentBody: CommentBodyComponent;
+  AvatarComponent?: CommentAvatar;
+}
+/** 报告页：正文是评论范围，右下角是本页评论；评论归属键是报告页的地址 */
+declare function ReportDocumentPage({ commentAction, CommentBody, AvatarComponent }: ReportDocumentPageProps): import("react").JSX.Element;
 //#endregion
 //#region src/site/report-view.d.ts
 type AssetUrl = (sourcePath: string, compiledPath: string) => string;
@@ -29,4 +38,4 @@ declare function reportMeta(input: ReportDocument | AssemblyResult): {
   markdown: string;
 };
 //#endregion
-export { type AssetUrl, ReportDocumentPage, type ReportListData, ReportListPage, ReportPage, type ReportPageData, type ReportPageProps, type ReportSummary, type ReportTocItem, ReportView, type ReportViewProps, reportAssetHrefOf, reportHrefOf, reportMeta };
+export { type AssetUrl, ReportDocumentPage, type ReportDocumentPageProps, type ReportListData, ReportListPage, ReportPage, type ReportPageComments, type ReportPageData, type ReportPageProps, type ReportSummary, type ReportTocItem, ReportView, type ReportViewProps, reportAssetHrefOf, reportHrefOf, reportMeta };

package/dist/site.mjs

@@ -1,15 +1,11 @@
 import { t as assembleDocument } from "./assemble-Czu-J7tB.mjs";
+import { n as reportHrefOf, t as reportAssetHrefOf } from "./page-data-DLPoVgXy.mjs";
 import { Link, useLoaderData } from "react-router";
 import { DocsBody, DocsPage, DocsTitle } from "@fumadocs/base-ui/layouts/docs/page";
+import { CommentsDock, commentScopeProps } from "@godcreator/comments/site";
 import { Fragment } from "react";
 import katex from "katex";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
-//#region src/site/page-data.ts
-/** 报告页地址 */
-const reportHrefOf = (hrefBase, reportId) => `${hrefBase}/${reportId}`;
-/** 报告里一张图的地址：组装后图的路径是 assets/<文档 id>/<文件名>，挂在报告页地址下面 */
-const reportAssetHrefOf = (hrefBase, reportId, compiledPath) => `${reportHrefOf(hrefBase, reportId)}/${compiledPath}`;
-//#endregion
 //#region src/site/report-view.tsx
 function RenderError({ children }) {
 	return /* @__PURE__ */ jsx("div", {
@@ -340,15 +336,16 @@ function ReportListPage() {
 		}) })
 	] });
 }
-function ReportDocumentPage() {
-	const { report, toc, reportId, siteName, hrefBase } = useLoaderData();
+/** 报告页：正文是评论范围，右下角是本页评论；评论归属键是报告页的地址 */
+function ReportDocumentPage({ commentAction, CommentBody, AvatarComponent }) {
+	const { report, toc, reportId, siteName, hrefBase, comments } = useLoaderData();
 	const { metadata } = report.document;
 	const metaLine = [
 		metadata.revision,
 		metadata.date,
 		metadata.authors?.join("、")
 	].filter((part) => part !== void 0 && part !== "");
-	return /* @__PURE__ */ jsxs(DocsPage, {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs(DocsPage, {
 		toc,
 		children: [
 			/* @__PURE__ */ jsx("title", { children: `${metadata.title} · ${siteName}` }),
@@ -362,12 +359,22 @@ function ReportDocumentPage() {
 				to: hrefBase,
 				children: "← 全部报告"
 			}),
-			/* @__PURE__ */ jsx(DocsBody, { children: /* @__PURE__ */ jsx(ReportView, {
-				report,
-				assetUrl: (_source, compiledPath) => reportAssetHrefOf(hrefBase, reportId, compiledPath)
-			}) })
+			/* @__PURE__ */ jsx(DocsBody, {
+				...commentScopeProps,
+				children: /* @__PURE__ */ jsx(ReportView, {
+					report,
+					assetUrl: (_source, compiledPath) => reportAssetHrefOf(hrefBase, reportId, compiledPath)
+				})
+			})
 		]
-	});
+	}), /* @__PURE__ */ jsx(CommentsDock, {
+		pagePath: reportHrefOf(hrefBase, reportId),
+		action: commentAction,
+		threads: comments.threads,
+		access: comments.access,
+		BodyComponent: CommentBody,
+		...AvatarComponent !== void 0 ? { AvatarComponent } : {}
+	})] });
 }
 //#endregion
 //#region src/site/report-meta.ts

package/engine/README.md

@@ -13,16 +13,16 @@
 .\.venv\Scripts\python.exe -m unittest discover -s tests -v
 ```
 
-## 报告包的数据入口
+## word-report 交给引擎的数据
 
-网站只用于阅读和评论。`@godcreator/docsite-reports` 的 `report-docx` CLI 与 `./export` API 先把分章内容编译成完整 `format: docreport` / `schemaVersion: 1` 文档与 `assets/`，交给以下入口。它们不依赖 gwb。`--data-only` 必须传递；这个模式不导入快照目录中的 `report.py`。未展开的文档引用不会通过正式 Schema。
+网站只用于阅读和评论。`@godcreator/word-report` 的命令行 `report-docx` 与 `./node` 出口的 `reportExport` 先把分章内容编译成完整 `format: docreport` / `schemaVersion: 1` 文档与 `assets/`，交给以下入口。它们不依赖 gwb。`--data-only` 必须传递；这个模式不导入快照目录中的 `report.py`。未展开的文档引用不会通过正式 Schema。
 
 ```powershell
 .\.venv\Scripts\python.exe -m docreport validate <快照目录> --data-only
 .\.venv\Scripts\python.exe -m docreport build <快照目录> --data-only --out out\<新的运行目录>
 ```
 
-需要版式数据时，可加 `--layout <layout.json>`，内容为已有 `validate_layout` 支持的节点 ID 字典：段落样式、图片宽度、表格列宽与行高、顶层章节起页与方向。默认采用 `templates/project-report.dotx`。报告包的 CLI/API 不接受任意 Python 布局程序。
+需要版式数据时，可加 `--layout <layout.json>`，内容为已有 `validate_layout` 支持的节点 ID 字典：段落样式、图片宽度、表格列宽与行高、顶层章节起页与方向。默认采用 `templates/project-report.dotx`。word-report 的命令行与 `reportExport` 不接受任意 Python 布局程序。
 
 已有 demo 保留其受信任的 `report.py` 与原入口，用于原有版式和专属验收回归：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godcreator/word-report",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": {
     "name": "godcreator"
   },
@@ -42,6 +42,7 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@godcreator/comments": "^0.1.3",
     "sharp": "^0.35.5"
   },
   "peerDependencies": {

package/template/report.tsx

@@ -1,10 +1,12 @@
 import type { Route } from './+types/report'
 import { ReportDocumentPage } from '@godcreator/word-report/site'
 import { reportPageLoader } from '@godcreator/word-report/site/server'
+import { commentAvatar, CommentBody } from '@/lib/content'
 import { wordReportSite } from './site.server'
 
 export const loader = (args: Route.LoaderArgs) => reportPageLoader(args, wordReportSite())
 
+/** 评论写进站点的评论写入路由 /comments（comments 功能），和内容页一样 */
 export default function Report() {
-  return <ReportDocumentPage />
+  return <ReportDocumentPage commentAction="/comments" CommentBody={CommentBody} AvatarComponent={commentAvatar} />
 }

package/template/routes.ts

@@ -2,7 +2,7 @@ import { relative, type RouteConfig } from '@react-router/dev/routes'
 
 const { route } = relative(import.meta.dirname)
 
-// 地址与 site.server.ts 的 reportHrefBase 一致；参数名 report、* 是 reportPageLoader、reportAssetLoader 读的
+// 地址与 href.ts 的 reportHrefBase 一致；参数名 report、* 是 reportPageLoader、reportAssetLoader 读的
 export default [
   route('reports', './list.tsx'),
   route('reports/:report', './report.tsx'),

package/template/site.server.ts

@@ -1,9 +1,19 @@
+import { commentsAccessOf } from '@godcreator/comments/site'
+import { pageThreadsOf } from '@godcreator/comments/site/server'
 import type { WordReportSite } from '@godcreator/word-report/site/server'
 import { site } from '@/lib/site.server'
 import { reportHrefBase } from './href'
 
-/** 报告功能的站点信息，每次请求现组装：报告在站点根下的 reports/，站名取页面树根（content/meta.json 的 title） */
+/** 报告功能的站点信息，每次请求现组装：报告在站点根下的 reports/，站名取页面树根（content/meta.json 的 title），评论取站点的评论集合 */
 export function wordReportSite(): WordReportSite {
   const name = site.source.getPageTree().name
-  return { siteDir: site.dir, siteName: typeof name === 'string' ? name : '', hrefBase: reportHrefBase }
+  return {
+    siteDir: site.dir,
+    siteName: typeof name === 'string' ? name : '',
+    hrefBase: reportHrefBase,
+    pageComments: (page) => ({
+      threads: pageThreadsOf({ entries: site.commentEntries, people: site.people(), page }),
+      access: commentsAccessOf(site.identity()),
+    }),
+  }
 }