@lark-apaas/coding-template-nestjs-react-fullstack 0.1.60-alpha.20261105142153 → 0.1.60-beta.0

package/template/package.json

@@ -45,7 +45,7 @@
     "crypto-js": "^4.2.0",
     "dayjs": "^1.11.15",
     "dotenv": "^17.2.2",
-    "drizzle-orm": "0.44.6",
+    "drizzle-orm": "0.45.2",
     "hbs": "^4.2.0",
     "reflect-metadata": "^0.1.14",
     "tslib": "^2.8.1"
@@ -133,16 +133,7 @@
     "uuid": "11.0.5",
     "vaul": "^1.1.2",
     "vite": "^8",
-    "zod": "^4.3.6",
-    "@floating-ui/dom": "1.7.4",
-    "@tiptap/core": "3.20.0",
-    "@tiptap/extension-document": "3.20.0",
-    "@tiptap/extension-hard-break": "3.20.0",
-    "@tiptap/extension-paragraph": "3.20.0",
-    "@tiptap/extension-text": "3.20.0",
-    "@tiptap/pm": "3.20.0",
-    "@tiptap/react": "3.20.0",
-    "@tiptap/suggestion": "3.20.0"
+    "zod": "^4.3.6"
   },
   "overrides": {
     "dayjs": "^1.11.15",
@@ -150,9 +141,7 @@
     "tailwind-merge": "^3.5.0",
     "zod": "^4.3.6",
     "echarts": "^6.1.0",
-    "stylelint": "^17.3.0",
-    "@tiptap/extension-bubble-menu": "3.20.0",
-    "@tiptap/extension-floating-menu": "3.20.0"
+    "stylelint": "^17.3.0"
   },
   "engines": {
     "node": ">=22.0.0",

package/template/scripts/build.sh

@@ -45,32 +45,49 @@ STEP_START=$(node -e "console.log(Date.now())")
 
 # 在 client/server 构建之前生成到 dist/，供 DefinePlugin 注入前端 bundle
 # 注意：nest-cli.json 中 deleteOutDir 必须为 false（模板默认值），否则 nest build 会清掉 dist/
-echo "   ├─ 生成 API 路由定义..."
-npx generate-api-routes --server-dir ./server --out-dir ./dist > /tmp/gen-api-routes.log 2>&1 &
-API_ROUTES_PID=$!
-
-echo "   ├─ 生成页面路由定义..."
-npx generate-page-routes --app-path ./client/src/app.tsx --out-dir ./dist > /tmp/gen-page-routes.log 2>&1 &
-PAGE_ROUTES_PID=$!
-
-API_ROUTES_EXIT=0
-PAGE_ROUTES_EXIT=0
-
-wait $API_ROUTES_PID || API_ROUTES_EXIT=$?
-wait $PAGE_ROUTES_PID || PAGE_ROUTES_EXIT=$?
-
-if [ $API_ROUTES_EXIT -ne 0 ]; then
-  echo "   ⚠️  API 路由生成失败（不影响构建）"
-  cat /tmp/gen-api-routes.log
+# 生成器来自 @lark-apaas/devtool-kits（由 preset 间接安装）。只用本地命令：
+# 未安装时直接跳过，不走 npx，避免联网查同名包 404 的等待；preset 读不到文件会注入空路由。
+API_ROUTES_BIN="$ROOT_DIR/node_modules/.bin/generate-api-routes"
+PAGE_ROUTES_BIN="$ROOT_DIR/node_modules/.bin/generate-page-routes"
+API_ROUTES_PID=""
+PAGE_ROUTES_PID=""
+
+if [ -x "$API_ROUTES_BIN" ]; then
+  echo "   ├─ 生成 API 路由定义..."
+  "$API_ROUTES_BIN" --server-dir ./server --out-dir ./dist > /tmp/gen-api-routes.log 2>&1 &
+  API_ROUTES_PID=$!
 else
-  echo "   ✅ API 路由生成完成"
+  echo "   ⏭️  未安装 generate-api-routes，跳过 API 路由定义生成"
 fi
 
-if [ $PAGE_ROUTES_EXIT -ne 0 ]; then
-  echo "   ⚠️  页面路由生成失败（不影响构建）"
-  cat /tmp/gen-page-routes.log
+if [ -x "$PAGE_ROUTES_BIN" ]; then
+  echo "   ├─ 生成页面路由定义..."
+  "$PAGE_ROUTES_BIN" --app-path ./client/src/app.tsx --out-dir ./dist > /tmp/gen-page-routes.log 2>&1 &
+  PAGE_ROUTES_PID=$!
 else
-  echo "   ✅ 页面路由生成完成"
+  echo "   ⏭️  未安装 generate-page-routes，跳过页面路由定义生成"
+fi
+
+if [ -n "$API_ROUTES_PID" ]; then
+  API_ROUTES_EXIT=0
+  wait $API_ROUTES_PID || API_ROUTES_EXIT=$?
+  if [ $API_ROUTES_EXIT -ne 0 ]; then
+    echo "   ⚠️  API 路由生成失败（不影响构建）"
+    cat /tmp/gen-api-routes.log
+  else
+    echo "   ✅ API 路由生成完成"
+  fi
+fi
+
+if [ -n "$PAGE_ROUTES_PID" ]; then
+  PAGE_ROUTES_EXIT=0
+  wait $PAGE_ROUTES_PID || PAGE_ROUTES_EXIT=$?
+  if [ $PAGE_ROUTES_EXIT -ne 0 ]; then
+    echo "   ⚠️  页面路由生成失败（不影响构建）"
+    cat /tmp/gen-page-routes.log
+  else
+    echo "   ✅ 页面路由生成完成"
+  fi
 fi
 print_time $STEP_START
 echo ""

package/template/scripts/prune-smart.js

@@ -1,9 +1,28 @@
 #!/usr/bin/env node
 // This file is auto-generated by @lark-apaas/fullstack-cli
 
-const { nodeFileTrace } = require('@vercel/nft');
 const fs = require('fs');
 const path = require('path');
+const { createRequire } = require('module');
+
+// @vercel/nft 是 fullstack-cli 自身的依赖：应用装了 CLI 时从应用 node_modules 加载；
+// 构建镜像全局预装 CLI、应用未安装时，从 PATH 上 fullstack-cli 的安装目录加载
+function loadNft() {
+  try {
+    return require('@vercel/nft');
+  } catch (err) {
+    if (err.code !== 'MODULE_NOT_FOUND') throw err;
+  }
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    const cliBin = dir && path.join(dir, 'fullstack-cli');
+    if (cliBin && fs.existsSync(cliBin)) {
+      return createRequire(fs.realpathSync(cliBin))('@vercel/nft');
+    }
+  }
+  throw new Error('未找到 @vercel/nft：应用未安装 fullstack-cli，PATH 上也没有全局 fullstack-cli');
+}
+
+const { nodeFileTrace } = loadNft();
 
 const ROOT_DIR = path.resolve(__dirname, '..');
 

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

