@lark-apaas/coding-template-nestjs-react-fullstack 0.1.55-alpha.20261101040602 → 0.1.55-alpha.20261101050259

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-template-nestjs-react-fullstack",
-  "version": "0.1.55-alpha.20261101040602",
+  "version": "0.1.55-alpha.20261101050259",
   "description": "NestJS + React fullstack template for miaoda coding",
   "type": "module",
   "files": [

package/template/client/src/components/business-ui/record-comments/README.md

@@ -1,9 +1,27 @@
 # Record comments
 
-完整受控记录评论组件，入口 `CommentPanel`。公共合同见 `comment-panel.contract.ts`、`types.ts`，统一从 `index.ts` 导入；目录内实现、CSS 和 `assets/reaction-sprite.png` 必须整体分发。不依赖旧 comment 目录，不包含测试应用、插件实例或表格配置。模板已配置 React、Tiptap 3.20.0、floating-ui 及 ui primitives 依赖。
+完整受控记录评论组件，入口 `CommentPanel`。公共合同见 `comment-panel.contract.ts`、`types.ts`，统一从 `index.ts` 导入；目录内 internal 实现、集中样式和 `assets/reaction-sprite.png` 必须整体分发。不依赖旧 comment 目录，不包含测试应用、插件实例或表格配置。模板已配置 React、Tiptap 3.20.0、floating-ui 及 ui primitives 依赖。
 
 组件管理现有样式、回复归属、编辑器、人员弹层、菜单、分页触发和乐观更新；评论 CRUD、身份、权限、插件调用、服务端缓存、分页游标、表情及文档请求由宿主提供。
 
+## Agent 接入与维护路径
+
+普通接入只读本说明和 `comment-panel.contract.ts`，从目录入口导入；人员/文档来源的详细类型按需查 `types.ts`。新增页面只在宿主 hook 中实现读取与写入，不需要遍历或修改内部编辑器。
+
+| 位置 | 职责 |
+| --- | --- |
+| `index.ts` | 唯一推荐导入入口：组件、公共类型、目录适配器和 URL 工具 |
+| `comment-panel.contract.ts` / `types.ts` | 评论受控接口及提及来源类型 |
+| `comment-panel.tsx` | 装配受控数据、分页和乐观更新 |
+| `app-source.ts` | 可选的妙搭人员目录适配器，不含评论 CRUD |
+| `internal/model.ts` / `mutations.ts` | 内容转换、命令校验、时间/提及规则、乐观更新状态 |
+| `internal/discussion.tsx` / `composer.tsx` | 评论展示、菜单、回复和输入区 |
+| `internal/editor.tsx` / `suggestions.tsx` / `mentions.tsx` | Tiptap、候选选择与引用解析缓存 |
+| `internal/content.tsx` / `icons.tsx` / `images.tsx` / `reactions.tsx` | 内容展示、图标、图片扩展和表情回应 |
+| `internal/view-types.ts` / `reaction-catalog.ts` / `styles.css` | 内部视图类型、静态表情数据、集中样式 |
+
+`internal/` 只由组件实现与组件测试引用；应用代码不深引其内部文件。文档适配器如需 URL 校验/识别，从入口（纯数据适配器也可从 `app-source.ts`）导入 `safeUrl/documentRefFromUrl`。样式由 `CommentPanel` 一次加载，分发时保留整个目录和 assets；不需要逐个导入 CSS。修复内部行为时沿上表定位一个职责，不为每个小工具再拆文件。
+
 ## 接入
 
 必填 `scopeKey/recordID/comments/mentionSource`。可选参数完整类型见 `CommentPanelProps`。
@@ -48,7 +66,7 @@ export function RecordComments(props: Props) {
 
 完整 Action 映射、身份约束和接入验收见配套 `plugin-guide/references/record-comments.md`。模板不含 mock 路由；仅 mock 通过不能声称真实链路完成。
 
-人员提及悬浮沿用官方颜色：普通人员浅蓝底、自身蓝色胶囊变亮、无权限人员灰底。样式由 mention-appearance.css 的组件专属类提供，不依赖宿主 accent 配色。
+人员提及悬浮沿用官方颜色：普通人员浅蓝底、自身蓝色胶囊变亮、无权限人员灰底。样式由 internal/styles.css 的组件专属类提供，不依赖宿主 accent 配色。
 
 
 ## 交互接入约束
@@ -56,3 +74,10 @@ export function RecordComments(props: Props) {
 宿主复用组件已有交互，不额外包装删除确认、成功 toast 或“已显示全部评论”提示。复制链接成功后只关闭菜单；编辑操作按钮保持“确认”，等待态不新增“保存中”文字。回复自己也会插入自身提及；未知作者不能伪造提及。保持人员搜索和提及悬浮样式，不用宿主全局 button/a/p 样式覆盖组件。
 
 保留读写失败的恢复入口和无障碍状态；未知写入结果不得开放盲目重试。新增提示或改变状态流前，应取得官方对应状态的操作证据；本地受控故障测试不等同于真实 Action 验收，未覆盖的权限/网络/图片能力需明确标注。
+
+
+初始无数据时，加载、空态和读取错误共用同一个 118px 状态占位（沿用原空态高度），长错误在占位内滚动；状态切换不会移动输入框。已有评论的后台读取错误保留列表并使用紧凑提示。宿主仍控制整体 height/maxHeight，不需要为三种状态分别补高度。重试失败后，外部 error 清除会同时清理旧的重试错误。
+
+空列表的分页提示也计入同一个读取占位区；后续页耗尽不会额外收缩面板。受限高度容器中该区域可随可用空间收缩，长分页错误在区域内滚动。
+
+若宿主在身份或权限查询完成后才提供写回调，输入框会稍后挂载；宿主可通过 `style={{ minHeight: 'min(250px, 60vh)', maxHeight: '60vh' }}` 预留整体空间，避免身份加载引起的高度变化。不要为占位提前开放写入能力。

package/template/client/src/components/business-ui/record-comments/app-source.ts

@@ -1,12 +1,7 @@
-import { listUsersByIds, searchUsers } from '../api/users/service';
+import type { CommentDataSource, CommentDocumentSource, MentionOption, MentionResult } from './types';
+import { mentionKey } from './internal/model';
 import { getI18nText } from '../utils/user';
-import { mentionKey } from './content';
-import type {
-  CommentDataSource,
-  CommentDocumentSource,
-  MentionOption,
-  MentionResult,
-} from './types';
+import { listUsersByIds, searchUsers } from '../api/users/service';
 
 function avatarUrl(avatar: unknown): string | undefined {
   if (typeof avatar === 'string') return avatar;
@@ -183,3 +178,5 @@ export function withDocumentSource(
     },
   };
 }
+
+export { documentRefFromUrl, safeUrl } from './internal/model';

package/template/client/src/components/business-ui/record-comments/comment-panel.contract.ts

@@ -1,14 +1,14 @@
+import type { CommentDataSource, CommentMentionClickHandler } from './types';
+import type { CSSProperties } from 'react';
+
 /**
  * Public contract for the controlled CommentPanel entry point.
  * Requests, credentials, pagination cursors and server caches belong to the host.
  * The panel owns optimistic drafts and per-message mutation state.
  */
-import type { CSSProperties } from 'react';
 
-import type {
-  CommentDataSource,
-  CommentMentionClickHandler,
-} from './types';
+
+
 
 export type CommentReadContent =
   | { type: 'text'; text: string }

package/template/client/src/components/business-ui/record-comments/comment-panel.tsx

@@ -1,27 +1,34 @@
-import { useCallback, useEffect, useReducer, useRef, useState, useSyncExternalStore } from 'react';
-import { LoaderCircle } from 'lucide-react';
-import { DiscussionPanel } from './discussion-panel';
-import {
-  buildPanelThreads, CommentPageLoader, preparePanelDeletion, preparePanelEdit,
-  loadPanelReactionDetails, preparePanelComment,
-} from './comment-panel-model';
-import { CommentMutations } from './comment-panel-optimistic';
 import type { CommentPanelProps, CommentTarget } from './comment-panel.contract';
+import { CommentMutations } from './internal/mutations';
+import { buildPanelThreads, CommentPageLoader, preparePanelDeletion, preparePanelEdit, loadPanelReactionDetails, preparePanelComment } from './internal/model';
+import { DiscussionPanel } from './internal/discussion';
+import { LoaderCircle } from 'lucide-react';
+import { useCallback, useEffect, useReducer, useRef, useState, useSyncExternalStore } from 'react';
+import './internal/styles.css';
 
-function ReadStatus({ loading, error, onRetry }: Pick<CommentPanelProps, 'loading' | 'error' | 'onRetry'>) {
+function ReadStatus({ loading, error, onRetry, empty, hasMore }: Pick<CommentPanelProps, 'loading' | 'error' | 'onRetry'> & { empty: boolean; hasMore?: boolean }) {
   const [failure, setFailure] = useState('');
   const [retrying, setRetrying] = useState(false);
   const busy = useRef(false);
-  if (!loading && !error && !failure) return null;
-  return <div className="replica-panel-status" role={error || failure ? 'alert' : 'status'}>
-    <span>{loading ? <LoaderCircle className="size-4 animate-spin text-primary" aria-label="正在加载评论" /> : failure || error}</span>
-    {!loading && onRetry && <button type="button" disabled={retrying} onClick={async () => {
-      if (busy.current) return;
-      busy.current = true; setRetrying(true); setFailure('');
-      try { await onRetry(); }
-      catch (cause) { setFailure(cause instanceof Error ? cause.message : '刷新失败，请重试'); }
-      finally { busy.current = false; setRetrying(false); }
-    }}>{retrying ? '正在重试…' : '重试刷新'}</button>}
+  // A successful external read must clear a previous retry failure as well.
+  useEffect(() => setFailure(''), [error]);
+  const pending = loading || retrying;
+  const message = failure || error;
+  if (!empty && !pending && !message) return null;
+  const state = pending ? 'loading' : message ? 'error' : 'empty';
+  return <div className={`replica-panel-status${empty ? ' replica-panel-placeholder' : ''}`}
+    data-state={state} role={state === 'error' ? 'alert' : 'status'} aria-busy={pending}>
+    <div className="replica-panel-status-content">
+      <span>{pending ? <LoaderCircle className="size-4 animate-spin text-primary" aria-label="正在加载评论" />
+        : message || (empty && !hasMore ? '当前记录暂无评论' : null)}</span>
+      {!pending && message && onRetry && <button type="button" onClick={async () => {
+        if (busy.current) return;
+        busy.current = true; setRetrying(true); setFailure('');
+        try { await onRetry(); }
+        catch (cause) { setFailure(cause instanceof Error ? cause.message : '刷新失败，请重试'); }
+        finally { busy.current = false; setRetrying(false); }
+      }}>重试刷新</button>}
+    </div>
   </div>;
 }
 
@@ -93,11 +100,11 @@ function PaginationFooter({ pagination, loading, getScrollContainer }: Pick<Comm
   });
   const error = pagination?.hasMore && (gate.error || pagination.error);
   const pending = gate.pending || pagination?.loading;
-  return <div ref={sentinel} className="replica-panel-pagination" aria-live="polite">
-    {error ? <><span role="alert">{error}</span><button type="button" disabled={pending} onClick={() => run.current(true)}>重试加载</button></>
+  return <div ref={sentinel} className={pagination?.hasMore ? 'replica-panel-pagination' : undefined} aria-live="polite">
+    {pagination?.hasMore && (error ? <><span role="alert">{error}</span><button type="button" disabled={pending} onClick={() => run.current(true)}>重试加载</button></>
       : pending ? <LoaderCircle className="size-4 animate-spin text-primary" aria-label="正在加载更多评论" />
         : pagination?.hasMore ? <button type="button" disabled={loading} onClick={() => run.current(true)}>继续加载</button>
-          : null}
+          : null)}
   </div>;
 }
 
@@ -145,8 +152,9 @@ function PanelSession(props: CommentPanelProps) {
       enablePrivateComments={false}
       enableDocuments={props.enableDocuments ?? false}
       autoScrollNewReplies={false}
-      emptyState={props.loading || props.error || props.pagination?.hasMore ? null : undefined}
-      listHeader={<ReadStatus loading={props.loading} error={props.error} onRetry={props.onRetry} />}
+      emptyState={null}
+      listHeader={<ReadStatus loading={props.loading} error={props.error} onRetry={props.onRetry}
+        empty={!comments.some((thread) => thread.replies.length > 0)} hasMore={props.pagination?.hasMore} />}
       listFooter={props.pagination && <PaginationFooter pagination={props.pagination} loading={props.loading || Boolean(props.error)} getScrollContainer={props.getScrollContainer} />}
       onMentionClick={props.onMentionClick}
       getCommentLink={(commentID, reply) => props.getCommentLink?.({ recordID: props.recordID, commentID, replyID: reply.replyID }) ?? ''}

package/template/client/src/components/business-ui/record-comments/index.ts

@@ -1,7 +1,7 @@
 export { CommentPanel } from './comment-panel';
 export { createAppCommentSource, withDocumentSource } from './app-source';
 export type * from './comment-panel.contract';
-export type {
-  CommentDataSource, CommentDocumentSource, CommentMentionClickHandler,
-  MentionRef, MentionOption, MentionResult, MentionKind, DocumentMentionMetadata,
-} from './types';
+export type { CommentDataSource, CommentDocumentSource, CommentMentionClickHandler, MentionRef, MentionOption, MentionResult, MentionKind, DocumentMentionMetadata } from './types';
+
+// URL helpers for external document adapters; no requests or permissions inside.
+export { documentRefFromUrl, safeUrl } from './internal/model';

package/template/client/src/components/business-ui/record-comments/{discussion-composer.tsx → internal/composer.tsx}

@@ -1,18 +1,182 @@
-import { useEffect, useRef, useState } from 'react';
-import { LockKeyhole, X } from 'lucide-react';
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from '@/components/ui/popover';
-import { CommentInput } from './comment-input';
-import { emptyComment } from './content';
-import { commentFailureMessage } from './comment-panel-model';
-import { COMMENT_THEME_CLASS } from './mention-appearance';
+import { emptyComment, normalizeValue, readApiContent, COMMENT_THEME_CLASS, commentFailureMessage } from './model';
+import type { CommentInputProps, CommentInputHandle, CommentEditorProps, CommentValue } from '../types';
+import { useMentionContext } from './mentions';
+import { CommentContent } from './content';
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { ErrorBoundary } from 'react-error-boundary';
+import * as React from 'react';
+import { useEffect, useImperativeHandle, useCallback, useRef, useState, type ComponentType } from 'react';
+import type { DiscussionDraft, DiscussionImage } from './view-types';
+import { COMMENT_IMAGE_ACCEPT, prepareCommentImage } from './images';
 import { DiscussionIcon } from './icons';
-import { COMMENT_IMAGE_ACCEPT, prepareCommentImage } from './image-files';
-import type { CommentInputHandle, CommentValue } from './types';
-import type { DiscussionDraft, DiscussionImage } from './discussion-types';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { LockKeyhole, X } from 'lucide-react';
+
+let modulePromise: Promise<typeof import('./editor')> | undefined;
+function loadEditor() {
+  // Reset rejected imports so explicit retry actually executes import again.
+  return (modulePromise ||= import('./editor').catch((error) => {
+    modulePromise = undefined;
+    throw error;
+  }));
+}
+export function preloadCommentEditor() {
+  void loadEditor().catch(() => {});
+}
+
+/** Public entry contains no static import of Tiptap. A session change resets all work. */
+export function CommentInput(props: CommentInputProps) {
+  const { store } = useMentionContext();
+  try {
+    normalizeValue(props.value);
+  } catch {
+    return (
+      <p role="alert" className="text-sm text-destructive">
+        评论内容格式无效，无法编辑
+      </p>
+    );
+  }
+  return (
+    <ErrorBoundary
+      key={JSON.stringify([store.source.scopeKey, props.documentKey])}
+      fallbackRender={({ resetErrorBoundary }) => (
+        <div
+          role="alert"
+          className="rounded-lg border p-3 text-sm text-destructive"
+        >
+          编辑器发生错误，输入内容已保留。
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            onClick={resetErrorBoundary}
+          >
+            重新加载
+          </Button>
+        </div>
+      )}
+    >
+      <InputSession {...props} />
+    </ErrorBoundary>
+  );
+}
+
+function InputSession(props: CommentInputProps) {
+  const [Editor, setEditor] =
+    React.useState<ComponentType<CommentEditorProps> | null>(null);
+  const latest = useRef(props);
+  latest.current = props;
+  const editorRef = useRef<CommentInputHandle | null>(null);
+  const editable = useRef(true);
+  const [enabled, setEnabled] = useState(true);
+  const loadingRef = useRef(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const alive = useRef(true);
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+    };
+  }, []);
+  const activate = useCallback(async () => {
+    if (loadingRef.current || latest.current.disabled || !editable.current)
+      return;
+    loadingRef.current = true;
+    setLoading(true);
+    setError('');
+    try {
+      const module = await loadEditor();
+      if (alive.current) setEditor(() => module.default);
+    } catch {
+      if (alive.current) setError('编辑器加载失败，请重试');
+    } finally {
+      loadingRef.current = false;
+      if (alive.current) setLoading(false);
+    }
+  }, []);
+  useImperativeHandle(
+    props.ref,
+    () => ({
+      getContent: () =>
+        editorRef.current?.getContent() ?? readApiContent(latest.current.value),
+      clear() {
+        if (!alive.current) return;
+        if (editorRef.current) editorRef.current.clear();
+        else {
+          const value = emptyComment();
+          latest.current = { ...latest.current, value };
+          latest.current.onChange(value);
+        }
+      },
+      setEditable(next) {
+        if (!alive.current) return;
+        editable.current = next;
+        editorRef.current?.setEditable(next && !latest.current.disabled);
+        setEnabled(next);
+      },
+      focus() {
+        if (!alive.current) return;
+        if (editorRef.current) editorRef.current.focus();
+        else void activate();
+      },
+    }),
+    [activate],
+  );
+  const { ref: _ref, ...editorProps } = props;
+  if (Editor)
+    return (
+      <Editor
+        {...editorProps}
+        disabled={props.disabled || !enabled}
+        editorRef={editorRef}
+      />
+    );
+  return (
+    <div className={cn(COMMENT_THEME_CLASS, 'replica-input', props.className)}>
+      <div className="relative flex min-h-[34px] flex-col justify-center rounded-[6px] border-[0.5px] border-border bg-card px-3 py-[5px] transition-colors hover:border-primary focus-within:border-primary">
+        <div
+          aria-hidden
+          className="pointer-events-none w-full text-sm leading-[22px]"
+        >
+          {loading || error ? (
+            <span className="text-muted-foreground">
+              {loading ? '正在加载编辑器…' : '重试加载编辑器'}
+            </span>
+          ) : props.value.content.length ? (
+            <CommentContent value={props.value} mentionVariant="pill" />
+          ) : (
+            <span className="text-muted-foreground">
+              {props.placeholder || '输入评论'}
+            </span>
+          )}
+        </div>
+        <Button
+          type="button"
+          variant="ghost"
+          className="no-default-hover-elevate no-default-active-elevate absolute inset-0 h-full min-h-0 w-full rounded-[6px] p-0"
+          disabled={props.disabled || !enabled || loading}
+          aria-busy={loading}
+          onPointerEnter={preloadCommentEditor}
+          onFocus={preloadCommentEditor}
+          onClick={() => {
+            void activate();
+          }}
+        >
+          <span className="sr-only">
+            {error ? '重试加载编辑器' : props.placeholder || '输入评论'}
+          </span>
+        </Button>
+      </div>
+      {error ? (
+        <p role="alert" className="mt-2 text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}
 
 export function DiscussionComposer({
   sessionKey,

package/template/client/src/components/business-ui/record-comments/{comment-content.tsx → internal/content.tsx}

@@ -1,28 +1,9 @@
-import { DocumentIcon } from './document-icon';
-import { fromApiContent } from './content';
-import {
-  USER_MENTION_CLASS,
-  INPUT_USER_MENTION_CLASS,
-  COMMENT_THEME_CLASS,
-  userMentionLabelClass,
-  atUserLabel,
-  DOCUMENT_MENTION_CLASS,
-  DOCUMENT_MENTION_UNREADABLE_CLASS,
-} from './mention-appearance';
-import * as React from 'react';
+import type { CommentMentionClickHandler, CommentApiContent, CommentPart, CommentValue } from '../types';
+import { useMentionContext, useMentionEntity, useResolveComment } from './mentions';
+import { mentionLabel, normalizeValue, safeUrl, USER_MENTION_CLASS, INPUT_USER_MENTION_CLASS, COMMENT_THEME_CLASS, userMentionLabelClass, atUserLabel, DOCUMENT_MENTION_CLASS, DOCUMENT_MENTION_UNREADABLE_CLASS, fromApiContent } from './model';
 import { cn } from '@/lib/utils';
-import { mentionLabel, normalizeValue, safeUrl } from './content';
-import {
-  useMentionContext,
-  useMentionEntity,
-  useResolveComment,
-} from './mention-provider';
-import type {
-  CommentMentionClickHandler,
-  CommentApiContent,
-  CommentPart,
-  CommentValue,
-} from './types';
+import * as React from 'react';
+import { DocumentIcon } from './icons';
 
 function Mention({
   part,

package/template/client/src/components/business-ui/record-comments/{discussion-panel.tsx → internal/discussion.tsx}

@@ -1,26 +1,15 @@
-import { useEffect, useRef, useState } from 'react';
-import { LockKeyhole } from 'lucide-react';
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from '@/components/ui/popover';
-import { MentionProvider, useMentionEntity } from './mention-provider';
-import { CommentContent } from './comment-content';
-import { CommentReactionEntry, CommentReactionList } from './comment-reactions';
-import { commentFailureMessage } from './comment-panel-model';
-import { DiscussionComposer } from './discussion-composer';
-import { DiscussionImageViewer } from './discussion-image-viewer';
+import type { DiscussionReply, DiscussionImage, DiscussionPanelProps } from './view-types';
+import type { MentionRef } from '../types';
+import { COMMENT_THEME_CLASS, formatCommentTime, commentFailureMessage } from './model';
 import { DiscussionIcon } from './icons';
-import { formatCommentTime } from './discussion-time';
-import { COMMENT_THEME_CLASS } from './mention-appearance';
-import type { MentionRef } from './types';
-import type {
-  DiscussionReply,
-  DiscussionImage,
-  DiscussionPanelProps,
-} from './discussion-types';
-import './discussion.css';
+import { DiscussionImageViewer } from './images';
+import { DiscussionComposer } from './composer';
+import { CommentReactionEntry, CommentReactionList } from './reactions';
+import { CommentContent } from './content';
+import { MentionProvider, useMentionEntity } from './mentions';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { LockKeyhole } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
 
 function PersonAvatar({
   refValue,