@@ -1,101 +0,0 @@
-# 评论组件
-
-默认通过 `useComments` 接入。页面只提供业务对象、当前用户和 adapter；请求方法、认证及服务协议由应用自己实现。UI、回复/编辑/删除、乐观更新仍由同一套组件管理。
-
-```tsx
-import {
-  useComments,
-  CommentsProvider,
-  CommentList,
-  CommentComposer,
-} from '@/components/business-ui/comments';
-
-function Comments({ recordId, currentUser, adapter }) {
-  const comments = useComments({ resourceKey: recordId, currentUser, adapter });
-  return (
-    <CommentsProvider value={comments}>
-      <div className="min-h-0 flex-1 overflow-y-auto">
-        <CommentList />
-      </div>
-      <CommentComposer />
-    </CommentsProvider>
-  );
-}
-```
-
-Provider 不输出布局 DOM。标题、边框、尺寸、滚动容器归页面。也可 `<CommentPanel value={comments} />` 使用默认完整布局。主输入框在同一个 Provider 内挂一次，行内编辑由列表承载。
-
-## 最小 adapter
-
-```ts
-import type { CommentAdapter } from '@/components/business-ui/comments';
-
-const adapter: CommentAdapter = {
-  scopeKey: 'my-api:tenant:authenticated-account',
-  async list({ resourceKey, cursor, signal }) {
-    // 调用应用自己的 API，并映射为 CommentPage；不要把后端原始结构直接返回。
-    return api.listComments({ recordId: resourceKey, cursor, signal });
-  },
-  async create(
-    { resourceKey, threadId, replyToMessageId, content, attachments },
-    context,
-  ) {
-    return api.createComment(
-      {
-        recordId: resourceKey,
-        threadId,
-        replyToMessageId,
-        content,
-        attachments,
-      },
-      context,
-    );
-  },
-};
-```
-
-`api` 是应用自身代码，不是组件内置客户端。只有 list 就是只读；提供 create 才能新增/回复，update/remove 配合每条消息权限启用编辑/删除。不要用组件参数替代后端鉴权。
-
-- scopeKey 隔离提供方、租户和认证上下文，不含凭证；切换连接或权限身份时变化。hook 额外根据 resourceKey 和 currentUser 的完整引用隔离会话。推荐用 useMemo 或模块变量保持 adapter 稳定；同一 scope 的新对象本身不会反复加载。
-- list 返回 `{threads,nextCursor?}`；讨论包含 id/messages，第一条为正文。messages 使用字符串 ID 和毫秒时间。nextCursor 省略表示没有下一页，不自行生成游标。
-- 单个讨论未读全时返回 nextReplyCursor，并提供 listReplies，返回 `{messages,nextCursor?}`。hook 接管两层分页、去重、游标保护，以及刷新后保留已加载页数。
-- create/update 返回 `{threadId,messageId,message?}`，message 是可选权威回读。create 不传 threadId 表示新讨论；回复同时带 threadId 和精确 replyToMessageId，后端只支持线性讨论时可以忽略后者。
-- remove 接收选中消息 ID，包括首条。删除后第二条自然提升；返回 `{threadId,threadDeleted?}`，不能确定讨论是否为空就省略该字段，不凭局部列表推断。
-- hook 自动首屏读取；写入前丢弃旧读取，等并发写入完成再静默刷新。正常写后回读不触发整体 loading，刷新失败不反转已成功写入。`comments.refresh()` 是主动刷新，`comments.refreshing` 可供宿主显示后台读取状态。
-- 每次写操作收到 `{operationId,signal}`；同一次重试保持 operationId。确定未写入可抛 Error 并设置 outcome:'not-applied'；超时/回包丢失为 outcome:'unknown'，普通未标注异常也按未知处理，不能盲重发。
-- 服务支持客户端幂等标识时，adapter 将 context.operationId 写入并在读取消息上返回 clientOperationId，组件据此核对未知新增结果。没有服务端关联证据时不按正文去重，也不宣称能自动恢复所有未知结果。
-
-## 可选能力都放 adapter
-
-| 字段                        | 作用                                                                                                                     |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| people.source               | search/recommend/resolve；search 或 recommend 可用时启用 @；只有 resolve 时只补展示资料                                  |
-| people.canMention / onClick | 可选人员插入策略、人员卡片回调                                                                                           |
-| documents                   | `{source,canInsert?}`，注册后默认可插入；canInsert:false 只提供元数据解析                                                |
-| reactions                   | `{catalog?,allowedKeys?,onChange?}`，无 onChange 为只读，onChange 接收 resourceKey、threadId、messageId、key、add/remove |
-| images                      | 设 true 才启用文件选择；create/update 必须能上传并持久化完整消息，注册不会自动上传                                       |
-| links                       | 是否允许插入结构化普通链接，默认 false                                                                                   |
-| validateDraft               | 服务特有正文限制；返回错误文案或 undefined                                                                               |
-| getMessageLink              | 提供消息链接时显示复制链接菜单                                                                                           |
-
-catalog 项为 `{key,label,text?,url?,group?}`；不传时沿用现有表情资产。allowedKeys 同时约束快捷点击和选择列表。回应数据放 message.reactions，undefined 表示未读取、[] 表示权威为空、mine 省略表示本人状态未知，不根据截断人员名单推断 false。
-
-正文是 CommentContent，不是 Tiptap JSON 或服务 wire schema。读取遇到不支持的节点要保留为 unsupported 并禁用编辑。不能丢图片或未知节点后保存。禁用插入新引用时，编辑可原样保留已有引用，最终仍由 validateDraft/后端确认支持。
-
-用户引用当前为 `{kind:'user',namespace,id}`。不能把 open_id 当妙搭 userId；需要对接平台人员体系时在服务端 adapter 转换，统一目录、作者和 currentUser 的身份域。组件没有内置身份转换或 owner 权限兜底。
-
-## 高级受控方式继续可用
-
-已有 React Query、自有缓存或实时订阅时，可以继续传 `scopeKey/subjectKey/threads/actions/loading/error/pagination/actors/input/extensions` 等原始 props，详见 contracts.ts。该模式由宿主维护读取、分页和写入屏障，组件仍管理乐观覆盖。不要同时传 value 和受控 props，不再另建一套临时消息队列。
-
-原 `business-ui/record-comments` 的多维表格合同与数字 ID/秒级时间入口保留兼容；不能与新入口的类型混用。新通用入口仍共享原 UI 内部实现，未移动 CSS/assets。
-
-## 样式与验收
-
-项目入口需要模板自身的全局 `index.css`（Tailwind、主题与基础重置），组件会引入原内部 CSS。使用 hook 不改变任何视觉 token。
-
-真实 OpenAPI 验收示例位于仓库 `scripts/__tests__/fixtures/record-comments/openapi/`，使用同一个 useComments 入口。它是开发工具，不随模板运行时携带；运行中的应用不能 shell 执行 lark-cli 或把 token 放到浏览器。
-
-本地完整能力示例在同级测试目录 `memory/`：用独立 adapter 验收人员选择、混合图片回复、文档、表情、确定失败重试和未知结果核对；图片仅在本地持久化，不代表 OpenAPI 图片接入。
-
-多维表格插件的真实应用 adapter 示例位于 `scripts/__tests__/fixtures/record-comments/bitable/`，使用与 OpenAPI 相同的 useComments 接口，保留服务自身身份域和权限。